@creatornader/agent-bridge 0.2.0 → 0.3.1

package/docs/ecosystem.md

@@ -0,0 +1,86 @@
+# Agent Bridge in the agent ecosystem
+
+Agent Bridge is a durable mailbox and work-delivery control plane for agent runtimes
+that may disconnect, restart, or move between machines. It stores immutable messages,
+read receipts, delivery claims, leases, retries, and replay state. It does not own the
+full agent stack.
+
+## System boundaries
+
+| Layer | Examples | Relationship to Agent Bridge |
+| --- | --- | --- |
+| 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 | 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
+
+Agent Bridge does not claim to replace agmsg's operator interface, process management,
+terminal integration, or community. It treats agmsg as a useful client and adapter
+reference.
+
+The two projects meet at the storage and delivery boundary. An agmsg adapter could map
+send, inbox, history, claim, and settlement operations onto Agent Bridge while keeping
+agmsg's local interaction model. Agent Bridge would then provide durable history,
+principal-bound identity, and cross-machine replay. The adapter must preserve Agent
+Bridge receipt and lease semantics instead of creating a second state model.
+
+## What Agent Bridge does not do
+
+Agent Bridge is not:
+
+- A workflow engine or scheduler.
+- A memory or retrieval system.
+- A terminal multiplexer or agent process manager.
+- A replacement for A2A task semantics.
+- An encrypted global network.
+- A general-purpose event streaming platform.
+
+These boundaries keep the protocol small enough to support clients from different
+vendors without forcing every participant into the same runtime or deployment stack.
+
+## Interoperability direction
+
+The next interoperability work is tracked in [ROADMAP.md](../ROADMAP.md). Planned
+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/docs/postmortems/2026-07-08-wrapper-source-drift.md

@@ -0,0 +1,82 @@
+# 2026-07-08 Agent Bridge Wrapper Source Drift
+
+## Status
+
+Resolved for basic Codex, Claude Code, and Claude Desktop availability.
+
+Codex, Claude Code, and Claude Desktop now launch the source repo MCP server
+directly from its built `dist/index.js` entrypoint with a pinned Node binary.
+The direct server reads credentials from `~/.agent-bridge/config`, so client
+configs no longer need to duplicate the Supabase URL or anon key.
+
+The broken Codex, Claude Code, and Claude Desktop signed-wrapper launchd jobs
+were removed after their labels stayed loaded while `/mcp/health` refused
+connections. The wrapper code still exists as an optional signed attribution
+layer.
+
+## Impact
+
+Codex, Claude Code, and Claude Desktop could not use Agent Bridge through MCP
+while their client configs pointed at signed HTTP wrapper ports:
+
+- Codex: `http://127.0.0.1:8794/mcp`
+- Claude Code: `http://127.0.0.1:8793/mcp`
+- Claude Desktop: `http://127.0.0.1:8791/mcp`
+
+The source repo CLI and Supabase connection stayed healthy. The outage was in
+the local wrapper path and client wiring, not in the shared context database.
+
+## Root Cause
+
+The live client configs made the wrapper the only MCP path. That turned an
+optional signing layer into the availability boundary for Agent Bridge.
+
+The wrapper launchd jobs also treated process supervision as enough. A label
+could be loaded while the HTTP health route was unavailable. Nothing moved the
+clients back to the source MCP server when `/mcp/health` failed.
+
+The source MCP server made the fallback harder than it should have been because
+it required `AGENT_BRIDGE_URL` and `AGENT_BRIDGE_KEY` in process env. The CLI
+already read `~/.agent-bridge/config`, so the two source-repo entrypoints had
+drifted.
+
+During recovery, the wrapper installer also selected `node` from ambient
+`PATH`. That allowed restarts to drift to a local Node shim instead of the
+Homebrew Node binary that had previously run the service.
+
+## Fixes
+
+- `src/server.ts` now reads `~/.agent-bridge/config` when env credentials are
+  absent. Env values still take precedence.
+- `test/server_factory.test.ts` covers config-file fallback, env precedence,
+  quoted config values, explicit config paths, and missing credentials.
+- Local Codex, Claude Code, and Claude Desktop configs now launch the source
+  MCP server directly with `/opt/homebrew/bin/node` and only set
+  `AGENT_BRIDGE_AGENT`.
+- The dead Codex, Claude Code, and Claude Desktop wrapper launchd jobs were
+  uninstalled.
+- The internal wrapper installer now prefers `/opt/homebrew/bin/node` by default
+  while still honoring `NODE_BIN`.
+
+## Wrapper Policy
+
+Keep the signed wrapper for attribution receipts and local-substrate metadata.
+Do not make it the only Agent Bridge path for Codex, Claude Code, or Claude
+Desktop.
+
+Only reinstall those wrapper jobs as active client targets after the wrapper has
+health-based supervision. A loaded launchd label is not proof that Agent Bridge
+MCP is available. The proof is a successful `/mcp/health` probe and a real MCP
+tool call.
+
+## Verification
+
+- `npm test`: 24 tests passed.
+- `npm run build`: passed.
+- Direct stdio MCP smoke: listed `post_context`, `get_context`, and
+  `ack_context`, then read live context.
+- CLI status: returned `{"status":"ok","message":"Agent Bridge is connected to Supabase"}`.
+- Claude Desktop launch proof: fresh Desktop log showed `initialize` and
+  `tools/list` succeeding against the direct source MCP entrypoint.
+- Wrapper cleanup: Codex, Claude Code, and Claude Desktop wrapper labels are
+  absent, and their launchd plist files are absent.

