@paybond/kit 0.9.8 → 0.11.0

package/dist/cli/globals.js

@@ -0,0 +1,248 @@
+import { generateRequestId } from "./request-id.js";
+import { parseColorMode, resolveColorModeFromEnv } from "./color.js";
+import { formatUnknownGlobalFlagMessage } from "./suggest.js";
+import { InsecureGatewayURLError, requireSecureGatewayUrl } from "../gateway-url.js";
+import { CliError } from "./types.js";
+export const DEFAULT_GATEWAY = "https://api.paybond.ai";
+export const DEFAULT_ENV_FILE = ".env.local";
+export const TENANT_OVERRIDE_FLAGS = ["--tenant-id", "--tenant", "--tenant_id"];
+export function rejectsTenantOverrideFlag(arg) {
+    for (const flag of TENANT_OVERRIDE_FLAGS) {
+        if (arg === flag || arg.startsWith(`${flag}=`)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function validateCliGateway(url) {
+    try {
+        return requireSecureGatewayUrl(url);
+    }
+    catch (err) {
+        const message = err instanceof InsecureGatewayURLError ? err.message : String(err);
+        throw new CliError(message, { category: "validation", code: "cli.validation.insecure_gateway" });
+    }
+}
+export function parseRequiredNonNegativeInt(raw, field) {
+    const text = raw.trim();
+    if (!text) {
+        throw new CliError(`invalid ${field} (expected non-negative integer)`, {
+            category: "validation",
+            code: "cli.validation.invalid_integer",
+        });
+    }
+    const value = Number(text);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new CliError(`invalid ${field} (expected non-negative integer)`, {
+            category: "validation",
+            code: "cli.validation.invalid_integer",
+        });
+    }
+    return value;
+}
+export function parseOptionalNonNegativeInt(raw, field) {
+    if (!raw?.trim()) {
+        return 0;
+    }
+    return parseRequiredNonNegativeInt(raw, field);
+}
+const GLOBAL_FLAGS = new Set([
+    "--gateway",
+    "--env-file",
+    "--format",
+    "--json",
+    "--jq",
+    "--profile",
+    "--request-id",
+    "--yes",
+    "--no-open",
+    "--color",
+    "--no-color",
+]);
+export function defaultGlobalOptions() {
+    return {
+        gateway: DEFAULT_GATEWAY,
+        envFile: DEFAULT_ENV_FILE,
+        format: "table",
+        color: resolveColorModeFromEnv(),
+        requestId: generateRequestId(),
+        yes: false,
+        noOpen: false,
+    };
+}
+function parseFormat(raw) {
+    const value = raw.trim().toLowerCase();
+    if (value === "table" || value === "json") {
+        return value;
+    }
+    throw new CliError("invalid --format (expected table|json)", { category: "usage", code: "cli.usage.invalid_format" });
+}
+function readFlagValue(argv, index, flag) {
+    const arg = argv[index];
+    if (arg.startsWith(`${flag}=`)) {
+        return { value: arg.slice(flag.length + 1), consumed: 1 };
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("-")) {
+        throw new CliError(`missing value for ${flag}`, { category: "usage", code: "cli.usage.missing_flag_value" });
+    }
+    return { value: next, consumed: 2 };
+}
+export function parseCliArgv(argv) {
+    for (const arg of argv) {
+        if (rejectsTenantOverrideFlag(arg)) {
+            throw new CliError("tenant scope comes from authenticated credentials; do not pass --tenant-id", {
+                category: "usage",
+                code: "cli.usage.tenant_override_forbidden",
+            });
+        }
+    }
+    const globals = defaultGlobalOptions();
+    const command = [];
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            command.push(arg);
+            i += 1;
+            continue;
+        }
+        if (arg === "--yes") {
+            globals.yes = true;
+            i += 1;
+            continue;
+        }
+        if (arg === "--no-open") {
+            globals.noOpen = true;
+            i += 1;
+            continue;
+        }
+        if (arg === "--no-color") {
+            globals.color = "never";
+            i += 1;
+            continue;
+        }
+        if (arg === "--color" || arg.startsWith("--color=")) {
+            const { value, consumed } = readFlagValue(argv, i, "--color");
+            try {
+                globals.color = parseColorMode(value);
+            }
+            catch (err) {
+                throw new CliError(err instanceof Error ? err.message : String(err), {
+                    category: "usage",
+                    code: "cli.usage.invalid_color",
+                });
+            }
+            i += consumed;
+            continue;
+        }
+        if (arg === "--gateway" || arg.startsWith("--gateway=")) {
+            const { value, consumed } = readFlagValue(argv, i, "--gateway");
+            if (!value.trim()) {
+                throw new CliError("invalid --gateway", { category: "usage", code: "cli.usage.invalid_gateway" });
+            }
+            globals.gateway = validateCliGateway(value.trim());
+            i += consumed;
+            continue;
+        }
+        if (arg === "--env-file" || arg.startsWith("--env-file=")) {
+            const { value, consumed } = readFlagValue(argv, i, "--env-file");
+            if (!value.trim()) {
+                throw new CliError("invalid --env-file", { category: "usage", code: "cli.usage.invalid_env_file" });
+            }
+            globals.envFile = value.trim();
+            i += consumed;
+            continue;
+        }
+        if (arg === "--format" || arg.startsWith("--format=")) {
+            const { value, consumed } = readFlagValue(argv, i, "--format");
+            globals.format = parseFormat(value);
+            i += consumed;
+            continue;
+        }
+        if (arg === "--profile" || arg.startsWith("--profile=")) {
+            const { value, consumed } = readFlagValue(argv, i, "--profile");
+            if (!value.trim()) {
+                throw new CliError("invalid --profile", { category: "usage", code: "cli.usage.invalid_profile" });
+            }
+            globals.profile = value.trim();
+            i += consumed;
+            continue;
+        }
+        if (arg === "--request-id" || arg.startsWith("--request-id=")) {
+            const { value, consumed } = readFlagValue(argv, i, "--request-id");
+            if (!value.trim()) {
+                throw new CliError("invalid --request-id", { category: "usage", code: "cli.usage.invalid_request_id" });
+            }
+            globals.requestId = value.trim();
+            i += consumed;
+            continue;
+        }
+        if (arg === "--json" || arg.startsWith("--json=")) {
+            const { value, consumed } = readFlagValue(argv, i, "--json");
+            if (!value.trim()) {
+                throw new CliError("invalid --json (expected comma-separated field names)", {
+                    category: "usage",
+                    code: "cli.usage.invalid_json_fields",
+                });
+            }
+            globals.jsonFields = value.trim();
+            i += consumed;
+            continue;
+        }
+        if (arg === "--jq" || arg.startsWith("--jq=")) {
+            const { value, consumed } = readFlagValue(argv, i, "--jq");
+            if (!value.trim()) {
+                throw new CliError("invalid --jq (expected filter expression)", { category: "usage", code: "cli.usage.invalid_jq" });
+            }
+            globals.jqExpr = value.trim();
+            i += consumed;
+            continue;
+        }
+        if (arg.startsWith("--") && !GLOBAL_FLAGS.has(arg.split("=")[0])) {
+            if (command.length === 0) {
+                throw new CliError(formatUnknownGlobalFlagMessage(arg), {
+                    category: "usage",
+                    code: "cli.usage.unknown_flag",
+                });
+            }
+        }
+        command.push(arg);
+        i += 1;
+    }
+    return { globals, command };
+}
+export function consumeFlag(argv, flag) {
+    const rest = [];
+    let present = false;
+    let value;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === flag) {
+            present = true;
+            const next = argv[i + 1];
+            if (!next || next.startsWith("-")) {
+                throw new CliError(`missing value for ${flag}`, { category: "usage", code: "cli.usage.missing_flag_value" });
+            }
+            value = next;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith(`${flag}=`)) {
+            present = true;
+            value = arg.slice(flag.length + 1);
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { present, value, rest };
+}
+export function consumeBooleanFlag(argv, flag) {
+    const rest = argv.filter((arg) => {
+        if (arg === flag) {
+            return false;
+        }
+        return true;
+    });
+    return { present: argv.length !== rest.length, rest };
+}

