@creatornader/agent-bridge 0.3.0 → 0.3.1

package/docs/architecture-v2.md

@@ -1,6 +1,6 @@
 # Agent Bridge v2 architecture
 
-Status: living architecture for the 0.3.0 development line. Version 0.2.0 was released on July 14, 2026.
+Status: living architecture. Version 0.3.0 was released on July 15, 2026.
 
 ## Product boundary
 
@@ -13,12 +13,14 @@ These authorization guarantees apply to local v2 and the authenticated gateway.
 - Local mode runs without an account or network connection.
 - Shared mode uses a remote service so agents on different machines see the same history and delivery state.
 
-The protocol must support informational context and executable work without treating them as the same thing. A2A and application task semantics sit above Agent Bridge. MCP, CLI, and HTTPS are access surfaces. Optional transports may sit below the core, but they cannot replace authoritative cursor replay or durable delivery state.
+The protocol must support informational context and executable work without treating them as the same thing. A2A and application task semantics sit above Agent Bridge. MCP, CLI, HTTPS, and the Node library are access surfaces. Agent harnesses and host applications use those surfaces through host adapters or direct integration. Optional transports may sit below the core, but they cannot replace authoritative cursor replay or durable delivery state.
 
 [ADR-0001](decisions/0001-protocol-layers-and-acknowledgment-semantics.md) defines these layers and the distinct meanings of receipts, claims, leases, delivery settlement, and external task completion.
 
 [ADR-0002](decisions/0002-canonical-operation-contract-registry.md) defines the canonical cross-surface operation contract, deterministic artifacts, capability discovery, and protocol negotiation.
 
+[ADR-0003](decisions/0003-host-adapters-and-consumer-instance-keys.md) separates harnesses, hosts, adapters, and access surfaces and defines the consumer instance-key contract.
+
 ## Decisions
 
 ### PostgreSQL is the shared source of truth
@@ -179,7 +181,7 @@ Migration 010 uses `nack_retry` as a conservative compatibility mapping for a le
 
 A receipt does not change delivery state. A claim or settlement does not create a receipt. Lease renewal proves only that the current owner retained its claim. External task completion belongs to A2A or the application layer and must be recorded separately when a workflow needs both task state and delivery settlement.
 
-Each delivery transition also appends an audit event. Runtime presence uses a separate leased record keyed by workspace, agent, and instance. Presence can carry a runtime type and declared capabilities without using a PID as ownership proof. Expired rows are pruned during normal presence operations. Each agent is limited to 128 active instances, and each workspace is limited to 4,096.
+Each delivery transition also appends an audit event. Instance presence uses a separate leased record keyed by workspace, principal, and caller-supplied instance key. Presence requires that key and can carry a host or harness type and declared capabilities. Supported installers generate and persist a stable key for each installed client. Direct clients that use presence must provide a stable key for each intended consumer. Processes that share a key also share its presence row. The gateway does not bind the key to an installer registration, and the row does not identify a unique live process or PID. Expired rows are pruned during normal presence operations. Each principal is limited to 128 active instance keys, and each workspace is limited to 4,096.
 
 The system promises at-least-once delivery. It does not promise exactly-once execution. Idempotency keys prevent duplicate insertion, and consumers must make side effects idempotent.
 
@@ -217,14 +219,26 @@ The identity model separates:
 - Workspace.
 - Agent principal.
 - Human-readable name.
-- Runtime type.
-- Client instance.
-- Session or thread.
+- Host adapter and harness type.
+- Consumer instance key.
+- Live process identity, which the released protocol does not represent separately.
+- Session or thread context.
 - Optional role.
 - Authentication subject and credential.
 
 Remote credentials bind the workspace and principal. Each installed client gets a separate owner-only backend file containing only its bound token and backend settings. The shared config does not hold a gateway token. A client cannot claim another source label. Local mode binds identity through its process configuration. `AGENT_BRIDGE_AGENT` remains the compatibility field for MCP and CLI clients.
 
