@embassys/ambassador 0.2.8 → 0.2.10

package/dist/sqlite-artifact.js

@@ -1,6 +1,6 @@
 import { chmodSync, closeSync, constants, fchmodSync, fstatSync, lstatSync, openSync, } from "node:fs";
 import { dirname } from "node:path";
-const POSIX = process.platform !== "win32";
+import { secureWindowsArtifactSync } from "./windows-access-control.js";
 function errorCode(error) {
     return error !== null && typeof error === "object" && "code" in error
         ? String(error.code)
@@ -9,7 +9,7 @@ function errorCode(error) {
 function sameArtifact(left, right) {
     return left.dev === right.dev && left.ino === right.ino;
 }
-function secureExistingFile(path, invalidArtifact) {
+function secureExistingFile(path, invalidArtifact, platform, windowsAccessControl) {
     let pathStats;
     try {
         pathStats = lstatSync(path, { bigint: true });
@@ -21,7 +21,9 @@ function secureExistingFile(path, invalidArtifact) {
     }
     if (!pathStats.isFile() || pathStats.nlink !== 1n)
         throw invalidArtifact();
-    if (POSIX)
+    if (platform === "win32")
+        windowsAccessControl?.secure(path, "file");
+    else
         chmodSync(path, 0o600);
     const currentStats = lstatSync(path, { bigint: true });
     if (!currentStats.isFile() ||
@@ -30,15 +32,21 @@ function secureExistingFile(path, invalidArtifact) {
         throw invalidArtifact();
     }
 }
-export function preparePrivateSqliteArtifact(path, invalidArtifact) {
+export function preparePrivateSqliteArtifact(path, invalidArtifact, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const windowsAccessControl = platform === "win32"
+        ? (options.windowsAccessControl ?? { secure: secureWindowsArtifactSync })
+        : undefined;
     const directoryPath = dirname(path);
     const initialDirectoryStats = lstatSync(directoryPath, { bigint: true });
     if (!initialDirectoryStats.isDirectory())
         throw invalidArtifact();
+    if (platform === "win32")
+        windowsAccessControl?.secure(directoryPath, "directory");
     let directoryDescriptor;
     let fileDescriptor;
     try {
-        if (POSIX) {
+        if (platform !== "win32") {
             directoryDescriptor = openSync(directoryPath, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
             const descriptorStats = fstatSync(directoryDescriptor, { bigint: true });
             const pathStats = lstatSync(directoryPath, { bigint: true });
@@ -53,10 +61,12 @@ export function preparePrivateSqliteArtifact(path, invalidArtifact) {
             fchmodSync(directoryDescriptor, 0o700);
         }
         for (const suffix of ["-wal", "-shm", "-journal"]) {
-            secureExistingFile(`${path}${suffix}`, invalidArtifact);
+            secureExistingFile(`${path}${suffix}`, invalidArtifact, platform, windowsAccessControl);
         }
+        let created = false;
         try {
             fileDescriptor = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR, 0o600);
+            created = true;
         }
         catch (error) {
             if (errorCode(error) !== "EEXIST")
@@ -64,8 +74,13 @@ export function preparePrivateSqliteArtifact(path, invalidArtifact) {
             const pathStats = lstatSync(path, { bigint: true });
             if (!pathStats.isFile() || pathStats.nlink !== 1n)
                 throw invalidArtifact();
-            fileDescriptor = openSync(path, constants.O_RDWR | constants.O_NOFOLLOW);
+            if (platform === "win32")
+                windowsAccessControl?.secure(path, "file");
+            const noFollow = platform === "win32" ? 0 : constants.O_NOFOLLOW;
+            fileDescriptor = openSync(path, constants.O_RDWR | noFollow);
         }
+        if (created && platform === "win32")
+            windowsAccessControl?.secure(path, "file");
         const validateDirectory = () => {
             const currentDirectoryStats = lstatSync(directoryPath, { bigint: true });
             const expectedDirectoryStats = directoryDescriptor === undefined
@@ -95,7 +110,7 @@ export function preparePrivateSqliteArtifact(path, invalidArtifact) {
             }
         };
         validate();
-        if (POSIX)
+        if (platform !== "win32")
             fchmodSync(fileDescriptor, 0o600);
         return {
             validate,

package/dist/sqlite-artifact.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-artifact.js","sourceRoot":"","sources":["../src/sqlite-artifact.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sqlite-artifact.js","sourceRoot":"","sources":["../src/sqlite-artifact.ts"],"names":[],"mappings":"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"}

package/dist/webhook-secret-store.d.ts

@@ -0,0 +1,16 @@
+import { type EncryptedFileCredentialStoreOptions } from "./credential-store.js";
+export interface WebhookSecretStore {
+    load(): Promise<string | undefined>;
+    createOrLoad(): Promise<string>;
+}
+export interface EncryptedFileWebhookSecretStoreOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly windowsAccessControl?: EncryptedFileCredentialStoreOptions["windowsAccessControl"];
+    readonly scope?: string;
+}
+export declare class EncryptedFileWebhookSecretStore implements WebhookSecretStore {
+    #private;
+    constructor(path: string, keyPath: string, options?: EncryptedFileWebhookSecretStoreOptions);
+    load(): Promise<string | undefined>;
+    createOrLoad(): Promise<string>;
+}

package/dist/webhook-secret-store.js

@@ -0,0 +1,49 @@
+import { randomBytes } from "node:crypto";
+import { resolve } from "node:path";
+import { EncryptedFileCredentialStore, } from "./credential-store.js";
+const SECRET = /^[a-f0-9]{48}$/u;
+const DEFAULT_SCOPE = '{"kind":"ambassador-webhook-secret","version":1}';
+const creations = new Map();
+function validateWebhookSecret(value) {
+    if (!SECRET.test(value))
+        throw new Error("The webhook secret store is invalid");
+}
+export class EncryptedFileWebhookSecretStore {
+    #path;
+    #store;
+    constructor(path, keyPath, options = {}) {
+        this.#path = resolve(path);
+        this.#store = new EncryptedFileCredentialStore(path, keyPath, options.scope ?? DEFAULT_SCOPE, {
+            ...(options.platform === undefined ? {} : { platform: options.platform }),
+            ...(options.windowsAccessControl === undefined
+                ? {}
+                : { windowsAccessControl: options.windowsAccessControl }),
+            validatePlaintext: validateWebhookSecret,
+        });
+    }
+    async load() {
+        return this.#store.load();
+    }
+    async createOrLoad() {
+        const existing = creations.get(this.#path);
+        if (existing !== undefined)
+            return existing;
+        const creation = this.#createOrLoad();
+        creations.set(this.#path, creation);
+        try {
+            return await creation;
+        }
+        finally {
+            creations.delete(this.#path);
+        }
+    }
+    async #createOrLoad() {
+        const stored = await this.#store.load();
+        if (stored !== undefined)
+            return stored;
+        const created = randomBytes(24).toString("hex");
+        await this.#store.save(created);
+        return created;
+    }
+}
+//# sourceMappingURL=webhook-secret-store.js.map

package/dist/webhook-secret-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-secret-store.js","sourceRoot":"","sources":["../src/webhook-secret-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EACL,4BAA4B,GAE7B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,MAAM,GAAG,iBAAiB,CAAC;AACjC,MAAM,aAAa,GAAG,kDAAkD,CAAC;AACzE,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;AAarD,SAAS,qBAAqB,CAAC,KAAa;IAC1C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,OAAO,+BAA+B;IACjC,KAAK,CAAS;IACd,MAAM,CAA+B;IAE9C,YAAY,IAAY,EAAE,OAAe,EAAE,OAAO,GAA2C,EAAE;QAC7F,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,IAAI,4BAA4B,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,IAAI,aAAa,EAAE;YAC5F,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;YACzE,GAAG,CAAC,OAAO,CAAC,oBAAoB,KAAK,SAAS;gBAC5C,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,EAAE,CAAC;YAC3D,iBAAiB,EAAE,qBAAqB;SACzC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI;QACR,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAC;QAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACtC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACpC,IAAI,CAAC;YACH,OAAO,MAAM,QAAQ,CAAC;QACxB,CAAC;gBAAS,CAAC;YACT,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,aAAa;QACjB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACxC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QACxC,MAAM,OAAO,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAChD,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

package/dist/windows-access-control.d.ts

@@ -0,0 +1,6 @@
+export type WindowsArtifactKind = "directory" | "file";
+export interface WindowsAccessControl {
+    secure(path: string, kind: WindowsArtifactKind): Promise<void>;
+}
+export declare function secureWindowsArtifact(path: string, kind: WindowsArtifactKind): Promise<void>;
+export declare function secureWindowsArtifactSync(path: string, kind: WindowsArtifactKind): void;

package/dist/windows-access-control.js

@@ -0,0 +1,161 @@
+import { execFile, execFileSync } from "node:child_process";
+import { win32 } from "node:path";
+const SYSTEM_SID = "S-1-5-18";
+const POWERSHELL_TIMEOUT_MS = 30_000;
+const WINDOWS_HELPER_ENVIRONMENT_NAMES = [
+    "SystemRoot",
+    "WINDIR",
+    "ComSpec",
+    "PATHEXT",
+    "PATH",
+    "TEMP",
+    "TMP",
+    "USERPROFILE",
+    "LOCALAPPDATA",
+    "APPDATA",
+    "PROGRAMDATA",
+];
+const WINDOWS_ACL_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+if ($args.Count -ne 0) { exit 41 }
+$target = [Environment]::GetEnvironmentVariable('AMBASSADOR_ACL_PATH', 'Process')
+$kind = [Environment]::GetEnvironmentVariable('AMBASSADOR_ACL_KIND', 'Process')
+if ([String]::IsNullOrEmpty($target)) { exit 42 }
+$attributes = [System.IO.File]::GetAttributes($target)
+if (($attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) { exit 43 }
+$isDirectory = ($attributes -band [System.IO.FileAttributes]::Directory) -ne 0
+if (($kind -eq 'directory') -ne $isDirectory) { exit 44 }
+if ($kind -ne 'directory' -and $kind -ne 'file') { exit 45 }
+$userIdentity = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$userSid = $userIdentity.Value
+$artifact = if ($isDirectory) {
+  [System.IO.DirectoryInfo]::new($target)
+} else {
+  [System.IO.FileInfo]::new($target)
+}
+$security = if ($isDirectory) {
+  [System.Security.AccessControl.DirectorySecurity]::new()
+} else {
+  [System.Security.AccessControl.FileSecurity]::new()
+}
+$security.SetOwner($userIdentity)
+$security.SetAccessRuleProtection($true, $false)
+$inheritance = if ($isDirectory) {
+  [System.Security.AccessControl.InheritanceFlags]'ContainerInherit,ObjectInherit'
+} else {
+  [System.Security.AccessControl.InheritanceFlags]::None
+}
+$expected = [System.Collections.Generic.HashSet[string]]::new(
+  [System.StringComparer]::OrdinalIgnoreCase
+)
+[void]$expected.Add($userSid)
+[void]$expected.Add('${SYSTEM_SID}')
+foreach ($sid in $expected) {
+  $identity = [System.Security.Principal.SecurityIdentifier]::new($sid)
+  $rule = [System.Security.AccessControl.FileSystemAccessRule]::new(
+    $identity,
+    [System.Security.AccessControl.FileSystemRights]::FullControl,
+    $inheritance,
+    [System.Security.AccessControl.PropagationFlags]::None,
+    [System.Security.AccessControl.AccessControlType]::Allow
+  )
+  [void]$security.AddAccessRule($rule)
+}
+$artifact.SetAccessControl($security)
+$actual = $artifact.GetAccessControl(
+  [System.Security.AccessControl.AccessControlSections]'Access,Owner'
+)
+if (-not $actual.AreAccessRulesProtected) { exit 46 }
+if ($actual.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $userSid) {
+  exit 47
+}
+$rules = @($actual.GetAccessRules(
+  $true,
+  $true,
+  [System.Security.Principal.SecurityIdentifier]
+))
+if ($rules.Count -ne $expected.Count) { exit 48 }
+foreach ($rule in $rules) {
+  if (-not $expected.Contains($rule.IdentityReference.Value)) { exit 49 }
+  if ($rule.IsInherited) { exit 50 }
+  if ($rule.AccessControlType -ne [System.Security.AccessControl.AccessControlType]::Allow) {
+    exit 51
+  }
+  if ([int]$rule.FileSystemRights -ne [int][System.Security.AccessControl.FileSystemRights]::FullControl) {
+    exit 52
+  }
+  if ($rule.InheritanceFlags -ne $inheritance) { exit 53 }
+  if ($rule.PropagationFlags -ne [System.Security.AccessControl.PropagationFlags]::None) {
+    exit 54
+  }
+}
+[Console]::Out.Write('AMBASSADOR_ACL_OK')
+`;
+function powershellExecutable() {
+    const systemRoot = process.env.SystemRoot;
+    if (systemRoot === undefined ||
+        !win32.isAbsolute(systemRoot) ||
+        systemRoot.includes("\u0000") ||
+        systemRoot.includes("\r") ||
+        systemRoot.includes("\n")) {
+        throw new Error("Windows state access control failed");
+    }
+    return win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+function helperEnvironment(path, kind) {
+    if (path.length < 1 || path.length > 32_768 || path.includes("\u0000")) {
+        throw new Error("Windows state access control failed");
+    }
+    const environment = {};
+    for (const name of WINDOWS_HELPER_ENVIRONMENT_NAMES) {
+        const value = process.env[name];
+        if (value !== undefined)
+            environment[name] = value;
+    }
+    environment.AMBASSADOR_ACL_PATH = path;
+    environment.AMBASSADOR_ACL_KIND = kind;
+    return environment;
+}
+function arguments_() {
+    return [
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-EncodedCommand",
+        Buffer.from(WINDOWS_ACL_SCRIPT, "utf16le").toString("base64"),
+    ];
+}
+function options(path, kind) {
+    return {
+        encoding: "utf8",
+        env: helperEnvironment(path, kind),
+        maxBuffer: 32 * 1024,
+        timeout: POWERSHELL_TIMEOUT_MS,
+        windowsHide: true,
+    };
+}
+export async function secureWindowsArtifact(path, kind) {
+    const output = await new Promise((resolve, reject) => {
+        execFile(powershellExecutable(), arguments_(), options(path, kind), (error, stdout, stderr) => {
+            if (error !== null || stderr.length !== 0 || stdout !== "AMBASSADOR_ACL_OK") {
+                reject(new Error("Windows state access control failed"));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+    if (output !== "AMBASSADOR_ACL_OK")
+        throw new Error("Windows state access control failed");
+}
+export function secureWindowsArtifactSync(path, kind) {
+    let output;
+    try {
+        output = execFileSync(powershellExecutable(), arguments_(), options(path, kind));
+    }
+    catch {
+        throw new Error("Windows state access control failed");
+    }
+    if (output !== "AMBASSADOR_ACL_OK")
+        throw new Error("Windows state access control failed");
+}
+//# sourceMappingURL=windows-access-control.js.map

package/dist/windows-access-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-access-control.js","sourceRoot":"","sources":["../src/windows-access-control.ts"],"names":[],"mappings":"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"}

package/docs/development-reset.md

@@ -0,0 +1,27 @@
+# Reset local test state
+
+This removes only local Ambassador test residue. It does not call the central
+service or delete a registered central identity.
+
+1. Stop `ambassador start`.
+2. Delete the complete Ambassador state directory for the test account:
+
+   | Platform | Default state directory |
+   | --- | --- |
+   | macOS | `~/Library/Application Support/ambassador` |
+   | Linux | `${XDG_STATE_HOME:-~/.local/state}/ambassador` |
+   | Windows | `%LOCALAPPDATA%\ambassador` |
+
+   The directory contains the encrypted central credential and key, encrypted
+   webhook secret and key, delivery profile, ID-only notification journal, and
+   process lock. Delete the directory only after checking the exact path.
+
+3. Remove any test-only Ambassador MCP entry, Hermes webhook route, or
+   OpenClaw plugin configuration that you created for the run. Do not remove
+   normal provider credentials.
+4. Start Ambassador again from the working directory you want the new direct
+   profile to use.
+
+Because this is a local-only reset, central still owns the old email identity.
+Use a new disposable email when repeating registration. A `409` for the old
+address is expected and is not fixed by deleting local files.

package/docs/getting-started-claude.md

@@ -3,9 +3,9 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Use Claude Code `2.1.257` or `2.1.258`.
-- For direct delivery, install `@agentclientprotocol/claude-agent-acp` `0.73.0`
-  so `claude-agent-acp` is on `PATH`.
+- Install Claude Code.
+- For direct delivery, install `@agentclientprotocol/claude-agent-acp` so
+  `claude-agent-acp` is on `PATH`.
 - Sign in to Claude Code normally. Ambassador never receives your Claude
   credential.
 
@@ -28,7 +28,9 @@
 Ambassador will launch `claude-agent-acp` when a central message arrives. That
 is a new gateway-managed session, not the chat used for registration.
 
-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
+Ambassador selects this profile by the exact known MCP client name, then tries
+the fixed `claude-agent-acp` ACP v1 contract. Reported client and adapter
+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.

package/docs/getting-started-codex.md

@@ -3,9 +3,9 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Use Codex `0.149.0` or `0.152.1`.
-- For direct delivery, install `@agentclientprotocol/codex-acp` `1.8.0` so
-  `codex-acp` is on `PATH`.
+- Install Codex.
+- For direct delivery, install `@agentclientprotocol/codex-acp` so `codex-acp`
+  is on `PATH`.
 - Sign in to Codex normally. Ambassador never receives your Codex credential.
 
 ## Set up direct delivery
@@ -31,7 +31,8 @@
 Ambassador will launch `codex-acp` when a central message arrives. That is a
 new gateway-managed session, not the chat used for registration.
 
-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
+Ambassador selects this profile by the exact known MCP client name, then tries
+the fixed `codex-acp` ACP v1 contract. Reported client and adapter 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.

package/docs/getting-started-gemini.md

@@ -3,7 +3,7 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Install and sign in to Gemini CLI `0.58.0`.
+- Install and sign in to Gemini CLI.
 - Gemini supplies native ACP through `gemini --acp`; no adapter is needed.
 - Ambassador never receives your Gemini or Google credential.
 
@@ -26,7 +26,8 @@
 Ambassador will launch `gemini --acp` when a central message arrives. That is
 a new gateway-managed session, not the chat used for registration.
 
-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
+Ambassador selects this profile by the exact known MCP client name, then tries
+the fixed `gemini --acp` ACP v1 contract. 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.

package/docs/getting-started-hermes.md

@@ -3,50 +3,101 @@
 ## Before you start
 
 - Install Node.js `>=24.19.0 <25`.
-- Install and authenticate Hermes Agent `0.20.5` or `0.21.0`.
+- Install and authenticate Hermes Agent.
 - Make sure `hermes-acp` is on `PATH` for direct delivery.
 - Ambassador never receives your provider credential.
 
-Hermes Agent `0.20.5` passed both live delivery modes and is included in
-Ambassador 0.2.8's direct profile. The qualification probe records the installed
-version without treating the observation itself as a failure.
-
 ## 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
+
+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.
 
-## Use a webhook instead
+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.
 
-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 the artifact-specific compatibility
-evidence.
+For local reruns, see [Reset local test state](development-reset.md).