package/dist/cli/help.d.ts

@@ -0,0 +1,3 @@
+export declare const ROOT_HELP = "Usage: paybond [--global-flags] <command> [<subcommand> ...] [args]\n\nGlobal flags:\n  --gateway <url>         Gateway base URL (default: https://api.paybond.ai)\n  --env-file <path>       Local secrets file (default: .env.local)\n  --format table|json     Human table or JSON envelope output (default: table)\n  --json <fields>         Field-selectable JSON for list/read commands (plain JSON; use --format json for envelope)\n  --jq <expr>             jq-style filter for list/read command output\n  --profile <name>        Named credential profile from the Paybond CLI config file\n  --request-id <id>       Correlation ID for Gateway calls and JSON output\n  --yes                   Skip confirmation for destructive operations\n  --no-open               Do not open a browser for device login\n  --color auto|always|never Colorize human table output and help text (default: auto)\n  --no-color              Disable color output (also honors NO_COLOR)\n\nCommands:\n  onboarding              Guided, non-destructive first-run checks\n  help                    Detailed help for a command\n  examples                Copy-paste examples from the command spec\n  completion bash|zsh|fish Shell completion scripts\n  login                   Sandbox device login\n  init                    Interactive first-run scaffold (solution, spend cap, framework, owned policy files)\n  init guardrail|completion|agent-middleware\n                          Scaffold sandbox guardrail, completion evidence, or agent middleware integration files\n  mcp serve|install|verify-config|tools MCP server and host configuration\n  doctor                  Validate local runtime, credentials, and optional agent setup\n  dev smoke|trace|loop|up\n                          Local sandbox developer loop: travel smoke, trace dashboard, WireMock up, and guided setup\n  version                 Print package version (use --verbose for runtime details)\n  diagnose                Emit a redacted support bundle with --redacted\n  config get|set|unset|list\n                          Manage CLI configuration values\n  whoami                  Resolve the authenticated principal and tenant realm\n  keys list|create|rotate|revoke\n                          Manage tenant service-account API keys\n  intents list|get|create|fund|evidence|settlement-confirm\n                          Harbor intent workflows\n  guardrails bootstrap|evidence\n                          Sandbox guardrail helpers\n  spend authorize         Authorize delegated spend for a tool call\n  signal reputation|portfolio|fraud\n                          Signal summaries and fraud reads\n  receipts get|verify\n                          Protocol settlement receipts\n  mandates verify|import\n                          Agent mandate verification and import\n  a2a card|contracts\n                          Agent card discovery and task contracts\n  policy init|init-org|extend|presets list|presets show|validate-tools|templates|preview|import-mcp-receipt|import-x402-receipt|validate-evidence\n                          Scaffold and validate paybond.policy.yaml (including enterprise org inheritance), browse policy presets and solutions, list completion presets, preview Harbor templates, and import receipts\n  agent run bind|status|trace|reload-policy|tool execute|validate|registry validate|sandbox smoke\n                          Agent middleware: bind runs, reload policy, execute tools, validate registry, sandbox smoke\n  audit exports list|get|verify|delete\n                          Compliance audit export jobs and local bundle verification\n\nGetting started:\n  Sandbox setup\n    Authenticate, validate the runtime, and confirm tenant context.\n    $ paybond login\n    $ paybond doctor --format json\n    Next: paybond whoami\n  Agent + MCP host\n    Preview MCP host config and list tools exposed to agents.\n    $ paybond mcp install --host claude --scope local\n    $ paybond mcp verify-config --host claude\n    $ paybond mcp tools\n    Next: paybond doctor --agent\n  Paid-tool guardrail\n    Scaffold a sandbox guardrail integration file for your agent runtime.\n    $ paybond init guardrail\n    $ paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100\n    Next: paybond spend authorize --help\n  Policy-driven agent sandbox\n    Validate and smoke-test agent middleware from a versioned paybond.policy.yaml file.\n    $ paybond policy init --out paybond.policy.yaml\n    $ paybond policy validate-tools --file paybond.policy.yaml\n    $ paybond agent sandbox smoke --policy-file paybond.policy.yaml --result-body '{\"status\":\"completed\",\"cost_cents\":18700}' --format json\n    Next: paybond policy validate-tools --help\n  Agent middleware sandbox\n    Bind a sandbox run and execute a guarded tool with auto-evidence.\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    Next: paybond agent run bind --help\n  Completion preset\n    Scaffold catalog-aligned completion evidence for Harbor release predicates.\n    $ paybond init completion --preset api_response_ok\n    $ paybond policy templates\n    $ paybond policy preview --preset api_response_ok --evidence-file evidence.json\n    Next: paybond policy preview --help\n\nDocumentation: https://docs.paybond.ai/kit\n\nLearn more:\n  paybond help <command>     Detailed help for a command\n  paybond examples           Copy-paste command examples\n  paybond onboarding         Guided first-run checks\n  paybond completion <shell> Shell completions (bash|zsh|fish)\n\nLegacy aliases: paybond-kit-login, paybond-init, paybond-kit-init, paybond-mcp-server\n";
+export declare const COMMAND_HELP: Record<string, string>;
+export declare function helpForCommand(path: string): string;