package/docs/troubleshooting.md

@@ -0,0 +1,89 @@
+# Troubleshooting Agent Bridge
+
+Start with the command line even when the failure appears inside an MCP client:
+
+```bash
+agent-bridge doctor --json
+```
+
+`doctor` checks the configured backend and reports named failures. It exits 0 when the
+client is ready, 2 when it is degraded, and 1 when a required check fails. `status` is
+passive and does not test remote reachability.
+
+## MCP server disconnected or could not attach
+
+An MCP client must be able to start the server in its own process environment. Desktop
+applications do not always inherit the `PATH` from an interactive shell, so the normal
+Claude Desktop installer records an absolute Node executable and an absolute server
+entry point.
+
+1. Reinstall the Claude Desktop registration:
+
+   ```bash
+   agent-bridge clients install claude-desktop --identity claude-desktop
+   ```
+
+2. Restart Claude Desktop completely. Closing only its window may leave the old process
+   running.
+
+3. Run `agent-bridge doctor --json` again from a shell.
+
+Use `--command` only when an operator intentionally maintains a separate executable.
+Pass an absolute path:
+
+```bash
+agent-bridge clients install claude-desktop \
+  --identity claude-desktop \
+  --command "$(command -v agent-bridge-mcp)"
+```
+
+Claude Desktop stores its Agent Bridge registration under `mcpServers.agent-bridge` in:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+
+The registered environment must contain distinct `AGENT_BRIDGE_AGENT`,
+`AGENT_BRIDGE_INSTANCE`, and `AGENT_BRIDGE_CONFIG` values for that client. Do not copy
+another client's identity or backend file into the entry.
+
+## The executable is missing
+
+Install the published package globally, then repeat the normal client installation:
+
+```bash
+npm install --global @creatornader/agent-bridge
+agent-bridge clients install claude-desktop --identity claude-desktop
+```
+
+The normal Claude Desktop registration does not depend on the application's inherited
+`PATH`. If an explicit `--command` override is necessary, locate that executable and
+pass its absolute path.
+
+## Identity mismatch
+
+The active runtime owns its identity. Shared backend config must not contain
+`AGENT_BRIDGE_AGENT`, and one client must not claim another client's source label.
+
+Check the client registration and its private backend file. Reinstall that client with
+its intended principal if the values differ. Do not work around the error by adding a
+literal `--source` for normal MCP traffic.
+
+## Gateway failures
+
+Use the doctor output to distinguish local edge health from remote reachability.
+
+- `unknown` means no active probe established remote state.
+- `degraded` can mean cached inbox data or queued outbox messages remain usable while
+  the gateway is unavailable.
+- `failed` means a required local or remote check did not pass.
+
+Queued sends retain their idempotency keys. Long-lived MCP clients retry them, and
+`agent-bridge sync` triggers the same bounded replay manually. Claims, lease changes,
+delivery settlement, presence, and read-receipt writes still require the gateway.
+
+## Report a defect
+
+Include the client name, operating system, package version, sanitized `doctor --json`
+output, and whether the executable path is absolute. Remove tokens, database URLs,
+message content, and private backend contents before posting an issue. Report possible
+security defects through the private process in [SECURITY.md](../SECURITY.md).

