LearnNewsExamplesServices

Neural Link Capability Matrix

This is the reference spine for the Neural Link tool surface. The conceptual guide explains why the Possession Interface matters; this page says what each registered verb is allowed to do, which App Worker surface it reaches, whether it participates in the transaction stack, and whether a generated payload may drive it directly.

The source of authority is ai/mcp/server/neural-link/openapi.yaml, with dispatch in ai/mcp/server/neural-link/toolService.mjs. If this page and the OpenAPI registry disagree, the registry is the runtime contract and the doc must be updated in the same change.

Projection Policy

openapi.yaml declares three Neural Link tiers:

Tier Projection Meaning
read Default visible Safe inspection. A harness-embedded agent can receive these by default.
write-locked Withheld until explicit locking/targets Mutates live App Worker state or user-visible runtime state. Trusted controller or e2e code may call these after validation. A model-generated artifact must never call them directly.
admin Operator only Lifecycle, config, arbitrary method, or hot-patch authority. These require an operator/admin gate and are never model-generated.

The direct model-generation rule is deliberately stricter than ordinary agent operation: a model may produce a candidate blueprint or plan, but that artifact does not get to select a Neural Link write/admin verb. A trusted caller must validate intent, resolve targets, and choose the verb.

Never Directly Model-Drivable

These operation IDs are not reachable from model-generated blueprints, route payloads, or boot-consumed generated artifacts. They may only be invoked by a trusted controller, fixture, maintainer, or operator path after its own guard has accepted the action.

abort_transaction, begin_transaction, call_method, capture_perspective, commit_transaction, create_component, create_instance, close_window, execute_dock_operation, focus_window, highlight_component, manage_connection, manage_neo_config, modify_state_provider, open_component_window, patch_code, position_window, redo, reload_page, remove_component, replay_transaction, restore_perspective, save_transaction, set_instance_properties, set_route, simulate_event, undo

Verb Matrix

