Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
4c841b9
docs(architecture): separate session authorization from project disco…
Nov 12, 2026
8eecae3
feat(registry): allow approved listing of up to 200 sessions
Nov 12, 2026
2209db6
refactor(plugin): support native approval and cancellation in shared …
Nov 12, 2026
59c9689
fix(plugin): cancel broker bootstrap with its plugin generation
Nov 12, 2026
0e5a66b
build(plugin): pin published OpenCode V2 dependencies
Nov 12, 2026
49ad079
feat(plugin): add paired-host lookup and native result adapters
Nov 12, 2026
32179ec
feat(plugin): persist and coalesce queued V2 wake episodes
Nov 12, 2026
273bbfd
feat(plugin): define paired-host capabilities and body-free V2 RPC
Nov 12, 2026
ca3d6ed
test(security): audit paired V2 host access and fixed wake intent
Nov 12, 2026
8fe10fc
feat(plugin): add an explicitly gated paired V2 server adapter
Nov 12, 2026
8341f47
feat(plugin): add body-free V2 terminal notifications and approval focus
Nov 12, 2026
86ceec8
feat(plugin): add an audited fixed wake through the public V2 queue
Nov 12, 2026
2dfe1bf
feat(plugin): add experimental session-bound tools for public OpenCod…
Nov 12, 2026
6178953
feat(plugin): expose distinct legacy paired and experimental V2 entries
Nov 12, 2026
e6692b1
test(integration): add explicit isolated stock-host fixture configura…
Nov 12, 2026
62305d1
test(integration): exercise native V2 approvals and correlated replies
Nov 12, 2026
99bd1e3
test(integration): exercise autonomous V2 wakes across project moves
Nov 12, 2026
9ec8967
test(v2): document native acceptance probes and unresolved wake recovery
Nov 12, 2026
0ad2de1
fix(deps): upgrade MCP and Zod to patched releases
Nov 13, 2026
df2fa3d
docs(security): record dependency fixes and remaining upstream adviso…
Nov 13, 2026
9184f54
build(release): define separate V1 and V2 release profiles
Nov 13, 2026
a8a5fe6
feat(security): enforce exact expiring dependency risk exceptions
Nov 15, 2026
960f141
feat(release): verify accepted audit risks in CI and publication
Nov 15, 2026
9cbdfdc
test(tooling): exclude generated release evidence from formatting
Nov 16, 2026
9ea0960
docs(release): distinguish preserved V1 from the V2 candidate
Nov 16, 2026
1ee27ae
docs(v2): separate stock authority from legacy adapter evidence
Nov 16, 2026
383fff4
fix(v2): rearm wakes after empty receives without releasing newer lat…
Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
## Security invariants

