@embassys/ambassador 0.0.0 → 0.2.7

package/dist/process-lock.js

@@ -0,0 +1,122 @@
+import { lstatSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import Database from "better-sqlite3";
+import { GatewayError } from "./errors.js";
+import { preparePrivateSqliteArtifact } from "./sqlite-artifact.js";
+const LOCK_HANDOFF_TIMEOUT_MS = 1_000;
+const activeLockKeys = new Set();
+const pendingLockPaths = new Set();
+function errorCode(error) {
+    if (error !== null && typeof error === "object" && "code" in error) {
+        return typeof error.code === "string" ? error.code : undefined;
+    }
+    return undefined;
+}
+function invalidLockArtifact() {
+    return new GatewayError("lock_invalid", "The Ambassador lock artifact is invalid", 7);
+}
+function daemonRunning() {
+    return new GatewayError("daemon_running", "Ambassador is already running", 7);
+}
+function pathKey(path) {
+    return process.platform === "win32" ? path.toLowerCase() : path;
+}
+function filesystemLockKey(path) {
+    try {
+        const stats = lstatSync(path, { bigint: true });
+        return `artifact:${stats.dev}:${stats.ino}`;
+    }
+    catch (error) {
+        if (errorCode(error) !== "ENOENT")
+            throw error;
+        const parentStats = lstatSync(dirname(path), { bigint: true });
+        return `new:${parentStats.dev}:${parentStats.ino}:${pathKey(basename(path))}`;
+    }
+}
+export class ProcessLock {
+    database;
+    keys;
+    released = false;
+    constructor(database, keys) {
+        this.database = database;
+        this.keys = keys;
+    }
+    static async acquire(path) {
+        const artifactPath = resolve(path);
+        const pendingPath = pathKey(artifactPath);
+        if (pendingLockPaths.has(pendingPath))
+            throw daemonRunning();
+        pendingLockPaths.add(pendingPath);
+        const keys = [];
+        try {
+            await mkdir(dirname(artifactPath), { recursive: true, mode: 0o700 });
+            const initialKey = filesystemLockKey(artifactPath);
+            if (activeLockKeys.has(initialKey))
+                throw daemonRunning();
+            activeLockKeys.add(initialKey);
+            keys.push(initialKey);
+            pendingLockPaths.delete(pendingPath);
+            const artifact = preparePrivateSqliteArtifact(artifactPath, invalidLockArtifact);
+            let database;
+            try {
+                const artifactKey = filesystemLockKey(artifactPath);
+                if (artifactKey !== initialKey) {
+                    if (activeLockKeys.has(artifactKey))
+                        throw daemonRunning();
+                    activeLockKeys.add(artifactKey);
+                    keys.push(artifactKey);
+                }
+                database = new Database(artifactPath, { timeout: LOCK_HANDOFF_TIMEOUT_MS });
+                artifact.validate();
+                // Closing another descriptor for this inode after BEGIN can release POSIX process locks.
+                artifact.releaseFile();
+                database.pragma(`busy_timeout = ${LOCK_HANDOFF_TIMEOUT_MS}`);
+                database.pragma("trusted_schema = OFF");
+                database.exec("BEGIN EXCLUSIVE");
+                artifact.validateDirectory();
+                return new ProcessLock(database, keys);
+            }
+            catch (error) {
+                database?.close();
+                const code = errorCode(error);
+                if (code?.startsWith("SQLITE_BUSY"))
+                    throw daemonRunning();
+                if (code === "SQLITE_NOTADB" || code === "SQLITE_FORMAT" || code === "SQLITE_CORRUPT") {
+                    throw invalidLockArtifact();
+                }
+                throw error;
+            }
+            finally {
+                artifact.close();
+            }
+        }
+        catch (error) {
+            pendingLockPaths.delete(pendingPath);
+            for (const key of keys)
+                activeLockKeys.delete(key);
+            if (errorCode(error) === "ENOENT" && keys.some((key) => key.startsWith("artifact:"))) {
+                throw daemonRunning();
+            }
+            throw error;
+        }
+    }
+    async release() {
+        if (this.released)
+            return;
+        this.released = true;
+        try {
+            this.database.exec("ROLLBACK");
+        }
+        finally {
+            try {
+                this.database.close();
+            }
+            finally {
+                for (const key of this.keys)
+                    activeLockKeys.delete(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=process-lock.js.map

package/dist/process-lock.js.map

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

package/dist/sqlite-artifact.d.ts

@@ -0,0 +1,7 @@
+export interface PreparedSqliteArtifact {
+    validate: () => void;
+    validateDirectory: () => void;
+    releaseFile: () => void;
+    close: () => void;
+}
+export declare function preparePrivateSqliteArtifact(path: string, invalidArtifact: () => Error): PreparedSqliteArtifact;

package/dist/sqlite-artifact.js

@@ -0,0 +1,121 @@
+import { chmodSync, closeSync, constants, fchmodSync, fstatSync, lstatSync, openSync, } from "node:fs";
+import { dirname } from "node:path";
+const POSIX = process.platform !== "win32";
+function errorCode(error) {
+    return error !== null && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function sameArtifact(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function secureExistingFile(path, invalidArtifact) {
+    let pathStats;
+    try {
+        pathStats = lstatSync(path, { bigint: true });
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return;
+        throw error;
+    }
+    if (!pathStats.isFile() || pathStats.nlink !== 1n)
+        throw invalidArtifact();
+    if (POSIX)
+        chmodSync(path, 0o600);
+    const currentStats = lstatSync(path, { bigint: true });
+    if (!currentStats.isFile() ||
+        currentStats.nlink !== 1n ||
+        !sameArtifact(pathStats, currentStats)) {
+        throw invalidArtifact();
+    }
+}
+export function preparePrivateSqliteArtifact(path, invalidArtifact) {
+    const directoryPath = dirname(path);
+    const initialDirectoryStats = lstatSync(directoryPath, { bigint: true });
+    if (!initialDirectoryStats.isDirectory())
+        throw invalidArtifact();
+    let directoryDescriptor;
+    let fileDescriptor;
+    try {
+        if (POSIX) {
+            directoryDescriptor = openSync(directoryPath, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+            const descriptorStats = fstatSync(directoryDescriptor, { bigint: true });
+            const pathStats = lstatSync(directoryPath, { bigint: true });
+            if (!descriptorStats.isDirectory() || !pathStats.isDirectory())
+                throw invalidArtifact();
+            if (!sameArtifact(descriptorStats, pathStats))
+                throw invalidArtifact();
+            if (typeof process.getuid === "function" &&
+                descriptorStats.uid !== BigInt(process.getuid())) {
+                throw invalidArtifact();
+            }
+            fchmodSync(directoryDescriptor, 0o700);
+        }
+        for (const suffix of ["-wal", "-shm", "-journal"]) {
+            secureExistingFile(`${path}${suffix}`, invalidArtifact);
+        }
+        try {
+            fileDescriptor = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR, 0o600);
+        }
+        catch (error) {
+            if (errorCode(error) !== "EEXIST")
+                throw error;
+            const pathStats = lstatSync(path, { bigint: true });
+            if (!pathStats.isFile() || pathStats.nlink !== 1n)
+                throw invalidArtifact();
+            fileDescriptor = openSync(path, constants.O_RDWR | constants.O_NOFOLLOW);
+        }
+        const validateDirectory = () => {
+            const currentDirectoryStats = lstatSync(directoryPath, { bigint: true });
+            const expectedDirectoryStats = directoryDescriptor === undefined
+                ? initialDirectoryStats
+                : fstatSync(directoryDescriptor, { bigint: true });
+            if (!currentDirectoryStats.isDirectory() ||
+                !sameArtifact(expectedDirectoryStats, currentDirectoryStats)) {
+                throw invalidArtifact();
+            }
+        };
+        const validate = () => {
+            const descriptorStats = fstatSync(fileDescriptor, { bigint: true });
+            const pathStats = lstatSync(path, { bigint: true });
+            if (!descriptorStats.isFile() ||
+                !pathStats.isFile() ||
+                descriptorStats.nlink !== 1n ||
+                pathStats.nlink !== 1n ||
+                !sameArtifact(descriptorStats, pathStats)) {
+                throw invalidArtifact();
+            }
+            validateDirectory();
+        };
+        const releaseFile = () => {
+            if (fileDescriptor !== undefined) {
+                closeSync(fileDescriptor);
+                fileDescriptor = undefined;
+            }
+        };
+        validate();
+        if (POSIX)
+            fchmodSync(fileDescriptor, 0o600);
+        return {
+            validate,
+            validateDirectory,
+            releaseFile,
+            close: () => {
+                releaseFile();
+                if (directoryDescriptor !== undefined) {
+                    closeSync(directoryDescriptor);
+                    directoryDescriptor = undefined;
+                }
+            },
+        };
+    }
+    catch (error) {
+        if (fileDescriptor !== undefined)
+            closeSync(fileDescriptor);
+        if (directoryDescriptor !== undefined)
+            closeSync(directoryDescriptor);
+        throw error;
+    }
+}
+//# sourceMappingURL=sqlite-artifact.js.map

package/dist/sqlite-artifact.js.map

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

package/dist/webhook-delivery.d.ts

@@ -0,0 +1,23 @@
+import type { CentralMessage } from "./central-rest.js";
+export type WebhookDeliveryErrorCode = "delivery_failed" | "invalid_configuration";
+export declare class WebhookDeliveryError extends Error {
+    readonly code: WebhookDeliveryErrorCode;
+    constructor(code: WebhookDeliveryErrorCode);
+}
+export interface WebhookDeliveryTargetOptions {
+    readonly url: string;
+    readonly secret: string;
+    readonly fetch?: typeof fetch;
+    readonly now?: () => number;
+    readonly deadlineMs?: number;
+    readonly maximumAttempts?: number;
+    readonly retryDelayMs?: number;
+}
+export declare class WebhookDeliveryTarget {
+    #private;
+    constructor(options: WebhookDeliveryTargetOptions);
+    deliver(message: CentralMessage, signal: AbortSignal): Promise<{
+        readonly status: "accepted";
+    }>;
+    close(): Promise<void>;
+}

package/dist/webhook-delivery.js

@@ -0,0 +1,122 @@
+import { createHmac, randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { canonicalWebhookUrl } from "./delivery-profile.js";
+const DEFAULT_DEADLINE_MS = 10_000;
+const DEFAULT_MAXIMUM_ATTEMPTS = 3;
+const DEFAULT_RETRY_DELAY_MS = 250;
+const MAX_MESSAGE_BYTES = 512 * 1024;
+export class WebhookDeliveryError extends Error {
+    code;
+    constructor(code) {
+        super("Webhook delivery failed");
+        this.code = code;
+        this.name = "WebhookDeliveryError";
+    }
+}
+function positiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
+async function cancel(response) {
+    await response.body?.cancel().catch(() => undefined);
+}
+export class WebhookDeliveryTarget {
+    #url;
+    #secret;
+    #authorization;
+    #fetch;
+    #now;
+    #deadlineMs;
+    #maximumAttempts;
+    #retryDelayMs;
+    #lifetime = new AbortController();
+    constructor(options) {
+        try {
+            this.#url = canonicalWebhookUrl(options.url);
+        }
+        catch {
+            throw new WebhookDeliveryError("invalid_configuration");
+        }
+        if (!/^[\x21-\x7e]{32,256}$/u.test(options.secret)) {
+            throw new WebhookDeliveryError("invalid_configuration");
+        }
+        this.#secret = options.secret;
+        this.#authorization = `Bearer ${options.secret}`;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#now = options.now ?? Date.now;
+        this.#deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS;
+        this.#maximumAttempts = options.maximumAttempts ?? DEFAULT_MAXIMUM_ATTEMPTS;
+        this.#retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+        if (!positiveInteger(this.#deadlineMs) ||
+            !positiveInteger(this.#maximumAttempts) ||
+            !positiveInteger(this.#retryDelayMs)) {
+            throw new WebhookDeliveryError("invalid_configuration");
+        }
+    }
+    async deliver(message, signal) {
+        let body;
+        try {
+            body = JSON.stringify(message);
+        }
+        catch {
+            throw new WebhookDeliveryError("delivery_failed");
+        }
+        if (Buffer.byteLength(body, "utf8") > MAX_MESSAGE_BYTES) {
+            throw new WebhookDeliveryError("delivery_failed");
+        }
+        const requestId = message.id ?? randomUUID();
+        const deadline = AbortSignal.timeout(this.#deadlineMs);
+        const requestSignal = AbortSignal.any([signal, deadline, this.#lifetime.signal]);
+        for (let attempt = 1; attempt <= this.#maximumAttempts; attempt += 1) {
+            if (requestSignal.aborted)
+                throw new WebhookDeliveryError("delivery_failed");
+            const now = this.#now();
+            if (!Number.isSafeInteger(now) || now < 0) {
+                throw new WebhookDeliveryError("invalid_configuration");
+            }
+            const timestamp = String(Math.floor(now / 1_000));
+            const signature = createHmac("sha256", this.#secret)
+                .update(timestamp, "ascii")
+                .update(".", "ascii")
+                .update(body, "utf8")
+                .digest("hex");
+            try {
+                const response = await this.#fetch(this.#url, {
+                    method: "POST",
+                    headers: {
+                        authorization: this.#authorization,
+                        "content-type": "application/json",
+                        "idempotency-key": requestId,
+                        "x-request-id": requestId,
+                        "x-webhook-timestamp": timestamp,
+                        "x-webhook-signature-v2": signature,
+                    },
+                    body,
+                    credentials: "omit",
+                    redirect: "manual",
+                    signal: requestSignal,
+                });
+                const accepted = response.status >= 200 && response.status < 300;
+                await cancel(response);
+                if (accepted)
+                    return { status: "accepted" };
+            }
+            catch {
+                if (requestSignal.aborted)
+                    throw new WebhookDeliveryError("delivery_failed");
+            }
+            if (attempt < this.#maximumAttempts) {
+                try {
+                    await delay(this.#retryDelayMs, undefined, { signal: requestSignal });
+                }
+                catch {
+                    throw new WebhookDeliveryError("delivery_failed");
+                }
+            }
+        }
+        throw new WebhookDeliveryError("delivery_failed");
+    }
+    async close() {
+        this.#lifetime.abort();
+    }
+}
+//# sourceMappingURL=webhook-delivery.js.map

package/dist/webhook-delivery.js.map

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

package/docs/getting-started-claude.md

@@ -0,0 +1,33 @@
+# Get started with Claude Code
+
+## 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`.
+- Sign in to Claude Code normally. Ambassador never receives your Claude
+  credential.
+
+## Set up direct delivery
+
+1. From the directory Claude Code may access, keep Ambassador running:
+
+   ```sh
+   npx --yes @embassys/ambassador@0.2.7 start
+   ```
+
+2. Add `http://127.0.0.1:8787/mcp` as a Streamable HTTP MCP server in Claude
+   Code's normal MCP configuration. Do not configure authentication.
+3. Start or restart Claude Code so it sees the MCP server.
+4. Ask Claude Code to register your email; it calls Ambassador's
+   `register_agent` tool.
+5. Enter the six-digit code sent to your email. Claude Code is direct-only, so
+   Ambassador does not ask a delivery question.
+
+Ambassador will launch `claude-agent-acp` when a central message arrives. That
+is a new gateway-managed session, not the chat used for registration.
+
+Only the exact versions above are enabled. Other versions fail closed until
+their capability profile is reviewed. See [Qualification](qualification.md)
+for compatibility evidence.

package/docs/getting-started-codex.md

@@ -0,0 +1,36 @@
+# Get started with Codex
+
+## 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`.
+- Sign in to Codex normally. Ambassador never receives your Codex credential.
+
+## Set up direct delivery
+
+1. From the directory Codex may access, keep Ambassador running:
+
+   ```sh
+   npx --yes @embassys/ambassador@0.2.7 start
+   ```
+
+2. In another terminal, add its token-free local MCP endpoint:
+
+   ```sh
+   codex mcp add ambassador --url http://127.0.0.1:8787/mcp
+   ```
+
+3. Start or restart Codex so it sees the MCP server.
+4. Ask Codex to register your email; it calls Ambassador's `register_agent`
+   tool.
+5. Enter the six-digit code sent to your email. Codex is direct-only, so
+   Ambassador does not ask a delivery question.
+
+Ambassador will launch `codex-acp` when a central message arrives. That is a
+new gateway-managed session, not the chat used for registration.
+
+Only the exact versions above are enabled. Other versions fail closed until
+their capability profile is reviewed. See [Qualification](qualification.md)
+for compatibility evidence.

package/docs/getting-started-gemini.md

@@ -0,0 +1,31 @@
+# Get started with Gemini CLI
+
+## Before you start
+
+- 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.
+
+## Set up direct delivery
+
+1. From the directory Gemini CLI may access, keep Ambassador running:
+
+   ```sh
+   npx --yes @embassys/ambassador@0.2.7 start
+   ```
+
+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.
+
+Ambassador will launch `gemini --acp` when a central message arrives. That is
+a new gateway-managed session, not the chat used for registration.
+
+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

@@ -0,0 +1,47 @@
+# Get started with Hermes Agent
+
+## Before you start
+
+- 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.
+
+## Set up direct delivery
+
+1. From the directory Hermes may access, keep Ambassador running:
+
+   ```sh
+   npx --yes @embassys/ambassador@0.2.7 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.
+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.
+
+Ambassador will launch `hermes-acp` when a central message arrives. That is a
+new gateway-managed session, not the chat used for registration.
+
+## 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 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.
+
+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

@@ -0,0 +1,48 @@
+# Get started with OpenClaw
+
+## Before you start
+
+- 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.
+
+## Set up direct delivery
+
+1. From the directory OpenClaw may access, keep Ambassador running:
+
+   ```sh
+   npx --yes @embassys/ambassador@0.2.7 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.
+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.