@creatornader/agent-bridge 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -6,8 +6,25 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ## [Unreleased]
 
-The changes in this section are implemented on the 0.3.0 development line. They are
-not released until the matching tag, GitHub release, and npm package exist.
+## [0.3.1] - 2026-07-15
+
+### Added
+
+- Add `agent-bridge --version` and `agent-bridge -V` commands that print the
+  installed package version without loading backend configuration.
+
+### Changed
+
+- Clarify the boundary between agent harnesses, host applications, host adapters, and
+  MCP, CLI, HTTPS, and Node library access. Define `AGENT_BRIDGE_INSTANCE` as the
+  stable consumer key used for cursor paths, leases, and presence. Supported installers
+  generate this key, while direct clients may supply it. Document the released
+  no-instance fallbacks and the fact that the key is not a unique live process or
+  session.
+- Require manual release recovery to run the workflow at the tag it publishes so npm
+  provenance identifies the checked-out release source.
+
+## [0.3.0] - 2026-07-15
 
 ### Control, portability, and recovery
 
@@ -77,7 +94,7 @@ not released until the matching tag, GitHub release, and npm package exist.
 - SQLite gateway outbox, inbox cache, restart-safe synchronization, and explicit stale-cache results.
 - Cross-platform Node CLI with init, health, delivery, sync, presence, watch, migration, and client installation commands.
 - Cheap `pending` process gate for unread context or due delivery work.
-- Runtime manifests and native installers for Codex, Claude Code, and Claude Desktop.
+- Host-adapter manifests and native installers for Codex, Claude Code, and Claude Desktop.
 - Runtime-neutral `SKILL.md` guidance and an `llms.txt` package map.
 - PostgreSQL migrations with checksum validation and runtime schema readiness checks.
 - Restricted PostgreSQL runtime grants separated from schema migration credentials.
@@ -86,7 +103,8 @@ not released until the matching tag, GitHub release, and npm package exist.
 ### Changed
 
 - Package identity is `@creatornader/agent-bridge` at version `0.2.0`. The first npm publication was performed manually. OIDC trusted publishing was configured afterward for later releases.
-- Agent identity is process-scoped. Shared config no longer supplies `AGENT_BRIDGE_AGENT`.
+- Agent principal is injected through the client process. Shared config no longer
+  supplies `AGENT_BRIDGE_AGENT`.
 - Exact idempotent replays deduplicate. Reusing a key for changed content returns a conflict.
 - Gateway clients authenticate through separate principal-bound credentials stored in owner-only client backend files.
 - Package-root imports expose the provider-neutral API without starting the MCP server.
@@ -118,5 +136,7 @@ First tagged release. Marks the point where agent-bridge has shipped its initial
 - Narrative-leak detection in CI + on commit via `creatornader/textleaks@v0.2.0` (renamed from leakguard).
 
 [0.1.0]: https://github.com/creatornader/agent-bridge/releases/tag/v0.1.0
-[Unreleased]: https://github.com/creatornader/agent-bridge/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/creatornader/agent-bridge/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/creatornader/agent-bridge/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/creatornader/agent-bridge/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/creatornader/agent-bridge/compare/v0.1.0...v0.2.0

package/README.md

@@ -54,8 +54,9 @@ client configuration, and recovery steps.
 - Idempotency conflict detection. Exact replay deduplicates; changed content under the same key fails.
 - Scoped credentials that bind a remote workspace and agent principal.
 - SQLite outbox and inbox cache for gateway clients.
-- Leased runtime presence with instance IDs and capabilities.
-- MCP, CLI, Codex, Claude Code, and Claude Desktop integration paths.
+- Leased instance-keyed presence with capabilities.
+- MCP, CLI, HTTPS, and Node library access, plus host adapters for Codex, Claude Code,
+  Claude Desktop, OpenClaw, and generic MCP clients.
 - Canonical portable archives for messages and read receipts across local SQLite and shared PostgreSQL stores.
 - Native SQLite and PostgreSQL backup, verification, and restore.
 - Existing `post_context`, `get_context`, `ack_context`, `post`, and `get` behavior during migration.
