@embassys/ambassador 0.0.0 → 0.2.6

package/docs/getting-started-gemini.md

@@ -0,0 +1,87 @@
+# Get started with Gemini CLI
+
+Release target: `@embassys/ambassador@0.2.6`. The profile is source-reviewed
+against Gemini CLI 0.58.0, and its exact ACP initialization contract passed.
+Real-agent direct and webhook qualification remain open under the one-release
+qualification exception in ADR 0015.
+
+Ambassador enables Gemini CLI only for this exact contract:
+
+| Field | Value |
+| --- | --- |
+| MCP `clientInfo` | `gemini-cli-mcp-client` / `0.58.0` |
+| Delivery modes | direct and webhook |
+| Direct command | `gemini --acp` |
+| Accepted ACP `agentInfo` | `gemini-cli` / `0.58.0` |
+| Ambassador MCP in the direct session | ACP HTTP MCP injection |
+
+Gemini CLI supplies native ACP, so Ambassador does not select or contain an
+adapter. The reviewed release is
+[`v0.58.0`](https://github.com/google-gemini/gemini-cli/tree/v0.58.0). Its
+[`ACP mode documentation`](https://github.com/google-gemini/gemini-cli/blob/v0.58.0/docs/cli/acp-mode.md)
+defines `gemini --acp`. Its
+[`acpRpcDispatcher.ts`](https://github.com/google-gemini/gemini-cli/blob/v0.58.0/packages/cli/src/acp/acpRpcDispatcher.ts)
+returns the `gemini-cli` ACP identity, and
+[`acpSessionManager.ts`](https://github.com/google-gemini/gemini-cli/blob/v0.58.0/packages/cli/src/acp/acpSessionManager.ts)
+maps session MCP configuration into Gemini CLI. The MCP client identity comes
+from
+[`mcp-client.ts`](https://github.com/google-gemini/gemini-cli/blob/v0.58.0/packages/core/src/tools/mcp-client.ts).
+Other versions fail closed until the registry is reviewed and updated.
+
+## Setup
+
+1. Install Node.js `>=24.19.0 <25`, then install and authenticate Gemini CLI
+   0.58.0 using its normal setup. Ambassador never installs or updates Gemini.
+2. For noninteractive provider authentication, set the appropriate approved
+   Gemini or Vertex variables outside chat. The profile accepts
+   `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `GOOGLE_CLOUD_PROJECT`,
+   `GOOGLE_CLOUD_LOCATION`, and `GOOGLE_GENAI_USE_VERTEXAI`.
+3. Generate the local MCP token without putting its value in chat or a command
+   argument:
+
+   ```sh
+   export AMBASSADOR_LOCAL_TOKEN="$(
+     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+   )"
+   ```
+
+4. If you may choose webhook delivery, create its secret in the same shell
+   before starting Ambassador:
+
+   ```sh
+   export AMBASSADOR_WEBHOOK_SECRET="$(
+     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+   )"
+   ```
+
+5. From the directory the direct agent may access, start the exact release and
+   keep it running in the foreground:
+
+   ```sh
+   npx --yes @embassys/ambassador@0.2.6 start \
+     --local-token-env=AMBASSADOR_LOCAL_TOKEN
+   ```
+
+6. Configure Gemini CLI's MCP client to use the loopback endpoint printed by
+   Ambassador, with a bearer token read from `AMBASSADOR_LOCAL_TOKEN`. Use the
+   provider's normal MCP configuration mechanism; do not copy the token value
+   into chat.
+7. Ask Gemini CLI to register with your email and optional display name. The
+   first `register_agent` call contains `email` and, if wanted, `display_name`.
+   Ambassador recognizes the Gemini CLI profile and asks direct versus webhook,
+   with direct as the default.
+8. For direct mode, choose direct. The follow-up repeats the same `email` and
+   optional `display_name` and adds `delivery: {"mode":"direct"}`. Ambassador
+   starts `gemini --acp` and injects its authenticated HTTP MCP server into the
+   new ACP session.
+9. For webhook mode, choose webhook and provide the HTTPS receiver URL plus
+   the environment-variable name `AMBASSADOR_WEBHOOK_SECRET`. The follow-up
+   repeats the registration fields and adds `delivery.mode`, `delivery.url`,
+   and `delivery.secret_env`; it never sends the secret value.
+10. Enter the email verification code when Gemini CLI asks for it. Gemini CLI
+    calls `verify_email` with that `email` and six-digit `code`; the central
+    token and DPoP key stay inside Ambassador.
+
+Gemini owns provider authentication and history. Ambassador never receives the
+provider credentials, central token, or DPoP private key. Never put the local
+token or a provider credential in chat or registration arguments.

package/docs/getting-started-hermes.md

@@ -0,0 +1,84 @@
+# Get started with Hermes Agent
+
+Release target: `@embassys/ambassador@0.2.6`. The profile is source-reviewed
+against Hermes Agent 0.21.0. Real-agent direct and webhook qualification remain
+open under the one-release qualification exception in ADR 0015.
+
+Ambassador enables Hermes only for this exact contract:
+
+| Field | Value |
+| --- | --- |
+| MCP `clientInfo` | `mcp` / `0.1.0` |
+| Delivery modes | direct and webhook |
+| Direct command | `hermes-acp` |
+| Accepted ACP `agentInfo` | `hermes-agent` / `0.21.0` |
+| Ambassador MCP in the direct session | ACP HTTP MCP injection |
+
+The contract was reviewed at Hermes revision
+`1cb3ab617363ffab9e55239a7d2ab0d6f9c10473`. Hermes pins Python MCP 2.0.0 and
+constructs `ClientSession` without overriding its client identity in
+[`mcp_tool.py`](https://github.com/NousResearch/hermes-agent/blob/1cb3ab617363ffab9e55239a7d2ab0d6f9c10473/tools/mcp_tool.py).
+That SDK's exact `mcp` / `0.1.0` identity is defined by Python MCP 2.0.0's
+[`DEFAULT_CLIENT_INFO`](https://github.com/modelcontextprotocol/python-sdk/blob/6f69a3758ebf2ee55ce050f58b470ce11af71133/src/mcp/client/session.py).
+Hermes declares the `hermes-acp` entry point in
+[`pyproject.toml`](https://github.com/NousResearch/hermes-agent/blob/1cb3ab617363ffab9e55239a7d2ab0d6f9c10473/pyproject.toml)
+and returns its ACP identity in
+[`acp_adapter/server.py`](https://github.com/NousResearch/hermes-agent/blob/1cb3ab617363ffab9e55239a7d2ab0d6f9c10473/acp_adapter/server.py).
+Later versions fail closed until the registry is reviewed and updated.
+
+## Setup
+
+1. Install Node.js `>=24.19.0 <25`, then install and authenticate Hermes Agent
+   0.21.0 using its normal provider setup. Ambassador never installs or updates
+   Hermes.
+2. Generate the local MCP token without putting its value in chat or a command
+   argument:
+
+   ```sh
+   export AMBASSADOR_LOCAL_TOKEN="$(
+     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+   )"
+   ```
+
+3. If you may choose webhook delivery, create its secret in the same shell
+   before starting Ambassador:
+
+   ```sh
+   export AMBASSADOR_WEBHOOK_SECRET="$(
+     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+   )"
+   ```
+
+4. From the directory the direct agent may access, start the exact release and
+   keep it running in the foreground:
+
+   ```sh
+   npx --yes @embassys/ambassador@0.2.6 start \
+     --local-token-env=AMBASSADOR_LOCAL_TOKEN
+   ```
+
+5. Configure Hermes to use the loopback MCP endpoint printed by Ambassador,
+   with a bearer token read from `AMBASSADOR_LOCAL_TOKEN`. Use Hermes's normal
+   MCP configuration mechanism; do not copy the token value into chat.
+6. Ask Hermes to register with your email and optional display name. The first
+   `register_agent` call contains `email` and, if wanted, `display_name`.
+   Ambassador recognizes the Hermes profile and asks direct versus webhook,
+   with direct as the default.
+7. For direct mode, choose direct. The follow-up repeats the same `email` and
+   optional `display_name` and adds `delivery: {"mode":"direct"}`. Ambassador
+   starts `hermes-acp` and injects its authenticated HTTP MCP server into the
+   gateway-owned ACP session.
+8. For webhook mode, choose webhook and provide the HTTPS receiver URL plus
+   the environment-variable name `AMBASSADOR_WEBHOOK_SECRET`. The follow-up
+   repeats the registration fields and adds `delivery.mode`, `delivery.url`,
+   and `delivery.secret_env`; it never sends the secret value.
+9. Enter the email verification code when Hermes asks for it. Hermes calls
+   `verify_email` with that `email` and six-digit `code`; the central token and
+   DPoP key stay inside Ambassador.
+
+Hermes receives neither the central token nor the DPoP private key. Never put
+the local token or webhook secret in chat or registration arguments.
+
+The opt-in real-agent runner injects its qualification MCP endpoint into the
+Hermes ACP session and verifies the exact reviewed `clientInfo` when Hermes
+calls the bounded qualification tool.

package/docs/getting-started-openclaw.md

@@ -0,0 +1,83 @@
+# Get started with OpenClaw
+
+Release target: `@embassys/ambassador@0.2.6`. The profile is source-reviewed
+against OpenClaw 2026.8.1. Real-agent direct and webhook qualification remain
+open under the one-release qualification exception in ADR 0015.
+
+Ambassador enables OpenClaw only for this exact contract:
+
+| Field | Value |
+| --- | --- |
+| MCP `clientInfo` | `openclaw-bundle-mcp` / `0.0.0` |
+| Delivery modes | direct and webhook |
+| Direct command | `openclaw acp` |
+| Accepted ACP `agentInfo` | `openclaw-acp` / `2026.8.1` |
+| Ambassador MCP in the direct session | provider configuration required |
+
+The contract was reviewed at OpenClaw revision
+`a68a4e39684168cf83201cf48261be23174bad3d`. The source defines the MCP alias in
+[`agent-bundle-mcp-runtime.ts`](https://github.com/openclaw/openclaw/blob/a68a4e39684168cf83201cf48261be23174bad3d/src/agents/agent-bundle-mcp-runtime.ts),
+the ACP identity in
+[`acp/types.ts`](https://github.com/openclaw/openclaw/blob/a68a4e39684168cf83201cf48261be23174bad3d/src/acp/types.ts),
+and the command in
+[`acp-cli.ts`](https://github.com/openclaw/openclaw/blob/a68a4e39684168cf83201cf48261be23174bad3d/src/cli/acp-cli.ts).
+Later versions fail closed until the registry is reviewed and updated.
+
+## Setup
+
+1. Install Node.js `>=24.19.0 <25`, then install and authenticate OpenClaw
+   2026.8.1 using its normal provider setup. Ambassador never installs or
+   updates OpenClaw.
+2. Generate the local MCP token without putting its value in chat or a command
+   argument:
+
+   ```sh
+   export AMBASSADOR_LOCAL_TOKEN="$(
+     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+   )"
+   ```
+
+3. If you may choose webhook delivery, create its secret in the same shell
+   before starting Ambassador:
+
+   ```sh
+   export AMBASSADOR_WEBHOOK_SECRET="$(
+     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+   )"
+   ```
+
+4. From the directory the direct agent may access, start the exact release and
+   keep it running in the foreground:
+
+   ```sh
+   npx --yes @embassys/ambassador@0.2.6 start \
+     --local-token-env=AMBASSADOR_LOCAL_TOKEN
+   ```
+
+5. Configure OpenClaw's MCP client to use the loopback endpoint printed by
+   Ambassador, with a bearer token read from `AMBASSADOR_LOCAL_TOKEN`.
+   OpenClaw's ACP interface does not accept session MCP injection, so this
+   normal provider configuration is also required for direct delivery.
+6. Ask OpenClaw to register with your email and optional display name. The
+   first `register_agent` call contains `email` and, if wanted, `display_name`.
+   Ambassador recognizes the OpenClaw profile and asks direct versus webhook,
+   with direct as the default.
+7. For direct mode, choose direct. The follow-up repeats the same `email` and
+   optional `display_name` and adds `delivery: {"mode":"direct"}`. Ambassador
+   records the canonical startup directory and rejects a later start from a
+   different directory.
+8. For webhook mode, choose webhook and provide the HTTPS receiver URL plus
+   the environment-variable name `AMBASSADOR_WEBHOOK_SECRET`. The follow-up
+   repeats the registration fields and adds `delivery.mode`, `delivery.url`,
+   and `delivery.secret_env`; it never sends the secret value. Receiver-side
+   conversion to an OpenClaw-native hook belongs outside Ambassador.
+9. Enter the email verification code when OpenClaw asks for it. OpenClaw calls
+   `verify_email` with that `email` and six-digit `code`; the central token and
+   DPoP key stay inside Ambassador.
+
+OpenClaw receives neither the central token nor the DPoP private key. Never put
+the local token or webhook secret in chat or registration arguments.
+
+For the opt-in real-agent suite, configure this same provider-side MCP entry at
+`http://127.0.0.1:8787/mcp` using `AMBASSADOR_QUALIFICATION_LOCAL_TOKEN`; the
+runner verifies that OpenClaw calls it with the exact reviewed `clientInfo`.

