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	16315
title	Dock demo: agent-driven perspective restore/list path + spec witness
state	Closed
labels	enhancementaitesting
assignees	neo-kimi-phoebe
createdAt	Aug 2, 2026, 1:31 AM
updatedAt	Aug 2, 2026, 2:33 AM
githubUrl	https://github.com/neomjs/neo/issues/16315
author	neo-kimi-phoebe
commentsCount	2
parentIssue	15252
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Aug 2, 2026, 2:33 AM

Dock demo: agent-driven perspective restore/list path + spec witness

Closed Backlog/active-chunk-11 enhancementaitesting

neo-kimi-phoebe commented on Aug 2, 2026, 1:31 AM

Context

The operator's 2026-08-02 flagship-film brief (90–150s, heavy drag-and-drop) names perspectives as a film beat. Fable's lane map on #15252 (issuecomment-5153855472) scoped L2 = "perspectives wiring — NL tools exist, workstation wiring unverified" and invited self-selection; @neo-kimi-phoebe claimed L2+L3 at 2026-08-01T23:15:25Z (A2A MESSAGE:c278901d-fdf1-4524-b275-c6ddfff83f24). Budget clock: the Fable family may go dark within 2–3 days — every artifact lands durably same-turn.

The Problem

The agent-driven perspective path — an agent or the film's screenplay-automation driving save → list → restore of named layouts through the Neural Link tools — had never been verified end-to-end against the workstation demo app, and has no spec witness.

What exists today (verified this session, 2026-08-01/02):

DockPerspectiveStore instantiated at apps/agentos/childapps/dockdemo/view/DemoBWorkspace.mjs:461; switcher bar born from store lifecycle events (DemoBWorkspace.mjs:618-631, createSwitcherBar at :1155); switcher buttons restore on click via loadPerspectiveByName (:4396)
App-vocabulary restore surface: loadPerspectiveByName(name) at DemoBWorkspace.mjs:1223, tour cue perspective-load at :1414 beside perspective-save at :1413
capturePerspective(name, {scope}) at DemoBWorkspace.mjs:1124; Mission Control captures via dockService.capturePerspective (MissionControlWorkspace.mjs:336)
Tour script apps/agentos/tour/demoBPerspectives.mjs + spec test/playwright/e2e/agentos/DemoBPerspectivesNL.spec.mjs proving capture + topology reconcile on Demo B — driven through the app's own tour/store path, never the NL tools
NL tools capture_perspective / restore_perspective / list_perspectives shipped via #14649 (closed); the showcase #14590 (closed) delivered named-layout morphing

What was missing (corrected 2026-08-02 — see correction comment; an earlier draft of this section wrongly asserted zero restore call sites based on an NL-vocabulary grep):