+`AGENT_BRIDGE_INSTANCE` is an optional caller-supplied stable consumer key. Unless
+`AGENT_BRIDGE_CURSOR` sets an explicit path, the instance key selects cursor storage.
+The key also selects delivery lease ownership and instance presence. Supported
+installers generate and persist it; direct clients may manage it themselves. When the
+key and explicit cursor path are both omitted, cursor storage uses the `default` path
+component. Delivery lease ownership falls back to the principal, and presence is
+unavailable. The gateway does not treat the key as registered authority. It is not a
+PID, conversation, or session identifier. A future per-process presence feature must
+add a separate identity instead of changing the meaning of `instance` and invalidating
+existing cursor or lease ownership.
+
 ### The core is provider-neutral
 
 Protocol logic depends on a `BridgeStore` interface, not a provider SDK. The initial stores are:
@@ -234,7 +248,7 @@ Protocol logic depends on a `BridgeStore` interface, not a provider SDK. The ini
 - Supabase legacy REST for v1 compatibility during migration.
 - Agent Bridge HTTP API for normal remote clients.
 
-Runtime and wakeup adapters are independent from storage. A client manifest declares identity injection, supported wake modes, config locations, health checks, and install actions for Codex, Claude Code, Claude Desktop, OpenClaw, or a generic MCP client.
+Host and wakeup adapters are independent from storage. A client manifest declares identity injection, supported wake modes, config locations, health checks, and install actions for Codex, Claude Code, Claude Desktop, OpenClaw, or a generic MCP client. The v1 manifest key named `runtime` identifies an installation target for compatibility. It does not identify a unique running process. The `codex` adapter configures the profile shared by the Codex CLI and the Codex surface in the ChatGPT desktop app. Scripts, CI jobs, daemons, and application services may instead call the CLI or HTTPS API or embed the Node library without pretending to be a harness adapter.
 
 ### v1 compatibility is additive
 
@@ -332,6 +346,11 @@ source, a tag-to-version check, and npm provenance. The npm environment does not
 currently require a human reviewer, so the release process must not claim a manual
 approval gate.
 
+GitHub immutable releases are enabled, and GitHub reports release `v0.3.0` as
+immutable. A tag ruleset also blocks update and deletion of `v*` tags with no bypass
+actor. Future recovery dispatches must run the workflow at the release tag ref so the
+provenance workflow identity and checked-out source commit do not diverge.
+
 ## Acceptance checks
 
 The TypeBox 1.x registry validates closed requests before domain semantics. Response schemas require known fields and accept additive properties. MCP and HTTP 2.1 claim and delivery-control results use object envelopes with nullable `delivery` fields. HTTP 2.0 and the unversioned CLI keep their released direct or null shapes.

package/docs/decisions/0001-protocol-layers-and-acknowledgment-semantics.md

@@ -30,7 +30,7 @@ Its protocol owns:
 The surrounding layers have separate responsibilities:
 
 - A2A and application protocols sit above Agent Bridge. They own task, conversation, artifact, and domain lifecycle semantics.
-- MCP, CLI, and HTTPS are client access surfaces. They expose Agent Bridge operations without defining its stored protocol.
+- MCP, CLI, HTTPS, and the Node library are access surfaces. They expose Agent Bridge operations without defining its stored protocol.
 - Optional transports such as SLIM or NATS may sit below the core as wakeup or transport adapters. They must not replace authoritative cursor replay or durable delivery state.
 - agmsg is a reference for adapters, interoperability, and client experience. Its patterns may inform clients, but it does not define Agent Bridge identity, persistence, or delivery semantics.
 
@@ -60,7 +60,7 @@ Read receipts and delivery settlement remain independent in both directions. Rec
 
 Agent Bridge can carry A2A messages without implementing the A2A task state machine. A client that needs both task completion and delivery settlement must record both operations explicitly.
 
-MCP remains replaceable by another access adapter. A transport integration must preserve cursors, idempotency, identity binding, and delivery leases.
+MCP remains replaceable by another access surface. A host or transport integration must preserve cursors, idempotency, identity binding, and delivery leases.
 
 Push notifications and future brokers can reduce wakeup latency. Pull and replay remain the recovery path.
 

