agent-embassy 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.7.0] - 2026-08-16
+
+### Added
+
+- DeepSeek and Grok Build are routable providers. Four providers — Claude Code, Codex, DeepSeek, Grok Build — give twelve ordered directions, each requiring an explicit consent edge. New providers ride ACP, the open Agent Client Protocol: a minimal spawn-owned client (`initialize`, `session/new`, `session/prompt`, `session/cancel`; permission requests always denied; all five stop reasons preserved; subprocess death settles the honest `UNKNOWN`) plus a per-provider launch definition. Grok Build launches from the ACP registry's exact pin; DeepSeek launches from a local harness checkout (`DSH_HOME`, default `~/.dsh`) and its `end_turn` receipts deliberately settle `unconfirmed`/`ACP_OUTCOME_COARSE` because that adapter collapses failure outcomes upstream — the receipt stays honest until the adapter does.
+- A strict generic pairing arm (`{aliases:[a,b]}`) beside the byte-preserved legacy Claude/Codex arm; deliveries UI gains independent from-provider/to-provider selectors; routed messages carry an additive `from-provider` attribute in the broker-owned envelope.
+- A release-owned provider support matrix (`support/provider-support-matrix.json`) records what each release was tested with; a test proves the running broker never imports it.
+- An offline ACP protocol-core conformance suite (framing, correlation, generation isolation, permission/cancel races, process-death phases, no-replay-after-uncertainty, reply bounds).
+
+### Removed
+
+- Online compatibility certification, in full: evidence tiers, boot compatibility probes, adapter certification APIs, version-gated quarantine providers, the Codex write-attestation probe and its capacity ledger, and the two-factor write gate. Runtime version and build strings are unverified metadata and never grant or withhold anything; authority is consent plus exact owned route identity; results are what the correlated operation proved. Net for this release: about 8,500 lines removed while two providers were added.
+- The bounded `claude --version` subprocess: an interop proof showed the version field was never load-bearing; version is now the attested launcher leaf or `unknown`.
+
+### Changed
+
+- Native persisted state is schema v2 with one role-neutral `consentEdges` table. Pre-v1.7 state fails ordinary strict parsing with a clear error and no in-binary migration — single-user installs re-pair once after upgrading (minutes; registration and pairing are two commands per route).
+- The Codex integration resolves and attests the exact managed `current` release (ownership, layout, architecture, endpoint generation) instead of consulting a version allowlist; exact-generation activation replaces certification at endpoint refresh.
+- The dashboard and site describe only observable truth: route staleness, connector health, last safe codes, consent edges, and the tested-with matrix.
+
+## [1.6.1] - 2026-08-16
+
+### Added
+
+- A stable, schema-attested Codex App Server whose write attestation passed may now hold writable routes, under a two-factor gate: durable write-covered attestation evidence AND a current-generation, process-local write-attestation pass. Neither factor alone enables writes — a recorded pass from an earlier daemon generation cannot authorize the current one — and prerelease versions remain fenced regardless of evidence.
+- Write-probe capacity exhaustion now reports the honest `CODEX_WRITE_PROBE_CAPACITY_EXHAUSTED` instead of a thread-setup failure. Only attempts that could have spent tokens occupy the fixed per-process bound; the two provably zero-spend declines (model pin unavailable, rate limit constrained) release their slot into one retryable decline slot so a transient constraint does not burn permanent capacity.
+
+### Changed
+
+- A monitor-only Codex provider now refuses route selection up front (`CODEX_PROVIDER_UNAVAILABLE`) instead of accepting a route whose every dispatch would fail; no transport is spawned for observation-only providers.
+
 ## [1.6.0] - 2026-08-16
 
 ### Fixed

package/README.md

