agent-embassy 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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/).
 
+## [4.0.0] - 2026-09-06
+
+### Changed
+- Replaced the accumulated route/service machinery with endpoint identities, one bounded delivery ledger, one batch coordinator, and explicit Claude, Codex, and SSH destinations. All four Claude/Codex directions work locally and across configured SSH nodes.
+- Both agents send with `embassy send --to <name@host>` or `--conversation <reference>`, using the inherited caller identity rather than `--from`. Receiving remains native. A bounded backlog is delivered in one wake with separately attributed messages; an active Codex operation retains its exact STEER capability until completion or its delivery deadline.
+- Replies are identity-bound ledger relations that survive broker restart while retained. Remote catalogs are display caches, never routing authority; direct owner resolution admits authenticated first contact without waiting for a reverse catalog poll.
+- Every new registration receives a fresh opaque endpoint ID; retirement evidence eviction cannot revive an old reply or remote reference. `retire --endpoint <public-id>` removes a stranded local endpoint even when its name is shared by exited sessions.
+- Status is metadata-only: recent ledger outcomes, retirement evidence and timestamped remote catalog observations. `check` proves a broker-only round trip without contacting a model; it does not claim provider readiness.
+- Breaking reset-only upgrade: private state schema 6, local control protocol 5, federation protocol 3. Stop and inspect unsettled work using the old build, preserve its state backup, and follow [the private-state reset procedure](docs/CONFIGURATION.md#private-state-reset). No automatic conversion or mixed-version federation is supported. Existing queued bodies and reply references do not cross a reset.
+
+### Removed
+- Native Claude sending advertisements and helper processes, shell-peer user endpoints and token/await commands, automatic Codex output forwarding and synthetic reply machinery, general activity/accounting journals, persisted remote mirrors, and `watch`.
+- Deprecated `reply` and `unregister-codex` spellings; use `send --conversation` and operator-authorized `retire`. Unused deduplication and delivery-notice configuration are no longer part of the runtime.
+- Historical deep-import compatibility remains unsupported: the maintained package surface is the CLI, packaged skill and documented public JSON.
+
+### Fixed during RC verification
+- The site quickstart uses the v4 sending forms. Supervision documentation distinguishes crash-signal relaunch from an operator's `kill -9`.
+- Claude pre-write generation changes retry cleanly. Uncertainty follows the committed write phase, without manufacturing a terminal ambiguous result before authorization.
+- Admission rejects bodies that cannot fit the escaped provenance frame. Body pruning preserves bounded receipt/reply stubs, retirement retention is independently bounded, and source-rate capacity is partitioned by host.
+- Delivery status reports its actual nonterminal phase; a missing receipt is a lookup failure rather than a failed delivery. Older RC readers do not understand body-pruned stubs: use the documented reset/rollback policy when replacing RC installations.
+
+## [3.1.0] - 2026-09-05
+
+### Added
+- `embassy retire --alias <local-alias>` — credential-free, same-UID operator removal of any local route (Claude session, Codex task, or shell peer) through the existing atomic removal. It settles queued and reserved work `cancelled`, armed work `ambiguous`, and accepted work `unconfirmed`, reports those counts, journals one `route_retired` event for every provider, and refuses federated mirrors with `FEDERATED_ROUTE_READ_ONLY`. No token, force, or remote option exists.
+- Proven destination enqueue refusals keep their safe code across federation; transport loss and failures after admission remain unknown and are never replayed.
+
+### Changed
+- Private control protocol 3 → 4: one new method (`retire_route`), 15 control methods, 18 CLI commands. A 3.0.0 CLI and a 3.1.0 broker refuse each other with the control mismatch code; restart the broker after upgrading.
+- `EMBASSY_MAX_ROUTES` accepts 2 through 128 and fails closed at config load above that with `INVALID_GATEWAY_CONFIGURATION`. 3.0.0 accepted 129–256 at parse and then refused provider startup. The tracked advertisement-helper cap is the same number.
+- Every busy-observation code on a Claude route (`CLAUDE_PEER_TARGET_UNKNOWN`, `CLAUDE_PEER_WORKSPACE_UNATTESTED`, `CLAUDE_PEER_NOT_OBSERVED`, `CLAUDE_DISCOVERY_UNAVAILABLE`) renders an operator remedy in `status`; the never-produced `CLAUDE_PEER_TARGET_STALE` and `CLAUDE_PEER_TARGET_CHANGED` codes are gone.
+- An idle or stale connector renders `ok` health; a named connector fault or a real provider failure stays `degraded`.
+- The supported package surface is the CLI, the skill, and the documented JSON. Deep imports of shipped `dist` declarations are unsupported; unused internal exports, dead validators, test-only runtime facades, and startup-owned route wiring were removed.
+- Public docs describe advertisement as one helper per local non-Claude route (`codex-*` or `peer-*`); federated mirrors are not advertised. A test guard rejects any singleton "one `codex-*` record" phrasing.
+
+### Fixed
+- Helper admission reserves a pending creation before forking, coalesces same-alias creation, releases a failed reservation, and joins in-flight creation on shutdown so every created client is closed.
+- Federated mirror routes are no longer handed to local native advertisement (no per-reconcile refusal or `NATIVE_ADVERTISEMENT_FAILED` alert).
+- Expired or unknown peer receipts return `not_found`, not `route_mismatch`; the peer-receipt fixtures no longer race a 100 ms timer on slow runners.
+- A renamed Claude source carries its current alias through envelopes, terminal replies, and native replies.
+- The service command's install/status/uninstall output is pinned byte-for-byte; the delivery runner's peer and provider engines are separate methods with a phase-failure characterization and no behavior change.
+
 ## [3.0.0] - 2026-09-03
 
 ### Added

package/CONTRIBUTING.md

@@ -1,208 +1,100 @@
 # Contributing to Embassy
 
-Embassy connects two powerful local agent runtimes across evidence-gated native
-interfaces. Small changes can alter permission, privacy, or delivery behavior,
-so contributions should be narrow, testable, and explicit about boundaries.
+Embassy sits on identity, process, filesystem, protocol, persistence, and
+delivery-settlement boundaries. Prefer a smaller responsibility set and a
+direct implementation over a reusable abstraction the product does not need.
 
 ## Development setup
 
-Use macOS, Node.js 20 or newer, and the npm version declared in `package.json`.
-
-```bash
+```sh
 npm ci
-npm run check
+TMPDIR=/tmp npm run check
 ```
 
-`npm run check` type-checks and runs the deterministic test suite; its `pretest`
-hook rebuilds `dist` first, so the suite always runs against freshly compiled
-output. Routine tests use fake Claude peers, fake App Server transports, and
-temporary directories; they must not contact Anthropic, OpenAI, SSH hosts, live
-provider sockets, or models.
-
-`npm run soak` is the separate deliverability gate. It drives a seeded,
-randomized churn of sends through scripted dispatch faults, busy/idle flips,
-clock jumps, and full restarts, asserting that every accepted message settles
-exactly once into an explicit terminal outcome. It is still deterministic and
-offline; run it for any change to routing, the queue, settlement, or restart
-recovery.
-
-## Before opening a pull request
-
-- Run `npm run check`, and `npm run soak` as well for any delivery, queue,
-  settlement, or restart-recovery change.
-- Add deterministic regression coverage for routing, protocol, persistence,
-  permission, process-lifecycle, or redaction changes.
-- Keep the pull request focused and explain every security-boundary change.
-- For every new audit check, cite the sentence it enforces in
-  [“What Embassy defends, and what it deliberately does not”](SECURITY.md#what-embassy-defends-and-what-it-deliberately-does-not).
-  If no sentence supports the check, propose the doctrine change explicitly,
-  with its product and threat-model consequence, before implementation. Do not
-  smuggle a boundary expansion into a test, review finding, or hardening patch.
-- Update README and architecture documentation when public behavior changes.
-- Verify that public files contain no credentials, native IDs, message bodies,
-  local state, or personal absolute paths.
-- Do not commit `node_modules`, `dist`, package archives, logs, environment
-  files, or live-validation artifacts.
-
-## Architecture rules
-
-### Routing and identity
-
-- Codex tasks self-register through inherited `CODEX_THREAD_ID` and a
-  `codex-*` alias. Never add a thread-ID argument or global task-history scan.
-- A Codex-to-Claude send installs the addressed session's route on first use;
-  a Claude session's own route installs on its first outbound message. There is
-  no separate grant: the permission is the OS boundary — same UID, same host or
-  a host configured in `nodes.json` — plus the exact alias, and the provenance
-  envelope names the sender.
-- Claude's session UUID is its stable logical identity. Current names are a
-  live index; do not add historical-name routing or PID/socket identity.
-- Preserve current-name collision refusal and exact registration fencing.
-- Codex registration is record-only: it changes the durable logical route and
-  performs no provider or App Server I/O. `register-codex --succeeds` is one
-  atomic logical replacement that settles queued/reserved work `cancelled`,
-  armed work `ambiguous`, and accepted work `unconfirmed`; removes every
-  incident conversation, reply, or native capability; and
-  installs only the successor. Do not add prepared generations, re-anchoring,
-  or recovery journals.
-
-### Provider adapters
-
-Claude Code's cross-session feature is official. Embassy's use of its external
-registry and peer socket shape remains an internal adapter: require native
-peer protocol 1 and validate every consumed field and frame. Unknown top-level
-registry fields may be ignored; required and consumed fields remain strict,
-and rejected-record or observed-empty counts must stay loud. Embassy derives
-the registry and callback roots from the verified current OS user; it does not
-inspect a Claude launcher or configuration file. Codex registration
-performs no provider I/O. Its bounded observer is display-only: it may report
-freshness and safe codes but never authorizes, rejects, or delays a delivery.
-Every Codex delivery instead creates an operation-local transport,
-negotiates the current interface, and resumes the exact registered task with
-history excluded before final write authorization. Unsafe ownership, path,
-symlink, lease, state, or used-artifact generation evidence for Embassy-owned
-or executed artifacts and Embassy callback, control, or state paths still
-aborts startup; an unsafe Claude-owned external sessions registry root
-quarantines only Claude. Provider versions remain diagnostic metadata, and
-interface drift or an unavailable optional provider degrades only that
-surface. Do not widen a declared protocol without documented review and
-deterministic fixtures.
-
-The gateway may publish one process-owned `codex-*` peer so Claude's native
-`ListAgents` and `SendMessage` tools can reach Codex. It must never overwrite a
-foreign registry record, claim to be a Claude model session, or unlink a socket
-whose exact generation it no longer owns.
-
-App Server calls use a closed allowlist. Do not add a generic RPC method,
-approval responses, history retrieval, shell execution, settings mutation, or
-provider authentication. The only active-turn method is exact same-session
-`turn/steer` for a leading `STEER:` body on the accepted operation, capped at
-three and admitted only at the next tool-call boundary. Embassy never calls
-`turn/interrupt`. Keep `experimentalApi: true` non-configurable and limited to
-`thread/resume.excludeTurns: true`; every resume must require an empty
-`thread.turns` response.
-
-### Permissions
-
-Embassy does not set or override a Codex task's persistent approval or sandbox
-policy. Registration is the gateway reachability boundary. Bounded observation
-may describe route and approval-waiting status, but it is never authority or a
-dispatch gate and must not classify policy or turn workspace/settings metadata
-into a second authorization gate.
-
-For Codex-to-Claude delivery, Claude's `crossSessionInbound` behavior remains
-native. Do not route around a hold or refusal or fabricate a successful receipt.
-
-### Delivery and state
-
-- Reply addresses are transient. Bodies are bounded and durable: the queue and
-  the recent-delivery ledger both persist them under bounded retention caps.
-- Queue while a Codex task is busy; do not interrupt an unrelated turn.
-- Distinguish gateway acceptance, transport progress, destination acceptance,
-  terminal failure, ambiguity, expiry, and restart abandonment.
-- Never retry an ambiguous provider write. Requeue only a confirmed clean
-  deferral that has not crossed an ambiguous mutation boundary.
-- The private mode-0600 v5 ledger retains bounded queued and recent bodies,
-  opaque delivery tokens, and status. Queued or reserved work may resume once
-  within its deadline and attempt budget against the same exact route and edge.
-  Armed work settles `ambiguous`; accepted work settles `unconfirmed`; neither
-  is replayed. Conversations, reply/native capabilities, raw frames, callback
-  addresses, and socket paths remain memory-only.
-- Persist native route identifiers only in the closed private binding schema.
-  Keep them out of events, snapshots, logs, errors, and CLI
-  output. The only CLI exception is a UUID explicitly supplied by the user as a
-  Claude selector.
-
-### Local control surface
-
-`embassy serve` may use one private same-user control UDS and nothing else. It
-must not listen on TCP or HTTP, and Embassy ships no other listener. Do not add
-a wildcard/remote listener, external assets, service workers, telemetry, or a
-mutation endpoint. Keep the shipped launcher foreground, macOS-only, and
-local-host-only.
-
-## Live validation
-
-Do not run a live probe merely because a test would be convenient. Live Claude
-registry discovery, peer connection, provider messaging, App Server turns, and
-SSH attachment are separate external actions.
-
-A live action requires an explicit user request that identifies its scope. For
-a message, confirm the exact destination and body and avoid fanout. Follow the
-send-failure policy below for command failures; never retry a confirmed
-delivery or a recipient denial. Never put real provider traffic in CI.
-
-## Reporting security issues
-
-Follow [SECURITY.md](SECURITY.md). Use a private GitHub Security Advisory rather
-than a public issue, and replace sensitive local values with synthetic ones.
-
-Two platform notes: the suite binds Unix-domain sockets under `TMPDIR`, and
-macOS caps socket paths at ~104 bytes — keep `TMPDIR` short (CI pins
-`TMPDIR=/tmp`; do the same locally if the transport tests hang). On Linux,
-the darwin-only lease and peer-generation tests skip explicitly (the host
-lease spawns macOS's `/usr/bin/lockf`); macOS runs the full suite.
-
-## Design honesty rules
-
-These outlive any visual era and bind every surface — CLI copy, site, docs:
-
-- Progress is never green. Only a terminal success state may look like one.
-- `delivered` means the write completed; `released` is not read; nothing may
-  imply a model consumed, understood, or acted on a message.
-- Refusals are not failures: a fail-closed refusal renders as policy, not as
-  breakage.
-- The brand accent is never a state color, and state colors are never
-  decoration.
-- Every alert pairs its state with the exact next command, copyable.
-
-### The declined ledger
-
-[`docs/DECLINED.md`](docs/DECLINED.md) records, per release, what we considered
-and chose not to build, each with a one-line reason. It is product
-documentation: a product that documents what it refuses to build is making the
-same promise its status output makes—the truth over the appearance of
-completeness.
-PRs that implement something in the ledger must address its reason.
-
-### Why tickets are priced by the PM
-
-The level of implementation—the one-hour version versus the one-week version—
-is a scope decision, and scope is a product judgment. The PM prices it; the
-engineer builds it faithfully within budget or contests the price with reasons.
-Economy here never means lowering the bar on what ships: it means fewer things,
-done well, and being explicit about what waits.
-
-### Send-failure policy
-
-A send or reply whose command result is an error, truncation, or ambiguity is
-not a delivery—it is a failed attempt to create one. Verify with read-only
-`status`/`delivery-status`; if no acceptance is confirmed, resend without
-asking, up to three attempts. Escalate to the PM only when a recipient
-explicitly denied the message or three resends have failed. A duplicated
-coordination message is a nuisance; a lost one deadlocks the pipeline, so
-deliverability beats ceremony. Never auto-retry a delivery the recipient's
-user denied: that is consent, not transport.
-
-For long messages, write the body to a file and pipe it
-(`embassy send --conversation ... < body.md`); never inline `printf` for prose.
+Tests must use test-owned state directories, fake Claude sockets, fake App
+Server transports, and fake SSH processes. Routine validation must not inspect
+the live Claude registry, contact a live agent or App Server, connect an SSH
+host, install a service, change global packages, or make a model request.
+
+A live operation requires explicit user authorization for that exact operation
+and must never run in CI.
+
+## Core shape
+
+Keep changes inside the v4 architecture:
+
+- `ledger.ts` owns pure synchronous state transitions;
+- `owned-state.ts` owns private atomic persistence;
+- `endpoint-directory.ts` owns alias lookup and exact endpoint resolution;
+- `coordinator.ts` owns batching, phase transitions, and scheduling;
+- Claude, Codex, and SSH each have one explicit destination adapter;
+- `broker.ts` composes application operations;
+- `local-control.ts` and `broker-control.ts` expose one closed private control
+  surface;
+- `core-cli.ts` is the public command entry point.
+
+Do not add another delivery machine, provider-independent engine, state store,
+catalog authority, event journal, callback service, or migration layer unless
+the product contract explicitly changes.
+
+## Required invariants
+
+- Endpoint IDs are identity; aliases are current lookup indexes. Resolve a name
+  once and never silently retarget an admitted message.
+- Validate the exact current endpoint and prepared bytes immediately before a
+  native write.
+- Keep `queued`, `reserved`, `armed`, `accepted`, and `terminal` distinct.
+  Never retry an ambiguous write.
+- Provider I/O never runs inside an owned-state transaction.
+- A destination owns its queue; remote first contact is admitted only from an
+  SSH-authenticated owner assertion.
+- Keep every queue, body, batch, deadline, rate, retained row, protocol frame,
+  and concurrent operation bounded.
+- Keep native identifiers, addresses, message bodies, secrets, and raw
+  provider data out of public projections and errors.
+- Registration, replacement, retirement, restart, expiry, and late callbacks
+  must settle work explicitly without moving it to another identity.
+- Native receive/wake is the core behavior. CLI sending is intentional.
+- STEER uses the exact accepted Codex operation at a safe boundary and never
+  calls `turn/interrupt`.
+
+The governing doctrine is
+[What Embassy defends, and what it deliberately does not](SECURITY.md#what-embassy-defends-and-what-it-deliberately-does-not).
+A new check must cite a current doctrine sentence. If none applies, propose a
+contract change instead of silently widening the boundary.
+
+## Testing changes
+
+Characterize the behavior that matters at the real boundary before changing
+it. Avoid a test that stubs the very loader, decoder, transport, or transaction
+it claims to prove.
+
+For delivery and persistence work, cover the failure phase, not merely the
+success response: before reservation, before authorization, after arming,
+after provider acceptance, after durable destination enqueue, restart, and a
+late or duplicate completion. Mutation or ablation checks are useful when two
+guards could mask one another.
+
+For protocol and CLI work, pin the exact closed JSON shape, protocol number,
+exit status, and stdout/stderr separation. For documentation, pin stable
+commands and version facts directly rather than broad regular expressions that
+unrelated prose can satisfy.
+
+Run the full check after source or test changes. Use the soak suite when a
+change affects scheduling, native transport, restart, or settlement.
+
+## Repository hygiene
+
+Do not commit `node_modules`, `dist`, package archives, state, logs,
+environment files, provider configuration, credentials, or live-validation
+artifacts. Keep public documentation free of personal absolute paths.
+
+Never move tags, force-push shared branches, or edit public main directly.
+Release actions, live drills, service installation, and global package changes
+belong to the release operator.
+
+## Security reports
+
+Use the private security-reporting path. Public issues may include safe codes,
+versions, and sanitized command names; they must not include message bodies,
+native IDs, socket paths, credentials, histories, or raw provider output.