package/docs/decisions/0003-host-adapters-and-consumer-instance-keys.md

@@ -0,0 +1,88 @@
+# ADR-0003: Separate host adapters from consumer instance keys
+
+## Status
+
+Accepted
+
+## Date
+
+2026-07-15
+
+## Context
+
+Agent products often combine an agent harness with a host application. Codex runs in
+the Codex CLI and in the Codex surface of the ChatGPT desktop app. Claude Code and
+Claude Desktop are separate hosts. OpenClaw, Hermes, Pi, scripts, CI jobs, and services
+have different host and access options.
+
+The released protocol also uses `AGENT_BRIDGE_INSTANCE` in several places. Supported
+installers generate one value for each installed client, but the gateway accepts the
+value from the caller. Calling it a registered process identity would promise an
+authority check that the server does not perform.
+
+## Decision
+
+The integration model separates these concepts:
+
+- A harness runs an agent loop.
+- A host is a CLI, desktop application, daemon, job, or service that contains a
+  harness or calls Agent Bridge.
+- A host adapter configures a host to use Agent Bridge.
+- MCP over stdio, the CLI, the HTTPS API, and the Node library are access surfaces.
+- Scripts, CI jobs, and services may use an access surface directly without becoming
+  agent harnesses.
+
+The `codex` adapter configures the profile shared by the Codex CLI and the Codex
+surface in the ChatGPT desktop app. Claude Code and Claude Desktop have separate
+adapters. Their supported installation flows create separate host registrations and
+instance keys. OpenClaw and generic MCP manifests are operator-managed. Hermes, Pi,
+and other harnesses have no dedicated compatibility or conformance claim until an
+adapter is tested.
+
+`AGENT_BRIDGE_INSTANCE` is an optional caller-supplied stable consumer key. Supported
+installers generate and persist one for each installed client. Direct clients should
+generate and persist a value when they need separate consumer state or presence. The
+gateway does not bind the value to an installer registration.
+
+Unless `AGENT_BRIDGE_CURSOR` sets an explicit path, a present instance key selects
+cursor storage. The key also selects delivery lease ownership and presence. Processes
+that share one key also share those resources. When the key and explicit cursor path
+are both absent, cursor storage uses the `default` path component. Delivery ownership
+falls back to the principal, and presence is unavailable. The key is not a PID,
+live-process identity, session, or conversation. Per-process presence requires a
+separate additive identity.
+
+The v1 client manifest key named `runtime` remains a compatibility field for the host
+installation target. A future manifest version may rename it without changing the
+meaning of `AGENT_BRIDGE_INSTANCE`.
+
+## Consequences
+
+The architecture diagram and compatibility matrix can list desktop apps, CLIs,
+daemons, and direct callers without presenting them as one category.
+
+Installer-generated keys work without a new protocol field. Direct client authors who
+use a key are responsible for stable storage and uniqueness within a principal. Reusing
+a key intentionally creates one shared delivery consumer and presence identity.
+
+The current gateway does not prevent two callers from choosing the same key. Clients
+must not treat an instance value as proof of process identity or server registration.
+
+## Alternatives considered
+
+### Treat the adapter name as the harness identity
+
+Rejected because one adapter may configure more than one host surface. The `codex`
+adapter is the current example.
+
+### Treat every live process as an instance
+
+Rejected because the released instance key already selects cursor paths, lease
+ownership, and presence. Changing it on every process start would alter consumer
+ownership and strand existing state.
+
+### Bind instance keys to server-side registrations now
+
+Deferred. Binding could prevent accidental key collisions, but it needs a migration,
+credential rules, and direct-client enrollment semantics. The current gateway accepts
+the caller-supplied key and must be documented honestly.

package/docs/ecosystem.md

@@ -9,16 +9,48 @@ full agent stack.
 
 | Layer | Examples | Relationship to Agent Bridge |
 | --- | --- | --- |