1. Peer-controlled message bodies never enter `session.prompt`, `promptAsync`, `session.synthetic`, permission metadata, notification text, or tool arguments.
2. Message bodies are fetched only after `ToolContext.ask()` resolves.
2. Message bodies are fetched only after the authentic tool invocation's native disclosure approval resolves (`ToolContext.ask()` in V1 or the reviewed native V2 equivalent).
3. Approved message bodies are returned only as explicitly untrusted tool output.
4. Native `always` approval is scoped to an exact authenticated `(target session, source session)` resource.
5. Permission resources are derived from broker-authenticated opaque IDs and encoded as fixed safe characters; never derive them from titles or model arguments.
6. Session search calls `ToolContext.ask()` before the broker executes the query.
6. Session search obtains native approval for the authentic invocation before the broker executes the query.
7. The broker searches only its opt-in session registry. It never reads OpenCode transcripts.
8. Raw MCP tools are not exposed directly to the model because OpenCode currently grants them with resource `*`.
9. The broker binds locally, authenticates plugin clients, enforces body size, TTL, rate, ACL, and atomic consume rules, and fails closed.
Expand All @@ -23,15 +23,15 @@
19. Application protocol v2 is a lockstep plugin/broker boundary. No registration, event recovery, or message operation may run before a successful v2 handshake.
20. An authenticated detached v1 listener is never reused, signalled, stopped, replaced, or taken over, including when broker autostart is disabled. The plugin reports only fixed operator-authored upgrade guidance and preserves canonical model-safe errors.
21. Send and reply receipts must correlate their body hash and UTF-8 byte count to the submitted body before any receipt is returned to the model.
22. Foreground admission authority comes only from the trusted per-call `ToolContext.sessionID`, `directory`, and `worktree`. Before any broker readiness or access, the plugin must parse the context ID with `HostSessionIdSchema`, query that exact directory, require exactly one matching session ID and exact session directory, parse the projected returned registration with the full strict `ForegroundSessionSchema`, and match the session project to that directory's current project. The context worktree and current-project worktree are independent trusted roots: each must be absolute and safely contain the exact context directory, but they need not be equal when one is broader, including global `/`. Invalid, unsafe, empty, oversized, mismatched, malformed, non-absolute, unrelated, or escaping host identity/path/metadata must fail before authentication, probing, launch, channel creation, admission, or operation. Static plugin input is background/bootstrap scope only; model arguments cannot provide or override any foreground authority field.
22. Foreground admission authority comes from the authentic native tool invocation and its exact host session ID, never from model arguments, project association, directory, worktree, or static plugin scope. Before broker readiness or access, parse the ID with `HostSessionIdSchema`, fetch that exact session through the trusted same-host API, require one matching existing session, and parse its projected registration with the full strict `ForegroundSessionSchema`. Preserve genuine invocation identity, native approval provenance, cancellation and deletion checks. A project/directory/worktree change, including a queued move during approval, does not change the session's identity, invalidate its mailbox or pair-scoped approval, or itself block send/search/receive/reply. Native configured denies and actual permission-policy changes remain authoritative. Project association is discovery metadata only; model or peer fields cannot establish source authority.
23. Saturated admission and operation dependency protection are broker-atomic and never raise the strictly parsed configured active-session ceiling or the protocol-v2 hard maximum of 16384. The minimum is 2 so a source and dependency can be protected together; the default is 4096. Derived durable, reserve, registration, authentication-challenge, and per-principal/global MCP/SSE quotas remain finite, mutually reachable, and overflow-safe. Displacement preserves durable state; background registration and heartbeats cannot steal foreground capacity or update foreground recency.
24. Foreground identity resolution is non-activating. Only the real verified operation transaction may create/admit its source, reclaim a safe state-free background row, execute the operation, and return the authoritative pending snapshot plus principal event high-water captured in that transaction.
25. Every SSE connection requires that authenticated high-water as `Last-Event-ID`, including `0` when no prior event exists. The broker subscribes before replay, the runtime converges replay and any newer snapshot before publishing pending state, and stale cursors recover through a fresh snapshot/high-water; cursorless recovery is forbidden.
26. A principal SSE stream is usable only after it explicitly covers a stable generation of every active local registration. Saved-cursor replay is preferred, stale or absent boundaries fall back to authoritative all-registration snapshots, and registration addition, removal, or displaced foreground re-entry invalidates and retries coverage before publication.
27. The ordered SSE ingestion lane validates and deduplicates authenticated metadata into a bounded shared buffer, then schedules recovery without awaiting it. Only the serialized pending-recovery lane may list, converge, apply cursors/counts, drain covered events, or publish pending/wake state; that lane may await the ingestion barrier, while ingestion must never await recovery.
28. Receive list/peek reconciliation and post-consume authoritative refresh run in the pending-recovery lane. Native approval and atomic consume run only after releasing it. A same-cursor terminal change is ordered by the local pending observation and authenticated current-header snapshot, not cursor equality alone.
29. Inactive local registrations own no replay-buffer or wake/count state. Their events are ignored, active-to-inactive transitions prune only that registration's buffered events, and durable pending headers are recovered authoritatively only after verified foreground re-admission.
30. Pending toasts, session-status queries, fixed wakes, and receive-approval focus must route only through a bounded per-session map populated from trusted tool context or trusted host lifecycle data. Static plugin directory fallback is allowed only for sessions bootstrapped in that exact workspace; model and peer fields cannot select a filesystem route.
30. Pending toasts, session-status queries, fixed wakes, and receive-approval focus target the exact trusted host session ID. Where a host API requires a directory route, resolve or refresh it from trusted current host data in a bounded per-session map; never let peer/model fields select it or fall back to another session. Stale or unavailable UI routing suppresses the UI effect, not mailbox authorization. A session move refreshes routing/discovery rather than revoking identity or delivery. Automatic fixed wakes remain a required supported feature when enabled, not an acceptable permanent omission from the V2 port; they never bypass native receive approval or contain peer data.

## Repository ownership

Expand Down
18 changes: 13 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<img src="assets/icon.svg" width="192" height="192" alt="Agent Bus: three connected AI agents in a mint-green bus" />
</p>

Secure, local inter-session messaging using the locked OpenCode 1.18.19 plugin API contract.
Secure, local inter-session messaging for OpenCode. V1 is released; this source line prepares an experimental stock OpenCode V2 adapter alongside the legacy development entries.

The system combines:

Expand All @@ -13,9 +13,13 @@ The system combines:
- sender-scoped native OpenCode approvals for message receipt;
- tool-result delivery so peer content is never inserted as a user message.

