@paybond/kit 0.9.8 → 0.11.0

package/dist/langgraph/config.js

@@ -0,0 +1,11 @@
+import { paybondAwrapToolCall } from "./awrap-tool-call.js";
+import { paybondToolNode } from "./tool-node.js";
+/**
+ * Framework runner helper for LangGraph `ToolNode` and `awrap_tool_call` integration.
+ */
+export function createPaybondLangGraphHooks(run) {
+    return {
+        awrapToolCall: paybondAwrapToolCall(run),
+        createToolNode: (tools, options) => paybondToolNode(tools, run, options),
+    };
+}

package/dist/langgraph/index.d.ts

@@ -0,0 +1,4 @@
+export { createPaybondLangGraphHooks, type PaybondLangGraphHooks, } from "./config.js";
+export { paybondAwrapToolCall, paybondAwrapToolCallCapability, normalizeLangGraphHookResult, type PaybondLangGraphAwrapToolCall, type PaybondLangGraphToolCallRequest, } from "./awrap-tool-call.js";
+export { paybondToolNode } from "./tool-node.js";
+export { runLangGraphSandboxDemo, type RunLangGraphSandboxDemoInput, type RunLangGraphSandboxDemoResult, } from "./sandbox-demo.js";

package/dist/langgraph/index.js

@@ -0,0 +1,4 @@
+export { createPaybondLangGraphHooks, } from "./config.js";
+export { paybondAwrapToolCall, paybondAwrapToolCallCapability, normalizeLangGraphHookResult, } from "./awrap-tool-call.js";
+export { paybondToolNode } from "./tool-node.js";
+export { runLangGraphSandboxDemo, } from "./sandbox-demo.js";

package/dist/langgraph/sandbox-demo.d.ts

@@ -0,0 +1,40 @@
+import type { Paybond } from "../index.js";
+export type RunLangGraphSandboxDemoInput = {
+    paybond: Paybond;
+    operation?: string;
+    requestedSpendCents?: number;
+    evidencePreset?: string;
+    toolCallId?: string;
+};
+export type RunLangGraphSandboxDemoResult = {
+    bind: {
+        run_id: string;
+        tenant_id: string;
+        intent_id: string;
+        capability_token: string;
+        operation: string;
+        sandbox_lifecycle_status?: string;
+    };
+    authorization: {
+        allow: boolean;
+        audit_id?: string;
+        decision_id?: string;
+    };
+    tool_message: {
+        content: string;
+        status: string;
+        name: string;
+        tool_call_id: string;
+    };
+    evidence: {
+        submitted: boolean;
+        sandbox_lifecycle_status?: string;
+        predicate_passed?: boolean | null;
+        intent_state?: string;
+    };
+    intent_state?: string;
+};
+/**
+ * No-LLM LangGraph sandbox demo: `ToolNode` + Paybond interceptor + auto-evidence.
+ */
+export declare function runLangGraphSandboxDemo(input: RunLangGraphSandboxDemoInput): Promise<RunLangGraphSandboxDemoResult>;

package/dist/langgraph/sandbox-demo.js

