DOCUMENTATION · v0.12.2

Feature → code → test traceability

This matrix is the audit behind the claim "the documented features work". A feature is only marked verified when a test exercises its behaviour, not when an identifier merely exists. "Browser E2E" means the multi-agent scenario on the example site (docs/E2E.md); "scenario" means tests/agent-scenarios.test.mjs.

Run everything offline with npm run test:all and node --test tests/agent-scenarios.test.mjs. Connection-bound presence is covered by tests/connection-lifecycle.test.mjs (12 tests). The generic browser scenario is npm run test:e2e and the Body4AI scenario is npm run test:e2e:body4ai; both need Chromium plus relay/ICE connectivity.

Identity and wallet#

FeatureCodeEvidenceStatus
Stable, cryptographically derived identitypackages/p2p/index.js (identityFor, signEnvelope)p2p-wallet.test.mjs, agent-identity.test.mjsVerified (unit)
Browser key generation and origin-scoped storagepackages/p2p/index.js (IndexedDB wallet)p2p-wallet.test.mjs; browser E2E wallet creationVerified (unit + E2E)
Headless key generation, encrypted file storagepackages/agent/keystore.jskeystore.test.mjs (permissions, corruption, wrong passphrase)Verified (unit)
Backup, restore, rotate, deletepackages/agent/keystore.jskeystore.test.mjs; docs/RECOVERY.mdVerified (unit)
Signed messages and actionssignEnvelope / verifyEnvelope in packages/p2pe2e.test.mjs, agent-scenarios A/F, browser E2E steps 9/20Verified (unit + E2E)
Challenge-response consentcreatePermissionRequest / approvePermissionRequest / verifyPermissionConsente2e.test.mjs, connect-cancel.test.mjs, browser E2E step 2Verified (unit + E2E)
Site-specific capabilitiespackages/p2p/capabilities.js, P2PRoom policyparticipation.test.mjs, browser E2E steps 11/18Verified (unit + E2E)
Session length, renewal, expiry, idle endpackages/p2p/session.jssession-lifetime.test.mjs, browser E2E step 3Verified (unit + E2E)
Revocable permissions and linkspackages/p2p/revocation.js, links.jsrevocation.test.mjs, site-links.test.mjs, browser E2E steps 15/16Verified (unit + E2E)
Multiple independent walletsseparate IndexedDB / keystore per agentscenario A (three wallets); browser E2E (six participants)Verified (scenario + E2E)
Reconnection with the same identitypackages/agent/runtime.js (resume, join)runtime.test.mjs, scenario EVerified (unit + scenario)
Concurrent sessions of one identity—packages/agent/README.md says a keystore clone is the same identityLimitation

Agent, runtime, connection, room#

FeatureCodeEvidenceStatus
Identity outlives a connectionkeystore + runtime.jsscenario E; runtime.test.mjs restart/resumeVerified (scenario)
Runtime owns the connection; page close is unrelatedpackages/agent/runtime.js, NostrWebRTCscenario B; browser E2E step 12Verified (scenario + E2E)
Presence ends when the runtime ends (no ghost)heartbeat leases + peer/goodbyepresence.test.mjs, runtime.test.mjs, scenario EVerified (unit + scenario)
A visitor returning sees identities and cursorscreateAIAuthAgentClient, presence.jsagent-client-presence.test.mjs, scenario C, E2E step 13Verified (unit + scenario + E2E)
Rooms are shared environments, open or restrictedpackages/p2p/p2p.js, membership.jsp2p-transport.test.mjs, participation.test.mjsVerified (unit + E2E)
Private presence modeP2PRoom({ privateMode })participation.test.mjs, browser E2E step 19Verified (unit + E2E)
Reconnect after transport lossbackoff + rejoin in runtime.jsruntime.test.mjs (backoff, silent transport)Verified (unit)

Tools#

FeatureCodeEvidenceStatus
Page tools: catalog, request, response, cancelpackages/p2p/webmcp.js, embed.jswebmcp-contract.test.mjs, in-page-agent.test.mjs, tool-addressing.test.mjsVerified (unit + E2E)
Human approval for each page tool callmountAIAuthInPageAgent({ authorize })in-page-agent.test.mjs, browser E2E step 10Verified (unit + E2E)
Authorization failure cannot run a page toolmembership/execution grantsparticipation.test.mjs, browser E2E steps 6/11Verified (unit + E2E)
Page tools require the page opencatalog expiry + absent-site pruningscenario D2; webmcp-contract.test.mjsVerified (scenario)
Agent-provided tools with no browserpackages/agent/tool-provider.js, runtime.provideToolstool-provider.test.mjs (7 tests), scenarios D/FVerified (unit + scenario)
Tool calls are authorized by the provider's ownercreateToolProvider({ authorize })tool-provider.test.mjs (denied call never runs the handler)Verified (unit)
Bounded tools: size, count, timeout, concurrencypackages/agent/tool-provider.jstool-provider.test.mjs (oversized result, failure)Verified (unit)
MCP exposure of participant toolspackages/mcp/bridge.js (listTools, invoke)bridge.test.mjs, scenarios D/FVerified (unit + scenario)
MCP built-in room tools (--provide room)packages/mcp/bridge.js, cli.js, cli-args.jsbridge.test.mjs, cli.test.mjsVerified (unit)

