Context
Operator seed (2026-07-04, live session, verbatim substance): "docking layouts: we will need new NL tools… NL-driven layout changes with animations" — the Lane-3 bar (D#14561: "NL changes layouts live, animated, e2e-tested") requires agents to DRIVE and VERIFY dock layouts natively, and today they cannot: the Neural Link observes motion (observe_motion), drag state (get_drag_state/get_drag_trace), and components (query_component), but has no dock-semantic surface — no way to read a dock topology or execute a dock operation.
The Problem
The two showcase demos, the whitebox-e2e leaf, and the FM-cockpit consumers (#14560 pop-out cards; seam-v0 on #14423) all need programmatic dock control. Without NL tools, "NL-driven docking" degrades to simulated pointer events against private DOM — brittle, animation-blind, and contract-free. The tools are also the recording substrate: a scripted NL run IS the demo tour (see the sibling showcase tickets).
The Architectural Reality
- The semantic-operation executor is SHIPPED:
src/dashboard/DockZoneModel.mjs (v1 vocabulary incl. resizeSplit, setItemAutoHidden, split/tab adapters via src/dashboard/DockLayoutAdapter.mjs). Contract of record: learn/agentos/HarnessDockZoneModel.md (dockZone.v1).
- NL tool substrate + discipline: the neural-link MCP tool modules (sibling precedent — structural-pre-flight Stage-1 fast-path applies: new tool files join the existing tool-module directory pattern); schema discipline per the
x-pass-as-object fixes (#14542/#14543).
- Verification siblings:
examples/dashboard/dock/ (#13247) as the correctness surface; observe_motion for animation assertions.
- Guardrail inherited from the epic: no parallel layout-mutation path — every mutation rides the model executor.
The Fix
One PR, two tools + handbook + unit coverage:
get_dock_topology — serialized dock-model tree for a given root (and window, multi-window-aware where the substrate already is): items, splits, tabs, auto-hide states, active perspective metadata when present. Read-only; JSON-first output (no live refs/DOMRects).execute_dock_operation — validated passthrough to the dockZone.v1 executor for the SHIPPED v1 vocabulary (move/split/tab/setItemAutoHidden/resizeSplit); fail-closed on unknown operations (unknown op = error naming the vocabulary, never a guess). Returns the post-operation topology delta so agents verify without a second call.
Both tools registered in the NL handbook with worked examples; unit specs per the unit-test skill (custom playwright configs — never default npx playwright test).
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
get_dock_topology (new NL tool) |
dockZone.v1 model (DockZoneModel.mjs) |
Read-only serialized topology |
absent tool = status quo (DOM scraping) |
NL handbook entry |
unit spec + live example run |
execute_dock_operation (new NL tool) |
the model executor (same) |
Validated v1-vocabulary passthrough, fail-closed, returns delta |
absent tool = simulate_event fallback |
NL handbook entry |
unit spec incl. unknown-op rejection |
Decision Record impact
aligned-with ADR 0020 + the dockZone.v1 contract. Perspective/cross-window tool extensions are explicitly #14423-spec-gated (see Out of Scope) — this ticket adds no semantics the shipped model doesn't already own.
Acceptance Criteria
Out of Scope
capture_perspective / restore_perspective / cross-window move tools — follow-up leaf AFTER #14423 settles §2/§3 semantics.- Demo apps and e2e suites (sibling leaves).
- Any dockZone.v1 model changes.
Related
Parent: #13158 (linked native). Design gate for follow-ups: #14423 (+ seam-v0 comment). Consumers: the two showcase leaves + the whitebox-e2e leaf (filed same batch), #14560 cockpit cards. Precedent: #14562/#14563 (Euclid's FM NL-proof pattern). Sweeps: latest-20 live at 2026-07-04T01:56Z — no equivalent; A2A all-status scan same minute — no docking-scoped claim (Lane 3 is mine, D#14561 DC…3Wl).
Origin Session ID: fa2a6fd5-7488-4af6-a0d2-3855c86003e4
Retrieval Hint: "NL dock tools topology readout execute dock operation fail-closed vocabulary"
Context
Operator seed (2026-07-04, live session, verbatim substance): "docking layouts: we will need new NL tools… NL-driven layout changes with animations" — the Lane-3 bar (D#14561: "NL changes layouts live, animated, e2e-tested") requires agents to DRIVE and VERIFY dock layouts natively, and today they cannot: the Neural Link observes motion (
observe_motion), drag state (get_drag_state/get_drag_trace), and components (query_component), but has no dock-semantic surface — no way to read a dock topology or execute a dock operation.The Problem
The two showcase demos, the whitebox-e2e leaf, and the FM-cockpit consumers (#14560 pop-out cards; seam-v0 on #14423) all need programmatic dock control. Without NL tools, "NL-driven docking" degrades to simulated pointer events against private DOM — brittle, animation-blind, and contract-free. The tools are also the recording substrate: a scripted NL run IS the demo tour (see the sibling showcase tickets).
The Architectural Reality
src/dashboard/DockZoneModel.mjs(v1 vocabulary incl.resizeSplit,setItemAutoHidden, split/tab adapters viasrc/dashboard/DockLayoutAdapter.mjs). Contract of record:learn/agentos/HarnessDockZoneModel.md(dockZone.v1).x-pass-as-objectfixes (#14542/#14543).examples/dashboard/dock/(#13247) as the correctness surface;observe_motionfor animation assertions.The Fix
One PR, two tools + handbook + unit coverage:
get_dock_topology— serialized dock-model tree for a given root (and window, multi-window-aware where the substrate already is): items, splits, tabs, auto-hide states, active perspective metadata when present. Read-only; JSON-first output (no live refs/DOMRects).execute_dock_operation— validated passthrough to the dockZone.v1 executor for the SHIPPED v1 vocabulary (move/split/tab/setItemAutoHidden/resizeSplit); fail-closed on unknown operations (unknown op = error naming the vocabulary, never a guess). Returns the post-operation topology delta so agents verify without a second call.Both tools registered in the NL handbook with worked examples; unit specs per the unit-test skill (custom playwright configs — never default
npx playwright test).Contract Ledger Matrix
get_dock_topology(new NL tool)DockZoneModel.mjs)execute_dock_operation(new NL tool)Decision Record impact
aligned-withADR 0020 + the dockZone.v1 contract. Perspective/cross-window tool extensions are explicitly #14423-spec-gated (see Out of Scope) — this ticket adds no semantics the shipped model doesn't already own.Acceptance Criteria
x-pass-as-object-compliant schemas.execute_dock_operationrejects unknown ops fail-closed with the vocabulary named.examples/dashboard/dock/(topology read + one op of each v1 class).Out of Scope
capture_perspective/restore_perspective/ cross-window move tools — follow-up leaf AFTER #14423 settles §2/§3 semantics.Related
Parent: #13158 (linked native). Design gate for follow-ups: #14423 (+ seam-v0 comment). Consumers: the two showcase leaves + the whitebox-e2e leaf (filed same batch), #14560 cockpit cards. Precedent: #14562/#14563 (Euclid's FM NL-proof pattern). Sweeps: latest-20 live at 2026-07-04T01:56Z — no equivalent; A2A all-status scan same minute — no docking-scoped claim (Lane 3 is mine, D#14561 DC…3Wl).
Origin Session ID: fa2a6fd5-7488-4af6-a0d2-3855c86003e4 Retrieval Hint: "NL dock tools topology readout execute dock operation fail-closed vocabulary"