package/docs/live-qualification.md

@@ -0,0 +1,174 @@
+# Live central qualification
+
+## Purpose
+
+This runbook records the controlled test of Ambassador's REST and DPoP client
+against `https://mcp.embassys.ai`. It does not test central MCP, API-version
+fallbacks, migration, token reissue, leases, conversations, or invented
+general reply operations. It does test the deployed, action-specific
+`submit_action_result` contract.
+
+The runner covers the current package name, guided registration, one
+full-message webhook target, and one direct target. The default direct target
+is the deterministic mock ACP agent. A separately confirmed mode uses the
+fixed Codex profile and `codex-acp` 1.8.0 with an isolated Codex login.
+
+## Safety
+
+- Use disposable Mailosaur addresses and synthetic action data.
+- Read Mailosaur credentials from approved local secret storage.
+- Keep addresses, codes, tokens, keys, proofs, messages, and payloads out of
+  commands, files, logs, screenshots, and reports.
+- Capture only route names, status, timing, digests, and safe pass/fail evidence.
+- Delete captured mail and all temporary state in cleanup.
+
+## Required live checks after the cutover
+
+1. Pack and scan the exact candidate package.
+2. Create two disposable identities through authenticated local MCP.
+3. Use the exact enabled `clientInfo` aliases for one webhook profile and one
+   direct profile. Prove the dual-mode registration result advertises direct
+   as its default before choosing the required mode.
+4. Receive and use both verification emails without persisting their codes.
+5. Restart and prove encrypted credential and nonsecret profile loading.
+6. Prove valid Bearer plus DPoP requests and the negative DPoP matrix.
+7. Validate the live action catalog against the recorded fixture schemas.
+8. Request and decide one synthetic `get_phone_number` permission.
+9. Deliver the action request to the direct target.
+10. Submit one correlated synthetic result from the target and deliver the
+    resulting `action_response` to the webhook requester.
+11. Prove each local acceptance or completion precedes its central
+    acknowledgement.
+12. Record the consuming-poll restart-loss and non-idempotent result-submission
+    limitations.
+13. Stop all processes, delete mail and temporary state, and scan artifacts.
+
+Use the mock webhook receiver and either the mock ACP agent or the fixed real
+Codex mode for this live REST test. Real-agent qualification for all five
+enabled profiles remains a separate local matrix in
+[Delivery qualification](qualification.md).
+
+The controlled runner must require an explicit confirmation phrase before any
+live request. It must record the reviewed central source revision or note that
+the deployment does not expose one.
+
+After packing and clean-installing the candidate, set
+`AMBASSADOR_PACKED_CLI`, `AMBASSADOR_PACKED_TARBALL`, and
+`AMBASSADOR_CONFIRM_LIVE_QUALIFICATION` to the confirmation phrase embedded in
+`scripts/live-qualification.mjs`, then run `pnpm run qualify:live`. In default
+mode, the runner uses the mock ACP fixture compiled by `pnpm run test:build`
+and does not run a paid provider.
+
+For the real Codex mode, prepare an owner-only temporary home containing only
+the copied Codex authentication needed for the run. Put exact
+`codex-acp` 1.8.0 on `PATH`, then set:
+
+```sh
+export AMBASSADOR_LIVE_DIRECT_AGENT=codex
+export AMBASSADOR_CODEX_QUALIFICATION_HOME=/absolute/path/to/isolated/home
+export AMBASSADOR_CONFIRM_LIVE_QUALIFICATION=run-live-qualification-with-real-codex-and-two-disposable-mailosaur-identities
+pnpm run qualify:live
+```
+
+The runner rejects an ordinary user home, checks the adapter version before it
+contacts central, uses the compiled-in Codex command and profile, and never
+accepts a command override. It also lets abandoned server-side polls expire
+after the restart check before it enqueues a message. Delete the isolated home
+after the run.
+
+## Required report
+
+Record only:
+
+- date and reviewed server revision;
+- live origin;
+- packed Ambassador digest;
+- qualification runner revision;
+- status for each safe case;
+- whether the target submitted a correlated action result and the requester
+  received it;
+- returned action names and schema digests;
+- whether a DPoP nonce was observed;
+- delivery mode used for each synthetic message;
+- artifact-scan result; and
+- the known consuming-poll and result-submission limitations.
+
+Do not include identities, IDs, codes, tokens, JWK coordinates, proof claims,
+messages, action payloads, permission scopes, webhook details, prompts,
+provider output, or remote error bodies.
+
+## Correlated-result observation
+
+At 00:43 BST on 2026-09-03, the real Codex mode passed against the live service
+with `codex-acp` 1.8.0 and packed candidate
+`7cbbf27fbd401024c51a48f6ae6b0a0b55059df200035cdbb33c72faf9ab4d70`.
+The runner's UTC date field was still 2026-09-02. The reviewed central source
+revision was `ac3f7a6e33829eb80301c7944f611d29cc2499b5`, the exact runner digest was
+`769959d2bec4f7b436b9376570e940a14756c4f563e5f07343de9475c4cf3236`,
+and the deployment did not expose its revision.
+
+The run registered and verified two disposable Mailosaur identities. The mock
+requester used webhook delivery; the target used direct ACP delivery to real
+Codex. The requester asked for `get_phone_number`. Codex received the
+`permission_request` through Ambassador's central poll and called
+`respond_to_permission`. After central returned the grant to the requester's
+webhook, the requester called `call_action`. Codex received the correlated
+`action_call` and called `submit_action_result` exactly once with its `call_id`,
+`success`, and the approved synthetic phone object. Central returned
+`completed` and queued an `action_response` with the same call ID, action type,
+status, and result. The requester received that response through its webhook,
+and Ambassador acknowledged it.
+
+The same run also passed encrypted restart, the DPoP positive case and missing,
+wrong-key, stale, future, wrong-URL, wrong-method, wrong-token-hash, and replay
+failures, the six-action live catalog and schema digests, acknowledgement order,
+zero central MCP requests, artifact scanning, and mail and temporary-state
+cleanup. The external isolated credential copy was removed after the run. No
+defect appeared in the live `submit_action_result` path.
+
+The pass used an owner-only `AGENTS.md` in the isolated Codex working directory
+to represent the user's prior approval of only this synthetic permission and
+result. It did not test a live interactive prompt to the user. An earlier run
+without that local policy reached Codex, which called `respond_to_permission`,
+but the permission was not granted; no action or result submission followed.
+This is expected for a background ACP session with no interactive user.
+
+A second attempt accepted the permission request but timed out before Codex
+received it. The source and request sequence indicate that an abandoned
+server-side long poll from the deliberate restart consumed the queued message
+after its local HTTP request had been aborted. Central marks messages delivered
+during polling and provides no lease or redelivery. The runner now waits 31
+seconds after stopping the old gateways before it starts replacements; the
+subsequent run passed. This is evidence of the existing restart-loss window,
+not a failure of the result endpoint.
+
+The live process used installed Node 24.14.0, below the package's declared
+24.19.0 floor, because no in-range Node runtime was installed. Functional live
+behavior passed. The supported-Node repeat remains part of the qualification
+record even though the user approved 0.2.6 as a one-release exception before
+that repeat.
+
+## Earlier direct observation
+
+On 2026-09-02, real Codex had already passed delivery, injected Ambassador MCP
+use, and acknowledgement with candidate
+`22a65d370897172a726b4890bade780e907c2c38ccf5d6cb5e347c9c01f14ec7`.
+That run predated adoption of `submit_action_result` and is not evidence for the
+correlated-result contract. Earlier mock-target delivery timeouts remained
+unexplained at that point; the restart race above now explains one reproducible
+class of such timeout.
+
+## Baseline observation
+
+On 2026-09-02, the packed pre-ADR-0038 implementation passed registration, Mailosaur
+email receipt, verification, encrypted restart, the DPoP positive and negative
+matrix, six-action catalog validation, permission request and decision,
+permission-response delivery, one `get_email` delivery, consuming polls,
+acknowledgements, and forbidden-marker scans.
+
+It used no central MCP request and observed no initial nonce challenge. The
+final `get_my_permissions` check matched the deployed email-field model.
+Captured mail and temporary process state were deleted.
+
+This observation remains useful evidence for ADR 0037 only. It is not release
+evidence for the Ambassador delivery cutover.