package/dist/cli/help.js

@@ -0,0 +1,83 @@
+// Generated by kit/cli-parity/generate.mjs — do not edit by hand.
+export const ROOT_HELP = "Usage: paybond [--global-flags] <command> [<subcommand> ...] [args]\n\nGlobal flags:\n  --gateway <url>         Gateway base URL (default: https://api.paybond.ai)\n  --env-file <path>       Local secrets file (default: .env.local)\n  --format table|json     Human table or JSON envelope output (default: table)\n  --json <fields>         Field-selectable JSON for list/read commands (plain JSON; use --format json for envelope)\n  --jq <expr>             jq-style filter for list/read command output\n  --profile <name>        Named credential profile from the Paybond CLI config file\n  --request-id <id>       Correlation ID for Gateway calls and JSON output\n  --yes                   Skip confirmation for destructive operations\n  --no-open               Do not open a browser for device login\n  --color auto|always|never Colorize human table output and help text (default: auto)\n  --no-color              Disable color output (also honors NO_COLOR)\n\nCommands:\n  onboarding              Guided, non-destructive first-run checks\n  help                    Detailed help for a command\n  examples                Copy-paste examples from the command spec\n  completion bash|zsh|fish Shell completion scripts\n  login                   Sandbox device login\n  init                    Interactive first-run scaffold (solution, spend cap, framework, owned policy files)\n  init guardrail|completion|agent-middleware\n                          Scaffold sandbox guardrail, completion evidence, or agent middleware integration files\n  mcp serve|install|verify-config|tools MCP server and host configuration\n  doctor                  Validate local runtime, credentials, and optional agent setup\n  dev smoke|trace|loop|up\n                          Local sandbox developer loop: travel smoke, trace dashboard, WireMock up, and guided setup\n  version                 Print package version (use --verbose for runtime details)\n  diagnose                Emit a redacted support bundle with --redacted\n  config get|set|unset|list\n                          Manage CLI configuration values\n  whoami                  Resolve the authenticated principal and tenant realm\n  keys list|create|rotate|revoke\n                          Manage tenant service-account API keys\n  intents list|get|create|fund|evidence|settlement-confirm\n                          Harbor intent workflows\n  guardrails bootstrap|evidence\n                          Sandbox guardrail helpers\n  spend authorize         Authorize delegated spend for a tool call\n  signal reputation|portfolio|fraud\n                          Signal summaries and fraud reads\n  receipts get|verify\n                          Protocol settlement receipts\n  mandates verify|import\n                          Agent mandate verification and import\n  a2a card|contracts\n                          Agent card discovery and task contracts\n  policy init|init-org|extend|presets list|presets show|validate-tools|templates|preview|import-mcp-receipt|import-x402-receipt|validate-evidence\n                          Scaffold and validate paybond.policy.yaml (including enterprise org inheritance), browse policy presets and solutions, list completion presets, preview Harbor templates, and import receipts\n  agent run bind|status|trace|reload-policy|tool execute|validate|registry validate|sandbox smoke\n                          Agent middleware: bind runs, reload policy, execute tools, validate registry, sandbox smoke\n  audit exports list|get|verify|delete\n                          Compliance audit export jobs and local bundle verification\n\nGetting started:\n  Sandbox setup\n    Authenticate, validate the runtime, and confirm tenant context.\n    $ paybond login\n    $ paybond doctor --format json\n    Next: paybond whoami\n  Agent + MCP host\n    Preview MCP host config and list tools exposed to agents.\n    $ paybond mcp install --host claude --scope local\n    $ paybond mcp verify-config --host claude\n    $ paybond mcp tools\n    Next: paybond doctor --agent\n  Paid-tool guardrail\n    Scaffold a sandbox guardrail integration file for your agent runtime.\n    $ paybond init guardrail\n    $ paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100\n    Next: paybond spend authorize --help\n  Policy-driven agent sandbox\n    Validate and smoke-test agent middleware from a versioned paybond.policy.yaml file.\n    $ paybond policy init --out paybond.policy.yaml\n    $ paybond policy validate-tools --file paybond.policy.yaml\n    $ paybond agent sandbox smoke --policy-file paybond.policy.yaml --result-body '{\"status\":\"completed\",\"cost_cents\":18700}' --format json\n    Next: paybond policy validate-tools --help\n  Agent middleware sandbox\n    Bind a sandbox run and execute a guarded tool with auto-evidence.\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    Next: paybond agent run bind --help\n  Completion preset\n    Scaffold catalog-aligned completion evidence for Harbor release predicates.\n    $ paybond init completion --preset api_response_ok\n    $ paybond policy templates\n    $ paybond policy preview --preset api_response_ok --evidence-file evidence.json\n    Next: paybond policy preview --help\n\nDocumentation: https://docs.paybond.ai/kit\n\nLearn more:\n  paybond help <command>     Detailed help for a command\n  paybond examples           Copy-paste command examples\n  paybond onboarding         Guided first-run checks\n  paybond completion <shell> Shell completions (bash|zsh|fish)\n\nLegacy aliases: paybond-kit-login, paybond-init, paybond-kit-init, paybond-mcp-server\n";
+export const COMMAND_HELP = {
+    "onboarding": "Usage: paybond onboarding [--host claude|codex|openai|generic]\n\nRuns a guided, non-destructive first-run workflow: runtime check, login status, guardrail file status, MCP config preview, and doctor.\n\nExamples:\n  $ paybond onboarding\n  $ paybond onboarding --host claude --format json\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond login",
+    "help": "Usage: paybond help [<command> [<subcommand> ...]]\n\nShows detailed help for a command path. Without arguments, prints root help.\n\nExamples:\n  $ paybond help\n  $ paybond help login\n  $ paybond help mcp install",
+    "examples": "Usage: paybond examples [<command> [<subcommand> ...]]\n\nLists copy-paste examples from the command spec. Filter with an optional command path.\n\nExamples:\n  $ paybond examples\n  $ paybond examples doctor",
+    "completion": "Usage: paybond completion bash|zsh|fish\n\nPrints a shell completion script generated from the command spec. Pipe to your shell config.\n\nExamples:\n  $ paybond completion bash >> ~/.bashrc\n  $ paybond completion zsh >> ~/.zshrc\n  $ paybond completion fish | source",
+    "login": "Usage: paybond login [--env sandbox] [--env-file .env.local] [--gateway <url>] [--no-open] [--force]\n\nStarts sandbox device login and writes PAYBOND_API_KEY to the env file.\n\nExamples:\n  $ paybond login\n  $ paybond login --no-open --format json\n\nDocs: https://docs.paybond.ai/kit/authentication\n\nNext: paybond doctor",
+    "init": "Usage: paybond init [--solution shopping|travel|saas|mcp-server|aws] [--max-spend-usd <n>] [--framework openai|langgraph|mcp|generic] [--language typescript|python] [--non-interactive] [--force]\n\nInteractive first-run scaffold: solution bundle policy, client bootstrap, framework instrument stub, .env.example, and npm smoke script.\n\nExamples:\n  $ paybond init\n  $ paybond init --solution travel --max-spend-usd 500 --framework langgraph --non-interactive\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent\n\nNext: paybond login",
+    "init guardrail": "Usage: paybond init guardrail [--preset paid-tool-guard] [--framework <name>] [--out <path>] [--force]\n\nScaffolds a sandbox paid-tool guardrail integration file aligned with the cost_and_completion catalog archetype.\n\nExamples:\n  $ paybond init guardrail\n  $ paybond init guardrail --framework openai --out guard.ts\n\nDocs: https://docs.paybond.ai/kit/index\n\nNext: paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100",
+    "init completion": "Usage: paybond init completion --preset <archetype> [--out <path>] [--force]\n\nScaffolds a completion evidence helper from the shared preset catalog (evidence_schema, buildCompletionEvidence, policy_binding stub).\n\nExamples:\n  $ paybond init completion --preset api_response_ok\n  $ paybond init completion --preset cost_and_completion --out paybond-completion.ts\n\nDocs: https://docs.paybond.ai/kit/completion-presets\n\nNext: paybond policy preview --preset api_response_ok --evidence-file evidence.json",
+    "policy templates": "Usage: paybond policy templates\n\nLists completion preset archetypes from kit/completion-presets/catalog.json.\n\nExamples:\n  $ paybond policy templates\n  $ paybond policy templates --format json\n\nDocs: https://docs.paybond.ai/kit/completion-presets\n\nNext: paybond policy preview --preset api_response_ok --evidence-file evidence.json",
+    "policy preview": "Usage: paybond policy preview --template <id>|--preset <archetype> [--parameters-file <path>] --evidence-file <path> [--schema-file <path>] [--amount-cents <n>]\n\nMaterializes a Harbor managed template and evaluates sample evidence (preview + test) against the gateway.\n\nExamples:\n  $ paybond policy preview --preset api_response_ok --evidence-file evidence.json\n  $ paybond policy preview --template api_response_v1 --parameters-file parameters.json --evidence-file evidence.json\n\nDocs: https://docs.paybond.ai/kit/completion-presets",
+    "policy import-mcp-receipt": "Usage: paybond policy import-mcp-receipt --decision-file <path> --outcome-file <path> [--write-evidence-file <path>]\n\nVerifies Ed25519 signatures on paired SEP-2828 MCP decision and outcome records, then maps them into artifact_attested evidence fields.\n\nExamples:\n  $ paybond policy import-mcp-receipt --decision-file decision.json --outcome-file outcome.json\n  $ paybond policy import-mcp-receipt --decision-file decision.json --outcome-file outcome.json --write-evidence-file evidence.json\n\nDocs: https://docs.paybond.ai/kit/completion-presets",
+    "policy import-x402-receipt": "Usage: paybond policy import-x402-receipt --receipt-file <path> [--write-evidence-file <path>]\n\nVerifies a signed x402 offer-receipt artifact (JWS or EIP-712), then maps it into artifact_attested evidence fields (BLAKE3 digest of JCS-canonical receipt bytes).\n\nExamples:\n  $ paybond policy import-x402-receipt --receipt-file receipt.json\n  $ paybond policy import-x402-receipt --receipt-file receipt.json --write-evidence-file evidence.json\n\nDocs: https://docs.paybond.ai/kit/completion-presets",
+    "policy validate-evidence": "Usage: paybond policy validate-evidence --preset <id> [--vendor-file <path>] [--canonical-file <path>] [--frozen-api-version <ver>] [--frozen-vendor-schema-digest <hex>] [--frozen-canonical-schema-digest <hex>]\n\nPre-validates vendor and canonical completion evidence against catalog JSON Schemas and preset forbidden_evidence_fields (signal-only; Harbor remains authoritative at submit).\n\nExamples:\n  $ paybond policy validate-evidence --preset stripe_charge --vendor-file vendor.json\n  $ paybond policy validate-evidence --preset ach_travel_booking --vendor-file booking.json --frozen-api-version 2024-10-28.acacia\n\nDocs: https://docs.paybond.ai/kit/completion-presets",
+    "policy presets list": "Usage: paybond policy presets list\n\nLists bundled policy domains, guardrails, flat/composed presets, and solution manifests.\n\nExamples:\n  $ paybond policy presets list\n  $ paybond policy presets list --format json\n\nDocs: https://docs.paybond.ai/kit/agent-policy\n\nNext: paybond policy presets show travel",
+    "policy presets show": "Usage: paybond policy presets show <preset>|--preset <id> [--max-spend <usd>] [--domain <id> --guardrails <csv>]\n\nPreview composed paybond.policy.yaml for a bundled preset or custom domain + guardrails composition.\n\nExamples:\n  $ paybond policy presets show travel\n  $ paybond policy presets show --preset travel --max-spend 500\n  $ paybond policy presets show --domain travel --guardrails read-only,max-spend:500\n\nDocs: https://docs.paybond.ai/kit/agent-policy\n\nNext: paybond policy init --preset travel --out paybond.policy.yaml",
+    "policy init": "Usage: paybond policy init [--out <path>] [--preset <id>] [--domain <id> --guardrails <csv>] [--max-spend <usd>] [--operation <name>] [--evidence-preset <id>] [--force]\n\nScaffolds paybond.policy.yaml from a bundled vertical preset, composed domain + guardrails, or a single-operation starter template.\n\nExamples:\n  $ paybond policy init --preset travel --out paybond.policy.yaml\n  $ paybond policy init --preset travel --max-spend 500 --out paybond.policy.yaml\n  $ paybond policy init --domain travel --guardrails read-only,max-spend:500 --out paybond.policy.yaml\n  $ paybond policy init --out paybond.policy.yaml\n  $ paybond policy init --operation travel.book_hotel --evidence-preset cost_and_completion\n\nDocs: https://docs.paybond.ai/kit/agent-policy\n\nNext: paybond policy validate-tools --file paybond.policy.yaml",
+    "policy init-org": "Usage: paybond policy init-org --policy-id <id> [--out <path>] [--operation <name>] [--evidence-preset <id>] [--max-spend-cents <n>] [--force]\n\nScaffolds a v2 org base policy for platform operators. Publish with PUT /v1/admin/org-policies/{policy_id}?org_id=... after review.\n\nExamples:\n  $ paybond policy init-org --policy-id acme-agent-spend-v1 --out org-agent-spend-v1.yaml\n  $ paybond policy init-org --policy-id acme-agent-spend-v1 --operation travel.book_hotel --max-spend-cents 20000\n\nDocs: https://docs.paybond.ai/kit/enterprise-policy-inheritance\n\nNext: paybond policy extend --extends org_acme_corp/acme-agent-spend-v1",
+    "policy extend": "Usage: paybond policy extend --extends <org_id/org_policy_id> [--out <path>] [--name <overlay_name>] [--operation <tenant_tool>] [--evidence-preset <id>] [--base-policy <path>] [--force]\n\nScaffolds a v2 tenant overlay paybond.policy.yaml that extends a published org base policy.\n\nExamples:\n  $ paybond policy extend --extends org_acme_corp/acme-agent-spend-v1 --out paybond.policy.yaml\n  $ paybond policy extend --extends org_acme_corp/acme-agent-spend-v1 --operation acme.internal.approve_po --evidence-preset cost_and_completion\n\nDocs: https://docs.paybond.ai/kit/enterprise-policy-inheritance\n\nNext: paybond policy validate-tools --file paybond.policy.yaml --remote --resolve-inheritance",
+    "policy validate-tools": "Usage: paybond policy validate-tools --file <path> [--remote] [--local-only] [--strict] [--check-gateway] [--resolve-inheritance]\n\nValidates a paybond.policy.yaml file before deploy or agent bind. Uses Gateway POST /v1/policy/validate when logged in (--remote, or default with credentials). --resolve-inheritance merges org base server-side for tenant overlays.\n\nExamples:\n  $ paybond policy validate-tools --file paybond.policy.yaml --local-only\n  $ paybond policy validate-tools --file paybond.policy.yaml --remote --format json\n  $ paybond policy validate-tools --file paybond.policy.yaml --remote --resolve-inheritance --format json\n\nDocs: https://docs.paybond.ai/kit/agent-policy-validate",
+    "mcp serve": "Usage: paybond mcp serve\n\nRuns the stdio MCP server until the host process exits. Diagnostics print to stderr; stdout is reserved for MCP JSON-RPC.\n\nExamples:\n  $ paybond mcp serve",
+    "mcp install": "Usage: paybond mcp install --host claude|codex|openai|generic [--scope local|project|user] [--format json|toml] [--out <path>] [--env-file <path>] [--tool-policy readonly|spend-write|allowlist] [--tool-allowlist <names>]\n\nWrites a stdio MCP server entry that references PAYBOND_ENV_FILE (never raw API keys).\nDefault format is TOML for codex and JSON for other hosts. --scope local prints without writing.\nOptional --tool-policy controls which Paybond MCP tools the server exposes.\n\nExamples:\n  $ paybond mcp install --host claude\n  $ paybond mcp install --host generic --scope project --tool-policy readonly\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond mcp verify-config --host claude",
+    "mcp verify-config": "Usage: paybond mcp verify-config --host claude|codex|openai|generic [--format json|toml] [--env-file <path>] [--config <path>]\n\nValidates a generated or on-disk MCP host config without launching the MCP server.\n\nExamples:\n  $ paybond mcp verify-config --host claude\n  $ paybond mcp verify-config --host generic --config .paybond/mcp.json\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond doctor --agent",
+    "mcp tools": "Usage: paybond mcp tools\n\nLists tools exposed by the local MCP server.\n\nExamples:\n  $ paybond mcp tools",
+    "doctor": "Usage: paybond doctor [--agent] [--host claude|codex|openai|generic]\n\nValidates runtime, package version, env file, key shape, principal lookup, and with --agent deep MCP checks plus agent middleware sandbox smoke (bind, authorize, execute, auto-evidence).\n\nExamples:\n  $ paybond doctor\n  $ paybond doctor --agent --format json\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: 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",
+    "dev": "Usage: paybond dev <smoke|trace|loop|up> [args]\n\nLocal sandbox developer workflows: travel smoke with checklist output, trace dashboard, optional WireMock Gateway (`dev up`), and a guided login → policy → validate → smoke loop. Use `--offline` on smoke/loop for in-process mock capability and simulated settlement without PAYBOND_API_KEY.\n\nExamples:\n  $ paybond dev smoke --offline\n  $ paybond dev trace\n  $ paybond dev loop\n  $ paybond dev up\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent\n\nNext: paybond dev loop --offline",
+    "dev smoke": "Usage: paybond dev smoke [--preset travel] [--offline] [--format table|json]\n\nRuns agent sandbox smoke with travel preset defaults and records a local trace event. With `--offline`, uses an in-process mock capability and simulated settlement lifecycle (no PAYBOND_API_KEY required).\n\nExamples:\n  $ paybond dev smoke\n  $ paybond dev smoke --offline\n  $ paybond dev smoke --format json\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent\n\nNext: paybond dev trace",
+    "dev trace": "Usage: paybond dev trace [--port 9477]\n\nStarts a local HTTP trace dashboard on port 9477 showing recent tool authorization events from dev smoke runs.\n\nExamples:\n  $ paybond dev trace\n  $ paybond dev trace --port 9477\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent",
+    "dev loop": "Usage: paybond dev loop [--policy-file paybond.policy.yaml] [--offline] [--no-login]\n\nGuided local loop: login when needed (skipped with `--offline`), scaffold travel policy, validate tools locally, then run dev smoke. Prints a startup banner with trace and audit log paths.\n\nExamples:\n  $ paybond dev loop\n  $ paybond dev loop --offline\n  $ paybond dev loop --format json\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent\n\nNext: paybond dev trace",
+    "dev up": "Usage: paybond dev up [--port 18089] [--down]\n\nStarts or stops a local WireMock Gateway using bundled partner-dry-run mappings (Docker required). After `dev up`, point `--gateway` at the printed URL for HTTP-level sandbox smoke.\n\nExamples:\n  $ paybond dev up\n  $ paybond dev up --port 18089\n  $ paybond dev up --down\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent\n\nNext: paybond dev loop --gateway http://127.0.0.1:18089 --no-login",
+    "version": "Usage: paybond version [--verbose]\n\nPrints the installed Kit package version. With --verbose, includes runtime, platform, config paths, gateway URL, request ID, MCP tool count, and redacted credential source.\n\nExamples:\n  $ paybond version\n  $ paybond version --verbose --format json\n\nDocs: https://docs.paybond.ai/kit/package-provenance",
+    "diagnose": "Usage: paybond diagnose --redacted\n\nEmits a redacted support bundle for troubleshooting. Never prints raw API keys.\n\nExamples:\n  $ paybond diagnose --redacted\n  $ paybond diagnose --redacted --format json\n\nDocs: https://docs.paybond.ai/kit/package-provenance",
+    "config get": "Usage: paybond config get <key>\n\nExamples:\n  $ paybond config get gateway",
+    "config set": "Usage: paybond config set <key> <value>\n\nExamples:\n  $ paybond config set gateway https://api.paybond.ai",
+    "config unset": "Usage: paybond config unset <key>\n\nExamples:\n  $ paybond config unset gateway",
+    "config list": "Usage: paybond config list\n\nExamples:\n  $ paybond config list --format json",
+    "whoami": "Usage: paybond whoami\n\nResolves the authenticated principal and tenant realm.\n\nExamples:\n  $ paybond whoami\n  $ paybond whoami --format json",
+    "keys list": "Usage: paybond keys list\n\nExamples:\n  $ paybond keys list --format json",
+    "keys create": "Usage: paybond keys create --name <service-account> --role <role> [--label <label>]\n\nExamples:\n  $ paybond keys create --name ci-bot --role operator",
+    "keys rotate": "Usage: paybond keys rotate <key_id> [--yes]\n\nExamples:\n  $ paybond keys rotate key-123 --yes",
+    "keys revoke": "Usage: paybond keys revoke <key_id> [--yes]\n\nExamples:\n  $ paybond keys revoke key-123 --yes",
+    "intents list": "Usage: paybond intents list [--status <status>] [--limit <n>]\n\nExamples:\n  $ paybond intents list --limit 10",
+    "intents get": "Usage: paybond intents get <intent_id>\n\nExamples:\n  $ paybond intents get intent-123",
+    "intents create": "Usage: paybond intents create --body <json-file>\n\nExamples:\n  $ paybond intents create --body intent.json",
+    "intents fund": "Usage: paybond intents fund <intent_id> [--body <json-file>]\n\nExamples:\n  $ paybond intents fund intent-123",
+    "intents evidence": "Usage: paybond intents evidence <intent_id> --body <json-file>\n\nExamples:\n  $ paybond intents evidence intent-123 --body evidence.json",
+    "intents settlement-confirm": "Usage: paybond intents settlement-confirm <intent_id> [--body <json-file>]\n\nExamples:\n  $ paybond intents settlement-confirm intent-123",
+    "guardrails bootstrap": "Usage: paybond guardrails bootstrap --operation <name> --requested-spend-cents <n>\n\nExamples:\n  $ paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100",
+    "guardrails evidence": "Usage: paybond guardrails evidence --intent-id <id> --body <json-file>\n\nExamples:\n  $ paybond guardrails evidence --intent-id intent-123 --body evidence.json",
+    "spend authorize": "Usage: paybond spend authorize --intent-id <id> --token <capability> --operation <name> [--requested-spend-cents <n>]\n\nExamples:\n  $ paybond spend authorize --intent-id intent-123 --token cap --operation paid-tool",
+    "signal reputation": "Usage: paybond signal reputation --did <did>\n\nExamples:\n  $ paybond signal reputation --did did:example:alice",
+    "signal portfolio": "Usage: paybond signal portfolio\n\nExamples:\n  $ paybond signal portfolio",
+    "signal fraud": "Usage: paybond signal fraud --did <did>\n\nExamples:\n  $ paybond signal fraud --did did:example:alice",
+    "receipts get": "Usage: paybond receipts get <receipt_id>\n\nExamples:\n  $ paybond receipts get receipt-123",
+    "receipts verify": "Usage: paybond receipts verify <receipt_id>\n\nExamples:\n  $ paybond receipts verify receipt-123",
+    "mandates verify": "Usage: paybond mandates verify --body <json-file>\n\nExamples:\n  $ paybond mandates verify --body mandate.json",
+    "mandates import": "Usage: paybond mandates import --body <json-file>\n\nExamples:\n  $ paybond mandates import --body mandate.json",
+    "a2a card": "Usage: paybond a2a card\n\nExamples:\n  $ paybond a2a card",
+    "a2a contracts": "Usage: paybond a2a contracts [--contract-id <id>]\n\nExamples:\n  $ paybond a2a contracts",
+    "init agent-middleware": "Usage: paybond init agent-middleware [--framework <name>] [--out <path>] [--force]\n\nScaffolds an agent middleware integration file (PaybondAgentRun, tool registry, interceptor). Default framework is generic (agent-agnostic).\n\nExamples:\n  $ paybond init agent-middleware\n  $ paybond init agent-middleware --framework claude-agents --out paybond-claude-agents.ts\n  $ paybond init agent-middleware --framework openai --out paybond-agent-middleware.ts\n\nDocs: https://docs.paybond.ai/kit/agent-middleware\n\nNext: paybond agent sandbox smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --result-body '{\"status\":\"ok\",\"cost_cents\":100}'",
+    "agent run bind": "Usage: paybond agent run bind [--sandbox] [--production] [--policy-file <path>] [--watch] [--operation <name> --requested-spend-cents <n>] [--completion-preset <id>] [--registry-file <path>] [--run-id <id>] [--attach-intent-id <id> --capability-token <token> --payee-did <did> --payee-signing-seed-hex <hex> --agent-recognition-key-id <id> --agent-recognition-signing-seed-hex <hex>] [--write-env]\n\nBind a run-scoped middleware context via sandbox bootstrap or attach an existing funded intent. Production attach requires payee and agent-recognition signing credentials (flags or APP_PAYEE_DID, APP_PAYEE_SEED_HEX, APP_AGENT_RECOGNITION_KEY_ID, APP_AGENT_RECOGNITION_SEED_HEX). Persists context to .paybond/runs/<run_id>.json (mode 0600). Use --watch with --policy-file to record file-watcher reload config for long-lived processes.\n\nExamples:\n  $ paybond agent run bind --policy-file paybond.policy.yaml --format json\n  $ paybond agent run bind --sandbox --operation travel.book_hotel --requested-spend-cents 20000 --completion-preset cost_and_completion --registry-file ./paybond.agent.registry.yaml --format json\n\nDocs: https://docs.paybond.ai/kit/agent-policy\n\nNext: paybond agent tool execute --help",
+    "agent run status": "Usage: paybond agent run status --run-id <id>\n\nInspect a bound run (tenant, intent, allowed tools, policy digest, reload metadata).\n\nExamples:\n  $ paybond agent run status --run-id run-123 --format json\n\nDocs: https://docs.paybond.ai/kit/agent-middleware",
+    "agent run trace": "Usage: paybond agent run trace --run-id <id>\n\nShow middleware trace events for a bound run (tool selection, spend authorization, evidence, settlement). Reads .paybond/runs/<run_id>.trace.json written during tool execute.\n\nExamples:\n  $ paybond agent run trace --run-id run-123 --format json\n  $ paybond agent run trace --run-id run-123 --format table\n\nDocs: https://docs.paybond.ai/kit/agent-middleware#trace-events-and-observability",
+    "agent run reload-policy": "Usage: paybond agent run reload-policy --run-id <id> [--policy-file <path>] [--remote] [--resolve-inheritance] [--allow-loosen]\n\nReload policy for a persisted run without re-binding the intent. Validates locally and optionally via Gateway before swapping the registry.\n\nExamples:\n  $ paybond agent run reload-policy --run-id run-123 --format json\n  $ paybond agent run reload-policy --run-id run-123 --policy-file ./paybond.policy.yaml --remote --format json\n\nDocs: https://docs.paybond.ai/kit/policy-hot-reload",
+    "agent tool execute": "Usage: paybond agent tool execute --run-id <id> --operation <name> --tool-call-id <id> [--arguments <json>] --result-body <json>|--result-file <path>\n\nRun one tool through the middleware interceptor: authorize, simulated execute, auto-evidence. CLI supplies --result-body; external processes are not invoked in v1.\n\nExamples:\n  $ paybond agent tool execute --run-id run-123 --operation travel.book_hotel --tool-call-id call-1 --arguments '{\"city\":\"Lisbon\",\"estimated_price_cents\":18700}' --result-body '{\"reservation\":{\"status\":\"confirmed\",\"price_cents\":18700}}' --format json\n\nDocs: https://docs.paybond.ai/kit/agent-middleware",
+    "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> --evidence-preset <id>] --result-body <json>|--result-file <path>\n\nOne-shot end-to-end sandbox lifecycle: bind, tool execute, combined result. Ideal for CI and coding agents.\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 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",
+    "agent demo claude-agents smoke": "Usage: paybond agent demo claude-agents smoke [--production] [--runtime typescript|python] --operation <name> --requested-spend-cents <n> --evidence-preset <id>\n\nBundled no-LLM Claude Agent SDK sandbox demo: in-process MCP tool handlers, authorize, execute, and auto-evidence.\n\nExamples:\n  $ paybond agent demo claude-agents smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json\n\nDocs: https://docs.paybond.ai/kit/claude-agents",
+    "agent demo openai-agents smoke": "Usage: paybond agent demo openai-agents smoke [--production] --operation <name> --requested-spend-cents <n> --evidence-preset <id>\n\nBundled no-LLM OpenAI Agents SDK sandbox demo: input guardrail pre-check, guarded invoke, and auto-evidence.\n\nExamples:\n  $ paybond agent demo openai-agents smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json\n\nDocs: https://docs.paybond.ai/kit/openai-agents",
+    "audit exports list": "Usage: paybond audit exports list\n\nExamples:\n  $ paybond audit exports list --format json",
+    "audit exports get": "Usage: paybond audit exports get <job_id> [--issue-download]\n\nExamples:\n  $ paybond audit exports get job-123",
+    "audit exports verify": "Usage: paybond audit exports verify <path>\n\nExamples:\n  $ paybond audit exports verify ./bundle",
+    "audit exports delete": "Usage: paybond audit exports delete <job_id> [--yes]\n\nExamples:\n  $ paybond audit exports delete job-123 --yes",
+};
+export function helpForCommand(path) {
+    return COMMAND_HELP[path] ?? ROOT_HELP;
+}

