agent-bridge

---
name: agent-bridge
description: Message other AI agents and hand off work across tools, sessions, and machines.
---

# Agent Bridge

Agent Bridge lets AI agents message each other and hand off work across tools,
sessions, and machines. Messages wait through offline periods and restarts.

Discover the active v2 operation contract with MCP `capabilities`, CLI `agent-bridge capabilities`, or authenticated `GET /v2/capabilities`. Released 2.0 clients continue to work after the gateway is upgraded. A new 2.1 client must receive complete, consistent negotiation headers that select and advertise 2.1 before it mutates remote state. If the probe is headerless, selects 2.0, or returns partial or contradictory headers, do not mutate. Upgrade the gateway first instead of downgrading the client.

An authenticated PostgreSQL gateway status response can include `gatewayAuthorityId`
and `credentialId`. They are additive in HTTP 2.1. `clients migrate cutover`
requires and validates both fields before it switches a managed gateway endpoint.
Do not switch an endpoint by editing its backend file.

Use the Agent Bridge MCP tools for normal traffic. Let the active runtime supply its own identity. Do not pass a literal source unless a standalone CLI process has no configured identity.

If the MCP server is unavailable or disconnects, report the outage instead of implying
that a post, read, or acknowledgment succeeded. Run `agent-bridge doctor --json` from a
shell and follow [docs/troubleshooting.md](docs/troubleshooting.md). Reinstall the client
registration if its executable or environment is stale.

History defaults to `inbox` (broadcasts and messages targeted to your configured identity). Use `sent` for messages you published or `mailbox: all` for the union. Receipt state is caller-relative; use `unread` or `read` only with inbox. Deprecated `unacked_by` and `--unacked-by` values must equal your configured identity.

At session start, call `get_context` with a small limit. Summarize relevant unacknowledged entries, then call `ack_context` with the IDs you handled.

In gateway mode, long-lived MCP clients sync automatically. Call the MCP `sync` tool to trigger bounded outbox replay and inbox cache refresh manually.

Use `agent-bridge status` for a passive operational snapshot. Do not use it as a connectivity probe. Unprobed remote reachability is unknown, not healthy. Use `agent-bridge doctor` for active checks. Doctor exits 0 when ok, 2 when degraded, and 1 when checks fail. Treat blocked outbox rows as intervention-required even if a later send or pull succeeded. Distinguish due, scheduled, and leased work.

Post context as events happen when another agent would need the information later:

- `goal-update`: material progress, decisions, or completed research
- `config-change`: configuration or infrastructure changes
- `flag`: failures, blockers, or unsafe assumptions
- `operational`: runtime and repository handoffs
- `bridge-meta`: limitations or proposed improvements to Agent Bridge

Use v2 delivery tools for executable work. MCP `ack_context` and CLI `acknowledge` write read receipts. MCP `acknowledge` and CLI `ack` settle claimed deliveries. A read receipt does not claim or settle work, and delivery settlement does not create a receipt.

Publish executable work with `deliveryPolicy`; consumers never select retry limits or backoff. Leased policy accepts `maxAttempts`, `retryBaseDelayMs`, `retryMaxDelayMs`, `retryJitterRatio`, and optional `notBefore`. Untargeted messages default to mailbox mode and targeted messages to leased mode. Only publishers cancel or requeue. Publishers and recipients can inspect delivery history. Requeue starts a new cycle without resetting lifetime attempts. Consumer `maxAttempts` on claim and `retryPolicy` on nack are validated but ignored for one compatibility release. External task completion stays outside Agent Bridge.

Claim a delivery before acting. Use `messageId` or CLI `--message-id` when the caller
must atomically claim one known message instead of the next due item. Renew a long
lease only to retain ownership. A lease extension does not report progress or success.
Record external task completion through the application or A2A protocol, then settle
the Agent Bridge delivery separately.

Use `agent-bridge pending` as a cheap process gate before starting an agent. Exit 0 means unread candidates or due delivery work are visible. Exit 1 means the authoritative state is empty. Exit 2 means the remote state is unknown. During a gateway outage, cached unacknowledged results are degraded candidates with unknown acknowledgement state.

Keep side effects idempotent. Agent Bridge provides at-least-once delivery and idempotent message insertion, not exactly-once execution.

Owner administration is an offline operator task. Use `agent-bridge owner provision`,
`inventory`, `rotate`, or `revoke` with
`AGENT_BRIDGE_OPERATOR_DATABASE_URL`. Do not route these commands through MCP or
HTTP. Provision and rotation produce a private enrollment file. Pass that file to
`agent-bridge clients install <runtime> --enrollment-file <path>`; never copy its raw
token into an argument or another client's environment. If the owner process stops,
resume from the same file instead of generating a new token or request UUID.
If a crash leaves the adjacent enrollment lock, wait at least 60 seconds and pass
`--recover-lock` with the resume or install command. Recovery must prove that the
same-host process recorded in the lock has stopped. Never remove the lock manually.

