@embassys/ambassador 0.2.8 → 0.2.10

package/docs/getting-started-openclaw.md

@@ -3,47 +3,110 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Install and authenticate OpenClaw `2026.8.1`.
+- 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.
+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
+
+Webhook mode needs the receiver plugin shipped inside the latest Ambassador
+package. Install Ambassador and the plugin once:
+
+```sh
+npm install --global @embassys/ambassador@latest
+openclaw plugins install --accept-capabilities \
+  "$(npm root --global)/@embassys/ambassador/integrations/openclaw-ambassador"
+```
+
+The capability is an exact authenticated HTTP route. Review and accept it only
+from the Ambassador package you installed.
+
+1. With `ambassador start` still running, choose **Send to a webhook** during
+   registration. Ambassador responds with this setup command:
+
+   ```sh
+   ambassador 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. Store the displayed value in OpenClaw without putting it in shell history:
+
+   ```sh
+   openclaw secrets store set AMBASSADOR_WEBHOOK_SECRET --value-file -
+   ```
+
+   Paste the value, press Enter, then send end-of-file (`Ctrl-D`). Point the
+   plugin at that store entry:
+
+   ```sh
+   openclaw config set plugins.entries.embassys-ambassador.config.secret \
+     --ref-source store --ref-provider default \
+     --ref-id AMBASSADOR_WEBHOOK_SECRET
+   openclaw plugins enable embassys-ambassador --accept-capabilities
+   ```
+
+   The plugin starts the configured OpenClaw agent, which defaults to `main`.
+   It does not select a model or expose the webhook secret to the model.
+
+3. Restart the OpenClaw gateway and run `openclaw plugins doctor`. The local
+   receiver URL is normally:
+
+   ```text
+   http://127.0.0.1:18789/embassys/ambassador
+   ```
 
-## Use a webhook instead
+   Use the actual configured gateway port. A non-loopback receiver must use an
+   HTTPS URL.
 
-- Before step 1, set the receiver secret in the same shell:
+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.
 
-  ```sh
-  export AMBASSADOR_WEBHOOK_SECRET="$(
-    node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
-  )"
-  ```
+The plugin verifies Ambassador's bearer token, exact-body HMAC V2 signature,
+five-minute timestamp window, request ID, and idempotency key before placing the
+message on a bounded in-memory service queue. That service starts the normal
+OpenClaw model turn outside the completed HTTP request. A webhook `202` proves
+that OpenClaw accepted custody. It does not by itself prove that the model later
+called Ambassador MCP; end-to-end checks must wait for the correlated
+permission or action response.
 
-- 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.
+If OpenClaw reports `model execution failed`, run `openclaw plugins doctor` and
+check that the agent's own provider credential and Ambassador MCP entry are
+available to the OpenClaw gateway. Ambassador intentionally logs only a safe
+failure category, not the provider error or message body.
 
-The qualification probe records the installed version without rejecting it.
-Production still checks the exact MCP client and ACP identities in the compiled
-profile, so a new incompatible release fails closed. See
-[Qualification](qualification.md) for compatibility evidence.
+For local reruns, see [Reset local test state](development-reset.md).

package/docs/live-qualification.md

@@ -11,10 +11,10 @@ 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 and their supported exact agent and adapter versions.
-Real-provider modes use isolated provider configuration copies. Their
-installed-version probes are observational; the compiled-in production profile
-still decides ACP compatibility by exact identity matching.
+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.
 
 ## Safety
 
@@ -29,11 +29,12 @@ still decides ACP compatibility by exact identity matching.
 
 1. Pack and scan the exact candidate package.
 2. Create two disposable identities through loopback local MCP.
-3. Use the exact enabled `clientInfo` aliases for one webhook profile and one
+3. Use the exact enabled `clientInfo.name` for one webhook profile and one
    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.
@@ -63,8 +64,8 @@ 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:
+the copied Codex authentication needed for the run. Put the installed
+`codex-acp` on `PATH`, then set:
 
 ```sh
 export AMBASSADOR_LIVE_DIRECT_AGENT=codex