@@ -70,30 +71,75 @@ The OpenAPI paths describe protocol 2.1. The embedded `x-agent-bridge-protocol-2
 
 ## Architecture
 
-```text
- Codex       Claude Code       Claude Desktop       scripts
-   |              |                  |                 |
-   +--------------+------------------+-----------------+
-                          MCP or CLI
-                              |
-                  process-scoped agent identity
-                              |
-             +----------------+----------------+
-             |                                 |
-       local SQLite                  SQLite edge store
-                                               |
-                                     authenticated HTTPS
-                                               |
-                                      Agent Bridge gateway
-                                               |
-                                          PostgreSQL
+```mermaid
+flowchart TB
+  subgraph execution["Agent execution"]
+    harnesses["Agent harnesses<br/>product-specific or custom"]
+    callers["Non-harness callers<br/>scripts, CI jobs, and application services"]
+  end
+
+  subgraph hosts["Host surfaces"]
+    clis["Command-line hosts<br/>Codex CLI and Claude Code CLI"]
+    desktops["Desktop hosts<br/>Codex in ChatGPT and Claude Desktop"]
+    daemons["Daemons and custom MCP hosts"]
+  end
+
+  subgraph access["Integration and access"]
+    adapter["Host adapter or MCP registration"]
+    mcp["MCP over stdio: agent-bridge-mcp"]
+    cli["CLI: agent-bridge"]
+    library["Node library"]
+    direct["Direct HTTPS client"]
+  end
+
+  harnesses --> clis
+  harnesses --> desktops
+  harnesses --> daemons
+  clis --> adapter
+  desktops --> adapter
+  daemons --> adapter
+  adapter --> mcp
+  callers --> cli
+  callers --> library
+  callers --> direct
+
+  mcp --> core["Agent Bridge client core<br/>principal plus optional consumer instance key"]
+  cli --> core
+  library --> core
+
+  core --> local["Local mode<br/>SQLite authority"]
+  core --> edge["Gateway client mode<br/>SQLite edge outbox and cache"]
+  edge -->|"HTTPS protocol 2.1"| gateway["Agent Bridge gateway"]
+  direct -->|"HTTPS protocol 2.1"| gateway
+  gateway --> postgres["PostgreSQL authority"]
 ```
 
+The diagram shows concepts, not exclusive product categories. A product may package a
+harness and a host together. A harness is the agent execution environment. A host is
+the CLI, desktop app, or daemon where it runs. A host adapter registers an access
+surface. Scripts are orthogonal callers: they can invoke the CLI, call HTTPS, or embed
+the Node library without becoming agent harnesses.
+
+| Adapter or integration | Host coverage | Access | Installation status |
+| --- | --- | --- | --- |
+| `codex` | Codex CLI and Codex in the ChatGPT desktop app through their shared profile | MCP stdio | Automated |
+| `claude-code` | Claude Code terminal harness | MCP stdio | Automated |
+| `claude-desktop` | Claude Desktop application | MCP stdio | Automated |
+| `openclaw` | OpenClaw host or daemon | MCP stdio | Manifest included; operator-managed |
+| `generic-mcp` | Any compatible stdio MCP host | MCP stdio | Manifest included; operator-managed |
+| Scripts and services | Shell jobs, CI, daemons, and application code | CLI, HTTPS, or Node library | Direct integration |
+| Hermes, Pi, and other harnesses | Depends on the host's supported interface | No interface assumed | No dedicated adapter or conformance claim yet |
+
+`agent-bridge-mcp` is a stdio server. The gateway exposes the Agent Bridge HTTPS API;
+it is not MCP over HTTP. A direct HTTPS client can bypass MCP, the CLI, and the local
+edge store, but then owns its own retry and offline behavior.
+
 Realtime notifications or hooks may wake a client, but cursored reads remain authoritative. A missed notification does not lose a message.
 