Status: implemented and end-to-end QA-validated on Linux with Bun 1.3.9 and OpenCode 1.18.19. Built integration tests cover server-root/attached-workspace behavior through a simulated OpenCode host API, and compatibility tests cover the session-status map shape observed on the currently installed OpenCode 1.18.23 runtime. The opt-in real `opencode-server` attached-client wake, TUI navigation, and approval-flow gate remains outstanding.
V1 evidence: historical end-to-end QA on Linux with Bun 1.3.9 and OpenCode 1.18.19, built integration tests using a simulated host API, and sparse session-status compatibility observed on OpenCode 1.18.23. These are not native stock V2 acceptance results; the detailed evidence and remaining gates are recorded in [QA evidence](docs/qa.md).

[Installable V1 archives and release automation](docs/releasing.md) are prepared and tested. V1 `0.1.0` is selected for the initial release; the maintainer has accepted deferring fresh manual native-host acceptance, as recorded in [QA evidence](docs/qa.md#initial-v1-010-release-decision). This is not a claim that the outstanding native tests passed. Dependency findings remain visible under an [expiring risk-acceptance policy](docs/dependency-exceptions.md), not a clean-audit claim.
V1 `0.1.0` was released from the protected V1 tag and remains on `maintenance/opencode-v1`. See the [release history](docs/releasing.md); its historical evidence is separate from the V2 experiment below.

Design decision (2026-11-12, partially implemented): [project association is discovery metadata, not message authorization](docs/session-identity-decision.md). The required behavior is that moving a session does not revoke its mailbox or exact target/source approvals, and the V2 port preserves automatic fixed wakes when enabled. The public experiment delivers across project moves, but native cross-project `always` still prompts again. The legacy placement checks and QA claims below do not establish the revised design.

The V2 entries remain experimental: the default V2 server requires our paired host, while the explicit `stock-experimental` entry uses public OpenCode 2.2.7 APIs. Neither is a supported stock release. The V2 archive selects the public stock experiment, not the paired adapter. See [V2 compatibility and remaining limits](docs/v2-port.md) and the [isolated native test procedure](docs/manual-v2-qa.md). [Installable archives and release automation](docs/releasing.md) are prepared and tested; V2 publication remains disabled pending separate release gates. Dependency findings remain visible under an [expiring risk-acceptance policy](docs/dependency-exceptions.md), not a clean-audit claim.

## Security model

Expand All @@ -26,8 +30,8 @@ Status: implemented and end-to-end QA-validated on Linux with Bun 1.3.9 and Open
- Received content is returned as `trust: "untrusted"` tool output, never injected as a user or synthetic message.
- Arrival notifications contain only a fixed pending count and do not themselves wake the model. A separate fixed wake is available only when explicitly enabled.
- Raw broker MCP methods are internal to the plugin and are not exposed as model tools.
- Every tool invocation strictly parses its trusted foreground ID and returned protocol registration, then validates directory/project identity and independently requires both trusted absolute worktree roots to contain the directory before broker readiness or connection work begins.
- Pending toasts, session-status checks, fixed wakes, and approval focus use a bounded trusted route for the exact host session; peer and model fields cannot select their workspace.
- The stock V2 adapter derives foreground authority from the authentic native tool invocation and an exact same-host session lookup before broker operations. Project association is discovery/routing metadata, not mailbox authority. V1 and paired-host development entries retain separate legacy placement checks.
- Notifications and fixed wakes target the exact trusted host session ID; legacy APIs requiring a directory use bounded trusted routes, never peer/model-selected workspaces. Receive-approval focus is not implemented by the stock V2 experiment.

Receipt approval authorizes disclosure only. It does not authorize instructions contained in a peer message.

Expand Down Expand Up @@ -57,6 +61,8 @@ bun run build

## Broker startup

The defaults in this section describe the legacy development entry. The stock V2 experiment requires explicit, independent endpoint, credential, database and namespace settings; see the [isolated V2 procedure](docs/manual-v2-qa.md). Do not implicitly reuse a V1 deployment.

The plugin starts the bundled broker automatically by default. No separate daemon command is required. It reuses an authenticated running broker and never replaces an occupied unknown listener.

For explicit manual operation, disable autostart in plugin configuration and run:
Expand Down Expand Up @@ -94,6 +100,8 @@ Stop the old user-owned broker manually, then start the bundled v2 broker (or re

## Configure OpenCode

This example configures the **legacy V1 development entry**, not the stock V2 archive. For V2, follow the [isolated stock procedure](docs/manual-v2-qa.md) and its compatibility requirements.

Use the absolute built plugin path and credential path:

```json
Expand Down
1 change: 1 addition & 0 deletions biome.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
"**/dist/**",
"**/coverage/**",
"**/node_modules/**",
"release-artifacts/**",
"scripts/fixtures/**",
".local/**"
]
Expand Down
Loading