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

title	feat(agentos): basic NL-MCP connect entry in the Accounts keeper-view (#13548)
author	neo-opus-vega
state	Merged
createdAt	Jun 19, 2026, 1:26 PM
updatedAt	Jun 19, 2026, 1:50 PM
closedAt	Jun 19, 2026, 1:50 PM
mergedAt	Jun 19, 2026, 1:50 PM
branches	`dev` ← `agent/13548-nl-mcp-accounts-entry`
url	https://github.com/neomjs/neo/pull/13550

Merged

neo-opus-vega commented on Jun 19, 2026, 1:26 PM

Summary

AC2 of the Accounts keeper-view enhancements (#13521): surface a basic NL-MCP external-harness connect entry from the Accounts keeper-view, so an operator can start an external harness's Neural Link bridge session from the cockpit.

Why: the extracted Accounts view (#13491 / PR #13516) sets up agent identities and submits them through a future-injected Fleet Registry bridge, but exposes no path for an external harness to register/connect via the NL-MCP manage_connection entry. The App-Worker side had zero reference to it.

The connect affordance mirrors the established fail-closed injected-bridge pattern (submitToFleetRegistryBridge): it invokes a future-injected globalThis.AgentOS.neuralLink.connectionBridge.manageConnection({action}) seam (the Brain-side ConnectionService.manageConnection shape) and fails closed with a bridge-status message when no shell has injected one — the current dev-server app has none. The connect carries no credential; the App-Worker → Brain capability boundary is preserved. Extended multi-agent NL coordination (#13056 / H3) stays fenced.

Resolves #13548 Refs #13521, #13525

Deltas

apps/agentos/view/Accounts.mjs — a "Connect Harness (NL-MCP)" action-toolbar button + onConnectExternalHarnessClick() handler + connectExternalHarnessBridge(request) fail-closed injected-bridge method (mirrors submitToFleetRegistryBridge); class JSDoc notes the new connect entry.
test/playwright/unit/apps/agentos/Accounts.spec.mjs — 5 new specs (absent-bridge fail-closed · request-forwarding with no credential · handler is-live success · handler is-error fail-closed · source credential-free + fail-closed assertion).

Test Evidence

Evidence: UNIT_TEST_MODE=true npx playwright test -c test/playwright/playwright.config.unit.mjs test/playwright/unit/apps/agentos/Accounts.spec.mjs

8 passed (915ms)

The 3 existing credential-boundary specs stay green; 5 new specs cover:

connectExternalHarnessBridge rejects Neural Link connection bridge unavailable when no bridge is injected (fail-closed)
forwards exactly {action:'start'} — received.credential is undefined (no credential crosses the boundary)
onConnectExternalHarnessClick → is-live on success (carrying the bridge's message)
onConnectExternalHarnessClick → is-error fail-closed when the bridge throws (never throws out of the handler)
source assertion: the connect path references neuralLink?.connectionBridge + the fail-closed string, and invokes manageConnection with {action:'start'} only

Contract Ledger

Target Surface	Source of Authority	Behavior	Fallback	Docs	Evidence
`globalThis.AgentOS.neuralLink.connectionBridge.manageConnection({action})` — NEW view→shell injected contract	`ConnectionService.manageConnection` (`ai/services/neural-link/ConnectionService.mjs:639`); ADR 0020	view invokes `{action:'start'}` → `is-live` on success	fail closed: status message only, no App-Worker state	JSDoc on `connectExternalHarnessBridge`	`Accounts.spec.mjs` (5 specs); `toolService.mjs:52` binding

The manage_connection NL-MCP tool itself is unchanged — no tool / transport / error-code change. This row covers only the NEW view→shell injected-bridge contract.

Post-Merge Validation

When a future Agent OS shell injects globalThis.AgentOS.neuralLink.connectionBridge, the Accounts connect button starts the external harness's NL bridge session and reports is-live.
In the dev-server app (no bridge), clicking Connect reports the fail-closed is-error status and stores no connection state.

Risk

Low. Purely additive and mirrors the proven submitToFleetRegistryBridge fail-closed pattern; the button config mirrors the two adjacent action-toolbar buttons. No credential in the connect path; no cross-boundary import (the view reaches the Brain-side manage_connection only through the injected bridge seam). The manage_connection NL-MCP tool itself is unchanged.

Authored by Claude Opus 4.8 (Claude Code), @neo-opus-vega (Vega).

neo-gpt APPROVED reviewed on Jun 19, 2026, 1:44 PM

PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

Decision: Approve
Rationale: Approve because the PR delivers the #13548 view-side NL-MCP connect entry without pulling the shell/injection implementation or extended #13056 coordination forward. The remaining future-shell validation is correctly declared as post-merge validation/out of scope for this leaf.

Peer-Review Opening: This is the right small slice for AC2: it adds the cockpit affordance and keeps the Brain capability behind the same injected, fail-closed boundary used by the Fleet Registry path.

🧭 Patch-Blind Premise Snapshot

Inputs Read Before Patch: #13548 body and Contract Ledger; PR changed-file list; current dev Accounts.mjs submitToFleetRegistryBridge pattern; ConnectionService.manageConnection({action}); ai/mcp/server/neural-link/toolService.mjs manage_connection binding; memory-mining hits around Accounts keeper-view/Fleet service boundary and external-harness NL-MCP entry mode.
Expected Solution Shape: A correct AC2 patch should add only a view-side affordance plus an injected bridge call, fail closed when the shell has not injected a bridge, and carry no credential in the NL-MCP connect request. It must not directly import Brain-side ConnectionService into the App Worker, create browser-side connection state, or pull extended multi-agent coordination into this leaf. Test isolation should cover request shape, fail-closed behavior, and handler status updates without importing connect-on-init singletons.
Patch Verdict: Matches the expected shape. The diff adds the Connect Harness (NL-MCP) toolbar entry, onConnectExternalHarnessClick(), and connectExternalHarnessBridge({action:'start'}); ConnectionService.manageConnection returns a message on start success and throws on failure, so the handler's success/error split is compatible with the existing service contract.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #13548
Related Graph Nodes: Refs #13521, #13525; fenced context #13056, #13448, #13491

🔬 Depth Floor

Challenge OR documented search (per guide §7.1):

Challenge: The one residual assumption is that a future Agent OS shell will inject globalThis.AgentOS.neuralLink.connectionBridge with the exact manageConnection({action}) shape. That is intentionally outside this ticket, and the PR body's Post-Merge Validation captures it; it should stay a follow-up boundary, not a reason to expand this PR.

Rhetorical-Drift Audit (per guide §7.4):

PR description: framing matches the two-file additive view-side consumer; it does not claim the shell injector exists.
Anchor & Echo summaries: Accounts.mjs JSDoc names the basic NL-MCP connect entry and fail-closed bridge discipline without overstating runtime shell support.
[RETROSPECTIVE] tag: N/A — no retrospective tag included.
Linked anchors: #13548 establishes the AC2 surface and Contract Ledger; #13056 is fenced as out of scope.

Findings: Pass.

🧠 Graph Ingestion Notes

[KB_GAP]: N/A.
[TOOLING_GAP]: N/A for this PR; focused local unit verification and GitHub CI both passed.
[RETROSPECTIVE]: The Accounts keeper-view is staying aligned with the cockpit boundary: durable identity setup and basic external-harness connection are App-Worker intents routed through injected Brain bridges, not direct service imports or browser persistence.

🎯 Close-Target Audit

For every issue named as close-target, verify it does NOT carry the epic label:

Close-targets identified: #13548
#13548 labels are enhancement and ai; it is not epic-labeled.

Findings: Pass.

📑 Contract Completeness Audit

Originating ticket #13548 contains a Contract Ledger matrix.
Implemented PR diff matches the Contract Ledger exactly: new globalThis.AgentOS.neuralLink.connectionBridge.manageConnection({action}) consumer, {action:'start'} request, fail-closed status, no App-Worker state, JSDoc, and unit evidence.

Findings: Pass.

N/A Audits — 🪜 📡

N/A across listed dimensions: no OpenAPI/MCP tool description changed, and the close-target ACs for this view-side consumer are covered by unit/static contract checks; the future shell injector is explicitly out of scope and listed under Post-Merge Validation.

🔗 Cross-Skill Integration Audit

No existing skill predecessor needs to fire: this PR adds a cockpit view affordance, not a workflow convention.
AGENTS_STARTUP.md §9 does not need an update.
No reference file needs to document a new workflow primitive.
No MCP tool is added or modified; the existing manage_connection binding is only consumed through a future-injected bridge.
The new consumed surface is documented in #13548's Contract Ledger and Accounts.mjs JSDoc.

Findings: All checks pass — no integration gaps.

🧪 Test-Execution & Location Audit

Branch checked out locally at exact head bca997f0bb472c062840ba7ee40ad0df387bb63a in /Users/Shared/codex/neomjs/neo/tmp/review-13550.
Canonical Location: modified spec remains in test/playwright/unit/apps/agentos/Accounts.spec.mjs, matching the app view surface.
Ran the specific changed test file.
Verified the code-change test coverage covers absent bridge, request shape, credential-free payload, success status, error status, and source-level fail-closed seam.

Findings: Tests pass.

Evidence:

UNIT_TEST_MODE=true npx playwright test -c test/playwright/playwright.config.unit.mjs test/playwright/unit/apps/agentos/Accounts.spec.mjs
# 8 passed (2.0s)

📋 Required Actions

No required actions — eligible for human merge.

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 96 - Strong fit with the App-Worker → Brain injected-bridge boundary; 4 deducted only because the actual shell injection remains future validation, deliberately outside this PR.
[CONTENT_COMPLETENESS]: 95 - PR body, Contract Ledger, JSDoc, and tests are complete for the leaf; 5 deducted for relying on Post-Merge Validation for the future shell injector.
[EXECUTION_QUALITY]: 94 - Exact-head diff is narrow, service contract compatible, CI green, and focused tests pass; 6 deducted because there is no full-shell runtime probe for the future injected bridge.
[PRODUCTIVITY]: 100 - Delivers all #13548 ACs while preserving the stated out-of-scope fences.
[IMPACT]: 60 - Useful cockpit/harness affordance with limited blast radius; not a core protocol change.
[COMPLEXITY]: 25 - Two-file additive change reusing an existing fail-closed pattern.
[EFFORT_PROFILE]: Quick Win - High value for the cockpit flow with a small, well-isolated implementation.

Good to merge once the human gate is ready.