@@ -76,15 +77,16 @@ pnpm run qualify:live
 The runner rejects an ordinary user home, records the installed version when
 one can be observed, uses the compiled-in Codex command and profile, and never
 accepts a command override. The observation does not establish compatibility;
-the exact ACP identity check remains authoritative. The runner also lets
+ACP v1 initialization with the exact known agent name remains authoritative.
+The runner also lets
 abandoned server-side polls expire after the restart check before it enqueues a
 message. Delete the isolated home after the run.
 
 For Hermes, prepare an owner-only temporary home containing only `.hermes/.env`,
 `.hermes/auth.json`, `.hermes/config.yaml`, and
 `.hermes/shared/nous_auth.json` copied from the authenticated installation.
-Remove unrelated MCP entries only from that copy. Put Hermes Agent 0.20.5 or
-0.21.0 and `hermes-acp` on `PATH`, then choose one fixed mode:
+Remove unrelated MCP entries only from that copy. Put the installed Hermes
+Agent and `hermes-acp` on `PATH`, then choose one fixed mode:
 
 ```sh
 export AMBASSADOR_HERMES_QUALIFICATION_HOME=/absolute/path/to/isolated/home
@@ -103,14 +105,46 @@ pnpm run qualify:live
 ```
 
 The runner rejects the ordinary Hermes home and non-owner-only copies. It uses
-exact MCP `clientInfo` `mcp` / `0.1.0`, launches only compiled-in
-`hermes-acp` for direct mode, and configures Ambassador MCP only in the isolated
-copy. The runner records the installed Hermes version when it can, but does not
-use that observation as a compatibility gate; direct ACP identity matching
-remains exact. Webhook mode starts Hermes's authenticated generic route,
+the exact MCP client name `mcp` with a deliberately non-release version value,
+launches only compiled-in `hermes-acp` for direct mode, and configures
+Ambassador MCP only in the isolated copy. The runner records the installed
+Hermes version when it can, but does not use that observation as a compatibility
+gate; direct mode requires ACP v1 and the exact `hermes-agent` name. Webhook
+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 installs the
+package-shipped receiver into the copy, creates the secret through the packed
+Ambassador CLI, stores it through OpenClaw's secret store, and runs the real
+OpenClaw gateway. Delete the isolated home after every attempt.
+
 ## Required report
 
 Record only:
@@ -262,6 +296,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/integrations/openclaw-ambassador/index.mjs