-| Tool and context access | MCP | Agent Bridge exposes MCP tools. MCP does not define Agent Bridge's stored message or delivery protocol. |
+| Tool and context access | MCP, CLI, HTTPS, Node library | These surfaces expose Agent Bridge operations. They do not define its stored message or delivery protocol. |
 | Agent task semantics | A2A and application protocols | These systems own tasks, artifacts, status, and domain completion. Agent Bridge can carry their identifiers and payloads. |
 | Durable mailbox | Agent Bridge | Agent Bridge owns cursored history, receipts, work claims, leases, retry state, and offline replay. |
 | Live transport and brokers | SLIM, NATS, RabbitMQ, Kafka | A future adapter may use one of these systems for transport or wakeups. Cursored pull remains the recovery path. |
-| Agent execution | LangGraph, AutoGen, agent-loop, hosted agent platforms | These systems decide what runs and how workflows advance. Agent Bridge carries messages between them. |
+| Agent execution | Codex, Claude Code, OpenClaw, Hermes, Pi, LangGraph, AutoGen, agent-loop | These harnesses decide what runs and how workflows advance. Agent Bridge can carry messages when their host implements a supported access surface. |
 | Local operator experience | agmsg and similar tools | These tools may provide terminal placement, agent spawning, roles, and local coordination. They can use Agent Bridge when they need its durable cross-machine state. |
 
 [ADR-0001](decisions/0001-protocol-layers-and-acknowledgment-semantics.md)
 defines the protocol boundary and the separate meanings of read receipts, delivery
 settlement, and external task completion.
+[ADR-0003](decisions/0003-host-adapters-and-consumer-instance-keys.md) defines
+the host layers and consumer instance-key contract.
+
+## Harnesses, hosts, adapters, and access
+
+Agent Bridge keeps four integration concepts separate:
+
+- A harness runs an agent loop, such as Codex, Claude Code, OpenClaw, Hermes, or Pi.
+- A host is the CLI, desktop application, daemon, CI job, or service that contains the
+  harness or invokes Agent Bridge.
+- A host adapter configures that host to use Agent Bridge.
+- An access surface is MCP over stdio, the CLI, the HTTPS API, or the Node library.
+
+This distinction matters when one profile serves more than one host surface. The
+`codex` adapter configures the profile shared by the Codex CLI and the Codex surface
+in the ChatGPT desktop app. It does not create two independent Agent Bridge
+registrations. Claude Code and Claude Desktop have separate adapters and registrations.
+
+| Adapter or integration | Host coverage | Access | Support level |
+| --- | --- | --- | --- |
+| `codex` | Codex CLI and Codex in the ChatGPT desktop app | MCP stdio | Automated install |
+| `claude-code` | Claude Code CLI | MCP stdio | Automated install |
+| `claude-desktop` | Claude Desktop | MCP stdio | Automated install |
+| `openclaw` | OpenClaw daemon or host | MCP stdio | Manifest included; operator-managed |
+| `generic-mcp` | Any compatible MCP host | MCP stdio | Manifest included; operator-managed |
+| Direct integration | Scripts, CI, daemons, and services | CLI, HTTPS, or Node library | No host adapter required |
+| Generic harness integration | Hermes, Pi, and other harnesses | Any access surface their host supports | No dedicated adapter or conformance claim yet |
+
+Scripts are orthogonal to harnesses. A script may start a harness, invoke the CLI,
+call the HTTPS API, or embed the Node library. It is not a separate agent category.
+The MCP server currently uses stdio. The gateway exposes the Agent Bridge HTTPS
+protocol, not MCP over HTTP.
 
 ## Relationship to agmsg
 
@@ -49,6 +81,6 @@ vendors without forcing every participant into the same runtime or deployment st
 ## Interoperability direction
 
 The next interoperability work is tracked in [ROADMAP.md](../ROADMAP.md). Planned
-surfaces include an agmsg adapter, a thin A2A envelope mapping, runtime conformance
+surfaces include an agmsg adapter, a thin A2A envelope mapping, host-adapter conformance
 fixtures, and client libraries. Each integration must retain caller-bound identity,
 idempotent publication, cursored replay, and at-least-once delivery semantics.

