agent-embassy 1.0.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "agent-embassy",
+  "version": "1.0.0",
+  "description": "A local gateway for bidirectional messaging between Claude Code sessions and Codex tasks.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YuanpingSong/embassy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YuanpingSong/embassy/issues"
+  },
+  "homepage": "https://github.com/YuanpingSong/embassy#readme",
+  "keywords": [
+    "ai-agents",
+    "gateway",
+    "claude-code",
+    "codex",
+    "multi-agent"
+  ],
+  "packageManager": "npm@10.9.8",
+  "type": "module",
+  "os": [
+    "darwin"
+  ],
+  "bin": {
+    "embassy": "dist/src/gateway/cli.js",
+    "claude-codex-gateway": "dist/src/gateway/cli.js"
+  },
+  "files": [
+    "dist/src/gateway",
+    "dist/src/errors.js",
+    "dist/src/errors.js.map",
+    "dist/src/errors.d.ts",
+    "dist/src/mutex.js",
+    "dist/src/mutex.js.map",
+    "dist/src/mutex.d.ts",
+    "assets/mark-seal.svg",
+    "assets/mark.svg",
+    "assets/social-preview.png",
+    "skills/embassy-peer",
+    "docs/DESIGN.md",
+    "docs/GATEWAY-ARCHITECTURE.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "README.md",
+    "README.zh-CN.md",
+    "SECURITY.md",
+    "LICENSE",
+    "assets/live-dashboard",
+    "assets/vendor/react"
+  ],
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.build.json && tsc -p src/gateway/live-dashboard-app/tsconfig.json",
+    "check": "npm run typecheck && npm test",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "embassy": "node dist/src/gateway/cli.js",
+    "prepack": "npm run build",
+    "probe:codex-local": "tsx scripts/probe-codex-local.ts",
+    "probe:codex-remote": "tsx scripts/probe-codex-remote.ts",
+    "pretest": "npm run build",
+    "start": "node dist/src/gateway/cli.js serve",
+    "test": "tsx --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json && tsc -p src/gateway/live-dashboard-app/tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ws": "8.21.3"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "@types/react": "18.3.12",
+    "@types/ws": "8.18.1",
+    "tsx": "4.20.6",
+    "typescript": "5.9.3"
+  },
+  "author": "Yuanping Song <yuanping.song@outlook.com>"
+}