package/dist/cli/mcp-install.d.ts

@@ -0,0 +1,41 @@
+import { type McpToolPolicyConfig } from "./mcp-policy.js";
+export type McpInstallFormat = "json" | "toml";
+export type McpInstallScope = "local" | "project" | "user";
+export type McpInstallHost = "claude" | "codex" | "openai" | "generic";
+export declare const MCP_INSTALL_HOSTS: readonly McpInstallHost[];
+export type McpServerEntry = {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+};
+export type McpInstallPlan = {
+    host: string;
+    scope: McpInstallScope;
+    format: McpInstallFormat;
+    envFile: string;
+    configPath: string | null;
+    serverCommand: string[];
+    payload: string;
+    printed: boolean;
+    toolPolicy?: McpToolPolicyConfig | null;
+};
+export declare function resolvePackageLocalMcpServerCommand(): string[];
+export declare function defaultMcpServerCommand(): string[];
+export declare function buildMcpServerEntry(envFile: string, serverCommand: string[], toolPolicy?: McpToolPolicyConfig | null): McpServerEntry;
+export declare function serializeMcpInstallPayload(format: McpInstallFormat, entry: McpServerEntry): string;
+export declare function resolveMcpInstallPath(scope: McpInstallScope, format: McpInstallFormat, out: string | undefined, cwd: string, home: string): string | null;
+export declare function defaultMcpInstallFormat(host: McpInstallHost): McpInstallFormat;
+export declare function planMcpInstall(input: {
+    host: McpInstallHost;
+    scope: McpInstallScope;
+    format: McpInstallFormat;
+    envFile: string;
+    out?: string;
+    cwd: string;
+    home: string;
+    serverCommand?: string[];
+    toolPolicy?: McpToolPolicyConfig | null;
+}): McpInstallPlan;
+export declare function parseMcpInstallHost(raw: string | undefined): McpInstallHost;
+export declare function parseMcpInstallFormat(raw: string | undefined, host: McpInstallHost): McpInstallFormat;
+export declare function parseMcpInstallScope(raw: string | undefined): McpInstallScope;