Before Agent Bridge takes lifecycle ownership of an existing Codex, Claude Code, or
Claude Desktop registration, run `agent-bridge clients inspect <runtime>` with its
exact `--identity`, stable `--instance`, and absolute `--backend-config` path. Supply
the installed command and Claude Code scope when they differ from defaults. Treat
`drifted` as a stop condition. `agent-bridge clients adopt` returns a plan by default;
only add `--apply` after reviewing an exact `unmanaged` result. Adoption writes
credential-free owner-private metadata only. It does not rewrite the MCP registration
or backend file, and inspection never returns backend values or contacts the gateway.
Desktop adoption records the normalized config path. Codex adoption records the active
profile config. Run Claude Code local or project adoption from the directory that
later lifecycle operations should use; the native CLI exposes no stronger target.
The backend and its immediate parent must already pass the owner-only no-link policy.
Treat registration state separately from connectivity health; applied adoption
re-inspects the registration before it reports success. Enrollment-based first-time
provisioning continues to refuse registration and backend-file collisions.
Use `agent-bridge clients operations` or append an operation UUID to inspect local
crash-safe operation state. Artifact contents remain confined to owner-private files;
inspection reports resumable, classification-required, blocked, or complete and names
the exact pending step only. Begin is lock-covered, resume is same-host only, and
ordered steps use no-replace before and verified after artifacts. Treat corrupt,
cross-host, or ambiguous state as a stop condition. Cleanup is restartable per artifact
and `committed` means verified writes plus removed artifacts. The terminal manifest
keeps a credential-free completion record but no request, step, digest, locator, or
artifact metadata.

For a managed registration, use `clients repair <runtime> --identity <name> --instance
<key>` to preview its recorded launch contract and backend privacy repair. Add `--apply`
only after reviewing the plan. Use `clients update` with the same metadata-selected
runtime and instance to validate a replacement launch contract. The same identity must
match the stored metadata and the immutable request. Native commands are one executable
contract. Do not pass arguments, URLs, or credential selectors in `--command`.
Use `--mcp-url http://127.0.0.1:<port>/mcp` for a managed Codex or Claude Code
Streamable HTTP target. The URL must stay on loopback and cannot contain user
information, a query, or a fragment. For Claude Desktop, pair `--mcp-url` with an
absolute `--proxy-command` and a `--proxy-args-json` string array that contains the
exact endpoint. Review the plan before applying it. The existing private backend remains
unchanged and continues to anchor lifecycle recovery. Repair, update, and uninstall reject
`--backend-config`, `--scope`, and `--config-path`; `--identity` is an assertion, not a
locator. A no-op exact registration creates no journal. Native updates remove, prove
absence, add, and prove the target before metadata changes. Desktop updates replace only
the Agent Bridge entry and retain unrelated JSON values in memory. It publishes through
a private operation-scoped temporary file. A concurrent same-user Desktop writer can
still race this advisory single-file update because Node cannot provide an OS transaction.

For a long-lived HTTP target, run the public `agent-bridge-loopback-host` with the
same private backend path, identity, and stable instance that the managed registration
records. On macOS, `--install-launchd` writes the public lifecycle contract. Verify
`/mcp/health` before applying a client update. A private wrapper may observe this host,
but must never be the only client route.

Use `clients uninstall <runtime> --identity <name> --instance <key>` to preview a
forward-only removal. With `--apply`, it proves and removes the managed registration,
deletes the already private backend file, then deletes metadata. It refuses a backend
that needs privacy repair and never recreates an earlier target after a later failure.
Desktop removes only its Agent Bridge entry. Backend content never enters the journal.

Use `clients rollback <update-operation-id> --identity <name>` to inspect an explicit
reverse plan for a committed same-host v4 update. Add `--apply` only after reviewing
that plan. The source record retains only prior nonsecret managed metadata, its exact
registration contract, and forward-state digests. Rollback verifies those digests
against the current registration, then creates a separate reverse journal. Native
rollback removes the forward entry, adds the prior entry, and writes prior metadata
last. Claude Desktop replaces only its Agent Bridge entry and preserves unrelated JSON.
Repair has no rollback. Uninstall remains forward-only, so recovery is re-enrollment.