@@ -12,7 +12,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node ≥ 20](https://img.shields.io/badge/node-%E2%89%A520-43853d)](package.json)
 
-Your [Claude Code](https://code.claude.com) sessions and [Codex](https://chatgpt.com/codex) desktop tasks can't talk to each other. When one needs the other's perspective, you carry context between windows yourself. Embassy is a small local broker that lets them find each other by name and exchange messages in both directions — no plugins, no API keys, no cloud relay.
+Your [Claude Code](https://code.claude.com) sessions, [Codex](https://chatgpt.com/codex) desktop tasks, local DeepSeek Harness, and Grok Build agent do not share one routing surface. Embassy is a small local broker that gives all four providers named routes and explicit consent edges — no plugins, no API keys handled by Embassy, and no cloud relay.
 
 ```bash
 npm install -g agent-embassy
@@ -25,7 +25,7 @@ Embassy is built for one person, one macOS account, and agents you already trust
 
 ## Quickstart
 
-**Requirements:** macOS, Node.js 20+, Claude Code on the supported 2.x major with peer protocol 1, and Codex desktop configured to use its managed standalone App Server. Embassy was last live-tested with Claude Code 2.1.227 and Codex App Server 0.147.0; those patch versions are evidence, not startup pins:
+**Requirements:** macOS and Node.js 20+. Claude routes require peer protocol 1; Codex routes require Desktop configured to use its managed standalone App Server. DeepSeek is optional and launches from `DSH_HOME` (default `~/.dsh`) through the checkout's `demo:acp` script; Grok Build is optional and launches the release-pinned ACP package. The release-owned [support matrix](support/provider-support-matrix.json) records the exact artifacts and capabilities tested for all four providers; it is release evidence, never a runtime allowlist:
 
 ```bash
 ~/.codex/packages/standalone/current/codex app-server daemon start
@@ -36,7 +36,7 @@ The first command starts the managed daemon if it is not already running (`resta
 
 Desktop attaches to the managed standalone App Server when it launches. If the daemon restarts while Desktop is already open, waiting alone does not reconnect that app process: fully quit Desktop, rerun `/usr/bin/open --env CODEX_APP_SERVER_USE_LOCAL_DAEMON=1 -a ChatGPT`, and reopen the exact task.
 
-Provider compatibility needs no separate operator step. `embassy serve` attests the resolved installations and applies one evidence ladder to both providers. A certified same-major build is writable; a same-major build outside this release's tested inventory is shown as `schema_attested` when every bounded live-schema probe passes and is writable only when those probes cover its write path. Claude's probes cover its native write path. Ordinary Codex compatibility and registration reads remain read-only: they may include `initialize`, `thread/loaded/list`, and registration-time `thread/resume`, but do not invoke `turn/start`. The optional Codex write-attestation probe is the sole exception. It may create at most one disposable broker-owned thread per attempt, under a bounded write fence with zero user-thread contact; every created probe thread is archived and confirmed absent from the loaded set. The probe resolves the pinned model's lowest advertised effort. Whenever that model/effort pin cannot resolve, it declines in a zero-spend fail-safe before creating any thread or model turn. Untested Codex 0.x therefore stays monitor-only pending a certified write schema. Failed probes, a different major, or version evidence that cannot establish a safe major leave only that provider degraded, monitor-only, and write-fenced. Probes never promote across a major or compensate for unknown major evidence; a different-major alert names the observed/tested versions and supported major and says that an Embassy release supporting the observed major is required. In every degraded case, the broker, control/dashboard surfaces, and other provider keep running. Only unsafe OS evidence for Embassy-owned or executed artifacts and Embassy callback, control, or state paths refuses broker startup; unsafe UID or mode evidence on Claude's external sessions registry root quarantines only Claude. A Claude session record whose peer protocol is not 1 is rejected in isolation and counted.
+Runtime delivery is best effort. Version and build strings are unverified metadata and never grant or withhold routing authority. Consent plus exact owned route/session identity authorizes an attempt; the current connector, route state, and correlated operation determine its honest result. Unsupported or changed interfaces therefore fail with provider-local safe codes instead of an online compatibility tier. Embassy still validates the trust boundary: exact owned executable and state paths, endpoint generations, strict consumed protocol fields, Claude peer protocol 1, bounded queues, and no replay after an ambiguous write.
 
 > **Known limitation:** Embassy can reach Codex tasks only while Desktop uses the managed standalone App Server. In that mode, tasks currently cannot connect to Desktop's built-in in-app browser (`@Browser` loads but does not attach). Switching Desktop back to its default private App Server restores the built-in browser immediately — but makes those tasks unreachable by Embassy. No other capability regressions have been identified, though this was not an exhaustive parity test.
 
@@ -70,7 +70,7 @@ embassy register-codex --alias codex-reviewer@this-mac
 
 You should see `"accepted":true`. The `codex-` prefix is required for Claude discovery. To retire the task later, run `embassy unregister-codex --alias codex-reviewer@this-mac` from inside that same task.
 
-Managed App Server generation changes and `embassy serve` restarts both use exact-task reactivation. Each replacement starts monitor-only; only a fresh initialize plus `thread/loaded/list` result that finds the byte-identical task exactly once may re-anchor the alias, and writes stay fenced until that exact generation is activated. A normal broker restart therefore needs no manual registration. An incompatible endpoint or a missing or duplicate exact task leaves the route stale with `REOBSERVATION_REQUIRED`; once that task is observable, rerun `embassy register-codex --alias codex-reviewer@this-mac` from the exact task without unregistering first. Embassy never retargets by alias or replays an ambiguously written body.
+Managed App Server generation changes and `embassy serve` restarts both use exact-task reactivation. A fresh initialize negotiates the connection; `thread/loaded/list` must find the byte-identical task exactly once before Embassy re-anchors the alias on that exact generation. A normal broker restart therefore needs no manual registration. A missing or duplicate exact task, changed generation, or failed negotiation leaves the route stale with a safe code; once that task is observable, rerun `embassy register-codex --alias codex-reviewer@this-mac` from the exact task without unregistering first. Embassy never retargets by alias or replays an ambiguously written body.
 
 ### 3. Select a Claude destination
 
@@ -84,7 +84,7 @@ Run this from the operator terminal, or from inside the Codex task — either wo
 
 You should see `"accepted":true`. Registration and selection together form a pair — this Claude session and this Codex task can now exchange messages through Embassy.
 
-Once you have more than one registered task, name both ends explicitly with `embassy pair --claude <name@host> --codex <codex-alias>`; many pairs can coexist. Unlike `select-claude`, `pair` and `unpair` must run **inside the Codex task**, the same way `register-codex` does. From a plain terminal they fail `CODEX_IDENTITY_REQUIRED`, and from inside a Claude session they fail `CALLER_IDENTITY_CONFLICT`.
+To connect any two routes from different providers, name both ends explicitly with `embassy pair --from <alias> --to <alias>`; many edges can coexist. The command must run under an inherited endpoint identity that belongs to the requested edge. The live dashboard offers the same bounded, confirmed operation to the local operator.
 
 ### 4. Send a message
 
@@ -169,9 +169,9 @@ The broker also publishes mode-0600 static snapshots as `gateway-dashboard.html`
   └───────────────────────────────────────────────────────────┘
 ```
 
-Embassy publishes each registered Codex task into Claude Code's live-session registry as its own `codex-*` peer. Compatible Claude sessions discover them through their native `ListAgents` and contact them with `SendMessage` — no plugin, MCP server, or settings change required.
+Embassy publishes each registered Codex task into Claude Code's live-session registry as its own `codex-*` peer. Claude sessions discover those tasks through `ListAgents`; Codex uses its managed App Server. DeepSeek and Grok Build are boot-registered ACP routes whose owned subprocess and one route-local session start lazily on first dispatch.
 
-A pair is one explicit permission edge between one Claude session and one Codex task — and pairs are many-to-many: one Claude session may hold edges to several Codex tasks, and one Codex task to several Claude sessions (bounded at 128 pairs by default). Every edge is created explicitly, with `pair` or the one-task `select-claude` shorthand; nothing is ever implied. Without an edge, a sender settles terminally as `SENDER_NOT_PAIRED`. `embassy serve --inbound open` is the explicit opt-out that restores any-session inbound.
+A pair is one explicit permission edge between two named routes from different providers, bounded at 128 edges by default. Every edge is created explicitly with generic `pair --from/--to`; `select-claude` remains the one-Codex-task shorthand for a Claude↔Codex edge. Nothing is implied. Without an edge, a sender settles terminally as `SENDER_NOT_PAIRED`. `embassy serve --inbound open` is the explicit opt-out for supported native inbound senders.
 
 Delivery timing is directional. Once routing and pre-write checks pass, every Claude-bound body is written immediately to Claude's native mailbox regardless of its observed busy or idle state. `transport_written` records that mailbox write and is the Claude-bound terminal `delivered` boundary; it does not mean Claude read or consumed the body. Codex-bound ordinary bodies instead queue while the task is busy and start a turn when it goes idle. In the Claude-to-Codex direction only, a body with an exact leading `STEER:` prefix may enter the active turn at the App Server's next tool-call boundary; if that boundary is unavailable, the message returns to the normal queue.
 
@@ -217,7 +217,7 @@ Codex tasks can then be prompted with `$embassy-peer`; Claude Code discovers it
 | `wait-delivery` | either provider | Wait for that tracker to settle, up to the delivery deadline |
 | `untrack` | either provider | Close one active progress watch: `embassy untrack --conversation conv_<token>` |
 | `register-codex` / `unregister-codex` | Codex task | Advertise or retire that exact task; both take `--alias <codex-alias>`, and `embassy register-codex --alias codex-successor@this-mac --succeeds codex-reviewer@this-mac` hands the registration to a different task |
-| `pair` / `unpair` | Codex task | Add or remove one explicit Claude↔Codex edge by naming both ends: `embassy pair --claude advisor@this-mac --codex codex-reviewer@this-mac`. Like `register-codex`, it must run inside the Codex task |
+| `pair` / `unpair` | endpoint participant | Add or remove one cross-provider edge by naming both ends: `embassy pair --from advisor@this-mac --to grok-main@this-mac`; the inherited caller must belong to the edge |
 | `select-claude` / `unselect-claude` | operator or Codex task | One-task shorthand for `pair`/`unpair`, taking `--alias <name@host>` or `--session <uuid>`: resolves the Codex end only when it is unambiguous (inherited or sole registered task), otherwise fails closed |
 | `send-to-claude` | registered Codex task | Send one bounded message to a paired Claude session: `--from <codex-alias> --to <claude-alias>`, body on stdin, optional `--expects-reply` and `--track [--idle-minutes <n>]` |
 | `send-to-codex` | Claude session | Same flags and stdin body, using the inherited native reply identity |
@@ -233,7 +233,7 @@ or by replying with a leading `DONE:`. See [Delivery](docs/DELIVERY.md).
 
 - **Local broker, stable loopback dashboard.** `embassy serve` listens on private Unix-domain sockets and makes no provider API call. The opt-in `embassy dashboard --live` companion is a separate process and the only listener Embassy can create, bound to exact `127.0.0.1` on stable port `41961` by default (or the per-invocation `--port <n>`). It is deliberately unauthenticated local HTTP for a trusted single-user machine; Host, Origin, and sentinel checks constrain browser-origin requests but do not authenticate local processes or OS users.
 - **Same-UID containment, not authentication.** Caller identity is inherited from the local process environment. Route ownership and generation checks reduce mistakes, but are not a defense against code already running as your OS user.
-- **Compatibility follows evidence, not patch pins.** Broker/provider startup attests exact filesystem ownership and paths, then applies the evidence ladder. Certified same-major builds are writable; fully probed same-major builds are `schema_attested` and writable only when the probes cover writes. Ordinary Codex compatibility and registration reads remain read-only: they may include `initialize`, `thread/loaded/list`, and registration-time `thread/resume`, but do not invoke `turn/start`. The optional Codex write-attestation probe is the sole exception. It may create at most one disposable broker-owned thread per attempt, under a bounded write fence with zero user-thread contact; every created probe thread is archived and confirmed absent from the loaded set. The probe resolves the pinned model's lowest advertised effort. Whenever that model/effort pin cannot resolve, it declines in a zero-spend fail-safe before creating any thread or model turn. Untested Codex 0.x therefore remains monitor-only. Failed probes, a different major, or unknown version evidence fence only that provider while the broker and other provider keep running. Probes never promote across a major or unknown version. Unsafe Embassy-owned/executed artifacts and Embassy callback/control/state paths still refuse startup; an unsafe Claude-owned sessions registry root quarantines only Claude.
+- **Compatibility is tested offline; runtime is best effort.** The release-owned support matrix records exact tested artifacts, protocols, capabilities, stop fidelity, limitations, and test dates. Runtime never imports that matrix and never turns a version fact into authority. It validates exact owned boundaries and protocol facts, attempts the current operation, and reports provider-local health, route staleness, and safe codes without replaying uncertainty.
 - **Native permissions stay native.** Embassy sends no Codex approval or sandbox overrides and answers no approval request. `crossSessionInbound` remains Claude's own control; Embassy cannot override it.
 - **Provenance is marked, not authenticated.** Routed bodies carry one broker-owned cross-session marker with the verified sender alias; it distinguishes the transport path for the receiving model but cannot make untrusted text safe or authenticate against code already running as your OS user.
 - **Bodies stored, bounded, and yours.** Message bodies persist in the broker's private mode-0600 state under bounded retention so the ledger can show you the mail itself; queued mail survives a broker restart and re-sends exactly once. Raw provider frames stay memory-only. The static dashboard files remain metadata-only; the live dashboard shows retained bodies.

package/README.zh-CN.md

@@ -12,7 +12,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node ≥ 20](https://img.shields.io/badge/node-%E2%89%A520-43853d)](package.json)
 
-你的 [Claude Code](https://code.claude.com) 会话和 [Codex](https://chatgpt.com/codex) 桌面任务彼此无法对话。当一方需要另一方的视角时，你只能在窗口之间手动搬运上下文。Embassy 是一个小型本地代理，让它们按名称互相发现并双向交换消息——无需插件、无需 API 密钥、无需云端中继。
+你的 [Claude Code](https://code.claude.com) 会话、[Codex](https://chatgpt.com/codex) 桌面任务、本地 DeepSeek Harness 与 Grok Build 代理没有共同路由面。Embassy 是一个小型本地代理，为四种提供方提供具名路由与显式同意边——无需插件，Embassy 不处理 API 密钥，也无需云端中继。
 
 ```bash
 npm install -g agent-embassy
@@ -25,7 +25,7 @@ Embassy 专为单人、单一 macOS 账户以及你已信任以该用户身份
 
 ## 快速开始
 
-**前置要求：** macOS、Node.js 20+、使用已支持 2.x 主版本且对等协议为 1 的 Claude Code，以及配置为使用托管独立 App Server 的 Codex 桌面应用。Embassy 最近完成实机测试的版本是 Claude Code 2.1.227 与 Codex App Server 0.147.0；这些补丁版本是测试证据，而非启动固定值：
+**前置要求：** macOS 与 Node.js 20+。Claude 路由要求对等协议 1；Codex 路由要求 Desktop 使用托管独立 App Server。DeepSeek 是可选提供方，通过 `DSH_HOME`（默认 `~/.dsh`）指向的本地 checkout 中 `demo:acp` 脚本启动；Grok Build 也是可选提供方，通过发布版固定的 ACP 包启动。发布版自有的[支持矩阵](support/provider-support-matrix.json)记录四种提供方已测试的精确构件与能力；它只是发布证据，绝不是运行时允许列表：
 
 ```bash
 ~/.codex/packages/standalone/current/codex app-server daemon start
@@ -36,7 +36,7 @@ Embassy 专为单人、单一 macOS 账户以及你已信任以该用户身份
 
 Desktop 仅在启动时附着到托管独立 App Server。如果 Desktop 已打开时守护进程重启，单纯等待不会让该应用进程重新连接：请完全退出 Desktop，重新运行 `/usr/bin/open --env CODEX_APP_SERVER_USE_LOCAL_DAEMON=1 -a ChatGPT`，再打开该确切任务。
 
-提供方兼容性无需操作员执行额外步骤。`embassy serve` 会验证解析到的安装边界，并对两种提供方应用同一套证据阶梯：同主版本且在已认证清单中的构建可写；同主版本但不在本发布版已测清单中的构建，在全部有界实时结构探测通过后显示为 `schema_attested`，但只有探测覆盖写入路径时才可写。Claude 探测覆盖原生写入路径。常规 Codex 兼容性与注册读取仍保持只读：它们可能包括 `initialize`、`thread/loaded/list` 与注册时的 `thread/resume`，但不会调用 `turn/start`。唯一例外是可选的 Codex 写入认证探测：每次尝试最多可创建一个代理自有的临时线程，在有界写入围栏下运行且绝不接触用户线程；每个已创建的探测线程都会被归档，并确认已从已加载集合中清除。该探测会解析固定模型所公布的最低 effort。只要该模型/effort 固定项无法解析，探测就会以零消耗故障安全方式拒绝，并且不会创建任何线程或模型轮次。未测试的 Codex 0.x 在认证写入结构出现前保持仅监控。探测失败、主版本不同或版本证据无法建立安全主版本时，只有该提供方保持降级、仅监控并禁止写入，代理、控制面/仪表盘和另一提供方继续运行。探测绝不能跨主版本或未知主版本提升权限。主版本不同的告警会列出已观测/已测版本和支持主版本，并说明必须使用支持已观测主版本的 Embassy 发布版。只有 Embassy 自有或执行的构件及其回调、控制与状态路径出现不安全 OS 证据时才会拒绝代理启动；Claude 外部会话注册表根目录的 UID 或模式不安全时，只隔离 Claude。对等协议不是 1 的 Claude 会话记录会单独被拒绝并计数。
+运行时投递采用尽力而为模式。版本与构建字符串只是未经验证的元数据，绝不授予或撤销路由权限。同意加上精确的自有路由/会话身份会授权一次尝试；当前连接器、路由状态与相关操作决定诚实结果。接口不受支持或发生变化时，Embassy 会返回提供方局部的安全代码，而不是在线兼容性等级。Embassy 仍会验证信任边界：精确自有的可执行文件与状态路径、端点代际、被消费协议字段的严格结构、Claude 对等协议 1、有界队列，以及结果不确定的写入绝不重放。
 
 > **已知限制：** 仅当 Desktop 使用托管独立 App Server 时，Embassy 才能访问 Codex 任务。在该模式下，任务目前无法连接 Desktop 内置的应用内浏览器（`@Browser` 可加载但无法附着）。将 Desktop 切换回其默认的私有 App Server 会立即恢复内置浏览器——但会使这些任务对 Embassy 不可达。目前未发现其他能力回退，但这并非穷尽的能力对比测试。
 
@@ -67,7 +67,7 @@ embassy register-codex --alias codex-reviewer@this-mac
 
 你应看到 `"accepted":true`。`codex-` 前缀是 Claude 发现所必需的。之后若要注销该任务，请在同一个任务内运行 `embassy unregister-codex --alias codex-reviewer@this-mac`。
 
-托管 App Server 端点代际变更与 `embassy serve` 重启都会使用精确任务重新激活。每个替代端点都从仅监控状态开始；只有重新初始化并通过 `thread/loaded/list` 恰好一次找到字节级一致的原任务时，才能重新锚定别名，而且在激活这个精确代际前写入始终保持封锁。因此，正常的代理重启不需要手动重新注册。端点不兼容，或精确任务缺失、重复，都会使路由以 `REOBSERVATION_REQUIRED` 保持陈旧；该任务恢复可观察后，请从精确任务内再次运行 `embassy register-codex --alias codex-reviewer@this-mac`，且不要先注销。Embassy 绝不会按别名改投其他任务，也不会重放写入结果不明确的正文。
+托管 App Server 端点代际变更与 `embassy serve` 重启都会使用精确任务重新激活。新的 `initialize` 用于协商连接；只有 `thread/loaded/list` 恰好一次找到字节级一致的原任务时，Embassy 才会在该精确代际上重新锚定别名。因此，正常的代理重启不需要手动重新注册。精确任务缺失或重复、代际变化或协商失败都会让路由以安全代码保持陈旧；任务恢复可观察后，请从精确任务内再次运行 `embassy register-codex --alias codex-reviewer@this-mac`，且不要先注销。Embassy 绝不会按别名改投其他任务，也不会重放写入结果不明确的正文。
 
 ### 3. 选择 Claude 目的地
 
@@ -81,7 +81,7 @@ embassy select-claude --alias advisor@this-mac
 
 你应看到 `"accepted":true`。注册和选择共同构成一个配对——现在这个 Claude 会话和这个 Codex 任务可以通过 Embassy 交换消息。
 
-当你注册了多个任务后，请用 `embassy pair --claude <name@host> --codex <codex-alias>` 显式指定两端；多个配对可以并存。与 `select-claude` 不同，`pair` 和 `unpair` 必须**在 Codex 任务内部**运行，就像 `register-codex` 一样。在普通终端中它们会以 `CODEX_IDENTITY_REQUIRED` 失败，在 Claude 会话内则以 `CALLER_IDENTITY_CONFLICT` 失败。
+要连接来自不同提供方的任意两条路由，请用 `embassy pair --from <alias> --to <alias>` 显式指定两端；多条边可以并存。命令必须在属于该请求边的继承端点身份下运行。本地操作者也可在实时仪表盘中执行同样的有界确认操作。
 
 ### 4. 发送消息
 
@@ -146,9 +146,9 @@ Embassy 会在实际写入提供方之前，为双向路由消息添加一个由
   └───────────────────────────────────────────────────────────┘
 ```
 
-Embassy 将每个已注册的 Codex 任务以各自的 `codex-*` 对等方身份发布到 Claude Code 的实时会话注册表中。兼容的 Claude 会话通过原生的 `ListAgents` 发现它们，并通过 `SendMessage` 与之通信——无需插件、MCP 服务器或设置更改。
+Embassy 将每个已注册的 Codex 任务以各自的 `codex-*` 对等方身份发布到 Claude Code 的实时会话注册表中。Claude 会话通过 `ListAgents` 发现这些任务；Codex 使用托管 App Server。DeepSeek 与 Grok Build 是启动时登记的 ACP 路由，其自有子进程与单个路由本地会话会在首次投递时惰性启动。
 
-配对是一个 Claude 会话与一个 Codex 任务之间的单一显式权限边，而配对关系是多对多的：一个 Claude 会话可以与多个 Codex 任务建立边，一个 Codex 任务也可以与多个 Claude 会话建立边（默认上限 128 个配对）。每条边都通过 `pair` 或单任务简写 `select-claude` 显式创建；一切都不会被隐式推断。没有边时，发送方以 `SENDER_NOT_PAIRED` 终局结算。`embassy serve --inbound open` 是显式的退出选项，可恢复任意会话入站。
+配对是来自不同提供方的两条具名路由之间的单一显式权限边，默认上限 128 条。每条边都通过通用的 `pair --from/--to` 显式创建；`select-claude` 保留为单 Codex 任务建立 Claude↔Codex 边的简写。一切都不会被隐式推断。没有边时，发送方以 `SENDER_NOT_PAIRED` 终局结算。`embassy serve --inbound open` 是针对受支持原生入站发送方的显式退出选项。
 
 投递时机因方向而异。通过路由与写前检查后，所有朝向 Claude 的正文都会立即写入 Claude 的原生邮箱，无论观测到 Claude 正繁忙还是空闲。`transport_written` 记录这次邮箱写入，并且就是朝向 Claude 的终局 `delivered` 边界；它不表示 Claude 已读取或消费正文。朝向 Codex 的普通正文则在任务忙碌时排队，并在任务空闲后启动轮次。仅在 Claude→Codex 方向，正文以精确 `STEER:` 开头的消息可以在 App Server 的下一个工具调用边界进入当前轮次；若该边界不可用，消息会回到普通队列。
 
@@ -192,7 +192,7 @@ cp -R "$(npm root -g)/agent-embassy/skills/embassy-peer" ~/.claude/skills/
 | `wait-delivery` | 任一提供方 | 等待该跟踪器结算，直至投递截止时间 |
 | `untrack` | 任一提供方 | 关闭一个活跃的进度监视：`embassy untrack --conversation conv_<token>` |
 | `register-codex` / `unregister-codex` | Codex 任务 | 通告或注销该任务；两者都需要 `--alias <codex-alias>`，而 `embassy register-codex --alias codex-successor@this-mac --succeeds codex-reviewer@this-mac` 会将注册转交给另一个任务 |
-| `pair` / `unpair` | Codex 任务 | 显式指定两端来添加或移除一条 Claude↔Codex 边：`embassy pair --claude advisor@this-mac --codex codex-reviewer@this-mac`。与 `register-codex` 一样，它必须在 Codex 任务内部运行 |
+| `pair` / `unpair` | 端点参与方 | 显式指定两端来添加或移除一条跨提供方边：`embassy pair --from advisor@this-mac --to grok-main@this-mac`；继承调用方必须属于该边 |
 | `select-claude` / `unselect-claude` | 操作员或 Codex 任务 | `pair`/`unpair` 的单任务简写，接受 `--alias <name@host>` 或 `--session <uuid>`：仅在 Codex 端无歧义（继承标识或唯一已注册任务）时解析，否则以关闭状态失败 |
 | `send-to-claude` | 已注册的 Codex 任务 | 向已配对的 Claude 会话发送一条有界消息：`--from <codex-alias> --to <claude-alias>`，正文从标准输入读取，可选 `--expects-reply` 与 `--track [--idle-minutes <n>]` |
 | `send-to-codex` | Claude 会话 | 标志与正文输入方式相同，使用继承的原生回复标识 |
@@ -204,7 +204,7 @@ cp -R "$(npm root -g)/agent-embassy/skills/embassy-peer" ~/.claude/skills/
 
 - **本地代理，稳定的 loopback 仪表盘。** `embassy serve` 仅监听私有 Unix 域套接字，不发起任何提供商 API 调用。可选启用的 `embassy dashboard --live` 组件是一个独立进程，也是 Embassy 能创建的唯一监听器；它精确绑定 `127.0.0.1`，默认使用稳定端口 `41961`（也可为本次启动传入 `--port <n>`）。它是在可信单用户机器上有意不设身份认证的本地 HTTP；Host、Origin 与哨兵检查约束浏览器来源的请求，但不认证本地进程或 OS 用户。
 - **同 UID 隔离，而非身份认证。** 调用者身份继承自本地进程环境。路由所有权和生成号检查能减少误操作，但不是对已以你的 OS 用户身份运行的代码的防御。
-- **兼容性依据证据，而非固定补丁版本。** 代理/提供方启动先验证精确的 OS 边界，再应用证据阶梯。同主版本的已认证构建可写；全部探测通过的同主版本构建显示为 `schema_attested`，且仅在探测覆盖写入时才可写。常规 Codex 兼容性与注册读取仍保持只读：它们可能包括 `initialize`、`thread/loaded/list` 与注册时的 `thread/resume`，但不会调用 `turn/start`。唯一例外是可选的 Codex 写入认证探测：每次尝试最多可创建一个代理自有的临时线程，在有界写入围栏下运行且绝不接触用户线程；每个已创建的探测线程都会被归档，并确认已从已加载集合中清除。该探测会解析固定模型所公布的最低 effort。只要该模型/effort 固定项无法解析，探测就会以零消耗故障安全方式拒绝，并且不会创建任何线程或模型轮次。未测试的 Codex 0.x 保持仅监控。探测失败、主版本不同或版本证据未知时，只封锁该提供方，代理和另一提供方继续运行。探测绝不能跨主版本或未知版本提升权限。Embassy 自有或执行的构件及其回调、控制与状态路径不安全时仍拒绝启动；Claude 外部会话注册表根目录不安全时只隔离 Claude。
+- **兼容性在离线阶段测试；运行时尽力而为。** 发布版自有支持矩阵记录精确已测构件、协议、能力、停止保真度、限制与测试日期。运行时从不导入该矩阵，也绝不会把版本事实变成权限。它验证精确自有边界与协议事实，尝试当前操作，并以提供方局部健康度、路由陈旧状态和安全代码报告结果，且绝不重放不确定写入。
 - **来源标记是提示，不是签名。** Embassy 在提供方写入边界生成跨会话来源封装，让接收模型能够区分代理路由消息及其已验证发送方别名；这不是密码学证明，也不会把不可信正文变成可信指令。
 - **原生权限保持原生。** Embassy 不发送任何 Codex 审批或沙盒覆盖，也不应答任何审批请求。`crossSessionInbound` 仍是 Claude 自身的控制机制；Embassy 无法覆盖它。
 - **消息体有界保存，属于你。** 消息体以有界保留策略持久化在 broker 的私有 mode-0600 状态中，让台账能够展示邮件本身；排队中的邮件在 broker 重启后幸存并恰好重发一次。原始提供方帧仍仅存于内存。静态仪表盘文件保持仅元数据；实时仪表盘展示保留的正文。

package/SECURITY.md

@@ -97,14 +97,13 @@ review, and audit work.
   browser can issue or read across origins. They do not authenticate a loopback
   caller, its process, or its UID; the live dashboard assumes a trusted
   single-user machine.
-- **Predictions based on version strings.** A version string is a compatibility
-  observation, never security evidence or attack detection. Directly observed
-  path, ownership, protocol, schema, and generation facts outrank prediction
-  from a version string. Within the security boundary, boot refusal is reserved
-  for an unsafe or lost singleton lease, corrupt controller state, or unsafe
-  OS-boundary attestation. Version drift, an unparseable version, failed probes,
-  or one incompatible provider degrades and write-fences that surface; it does
-  not take down the broker or the other provider.
+- **Predictions based on version strings.** A version string is diagnostic
+  metadata, never routing authority, security evidence, or attack detection.
+  Current path, ownership, protocol, interface, generation, and correlated
+  operation facts decide what Embassy can safely do. Boot refusal is reserved
+  for an unsafe or lost singleton lease, corrupt controller state, or an unsafe
+  OS boundary. Interface drift or one unavailable optional provider degrades
+  that surface; it does not take down the broker or the other providers.
 
 ### Audit rule
 
@@ -172,51 +171,28 @@ broker.
   only listeners are private Unix-domain sockets. The opt-in
   `embassy dashboard --live` companion is a separate process with its own
   loopback HTTP listener — see "Live companion boundary" below.
-- Provider compatibility is evidence-gated rather than patch-version-pinned.
-  Provider startup first validates exact OS ownership, path, symlink, lease,
-  state, and generation evidence. Unsafe evidence for Embassy-owned or executed
+- Provider startup validates exact OS ownership, path, symlink, lease, state,
+  and generation evidence. Unsafe evidence for Embassy-owned or executed
   artifacts and Embassy callback, control, or state paths refuses broker
   startup; unsafe UID or mode evidence for Claude's external sessions registry
-  root quarantines and write-fences only Claude.
-  A certified same-major provider build is writable. A same-major build whose
-  bounded live-schema probes all pass is `schema_attested` and writable only
-  when those probes cover the write path. Claude's probes cover its native
-  write path. Ordinary Codex compatibility and registration reads remain
-  read-only: they may include `initialize`, `thread/loaded/list`, and
-  registration-time `thread/resume`, but do not invoke `turn/start`. The
-  optional Codex write-attestation probe is the sole exception. It may create
-  at most one disposable broker-owned thread per attempt, under a bounded write
-  fence with zero user-thread contact; every created probe thread is archived
-  and confirmed absent from the loaded set. The probe resolves the pinned
-  model's lowest advertised effort. Whenever that model/effort pin cannot
-  resolve, it declines in a zero-spend fail-safe before creating any thread or
-  model turn. Untested Codex 0.x therefore stays monitor-only pending a
-  certified write schema. Failed
-  probes, a different major, or version evidence that cannot establish a safe
-  major leave only that
-  provider degraded, monitor-only, and write-fenced while the broker,
-  control/dashboard surfaces, and other provider remain available; probes
-  never promote across a major or unknown version. A Claude
-  session record whose peer protocol is not 1 is rejected in isolation and
+  root quarantines only Claude. A provider version is best-effort diagnostic
+  metadata and carries no routing authority. Runtime authority comes from an
+  explicit pair, exact owned route and session identity, current connector and
+  generation facts, strict protocol handling, and correlated operation results.
+  A Claude record whose peer protocol is not 1 is rejected in isolation and
   included in bounded rejection evidence. Every replacement Codex endpoint
-  generation remains write-fenced until its fresh initialize and exact-task
-  listing checks pass and the controller activates it.
+  generation must negotiate its current interface and re-observe the exact task
+  before the controller re-anchors it.
 - Embassy publishes at most one process-owned `codex-*` record in Claude's
   registry with the supported explicit versioned Embassy-advertisement marker.
   The prefix is a visible alias convention, not the discriminator: an unmarked
   genuine Claude session named `codex-*` remains discoverable. Embassy creates
   one callback socket and removes only exact-owned artifacts whose generation
   still matches during graceful shutdown.
-- App Server methods are allowlisted. Ordinary connectors expose no archive,
-  deletion, shell, configuration, authentication, plugin, history,
-  approval-response, or generic RPC method. The optional write-attestation
-  probe alone may call `thread/archive`, only for its validated disposable
-  broker-owned probe thread; it then confirms that thread is absent from the
-  loaded set. The probe resolves the pinned model's lowest advertised effort.
-  Whenever that model/effort pin cannot resolve, it declines in a zero-spend
-  fail-safe before creating any thread or model turn. No archive method is
-  exposed to ordinary routes, and the other excluded method classes remain
-  excluded everywhere.
+- App Server methods are allowlisted. Connectors expose no archive, deletion,
+  shell, configuration, authentication, plugin, history, approval-response, or
+  generic RPC method. ACP permission requests are always denied or cancelled;
+  Embassy never turns them into an approval surface.
 - `turn/steer` is reachable only for an exact leading `STEER:` body in the
   Claude-to-Codex direction, with an exact observed active-turn ID. App Server
   admits it at the next tool-call boundary; Embassy never interrupts or injects
@@ -353,39 +329,20 @@ because this surface intentionally has no such authentication boundary.
 Routine tests use temporary directories, fake peers, and fake App Server
 transports. They do not inspect live provider state or contact a model.
 
-Compatibility admission is automatic and evidence-gated. Broker/provider
-startup owns bounded read-only validation of the configured installations,
-exact OS boundaries, provider majors, declared protocol constants, and live
-schemas. Unsafe Embassy-owned/executed artifacts or Embassy callback, control,
-or state paths remain startup-fatal; unsafe UID or mode evidence on Claude's
-external sessions registry root quarantines only that provider. Certified
-same-major builds are writable. Fully probed same-major
-builds are `schema_attested` and writable only where the probes cover writes.
-Ordinary Codex compatibility and registration reads remain read-only: they may
-include `initialize`, `thread/loaded/list`, and registration-time
-`thread/resume`, but do not invoke `turn/start`. The optional Codex
-write-attestation probe is the sole exception. It may create at most one
-disposable broker-owned thread per attempt, under a bounded write fence with
-zero user-thread contact; every created probe thread is archived and confirmed
-absent from the loaded set. The probe resolves the pinned model's lowest
-advertised effort. Whenever that model/effort pin cannot resolve, it declines
-in a zero-spend fail-safe before creating any thread or model turn. Untested
-Codex 0.x therefore remains monitor-only. Failed
-probes, different majors, and
-version evidence that cannot establish a safe major remain provider-local
-monitor-only states; the
-broker and other provider stay available, and no probe can promote across a
-major or unknown version. Different-major guidance
-names the observed/tested versions and supported major and requires an Embassy
-release supporting the observed major. These checks do not route a user
-message or start a model turn. Claude
-registry parsing remains strict for every required and consumed field while
-ignoring unknown top-level fields; bounded rejected-record counts and an
-observed-empty registry are surfaced instead of hidden. A replacement Codex
-endpoint generation receives its own fresh monitor-only initialize and
-exact-task listing check, while the write gate stays closed until controller
-activation. Runtime record, frame, response, identity, generation, and
-deadline checks remain mandatory after admission.
+Broker/provider startup owns bounded validation of configured installations and
+exact OS boundaries. Unsafe Embassy-owned or executed artifacts, callback,
+control, or state paths remain startup-fatal; unsafe UID or mode evidence on
+Claude's external sessions registry root quarantines only that provider.
+Runtime does not import the release-owned support matrix or derive authority
+from version metadata. It reports best-effort connector health, route
+staleness, observed metadata, and last safe codes while strict record, frame,
+response, identity, generation, correlation, and deadline checks decide each
+operation. Claude registry parsing remains strict for every required and
+consumed field while ignoring unknown top-level fields; bounded rejected-record
+counts and an observed-empty registry are surfaced instead of hidden. A
+replacement Codex endpoint negotiates its current interface and re-observes the
+exact registered task before re-anchoring. No validation traffic routes a user
+message or starts a model turn.
 
 Passive live discovery, a live provider connection, a native message, and an
 App Server turn are distinct authorization gates. Each requires an explicit

package/dist/src/gateway/acp-client.d.ts

@@ -0,0 +1,117 @@
+import { type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from "node:child_process";
+export declare const ACP_MAX_REPLY_BYTES: number;
+type JsonObject = Record<string, unknown>;
+type AcpChild = Pick<ChildProcessWithoutNullStreams, "exitCode" | "kill" | "off" | "once" | "signalCode" | "stderr" | "stdin" | "stdout">;
+export type AcpSpawn = (command: string, args: readonly string[], options: SpawnOptionsWithoutStdio) => AcpChild;
+type AcpLaunchCommon = Readonly<{
+    args?: readonly string[];
+    cwd?: string;
+}>;
+export type AcpLaunchSpec = (AcpLaunchCommon & Readonly<{
+    kind: "npx";
+    package: string;
+}>) | (AcpLaunchCommon & Readonly<{
+    kind: "binary";
+    path: string;
+    /** Registry metadata; artifact installation/verification is not this client's job. */
+    sha256: string;
+}>) | (AcpLaunchCommon & Readonly<{
+    kind: "local-checkout";
+    command: string;
+}>);
+export type AcpAgentCapabilities = Readonly<JsonObject>;
+export type AcpConnectionInfo = Readonly<{
+    protocolVersion: number;
+    agentCapabilities: AcpAgentCapabilities;
+    authMethods: readonly unknown[];
+}>;
+export type AcpRpcErrorDetail = Readonly<{
+    code: number;
+    message: string;
+    data?: unknown;
+}>;
+export type AcpPromptReceipt = Readonly<{
+    terminalState: "delivered";
+    stopReason: "end_turn";
+    text: string;
+    textTruncated: boolean;
+}> | Readonly<{
+    terminalState: "failed";
+    stopReason: "max_tokens" | "max_turn_requests" | "refusal";
+    text: string;
+    textTruncated: boolean;
+}> | Readonly<{
+    terminalState: "cancelled";
+    stopReason: "cancelled";
+    text: string;
+    textTruncated: boolean;
+}> | Readonly<{
+    terminalState: "failed";
+    error: AcpRpcErrorDetail;
+    reportOnly: boolean;
+    text: string;
+    textTruncated: boolean;
+}> | Readonly<{
+    /** Process loss cannot prove whether the outstanding prompt completed. */
+    terminalState: "unknown";
+    text: string;
+    textTruncated: boolean;
+}>;
+export type AcpOptionalResult<T> = Readonly<{
+    available: true;
+    value: T;
+}> | Readonly<{
+    available: false;
+    reason: "not_advertised" | "method_not_found";
+}>;
+export type AcpSessionOptions = Readonly<{
+    sessionId: string;
+    cwd: string;
+    mcpServers?: readonly unknown[];
+}>;
+export declare class AcpRequestError extends Error {
+    readonly detail: AcpRpcErrorDetail;
+    constructor(detail: AcpRpcErrorDetail);
+}
+export declare class AcpClient {
+    private readonly child;
+    private readonly pending;
+    private readonly disabledMethods;
+    private readonly activePrompts;
+    private readonly lines;
+    private nextRequestId;
+    private writeChain;
+    private exited;
+    private infoValue;
+    private constructor();
+    static spawn(launch: AcpLaunchSpec, options?: Readonly<{
+        spawn?: AcpSpawn;
+    }>): Promise<AcpClient>;
+    get connectionInfo(): AcpConnectionInfo;
+    newSession(cwd: string, mcpServers?: readonly unknown[]): Promise<Readonly<{
+        sessionId: string;
+    }>>;
+    prompt(sessionId: string, text: string): Promise<AcpPromptReceipt>;
+    cancel(sessionId: string): Promise<void>;
+    authenticate(methodId: string): Promise<void>;
+    listSessions(params?: Readonly<{
+        cwd?: string;
+        cursor?: string;
+    }>): Promise<AcpOptionalResult<unknown>>;
+    resumeSession(options: AcpSessionOptions): Promise<AcpOptionalResult<unknown>>;
+    loadSession(options: AcpSessionOptions): Promise<AcpOptionalResult<unknown>>;
+    close(): void;
+    private initialize;
+    private optionalRequest;
+    private request;
+    private notify;
+    private write;
+    private handleLine;
+    private handleInbound;
+    private consumeSessionUpdate;
+    private handleProcessExit;
+}
+export declare function spawnAcpClient(launch: AcpLaunchSpec, options?: Readonly<{
+    spawn?: AcpSpawn;
+}>): Promise<AcpClient>;
+export {};