agent-embassy 3.0.0 → 4.0.0

package/README.md

@@ -1,191 +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.
+
+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.
 
-[![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)
+## Requirements
 
-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.
+- 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.
 
-## Install
+Install one copy with one package manager and verify what the shell resolves:
 
-```bash
+```sh
 npm install -g agent-embassy
-embassy service install
+which -a embassy
+embassy --version
 ```
 
-`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.
-
-```bash
-embassy status
-```
+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.
 
-**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.
+Install the supervised broker:
 
-```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 — kept out of the durable state document and the federation catalog, expiring on its own; its only trace is the native advertisement to Claude sessions, released with it, and a broker that dies mid-check can leave that record until the alias is next registered and released — 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
-
-  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
+The recipient gets a provenance envelope and a conversation-bound reply
+command:
 
-check passed
+```sh
+printf '%s\n' 'Review complete.' |
+  embassy send --conversation conv_example
 ```
 
-Install the skill where each agent discovers skills — Codex tasks can then be prompted with `$embassy-peer`, and Claude Code finds it as a user skill:
+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.
 
-```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/
-```
+## 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 but the unchanged JSON snapshot when piped or with `--json`, so `embassy status --json | jq .routes` and every script keep working. `--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.0.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.0.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 seventeen 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.
+
+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.
 
-## Safety in one minute
+`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.
 
-- **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.
-- **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.
+`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.
 
-See [SECURITY.md](SECURITY.md) for the boundary in depth and how to report a vulnerability.
+## Safety
 
-<!-- tested-with: filled by the PM after the cutover drill -->
+- 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.
 
-## Upgrading from 2.x
+See [Security](SECURITY.md), [Configuration](docs/CONFIGURATION.md), and
+[Architecture](docs/GATEWAY-ARCHITECTURE.md).
 
-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).
+## Upgrading to 4.x
 
-## Documentation
+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