agent-embassy 4.1.0 → 4.2.0

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.