-A2A and application task semantics sit above Agent Bridge. MCP, CLI, and HTTPS are access surfaces. Optional transports such as SLIM or NATS may provide wakeups or transport below the core, but authoritative recovery still uses cursored pull. agmsg remains a reference for adapters, interoperability, and client experience.
+A2A and application task semantics sit above Agent Bridge. MCP, CLI, HTTPS, and the Node library are access surfaces. Optional transports such as SLIM or NATS may provide wakeups or transport below the core, but authoritative recovery still uses cursored pull. agmsg remains a reference for adapters, interoperability, and client experience.
 
 [ADR-0001](docs/decisions/0001-protocol-layers-and-acknowledgment-semantics.md) defines this boundary and the distinct acknowledgment meanings.
+[ADR-0003](docs/decisions/0003-host-adapters-and-consumer-instance-keys.md) defines the host layers and consumer instance-key contract.
 
 Agent Bridge is not a workflow engine, scheduler, memory system, terminal manager, or
 new universal agent protocol. See [Agent Bridge in the agent ecosystem](docs/ecosystem.md)
@@ -308,9 +354,10 @@ directory durability proof. Successful Windows commands report
 library API is available from
 `@creatornader/agent-bridge/dr`.
 
-## Install client integrations
+## Install host adapters
 
-Agent identity and gateway credentials belong to each client process, not the shared `~/.agent-bridge/config` file.
+Agent identity and gateway credentials belong to each installed client, not the shared
+`~/.agent-bridge/config` file.
 
 ```bash
 agent-bridge clients install codex --identity codex
@@ -330,11 +377,19 @@ AGENT_BRIDGE_CLIENT_TOKEN=<claude-desktop token> \
   agent-bridge clients install claude-desktop --identity claude-desktop
 ```
 
-`--token` accepts the same value, but the environment form avoids putting a credential in shell history. Each install writes an owner-only backend file under `~/.agent-bridge/clients/`. The host MCP registration receives that file path, the client identity, and a generated instance ID. Tokens are not copied into the shared config, and one client cannot reuse a token bound to another principal.
+`--token` accepts the same value, but the environment form avoids putting a credential in shell history. Each install writes an owner-only backend file under `~/.agent-bridge/clients/`. The host MCP registration receives that file path, the client identity, and a generated stable instance key. Tokens are not copied into the shared config, and one client cannot reuse a token bound to another principal.
 
-Codex and Claude Code installation uses their native MCP commands. Claude Desktop installation merges the `agent-bridge` server into its JSON config with an atomic write. Restart the client after installation.
+The `codex` adapter uses the Codex profile shared by the Codex CLI and the Codex
+surface in the ChatGPT desktop app; it does not install two independent registrations.
+Claude Code installation uses its native MCP command. Claude Desktop installation
+merges the `agent-bridge` server into its JSON config with an atomic write. Restart the
+client after installation.
 
-The runtime contracts are under [`clients/`](clients/). OpenClaw and generic MCP manifests declare the required environment variable and command but leave config mutation to the operator because their host config shapes vary.
+The v1 host-adapter manifests are under [`clients/`](clients/). Their compatibility
+field is named `runtime`, but its value identifies the installation target, not a
+unique process. OpenClaw and generic MCP manifests declare the required environment
+variables and command but leave config mutation to the operator because their host
+config shapes vary.
 
 [`SKILL.md`](SKILL.md) provides concise runtime-neutral operating instructions for agents. [`llms.txt`](llms.txt) gives tools and model crawlers a compact map of the package, modes, commands, and identity rules.
 
@@ -575,6 +630,7 @@ Normal inbox and pending reads fall back to the local cache when the gateway is
 ## CLI
 
 ```bash
+agent-bridge --version
 agent-bridge init --provider local
 agent-bridge doctor
 agent-bridge status
@@ -647,6 +703,22 @@ The acknowledgment names depend on the interface. MCP `ack_context` and CLI `ack
 ## Identity and security
 
 - `~/.agent-bridge/config` contains backend settings only. A stored `AGENT_BRIDGE_AGENT` value is ignored.
