@creatornader/agent-bridge 0.3.0 → 0.4.0

package/llms.txt

@@ -11,11 +11,20 @@ History uses mailbox `inbox` (default), `sent`, or `all`. Receipt state is `any`
 - `npm install --global @creatornader/agent-bridge`
 - `agent-bridge init --provider local`
 - `agent-bridge demo`
+- Development gateway: create `.secrets/postgres_password` and
+  `.secrets/runtime_password`, then run `docker compose up --build --wait gateway`.
+  Both checked-in port bindings are loopback-only. See `docs/deployment.md` before a
+  non-loopback deployment.
 
 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 +33,8 @@ 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 --help`, `agent-bridge -h`, or a command followed by either help flag: print help without loading backend configuration or dispatching the command.
 - `agent-bridge capabilities`: print the canonical v2 operation and protocol capability document.
 
 - agent-bridge init --provider local
@@ -35,11 +46,49 @@ do not copy another runtime's identity or backend file.
 - 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 clients inspect <runtime> --identity <principal> --instance <stable-key> --backend-config <absolute path>
+- agent-bridge clients adopt <runtime> --identity <principal> --instance <stable-key> --backend-config <absolute path> [--apply]
+- agent-bridge clients repair <runtime> --identity <principal> --instance <stable-key> [--apply] [--resume <uuid>] [--recover-lock]
+- agent-bridge clients update <runtime> --identity <principal> --instance <stable-key> [--command <command>] [--apply] [--resume <uuid>] [--recover-lock]
+- agent-bridge clients uninstall <runtime> --identity <principal> --instance <stable-key> [--apply] [--resume <uuid>] [--recover-lock]
+- agent-bridge clients rollback <update-operation-id> --identity <principal> [--apply] [--recover-lock]
+- agent-bridge clients migrate stage <runtime> --identity <principal> --instance <stable-key> --enrollment-file <private-path> [--apply] [--recover-lock]
+- agent-bridge clients migrate cutover <stage-operation-id> --exclusive-edge [--apply] [--recover-lock]
+- agent-bridge clients migrate finalize <cutover-operation-id> --exclusive-edge [--apply] [--recover-lock]
+- agent-bridge clients resume <operation-id> [--recover-lock]  # resumes recorded v3, supported v4, v5 stage, or v6 migration authority
+- agent-bridge clients operations [<operation-id>]  # read-only resumable/classification-required/blocked/complete summaries
 - 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
 
+Client inspection is local, read-only, secret-free, and reports absent, unmanaged,
+managed, or drifted. Adoption is a plan unless `--apply` is explicit. It writes only
+owner-private credential-free management metadata after the identity, stable instance,
+backend path, scope, and launch contract match exactly; it never rewrites the host
+registration or backend file. Enrollment-based first-time provisioning continues to
+refuse registration and backend-file collisions. Metadata binds Desktop to its
+normalized config path and Codex to its active profile config. Claude Code local and
+project scope bind to the invocation directory because its native CLI exposes no
+stronger registration target.
+The backend and its immediate parent must pass the owner-only no-link policy. Codex
+registration comparison ignores diagnostic fields and JSON property order but requires
+exactly AGENT_BRIDGE_AGENT, AGENT_BRIDGE_INSTANCE, and AGENT_BRIDGE_CONFIG. Claude Code
+connectivity status is not registration state. Desktop inspection uses the installer's
+validated absolute launch resolver, and applied adoption re-inspects its postcondition.
+Only Claude Code accepts `--scope`; only Claude Desktop accepts `--config-path` for
+inspect and adopt. Repair, update, and uninstall derive those locators from strict managed metadata.
+They reject backend, scope, and config-path authority flags. `--identity` binds the
+metadata record and immutable request. Repair restores the recorded launch contract.
+Update records a normalized credential-free launch request, including only fixed Agent
+Bridge environment key names. Native commands are one executable contract and reject
+arguments, URL-like selectors, and credential surfaces. Plan-only calls create no lock
+or operation. Native changes prove remove then add. Desktop replaces only the Agent
+Bridge config entry through a private operation-scoped temporary file. Its same-user
+writer race is advisory because Node cannot provide an OS transaction. Resume requires
+the same action and managed identity. Lock recovery requires
+same-host process-death proof.
+
 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
@@ -69,11 +118,16 @@ excludes transient request, rate-limit, instance, and archive-authorization rows
 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.
+The immutable PostgreSQL gateway authority UUID is preserved by native DR. It identifies
+one logical authority across restore but does not fence a live clone.
 
 ## 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.
+- Authenticated gateway `/v2/status` returns optional `gatewayAuthorityId` and
+  `credentialId` fields when PostgreSQL request authority is active. They are additive
+  in HTTP 2.1 and do not appear in capabilities.
 
 Compatibility: post_context, get_context, ack_context.
 Reliable messaging: send, history, claim, extend, acknowledge, negative_acknowledge, heartbeat, presence, sync.
@@ -84,7 +138,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 +156,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
@@ -114,6 +170,24 @@ workspace, and live MCP registration matches. Consumed-file deletion and lock re
 report retained, missing, durable, and durability-unknown outcomes without claiming that
 an unlinked path was retained.
 
+`clients migrate stage` is a plan-first gateway migration preparation command. An
+applied stage creates an owner-private successor backend and credential-free operation
+record. It leaves the active registration, active backend, and source edge scope
+active after initializing its gate. Staging requires an absolute, normalized source
+edge database path and rejects `:memory:`.
+
+`clients migrate cutover` requires a committed v5 stage and `--exclusive-edge`. Initial
+preflight checks exact HTTP 2.1 status bindings at both gateways, one immutable
+authority ID, the successor's `status:read` and `messages:write` grants, and a direct
+predecessor-to-successor route challenge. Once it creates the journal, it uses a
+retained normalized source URL and the successor credential for every route proof and
+source outbox replay through the target gateway. `finalize` requires a fresh assertion
+after grace expires and retires the source. To return to a former endpoint, rotate a
+new owner credential and run an ordinary forward cutover to that endpoint. Dry runs
+read private edge state without SQLite writes or gateway requests. They refuse live WAL
+sidecars rather than read uncheckpointed outbox state. Resume uses only the retained v6
+request and waits for an unexpired drain lease instead of taking it over.
+
 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.
 
@@ -124,8 +198,10 @@ Local CLI calls may override workspace for one invocation. The legacy Supabase s
 - 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/deployment.md: Compose development stack and production deployment constraints
 - 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