Curate Neural Link tool-surface tiers for harness agents

Context

Epic #13056 is now unblocked: its ## Discussion Criteria Mapping maps the inherited coordination-track criterion Tool-surface design to a curated Neural Link surface for harness-embedded agents. The current Neural Link MCP surface is still a developer-grade flat API. That is fine for a trusted single local operator, but the harness product needs a safer projection before embedded agents inherit the full dev surface.

Release classification: harness line (Project 13); post-v13, not v13.x release-blocking.

The Problem

ai/mcp/server/neural-link/openapi.yaml currently exposes 37 operations with no tier metadata. Read-only inspection, live mutation, navigation, page reload, bridge connection management, and config management all sit in one undifferentiated tool catalog. #13056 names this as a coordination substrate risk: an embedded harness agent should not receive the same full developer surface by default, especially before Topological Locking and identity-bound transport land.

Without an explicit tier contract, later leaves can diverge in two bad directions: either every agent gets the full Neural Link surface because it already exists, or each harness adapter invents a private allowlist. Both lose the graph-readable contract that reviewers need.

The Architectural Reality

V-B-A on 2026-06-13:

• ai/mcp/server/neural-link/openapi.yaml exposes 37 operations and no read/write/admin tier metadata.
• Mutation/admin-shaped operations already include modify_state_provider, reload_page, set_route, manage_connection, set_instance_properties, call_method, patch_code, manage_neo_config, and simulate_event.
• ai/mcp/server/neural-link/Bridge.mjs still identifies clients by query-string role / id; it is not an identity-bound authorization surface.
• ai/services/neural-link/ConnectionService.mjs still auto-targets the most recent session when no sessionId is passed; #13056 assigns explicit-target behavior to the locking leaf, not this ticket.
• Historical KB results surfaced older Neural Link tool work and the existing RecorderService / toolService machinery, but no active #13056 leaf that classifies the harness projection tiers.

The Fix

Define the Neural Link tool-surface curation contract:

1. Classify every current Neural Link operation into one of the harness-facing tiers: read, write-locked, or admin.
2. Encode that classification in a graph-reviewable source-of-authority, preferably in or mechanically derived from ai/mcp/server/neural-link/openapi.yaml rather than in a private UI allowlist.
3. Define the harness-visible projection rule: embedded agents receive the read tier by default; write-class operations require the Topological Locking / explicit-target contract; admin operations remain hidden or explicit-operator-only until a later auth leaf grants them.
4. Add static validation that fails when a Neural Link operation lacks a tier or when known mutation/admin operations are mislabeled as read.
5. Document the boundary without implementing identity-bound transport, lock acquisition, or the harness UI selector in this leaf.

Contract Ledger Matrix

Decision Record impact

Aligned-with ADR 0020. This keeps the harness UI/product surface from inheriting raw developer authority by default while preserving Neural Link as the bridge between Body and Brain. No ADR amendment expected.

Acceptance Criteria

• Every current Neural Link OpenAPI operation is classified as read, write-locked, or admin in a graph-reviewable source-of-authority.
• The PR defines the harness-visible projection rule for embedded agents and explicitly names which tiers are default-visible, withheld pending locks, or operator/admin-only.
• Static validation fails if any Neural Link operation lacks a tier.
• Static validation fails if known mutation/admin operations are mislabeled as read.
• The PR cites #13056 and explains that this leaf does not implement identity-bound transport, Topological Locking, or admin authorization.
• The branch history and PR body Refs #13056 / #13012 but Resolves only this leaf ticket.

Out of Scope

• Implementing identity-bound Bridge authentication.
• Implementing Topological Locking or lock acquisition.
• Removing ConnectionService.call() auto-targeting behavior.
• Building a harness UI tool-picker.
• Changing runtime behavior of any Neural Link operation beyond metadata/validation needed for the contract.

Avoided Traps

• Full developer surface by default — rejected; a product harness cannot silently inherit mutation/admin authority.
• Private UI allowlist — rejected unless it is mechanically derived from a source-of-authority; reviewers need one durable taxonomy.
• Bundling auth, locking, and curation — rejected; those are separate #13056 leaves with different evidence requirements.
• Bridge-level authorization theater — rejected here; #13056 names in-heap locking and identity-bound transport as their own leaves.

Related

Parent: #13056 Refs #13012 Refs #12984 Refs #13037 Refs #13049

Live latest-open sweep: checked latest 20 open issues at 2026-06-13T05:45Z; no equivalent curated Neural Link tool-surface leaf found. Closest source: parent #13056. A2A in-flight sweep: checked latest 30 messages at 2026-06-13T05:45Z; no recent overlapping [lane-claim] / [lane-intent] for this leaf. KB/local sweep: ask_knowledge_base found historical Neural Link tool work but no active #13056 curation leaf; exact rg over synced issues/discussions for curated tool surface, tool-surface design, write-locked, harness-visible projection, and read/write/admin found no equivalent ticket.

Origin Session ID: d2d31447-5009-47a8-992e-9ecc35b806c1

Retrieval Hint: "Neural Link tool-surface curation read write-locked admin tier metadata harness-visible projection #13056"