package/skills/embassy-peer/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: embassy-peer
+description: Operate Embassy through current name@host or Claude session-UUID selectors. Use when a Codex task needs to register for native inbound messaging, list available peers, open the local dashboard, pair with and message a Claude session, or unregister without exposing provider credentials, socket paths, or message bodies.
+---
+
+# Embassy Peer Gateway
+
+Use only the installed `embassy` CLI. Treat it as the sole facade over the private, local Embassy control socket. Keep this skill repo-scoped; do not install, copy, or modify provider configuration.
+
+Provider-authorized mutations require exactly one inherited principal. Stop on missing or dual Codex/Claude identity; never choose one on the caller's behalf. Operator-only `serve`, health, status, refresh, select, and unselect commands do not infer a provider principal. `pair` and `unpair` carry the inherited `CODEX_THREAD_ID` as attestation when run inside a Codex task and otherwise fail closed; only the authenticated live dashboard creates or removes an edge without attestation.
+
+## Select a peer
+
+Address a Claude session by its latest `name@host` or by a user-supplied native session UUID. The UUID is the stable identity; the name is only the current live index. The gateway stores no historical names, so an old name stops resolving immediately after a rename. The shipped launcher accepts only `this-mac`; remote connectors are deferred. Ask the user to choose a selector when it is ambiguous.
+
+Run `embassy status` to read the current snapshot. Run `embassy refresh-dashboard` when passive live discovery is authorized. Claude Code's native `ListAgents` includes genuine Claude sessions plus each explicitly advertised `codex-*` Embassy peer.
+
+Read the status snapshot's `availablePeers` as sanitized current-name candidates. Native `codex-*` gateway advertisements are excluded because they are not Claude destinations. A send never pairs with a Claude session automatically. Create the exact user-chosen edge with `pair` — or the one-task shorthand `select-claude` — before sending; an unpaired destination is not routable.
+
+Accept a Claude session UUID only when the user supplies it or it is already part of the current task context. Never discover one by scanning history or configuration, and never infer a peer from a thread ID, process ID, working directory, socket path, or title.
+
+## Check the gateway
+
+Run this before a state-changing operation:
+
+```sh
+embassy health
+```
+
+If Embassy is unavailable, stop and report that it must be started in a trusted local terminal with `embassy serve`. `GATEWAY_INSTANCE_IN_USE` means an Embassy or recognized legacy lock already owns this login account; stop that foreground process rather than changing `EMBASSY_STATE_DIR`. If no legacy process remains, the operator may remove only the exact stale legacy controller lock and retry. Do not launch a background copy, retry in a loop, discover sockets, or fall back to a provider CLI.
+
+List the public snapshot:
+
+```sh
+embassy status
+```
+
+Regenerate the metadata-only dashboard:
+
+```sh
+embassy refresh-dashboard
+```
+
+Run that refresh only at the passive-discovery authorization stage. Treat the response as a normalized refresh result; it does not reveal the path. The operator-facing page is `gateway-dashboard.html` in the configured state directory, by default `~/.local/state/agent-embassy/`. Use the operator's configured location when it differs. Do not search for the file or scan controller-owned paths.
+
+## Pair with a Claude session
+
+Create one explicit Claude↔Codex edge by naming both ends. The Claude end must be a user-chosen, unique candidate from `availablePeers`:
+
+```sh
+embassy pair --claude advisor@this-mac --codex codex-reviewer@this-mac
+```
+
+Pairs are additive and bounded; many edges may coexist, and `pair` never retires another edge. Run `pair` and `unpair` from inside a registered Codex task so the CLI reads the inherited `CODEX_THREAD_ID`; a plain operator shell fails closed with `CODEX_IDENTITY_REQUIRED` — use the live dashboard or the one-task shorthand instead. Remove exactly the named edge:
+
+```sh
+embassy unpair --claude advisor@this-mac --codex codex-reviewer@this-mac
+```
+
+When the Codex end is unambiguous — inherited from the calling task, or the sole registered task — the one-task shorthand forms or removes the same edge:
+
+```sh
+embassy select-claude --alias advisor@this-mac
+```
+
+Or address the same logical session directly by UUID:
+
+```sh
+embassy select-claude --session 123e4567-e89b-42d3-a456-426614174000
+```
+
+Remove the same one-task edge by naming the Claude endpoint:
+
+```sh
+embassy unselect-claude --alias advisor@this-mac
+```
+
+With zero or several possible Codex ends, the shorthands fail closed and name the explicit verb; never guess an end on the caller's behalf.
+
+Let the gateway resolve either selector against the current genuine Claude discovery snapshot. It refreshes process and socket coordinates by UUID; those transport details are never caller inputs. If discovery is ambiguous, incompatible, or unavailable, stop on the result.
+
+If the paired session is offline or was renamed while Embassy was stopped, the user may instead supply its UUID with `--session`. Pairing and removal manage only the gateway edge. They do not start, interrupt, configure, or terminate Claude Code.
+
+## Register a Codex task
+
+Register only from the Codex task being named:
+
+```sh
+embassy register-codex --alias codex-reviewer@this-mac
+```
+
+Let the CLI read that task's inherited `CODEX_THREAD_ID`. Never supply the thread ID as an argument, print it, persist it, or register another task by guessing its identity. The alias must start with `codex-`; a successful registration advertises that task for native inbound turns.
+
+The first successful Codex registration fixes its exact alias, task, and host
+until it is explicitly succeeded. Exact re-registration remains available for
+connector recovery. To hand the registration to a different task on the same
+host, run this from inside the successor task:
+
+```sh
+embassy register-codex --alias codex-successor@this-mac --succeeds codex-reviewer@this-mac
+```
+
+This is the only supported identity change without restarting the broker.
+Embassy freezes the outgoing route, drains its accepted work to terminal
+settlement, and publishes the successor on a fresh listener generation.
+Nothing transfers: no queued body, conversation, reply capability, or delivery
+token. A succession that cannot be completed pins the identity fail-closed
+until manual recovery rather than leaving two live registrations.
+
+Embassy also pins the exact identity fail-closed when a retained route cannot fully reactivate or a fresh registration cannot confirm complete rollback. Retry only that exact identity; choose another only after the old route is confirmed unregistered and Embassy is restarted.
+
+Unregister from the same Codex task:
+
+```sh
+embassy unregister-codex --alias codex-reviewer@this-mac
+```
+
+If the task identity or selector does not match, stop on the fail-closed result.
+
+## Send a message
+
+Pass a non-empty UTF-8 body through standard input. Never place message text in a gateway argument or a temporary file.
+
+From a registered Codex task to a paired Claude session:
+
+```sh
+embassy send-to-claude \
+  --from codex-reviewer@this-mac \
+  --to advisor@this-mac <<'GATEWAY_MESSAGE'
+Please review the current approach and note the main risk in your own session.
+GATEWAY_MESSAGE
+```
+
+The `--to` value may instead be the session UUID. The current name and UUID
+address the same logical route; a former name is not retained as an alias.
+
+Let the CLI read the current `CODEX_THREAD_ID`; do not inspect or forward it.
+
+The foreground launcher supports native bidirectional messaging for each explicitly registered `codex-*` task. Claude discovers them with native `ListAgents` and sends with native `SendMessage`. In default paired mode, a task accepts only compatible live Claude sessions holding an explicit pair edge with it; every other sender settles terminally with `SENDER_NOT_PAIRED`. `embassy serve --inbound open` is the explicit operator opt-out that accepts any compatible live same-UID session. The Codex task's existing native approval and sandbox policy governs an accepted turn. Claude Code's `crossSessionInbound` controls messages entering the paired Claude session, including Embassy's outbound Codex-to-Claude delivery. Embassy starts the Codex turn and returns its final reply to the originating Claude session.
+
+An accepted send returns a public conversation token and a fresh delivery token. The delivery token is an opaque, memory-only correlation handle, exactly `dlv_` plus 24 base64url characters. Copy the exact returned value; do not construct, shorten, log, or persist it.
+
+Use exactly one send for one user-authorized message. A send never selects a Claude session automatically. Do not automatically retry, fan out, hand-roll a poll loop, or fall back to Claude Code's native `SendMessage`.
+
+## Reply to a conversation
+
+Use the exact public conversation token returned by the gateway; do not construct one:
+
+```sh
+embassy reply \
+  --conversation conv_REPLACE_WITH_RETURNED_TOKEN \
+  --alias codex-reviewer@this-mac <<'GATEWAY_MESSAGE'
+Here is the requested adjustment.
+GATEWAY_MESSAGE
+```
+
+The CLI infers the caller from the inherited environment. In a Codex task it uses `CODEX_THREAD_ID`; in Claude Code it uses `CLAUDE_CODE_MESSAGING_SOCKET` transiently. Never echo it or pass it as an argument. If both identities or neither identity are present, stop on the fail-closed result instead of selecting one.
+
+An accepted reply returns its own fresh delivery token under the same rules as a send.
+
+## Check or wait for delivery
+
+Use the exact delivery token returned by the accepted send or reply. For one current observation, run:
+
+```sh
+embassy delivery-status --token dlv_0123456789abcdefghijklmn
+```
+
+The token above is a format-only placeholder. Substitute the exact returned token. The result is either `{"found":false}` or a found result with `state`, `terminal`, `updatedAt`, and `deadlineAt`, plus optional `pendingForMs` and `safeErrorCode`. `pendingForMs` is age since gateway acceptance, including time spent in flight. The closed state vocabulary is `queued`, `stalled`, `delivered`, `expired`, `failed`, `ambiguous`, and `cancelled`. Only `queued` and `stalled` are nonterminal.
+
+When the user explicitly asks to wait for finality, run the bounded waiter once:
+
+```sh
+embassy wait-delivery --token dlv_0123456789abcdefghijklmn
+```
+
+It checks every 250 ms and emits only a terminal result. It stops at the delivery deadline plus 3 seconds; an unknown token fails immediately. Exit `0` means `delivered`; every other terminal state (`expired`, `failed`, `ambiguous`, or `cancelled`) preserves its exact JSON result and uses the shared delivery-failure exit `6`. An unknown token exits `3`. A local waiter timeout exits `4`, is not a terminal result, and is not permission to resend. A terminal result closes only that delivery attempt: `delivered` does not promise a reply, and `ambiguous` must never be retried automatically.
+
+The in-memory status table is bounded. Under pressure, only its oldest terminal handle may be evicted; active `queued` or `stalled` handles are retained. An evicted handle returns `{"found":false}`.
+
+## Interpret queue state
+
+Treat `accepted` as gateway ownership, not proof that the peer read or answered the message. Use `delivery-status` for the accepted delivery, or `status` and the dashboard for aggregate route state, when the user asks for progress. The optional `pendingForMs` field is age since acceptance, including in-flight time. `stalled` remains nonterminal. For native Claude-to-Codex ingress, Embassy first attempts immediate dispatch. A terminal result observed before the one-second prompt boundary produces only its terminal acknowledgement; native `held` is sent only when the body truly remains queued or dispatch is still nonterminal at that boundary, followed later by the terminal acknowledgement. Claude's rendered “approved and released” notice means only that the paired-consent gateway accepted and released the body to the recipient queue — released is not read, and no human approval is implied. The default `merged` notice policy separately sends at most one nonterminal stall user frame exactly at `floor(messageDeadlineMs / 2)`, containing only a bounded pending age and allowlisted reason. The operator may choose `verbose` to retain the additional terminal diagnostic user frame or `quiet` to suppress gateway-authored user-frame notices; native status and dashboard truth do not change. Ordinary work queues while the Codex task is active or temporarily unavailable. Only when the user explicitly asks to steer the active Codex turn may a Claude sender put the exact prefix `STEER:` at the beginning of the body. Embassy submits that input at the next tool-call boundary, never mid-generation or by interrupting; clean boundary refusal silently returns it to the normal queue. At most three steering messages remain queued per route, and the dashboard journal labels their lifecycle with `STEER`. If a registered Codex connector is closed or faulted, an explicit `register-codex` replaces it and wakes held work when the recovered route is idle; it never retries an ambiguous write.
+
+Do not synthesize `STEER:`, use it from Codex to Claude, approve permissions, widen tools, alter inbound-message policy, or interrupt a turn to force delivery. Report `held`, refused, incompatible, full, expired, unavailable, or `STEER_QUEUE_SUPERSEDED` outcomes or safe error codes without treating them as additional `delivery-status` states and without retrying. Native receipt settlement follows the originating Claude session's stable UUID and revalidates its current endpoint before every stall or terminal write; names, PIDs, and sockets are not receipt identity. Ordinary process/socket rotation for the same Claude UUID is therefore refreshed automatically. After a gateway restart, the prior UUID-bound selection starts stale, but the next authorized complete discovery may reactivate exactly that UUID and adopt its latest name. A changed UUID, name or UUID collision, incomplete discovery, or failed workspace/provider revalidation stays stale; do not retry around it. Queued or in-flight text, callbacks, native receipt handles, delivery tokens/status trackers, pending replies, and conversation capabilities do not survive. A pre-restart delivery token is unknown and no body is replayed.
+
+## Preserve the boundary
+
+- Keep the gateway local, single-user, and non-hosted.
+- Keep the shipped launcher local-host-only.
+- Never read provider credentials, authentication state, history, settings, registries, raw sockets, or Keychain entries.
+- Publish only each registered `codex-*` peer record owned by the gateway and remove it on shutdown.
+- Never print or copy discovered provider-native identifiers, callback addresses, raw message bodies, tool data, or stderr into skill output or an agent-created file. A user-supplied Claude session UUID may be passed unchanged as an explicit selector, but do not echo it in the normalized result. The gateway may retain the UUID in its closed, mode-0600 private route-binding state.
+- Never modify Claude or Codex permissions, hooks, plugins, agents, MCP configuration, or settings.
+- Return only the CLI's concise public outcome: selectors, normalized state, a public conversation token, or an opaque delivery correlation handle when present.
+
+
+Agents do not use the live dashboard; it is an operator-facing browser surface whose only mutations are explicitly confirmed two-endpoint pair, unpair, and refresh-discovery actions. It has no registration, send, reply, approval, interruption, settings, or generic provider authority. Agent-facing paths remain `embassy status` for a sanitized snapshot and the static `gateway-dashboard.html` for offline metadata. A status snapshot observation may settle already-due lifecycle deliveries before projecting state.

package/skills/embassy-peer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Embassy Peer Gateway"
+  short_description: "Message selected Claude and registered Codex peers"
+  default_prompt: "Use $embassy-peer to register this task and message a selected name@host peer safely."