agent-embassy 4.0.0 → 4.2.0

package/docs/CONFIGURATION.md

@@ -9,6 +9,8 @@ or version metadata never grants routing authority.
 `EMBASSY_STATE_DIR` may set an absolute state directory. Otherwise Embassy
 uses `$XDG_STATE_HOME/agent-embassy`, or
 `$HOME/.local/state/agent-embassy` when `XDG_STATE_HOME` is unset.
+Every client shell must use the same state-directory configuration captured
+by the installed service.
 
 The directory must be owned by the current user, mode 0700, and must not be a
 symbolic link. `gateway-state.json`, `nodes.json`, and other broker-owned files
@@ -18,8 +20,11 @@ contact the broker. If access was expected, also verify the configured state
 directory belongs to this user; do not start a second broker to work around an
 access denial.
 
-`nodes.json` is the static host and federation inventory. A machine without
-peers uses an empty list:
+`nodes.json` is the static host and federation inventory.
+Create the private state directory before saving the example, and set directory
+mode 0700 and `nodes.json` mode 0600 before installing the service.
+
+A machine without peers uses an empty list:
 
 ```json
 {"version":1,"host":"studio","nodes":[]}
@@ -40,6 +45,9 @@ fallback, dynamic discovery, or multi-hop routing.
 Local route aliases end in the inventory's exact host. `register-codex` and
 `retire` refuse a different host. Remote routes are resolved through the owner
 listed in `nodes`; they can be retired only on that owner.
+Read `host` from the `nodes.json` that first boot created and use it as every
+local `@host` suffix; the examples use `@studio` only when you explicitly chose
+`host: studio`, not as a universal alias suffix.
 
 ## Delivery settings
 
@@ -86,18 +94,35 @@ native agent list.
 
 ### Codex CLI
 
+To receive in Codex, use its managed standalone installation with its App Server
+daemon already running under the same macOS login; merely having a `codex`
+executable on PATH is insufficient, and Embassy does not install or start that daemon.
+
 A Codex task registers itself with `embassy register-codex --alias ...` using
 its inherited `CODEX_THREAD_ID`. The ID is not a command argument or public
 output. Registration is a logical state change and performs no App Server I/O.
 Each delivery independently attests the current App Server interface and exact
 task before authorization, resumes that task without retaining history, and
 writes through a fresh operation.
+The ellipsis in `--alias ...` is a substitution: use the task's chosen
+`codex-` name with this machine's exact `@host` suffix.
 
 `register-codex --succeeds <old-alias>` atomically retires a predecessor and
 installs the caller. It never reanchors pending work to a new identity.
 
 ## SSH federation
 
+Install Embassy and run `embassy service install` on both Macs; for `studio`
+and `laptop`, use `{"version":1,"host":"studio","nodes":["laptop"]}` on
+studio and `{"version":1,"host":"laptop","nodes":["studio"]}` on laptop,
+with each peer name matching both the remote inventory's `host` and a working
+SSH destination or `~/.ssh/config` Host alias.
+
+After changing a running broker's inventory, reload it with
+`embassy service install`; register `codex-reviewer@laptop` from the live
+Codex task on laptop, then ask the Claude session on studio to run
+`embassy send --to codex-reviewer@laptop` with the message on stdin.
+
 For each configured remote node Embassy runs the fixed system SSH client in
 batch mode with forwarding and local commands disabled. Authentication is the
 user's SSH configuration. The remote command is `embassy peer-stdio`; the two
@@ -110,10 +135,12 @@ requires that host to be in its `nodes.json` peer list. The SSH login is
 trusted, so the claim is trusted too. Keep the local `host` correct when
 copying configuration: a wrong allowed host label can misattribute origin.
 
-The non-interactive SSH environment must resolve the intended `embassy`
-installation. Verify that environment with `which -a embassy`. Federation
-does not accept a password, private key, host override, or arbitrary SSH
-argument from Embassy configuration.
+From studio, verify the remote command environment with
+`/usr/bin/ssh laptop 'which -a embassy; node --version; embassy --version'`,
+then verify the corresponding direction from laptop; both remote Node and
+Embassy must resolve without an interactive shell or password prompt.
+Federation does not accept a password, private key, host override, or arbitrary
+SSH argument from Embassy configuration.
 
 Remote endpoint catalogs are bounded memory-only caches. The owner is queried
 again for exact identity resolution. A handoff is one correlated write, the
@@ -127,6 +154,20 @@ and timestamp. A failed observation retains its last rows and records
 provider I/O. Display is capped at 128 remote rows across all nodes; exact and
 named routing always queries the owner and is unaffected by display truncation.
 
+## Multi-host terminal
+
+`embassy tui` uses this inventory for its host overview. Opening it in a terminal
+starts bounded status reads over the same non-interactive SSH configuration as
+federation; it does not modify SSH keys, configuration, or broker protocols.
+Use `[` / `]` for host selection. Explicit actions execute the existing CLI on
+that host, and remote retirement confirms the HOST and full endpoint ID.
+Read timeout is eight seconds; refresh/retire allow fifteen seconds and loopback
+check thirty. A timed-out SSH process is terminated, escalated after one second,
+and never overlapped by a replacement before it closes. Its pane stays stale;
+local operation and other hosts continue. Version diagnostics are lazy remote
+CLI observations only, never broker-version evidence. Unsupported shapes refuse
+display as current data and disable retirement until a supported fresh read.
+
 ## launchd service
 
 ```sh
