feat(spec): bridge protocol v0.1 — ops, capabilities, transports, security

[espetro]

Summary

Draft of the AnyHarness bridge protocol v0.1 — the versioned JSON-RPC contract ("LSP-for-extensions") that lets any agent harness adopt the registry + install + trust layer by implementing the client side once, instead of building a plugin system. Part of the v2 foundation plan (.agents/plans/2026-10-07-v2-foundation.md, W3).

Changes

Adds spec/bridge/:

• protocol.md — JSON-RPC 2.0 envelope (NDJSON framing, no batches), protocolVersion handshake + sibling-spec version negotiation (specs map referencing spec/manifest.md's versioning policy by name), error model (standard codes + -32001…-32012 bridge codes + -32800 cancel), ordering/streaming rules (streamId-correlated events.notify for hook progress/deltas), session lifecycle.
• operations.md — the exact 8-op set: capabilities.negotiate, extensions.list, extensions.get, hooks.invoke, commands.resolve, skills.materialize, tools.call (MCP passthrough), events.notify. Each op: params, result, error codes, and when the harness calls it.
• capabilities.md — Capabilities = declared ExtensionKinds + canonical hook events + host env slots (storage|secrets|exec|skills|mcp); graceful-degradation-by-filtering rules; feature-vs-permission split.
• transports.md — stdio (primary; harness serve, NDJSON), HTTP loopback (daemon + browser contexts; bearer token, serve.json port/token discovery, SSE notifications), in-process (@any-harness/sdk createBridge()); caller-identity model + per-caller allow/deny op scoping for daemon mode.
• messages.schema.json — JSON Schema draft 2020-12 for the envelope and every op's params/result.
• security.md — trust boundaries (adopting the bridge = adopting the trust layer), per-context loopback threat model (file perms vs bearer/CORS/Host-header rules), script-policy surfacing through capabilities, non-goals.

Interface pins kept verbatim: Extension, ExtensionKind, ManifestRef, Capabilities. Store layout and manifest fields are referenced by name (spec/store-layout.md, spec/manifest.md, spec/lockfile.md, spec/trust.md), never redefined.

Test plan

• pnpm test passes — n/a, docs-only change, no code touched
• pnpm -r exec tsc --noEmit passes — n/a, no TS changes
• Capability matrix updated (if adapter behaviour changed) — n/a
• Linked to a refined issue in Project 14
• messages.schema.json parses as valid JSON

Notes

• Deliberate design calls worth review: NDJSON framing over LSP Content-Length headers (matches MCP stdio); cancellation routed through events.notify/request.cancelled to keep the op set closed at 8; auth-failed/forbidden/capability-unsupported kept as three distinct failure axes (401/403/feature-grant); TLS off on loopback, justified in security.md §2.
• Intended as the attachable artifact for claurst #186 / jcode #745 outreach once reviewed.

Link to Devin session: https://app.devin.ai/sessions/47d4fa2868ca426eb7bfc3181b136e00
Open in Devin Desktop: https://app.devin.ai/desktop/session/47d4fa2868ca426eb7bfc3181b136e00?variant=devin
Requested by: @espetro

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[cursor]

Approved. Cursor Bugbot was not present after the first check poll, so that signal was skipped; no approval policy requires human review, and this automation has no prior approval to keep or dismiss.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}