package/llms.txt

@@ -3,7 +3,23 @@
 Repository: https://github.com/creatornader/agent-bridge
 Package: @creatornader/agent-bridge
 
-Agent Bridge carries durable context and executable work between AI agents in different clients, processes, sessions, and machines.
+Agent Bridge is a durable, pull-first mailbox and work-delivery control plane for AI agents in different clients, processes, sessions, and machines.
+History uses mailbox `inbox` (default), `sent`, or `all`. Receipt state is `any` (default), `unread`, or `read`; it is caller-relative and inbox-only. CLI: `inbox`, `sent`, and `history --mailbox/--receipt-state`. Deprecated unacked-principal arguments must equal the configured identity.
+
+## Install
+
+- `npm install --global @creatornader/agent-bridge`
+- `agent-bridge init --provider local`
+- `agent-bridge demo`
+
+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
 
@@ -13,27 +29,112 @@ Agent Bridge carries durable context and executable work between AI agents in di
 
 ## 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
 - agent-bridge demo
-- agent-bridge doctor
+- `agent-bridge status`: passive JSON snapshot; never probes or synchronizes. Unprobed remote reachability returns unknown with `connected: false`.
+- `agent-bridge doctor`: active named checks; exits 0 ok, 2 degraded, 1 failed. Blocked outbox rows cannot be healthy.
 - agent-bridge pending
 - agent-bridge send, inbox, history, acknowledge
-- agent-bridge claim, extend, ack, nack
+- agent-bridge claim, extend, ack, nack, deliveries, delivery-events, cancel, requeue
 - agent-bridge sync, watch, join, presence
 - agent-bridge clients install <runtime> --identity <principal>
+- agent-bridge owner provision|inventory|rotate|revoke
+- agent-bridge clients install <runtime> --enrollment-file <private path>
+- agent-bridge archive export|verify|import
+- agent-bridge dr backup|verify|restore
+
+Archive export moves one workspace's immutable messages and read receipts between
+canonical local SQLite and PostgreSQL stores. Import defaults to a rollback-backed dry
+run and requires `--apply` to commit. PostgreSQL archive authority comes only from
+`AGENT_BRIDGE_ARCHIVE_DATABASE_URL`. The digest detects changed bytes; it is neither
+encryption nor authentication. Archives exclude delivery, event, presence, credential,
+control, and security state. Import uses one private file descriptor for format,
+message, and receipt passes with a 4 MiB batch budget. Export completes its audit only
+after durable publication. `--dry-run` and `--apply` are exclusive. Library import:
+`@creatornader/agent-bridge/archive`.
+Portable v1 requires current-domain records, lowercase UUIDs, and six-digit UTC
+timestamps. It does not trim, deduplicate, default, or rewrite message content.
+Legacy or direct rows that fail validation require native database recovery.
+Export accepts a request ID, stores it as header `exportRequestId`, and returns it.
+Verify and import return the same provenance; an import request ID is independent.
+Same-ID export retries verify completed files or reconcile matching started files
+without streaming again. Deterministic adjacent recovery files are derived from the
+export ID. Force replacement keeps a private backup until the new file is durable and
+reports recovery paths plus backup, durability, and audit uncertainty.
+
+Native DR preserves a complete local SQLite authority or shared PostgreSQL authority;
+it does not translate between providers. Local DR rejects gateway edge stores.
+PostgreSQL source and target URLs come only from AGENT_BRIDGE_DR_SOURCE_DATABASE_URL
+and AGENT_BRIDGE_DR_TARGET_DATABASE_URL. Restore requires a dedicated fresh database
+with the same name and PostgreSQL major, superuser authority, an explicit request ID,
+and --accept-source-sql-risk. The backup includes role membership and default ACL state,
+excludes transient request, rate-limit, instance, and archive-authorization rows, and
+normalizes claimed deliveries on restore. Never run source and restored target at the
+same time. The package API is @creatornader/agent-bridge/dr. Bundle hashes detect
+changed bytes but do not encrypt or authenticate the source.
 
 ## MCP tools
 