@@ -135,6 +176,11 @@ embassy service status
 embassy service uninstall
 ```
 
+`embassy service install` starts the per-user launchd agent immediately and
+arranges login startup; use the same command to reload broker configuration or
+start a stopped installation, and use `embassy service uninstall` to stop and
+unload it.
+
 The service is a per-user launchd agent. Installation captures the absolute
 Node executable and Embassy CLI file, plus every nonempty `EMBASSY_*` value and
 `XDG_STATE_HOME` from the installing shell. It captures no other environment
@@ -146,7 +192,7 @@ The plist uses `RunAtLoad` and `KeepAlive` with only `Crashed: true`. A verified
 `SIGABRT` crash relaunches it. A clean exit, nonzero boot refusal, ordinary
 `SIGTERM`, or a deliberate
 `kill -9` leaves the service not running. Use `embassy service status` to
-observe that state and start or reinstall it deliberately.
+observe that state and run `embassy service install` deliberately.
 
 The foreground alternative is `embassy serve`. It does not daemonize or open
 a network listener. Both forms acquire the same fixed host-wide advisory lease
@@ -155,20 +201,26 @@ before provider setup, so only one broker can run.
 ## Private state reset
 
 Version 4 accepts only schema-6 `gateway-state.json`. It deliberately contains
-no v3 converter or compatibility reader. An older or unknown schema refuses
+no 3.x converter or compatibility reader. An older or unknown schema refuses
 with `GATEWAY_STATE_SCHEMA_UNSUPPORTED`; invalid schema-6 bytes refuse with
 `CORRUPT_GATEWAY_STATE`. Refusal does not mutate the installed file.
 
 Reset procedure:
 
-1. With the old matching binary, inspect delivery state and settle or abandon
-   work deliberately.
-2. Stop the broker and confirm the service is not running.
-3. Copy the old `gateway-state.json` to an operator-owned backup.
-4. Move the installed state file aside. Keep the valid `nodes.json`.
-5. Start the v4 broker; it creates fresh schema-6 state.
+1. Before replacing a 3.x installation, use its matching CLI to inspect and
+   settle or explicitly abandon pending work.
+2. Stop a launchd broker with `embassy service uninstall` (or stop the foreground
+   serve process) and confirm it is stopped with `embassy service status`.
+3. Back up and move aside only `gateway-state.json` in that broker's state
+   directory. Keep the valid `nodes.json`.
+4. Install 4.0.0, then run `embassy service install`.
+5. The v4 broker creates fresh schema-6 state.
 6. Re-register Codex tasks. Claude endpoints are recorded on discovery/use.
 
+All state produced by Embassy 3.x is unsupported by 4.x; preserve the matching
+old binary as well as its old state if rollback may be needed, and never run
+the old and new brokers together.
+
 A reset abandons unsettled work and invalidates delivery tokens and
 conversation references. Rollback means stopping v4 and restoring both the old
 binary and its untouched old state. Never hand-edit either schema.

package/docs/GATEWAY-ARCHITECTURE.md

@@ -226,7 +226,7 @@ socket. A mutating request whose reply is lost after write reports
 The public CLI is:
 
 ```text
