@paybond/kit 0.11.5 → 0.11.7

package/dist/cli/commands/setup.js

@@ -7,7 +7,8 @@ import { assertApiKeyShape, resolveApiKey, resolvedDefaultsForDoctor } from "../
 import { runAgentMiddlewareDoctorCheck } from "../doctor-agent-middleware.js";
 import { packageVersion, runAgentMcpChecks } from "../doctor-agent.js";
 import { runCompletionCatalogDoctorChecks } from "../../doctor-completion.js";
-import { consumeBooleanFlag, consumeFlag } from "../globals.js";
+import { consumeBooleanFlag, consumeFlag, parseCliArgv } from "../globals.js";
+import { helpForCommand } from "../help.js";
 import { maskApiKey, redactConfigValue } from "../redact.js";
 import { mergeMcpToolPolicy, parseMcpToolAllowlist, parseMcpToolPolicy, resolveMcpToolPolicy, } from "../mcp-policy.js";
 import { parseMcpInstallFormat, parseMcpInstallHost, parseMcpInstallScope, planMcpInstall, } from "../mcp-install.js";
@@ -197,16 +198,48 @@ export async function handleInitCompletion(ctx, argv) {
         },
     };
 }
-export async function handleMcpServe(ctx, argv) {
-    if (argv.length > 0 && argv[0] !== "--help" && argv[0] !== "-h") {
-        throw new CliError(`unexpected arguments: ${argv.join(" ")}`, { category: "usage", code: "cli.usage.unexpected_args" });
+export function mcpServeArgvMatches(argv) {
+    try {
+        const { command } = parseCliArgv(argv);
+        return command.length >= 2 && command[0] === "mcp" && command[1] === "serve";
     }
-    ctx.stderr.write("Starting Paybond MCP stdio server (stdout is reserved for MCP JSON-RPC).\n");
-    const code = runMcpServerMain([]);
-    if (code !== 0) {
-        throw new CliError("mcp serve failed", { category: "internal", code: "cli.mcp.serve_failed", exitCode: code });
+    catch {
+        return false;
+    }
+}
+function isMcpServeHelpCommand(command) {
+    return command.length === 0 || command.includes("--help") || command.includes("-h");
+}
+/** Run the blocking MCP stdio server. Must not run through the async CLI dispatcher. */
+export function runMcpServeCommandSync(argv, writers) {
+    let command;
+    try {
+        ({ command } = parseCliArgv(argv));
     }
-    return { data: { started: true } };
+    catch (err) {
+        const message = err instanceof CliError ? err.message : String(err);
+        writers.stderr.write(`${message}\n`);
+        return err instanceof CliError ? err.exitCode : 1;
+    }
+    if (isMcpServeHelpCommand(command)) {
+        const helpPath = command.filter((part) => part !== "--help" && part !== "-h").join(" ") || "mcp serve";
+        writers.stdout.write(`${helpForCommand(helpPath)}\n`);
+        return 0;
+    }
+    const rest = command.slice(2);
+    if (rest.length > 0 && rest[0] !== "--help" && rest[0] !== "-h") {
+        writers.stderr.write(`unexpected arguments: ${rest.join(" ")}\n`);
+        return 2;
+    }
+    writers.stderr.write("Starting Paybond MCP stdio server (stdout is reserved for MCP JSON-RPC).\n");
+    const code = runMcpServerMain([]);
+    return code;
+}
+export async function handleMcpServe(_ctx, _argv) {
+    throw new CliError("mcp serve must run via the sync CLI entrypoint (not the async dispatcher)", {
+        category: "internal",
+        code: "cli.mcp.serve_async_forbidden",
+    });
 }
 export async function handleMcpTools(ctx) {
     const server = new PaybondMCPServer({ gatewayBaseUrl: ctx.globals.gateway, apiKey: "paybond_sk_sandbox_redacted_redacted_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" });

package/dist/cli/help.js

@@ -68,6 +68,8 @@ export const COMMAND_HELP = {
     "agent tool validate": "Usage: paybond agent tool validate --run-id <id> --operation <name> [--requested-spend-cents <n>] [--arguments <json>]\n\nAuthorize-only dry run (no execute, no evidence). Useful for agents checking budget before side effects.\n\nExamples:\n  $ paybond agent tool validate --run-id run-123 --operation travel.book_hotel --requested-spend-cents 18700 --format json\n\nDocs: https://docs.paybond.ai/kit/agent-middleware",
     "agent registry validate": "Usage: paybond agent registry validate --file <path>\n\nValidate a registry YAML/JSON file before bind (evidence_preset required on side-effecting tools).\n\nExamples:\n  $ paybond agent registry validate --file ./paybond.agent.registry.yaml --format json\n\nDocs: https://docs.paybond.ai/kit/agent-middleware",
     "agent sandbox smoke": "Usage: paybond agent sandbox smoke [--production] [--preset <id> | --policy-file <path> [--operation <name>] [--requested-spend-cents <n>]] | (--operation <name> --requested-spend-cents <n> --evidence-preset <id>) --result-body <json>|--result-file <path>\n\nOne-shot end-to-end sandbox lifecycle: bind, tool execute, combined result. With --policy-file, completion_preset is derived from each tool's evidence_preset in YAML — do not pass --evidence-preset (Gateway rejects conflicting bootstrap fields).\n\nExamples:\n  $ paybond agent sandbox smoke --preset travel --result-body '{\"status\":\"completed\",\"cost_cents\":18700}' --format json\n  $ paybond agent sandbox smoke --policy-file paybond.policy.yaml --result-body '{\"status\":\"completed\",\"cost_cents\":18700}' --format json\n  $ paybond agent sandbox smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --result-body '{\"status\":\"ok\",\"cost_cents\":100}' --format json\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent",
+    "agent production attach smoke": "Usage: paybond agent production attach smoke --attach-intent-id <id> --capability-token <token> --operation <name> [--requested-spend-cents <n>] [--policy-file <path>] [--payee-did <did> --payee-signing-seed-hex <hex> --agent-recognition-key-id <id> --agent-recognition-signing-seed-hex <hex>] --result-body <json>|--result-file <path>\n\nOne-shot production attach lifecycle against live /harbor/* with agent recognition proofs: bind an existing funded intent, execute a guarded tool, and submit Kit-signed payee evidence. Requires production credentials (flags or PAYBOND_ATTACH_INTENT_ID, PAYBOND_CAPABILITY_TOKEN, APP_PAYEE_*, APP_AGENT_RECOGNITION_*). Not a substitute for sandbox smoke — run in staging before production attach rollouts.\n\nExamples:\n  $ paybond agent production attach smoke --attach-intent-id <intent-id> --capability-token <token> --operation paid-tool --requested-spend-cents 100 --result-body '{\"status\":\"ok\",\"cost_cents\":100}' --format json\n\nDocs: https://docs.paybond.ai/kit/production-attach",
+    "agent harbor evidence smoke": "Usage: paybond agent harbor evidence smoke --intent-id <id> [--payee-did <did> --payee-signing-seed-hex <hex> --agent-recognition-key-id <id> --agent-recognition-signing-seed-hex <hex>] [--idempotency-key <key>] --result-body <json>|--result-file <path>\n\nSingle POST /harbor/intents/{id}/evidence with Kit-signed payee evidence and agent recognition proof. Use in staging with Harbor SEC-003 enforcement on to confirm gateway proxy + Harbor nonce semantics (no double-claim replay). Requires a funded intent not yet in evidence_submitted state.\n\nExamples:\n  $ paybond agent harbor evidence smoke --intent-id <intent-id> --result-body '{\"status\":\"ok\",\"cost_cents\":100}' --format json\n\nDocs: https://docs.paybond.ai/kit/production-attach",
     "agent demo vercel-ai smoke": "Usage: paybond agent demo vercel-ai smoke [--production] --operation <name> --requested-spend-cents <n> --evidence-preset <id>\n\nBundled no-LLM Vercel AI SDK sandbox demo: toolApproval, wrapped execute, and auto-evidence via MockLanguageModelV4.\n\nExamples:\n  $ paybond agent demo vercel-ai smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json\n\nDocs: https://docs.paybond.ai/kit/vercel-ai",
     "agent demo langgraph smoke": "Usage: paybond agent demo langgraph smoke [--production] [--runtime typescript|python] --operation <name> --requested-spend-cents <n> --evidence-preset <id>\n\nBundled no-LLM LangGraph sandbox demo: ToolNode interceptor, authorize, execute, and auto-evidence.\n\nExamples:\n  $ paybond agent demo langgraph smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json\n\nDocs: https://docs.paybond.ai/kit/langgraph",
     "agent demo generic smoke": "Usage: paybond agent demo generic smoke [--production] [--runtime typescript|python] --operation <name> --requested-spend-cents <n> --evidence-preset <id>\n\nBundled no-LLM agent-agnostic sandbox demo: createPaybondGenericAgentConfig, wrapped execute, and auto-evidence.\n\nExamples:\n  $ paybond agent demo generic smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json\n\nDocs: https://docs.paybond.ai/kit/agent-agnostic",

package/dist/cli/http-error-message.d.ts

@@ -0,0 +1,18 @@
+import type { CliErrorDetails } from "./types.js";
+/**
+ * Summarize an HTTP error body for operator-facing CLI output.
+ * Never includes raw edge payloads (Cloudflare ray IDs, zones, HTML, etc.).
+ */
+export declare function summarizeGatewayHttpError(statusCode: number, bodyText: string): {
+    message: string;
+    details: CliErrorDetails;
+};
+/**
+ * Build a CLI-safe message for SDK HTTP failures that embed raw bodies in `.message`.
+ */
+export declare function formatSdkHttpErrorMessage(rawMessage: string, statusCode: number, bodyText: string): string;
+/**
+ * Resolve a CLI-safe gateway error message from SDK or agent middleware failures.
+ * Never echoes Cloudflare edge JSON, HTML, or raw upstream bodies.
+ */
+export declare function resolveCliGatewayErrorMessage(err: unknown): string;

package/dist/cli/http-error-message.js

@@ -0,0 +1,148 @@
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Summarize an HTTP error body for operator-facing CLI output.
+ * Never includes raw edge payloads (Cloudflare ray IDs, zones, HTML, etc.).
+ */
+export function summarizeGatewayHttpError(statusCode, bodyText) {
+    const trimmed = bodyText.trim();
+    if (!trimmed) {
+        return {
+            message: `Gateway HTTP ${statusCode}`,
+            details: { gateway_status: statusCode },
+        };
+    }
+    try {
+        const body = JSON.parse(trimmed);
+        if (body.cloudflare_error === true) {
+            const retryAfter = typeof body.retry_after === "number" ? body.retry_after : undefined;
+            const title = typeof body.title === "string"
+                ? body.title.replace(/^Error \d+:\s*/i, "")
+                : "service temporarily unavailable";
+            let message = `Gateway unavailable (HTTP ${statusCode}): ${title}`;
+            if (retryAfter !== undefined) {
+                message += `. Retry after ${retryAfter} seconds.`;
+            }
+            return {
+                message,
+                details: {
+                    gateway_status: statusCode,
+                    ...(retryAfter !== undefined ? { retry_after: retryAfter } : {}),
+                },
+            };
+        }
+        const nested = asRecord(body.error);
+        if (nested) {
+            const gatewayCode = typeof nested.code === "string" ? nested.code : String(nested.code ?? "");
+            const gatewayMessage = typeof nested.message === "string" ? nested.message : "";
+            if (gatewayMessage) {
+                return {
+                    message: gatewayMessage,
+                    details: {
+                        gateway_status: statusCode,
+                        ...(gatewayCode ? { gateway_code: gatewayCode } : {}),
+                    },
+                };
+            }
+        }
+        const flatMessage = typeof body.message === "string" ? body.message : "";
+        if (flatMessage) {
+            const gatewayCode = typeof body.code === "string" ? body.code : "";
+            return {
+                message: flatMessage,
+                details: {
+                    gateway_status: statusCode,
+                    ...(gatewayCode ? { gateway_code: gatewayCode } : {}),
+                },
+            };
+        }
+        if (typeof body.title === "string") {
+            const detail = typeof body.detail === "string" ? body.detail : "";
+            const combined = detail ? `${body.title}: ${detail}` : body.title;
+            const message = combined.length > 240 ? `${combined.slice(0, 237)}...` : combined;
+            return {
+                message,
+                details: { gateway_status: statusCode },
+            };
+        }
+    }
+    catch {
+        // Non-JSON bodies must not be echoed (HTML, stack traces, etc.).
+    }
+    return {
+        message: `Gateway HTTP ${statusCode}`,
+        details: { gateway_status: statusCode },
+    };
+}
+/**
+ * Build a CLI-safe message for SDK HTTP failures that embed raw bodies in `.message`.
+ */
+export function formatSdkHttpErrorMessage(rawMessage, statusCode, bodyText) {
+    const operation = rawMessage.replace(/ HTTP \d+:[\s\S]*$/u, "").trim() || "Gateway request";
+    const summary = summarizeGatewayHttpError(statusCode, bodyText);
+    if (summary.message === `Gateway HTTP ${statusCode}`) {
+        return `${operation} HTTP ${statusCode}`;
+    }
+    if (summary.message.startsWith("Gateway unavailable")) {
+        return `${operation}: ${summary.message}`;
+    }
+    return `${operation} HTTP ${statusCode}: ${summary.message}`;
+}
+function isSdkHttpErrorLike(err) {
+    if (!err || typeof err !== "object") {
+        return false;
+    }
+    const candidate = err;
+    return (typeof candidate.message === "string" &&
+        typeof candidate.statusCode === "number" &&
+        typeof candidate.bodyText === "string");
+}
+function parseEmbeddedHttpErrorBody(message) {
+    const match = / HTTP (\d{3}):\s*(\{[\s\S]*\})\s*$/u.exec(message);
+    if (!match) {
+        return undefined;
+    }
+    return {
+        statusCode: Number(match[1]),
+        bodyText: match[2] ?? "",
+    };
+}
+function extractSdkHttpError(err) {
+    const chain = [];
+    let current = err;
+    while (current) {
+        chain.push(current);
+        current =
+            current instanceof Error && "cause" in current
+                ? current.cause
+                : undefined;
+    }
+    for (const item of chain) {
+        if (isSdkHttpErrorLike(item)) {
+            return item;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve a CLI-safe gateway error message from SDK or agent middleware failures.
+ * Never echoes Cloudflare edge JSON, HTML, or raw upstream bodies.
+ */
+export function resolveCliGatewayErrorMessage(err) {
+    const sdkError = extractSdkHttpError(err);
+    if (sdkError) {
+        return formatSdkHttpErrorMessage(sdkError.message, sdkError.statusCode, sdkError.bodyText);
+    }
+    if (err instanceof Error) {
+        const embedded = parseEmbeddedHttpErrorBody(err.message);
+        if (embedded) {
+            const operation = err.message.replace(/ HTTP \d{3}:[\s\S]*$/u, "").trim() || "Gateway request";
+            return formatSdkHttpErrorMessage(operation, embedded.statusCode, embedded.bodyText);
+        }
+        return err.message;
+    }
+    return String(err);
+}

package/dist/cli/offline-session.d.ts

@@ -0,0 +1,9 @@
+import type { CliContext } from "./context.js";
+export type OfflineDevSession = {
+    ctx: CliContext;
+    restore: () => void;
+};
+/** Reject offline mode when production credentials are present in env or env file. */
+export declare function assertOfflineDevCredentialsSafe(ctx: CliContext): Promise<void>;
+/** Patch ctx.fetch with the in-process offline Gateway mock. */
+export declare function beginOfflineDevSession(ctx: CliContext): OfflineDevSession;

package/dist/cli/offline-session.js

@@ -0,0 +1,33 @@
+import { activateOfflineDevMode, createOfflineDevGatewayFetch, isProductionApiKey, } from "../dev/offline-gateway.js";
+import { loadEnvFile } from "./credentials.js";
+import { CliError } from "./types.js";
+function rejectOfflineWithProductionKey(apiKey) {
+    const trimmed = apiKey?.trim();
+    if (trimmed && isProductionApiKey(trimmed)) {
+        throw new CliError("offline dev mode cannot be used with production API keys (paybond_sk_live_...); unset PAYBOND_API_KEY or use a sandbox key", {
+            category: "validation",
+            code: "cli.dev.offline_production_key",
+            exitCode: 1,
+        });
+    }
+}
+/** Reject offline mode when production credentials are present in env or env file. */
+export async function assertOfflineDevCredentialsSafe(ctx) {
+    rejectOfflineWithProductionKey(process.env.PAYBOND_API_KEY);
+    if (process.env.PAYBOND_API_KEY?.trim()) {
+        return;
+    }
+    const fromFile = await loadEnvFile(ctx.globals.envFile, ctx.cwd);
+    rejectOfflineWithProductionKey(fromFile);
+}
+/** Patch ctx.fetch with the in-process offline Gateway mock. */
+export function beginOfflineDevSession(ctx) {
+    const { restore } = activateOfflineDevMode();
+    return {
+        ctx: {
+            ...ctx,
+            fetch: createOfflineDevGatewayFetch(),
+        },
+        restore,
+    };
+}

package/dist/cli/router.js

@@ -1,4 +1,6 @@
+import { HarborHttpError, SignalHttpError } from "../index.js";
 import { commandPath, createContext } from "./context.js";
+import { formatSdkHttpErrorMessage, summarizeGatewayHttpError } from "./http-error-message.js";
 import { handleA2a, handleAuditExports, handleMandates, handleReceipts, handleSignal, } from "./commands/discovery.js";
 import { handleConfig, handleDoctor, handleDiagnose, handleInitCompletion, handleInitAgentMiddleware, handleInitGuardrail, handleInitWizard, handleLogin, handleMcpInstall, handleMcpServe, handleMcpTools, handleMcpVerifyConfig, handleVersion, handleWhoami, } from "./commands/setup.js";
 import { handlePolicyExtend, handlePolicyImportMcpReceipt, handlePolicyImportX402Receipt, handlePolicyInit, handlePolicyInitOrg, handlePolicyPresetsList, handlePolicyPresetsShow, handlePolicyPreview, handlePolicyTemplates, handlePolicyValidateEvidence, handlePolicyValidateTools, } from "./commands/policy.js";
@@ -13,7 +15,7 @@ import { generateRequestId } from "./request-id.js";
 import { colorize, shouldUseColor } from "./color.js";
 import { formatUnknownCommandMessage } from "./suggest.js";
 import { handleCompletionCommand, handleExamplesCommand, handleHelpCommand, handleOnboarding, } from "./ux.js";
-import { CliError, EXIT_SUCCESS, } from "./types.js";
+import { CliError, EXIT_SUCCESS, exitCodeForHttpStatus, } from "./types.js";
 function isHelp(argv) {
     return argv.length === 0 || argv.includes("--help") || argv.includes("-h");
 }
@@ -36,6 +38,32 @@ function renderTable(command, result, globals) {
     }
     return lines;
 }
+function isSdkHttpError(err) {
+    if (err instanceof HarborHttpError || err instanceof SignalHttpError) {
+        return true;
+    }
+    if (!(err instanceof Error)) {
+        return false;
+    }
+    const candidate = err;
+    return typeof candidate.statusCode === "number" && typeof candidate.bodyText === "string";
+}
+function sdkHttpErrorShape(err) {
+    const mapped = exitCodeForHttpStatus(err.statusCode);
+    const summary = summarizeGatewayHttpError(err.statusCode, err.bodyText);
+    const gatewayCode = typeof summary.details.gateway_code === "string"
+        ? summary.details.gateway_code
+        : undefined;
+    return {
+        shape: {
+            category: mapped.category,
+            code: gatewayCode || `cli.gateway.http_${err.statusCode}`,
+            message: formatSdkHttpErrorMessage(err.message, err.statusCode, err.bodyText),
+            details: summary.details,
+        },
+        exitCode: mapped.exitCode,
+    };
+}
 function toErrorShape(err) {
     if (err instanceof CliError) {
         if (err.message === "help") {
@@ -54,6 +82,9 @@ function toErrorShape(err) {
             exitCode: err.exitCode,
         };
     }
+    if (isSdkHttpError(err)) {
+        return sdkHttpErrorShape(err);
+    }
     return {
         shape: {
             category: "internal",
@@ -319,7 +350,10 @@ export async function runCli(argv, deps = {}) {
                 ctx.stdout.write(`${line}\n`);
             }
         }
-        else if (canonical === "agent sandbox smoke" && Array.isArray(result.data.checklist_lines)) {
+        else if ((canonical === "agent sandbox smoke" ||
+            canonical === "agent production attach smoke" ||
+            canonical === "agent harbor evidence smoke") &&
+            Array.isArray(result.data.checklist_lines)) {
             writeTableLines(ctx.stdout, result.data.checklist_lines);
             if (output.warnings.length) {
                 for (const warning of output.warnings) {

package/dist/cli.js

@@ -2,6 +2,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { deprecatedAliasWarning } from "./cli/automation.js";
+import { mcpServeArgvMatches, runMcpServeCommandSync } from "./cli/commands/setup.js";
 import { runCli } from "./cli/router.js";
 async function invokedFromCLI() {
     const scriptPath = process.argv[1];
@@ -25,7 +27,19 @@ invokedFromCLI().then((invoked) => {
     if (!invoked) {
         return;
     }
-    runCli(process.argv.slice(2)).then((code) => {
+    const argv = process.argv.slice(2);
+    const aliasWarning = deprecatedAliasWarning(process.argv[1]);
+    if (aliasWarning) {
+        process.stderr.write(`${aliasWarning}\n`);
+    }
+    if (mcpServeArgvMatches(argv)) {
+        process.exitCode = runMcpServeCommandSync(argv, {
+            stdout: process.stdout,
+            stderr: process.stderr,
+        });
+        return;
+    }
+    runCli(argv).then((code) => {
         process.exitCode = code;
     }, (err) => {
         process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);

package/dist/gateway-retry.d.ts

@@ -0,0 +1,16 @@
+/** True when the body is a Cloudflare-generated edge error (not Paybond gateway JSON). */
+export declare function isCloudflareEdgeErrorBody(bodyText: string): boolean;
+/** Whether an HTTP status/body pair should be retried by SDK gateway clients. */
+export declare function shouldRetryGatewayHttpStatus(status: number, bodyText: string): boolean;
+/** Inspect a response body (via clone) to decide whether to retry transient gateway errors. */
+export declare function shouldRetryGatewayResponse(res: Response): Promise<boolean>;
+export declare function backoffMs(attempt: number): number;
+export declare function parseRetryAfterSeconds(value: string | null): number | null;
+/** Prefer `Retry-After` when present; otherwise exponential backoff with jitter. */
+export declare function gatewayRetryDelayMs(attempt: number, retryAfterHeader: string | null): number;
+/**
+ * Shared 429/5xx retry loop for Paybond gateway HTTP clients.
+ * Skips retries on Cloudflare edge error bodies. Returns the response on success;
+ * otherwise throws the last network error.
+ */
+export declare function fetchWithGatewayRetries(url: string, init: RequestInit, maxRetries: number): Promise<Response>;

package/dist/gateway-retry.js

@@ -0,0 +1,83 @@
+/** True when the body is a Cloudflare-generated edge error (not Paybond gateway JSON). */
+export function isCloudflareEdgeErrorBody(bodyText) {
+    const trimmed = bodyText.trim();
+    if (!trimmed) {
+        return false;
+    }
+    try {
+        const body = JSON.parse(trimmed);
+        return body.cloudflare_error === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether an HTTP status/body pair should be retried by SDK gateway clients. */
+export function shouldRetryGatewayHttpStatus(status, bodyText) {
+    if (![429, 500, 502, 503, 504].includes(status)) {
+        return false;
+    }
+    if (isCloudflareEdgeErrorBody(bodyText)) {
+        return false;
+    }
+    return true;
+}
+/** Inspect a response body (via clone) to decide whether to retry transient gateway errors. */
+export async function shouldRetryGatewayResponse(res) {
+    if (![429, 500, 502, 503, 504].includes(res.status)) {
+        return false;
+    }
+    const peek = await res.clone().text();
+    return shouldRetryGatewayHttpStatus(res.status, peek);
+}
+export function backoffMs(attempt) {
+    const base = 200 * 2 ** attempt;
+    const jitter = Math.random() * 100;
+    return Math.min(base + jitter, 5000);
+}
+export function parseRetryAfterSeconds(value) {
+    if (!value) {
+        return null;
+    }
+    const n = Number.parseFloat(value.trim());
+    if (!Number.isFinite(n)) {
+        return null;
+    }
+    return Math.min(n, 30);
+}
+/** Prefer `Retry-After` when present; otherwise exponential backoff with jitter. */
+export function gatewayRetryDelayMs(attempt, retryAfterHeader) {
+    const raSec = parseRetryAfterSeconds(retryAfterHeader);
+    return raSec != null ? raSec * 1000 : backoffMs(attempt);
+}
+/**
+ * Shared 429/5xx retry loop for Paybond gateway HTTP clients.
+ * Skips retries on Cloudflare edge error bodies. Returns the response on success;
+ * otherwise throws the last network error.
+ */
+export async function fetchWithGatewayRetries(url, init, maxRetries) {
+    let lastErr;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        let res;
+        try {
+            res = await fetch(url, init);
+        }
+        catch (e) {
+            lastErr = e;
+            if (attempt + 1 >= maxRetries) {
+                throw e;
+            }
+            await new Promise((r) => setTimeout(r, gatewayRetryDelayMs(attempt, null)));
+            continue;
+        }
+        if ([429, 500, 502, 503, 504].includes(res.status) && attempt + 1 < maxRetries) {
+            if (!(await shouldRetryGatewayResponse(res))) {
+                return res;
+            }
+            await new Promise((r) => setTimeout(r, gatewayRetryDelayMs(attempt, res.headers.get("retry-after"))));
+            continue;
+        }
+        return res;
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}

package/dist/index.d.ts

@@ -1301,7 +1301,7 @@ export declare class Paybond {
 }
 export { normalizeJson, jsonValueDigest } from "./json-digest.js";
 export { buildSignedCreateIntentBody, buildSignedCreateIntentBodyWithPolicyBinding, intentCreationSignBytesRaw, intentCreationSignBytesWithPolicyBinding, type BuildSignedCreateIntentParams, type BuildSignedCreateIntentWithPolicyBindingParams, type PolicyBindingRef, type PublishedPolicyHead, type SettlementRail, } from "./principal-intent.js";
-export { artifactsDigest, signPayeeEvidenceBinding, type SignPayeeEvidenceParams } from "./payee-evidence.js";
+export { artifactsDigest, evidenceSignBytesV1, signPayeeEvidenceBinding, type SignPayeeEvidenceParams, } from "./payee-evidence.js";
 export { AGENT_RECOGNITION_GATEWAY_VERIFIER_ID, AGENT_RECOGNITION_PROOF_KIND_V1, AGENT_RECOGNITION_PURPOSE_EVIDENCE_SUBMIT, newAgentRecognitionRequestEnvelope, signAgentRecognitionProofV1, signHarborEvidenceSubmitRecognitionProof, type SignAgentRecognitionProofV1Params, type SignedAgentRecognitionProofV1, } from "./agent-recognition.js";
 export { validateCompletionEvidence, type CompletionEvidenceValidationReport, } from "./completion-validate-evidence.js";
 export { completionSchemaDigestHex, computeVendorContractDigests, verifyVendorContract, verifyCatalogVendorContracts, type VendorContract, type VendorContractDigests, } from "./completion-contract-digest.js";