package/dist/cli/mcp-install.js

@@ -0,0 +1,95 @@
+import { fileURLToPath } from "node:url";
+import { mcpToolPolicyEnv, resolveMcpToolPolicy } from "./mcp-policy.js";
+export const MCP_INSTALL_HOSTS = ["claude", "codex", "openai", "generic"];
+export function resolvePackageLocalMcpServerCommand() {
+    const mcpServerJs = fileURLToPath(new URL("../mcp-server.js", import.meta.url));
+    return [process.execPath, mcpServerJs];
+}
+export function defaultMcpServerCommand() {
+    return resolvePackageLocalMcpServerCommand();
+}
+export function buildMcpServerEntry(envFile, serverCommand, toolPolicy) {
+    return {
+        command: serverCommand[0],
+        args: serverCommand.slice(1),
+        env: { PAYBOND_ENV_FILE: envFile, ...mcpToolPolicyEnv(resolveMcpToolPolicy(toolPolicy ?? { policy: null, allowlist: [] })) },
+    };
+}
+export function serializeMcpInstallPayload(format, entry) {
+    if (format === "toml") {
+        const argsJson = JSON.stringify(entry.args);
+        return [
+            "# Paybond MCP stdio server — merge into your host MCP config",
+            "[mcp_servers.paybond]",
+            `command = ${JSON.stringify(entry.command)}`,
+            `args = ${argsJson}`,
+            "",
+            "[mcp_servers.paybond.env]",
+            ...Object.entries(entry.env).map(([key, value]) => `${key} = ${JSON.stringify(value)}`),
+            "",
+        ].join("\n");
+    }
+    return `${JSON.stringify({
+        mcpServers: {
+            paybond: entry,
+        },
+    }, null, 2)}\n`;
+}
+export function resolveMcpInstallPath(scope, format, out, cwd, home) {
+    if (out?.trim()) {
+        return out.trim();
+    }
+    if (scope === "local") {
+        return null;
+    }
+    const ext = format === "toml" ? "toml" : "json";
+    const base = scope === "user" ? home : cwd;
+    return `${base.replace(/\/+$/, "")}/.paybond/mcp.${ext}`;
+}
+export function defaultMcpInstallFormat(host) {
+    return host === "codex" ? "toml" : "json";
+}
+export function planMcpInstall(input) {
+    const serverCommand = input.serverCommand ?? defaultMcpServerCommand();
+    const entry = buildMcpServerEntry(input.envFile, serverCommand, input.toolPolicy);
+    const payload = serializeMcpInstallPayload(input.format, entry);
+    const configPath = resolveMcpInstallPath(input.scope, input.format, input.out, input.cwd, input.home);
+    return {
+        host: input.host,
+        scope: input.scope,
+        format: input.format,
+        envFile: input.envFile,
+        configPath,
+        serverCommand,
+        payload,
+        printed: configPath === null,
+        toolPolicy: input.toolPolicy ?? null,
+    };
+}
+export function parseMcpInstallHost(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    if (!value) {
+        throw new Error("missing --host (expected claude|codex|openai|generic)");
+    }
+    if (MCP_INSTALL_HOSTS.includes(value)) {
+        return value;
+    }
+    throw new Error("invalid --host (expected claude|codex|openai|generic)");
+}
+export function parseMcpInstallFormat(raw, host) {
+    if (!raw?.trim()) {
+        return defaultMcpInstallFormat(host);
+    }
+    const value = raw.trim().toLowerCase();
+    if (value === "json" || value === "toml") {
+        return value;
+    }
+    throw new Error("invalid --format (expected json|toml)");
+}
+export function parseMcpInstallScope(raw) {
+    const value = (raw ?? "project").trim().toLowerCase();
+    if (value === "local" || value === "project" || value === "user") {
+        return value;
+    }
+    throw new Error("invalid --scope (expected local|project|user)");
+}