+- Workspace is the tenant boundary. Principal is the durable agent identity and message source.
+- `AGENT_BRIDGE_INSTANCE` is an optional caller-supplied stable consumer key. Supported
+  installers generate and persist one for each installed client. Direct clients should
+  do the same when they need separate consumer state or presence.
+- Unless `AGENT_BRIDGE_CURSOR` sets an explicit path, a present instance key selects
+  the cursor path. The key also selects the delivery lease owner and presence row.
+  Processes that share a key also share those resources. The gateway does not bind the
+  key to an installer registration. It is not a PID, unique live process, or
+  conversation ID.
+- When the key and explicit cursor path are both omitted, cursor storage uses
+  `default`. Delivery leases fall back to the principal, and presence operations reject
+  the request because presence requires an instance key.
+- Presence is instance-keyed in the released protocol. Per-process presence requires
+  an additive identity instead of a silent change to lease ownership or cursor paths.
+- Session and thread identifiers are message and application context. They do not
+  select credentials, workspace, principal, or delivery ownership.
 - Local clients bind identity through their process environment or an explicit CLI send argument.
 - Gateway tokens bind workspace and principal. The API ignores caller-supplied source and workspace fields.
 - Gateway clients use separate owner-only backend files and principal-bound tokens.
@@ -654,7 +726,8 @@ The acknowledgment names depend on the interface. MCP `ack_context` and CLI `ack
 - Remote HTTP must use TLS. Plain HTTP is accepted only on loopback.
 - Local config, database, WAL, and shared-memory files use owner-only permissions where the platform supports POSIX modes.
 - The private `agent_bridge` schema is denied to Supabase `anon` and `authenticated` Data API roles.
-- Expired presence rows are pruned during heartbeat and listing. Each agent is capped at 128 active instances, and each workspace is capped at 4,096.
+- Expired instance-presence rows are pruned during heartbeat and listing. Each agent
+  is capped at 128 active instance keys, and each workspace is capped at 4,096.
 - Errors expose stable codes without database URLs, tokens, or provider response bodies.
 - Delivery work is at least once, not exactly once. Consumers must make external side effects idempotent.
 
@@ -681,7 +754,7 @@ The original v1 schema remains in [`sql/setup.sql`](sql/setup.sql). Ordered gate
 `status` is a passive snapshot. It does not synchronize or probe a remote provider. An unprobed remote reports `status: "unknown"`, `connected: false`, and `remoteReachable: null`. Passive status still exits 0. `doctor` evaluates named checks and exits 0 for `ok`, 2 for `degraded`, and 1 for `failed`. Both return JSON with:
 
 - Provider and actual schema version.
-- Bound workspace, agent, and instance.
+- Bound workspace, agent, and consumer instance key.
 - Endpoint or database path.
 - Cursor and queue state.
 - Pending, claimed, retrying, and dead delivery counts, plus due versus scheduled work, expired leases, oldest-due time, and bounded queue lag.
@@ -759,11 +832,12 @@ durability behavior has not yet been proved on a dedicated Windows host.
 ## Documentation
 
 - [ROADMAP.md](ROADMAP.md): released work, unreleased implementation, and the remaining program.
-- [SECURITY.md](SECURITY.md): supported versions, private vulnerability reporting, and security boundaries.
+- [SECURITY.md](SECURITY.md): supported versions, release integrity, private vulnerability reporting, and security boundaries.
 - [docs/ecosystem.md](docs/ecosystem.md): product boundary, adjacent systems, and interoperability direction.
 - [docs/troubleshooting.md](docs/troubleshooting.md): MCP startup, identity, backend, and client recovery.
 - [ADR-0001](docs/decisions/0001-protocol-layers-and-acknowledgment-semantics.md): protocol layers and acknowledgment semantics.
 - [ADR-0002](docs/decisions/0002-canonical-operation-contract-registry.md): canonical contracts, generated artifacts, discovery, and version negotiation.
+- [ADR-0003](docs/decisions/0003-host-adapters-and-consumer-instance-keys.md): host layers and consumer instance-key semantics.
 - [docs/architecture-v2.md](docs/architecture-v2.md): protocol and storage decisions.
 - [SKILL.md](SKILL.md): runtime-neutral agent operating instructions.
 - [llms.txt](llms.txt): compact machine-readable project map.

package/ROADMAP.md

@@ -9,17 +9,17 @@ published and the supported clients pass a fresh end-to-end check.
 
 ## Status
 
-### Released in 0.2.0
+### Released by 0.3.0
 
 - Local SQLite and shared PostgreSQL storage behind provider-neutral interfaces.
 - An authenticated HTTPS gateway and a named legacy Supabase adapter.
 - Immutable messages, caller receipts, delivery leases, retries, dead letters, and
   presence.
 - Durable SQLite edge outbox and inbox cache for gateway clients.
-- CLI, MCP, Codex, Claude Code, and Claude Desktop integration paths.
-
-### Implemented for the next release
-
+- CLI, MCP, HTTPS, and Node library access surfaces.
+- Automated host adapters for Codex, Claude Code, and Claude Desktop. The Codex
+  adapter configures the profile shared by the Codex CLI and the Codex surface in the
+  ChatGPT desktop app.
 - Caller-bound inbox, sent, and combined history with scope-bound cursors.
 - Publisher-owned delivery policy, priority claims, cancel, requeue, and delivery event
   inspection.
@@ -34,13 +34,14 @@ published and the supported clients pass a fresh end-to-end check.
 - Portable workspace archives across canonical SQLite and PostgreSQL stores.
 - Native SQLite and PostgreSQL backup, verification, and restore.
 
-### Required before the next release is complete
+### Post-release validation and adoption
 
-- Merge the development branch through the protected-main checks.
-- Publish the package through the configured npm OIDC workflow.
-- Prove Codex, Claude Code, and Claude Desktop startup, send, receive, receipt, claim,
-  settlement, offline replay, and restart behavior against the released package.
-- Move the project's own normal traffic to v2 while retaining a tested v1 rollback path.
+- Move the project's own normal traffic to the authenticated gateway while retaining a
+  tested legacy rollback path.
+- Prove cross-machine claim, settlement, offline replay, and restart behavior against
+  the published package and a deployed v2 gateway. The 0.3.0 live release check covered
+  startup, private mailbox sends, caller-scoped history, receipts, and client restart
+  through the legacy compatibility backend; it could not prove gateway-only behavior.
 - Replace remaining direct legacy table pollers with the v2 cursor protocol.
 - Confirm the README, npm metadata, GitHub metadata, release notes, and package contents
   match the released artifact.
@@ -64,6 +65,11 @@ published and the supported clients pass a fresh end-to-end check.
 
 ### Presence and wakeups
 
+- Separate the stable consumer instance key from a live process identity. Supported
+  installers generate one key per installed client, while direct clients may supply
+  their own. Processes that share a key also share presence in 0.3.
+- Add per-process presence and session correlation only through an additive protocol
+  change with migration and conformance coverage.
 - Maintain heartbeat and expiry automatically for supported long-lived clients.
 - Add wake adapters only where they reduce latency. Lost wakeups must never lose data.
 - Keep cursored pull as the authoritative recovery path.
@@ -83,7 +89,11 @@ published and the supported clients pass a fresh end-to-end check.
 - Carry A2A envelopes without implementing a competing task state machine.
 - Publish conformance fixtures and an adapter template.
 - Add client libraries where real integrations need them.
-- Expand runtime installers after each host has a stable configuration contract.
+- Rename the compatibility `runtime` manifest key to an explicit host-adapter key in a
+  versioned manifest contract.
+- Expand host installers after each product has a stable configuration contract.
+  Hermes, Pi, and similar harnesses can use a generic access surface when their host
+  supports one, but they do not have a dedicated adapter or conformance claim.
 
 See [docs/ecosystem.md](docs/ecosystem.md) for the product boundary.
 

package/SECURITY.md

@@ -4,13 +4,30 @@
 
 | Version | Security updates |
 | --- | --- |
-| 0.2.x | Supported until its successor is released |
+| 0.3.x | Supported |
+| 0.2.x | Not supported |
 | 0.1.x | Not supported |
 | Unreleased development code | No public support guarantee |
 
 Upgrade to the latest published package before reporting a defect that may already be
 fixed. The npm package and GitHub release page are the public version authorities.
 
+## Release integrity
+
+GitHub immutable releases are enabled, and GitHub reports release `v0.3.0` as
+immutable. A repository ruleset also blocks updates and deletion for every `v*` tag
+without a bypass actor. The `v0.3.0` tag is unsigned.
+
+npm publication uses a protected GitHub environment, an OIDC trusted-publisher
+binding, and provenance for the package artifact. Verify the package digest and
+attestation before treating provenance as source identity. The `v0.3.0`
+[recovery run](https://github.com/creatornader/agent-bridge/actions/runs/29461308262)
+checked out package commit `95eb861`, while its attestation names recovery commit
+`c23d9df` as the workflow identity. GitHub Actions logs expire, so the
+[release notes](https://github.com/creatornader/agent-bridge/releases/tag/v0.3.0)
+also record this boundary. Future recovery dispatches must run at the release tag, and
+the workflow enforces that match before packaging.
+
 ## Report a vulnerability
 
 Use [GitHub private vulnerability reporting](https://github.com/creatornader/agent-bridge/security/advisories/new).

package/SKILL.md

@@ -87,4 +87,4 @@ the source.
 
 Use `project` only as an optional message label. Workspace remains the tenant and credential boundary. Omit a project filter to read labeled and unlabeled messages, or provide one for an exact match. Reusing a workspace/source idempotency key with a different project is a conflict.
 
-For gateway mode, treat the credential-bound workspace and principal returned by the server as authoritative. Instance identifies one runtime of that same principal; it cannot select a workspace, agent, or scopes. A production gateway reports row isolation only when transaction-bound request authority and every database readiness check pass. RLS isolates workspace and principal rows. The service still enforces lease transitions and target-to-delivery membership.
+For gateway mode, treat the credential-bound workspace and principal returned by the server as authoritative. Instance is an optional caller-supplied stable consumer key; it cannot select a workspace, agent, or scopes. Supported installers generate and persist it. Direct clients may do so when they need separate consumer state or presence. The gateway does not bind the key to an installer registration. Unless `AGENT_BRIDGE_CURSOR` is explicit, processes that share one key also share its cursor path. They also share delivery lease ownership and instance-keyed presence. Without a key or explicit cursor path, cursor storage uses `default`. Leases use the principal, and presence is unavailable. Instance is not a PID, unique live process, session, or thread. A production gateway reports row isolation only when transaction-bound request authority and every database readiness check pass. RLS isolates workspace and principal rows. The service still enforces lease transitions and target-to-delivery membership.

package/dist/cli.js

@@ -3437,6 +3437,11 @@ function watchCursorPath(path, project) {
   const scope = createHash4("sha256").update(project).digest("hex").slice(0, 16);
   return `${path}.project-${scope}`;
 }
+function packageVersion() {
+  const manifest = JSON.parse(readFileSync3(fileURLToPath2(new URL("../package.json", import.meta.url)), "utf8"));
+  if (typeof manifest.version !== "string" || !manifest.version) throw new Error("package version is unavailable");
+  return manifest.version;
+}
 function help() {
   process.stdout.write(`agent-bridge: provider-neutral agent messaging
 
@@ -3448,6 +3453,10 @@ Commands:
   archive <export|verify|import>
   dr <backup|verify|restore>
   clients install <codex|claude-code|claude-desktop> --identity <name>
+
+Options:
+  -V, --version  Print the installed package version
+  -h, --help     Show this help
 `);
 }
 function rejectUnknownOptions(options) {
@@ -3629,6 +3638,11 @@ async function runCli(argv = process.argv.slice(2)) {
   }
   const { command: raw, options, positionals } = parse3(argv);
   const command = { post: "send", get: "inbox", receipt: "acknowledge" }[raw] ?? raw;
+  if (["-V", "--version"].includes(command)) {
+    process.stdout.write(`${packageVersion()}
+`);
+    return;
+  }
   if (["help", "-h", "--help"].includes(command)) {
     help();
     return;