package/llms.txt

@@ -16,6 +16,11 @@ If an MCP client cannot attach, run `agent-bridge doctor --json` and see
 `docs/troubleshooting.md`. Normal client installation resolves the MCP launch command;
 do not copy another runtime's identity or backend file.
 
+The `codex` host adapter configures the profile shared by the Codex CLI and the Codex
+surface in the ChatGPT desktop app. Claude Code and Claude Desktop use separate
+adapters. OpenClaw and generic MCP manifests are operator-managed. Scripts and
+services can call the CLI or HTTPS API or embed the Node library without a host adapter.
+
 ## Modes
 
 - local: SQLite WAL, no account or daemon
@@ -24,6 +29,7 @@ do not copy another runtime's identity or backend file.
 
 ## Commands
 
+- `agent-bridge --version` or `agent-bridge -V`: print the installed package version without loading backend configuration.
 - `agent-bridge capabilities`: print the canonical v2 operation and protocol capability document.
 
 - agent-bridge init --provider local
@@ -84,7 +90,9 @@ Gateway MCP clients sync automatically and expose manual sync for bounded outbox
 ## Protocol boundary
 
 A2A and application task semantics sit above Agent Bridge.
-MCP, CLI, and HTTPS are client access surfaces.
+MCP, CLI, HTTPS, and the Node library are access surfaces.
+Harnesses, host applications, host adapters, and access surfaces are separate layers.
+The MCP server uses stdio. The gateway HTTPS API is not MCP over HTTP.
 Optional transports such as SLIM or NATS may sit below the core.
 agmsg is a reference for adapters, interoperability, and client experience.
 HTTP protocol 2.1 is current. Upgraded gateways continue to serve released headerless and explicit 2.0 clients. New 2.1 clients probe before mutation and proceed only after complete, consistent negotiation selects and advertises 2.1. They reject headerless or selected 2.0 gateways instead of downgrading. Upgrade the gateway before 2.1 clients. Capabilities distinguish current, selected, and supported versions.
@@ -100,7 +108,7 @@ Lease extension does not report progress or external task completion.
 
 ## Identity rule
 
-The active runtime supplies AGENT_BRIDGE_AGENT and AGENT_BRIDGE_INSTANCE. Do not hardcode another client name and do not store agent identity in the shared backend config. Gateway installations use a separate principal-bound token and owner-only backend file for each client.
+The active client supplies AGENT_BRIDGE_AGENT and may supply a stable AGENT_BRIDGE_INSTANCE consumer key. Do not hardcode another client name and do not store agent identity in the shared backend config. Gateway installations use a separate principal-bound token and owner-only backend file for each client. Supported installers generate and persist the instance key; direct clients may do so when they need separate consumer state or presence. The gateway does not bind it to an installer registration. It is not a PID, unique live process, session, or thread. 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.
 
 Owner commands are offline and use only AGENT_BRIDGE_OPERATOR_DATABASE_URL. They are
 not MCP, HTTP, or public gateway operations. Provision and rotation write private
@@ -126,6 +134,7 @@ Local CLI calls may override workspace for one invocation. The legacy Supabase s
 - docs/troubleshooting.md: MCP startup and client recovery
 - docs/decisions/0001-protocol-layers-and-acknowledgment-semantics.md: protocol layers and acknowledgment semantics
 - docs/decisions/0002-canonical-operation-contract-registry.md: generated contracts and version negotiation
+- docs/decisions/0003-host-adapters-and-consumer-instance-keys.md: host layers and instance-key semantics
 - docs/architecture-v2.md: protocol, storage, identity, delivery, and acceptance decisions
-- clients/*.json: runtime adapter manifests
+- clients/*.json: v1 host-adapter manifests; `runtime` is the compatibility key for the installation target
 - SKILL.md: concise agent operating instructions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creatornader/agent-bridge",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Durable, pull-first mailbox and work-delivery control plane for AI agents across runtimes, sessions, and machines.",
   "type": "module",
   "license": "Apache-2.0",