@@ -0,0 +1,96 @@
+import { AIMessage } from "@langchain/core/messages";
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import { createPaybondToolRegistry } from "../agent/registry.js";
+import { paybondToolNode } from "./tool-node.js";
+async function executePaidTool(args) {
+    return { status: "completed", cost_cents: args.estimatedPriceCents };
+}
+/**
+ * No-LLM LangGraph sandbox demo: `ToolNode` + Paybond interceptor + auto-evidence.
+ */
+export async function runLangGraphSandboxDemo(input) {
+    const operation = (input.operation ?? "paid-tool").trim();
+    const requestedSpendCents = input.requestedSpendCents ?? 100;
+    const evidencePreset = (input.evidencePreset ?? "cost_and_completion").trim();
+    const toolCallId = (input.toolCallId ?? "langgraph-demo-1").trim();
+    const registry = createPaybondToolRegistry({
+        defaultDeny: true,
+        sideEffecting: {
+            [operation]: {
+                operation,
+                evidencePreset,
+                spendCents: (args) => typeof args === "object" &&
+                    args !== null &&
+                    "estimatedPriceCents" in args &&
+                    typeof args.estimatedPriceCents === "number"
+                    ? args.estimatedPriceCents
+                    : requestedSpendCents,
+                evidenceMapper: (result) => {
+                    const payload = result;
+                    return {
+                        status: payload.status,
+                        cost_cents: payload.cost_cents,
+                    };
+                },
+            },
+        },
+    });
+    const run = await input.paybond.agentRun.bind({
+        bootstrap: {
+            kind: "sandbox",
+            operation,
+            requestedSpendCents,
+            completionPreset: evidencePreset,
+        },
+        registry,
+    });
+    const paidTool = tool(executePaidTool, {
+        name: operation,
+        description: `Paid operation ${operation}`,
+        schema: z.object({
+            estimatedPriceCents: z.number().int().nonnegative(),
+        }),
+    });
+    const node = paybondToolNode([paidTool], run);
+    const fakeAi = new AIMessage({
+        content: "",
+        tool_calls: [
+            {
+                name: operation,
+                args: { estimatedPriceCents: requestedSpendCents },
+                id: toolCallId,
+                type: "tool_call",
+            },
+        ],
+    });
+    const out = await node.invoke([fakeAi]);
+    const messages = Array.isArray(out) ? out : out.messages;
+    const toolMessage = messages[messages.length - 1];
+    const sandboxStatus = run.binding.sandbox?.sandboxLifecycleStatus;
+    return {
+        bind: {
+            run_id: run.runId,
+            tenant_id: run.tenantId,
+            intent_id: run.intentId,
+            capability_token: run.capabilityToken,
+            operation,
+            sandbox_lifecycle_status: sandboxStatus,
+        },
+        authorization: {
+            allow: toolMessage.status !== "error",
+        },
+        tool_message: {
+            content: String(toolMessage.content),
+            status: String(toolMessage.status ?? "success"),
+            name: String(toolMessage.name ?? operation),
+            tool_call_id: String(toolMessage.tool_call_id ?? toolCallId),
+        },
+        evidence: {
+            submitted: toolMessage.status !== "error",
+            sandbox_lifecycle_status: sandboxStatus,
+            predicate_passed: toolMessage.status !== "error" ? true : null,
+        },
+        intent_state: sandboxStatus,
+    };
+}

package/dist/langgraph/tool-node.d.ts

@@ -0,0 +1,10 @@
+import type { DynamicTool, StructuredToolInterface } from "@langchain/core/tools";
+import type { RunnableToolLike } from "@langchain/core/runnables";
+import { ToolNode, type ToolNodeOptions } from "@langchain/langgraph/prebuilt";
+import type { PaybondAgentRun } from "../agent/run.js";
+type LangGraphTool = StructuredToolInterface | DynamicTool | RunnableToolLike;
+/**
+ * Convenience factory: `ToolNode` with Paybond spend guard + auto-evidence on every tool call.
+ */
+export declare function paybondToolNode(tools: LangGraphTool[], run: PaybondAgentRun, options?: ToolNodeOptions): ToolNode;
+export {};

package/dist/langgraph/tool-node.js

@@ -0,0 +1,38 @@
+import { ToolNode } from "@langchain/langgraph/prebuilt";
+import { normalizeLangGraphHookResult, paybondAwrapToolCall, } from "./awrap-tool-call.js";
+/**
+ * `ToolNode` subclass that runs {@link paybondAwrapToolCall} before each tool invocation.
+ *
+ * LangGraph JS does not yet expose `awrapToolCall` on `ToolNode`; this wrapper provides the
+ * same interceptor boundary as Python's `ToolNode(..., awrap_tool_call=...)`.
+ */
+class PaybondGuardedToolNode extends ToolNode {
+    awrap;
+    constructor(tools, run, options) {
+        super(tools, options);
+        this.awrap = paybondAwrapToolCall(run);
+    }
+    async runTool(call, config, state) {
+        const request = {
+            tool_call: {
+                name: call.name,
+                id: call.id,
+                args: (call.args ?? {}),
+            },
+        };
+        const execute = async (req) => super.runTool({
+            ...call,
+            name: req.tool_call.name,
+            id: req.tool_call.id ?? call.id,
+            args: req.tool_call.args ?? call.args,
+        }, config, state);
+        const result = await this.awrap(request, execute);
+        return normalizeLangGraphHookResult(call, result);
+    }
+}
+/**
+ * Convenience factory: `ToolNode` with Paybond spend guard + auto-evidence on every tool call.
+ */
+export function paybondToolNode(tools, run, options) {
+    return new PaybondGuardedToolNode(tools, run, options);
+}