Verb Purpose Owner / App Worker Surface Class Transaction Error Shape Firewall E2E Fixture Support
abort_transaction Discard pending dock Group inputs when groupId is supplied; otherwise abort the requester's non-dock record. InstanceService -> explicit manager.Transaction Group or legacy non-dock service. write-locked Group abort changes no live document; legacy abort retains already-applied non-dock effects. Recoverable {aborted:false, reason} for expected misses; schema/server errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Direct SDK/MCP only; no fixture wrapper.
begin_transaction Open a bounded pending batch in the explicit dock Group, or a legacy non-dock batch without groupId. InstanceService -> explicit manager.Transaction Group or legacy non-dock service. write-locked Dock inputs remain staged until one atomic commit; mixed domains refuse. Recoverable {opened:false, reason} for expected misses; schema/server errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Direct SDK/MCP only; no fixture wrapper.
call_method Invoke an arbitrary method on a live instance. InstanceService -> live instance method dispatch. admin Lock-enforced; generic calls are not undoable except server-stamped create/remove paths. Throws missing instance/method or downstream errors as {error}. Operator/admin only; never direct from model-generated payload. Fixture wrapper: callMethod; use sparingly.
capture_perspective Capture a named dock record — window selects Persistence.capturePerspective() over one Workspace; topology selects captureTopologyPerspective() over the holder's keyed getDockTopologyWorkspaces() seam. The output schema, not a stored mode flag, distinguishes the artifacts. DockService -> App Worker dock holder + model.Persistence; layouts store through PerspectiveLibrary, topologies through the holder's separate topology collection when present. write-locked Dock commit path, not the transaction stack. {captured, stored, collision, errors, layout, topology} with exactly one record non-null; scope/name refusals are structured errors. Trusted controller/e2e only; never direct from model-generated payload. SDK export: NeuralLink_DockService; no fixture wrapper yet.
check_namespace Check whether a namespace exists in the App Worker runtime. RuntimeService -> namespace lookup. read None. Boolean-style result or {error}. Model-readable after caller validates the namespace query. Fixture wrapper: checkNamespace.
close_window Close an owner-granted topology-known popup through its private native route and observe terminal disappearance. RuntimeService -> window operation bridge. write-locked Runtime window mutation; not transaction-captured. Unsupported without an owner grant; otherwise verified terminal result or {error}. Trusted controller/e2e only; never direct from model-generated payload and never bypass a product semantic return/disposal contract. Fixture wrapper: closeWindow.
commit_transaction Prepare and adopt the explicit Group batch as one history row, or commit the legacy non-dock batch. InstanceService -> explicit manager.Transaction Group or legacy non-dock service. write-locked Group preparation/refusal is atomic; cursor advances only after adoption. Recoverable {committed:false, reason} for expected misses; schema/server errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Direct SDK/MCP only; no fixture wrapper.
create_component Add a component config to a target container through constrained container.add. ComponentService -> App Worker call_method with server-stamped undoKind. write-locked Captured when Bridge-stamped; named-batch aware. Fail-fast validation for missing target/config/class identity; downstream errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Fixture wrapper: createComponent; keeper parity gap filed as #14815.
create_instance Create any JSON-addressable Neo instance, optionally attaching to a parent container. InstanceService -> Neo.create / Neo.ntype in the App Worker. write-locked Captured when Bridge-stamped; named-batch aware. Fail-fast data-only validation and parent checks; downstream errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Fixture wrapper: createInstance; direct SDK specs exist.
diff_dock_topology Compare a supplied dockZone document with the live holder document and return semantic dock deltas. DockService -> App Worker dock document holder / DockTopologyDiff. read None. Diff result includes deterministic category arrays plus shape-gate errors; missing holder/session errors use {error}. Model-readable after caller validates holder id and before-document provenance. SDK export: NeuralLink_DockService; no Playwright fixture wrapper.
execute_dock_operation Apply one semantic dock operation and return the post-operation document. DockService -> App Worker dock document holder / Operations.applyOperation. write-locked Registered dock holders use the Group writer and shared history; named Group batches return staged:true until commit. Executor returns {applied, document, errors}; malformed holder/transport errors use {error}. Operator/e2e-tier only; never direct from model-generated payload. SDK export: NeuralLink_DockService; fixture wrapper: executeDockOperation.
find_instances Find live instances by property selector. InstanceService -> App Worker instance registry. read None. Returns matching instances or {error}. Model-readable after caller validates selector scope. Fixture wrapper: findInstances.
focus_window Focus a known runtime window through its trusted native owner. RuntimeService -> window operation bridge. write-locked None. Verified focus result or {error}. Trusted controller/e2e only; never direct from model-generated payload. Fixture wrapper: focusWindow.
get_component_tree Read the live component tree from a root. ComponentService -> component serialization / toJSON-style tree. read None. Tree result or {error} for invalid root/session. Model-readable after caller bounds depth/root. Fixture wrapper: getComponentTree.
get_computed_styles Read computed CSS properties for a component. ComponentService -> main-thread style read. read None. Style result or {error}. Model-readable after caller validates target id. Fixture wrapper: getComputedStyles.
get_console_logs Read captured console logs for the App Worker/session. ConnectionService -> bridge/session log buffer. read None. Log list or {error}. Model-readable; filter before large dumps. Fixture wrapper: getConsoleLogs.
get_dock_topology Read a dock workspace document plus executable operation vocabulary. DockService -> App Worker dock document holder. read None. Topology result or {error} for missing holder/session. Model-readable after caller validates holder id. SDK export: NeuralLink_DockService; fixture wrapper: getDockTopology.
get_dom_event_listeners Read bound DOM event listeners for a component. RuntimeService -> DOM event manager summary. read None. Listener list or {error}. Model-readable after caller validates target id. Fixture wrapper: getDomEventListeners.
get_dom_event_summary Read a high-level DOM event manager summary. RuntimeService -> DOM event manager. read None. Summary result or {error}. Model-readable for diagnostics. Fixture wrapper: getDomEventSummary.
get_dom_rect Read physical DOM rects for components. ComponentService -> main-thread DOM geometry read. read None. Rect list or {error}. Model-readable after caller validates target ids. Fixture wrapper: getDomRect.
get_drag_state Read the current drag coordinator state. InteractionService -> drag coordinator. read None. Drag state or {error}. Model-readable for drag diagnostics. Fixture wrapper: getDragState.
get_drag_trace Read recent SortZone drag lifecycle trace entries, optionally clearing them. InteractionService -> drag trace ring buffer. read None. Trace result or {error}. Model-readable; clear only when the test owns the trace. Fixture wrapper: getDragTrace.
get_instance_properties Read selected properties from a live instance. InstanceService -> live instance property access. read None. Property map or {error}. Model-readable after caller scopes properties. Fixture wrapper via getComponent.
get_mcp_tool_handbook Read lazy usage detail for one Neural Link MCP tool. ToolService -> OpenAPI handbook cache. read None. {found, handbook} result or {error}. Model-readable; stale MCP runtime must not override source. Direct MCP only.
get_method_source Read a live class method source string. RuntimeService -> class/method introspection. read None. Source result or {error}. Model-readable; required before any patch_code. Fixture wrapper: getMethodSource.
get_namespace_tree Read the loaded namespace tree. RuntimeService -> namespace traversal. read None. Namespace tree or {error}. Model-readable with root/depth restraint. Fixture wrapper: getNamespaceTree.
get_record Read one data record, optionally scoped to a store. DataService -> store/record lookup. read None. Record result or {error}. Model-readable after caller validates store/record ids. Fixture wrapper: getRecord.
get_route_history Read route history for a window/session. RuntimeService -> navigation history. read None. Route history or {error}. Model-readable for navigation diagnostics. Fixture wrapper: getRouteHistory.
get_window_topology Read connected window metadata and generic physical-operation capabilities. RuntimeService -> ConnectionService.sessionData. read None. Window list or {error}. Model-readable; one-time grants and private generation routes are never projected. Fixture wrapper: getWindowTopology.
get_worker_topology Read connected App Worker/session metadata. RuntimeService -> ConnectionService.sessionData. read None. Worker list or {error}. Model-readable. Fixture wrapper: getWorkerTopology.
healthcheck Report server, bridge, session, and runtime freshness status. HealthService -> MCP server + bridge observability. read None. Healthy payload or 503-style {error}/freshness details. Model-readable; stale freshness blocks schema/source assertions. Direct MCP only; fixture starts bridge separately.
highlight_component Temporarily apply a visual highlight style to a component. InteractionService -> component style mutation. write-locked Temporary visual mutation; not captured in transaction stack. Missing component or style errors use {error}. Trusted diagnostic/e2e only; never direct from model-generated payload. Fixture wrapper: highlightComponent.
inspect_class Read a Rich Blueprint for a Neo class. RuntimeService -> class introspection. read None. Class schema or {error}. Model-readable; use before patching or class claims. Fixture wrapper: inspectClass.
inspect_component_render_tree Read VDOM/VNode render tree for a component. ComponentService -> render-tree serialization. read None. Render tree or {error}. Model-readable after caller bounds root/depth. Fixture wrapper: inspectComponentRenderTree.
inspect_state_provider Read a state provider's data. DataService -> state provider lookup. read None. Provider data or {error}. Model-readable after caller validates provider id. Fixture wrapper: inspectStateProvider.
inspect_store Read store metadata and records. DataService -> store lookup. read None. Store result or {error}. Model-readable; use limits for large stores. Fixture wrappers: getStore / inspectStore.
list_perspectives List a dock workspace's declared perspectives — the names activePerspective accepts, with the published perspective facts (active, modified, pending) — beside its stored perspective summaries, keyed topologies and the two active layout ids. The key is the discriminator: a declared name has no record to summarize. DockService -> the workspace's declared list (declaredPerspectives()), its perspective store and its topology collection. read None. {declared, perspective, perspectives, topologies, activeLayoutId, activeTopologyLayoutId, errors}; a holder that declares nothing and holds no store is a structured error, never an empty list. Model-readable after caller validates holder id. SDK export: NeuralLink_DockService; no fixture wrapper yet.
list_stores List available data stores. DataService -> store manager. read None. Store list or {error}. Model-readable. Fixture wrapper: listStores.
list_transactions Read the explicit Group's shared cursor/history, or the requester's non-dock audit without groupId. InstanceService -> explicit manager.Transaction Group or legacy non-dock service. read Non-consuming projection; unknown explicit Groups refuse. Empty lists for no writer/stack; server errors use {error}. Model-readable for the current writer's own stack. Direct SDK/MCP only; no fixture wrapper.
manage_connection Start or stop the local Neural Link WebSocket bridge. ConnectionService -> bridge process lifecycle. admin None. Action result or {error}. Operator/admin only; never direct from model-generated payload. Fixture setup calls start; no per-test wrapper.
manage_neo_config Get or merge Neo.config at runtime. RuntimeService -> App Worker config surface. admin None. Config result or {error}. Operator/admin only; never direct from model-generated payload. Fixture wrapper: manageNeoConfig.
modify_state_provider Merge data into a live state provider. DataService -> provider.setData. write-locked Not captured in transaction stack. Missing provider or payload errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Fixture wrapper: modifyStateProvider.
observe_motion Sample component/raw DOM rects over a bounded time window. InteractionService -> rendered geometry sampler. read None. Motion trace or {error}. Model-readable; duration is clamped. Fixture wrapper: observeMotion.
open_component_window Open a live component in a popup/window target. RuntimeService -> window operation bridge. write-locked Runtime window mutation; not transaction-captured. Window operation result or {error}. Trusted controller/e2e only; never direct from model-generated payload. Fixture wrapper: openComponentWindow.
patch_code Replace a class prototype method implementation at runtime. RuntimeService -> App Worker hot-patch gate. admin None. Fails when hot patching is disabled, target missing, or source invalid; errors use {error}. Operator/admin only; must be preceded by get_method_source; never direct from model-generated payload. Fixture wrapper: patchCode.
position_window Move a known popup/window when a native handle exists. RuntimeService -> window operation bridge. write-locked Runtime window mutation; not transaction-captured. Window operation result or {error}. Trusted controller/e2e only; never direct from model-generated payload. Fixture wrapper: positionWindow.
query_component Find live components by selector. ComponentService -> component manager/tree query. read None. Component list or {error}. Model-readable after caller scopes selectors. Fixture wrapper: queryComponent.
query_vdom Find VDOM nodes by selector/root. ComponentService -> VDOM traversal. read None. Node list or {error}. Model-readable after caller scopes selectors/root. Fixture wrapper: queryVdom.
redo Move the explicit Group's shared cursor forward, or redo the requester's non-dock stack. InstanceService -> explicit manager.Transaction Group or legacy non-dock service. write-locked Group compensation and current-caller enforcement precede cursor movement. Recoverable {redone:false, reason} for expected misses; server errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Direct SDK specs exist; no fixture wrapper.
reload_page Reload the application page/window. RuntimeService -> page lifecycle. admin None; invalidates session ids. Reload result or {error}. Operator/admin only; never direct from model-generated payload. Fixture wrapper: reloadPage; caller must rediscover session.
remove_component Destroy and detach a live component by id. ComponentService -> App Worker call_method with server-stamped undoKind. write-locked Captured when Bridge-stamped; named-batch aware. Fail-fast missing component id; downstream errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Fixture wrapper: removeComponent.
replay_transaction Replay archived Group participant endpoints into the explicit Group, or replay non-dock commands. InstanceService -> explicit manager.Transaction Group or legacy non-dock service. write-locked One new Group transaction under current-caller enforcement; mixed domains refuse before effects. Recoverable {replayed:false, reason} for missing archive, invalid archive, or replay denial; schema/server errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Direct SDK/MCP only; no fixture wrapper.
restore_perspective Restore a perspective by name, resolved across the workspace's declared list and its stored layout and topology records; a name found in more than one is refused with the sources named. A declared name takes the workspace's accepted activePerspective write — the same identity and provenance as a UI switch; the active name re-applies its baseline. Stored records route by schema: layout.v1 rides the single-Workspace switch/load seam; topology.v1 reconciles exact workspace keys and commits once through commitDockTopologyWorkspaces(). DockService -> the declared list, then read-only layout/topology lookup, then the accepted activePerspective write, activatePerspective / layout load, or DockTopologyReconciler + the keyed atomic holder seam. write-locked Dock commit path, not the transaction stack; under a Group a remote caller is fenced against the live document owners and an open batch refuses. Declared: {switched, source:'declared', schema:null, captureScope:'window', errors, document}. Layout: {switched, schema, captureScope:'window', errors, document}. Topology: {switched, schema, errors, document, workspaces, restored, unrestored, displaced}; remainders name workspaceKey. A refusal leaves live documents, the selection and both active pointers untouched. Trusted controller/e2e only; never direct from model-generated payload. SDK export: NeuralLink_DockService; no fixture wrapper yet.
save_transaction Archive a committed Group participant snapshot or non-dock transaction. InstanceService -> explicit manager.Transaction Group or legacy non-dock service. write-locked Human Group provenance is retained without inventing an agent writer; no live mutation. Recoverable {saved:false, reason} for missing transaction or archive-store failures; schema/server errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Direct SDK/MCP only; no fixture wrapper.
set_instance_properties Set properties/configs on a live instance. InstanceService -> live instance set. write-locked Captured when Bridge-stamped; named-batch aware. Missing instance or setter errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Fixture wrapper: setProperties.
set_route Drive a window/session to a hash route. RuntimeService -> navigation. write-locked Navigation mutation; not transaction-captured. Route result or {error}. Trusted controller/e2e only; never direct from model-generated payload. Fixture wrapper: setRoute.
simulate_event Dispatch native DOM events against target DOM ids. InteractionService -> browser/main-thread event dispatch. write-locked Interaction side effects are not transaction-captured. Event dispatch result or {error}. Trusted controller/e2e only; never direct from model-generated payload. Fixture wrapper: simulateEvent.
undo Move the explicit Group's shared cursor backward, or undo the requester's non-dock stack. InstanceService -> explicit manager.Transaction Group or legacy non-dock service. write-locked Group compensation and current-caller enforcement precede cursor movement. Recoverable {undone:false, reason} for expected misses; server errors use {error}. Trusted controller/e2e only; never direct from model-generated payload. Direct SDK specs exist; no fixture wrapper.
verify_component_consistency Compare logical items, VDOM, and real DOM child surfaces. InteractionService -> component consistency oracle. read None. Consistency report or {error}. Model-readable after caller validates container id. Fixture wrapper: verifyComponentConsistency.

Gap Ledger

Gap Filed Leaf Why It Is A Gap
Scripted tour-mode driving primitives #14640 Journey and demo work needs deterministic scene execution, not ad-hoc e2e timing glue.
Keeper external create_component parity #14815 Keeper-owned materialization and external Neural Link inserts must have an explicit, tested provenance/chrome boundary before journey authors assume parity.

Verification

test/playwright/unit/ai/mcp/server/neural-link/CapabilityMatrix.spec.mjs parses this table and ai/mcp/server/neural-link/openapi.yaml. A registered operation without a row fails. A row without a registered operation fails. The same spec checks the explicit never-direct model set against every non-read operation and requires the firewall cell for non-read rows to state that it is never direct from a model-generated payload.

The Knowledge Base ingestion AC is post-merge: after this page lands and the KB sync runs, ask_knowledge_base should surface per-verb contracts from this reference page.