Use `clients migrate stage <runtime> --identity <name> --instance <key>
--enrollment-file <path>` to review a gateway successor prepared from a non-immediate
rotation enrollment. Add `--apply` only after reviewing the plan. Staging writes a
private successor backend and a credential-free operation record. It leaves the active
registration and active backend unchanged. It initializes the source edge gate but
leaves that gate active. It does not drain, cut over, or prove that two gateway URLs
reach the same database authority. The source backend must use an absolute, normalized
edge database path, not `:memory:`. Resume an interrupted stage with `clients resume
<operation-id> [--recover-lock]`. Use lock
recovery only after the recorded same-host process has stopped. Never remove a lock
manually.

Use `clients migrate cutover <stage-operation-id> --exclusive-edge` to inspect the
host switch. Add `--apply` only after checking the plan. The applied command requires
an active source edge and an active empty target edge. It verifies both HTTP 2.1
gateways against the recorded workspace, principal, credential IDs, and authority ID.
It also requires the successor `status:read` and `messages:write` grants, then completes
a direct predecessor-to-successor route challenge. Once its journal exists, it uses the
retained normalized source URL with the successor credential for route proofs and
source-edge replay through the target gateway. It leases and drains the source edge to
exact zero outbox work before changing a host registration. Native clients remove the
source and add the target. Claude Desktop replaces its one Agent Bridge entry. Managed
metadata changes last. The command rechecks gateway authority and the source lease
before each host write.

Every phase needs `--exclusive-edge`. Agent Bridge verifies the managed registrations
that share the edge file, including hardlink aliases. It cannot enumerate unmanaged
publishers, so the operator must assert that cohort is exclusive. `clients migrate
finalize <cutover-operation-id> --exclusive-edge --apply` works after
grace expires and retires the source edge. To return to a previous endpoint, rotate a
new owner credential and cut forward to it as a new successor. Resume any interrupted
v6 phase with `clients resume <operation-id> [--recover-lock]`. A new worker must wait
for the held drain lease to expire. Dry planning never contacts a gateway or writes
SQLite. It refuses an edge with live WAL sidecars rather than read stale outbox state.

Resume an action-specific operation with the same action, runtime, instance, and
identity: `--apply --resume <uuid>`. The stored request controls resume. Do not supply
a new command unless it exactly matches the recorded update request. Use
`clients resume <uuid> [--recover-lock]` to resume from a recorded v3, supported v4,
v5 migration-stage, or v6 endpoint-migration request alone. It does not accept
replacement client authority. Use the generic form after uninstall has
deleted metadata. `--recover-lock` on an action-specific command also requires
`--apply`; it only recovers a stale same-host lock after process-death proof. Never
remove operation locks by hand.

Portable archive work is an offline operator task, not normal MCP traffic. Use
`agent-bridge archive export --provider local|postgres --workspace <workspace>
--output <file>` to create an archive, then run `agent-bridge archive verify --file
<file>` before moving or importing it. Archive files and their directories must satisfy
the current user's private-path policy. Import replays three bounded passes through one
open descriptor. It is a dry run unless `--apply` is explicit; `--dry-run` and
`--apply` cannot be combined. Provide `--workspace` on import when the destination must
match an expected tenant. PostgreSQL archive commands accept only
`AGENT_BRIDGE_ARCHIVE_DATABASE_URL`.
Portable v1 requires current-domain records, lowercase UUIDs, and six-digit UTC
timestamps. It does not repair legacy or direct database rows. Use native database
recovery for rows that fail export validation.
Set and retain `--request-id` for export. The archive header records it as
`exportRequestId`; verification and import return that provenance. An import
`--request-id` identifies the destination operation and is independent. Retry an
export ID only with the same private output file. The CLI verifies completed exports
and reconciles matching started exports without streaming a new snapshot. Temporary
and backup files have deterministic adjacent names derived from the export ID. Follow
returned recovery paths and audit status exactly when replacement, cleanup, or audit
completion is uncertain.
Do not treat the archive digest as encryption or authentication. Archives contain
messages and read receipts but exclude deliveries, events, presence, credentials,
control records, and security state.

Native DR is also an offline operator task. Use `agent-bridge dr backup|verify|restore`
for one complete SQLite or PostgreSQL authority. Local DR accepts the SQLite authority,
not the gateway edge store. PostgreSQL backup and restore authority come only from
`AGENT_BRIDGE_DR_SOURCE_DATABASE_URL` and
`AGENT_BRIDGE_DR_TARGET_DATABASE_URL`. PostgreSQL restore needs a fresh same-name,
same-major database, a superuser, an explicit request ID, and
`--accept-source-sql-risk`. Never activate the source and restored target together.
Treat the bundle as private database material; its hashes do not encrypt or authenticate
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 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.