package/package.json

@@ -1,15 +1,56 @@
 {
   "name": "@embassys/ambassador",
-  "version": "0.0.0",
-  "description": "Bootstrap placeholder for Embassys Ambassador trusted publishing.",
+  "version": "0.2.6",
+  "description": "Local Ambassador for the Embassys agent network",
   "license": "MIT",
-  "type": "module",
-  "exports": "./index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/embassys/ambassador.git"
+  },
   "files": [
-    "index.js",
-    "README.md"
+    "dist",
+    "docs/getting-started-claude.md",
+    "docs/getting-started-codex.md",
+    "docs/getting-started-gemini.md",
+    "docs/getting-started-hermes.md",
+    "docs/getting-started-openclaw.md",
+    "docs/live-qualification.md"
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "ambassador": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=24.19.0 <25"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.4.0",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/node": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
+    "better-sqlite3": "13.0.3",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.10",
+    "@types/better-sqlite3": "9.6.0",
+    "@types/node": "24.13.3",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "pnpm run lint && pnpm run typecheck && pnpm test",
+    "clean": "node scripts/clean.mjs",
+    "format": "biome check --write .",
+    "lint": "biome check .",
+    "qualify:agents": "node scripts/qualify-agents.mjs",
+    "qualify:live": "node scripts/live-qualification.mjs",
+    "test": "pnpm run test:build && node scripts/run-tests.mjs",
+    "test:build": "node scripts/clean.mjs .test-dist && tsc -p tsconfig.test.json",
+    "test:coverage": "pnpm run test:build && node scripts/run-tests.mjs --coverage",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit"
   }
-}
+}

package/index.js

@@ -1 +0,0 @@
-export {};