agent-embassy 3.1.0 → 4.0.0

package/README.md

@@ -1,210 +1,212 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/YuanpingSong/embassy/main/assets/social-preview.png" alt="Embassy — a local gateway for messaging between Claude Code sessions and Codex CLI tasks" width="720">
-</p>
-
 # Embassy
 
-**A local embassy for your AI agents.**
+Embassy lets live Claude Code sessions and Codex CLI tasks message one another
+by name, on one Mac or across user-owned Macs reached through SSH. The broker
+wakes the receiving agent through its native interface; agents do not poll.
+Claude→Claude, Claude→Codex, Codex→Claude, and Codex→Codex all use the same
+command and receipt model.
 
-[![CI](https://github.com/YuanpingSong/embassy/actions/workflows/ci.yml/badge.svg)](https://github.com/YuanpingSong/embassy/actions/workflows/ci.yml)
-[![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)
+The core is deliberately small: one private ledger, one delivery coordinator,
+and three write adapters (Claude socket, Codex App Server operation, and SSH
+handoff). Aliases are lookup names. Opaque endpoint IDs are the routing
+identity, so a rename or replacement never silently retargets queued work.
 
-Embassy is a small local broker that lets a [Claude Code](https://code.claude.com) session and a [Codex](https://chatgpt.com/codex) CLI task on the same Mac message each other by name, with a receipt for every delivery. It is personal software — one person, one macOS account, agents you already trust to run as that user — and an unofficial project, not affiliated with or endorsed by Anthropic or OpenAI.
+## Requirements
 
-## Install
+- macOS and Node.js 20 or newer.
+- Claude Code and/or Codex CLI installed for the agents you use.
+- A private `nodes.json` when choosing an explicit host name or federating;
+  first single-machine boot creates one from the short hostname.
+- Key-based, non-interactive SSH between configured machines when federating.
 
-```bash
-npm install -g agent-embassy
-embassy service install
-```
+Install one copy with one package manager and verify what the shell resolves:
 
-Use one global package manager for Embassy (npm or pnpm), not both. Check for shadowing installations in each launch environment:
-
-```bash
+```sh
+npm install -g agent-embassy
 which -a embassy
 embassy --version
-ssh <node> 'which -a embassy; embassy --version'
 ```
 
-For a configured federation peer, `<node>` is its OpenSSH Host alias; the SSH
-check uses federation's non-interactive launch environment. Update or remove a
-shadowing install through its owning package manager; updating npm does not update pnpm.
-The launchd plist pins the absolute Node and CLI paths used by `embassy service install`,
-not the next shell's PATH. After removing an installation, rerun `embassy service install`
-from the retained installation. `embassy service status` reports a plist program path
-that is no longer on disk.
-
-`service install` runs the broker as your user's launchd agent: it starts at login, restarts after a crash, and logs to `~/Library/Logs/agent-embassy/broker.log`. Prefer a process you start by hand? Run `embassy serve` in a terminal and leave it running instead. You need macOS, Node.js 20+, Claude Code (with its [`crossSessionInbound`](docs/CONFIGURATION.md#claude-codes-own-setting-crosssessioninbound) setting enabled on any session that should receive mail), and Codex CLI with the managed standalone App Server — the official installer `curl -fsSL https://chatgpt.com/codex/install.sh | sh`, then `codex app-server daemon start`. From source: `git clone https://github.com/YuanpingSong/embassy && cd embassy && npm ci && npm run build && npm link`.
+The launchd service records the absolute installation path used by
+`embassy service install`. After replacing or removing that installation, run
+the install command again.
 
-Every alias below ends in `@your-host`. Replace `your-host` with this machine's host — the `hostId` on the broker's ready line (in the log, under launchd); name the wrong host and the CLI says which one this machine uses.
+The agent starts at login and uses launchd's crash-only keepalive policy. A
+verified `SIGABRT` crash relaunches it. A clean exit, boot refusal, `SIGTERM`,
+or deliberate `kill -9` leaves it stopped; inspect `embassy service status`
+and install/start it deliberately rather than assuming every signal restarts it.
 
-## Your first message in four commands
+## Quickstart
 
-**1. Register the Codex task.** Ask your Codex agent to run this as a shell step in its current turn; it must run inside the task so it inherits the task's identity. You should see `"accepted":true`.
+For an explicit host name or federation, create `nodes.json` before starting
+the broker. `host` is this machine's name; `nodes` lists directly reachable
+Embassy hosts.
 
-```bash
-embassy register-codex --alias codex-reviewer@your-host
+```json
+{"version":1,"host":"studio","nodes":[]}
 ```
 
-**2. Read what the broker sees.** The `sessions` block lists your live Claude Code sessions by name. If it is empty, start a Claude Code session and run `embassy refresh`, then look again.
+The file lives at
+`$XDG_STATE_HOME/agent-embassy/nodes.json`, or
+`~/.local/state/agent-embassy/nodes.json` when `XDG_STATE_HOME` is unset. It
+must be owned by the current user, mode 0600, inside the private mode-0700 state
+directory. If it is absent on first single-machine boot, Embassy derives a
+lower-case name from the short hostname and atomically writes the equivalent
+empty-node file. It never rewrites a present inventory.
 
-```bash
-embassy status
-```
+Install the supervised broker:
 
-**3. Send.** From the Codex task, body on stdin, to the name `status` showed. The session's route installs on its first use — there is no step between reading a name and messaging it. You get a `conv_` conversation token and a `dlv_` delivery token back.
-
-```bash
-embassy send --from codex-reviewer@your-host --to advisor@your-host --expects-reply <<'MSG'
-Please review the current approach and identify the main risk.
-MSG
+```sh
+embassy service install
+embassy health
 ```
 
-**4. Answer by conversation.** Every delivered body arrives inside one broker-owned `<cross-session-message>` frame naming the attested sender (on a federated hop, the sender is named by the sending node — see [SECURITY.md](SECURITY.md)), and its first `<embassy-reply-hint>` carries the full `conv_` token and this exact command; the recipient runs it with the answer on stdin.
+A Codex task registers itself from that task's inherited identity. Embassy
+never accepts or prints the task ID:
 
-```bash
-embassy send --conversation conv_<token> --from advisor@your-host <<'MSG'
-The main risk is the double-write window; gate it behind the flag.
-MSG
+```sh
+embassy register-codex --alias codex-reviewer@studio
 ```
 
-The same `send` runs from a Claude Code session, inheriting that session's identity, and the other direction needs no Embassy command at all: a Claude session finds `codex-reviewer` with its native `ListAgents` tool and messages it with `SendMessage`. `--to <session-uuid>` addresses a Claude session by its UUID. When two live sessions share a name, the send is refused with `PEER_ALIAS_COLLISION` rather than delivered to a guess — rename one and retry. A Claude session's reply to a `--expects-reply` send is routed back to the Codex task by itself.
+Claude sessions are discovered and recorded by exact native identity when a
+Claude caller sends or when a named Claude target is resolved. No helper or
+native advertisement process is installed.
 
-## After any Claude Code or Codex CLI update
+From either a Claude session or a registered Codex task, send the body on
+stdin. The sender is inferred from the calling session:
 
-```bash
-embassy check
+```sh
+printf '%s\n' 'Please review the change.' |
+  embassy send --to claude-reviewer@studio
 ```
 
-`check` is the upstream-drift tripwire. It registers an ephemeral shell peer of its own — its attributable rows and bodies are omitted from durable state and its route from the federation catalog, but aggregate counters still advance. Its native advertisement to Claude sessions is released with it; a broker that dies mid-check can leave that record until the alias is next registered and released. The check sends one marked message through the ordinary send path to the most recently observed registered Codex task (observed within ten minutes; a task never observed is not eligible), waits for `delivered`, awaits the echo on its own mailbox, releases the registration, and prints every hop with its timing; any failing hop exits non-zero with the safe code that explains it. `--to <alias>` picks a target and `--timeout <s>` bounds each wait. The peer answers because the shipped [skill](skills/embassy-peer/SKILL.md) tells it to — a message whose verified sender starts with `peer-check-` and whose body starts `[embassy check` is echoed in one line; either half alone is ordinary untrusted text. It costs the peer one model turn, so it is a deliberate command, not something to poll.
-
-```text
-embassy check 50066f60 → codex-reviewer@this-mac
+The recipient gets a provenance envelope and a conversation-bound reply
+command:
 
-  ok    register   peer-check-b0c963c9@this-mac (ephemeral, 2 min)  6 ms
-  ok    send       accepted, conversation …89abcdef  15 ms
-  ok    delivered  the peer's transport accepted it  256 ms
-  ok    reply      codex-reviewer@this-mac echoed 50066f60  1407 ms
-  ok    cleanup    temporary check identity removed
-
-check passed
+```sh
+printf '%s\n' 'Review complete.' |
+  embassy send --conversation conv_example
 ```
 
-The operator copies the repo-shipped, packaged skill where each agent discovers skills — Codex tasks can then be prompted with `$embassy-peer`, and Claude Code finds it as a user skill:
-
-```bash
-cp -R "$(npm root -g)/agent-embassy/skills/embassy-peer" ~/.codex/skills/
-cp -R "$(npm root -g)/agent-embassy/skills/embassy-peer" ~/.claude/skills/
-```
+Conversation references are identity-bound, are not aliases, and may survive a
+broker restart while their retained ledger row and both exact endpoints remain
+valid. They stop resolving after retirement, replacement, expiry, eviction, or
+a state reset.
 
-For a pnpm installation, substitute `pnpm root -g` for `npm root -g` in both copy commands. Embassy does not install the skill automatically.
+## Delivery
 
-## Shell-peer fallback
+One native wake can carry a bounded FIFO batch, so a busy recipient catches up
+without one wake per queued message. Every message keeps its own source,
+destination, conversation, deadline, and receipt. Capacity and expiry remain
+visible per message.
 
-Any local harness that can run the CLI can join as a `peer-*` route — no plugin, daemon, PID binding, token file, or Keychain entry — and it is the supported fallback channel when native Codex delivery is unavailable. `embassy register-peer --alias peer-reviewer@your-host` prints a `peer_` token exactly once; keep it in the agent's context, never in argv, and pass it as the first stdin line of every later peer command with `--token-stdin` (the remaining stdin bytes are the body; `--emit-env` exists only for a harness that really does keep one stable shell). `embassy await --alias peer-reviewer@your-host --token-stdin` long-polls the mailbox in bounded 30-second iterations — one waiter per route, 16 in total — writes the complete framed message to stdout, and acknowledges only after stdout has flushed. A missing acknowledgement settles `unconfirmed`; uncertainty after the write was armed settles `ambiguous`; neither is replayed.
+The durable write phases are `queued`, `reserved`, `armed`, `accepted`, and
+`terminal`. Work known not to have been written may return to the queue. An
+uncertain armed or accepted write is never replayed.
 
-## Federation
+An exact leading `STEER:` from Claude to Codex targets the active accepted
+Codex operation at its next safe tool-call boundary. It never interrupts a
+generation. If that boundary is cleanly unavailable, the message remains in
+the ordinary bounded queue. The global kill switch is
+`EMBASSY_STEERING_ENABLED=0`.
 
-`nodes.json` in the state directory is optional. The broker writes it on first boot, naming this machine by its own hostname with an empty peer list, and from then on that file — not the hostname — is the broker's durable identity. To reach a second machine, add its OpenSSH `Host` alias to `nodes`, keep `host` exactly as written, and restart: the brokers exchange body-free route catalogs and destination-owned handoffs over `ssh <node> embassy peer-stdio`, your SSH configuration owns keys and users, and Embassy opens no listener. Remote routes appear as `alias@host` mirrors. Details in [Configuration](docs/CONFIGURATION.md).
+See [Delivery semantics](docs/DELIVERY.md) for the phase and receipt contract.
 
-## Observability
+## Multiple machines
 
-`embassy status` is the one command for "what is going on". It is read-only — it never rescans; `embassy refresh` does — and prints prose in a terminal. Piped or with `--json`, it emits `{ok,command,result}` with the snapshot under `result`: use `embassy status --json | jq .result.routes`. `--recent <n>` (1–100, default 10) sizes the message list.
+List direct peers in each machine's `nodes.json`. The local broker launches:
 
 ```text
-embassy 3.1.0  broker ok · pid 41213 · snapshot just now
-state dir /Users/you/.local/state/agent-embassy
-sessions scanned 3s ago
-
-connectors
-  claude  ok
-  codex   ok
-
-sessions
-  session           state  route   last seen
-  advisor@this-mac  busy   routed  3s ago
-
-routes
-  alias                    provider  state  queue  last seen
-  advisor@this-mac         claude    busy   2      discovered 3s
-  codex-reviewer@this-mac  codex     idle   0      12s ago
-
-recent (3 of 3)
-  12s ago    advisor@this-mac → codex-reviewer@this-mac  queued
-  2m ago     codex-reviewer@this-mac → advisor@this-mac  delivered  210 ms
-             The risk is the double-write window; I would gate it behind…
-  5m ago     advisor@this-mac → codex-reviewer@this-mac  delivered  61 ms
-             Please review the migration risk before the freeze.
+/usr/bin/ssh <node> embassy peer-stdio
 ```
 
-When something is wrong it says the safe code **and** what to do about it, and one quiet corner never makes the whole broker look broken:
-
-```text
-embassy 3.1.0  broker degraded · pid 41213 · snapshot just now
-state dir /Users/you/.local/state/agent-embassy
-sessions scanned 3s ago
-
-connectors
-  claude  ok
-  codex   degraded  MANAGED_CODEX_UNAVAILABLE
-          Either a process outside Embassy holds the managed Codex control socket — quit it — or the managed App Server standalone layout is missing, which starting the daemon alone does not create: follow the Codex prerequisite in the README (the official installer, then the daemon).
-  peer-release@this-mac stale (token or await loop gone)
-          2 message(s) waiting: run `embassy await --alias peer-release@this-mac --token-stdin` in the shell holding its token, or `embassy unregister-peer --alias peer-release@this-mac --token-stdin`.
-
-sessions
-  session           state  route   last seen
-  advisor@this-mac  busy   routed  3s ago
-
-routes
-  alias                    provider  state  queue  last seen
-  advisor@this-mac         claude    busy   2      discovered 3s
-  codex-reviewer@this-mac  codex     stale  1      30m ago
-  peer-release@this-mac    peer      idle   2      never
-    codex-reviewer@this-mac: That Codex task is gone. Run `embassy register-codex --alias <new-alias> --succeeds <this alias>` from the new task, or `embassy unregister-codex --alias <this alias>` from the old one.
-
-recent (3 of 3)
-  12s ago    advisor@this-mac → codex-reviewer@this-mac  queued
-  2m ago     codex-reviewer@this-mac → advisor@this-mac  delivered  210 ms
-             The risk is the double-write window; I would gate it behind…
-  5m ago     advisor@this-mac → codex-reviewer@this-mac  delivered  61 ms
-             Please review the migration risk before the freeze.
-
-alerts
-  PEER_TUNNEL_UNAVAILABLE  studio  45s ago
-    The SSH tunnel to that node is down; check the node is reachable and its broker is running.
+The plain same-user SSH login is the trust boundary. The peer's claimed host
+must be listed in the destination's `nodes.json`; that claim is trusted, not
+independently bound to a physical machine. No forced command or dedicated
+per-node key is required. Configure each node's host label accurately.
+Federation has no listener or multi-hop routing. The destination owns the
+queue and trusts the peer's source identity, so first contact does not wait
+for a destination catalog poll. Catalogs are bounded memory-only observations,
+never routing authority.
+
+`embassy refresh` observes local Claude sessions and every configured SSH
+catalog in parallel. `status` performs no provider or network I/O: it shows the
+last per-node catalog rows and observation time, retains the last rows when a
+later refresh fails, and labels that node `PEER_TUNNEL_UNAVAILABLE`. At most 128
+remote rows are displayed; truncation is explicit. Named and exact sends still
+ask the owner directly.
+
+## Operations
+
+```sh
+embassy status
+embassy status --json
+embassy refresh
+embassy delivery-status --token dlv_example
+embassy wait-delivery --token dlv_example
+embassy retire --alias codex-reviewer@studio
+embassy check
+embassy service status
+embassy serve                              # foreground alternative
 ```
 
-`embassy watch` tails the broker until Ctrl-C: each new message and each settlement at most once (`accepted → delivered (61 ms)`), stamped with the local time, plus route installs and retirements as a secondary line; `--json` streams the same events as JSONL. At most once, not exactly once — a transition that passes entirely between two one-second polls is never seen, and rows that left the retained window before the tail reached them are announced as a one-line note. `embassy --help` lists all eighteen commands.
+`status` reports the broker ledger, queue depth, recent message outcomes,
+retirements, each local route's last native operation, and the last bounded SSH
+catalog observation. It does not claim that an idle provider is ready.
 
-## Safety in one minute
+Machine output is one closed JSON line shaped as
+`{"ok":true,"command":"status","result":{...}}`; route rows are therefore at
+`.result.routes`. A terminal `embassy status` renders the same body for a
+person, while `--json` keeps the envelope.
 
-- **The OS boundary is the permission.** Reaching the same-UID private control socket on this host — or on a host in your `nodes.json` — plus an exact alias is what lets a process message. There is no separate grant to hand out or revoke, because none could stop code already running as your user; a Claude session's route installs on its first use, and a Codex task registers explicitly only because Embassy must record its inherited identity. `embassy serve` binds no TCP port and serves no HTTP.
-- **Retirement is an explicit OS-boundary exception to owner unregister.** `embassy retire --alias codex-reviewer@your-host` requires no route credential and atomically removes any local Claude, Codex, or shell-peer route; it accepts no token, force, or remote option, refuses a federated mirror with `FEDERATED_ROUTE_READ_ONLY`, and prints settlement counts `{cancelled,ambiguous,unconfirmed}`.
-- **Every routed body carries the provenance envelope naming the sender.** It is a marker for the receiving model, not a signature: treat every delivered body as untrusted input. Native permissions stay native — Embassy answers no Codex approval and cannot override Claude's `crossSessionInbound`.
-- **Bounded by design.** Queues, bodies (16 KiB), conversations, rate windows, and deadlines are bounded, and an ambiguous write is never replayed. `delivered` means the provider boundary was crossed — toward Codex the App Server accepted the turn; toward Claude the native mailbox write completed (`transport_written`) — never that a model read it; `unconfirmed` and `ambiguous` mean the evidence is missing and are terminal. Claude-bound bodies are written immediately, busy or idle; Codex-bound bodies queue until the task is idle, and only an exact leading `STEER:` from Claude may enter the active turn at its next tool-call boundary.
-- **Bodies are retained locally and yours.** Message bodies and their opaque delivery token/status persist in the broker's private mode-0600 state under bounded retention, and what `status` prints is a status snapshot that includes retained message bodies: `embassy status` shows retained bodies; treat its output as sensitive as the messages themselves.
+`check` is a broker-only loopback through the real ledger and coordinator. It
+proves local control, persistence, routing, and receipt handling without
+contacting a live Claude or Codex agent. It is not a provider-readiness test.
 
-See [SECURITY.md](SECURITY.md) for the boundary in depth and how to report a vulnerability.
+`retire` removes one local endpoint identity. Queued and reserved work is
+cancelled, armed work becomes ambiguous, and accepted work becomes unconfirmed.
+Remote endpoints must be retired on their owning host.
+If departed sessions share a name, retire one exactly with
+`embassy retire --endpoint <public-id>` using its opaque ID from status.
 
-**Tested with** (cutover drill, 2026-09-03): Claude Code 2.1.259 and Codex CLI 0.152.0 on macOS, Node 22.23, on two machines — a Claude Code session ↔ Codex CLI task round trip in both directions, `embassy check` (register → send → delivered → reply → cleanup), and a cross-machine shell-peer handoff over ssh.
+## Safety
 
-## Upgrading from 2.x
+- The broker uses one private Unix socket and mode-0600 state inside a
+  mode-0700 directory. It does not listen on TCP or HTTP.
+- Native task/session IDs, socket paths, credentials, transcripts, and raw
+  provider frames never appear in public output.
+- Every native write is authorized against the exact current endpoint after
+  preparation. Names are never silently resolved again during an attempt.
+- SSH uses the fixed system binary, batch mode, no forwarding, and no shell.
+- `health` and `check` describe broker infrastructure, not model readiness or
+  comprehension.
 
-Version 3 accepts only fresh private state. Stop Embassy, move `gateway-state.json` aside, start 3.0, and re-register Codex tasks; Claude routes reinstall themselves on first use, and `nodes.json` is written for you if absent. The full [private state reset](docs/CONFIGURATION.md#private-state-reset) and every change are in the [changelog](CHANGELOG.md).
+See [Security](SECURITY.md), [Configuration](docs/CONFIGURATION.md), and
+[Architecture](docs/GATEWAY-ARCHITECTURE.md).
 
-## Documentation
+## Upgrading to 4.x
+
+Version 4 accepts only fresh private state schema 6 and private control
+protocol 5. It does not migrate or read v3 state. Before upgrading, use the old
+binary to inspect and settle work, stop the broker, preserve a backup of the
+old state, then reset `gateway-state.json`. Keep `nodes.json`.
+
+The rollback boundary is the preserved old state plus its matching old binary.
+Do not point an old binary at schema-6 state or a v4 binary at old state.
+
+## Development
+
+Routine tests use test-owned directories, fake Claude sockets, fake App Server
+transports, and fake SSH processes:
+
+```sh
+npm ci
+TMPDIR=/tmp npm run check
+```
 
-| Document | What it covers |
-| --- | --- |
-| [Architecture](docs/GATEWAY-ARCHITECTURE.md) | Topology, adapters, control plane, federation, protocol versions, and the OS-boundary permission model |
-| [Delivery](docs/DELIVERY.md) | Delivery semantics, tokens, settlement states, and retry rules |
-| [Configuration](docs/CONFIGURATION.md) | Environment variables, `nodes.json`, the launchd service, and addressing |
-| [Security policy](SECURITY.md) | The boundary in depth, and how to report a vulnerability |
-| [Contributing](CONTRIBUTING.md) | Where changes go, and how to run the deterministic suite |
-| [Changelog](CHANGELOG.md) | What each release contains |
-| [Agent skill](skills/embassy-peer/SKILL.md) | The workflow an agent follows to operate Embassy |
+No routine test connects a live provider or SSH host. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-[MIT](LICENSE)
+MIT