What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	13499
title	Add turn-presence writer substrate
state	Closed
labels	enhancementaiarchitecture
assignees	neo-gpt
createdAt	Jun 19, 2026, 3:57 AM
updatedAt	Jun 19, 2026, 8:49 AM
githubUrl	https://github.com/neomjs/neo/issues/13499
author	neo-gpt
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[x] 13524 Wire add_memory recency into who_is_online projection
closedAt	Jun 19, 2026, 8:49 AM

Add turn-presence writer substrate

Closed v13.1.0/archive-v13-1-0-chunk-4 enhancementaiarchitecture

neo-gpt commented on Jun 19, 2026, 3:57 AM

Context

This leaf splits Substrate A out of the broader who_is_online ticket so the turn-presence writer PR can carry a precise Resolves target without prematurely closing Ada's Substrate B projection work.

Live latest-open sweep: checked the latest 30 open GitHub issues on 2026-06-19; #13498 is the umbrella and no equivalent turn-presence-writer leaf exists. A2A in-flight claim sweep: latest 30 messages show the agreed ownership split, with GPT owning Substrate A and Ada owning Substrate B.

Release classification: boardless (Agent OS coordination hardening; not a v13 release blocker).

The Problem

The swarm needs a reliable signal that a maintainer has actually begun a turn. Process presence and wake-route reachability are not enough: a harness can be running while the agent is frozen, rate-limited, or wedged. The broader #13498 ticket covers both the writer and the who_is_online projection, but those are separable PR-sized surfaces with different owners.

Without this leaf, a Substrate A PR would have to use Resolves #13498, which would auto-close the umbrella before Substrate B lands.

The Architectural Reality

The wake/presence substrate already has process-route vocabulary through HARNESS_PRESENCE, but that proves addressability, not a trusted turn start.
Memory Core graph-backed tools need a new AGENT_TURN_PRESENCE interval record with start/progress/terminal semantics.
Codex turn-start emission must live in the harness prompt-submit hook and must not import Neo singletons from the standalone context hook process.
AiConfig remains the source of provider/runtime configuration shape; hook-safe pure metadata can feed both config leaves and the hook path.

The Fix

Add a Memory Core TurnPresenceService for start, progress, and terminal interval writes.
Expose a record_turn_presence Memory Core MCP tool and OpenAPI operation.
Add turnPresence config leaves for freshness, TTL, note cap, and hook write timeout.
Add a fail-soft Codex UserPromptSubmit writer that records an AGENT_TURN_PRESENCE start row before ordinary tool work.
Terminalize the newest active interval when add_memory succeeds, without making add_memory the liveness primary.

Contract Ledger

Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
`AGENT_TURN_PRESENCE` graph node	Memory Core graph	Stores `{turnId, startedAt, lastProgressAt, freshUntil, expiresAt, terminalState}` intervals per agent identity	TTL expiry makes the record stale	OpenAPI + service JSDoc	Unit test
`record_turn_presence` MCP tool	Memory Core MCP	Writes start/progress/terminal interval updates	Fails closed on graph absence; no embedder dependency	OpenAPI	Server health-gate test
Codex context hook writer	Codex `UserPromptSubmit` hook	Writes a start interval before context payload output	Fail-soft no-op on missing DB, invalid env, timeout, or SQLite error	Hook JSDoc	Temp-SQLite probe
`turnPresence` config leaves	Memory Core config template	Configures freshness, TTL, note cap, hook timeout from env-backed leaves	Defaults from shared helper metadata	Config template	Config/template tests

Decision Record impact

aligned-with AiConfig Provider SSOT; no ADR amendment.

Decision Record

Discussion #13495 is the decision record for the umbrella design; this leaf only implements Substrate A.

Discussion Criteria Mapping

OQ1 threshold -> freshMs / ttlMs leaves and persisted freshUntil / expiresAt.
OQ2 frozen-vs-thinking -> lastProgressAt refresh plus terminal state.
OQ4 home -> Memory Core graph writer plus Codex hook emitter.
OQ5 consumers -> Substrate B remains out of scope here; this PR provides the read-model input.

Acceptance Criteria

Turn-started beacon emitted at Codex turn entry before ordinary tool work.
AGENT_TURN_PRESENCE interval stores turnId, startedAt, lastProgressAt, freshUntil, expiresAt, and terminalState.
Progress updates refresh lastProgressAt without changing startedAt.
Terminal updates can close the newest active interval for an agent.
Successful add_memory terminalizes the active interval without becoming the primary liveness signal.
Writer path is fail-soft and does not import Memory Core Neo singletons from the Codex context hook.
Memory Core tool/schema exposure is covered, including health-gate exemption from embedding/provider canaries.

Out of Scope

who_is_online projection/read tool.
Advisory cockpit or routing consumers.
Claude/Antigravity harness turn-start hooks.
Hard-gating routing decisions on the liveness projection.

Avoided Traps / Gold Standards Rejected

add_memory as primary liveness: rejected because it can false-negative under load.
Process presence as primary liveness: rejected because addressable harnesses can still be stuck.
Direct service imports in Codex hook: rejected because standalone hook processes do not safely bootstrap Neo singletons.

Related: #13498 Related: #13495

Origin Session ID: c3a6e312-b858-4be4-ad97-9bc55cbad5ae

Handoff Retrieval Hints

query_raw_memories: "turn presence writer Substrate A AGENT_TURN_PRESENCE Codex hook"
Branch: codex/13498-turn-presence-writer