@embassys/ambassador 0.2.6 → 0.2.7

package/docs/getting-started-gemini.md

@@ -1,87 +1,31 @@
 # 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.
+## Before you start
 
-Ambassador enables Gemini CLI only for this exact contract:
+- Install Node.js `>=24.19.0 <25`.
+- Install and sign in to Gemini CLI `0.58.0`.
+- Gemini supplies native ACP through `gemini --acp`; no adapter is needed.
+- Ambassador never receives your Gemini or Google credential.
 
-| 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 |
+## Set up direct delivery
 
-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:
+1. From the directory Gemini CLI may access, keep Ambassador running:
 
    ```sh
-   export AMBASSADOR_LOCAL_TOKEN="$(
-     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
-   )"
+   npx --yes @embassys/ambassador@0.2.7 start
    ```
 
-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
-   ```
+2. Add `http://127.0.0.1:8787/mcp` as a Streamable HTTP MCP server in Gemini
+   CLI's normal MCP configuration. Do not configure authentication.
+3. Start or restart Gemini CLI so it sees the MCP server.
+4. Ask Gemini CLI to register your email; it calls Ambassador's
+   `register_agent` tool.
+5. Enter the six-digit code sent to your email. Gemini CLI is direct-only, so
+   Ambassador does not ask a delivery question.
 
-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.
+Ambassador will launch `gemini --acp` when a central message arrives. That is
+a new gateway-managed session, not the chat used for registration.
 
-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.
+Only the exact version above is enabled. Other versions fail closed until
+their capability profile is reviewed. See [Qualification](qualification.md)
+for compatibility evidence.

package/docs/getting-started-hermes.md

@@ -1,84 +1,47 @@
 # 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.
+## Before you start
 
-Ambassador enables Hermes only for this exact contract:
+- Install Node.js `>=24.19.0 <25`.
+- Install and authenticate Hermes Agent `0.21.0`.
+- Make sure `hermes-acp` is on `PATH` for direct delivery.
+- Ambassador never receives your provider credential.
 
-| 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 |
+## Set up direct delivery
 
-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:
+1. From the directory Hermes may access, keep Ambassador running:
 
    ```sh
-   export AMBASSADOR_LOCAL_TOKEN="$(
-     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
-   )"
+   npx --yes @embassys/ambassador@0.2.7 start
    ```
 
-3. If you may choose webhook delivery, create its secret in the same shell
-   before starting Ambassador:
+2. Add `http://127.0.0.1:8787/mcp` as a Streamable HTTP MCP server in Hermes's
+   normal MCP configuration. Do not configure authentication.
+3. Start or restart Hermes so it sees the MCP server.
+4. Ask Hermes to register your email; it calls Ambassador's `register_agent`
+   tool.
+5. Choose **Send directly to this Hermes agent**.
+6. Enter the six-digit code sent to your email.
 
-   ```sh
-   export AMBASSADOR_WEBHOOK_SECRET="$(
-     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
-   )"
-   ```
+Ambassador will launch `hermes-acp` when a central message arrives. That is a
+new gateway-managed session, not the chat used for registration.
 
-4. From the directory the direct agent may access, start the exact release and
-   keep it running in the foreground:
+## Use a webhook instead
 
-   ```sh
-   npx --yes @embassys/ambassador@0.2.6 start \
-     --local-token-env=AMBASSADOR_LOCAL_TOKEN
-   ```
+- Before step 1, set the receiver secret in the same shell:
 
-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.
+  ```sh
+  export AMBASSADOR_WEBHOOK_SECRET="$(
+    node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+  )"
+  ```
 
-Hermes receives neither the central token nor the DPoP private key. Never put
-the local token or webhook secret in chat or registration arguments.
+- During registration, choose **Send to a webhook**.
+- Give Hermes the HTTPS webhook URL and the variable name
+  `AMBASSADOR_WEBHOOK_SECRET`.
+- Hermes supplies `delivery.url` and `delivery.secret_env`; it never receives
+  the secret value.
 
-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.
+Only the exact version above is enabled. Other versions fail closed until
+their capability profile is reviewed. See [Qualification](qualification.md)
+for compatibility evidence.

package/docs/getting-started-openclaw.md

@@ -1,83 +1,48 @@
 # 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.
+## Before you start
 
-Ambassador enables OpenClaw only for this exact contract:
+- Install Node.js `>=24.19.0 <25`.
+- Install and authenticate OpenClaw `2026.8.1`.
+- Make sure `openclaw` is on `PATH` for direct delivery.
+- Ambassador never receives your provider credential.
 
-| 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 |
+## Set up direct delivery
 
-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:
+1. From the directory OpenClaw may access, keep Ambassador running:
 
    ```sh
-   export AMBASSADOR_WEBHOOK_SECRET="$(
-     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
-   )"
+   npx --yes @embassys/ambassador@0.2.7 start
    ```
 
-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`.
+2. Add `http://127.0.0.1:8787/mcp` as a Streamable HTTP MCP server in
+   OpenClaw's normal MCP configuration. Do not configure authentication.
+3. Start or restart OpenClaw so it sees the MCP server.
+4. Ask OpenClaw to register your email; it calls Ambassador's `register_agent`
+   tool.
+5. Choose **Send directly to this OpenClaw agent**.
+6. Enter the six-digit code sent to your email.
+
+Ambassador will launch `openclaw acp` when a central message arrives. OpenClaw
+does not accept session MCP injection, so keep the provider-side MCP entry from
+step 2 configured.
+
+## Use a webhook instead
+
+- Before step 1, set the receiver secret in the same shell:
+
+  ```sh
+  export AMBASSADOR_WEBHOOK_SECRET="$(
+    node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+  )"
+  ```
+
+- During registration, choose **Send to a webhook**.
+- Give OpenClaw the HTTPS webhook URL and the variable name
+  `AMBASSADOR_WEBHOOK_SECRET`.
+- OpenClaw supplies `delivery.url` and `delivery.secret_env`; it never receives
+  the secret value.
+
+Only the exact version above is enabled. Other versions fail closed until
+their capability profile is reviewed. See [Qualification](qualification.md)
+for compatibility evidence.

package/docs/live-qualification.md

@@ -25,10 +25,10 @@ fixed Codex profile and `codex-acp` 1.8.0 with an isolated Codex login.
 ## Required live checks after the cutover
 
 1. Pack and scan the exact candidate package.
-2. Create two disposable identities through authenticated local MCP.
+2. Create two disposable identities through loopback 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.
+   direct profile. Prove a dual-mode profile advertises direct as its default;
+   prove a direct-only profile proceeds without a delivery question.
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embassys/ambassador",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Local Ambassador for the Embassys agent network",
   "license": "MIT",
   "repository": {