@@ -0,0 +1,171 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { resolveConfiguredSecretInputString } from "openclaw/plugin-sdk/secret-input-runtime";
+
+import {
+  buildAmbassadorPrompt,
+  classifyOpenClawExecutionError,
+  createBoundedOpenClawWorkQueue,
+  verifyAmbassadorWebhook,
+} from "./receiver.mjs";
+
+const MAX_BODY_BYTES = 512 * 1024;
+const SECRET = /^[a-f0-9]{48}$/u;
+const AGENT_ID = /^[A-Za-z0-9._~-]{1,128}$/u;
+const RECEIPT_TTL_MS = 60 * 60 * 1_000;
+const MAX_RECEIPTS = 1_024;
+const MAX_PENDING_MODEL_TURNS = 64;
+
+function response(res, status) {
+  res.statusCode = status;
+  res.setHeader("cache-control", "no-store");
+  res.end();
+  return true;
+}
+
+async function readBody(req) {
+  const declared = req.headers["content-length"];
+  if (declared !== undefined) {
+    const value = Array.isArray(declared) ? Number.NaN : Number(declared);
+    if (!Number.isSafeInteger(value) || value < 0 || value > MAX_BODY_BYTES) return undefined;
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += bytes.byteLength;
+    if (size > MAX_BODY_BYTES) {
+      req.resume();
+      return undefined;
+    }
+    chunks.push(bytes);
+  }
+  return Buffer.concat(chunks, size);
+}
+
+function requestHeaders(req) {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (typeof value === "string") headers.set(name, value);
+  }
+  return headers;
+}
+
+export default definePluginEntry({
+  id: "embassys-ambassador",
+  name: "Embassys Ambassador",
+  description: "Accepts authenticated Ambassador webhooks and starts an OpenClaw model turn.",
+  register(api) {
+    const secret = api.pluginConfig?.secret;
+    const configuredAgentId = api.pluginConfig?.agentId;
+    const agentId = configuredAgentId === undefined ? "main" : configuredAgentId;
+    if (secret === undefined) {
+      api.logger.warn("Embassys Ambassador webhook is not configured");
+      return;
+    }
+    if (
+      !(
+        (typeof secret === "string" && SECRET.test(secret)) ||
+        (secret !== null && typeof secret === "object" && !Array.isArray(secret))
+      )
+    ) {
+      throw new Error("Embassys Ambassador webhook configuration is invalid");
+    }
+    if (typeof agentId !== "string" || !AGENT_ID.test(agentId)) {
+      throw new Error("Embassys Ambassador webhook configuration is invalid");
+    }
+    const receipts = new Map();
+    const workQueue = createBoundedOpenClawWorkQueue(MAX_PENDING_MODEL_TURNS);
+    let acceptingWork = false;
+    let activeRunController;
+    let serviceLoop;
+
+    api.registerService({
+      id: "embassys-ambassador-model-turns",
+      start(ctx) {
+        acceptingWork = true;
+        serviceLoop = (async () => {
+          while (acceptingWork) {
+            const work = await workQueue.next();
+            if (work === undefined) return;
+            const controller = new AbortController();
+            activeRunController = controller;
+            try {
+              const config = api.runtime.config.current();
+              await api.runtime.agent.runEmbeddedAgent({
+                sessionId: work.requestId,
+                runId: work.requestId,
+                timeoutMs: api.runtime.agent.resolveAgentTimeoutMs({ cfg: config }),
+                agentId,
+                workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(config, agentId),
+                config,
+                prompt: work.prompt,
+                trigger: "manual",
+                initialTurnTainted: true,
+                abortSignal: controller.signal,
+              });
+              ctx.serviceHealth?.clearFailure();
+            } catch (error) {
+              if (!controller.signal.aborted) {
+                const classification = classifyOpenClawExecutionError(error);
+                api.logger.error(`Embassys Ambassador model execution failed (${classification})`);
+                ctx.serviceHealth?.reportFailure(
+                  new Error(`Embassys Ambassador model execution failed (${classification})`),
+                );
+              }
+            } finally {
+              if (activeRunController === controller) activeRunController = undefined;
+            }
+          }
+        })();
+      },
+      async stop() {
+        acceptingWork = false;
+        workQueue.close();
+        activeRunController?.abort();
+        await serviceLoop;
+        serviceLoop = undefined;
+      },
+    });
+
+    api.registerHttpRoute({
+      path: "/embassys/ambassador",
+      auth: "plugin",
+      match: "exact",
+      async handler(req, res) {
+        const body = await readBody(req);
+        if (body === undefined) return response(res, 413);
+        const resolvedSecret = await resolveConfiguredSecretInputString({
+          config: api.runtime.config.current(),
+          env: process.env,
+          value: secret,
+          path: "plugins.entries.embassys-ambassador.config.secret",
+          unresolvedReasonStyle: "generic",
+        }).catch(() => ({}));
+        if (typeof resolvedSecret.value !== "string" || !SECRET.test(resolvedSecret.value)) {
+          return response(res, 503);
+        }
+        const verification = verifyAmbassadorWebhook({
+          method: req.method ?? "",
+          headers: requestHeaders(req),
+          body,
+          secret: resolvedSecret.value,
+          nowSeconds: Math.floor(Date.now() / 1_000),
+        });
+        if (!verification.ok) return response(res, verification.status);
+
+        const requestId = requestHeaders(req).get("idempotency-key");
+        if (requestId === null) return response(res, 400);
+        const now = Date.now();
+        for (const [id, expiresAt] of receipts) {
+          if (expiresAt <= now) receipts.delete(id);
+        }
+        if (receipts.has(requestId)) return response(res, 202);
+        if (!acceptingWork || receipts.size >= MAX_RECEIPTS) return response(res, 503);
+        const prompt = buildAmbassadorPrompt(verification.message);
+        if (!workQueue.enqueue({ requestId, prompt })) return response(res, 503);
+        receipts.set(requestId, now + RECEIPT_TTL_MS);
+        return response(res, 202);
+      },
+    });
+  },
+});