~~app-surface restore/list~~ — dissolved by evidence: the surface exists in store vocabulary (method + cue + switcher)
No spec witness drives the NL capture_perspective / list_perspectives / restore_perspective tools against the live workstation app (the residual, and this ticket's deliverable)
The NL chain itself had never been run live — discharged 2026-08-01 (AC1 receipt below)

The Architectural Reality

Normative authority: ADR 0029 §2.2 — capture scope (DockZoneModel.CAPTURE_SCOPES = ['window', 'topology']), cross-topology restore via DockTopologyReconciler.reconcile(), fail-closed structured results, revision-migration-honest loadPerspective
Store: src/dashboard/DockPerspectiveStore.mjs — atomic CRUD over dockLayoutCollection.v1, collision verdicts, lifecycle events feeding UI
NL tools per #14649: capture/restore write-locked, list read-tier
Contract doc: learn/agentos/HarnessDockZoneModel.md (serializable vs runtime state)

The Fix

~~Verify the live chain~~ — DONE 2026-08-01 (headed+GPU receipt in comments: capture → list → restore + fail-closed all pass against the workstation dockdemo).
~~Close the app-surface gap~~ — dissolved by evidence (2026-08-02 correction): perspective-load cue + loadPerspectiveByName + switcher restore already exist.
Spec beat (the deliverable): a deterministic whitebox-e2e witness (sibling pattern: DemoBPerspectivesNL.spec.mjs) that drives the NL tools — capture → mutate via execute_dock_operation → restore → list_perspectives — and asserts worker truth (restored dockZone.v1 document equality + fail-closed structured error on unknown names). Spec = authority, film = derivative.
Handoff: filmable, deterministic cue sequence posted as a comment on #15252 same-turn — nothing strandable in Fable context.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
NL `restore_perspective`	`#14649` + ADR 0029 §2.2	Verified live against dockdemo; fail-closed structured result asserted in spec	n/a (exists)	tool schema	headed receipt + spec
NL `list_perspectives`	`#14649`	Verified live; spec asserts store-backed listing	n/a (exists)	tool schema	spec
`DemoBWorkspace` tour cues (`perspective-save` / `perspective-load`)	`DemoBWorkspace.mjs:1413-1414`	Unchanged (existing surface)	n/a	tour script	existing spec
Perspective switcher bar	`DemoBWorkspace.mjs:1155`, `:4396`	Unchanged (existing surface)	n/a	—	existing spec

Decision Record impact

aligned-with ADR 0029 — §2.2 perspectives contract is exercised, never amended.

Acceptance Criteria

Live headed+GPU receipt: NL capture → list → restore chain executed against the workstation demo app on this host; output pasted on this ticket (issuecomment-5154028743)
~~App-surface gap closed~~ — dissolved by evidence (correction comment issuecomment-5154088209): restore/list reachable from the demo surface (tour cue + switcher)
Deterministic whitebox-e2e spec beat green locally (headed), driving the NL restore path and asserting worker truth; run command documented in the spec header per sibling pattern
Filmable cue sequence handed to Fable as a #15252 comment (durable, same-turn)
Claim boundary honored: no cross-platform / default-selection / portability claims (#15243→#15245 gate)

Out of Scope

New perspective features in framework core (DockZoneModel / Reconciler changes) — the ADR 0029 surface is exercised, not extended
QT-parity polish (parent epic #13158, Clio — coordinate before any shared-surface edit)
Mission Control restore parity unless the film beat requires it (intake verifies)
L3 undo/redo wiring (sibling ticket #16316)

Avoided Traps

Re-building the showcase: #14590 already delivered morphing; this ticket verifies + witnesses the agent-driven path rather than re-authoring Demo B
Headless "green" receipts: headless canvas is blank — only headed+GPU runs count (operator contract)
NL-vocabulary grep as absence-proof: restorePerspective/listPerspectives zero-hits measured the wrong vocabulary; the app rides store vocabulary (loadPerspectiveByName, perspective-load)

Parent epic: #15252 (this is the L2 leaf)
Closed precedents: #14590 (showcase), #14649 (NL tools)
Overlap gate: #13158 (Clio's QT-parity epic — coordinate, don't collide)
Lane map: #15252 issuecomment-5153855472; claim: A2A 2026-08-01T23:15:25Z

Live latest-open sweep: checked latest 20 open issues at 2026-08-01T23:24Z; no equivalent found. A2A in-flight sweep (60 min): no competing claim on this scope (Iris claimed L1 #16309 at 23:21Z — disjoint). KB semantic sweep surfaced closed precedents #14590 / #14649 only.

Origin Session ID: 14f1d6fa-235a-4101-88d4-c9490e3f7fd5

Retrieval Hint: "flagship film perspectives NL restore list dockdemo witness"

tobiu referenced in commit ed05e92 - "test(e2e): witness the NL perspective capture/list/restore path on Demo B (#16315) (#16319)" on Aug 2, 2026, 2:33 AM

tobiu closed this issue on Aug 2, 2026, 2:33 AM