package/dist/login.d.ts

@@ -10,6 +10,17 @@ export type LoginOptions = {
     noOpen: boolean;
     force: boolean;
 };
+export type LoginResult = {
+    envPath: string;
+    keyMasked: string;
+    keyWritten: true;
+    environment: DeviceEnvironment;
+    tenantId: string;
+    tenantUuid: string;
+    expiresAt?: string;
+    verificationUri: string;
+    userCode: string;
+};
 type FetchInput = string | URL;
 type FetchInit = {
     method?: string;
@@ -25,11 +36,13 @@ export type LoginDependencies = {
     stdout?: Writable;
     stderr?: Writable;
     now?: () => number;
+    /** When false, suppress human-readable progress lines (for JSON CLI output). */
+    humanOutput?: boolean;
 };
 export declare function parseArgs(argv: string[]): LoginOptions | "help";
 export declare function assertGitIgnored(envPath: string, cwd: string): Promise<void>;
 export declare function assertCanWriteEnvFile(envPath: string, force: boolean): Promise<void>;
 export declare function writeEnvFile(envPath: string, rawKey: string, force: boolean): Promise<void>;
-export declare function runLogin(options: LoginOptions, deps?: LoginDependencies): Promise<number>;
+export declare function runLogin(options: LoginOptions, deps?: LoginDependencies): Promise<LoginResult>;
 export declare function main(argv?: string[], deps?: LoginDependencies): Promise<number>;
 export {};

package/dist/login.js

@@ -1,10 +1,31 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { runCli } from "./cli/router.js";
+import { requireSecureGatewayUrl } from "./gateway-url.js";
 const DEFAULT_GATEWAY = "https://api.paybond.ai";
 const DEFAULT_ENV_FILE = ".env.local";
 const CLIENT_ID = "paybond-kit-cli";
 const CLIENT_NAME = "Paybond CLI";
 const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
 const MIN_POLL_INTERVAL_SECONDS = 1;
+const DEFAULT_DEVICE_EXPIRES_IN_SECONDS = 600;
+const DEFAULT_DEVICE_POLL_INTERVAL_SECONDS = 5;
+const MS_PER_SECOND = 1_000;
+const DEVICE_EXPIRY_GRACE_MS = MS_PER_SECOND;
+const PROCESS_EXIT_SUCCESS = 0;
+const SPAWN_COMMAND_NOT_FOUND_EXIT_CODE = 127;
+const GIT_CHECK_IGNORE_MATCHED = PROCESS_EXIT_SUCCESS;
+const GIT_CHECK_IGNORE_NOT_MATCHED = 1;
+const MAX_GIT_WORKTREE_WALK_DEPTH = 256;
+const ENV_FILE_MODE = 0o600;
+const GITIGNORE_FILE_MODE = 0o644;
+const API_KEY_MASK_MIN_PARTS = 5;
+const API_KEY_MASK_MIN_ID_LENGTH = 12;
+const API_KEY_MASK_ID_PREFIX_LENGTH = 8;
+const API_KEY_MASK_ID_SUFFIX_LENGTH = 4;
 class PaybondLoginError extends Error {
     constructor(message) {
         super(message);
@@ -104,6 +125,12 @@ export function parseArgs(argv) {
     if (!gateway.trim()) {
         throw new PaybondLoginError("invalid --gateway");
     }
+    try {
+        gateway = requireSecureGatewayUrl(gateway);
+    }
+    catch (err) {
+        throw new PaybondLoginError(err instanceof Error ? err.message : String(err));
+    }
     return { envFile, gateway, environment, noOpen, force };
 }
 function envKeyPattern() {
@@ -127,19 +154,9 @@ function replaceOrAppendEnvValue(existing, rawKey, force) {
     const suffix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
     return `${existing}${suffix}${line}\n`;
 }
-async function pathModule() {
-    // @ts-expect-error Node builtins are available in the published CLI runtime.
-    return await import("node:path");
-}
-async function fsModule() {
-    // @ts-expect-error Node builtins are available in the published CLI runtime.
-    return await import("node:fs/promises");
-}
 async function spawnCommand(command, args, cwd) {
-    // @ts-expect-error Node builtins are available in the published CLI runtime.
-    const childProcess = await import("node:child_process");
     return await new Promise((resolve) => {
-        const child = childProcess.spawn(command, args, {
+        const child = spawn(command, args, {
             cwd,
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -152,7 +169,7 @@ async function spawnCommand(command, args, cwd) {
             stderr += String(chunk);
         });
         child.on("error", (err) => {
-            resolve({ code: 127, stdout: "", stderr: err.message });
+            resolve({ code: SPAWN_COMMAND_NOT_FOUND_EXIT_CODE, stdout: "", stderr: err.message });
         });
         child.on("close", (code) => {
             resolve({ code, stdout, stderr });
@@ -160,31 +177,55 @@ async function spawnCommand(command, args, cwd) {
     });
 }
 async function resolveEnvFile(envFile, cwd) {
-    const path = await pathModule();
     return path.isAbsolute(envFile) ? path.resolve(envFile) : path.resolve(cwd, envFile);
 }
 export async function assertGitIgnored(envPath, cwd) {
     await ensureGitIgnored(envPath, cwd, false);
 }
+async function inGitWorkTree(start) {
+    let current = path.resolve(start);
+    for (let depth = 0; depth < MAX_GIT_WORKTREE_WALK_DEPTH; depth += 1) {
+        try {
+            await fs.access(path.join(current, ".git"));
+            return true;
+        }
+        catch {
+            // continue walking parents
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return false;
+        }
+        current = parent;
+    }
+    return false;
+}
+function gitMissingForSecretWriteError() {
+    return new PaybondLoginError("git is required to verify the env file is ignored before writing secrets; install git or pass --env-file outside the repository");
+}
 async function ensureGitIgnored(envPath, cwd, autoAddDefaultEnvFile) {
-    const path = await pathModule();
-    const fs = await fsModule();
     const rootResult = await spawnCommand("git", ["rev-parse", "--show-toplevel"], cwd);
     if (rootResult.code !== 0) {
+        if (rootResult.code === SPAWN_COMMAND_NOT_FOUND_EXIT_CODE || /ENOENT/i.test(rootResult.stderr)) {
+            if (await inGitWorkTree(cwd)) {
+                throw gitMissingForSecretWriteError();
+            }
+        }
         return;
     }
     const repoRoot = await fs.realpath(path.resolve(rootResult.stdout.trim()));
     const targetDir = await fs.realpath(path.dirname(path.resolve(envPath)));
     const target = path.resolve(targetDir, path.basename(envPath));
     const relativeTarget = path.relative(repoRoot, target);
-    if (relativeTarget !== "" && (relativeTarget.startsWith("..") || path.isAbsolute(relativeTarget))) {
+    if (relativeTarget !== "" &&
+        (relativeTarget.startsWith("..") || path.isAbsolute(relativeTarget))) {
         return;
     }
     const ignoreResult = await spawnCommand("git", ["-C", repoRoot, "check-ignore", "--quiet", "--", relativeTarget], cwd);
-    if (ignoreResult.code === 0) {
+    if (ignoreResult.code === GIT_CHECK_IGNORE_MATCHED) {
         return;
     }
-    if (ignoreResult.code === 1) {
+    if (ignoreResult.code === GIT_CHECK_IGNORE_NOT_MATCHED) {
         if (autoAddDefaultEnvFile && relativeTarget === DEFAULT_ENV_FILE) {
             const gitignorePath = path.resolve(repoRoot, ".gitignore");
             let existing = "";
@@ -192,14 +233,17 @@ async function ensureGitIgnored(envPath, cwd, autoAddDefaultEnvFile) {
                 existing = await fs.readFile(gitignorePath, "utf8");
             }
             catch (err) {
-                if (!(err && typeof err === "object" && "code" in err && err.code === "ENOENT")) {
+                if (!(err &&
+                    typeof err === "object" &&
+                    "code" in err &&
+                    err.code === "ENOENT")) {
                     throw err;
                 }
             }
             const suffix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-            await fs.writeFile(gitignorePath, `${existing}${suffix}${DEFAULT_ENV_FILE}\n`, { encoding: "utf8", mode: 0o644 });
+            await fs.writeFile(gitignorePath, `${existing}${suffix}${DEFAULT_ENV_FILE}\n`, { encoding: "utf8", mode: GITIGNORE_FILE_MODE });
             const recheck = await spawnCommand("git", ["-C", repoRoot, "check-ignore", "--quiet", "--", relativeTarget], cwd);
-            if (recheck.code === 0) {
+            if (recheck.code === GIT_CHECK_IGNORE_MATCHED) {
                 return;
             }
         }
@@ -208,7 +252,6 @@ async function ensureGitIgnored(envPath, cwd, autoAddDefaultEnvFile) {
     throw new PaybondLoginError(`Unable to verify git ignore status for ${target}: ${ignoreResult.stderr.trim() || "git check-ignore failed"}`);
 }
 export async function assertCanWriteEnvFile(envPath, force) {
-    const fs = await fsModule();
     try {
         const existing = await fs.readFile(envPath, "utf8");
         if (envKeyPattern().test(existing) && !force) {
@@ -216,26 +259,31 @@ export async function assertCanWriteEnvFile(envPath, force) {
         }
     }
     catch (err) {
-        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+        if (err &&
+            typeof err === "object" &&
+            "code" in err &&
+            err.code === "ENOENT") {
             return;
         }
         throw err;
     }
 }
 export async function writeEnvFile(envPath, rawKey, force) {
-    const fs = await fsModule();
     let existing = "";
     try {
         existing = await fs.readFile(envPath, "utf8");
     }
     catch (err) {
-        if (!(err && typeof err === "object" && "code" in err && err.code === "ENOENT")) {
+        if (!(err &&
+            typeof err === "object" &&
+            "code" in err &&
+            err.code === "ENOENT")) {
             throw err;
         }
     }
     const next = replaceOrAppendEnvValue(existing, rawKey, force);
-    await fs.writeFile(envPath, next, { encoding: "utf8", mode: 0o600 });
-    await fs.chmod(envPath, 0o600);
+    await fs.writeFile(envPath, next, { encoding: "utf8", mode: ENV_FILE_MODE });
+    await fs.chmod(envPath, ENV_FILE_MODE);
 }
 function gatewayUrl(base, path) {
     return `${base.trim().replace(/\/+$/, "")}${path}`;
@@ -278,7 +326,8 @@ async function postGatewayJson(fetchFn, gateway, path, body) {
     if (error) {
         throw new OAuthPollError({
             error,
-            error_description: stringField(parsed, "error_description") || stringField(parsed, "message"),
+            error_description: stringField(parsed, "error_description") ||
+                stringField(parsed, "message"),
             interval: numberField(parsed, "interval", 0) || undefined,
         });
     }
@@ -290,10 +339,12 @@ function toDeviceStartResponse(body) {
         user_code: stringField(body, "user_code"),
         verification_uri: stringField(body, "verification_uri"),
         verification_uri_complete: stringField(body, "verification_uri_complete") || undefined,
-        expires_in: numberField(body, "expires_in", 600),
-        interval: numberField(body, "interval", 5),
+        expires_in: numberField(body, "expires_in", DEFAULT_DEVICE_EXPIRES_IN_SECONDS),
+        interval: numberField(body, "interval", DEFAULT_DEVICE_POLL_INTERVAL_SECONDS),
     };
-    if (!response.device_code || !response.user_code || !response.verification_uri) {
+    if (!response.device_code ||
+        !response.user_code ||
+        !response.verification_uri) {
         throw new PaybondLoginError("Gateway device start response was missing required fields.");
     }
     return response;
@@ -332,11 +383,11 @@ async function startDeviceFlow(fetchFn, gateway, environment) {
     return toDeviceStartResponse(body);
 }
 async function pollDeviceToken(fetchFn, gateway, environment, start, deps) {
-    let intervalSeconds = Math.max(MIN_POLL_INTERVAL_SECONDS, Math.trunc(start.interval || 5));
-    const expiresAtMs = deps.now() + Math.max(1, start.expires_in) * 1000;
+    let intervalSeconds = Math.max(MIN_POLL_INTERVAL_SECONDS, Math.trunc(start.interval || DEFAULT_DEVICE_POLL_INTERVAL_SECONDS));
+    const expiresAtMs = deps.now() + Math.max(1, start.expires_in) * MS_PER_SECOND;
     for (;;) {
-        await deps.sleep(intervalSeconds * 1000);
-        if (deps.now() > expiresAtMs + 1000) {
+        await deps.sleep(intervalSeconds * MS_PER_SECOND);
+        if (deps.now() > expiresAtMs + DEVICE_EXPIRY_GRACE_MS) {
             throw new PaybondLoginError("Device authorization expired before approval.");
         }
         try {
@@ -372,10 +423,12 @@ async function pollDeviceToken(fetchFn, gateway, environment, start, deps) {
 function maskAPIKey(rawKey) {
     const trimmed = rawKey.trim();
     const parts = trimmed.split("_");
-    if (parts.length >= 5 && parts[0] === "paybond" && parts[1] === "sk") {
+    if (parts.length >= API_KEY_MASK_MIN_PARTS && parts[0] === "paybond" && parts[1] === "sk") {
         const environment = parts[2];
         const keyID = parts[3];
-        const redactedKeyID = keyID.length > 12 ? `${keyID.slice(0, 8)}...${keyID.slice(-4)}` : "redacted";
+        const redactedKeyID = keyID.length > API_KEY_MASK_MIN_ID_LENGTH
+            ? `${keyID.slice(0, API_KEY_MASK_ID_PREFIX_LENGTH)}...${keyID.slice(-API_KEY_MASK_ID_SUFFIX_LENGTH)}`
+            : "redacted";
         return `paybond_sk_${environment}_${redactedKeyID}`;
     }
     return "paybond_sk_...";
@@ -388,11 +441,12 @@ async function defaultOpenBrowser(url) {
     const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
     const args = platform === "win32" ? ["/c", "start", "", url] : [url];
     const result = await spawnCommand(command, args, process.cwd());
-    return result.code === 0;
+    return result.code === PROCESS_EXIT_SUCCESS;
 }
 export async function runLogin(options, deps = {}) {
     const cwd = deps.cwd ?? process.cwd();
     const stdout = deps.stdout ?? process.stdout;
+    const humanOutput = deps.humanOutput ?? true;
     const fetchFn = deps.fetch ?? fetch;
     const sleep = deps.sleep ?? defaultSleep;
     const now = deps.now ?? Date.now;
@@ -402,25 +456,40 @@ export async function runLogin(options, deps = {}) {
     await ensureGitIgnored(envPath, cwd, options.envFile === DEFAULT_ENV_FILE);
     const start = await startDeviceFlow(fetchFn, options.gateway, options.environment);
     const verificationUrl = start.verification_uri_complete || start.verification_uri;
-    stdout.write(`Paybond ${options.environment} login\n`);
-    stdout.write(`Verification URL: ${verificationUrl}\n`);
-    stdout.write(`Code: ${start.user_code}\n`);
-    if (!options.noOpen) {
-        const opened = await openBrowser(verificationUrl);
-        if (!opened) {
-            stdout.write(`Open the verification URL in a browser to approve this login.\n`);
+    if (humanOutput) {
+        stdout.write(`Paybond ${options.environment} login\n`);
+        stdout.write(`Verification URL: ${verificationUrl}\n`);
+        stdout.write(`Code: ${start.user_code}\n`);
+        if (!options.noOpen) {
+            const opened = await openBrowser(verificationUrl);
+            if (!opened) {
+                stdout.write(`Open the verification URL in a browser to approve this login.\n`);
+            }
         }
+        stdout.write(`Waiting for approval...\n`);
     }
-    stdout.write(`Waiting for approval...\n`);
     const token = await pollDeviceToken(fetchFn, options.gateway, options.environment, start, { sleep, now });
     await writeEnvFile(envPath, token.access_token, options.force);
-    stdout.write(`Wrote PAYBOND_API_KEY to ${envPath}\n`);
-    stdout.write(`Key: ${maskAPIKey(token.access_token)}\n`);
-    stdout.write(`Target ${token.environment} tenant: ${token.tenant_id} (${token.tenant_uuid})\n`);
-    if (token.expires_at) {
-        stdout.write(`This key auto-expires at ${token.expires_at}; re-run paybond login to mint a new one.\n`);
+    const keyMasked = maskAPIKey(token.access_token);
+    if (humanOutput) {
+        stdout.write(`Wrote PAYBOND_API_KEY to ${envPath}\n`);
+        stdout.write(`Key: ${keyMasked}\n`);
+        stdout.write(`Target ${token.environment} tenant: ${token.tenant_id} (${token.tenant_uuid})\n`);
+        if (token.expires_at) {
+            stdout.write(`This key auto-expires at ${token.expires_at}; re-run paybond login to mint a new one.\n`);
+        }
     }
-    return 0;
+    return {
+        envPath,
+        keyMasked,
+        keyWritten: true,
+        environment: options.environment,
+        tenantId: token.tenant_id,
+        tenantUuid: token.tenant_uuid,
+        expiresAt: token.expires_at || undefined,
+        verificationUri: verificationUrl,
+        userCode: start.user_code,
+    };
 }
 export async function main(argv = process.argv.slice(2), deps = {}) {
     let parsed;
@@ -430,7 +499,8 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
             (deps.stdout ?? process.stdout).write(`${usage()}\n`);
             return 0;
         }
-        return await runLogin(parsed, deps);
+        await runLogin(parsed, deps);
+        return 0;
     }
     catch (err) {
         (deps.stderr ?? process.stderr).write(`${err instanceof Error ? err.message : String(err)}\n`);
@@ -438,19 +508,15 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     }
 }
 function normalizeFileURL(url) {
-    return url.startsWith("file:///var/") ? url.replace("file:///var/", "file:///private/var/") : url;
+    return url.startsWith("file:///var/")
+        ? url.replace("file:///var/", "file:///private/var/")
+        : url;
 }
 async function invokedFromCLI() {
     const scriptPath = process.argv[1];
     if (!scriptPath) {
         return false;
     }
-    // @ts-ignore Node builtins are available in the published CLI runtime.
-    const fs = (await import("node:fs/promises"));
-    // @ts-ignore Node builtins are available in the published CLI runtime.
-    const path = (await import("node:path"));
-    // @ts-ignore Node builtins are available in the published CLI runtime.
-    const url = (await import("node:url"));
     async function realFileURL(filePath) {
         let resolved = path.resolve(filePath);
         try {
@@ -460,15 +526,16 @@ async function invokedFromCLI() {
             // If realpath fails, compare the absolute path. This keeps direct execution
             // working even when the script path disappears during process startup.
         }
-        return normalizeFileURL(url.pathToFileURL(resolved).href);
+        return normalizeFileURL(pathToFileURL(resolved).href);
     }
-    return (await realFileURL(scriptPath)) === (await realFileURL(url.fileURLToPath(import.meta.url)));
+    return ((await realFileURL(scriptPath)) ===
+        (await realFileURL(fileURLToPath(import.meta.url))));
 }
 invokedFromCLI().then((invoked) => {
     if (!invoked) {
         return;
     }
-    main().then((code) => {
+    runCli(["login", ...process.argv.slice(2)]).then((code) => {
         process.exitCode = code;
     }, (err) => {
         process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);

package/dist/mcp/index.d.ts

@@ -0,0 +1 @@
+export { createPaybondMcpToolSurface, type PaybondMcpToolSurface, type PaybondMcpToolSurfaceOptions, } from "./tool-surface.js";

package/dist/mcp/index.js

@@ -0,0 +1 @@
+export { createPaybondMcpToolSurface, } from "./tool-surface.js";

package/dist/mcp/tool-surface.d.ts

@@ -0,0 +1,25 @@
+import type { PaybondAgentRun } from "../agent/run.js";
+import { type McpInstallFormat, type McpServerEntry } from "../cli/mcp-install.js";
+import type { McpToolPolicyConfig } from "../cli/mcp-policy.js";
+export type PaybondMcpToolSurfaceOptions = {
+    /** Env file referenced by `PAYBOND_ENV_FILE` in the MCP host config (default `.env.local`). */
+    envFile?: string;
+    /** Override stdio server launch command (default: package-local `paybond-mcp-server`). */
+    serverCommand?: string[];
+    /** Optional MCP tool exposure policy for the stdio server process. */
+    toolPolicy?: McpToolPolicyConfig | null;
+};
+/** Stdio MCP host configuration derived from `paybond mcp install` patterns. */
+export type PaybondMcpToolSurface = {
+    serverConfig: McpServerEntry;
+    /** Serialize host config as JSON (Claude Desktop, generic) or TOML (Codex). */
+    installPayload: (format?: McpInstallFormat) => string;
+};
+/**
+ * Framework runner helper for external MCP hosts (Claude Desktop, Codex, generic stdio).
+ *
+ * The bound {@link PaybondAgentRun} establishes tenant/intent context for your app;
+ * the returned `serverConfig` is the stdio entry coding-agent hosts consume via
+ * `PAYBOND_ENV_FILE` (never raw API keys in host config files).
+ */
+export declare function createPaybondMcpToolSurface(_run: PaybondAgentRun, options?: PaybondMcpToolSurfaceOptions): PaybondMcpToolSurface;