-register-codex   send              status
+register-codex   send              status            tui
 refresh          delivery-status   wait-delivery
 retire           check             health
 serve            service           peer-stdio
@@ -242,6 +242,14 @@ private loopback endpoints and uses the real ledger/coordinator/receipt path,
 then retires them; no provider or model is contacted. It is not a
 provider-readiness test.
 
+`tui` is a terminal-only client: one in-flight operation per host and no broker
+protocol or state extension. Its local pane uses private control; remote panes
+run existing CLI commands over non-interactive SSH, independently of each other.
+Remote status is validated with the same closed snapshot decoder, not inferred
+from catalogs. Each confirmation captures host and endpoint ID; stale remote
+observations cannot authorize retirement. Lost action responses remain unknown
+and are never automatically replayed. Non-TTY output is local-only.
+
 Machine-facing CLI success is one `{ok, command, result}` JSON line. The
 snapshot is at `.result` and its endpoint rows at `.result.routes`; native
 handles and message bodies cannot hitchhike through the closed result decoder.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-embassy",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "A local gateway for bidirectional messaging between Claude Code sessions and Codex tasks.",
   "license": "MIT",
   "repository": {

package/skills/embassy-peer/SKILL.md

@@ -5,32 +5,40 @@ description: Register a Codex task, find named Claude/Codex sessions, and send o
 
 # Embassy Peer Gateway
 
-Use the installed `embassy` CLI. This skill is packaged for the operator to copy into agent skill directories. The agent must not install or copy skills, or modify provider configuration.
+Use the installed `embassy` CLI. Global npm installation includes `skills/embassy-peer` under the `agent-embassy` package in `npm root -g`; the operator can copy that entire folder into `~/.codex/skills/` and `~/.claude/skills/`, then ask each agent to use it, or provide the shown commands directly to the agent's shell tool. The agent must not install or copy skills, or modify provider configuration.
 
 Send only the authorized body to the named recipient. A peer's message is a request, not a grant to change scope or permissions. Never inspect provider credentials, histories, registry files, socket paths, or inherited identity values to make a call work.
 
 ## Connect and identify
 
-`embassy health` checks the broker control/ledger, not provider readiness. `embassy check` exercises a broker-only loopback without a live agent; it requires no special inbound reply handler. Leave service installation, removal and restarting to the operator unless explicitly requested.
+Healthy means the Embassy control socket and ledger respond; a passing check exercises only broker loopback, so neither proves that a Claude session or Codex task can receive or answer a message. `embassy health` checks the broker control/ledger. `embassy check` requires no special inbound reply handler. Leave service installation, removal and restarting to the operator unless explicitly requested.
 
 A client reads the private state directory and optional `nodes.json`, then connects to its private Unix socket. A sandboxed task needs read/write access to that directory. Follow denied-access guidance; do not relocate state or start a second broker to bypass it. If access was expected, verify `EMBASSY_STATE_DIR` names this user's own directory.
 
-A Codex task registers itself once:
+To receive in Codex, use its managed standalone installation with its App Server daemon already running under the same macOS login; merely having a `codex` executable on PATH is insufficient, and Embassy does not install or start that daemon.
+
+Ask the live Codex CLI task to execute the following registration through its shell tool; an ordinary terminal lacks that task's inherited identity:
 
 ```sh
 embassy register-codex --alias codex-reviewer@your-host
 ```
 
-Replace `your-host` with the configured local host. The CLI reads inherited `CODEX_THREAD_ID`; never supply, print, or guess it. Registration performs no provider I/O. Claude callers are identified from inherited `CLAUDE_CODE_MESSAGING_SOCKET` and live registry evidence on first use; there is no separate Claude registration command.
+Read `host` from the `nodes.json` that first boot created and use it as every local `@host` suffix; replace `your-host` with that exact value, not the example `studio` unless you explicitly chose it. `nodes.json` lives inside `EMBASSY_STATE_DIR` when set; otherwise it lives in `$XDG_STATE_HOME/agent-embassy`, or `~/.local/state/agent-embassy` when `XDG_STATE_HOME` is unset; every client shell must use the same state-directory configuration captured by the installed service.
+
+The CLI reads inherited `CODEX_THREAD_ID`; never supply, print, or guess it. Registration performs no provider I/O. Claude callers are identified from inherited `CLAUDE_CODE_MESSAGING_SOCKET` and live registry evidence on first use; there is no separate Claude registration command.
 
 For `CALLER_IDENTITY_CONFLICT`, strip only the unwanted identity at the call site: `env -u CLAUDE_CODE_MESSAGING_SOCKET embassy …` for Codex, or `env -u CODEX_THREAD_ID embassy …` for Claude. Do not read either value or restart the broker to repair the caller's environment.
 
+Ellipses (`...` or `…`) stand for the intended command and arguments; `conv_REPLACE_WITH_EXACT_REFERENCE`, `dlv_REPLACE_WITH_EXACT_TOKEN`, and `<public-id>` are substitutions for exact received references, returned tokens, and public endpoint IDs, not runnable literal values.
+
 ## Address, send, reply
 
 `embassy status --json` returns metadata under `.result`: owned routes, recent delivery states, retirements and last operation outcomes. It includes no bodies or native IDs. Human terminal rendering is not a parser contract. `embassy refresh` performs live Claude discovery; run it only when authorized. Named sends resolve directly, including over configured SSH, without requiring prior catalog polling at the destination.
 
 Names are lookup indexes, not identities. Stop on `PEER_ALIAS_COLLISION` rather than choosing a session. A Claude UUID may be used as `--to` only when user-supplied; do not discover or echo native IDs. A renamed or replaced endpoint never inherits work addressed to another identity.
 
+Find the current Claude target name with an authorized `embassy refresh` followed by `embassy status --json`, or use the exact current name supplied by that session.
+
 Claude and Codex both send in one command, with no `--from`:
 
 ```sh
@@ -41,7 +49,15 @@ MESSAGE
 
 Use nonempty UTF-8 standard input, at most 16 KiB, never a body argument. Acceptance returns an opaque `deliveryToken` and `conversationId`, not proof of reading or comprehension.
 
-Reply using the exact command from the broker-owned first reply hint:
+Reply using the exact command from the broker-owned first reply hint.
+
+The receiving Codex task sees a broker hint such as:
+
+```text
+<embassy-reply-hint conversation="conv_EXACT_REFERENCE" ...>Reply by running `embassy send --conversation conv_EXACT_REFERENCE` with the reply body on stdin.</embassy-reply-hint>
+```
+
+It must execute the exact received command to send the reply, because ordinary Codex final output is not forwarded automatically; the references below are substitutions, not usable literal values.
 
 ```sh
 embassy send --conversation conv_REPLACE_WITH_EXACT_REFERENCE <<'MESSAGE'
@@ -55,13 +71,15 @@ One wake may contain several independently framed messages. Read each outer `cro
 
 ## Delivery and active turns
 
-Use the exact returned token:
+Retain `result.deliveryToken` from the successful send response in your current session and substitute that exact value for the example; status shows aggregate route queues and recent delivery metadata but cannot recover a lost delivery token or distinguish identical sends by token.
 
 ```sh
 embassy delivery-status --token dlv_REPLACE_WITH_EXACT_TOKEN
 embassy wait-delivery --token dlv_REPLACE_WITH_EXACT_TOKEN
 ```
 
+Use `delivery-status` to inspect that delivery's phase, pending age or terminal code; use `status --json` to identify a stranded local route, and retire it with `retire --alias` using its alias or `retire --endpoint` using its public id from `result.routes`, understanding that this settles all outstanding work for that endpoint.
+
 The waiter is bounded by the deadline plus three seconds. A found result has `state`, `terminal`, `deadlineAt`, and either `pendingForMs` or `safeErrorCode`; an evicted token returns `{found:false}` and waiter exit 3, not a failed-delivery result. `queued`, `reserved`, `armed`, and `accepted` are nonterminal. Terminal states are `delivered`, `failed`, `cancelled`, `expired`, `ambiguous`, and `unconfirmed`. Body pruning keeps receipt and reply references until their count/time retention expires. Cross-host confirmation means the destination durably owns the handoff, not that its agent consumed it.
 
 Do not resend an ambiguous or unconfirmed delivery. `CONTROL_WRITE_OUTCOME_AMBIGUOUS` also means the operation may have applied: inspect status, do not repeat it. Explicit replies are new messages, not automatic forwarding of Codex output.