Connection-bound presence and WebMCP#

FeatureCodeEvidenceStatus
Strict connected requires live authenticated transportpackages/p2p/connection-state.js, packages/mcp/bridge.jsconnection-lifecycle.test.mjs 1; connection-state.test.mjs; cli.test.mjsVerified (unit)
Heartbeat lease + implicit offline on silencepackages/p2p/p2p.js, presence.js, runtime.jsconnection-lifecycle.test.mjs 5; presence.test.mjsVerified (unit)
Immediate invalidation on channel/ICE failureP2PRoom.invalidateSource, NostrWebRTC.handleChannelLostconnection-state.test.mjs (peer-connect-failed → reconnecting)Verified (unit)
Reconnect with new generation, same identityruntime.js (join, setGeneration)connection-lifecycle.test.mjs 7; agent-scenarios EVerified (unit + scenario)
Expired/revoked authorization blocks reconnectruntime.js (authorization, setAuthorization)connection-lifecycle.test.mjs 8; session-lifetime/revocation testsVerified (unit)
One live runtime per identity in a processruntime.js (liveIdentities)connection-lifecycle.test.mjs 12Verified (unit)
Page WebMCP catalog is connection-boundwebmcp.js, embed.jsconnection-lifecycle.test.mjs 9; agent-client-presence.test.mjsVerified (unit)
Schema validation and stable tool error codeswebmcp.js, tool-provider.js, bridge.jsconnection-lifecycle.test.mjs 3/9; webmcp-contract.test.mjsVerified (unit)
Browser connected/disconnected/tool-withdrawn evidencescripts/test-browser-e2e.mjsgeneric-site-connected.png, generic-site-disconnected.png, generic-agent-tools-withdrawn.pngVerified (browser E2E)
Code Mode (worker-thread script over checked APIs, kill timeout)packages/mcp/bridge.js (--code-mode)bridge.test.mjs, code-mode-timeout.test.mjsVerified (unit)

Integration and user experience#

FeatureCodeEvidenceStatus
Copyable connect instruction and connect panelpackages/p2p/agent-connect.jsagent-connect.test.mjs, scenario G, browser connect flowVerified (unit + scenario + browser)
SDK works on a generic site with no example codepublic package exportsscenario G (generic origin, no private imports)Verified (scenario)
Example site: identity, cursor, chat, wheel, toolsexamples/body4ai/site/*browser E2E steps 1–20; site e2e/visual/body4ai-visual.mjsVerified (browser E2E)
MCP over stdio and HTTPpackages/mcp/index.js, http.jsserver.test.mjs, cli.test.mjsVerified (unit)
Claude Code as a harnesspackages/mcp docsdocs/agents.md 2026-11-15 recordVerified (manual)
Codex as a harnesspackages/mcp docsregistration only; model call blocked by usage limitLimitation
OpenCode as a harnesspackages/mcp docsconnected and listed tools; no completed callLimitation
ChatGPT desktop plugin harness--http MCP endpointdocs/agents.md harness notes; 2026-11-16 three-agent run (A/C active, B manual re-add)Verified (manual)

Remaining limitations (real, not hidden)#

  1. A connection lasts only while its runtime runs. There is no hosted agent host, and none is required. When ChatGPT, Codex, Claude Code, OpenCode or a custom process stops (or loses networking), its connection ends. Identity stays in the wallet and the next connection reuses it. Non-expiring sessions do not keep a dead process alive.
  2. Page tools need a page. Only the site's page can run them. With no page open they disappear from the catalog; callers get an explicit unavailable answer. Agent-provided tools (provideTools, --provide room) are the category that works without a page.
  3. No TURN. Direct WebRTC fails on some NAT/firewall combinations. The runtime reports diagnostics and stays waiting-for-peers; it does not silently fall back.
  4. One identity, one live runtime. Copies of a keystore are the same identity. A second live runtime with the same identity is now rejected within one process; cross-process lease coordination is still unsupported.
  5. Codex and OpenCode tool calls are not verified end to end. Their servers were registered and tools discovered, but no model-initiated call completed in the recorded runs.
  6. ChatGPT plugin B needs one manual re-add. Its HTTP endpoint is a credential printed by the CLI, and its public hostname changed when the process/quick tunnel restarted. ChatGPT keeps the stale URL, so the plugin must be removed and added again with the current URL. Agents A and C still work. The current URL is reported out of band; it is deliberately not committed because the secret path is the credential.
  7. Node scenario tests use an in-process transport. They verify signing, routing, and lifecycle, not real relay/ICE behaviour. The browser E2E is the real-network evidence.
  8. No Playwright screenshot exists for reconnecting. The state is exposed in ai_auth_status and asserted by unit tests, but the generic browser UI does not yet surface a distinct reconnecting badge. Screenshots cover connected, disconnected, and withdrawn-tool states.
  9. Cross-network/symmetric-NAT behavior is not proven. The real-browser evidence uses one machine/network; there is no TURN.
On this page