package/dist/cli/mcp-policy.d.ts

@@ -0,0 +1,26 @@
+export type McpToolPolicy = "readonly" | "spend-write" | "allowlist";
+export declare const MCP_TOOL_POLICY_ENV = "PAYBOND_MCP_TOOL_POLICY";
+export declare const MCP_TOOL_ALLOWLIST_ENV = "PAYBOND_MCP_TOOL_ALLOWLIST";
+export declare const DEFAULT_MCP_TOOL_POLICY: McpToolPolicy;
+export declare const LIVE_MONEY_TOOL_NAMES: Set<string>;
+export type McpToolPolicyConfig = {
+    policy: McpToolPolicy | null;
+    allowlist: readonly string[];
+};
+export declare function defaultMcpToolPolicyConfig(): McpToolPolicyConfig;
+export declare function resolveMcpToolPolicy(config: McpToolPolicyConfig): McpToolPolicyConfig;
+export type McpToolAnnotations = {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+};
+export declare function parseMcpToolPolicy(raw: string | undefined): McpToolPolicyConfig;
+export declare function parseMcpToolAllowlist(raw: string | undefined): string[];
+export declare function mergeMcpToolPolicy(policy: McpToolPolicyConfig, allowlist?: readonly string[]): McpToolPolicyConfig;
+export declare function mcpToolPolicyEnv(config: McpToolPolicyConfig): Record<string, string>;
+export declare function toolAnnotationsFlags(annotations: McpToolAnnotations | undefined): {
+    readOnly: boolean;
+    destructive: boolean;
+};
+export declare function toolAllowedByPolicy(name: string, annotations: McpToolAnnotations | undefined, config: McpToolPolicyConfig): boolean;
+export declare function validateMcpToolSchema(tool: Record<string, unknown>): string[];
+export declare function isLiveMoneyTool(name: string, annotations: McpToolAnnotations | undefined): boolean;