@embassys/ambassador 0.2.9 → 0.2.11

package/docs/getting-started-hermes.md

@@ -3,49 +3,101 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Install and authenticate the latest Hermes Agent release.
+- Install and authenticate Hermes Agent.
 - Make sure `hermes-acp` is on `PATH` for direct delivery.
 - Ambassador never receives your provider credential.
 
 ## Set up direct delivery
 
-1. From the directory Hermes may access, keep Ambassador running:
+1. From the directory Hermes may access, keep the latest Ambassador running:
 
    ```sh
    npx --yes @embassys/ambassador@latest start
    ```
 
-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.
+2. Add the endpoint printed by Ambassador as an unauthenticated Streamable
+   HTTP MCP server:
+
+   ```sh
+   hermes mcp add ambassador \
+     --url http://127.0.0.1:8787/mcp \
+     --connect-timeout 15
+   ```
+
+   Replace the URL if Ambassador printed a different loopback port. 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`
+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.
 
-Ambassador will launch `hermes-acp` when a central message arrives. That is a
-new gateway-managed session, not the chat used for registration.
+Ambassador launches `hermes-acp` when a central message arrives. That is a new
+gateway-managed session, not the chat used for registration. Reported versions
+are diagnostic only: Ambassador tries the fixed ACP v1 command and exact
+`hermes-agent` identity, then reports a bounded startup, initialization,
+session, or delivery failure if they are incompatible.
+
+## Set up webhook delivery
 
-## Use a webhook instead
+Hermes has a native generic webhook receiver. Configure one owner-controlled
+route that uses the same value for Ambassador's bearer and HMAC V2 contract:
+
+1. With Ambassador running, choose **Send to a webhook** during registration.
+   Ambassador responds with:
+
+   ```sh
+   npx --yes @embassys/ambassador@latest webhook-secret
+   ```
+
+   Ambassador creates the secret, encrypts it in its own owner-only state, and
+   displays it. Repeating the command displays the same value; it does not
+   rotate it.
+
+2. Enable Hermes webhooks with `WEBHOOK_ENABLED=true` and your chosen
+   `WEBHOOK_PORT` in Hermes's owner-only `.hermes/.env`. Add this route to
+   `.hermes/webhook_subscriptions.json`, replacing both placeholders with the
+   displayed value and preserving any existing routes:
+
+   ```json
+   {
+     "embassys": {
+       "description": "Embassys Ambassador",
+       "events": [],
+       "filters": [
+         {
+           "field": "headers.Authorization",
+           "equals": "Bearer PASTE_AMBASSADOR_SECRET_HERE"
+         }
+       ],
+       "prompt": "",
+       "skills": [],
+       "deliver": "log",
+       "secret": "PASTE_AMBASSADOR_SECRET_HERE"
+     }
+   }
+   ```
+
+   Keep the file mode `0600`. An empty prompt passes the complete canonical
+   JSON to the model. The route uses Hermes's normal tool configuration, so
+   keep the Ambassador MCP server enabled there.
+
+3. Start or restart `hermes gateway run`. The local receiver URL is normally:
+
+   ```text
+   http://127.0.0.1:8644/webhooks/embassys
+   ```
 
-- Before step 1, set the receiver secret in the same shell:
+   Use the actual configured port. A non-loopback receiver must use an HTTPS
+   URL.
 
-  ```sh
-  export AMBASSADOR_WEBHOOK_SECRET="$(
-    node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
-  )"
-  ```
+4. Retry `register_agent` with webhook selected and that URL. MCP carries only
+   `delivery.mode` and `delivery.url`; it never carries the secret or a secret
+   name.
 
-- 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.
+Hermes validates the bearer filter and HMAC V2 timestamp/signature before its
+model runs. A webhook `2xx` proves custody only. Keep both Hermes and
+Ambassador running until the model calls `respond_to_permission` or
+`submit_action_result` and the requester receives the correlated response.
 
-Ambassador selects this profile by the exact known MCP client name, then tries
-the fixed `hermes-acp` ACP v1 contract for direct delivery. Reported client and
-agent versions are diagnostic only. An incompatible release fails at startup,
-ACP initialization, session creation, or delivery instead of being rejected by
-a version list. See
-[Qualification](qualification.md) for the artifact-specific compatibility
-evidence.
+For local reruns, see [Reset local test state](development-reset.md).

package/docs/getting-started-openclaw.md

@@ -3,49 +3,110 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Install and authenticate the latest OpenClaw release.
+- Install and authenticate OpenClaw.
 - Make sure `openclaw` is on `PATH` for direct delivery.
 - Ambassador never receives your provider credential.
 
 ## Set up direct delivery
 
-1. From the directory OpenClaw may access, keep Ambassador running:
+1. From the directory OpenClaw may access, keep the latest Ambassador running:
 
    ```sh
    npx --yes @embassys/ambassador@latest start
    ```
 
-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.
+2. Add the endpoint printed by Ambassador as an unauthenticated Streamable
+   HTTP MCP server, then probe it:
+
+   ```sh
+   openclaw mcp set ambassador \
+     '{"url":"http://127.0.0.1:8787/mcp","transport":"streamable-http","enabled":true}'
+   openclaw mcp doctor ambassador --probe
+   ```
+
+   Replace the URL if Ambassador printed a different loopback port. 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.
+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
+Ambassador launches `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.
-
-Ambassador selects this profile by the exact known MCP client name, then tries
-the fixed `openclaw acp` ACP v1 contract for direct delivery. Reported client
-and agent versions are diagnostic only. An incompatible release fails at
-startup, ACP initialization, session creation, or delivery instead of being
-rejected by a version list. See
-[Qualification](qualification.md) for compatibility evidence.
+step 2 configured. Reported versions are diagnostic only: Ambassador tries the
+fixed ACP v1 command and exact `openclaw-acp` identity, then reports a bounded
+startup, initialization, session, or delivery failure if they are incompatible.
+
+## Set up webhook delivery
+
+1. With `ambassador start` still running, choose **Send to a webhook** during
+   registration. Ambassador responds with this setup command:
+
+   ```sh
+   npx --yes @embassys/ambassador@latest webhook-secret
+   ```
+
+   Ambassador creates the secret, encrypts it in its own owner-only state, and
+   displays it. Repeating the command displays the same value; it does not
+   rotate it.
+
+2. Open OpenClaw's native hook configuration:
+
+   ```sh
+   openclaw config patch --stdin
+   ```
+
+   Paste this block with the displayed secret, then send end-of-file with
+   `Ctrl-D`:
+
+   ```json5
+   {
+     hooks: {
+       enabled: true,
+       token: "PASTE_AMBASSADOR_SECRET_HERE",
+       path: "/hooks",
+       allowedAgentIds: ["main"],
+       allowRequestSessionKey: false,
+     },
+   }
+   ```
+
+   OpenClaw stores `hooks.token` in its owner-only configuration. Its native
+   hook does not accept a SecretRef for this field. The secret does not enter a
+   command argument, shell history, or model prompt.
+
+3. Validate the configuration and restart the OpenClaw gateway:
+
+   ```sh
+   openclaw config validate
+   openclaw gateway restart
+   ```
+
+   If the gateway runs in the foreground, stop and start that process instead.
+   The local receiver URL is normally:
+
+   ```text
+   http://127.0.0.1:18789/hooks/agent
+   ```
+
+   Use the actual configured gateway port. A non-loopback receiver must use an
+   HTTPS URL.
+
+4. Retry `register_agent` with webhook selected and that URL. MCP carries only
+   `delivery.mode` and `delivery.url`; it never carries the secret or a secret
+   name.
+
+Ambassador sends OpenClaw's native agent-hook body with the complete central
+message inside a fixed untrusted-input prompt. It selects agent `main`, uses an
+isolated session, suppresses announcement delivery, authenticates with the
+generated bearer secret, and sends the central message ID as the idempotency
+key. A webhook `200` proves that OpenClaw admitted the run. It does not prove
+that the model later called Ambassador MCP. End-to-end checks must wait for the
+correlated permission or action response.
+
+If OpenClaw admits the run but the action times out, check that the agent's own
+provider credential and Ambassador MCP entry are available to the gateway.
+Ambassador does not receive either credential.
+
+For local reruns, see [Reset local test state](development-reset.md).