+- `capabilities`: return operations, required scopes, provider-specific enforcement, and supported protocol versions. Gateway access needs an active credential but no named scope for this operation.
+- Production gateway capabilities report `requestAuthority: true` and `rowIsolation: true` only after the migration and live catalog, role, policy, privilege, and function checks pass. PostgreSQL forces RLS on messages, receipts, deliveries, delivery events, and presence. Lease transitions and target-to-delivery membership remain service-enforced.
+
 Compatibility: post_context, get_context, ack_context.
-Reliable messaging: send, history, claim, extend, acknowledge, negative_acknowledge, heartbeat, presence.
+Reliable messaging: send, history, claim, extend, acknowledge, negative_acknowledge, heartbeat, presence, sync.
+Publisher delivery intent: `deliveryPolicy` mode `mailbox|leased` with `maxAttempts`, `retryBaseDelayMs`, `retryMaxDelayMs`, `retryJitterRatio`, and optional `notBefore`. MCP delivery controls: `list_deliveries`, `list_delivery_events`, `cancel_delivery`, `requeue_delivery`. Consumer `maxAttempts` and `retryPolicy` are validated but ignored for one compatibility release.
+
+Gateway MCP clients sync automatically and expose manual sync for bounded outbox replay and inbox cache refresh. Offline unacknowledged results are degraded candidates with unknown acknowledgement state, not proof that messages are unread or that no remote work exists.
+
+## Protocol boundary
+
+A2A and application task semantics sit above Agent Bridge.
+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.
+MCP and HTTP 2.1 use delivery response envelopes. The unversioned CLI and HTTP 2.0 retain direct or null delivery results.
+OpenAPI paths describe 2.1. Embedded 2.0 vendor extensions provide limited compatibility schema metadata, not a second OpenAPI description.
+
+## Acknowledgment rules
+
+MCP ack_context and CLI acknowledge write read receipts.
+MCP acknowledge and CLI ack settle claimed deliveries.
+A receipt does not settle work. Delivery settlement does not create a receipt.
+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
+versioned enrollment files before calling PostgreSQL. The installer consumes the raw
+token from that file without command arguments. Rotation updates the exact existing
+client backend and does not repeat host registration. Enrollment operations hold an
+exclusive per-file lock and use revisioned compare-and-swap transitions. Use explicit
+`--recover-lock` only after a crash; recovery checks lock age, host, owner, and process
+liveness. Rotation requires predecessor credential, principal, instance, gateway,
+workspace, and live MCP registration matches. Consumed-file deletion and lock release
+report retained, missing, durable, and durability-unknown outcomes without claiming that
+an unlinked path was retained.
+
+Project is an optional immutable message label, not a tenant or identity selector. Omitted project reads include labeled and unlabeled messages. Exact project filters are supported by CLI, MCP, HTTP, and stores. Gateway workspace assertions must match the bound credential before network access.
+Local CLI calls may override workspace for one invocation. The legacy Supabase schema is global and always reports workspace `*`; use project labels for legacy filtering.
 
 ## References
 
 - README.md: setup, commands, security, and provider behavior
+- ROADMAP.md: released, implemented, and remaining work
+- SECURITY.md: reporting process and security boundaries
+- docs/ecosystem.md: relationship to adjacent protocols, brokers, and runtimes
+- 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