package/integrations/openclaw-ambassador/openclaw.plugin.json

@@ -0,0 +1,73 @@
+{
+  "id": "embassys-ambassador",
+  "name": "Embassys Ambassador",
+  "description": "Accepts authenticated Ambassador webhooks and starts an OpenClaw model turn.",
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "$defs": {
+      "secretRef": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "source": {
+            "type": "string",
+            "enum": ["env", "file", "exec", "store"]
+          },
+          "provider": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          }
+        },
+        "required": ["source", "provider", "id"]
+      },
+      "secretInput": {
+        "anyOf": [
+          {
+            "type": "string",
+            "pattern": "^[a-f0-9]{48}$"
+          },
+          {
+            "$ref": "#/$defs/secretRef"
+          }
+        ]
+      }
+    },
+    "properties": {
+      "secret": {
+        "$ref": "#/$defs/secretInput"
+      },
+      "agentId": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 128
+      }
+    },
+    "additionalProperties": false
+  },
+  "configContracts": {
+    "secretInputs": {
+      "paths": [
+        {
+          "path": "secret",
+          "expected": "string",
+          "ownerKind": "route"
+        }
+      ]
+    }
+  },
+  "uiHints": {
+    "secret": {
+      "label": "Ambassador webhook secret",
+      "sensitive": true
+    },
+    "agentId": {
+      "label": "OpenClaw agent ID",
+      "placeholder": "main"
+    }
+  }
+}

package/integrations/openclaw-ambassador/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "embassys-ambassador",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./index.mjs"
+    ]
+  }
+}

package/integrations/openclaw-ambassador/receiver.d.mts

@@ -0,0 +1,43 @@
+export interface AmbassadorWebhookVerificationInput {
+  readonly method: string;
+  readonly headers: Headers;
+  readonly body: Uint8Array;
+  readonly secret: string;
+  readonly nowSeconds: number;
+}
+
+export type AmbassadorWebhookVerification =
+  | { readonly ok: true; readonly message: Record<string, unknown> }
+  | { readonly ok: false; readonly status: 400 | 401 | 405 | 413 };
+
+export function verifyAmbassadorWebhook(
+  input: AmbassadorWebhookVerificationInput,
+): AmbassadorWebhookVerification;
+
+export function buildAmbassadorPrompt(message: Record<string, unknown>): string;
+
+export type OpenClawExecutionErrorClassification =
+  | "plugin_runtime_scope"
+  | "session_admission"
+  | "plugin_admission"
+  | "model_start"
+  | "workspace"
+  | "configuration"
+  | "unknown";
+
+export function classifyOpenClawExecutionError(
+  error: unknown,
+): OpenClawExecutionErrorClassification;
+
+export interface OpenClawQueuedWork {
+  readonly requestId: string;
+  readonly prompt: string;
+}
+
+export interface BoundedOpenClawWorkQueue<T> {
+  enqueue(value: T): boolean;
+  next(): Promise<T | undefined>;
+  close(): void;
+}
+
+export function createBoundedOpenClawWorkQueue<T>(capacity: number): BoundedOpenClawWorkQueue<T>;