package/docs/live-qualification.md

@@ -11,7 +11,7 @@ general reply operations. It does test the deployed, action-specific
 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. Separately confirmed modes use the fixed
-Codex or Hermes profiles. Real-provider modes use isolated provider
+Codex, Hermes, or OpenClaw profiles. Real-provider modes use isolated provider
 configuration copies. Installed-version probes are observational; production
 requires the exact known client and ACP agent names and then tries the fixed
 ACP v1 contract.
@@ -33,7 +33,8 @@ ACP v1 contract.
    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.
+5. Restart and prove encrypted credential, encrypted webhook-secret, 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.
@@ -113,6 +114,38 @@ mode starts Hermes's authenticated generic route,
 requires its bearer filter and native HMAC V2 validation, and suppresses
 provider output. Delete the isolated home after every attempt.
 
+For OpenClaw, prepare an owner-only temporary home containing copies of
+`.openclaw/openclaw.json`, `.openclaw/state/openclaw.sqlite`, and
+`.openclaw/agents/main/agent/openclaw-agent.sqlite`. Copy only the provider
+credential used by that OpenClaw agent; for the tested Codex-backed agent this
+also means `.codex/auth.json` and its provider configuration. Use SQLite's
+backup operation for live database copies. Put the installed `openclaw` on
+`PATH`, then choose one fixed mode:
+
+```sh
+export AMBASSADOR_OPENCLAW_QUALIFICATION_HOME=/absolute/path/to/isolated/home
+export AMBASSADOR_LIVE_DIRECT_AGENT=openclaw-direct
+export AMBASSADOR_CONFIRM_LIVE_QUALIFICATION=run-live-qualification-with-real-openclaw-direct-and-two-disposable-mailosaur-identities
+pnpm run qualify:live
+```
+
+or:
+
+```sh
+export AMBASSADOR_OPENCLAW_QUALIFICATION_HOME=/absolute/path/to/isolated/home
+export AMBASSADOR_LIVE_DIRECT_AGENT=openclaw-webhook
+export AMBASSADOR_CONFIRM_LIVE_QUALIFICATION=run-live-qualification-with-real-openclaw-webhook-and-two-disposable-mailosaur-identities
+pnpm run qualify:live
+```
+
+The runner rejects the ordinary OpenClaw home. It configures Ambassador MCP
+only in the copy. Direct mode launches the fixed `openclaw acp` profile and
+requires ACP v1 plus exact agent name `openclaw-acp`. Webhook mode creates the
+secret through the packed Ambassador CLI, writes it to the copied
+OpenClaw configuration through `openclaw config patch --stdin`, enables the
+native `/hooks/agent` route for `main`, and runs the real OpenClaw gateway. It
+does not install a plugin. Delete the isolated home after every attempt.
+
 ## Required report
 
 Record only:
@@ -264,6 +297,45 @@ These observations approve the source registry's exact Hermes ACP 0.20.5
 entry. They do not show that published Ambassador 0.2.7 supports Hermes 0.20.5
 direct mode. Ambassador 0.2.8 contains the candidate change.
 
+## OpenClaw observations
+
+On 2026-09-03, authenticated OpenClaw 2026.8.2 ran on macOS arm64 with Node
+24.19.0 and passed the complete live correlated-result flow in direct and
+webhook modes with the Ambassador 0.2.10 candidate. Both modes registered and
+verified two disposable identities, reloaded encrypted Ambassador state after
+restart, exercised live REST and DPoP plus the deployed action catalog, and
+completed the synthetic phone-number permission and action round trip. The
+real OpenClaw model called `respond_to_permission` and called
+`submit_action_result` exactly once. The controlled requester received the
+correlated final response, and local completion or webhook custody preceded
+central acknowledgement. Final candidate digests and the separate mode results
+are recorded in [Delivery qualification](qualification.md).
+
+Direct mode proved ACP v1 initialization through fixed `openclaw acp`, exact
+agent name `openclaw-acp`, provider-side Ambassador MCP configuration, real
+model execution, and correlated submission. An earlier isolation attempt
+omitted the credential for the agent's configured provider backend; OpenClaw
+then ended the model turn with an authentication failure before any Ambassador
+MCP call. Adding that owner-only credential to the isolated copy made the
+unchanged direct flow pass. This was an isolation-fixture failure, not an
+Ambassador ACP incompatibility.
+
+Webhook mode proved the package-shipped route's bearer and exact-body HMAC V2
+checks, bounded custody queue, real model execution, Ambassador MCP calls, and
+the final response. Earlier receiver attempts returned `202` and Ambassador
+correctly acknowledged central, but OpenClaw made no model or MCP call. The
+first implementation omitted required embedded-run fields. After those were
+added, the detached run inherited the HTTP handler's released work-admission
+lease and OpenClaw rejected it with the safe class `GatewayDrainingError`. A
+plugin-service queue created outside the request context removes that false
+drain path. A `202` still proves custody only; the passing run waited for the
+model calls and requester response.
+
+All OpenClaw attempts used an owner-only isolated home. Mailosaur messages,
+temporary Ambassador state, the OpenClaw copy, and copied provider credentials
+were removed after qualification. No provider output or message content was
+recorded.
+
 ## Earlier direct observation
 
 On 2026-09-02, real Codex had already passed delivery, injected Ambassador MCP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embassys/ambassador",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "Local Ambassador for the Embassys agent network",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,7 @@
     "docs/getting-started-gemini.md",
     "docs/getting-started-hermes.md",
     "docs/getting-started-openclaw.md",
+    "docs/development-reset.md",
     "docs/live-qualification.md"
   ],
   "publishConfig": {