@paybond/kit 0.9.8 → 0.11.0

package/dist/init.js

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { runCli } from "./cli/router.js";
+import { getCompletionPreset, jsonLiteral } from "./completion-catalog.js";
 const FRAMEWORKS = new Set([
     "generic",
     "provider-agnostic",
@@ -11,7 +16,21 @@ const FRAMEWORKS = new Set([
     "langgraph",
     "mcp",
 ]);
-const PRESETS = new Set(["paid-tool-guard"]);
+const AGENT_MIDDLEWARE_FRAMEWORKS = new Set([
+    "generic",
+    "claude-agents",
+    "openai",
+    "langgraph",
+    "vercel-ai",
+]);
+const AGENT_MIDDLEWARE_FRAMEWORK_ALIASES = {
+    "provider-agnostic": "generic",
+};
+const PRESETS = new Set(["paid-tool-guard", "agent-middleware"]);
+const PRESET_DEFAULT_OUT = {
+    "paid-tool-guard": "paybond-paid-tool-guard.ts",
+    "agent-middleware": "paybond-agent-middleware.ts",
+};
 const FRAMEWORK_NOTES = {
     generic: "Wrap the returned function around any side-effecting tool handler.",
     "provider-agnostic": "Use the guarded handler with OpenAI, Gemini, Claude/Anthropic, local models, or any custom runtime.",
@@ -26,15 +45,41 @@ const FRAMEWORK_NOTES = {
 };
 function usage() {
     return [
-        "Usage: paybond-init [--preset paid-tool-guard] [--framework generic|provider-agnostic|openai|claude|anthropic|gemini|google-ai|vercel-ai|langgraph|mcp] [--out paybond-paid-tool-guard.ts] [--force]",
+        "Usage: paybond-init [--preset paid-tool-guard|agent-middleware] [--framework <name>] [--out <path>] [--force]",
+        "",
+        "Presets:",
+        "  paid-tool-guard     Per-tool guardTool helper (default)",
+        "  agent-middleware    PaybondAgentRun + tool registry middleware",
         "",
-        "Scaffolds a production-shaped Paybond guardrail integration helper.",
+        "Frameworks (paid-tool-guard): generic|provider-agnostic|openai|claude|anthropic|gemini|google-ai|vercel-ai|langgraph|mcp",
+        "Frameworks (agent-middleware): generic|claude-agents|openai|langgraph|vercel-ai",
     ].join("\n");
 }
+function normalizeAgentMiddlewareFramework(framework) {
+    const alias = AGENT_MIDDLEWARE_FRAMEWORK_ALIASES[framework];
+    if (alias) {
+        return alias;
+    }
+    if (!AGENT_MIDDLEWARE_FRAMEWORKS.has(framework)) {
+        throw new Error("invalid --framework for agent-middleware preset");
+    }
+    return framework;
+}
+function validateFrameworkForPreset(preset, framework) {
+    if (preset === "agent-middleware") {
+        normalizeAgentMiddlewareFramework(framework);
+        return;
+    }
+    if (!FRAMEWORKS.has(framework)) {
+        throw new Error("invalid --framework");
+    }
+}
 function parseArgs(argv) {
     let preset = "paid-tool-guard";
     let framework = "provider-agnostic";
-    let out = "paybond-paid-tool-guard.ts";
+    let frameworkExplicit = false;
+    let out = PRESET_DEFAULT_OUT["paid-tool-guard"];
+    let outExplicit = false;
     let force = false;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -54,15 +99,19 @@ function parseArgs(argv) {
                 throw new Error("invalid --preset");
             }
             preset = raw;
+            if (!outExplicit) {
+                out = PRESET_DEFAULT_OUT[preset];
+            }
             continue;
         }
         if (arg === "--framework") {
             const raw = argv[i + 1];
             i += 1;
-            if (!raw || !FRAMEWORKS.has(raw)) {
+            if (!raw) {
                 throw new Error("invalid --framework");
             }
             framework = raw;
+            frameworkExplicit = true;
             continue;
         }
         if (arg === "--out") {
@@ -72,55 +121,22 @@ function parseArgs(argv) {
                 throw new Error("invalid --out");
             }
             out = raw;
+            outExplicit = true;
             continue;
         }
         throw new Error(`unknown argument: ${arg}`);
     }
+    if (preset === "agent-middleware" && !frameworkExplicit) {
+        framework = "generic";
+    }
+    validateFrameworkForPreset(preset, framework);
     return { preset, framework, out, force };
 }
-function template(framework) {
-    return `import {
-  Paybond,
-  type SandboxGuardrailBootstrapResult,
-  type SandboxGuardrailEvidenceResult,
-} from "@paybond/kit";
-
-declare const process: {
+function envHelpersBlock() {
+    return `declare const process: {
   env: Record<string, string | undefined>;
 };
 
-// Production integration helpers only. Add your paid-tool handler in
-// application code and pass it to wrapPaidTool(...).
-const DEFAULT_OPERATION = "paid_tool.operation";
-const DEFAULT_REQUESTED_SPEND_CENTS = 500;
-
-export type PaidToolHandler<TInput, TResult> = (input: TInput) => TResult | Promise<TResult>;
-
-export type SandboxGuardrailIntentOptions = {
-  operation?: string;
-  requestedSpendCents?: number;
-  currency?: string;
-  evidenceSchema?: Record<string, unknown>;
-  metadata?: Record<string, unknown>;
-  idempotencyKey?: string;
-};
-
-export type SubmitSandboxEvidenceOptions = {
-  operation?: string;
-  requestedSpendCents?: number;
-  metadata?: Record<string, unknown>;
-  artifacts?: string[];
-  idempotencyKey?: string;
-};
-
-export type OpenPaybondFromEnvOptions = {
-  /**
-   * Load PAYBOND_API_KEY from this local env file when the process environment
-   * does not already provide it. Pass false when your agent host injects secrets.
-   */
-  envFile?: string | false;
-};
-
 function readEnvValue(body: string, key: string): string | undefined {
   const pattern = new RegExp("^\\\\s*(?:export\\\\s+)?" + key + "\\\\s*=\\\\s*(.*)$", "m");
   const match = body.match(pattern);
@@ -139,8 +155,6 @@ function readEnvValue(body: string, key: string): string | undefined {
 }
 
 async function readTextFile(envFile: string): Promise<string | undefined> {
-  // @ts-ignore Node builtins are available in agent and CLI Node runtimes.
-  const fs: { readFile(path: string, encoding: "utf8"): Promise<string> } = await import("node:fs/promises");
   try {
     return await fs.readFile(envFile, "utf8");
   } catch (err) {
@@ -159,6 +173,14 @@ export async function loadPaybondEnvFile(envFile = ".env.local"): Promise<void>
   }
 }
 
+export type OpenPaybondFromEnvOptions = {
+  /**
+   * Load PAYBOND_API_KEY from this local env file when the process environment
+   * does not already provide it. Pass false when your agent host injects secrets.
+   */
+  envFile?: string | false;
+};
+
 export async function openPaybondFromEnv(options: OpenPaybondFromEnvOptions = {}): Promise<Paybond> {
   if (options.envFile !== false) {
     await loadPaybondEnvFile(options.envFile ?? ".env.local");
@@ -173,8 +195,293 @@ export async function openPaybondFromEnv(options: OpenPaybondFromEnvOptions = {}
     gatewayBaseUrl: process.env.PAYBOND_GATEWAY_URL ?? process.env.PAYBOND_GATEWAY_BASE_URL,
     expectedEnvironment: "sandbox",
   });
+}`;
+}
+function agentMiddlewareFrameworkBlock(framework) {
+    switch (framework) {
+        case "claude-agents":
+            return `import { tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import {
+  createGuardedAgent,
+  createGuardedAgentRunner,
+  type CreateGuardedAgentResult,
+} from "@paybond/kit/agent";
+
+const TRAVEL_AGENT_POLICY = {
+  version: 1,
+  name: "travel-agent-v1",
+  default_deny: true,
+  tools: {
+    "travel.book_hotel": {
+      side_effecting: true,
+      max_spend_cents: DEFAULT_REQUESTED_SPEND_CENTS,
+      evidence_preset: COMPLETION_PRESET_ID,
+    },
+    "search.web": {
+      side_effecting: false,
+    },
+  },
+  intent: {
+    allowed_tools: ["travel.book_hotel"],
+    budget: { currency: "usd", max_spend_usd: 200 },
+  },
+} as const;
+
+/** Policy-driven Claude Agent SDK wiring: bind run, wrap \`tool()\` handlers, expose MCP server config. */
+export async function createClaudeAgentsGuardedRunner(
+  paybond: Paybond,
+): Promise<CreateGuardedAgentResult> {
+  const sdkTools = [
+    tool(
+      "travel.book_hotel",
+      "Book a hotel room",
+      { city: z.string(), estimatedPriceCents: z.number().int().nonnegative() },
+      async (args) => ({
+        content: [{ type: "text" as const, text: JSON.stringify(await bookHotel(args)) }],
+        structuredContent: await bookHotel(args),
+      }),
+    ),
+  ];
+  return createGuardedAgent(paybond, {
+    policy: TRAVEL_AGENT_POLICY,
+    framework: "claude-agents",
+    tools: sdkTools,
+    bootstrap: {
+      operation: DEFAULT_OPERATION,
+      requestedSpendCents: DEFAULT_REQUESTED_SPEND_CENTS,
+      completionPreset: COMPLETION_PRESET_ID,
+    },
+  });
+}
+
+/** Alias matching {@link createGuardedAgentRunner} naming. */
+export const createClaudeAgentsGuardedAgentRunner = createClaudeAgentsGuardedRunner;
+
+export { createGuardedAgentRunner };`;
+        case "openai":
+            return `import { createOpenAIAgentsAdapter } from "@paybond/kit/openai-agents";
+import type { FunctionTool } from "@openai/agents";
+
+/** Wrap OpenAI Agents SDK function tools with Paybond middleware (verify → execute → auto-evidence). */
+export function wrapOpenAIAgentTools<TContext>(
+  run: PaybondAgentRun,
+  tools: Array<FunctionTool<TContext>>,
+): Array<FunctionTool<TContext>> {
+  return createOpenAIAgentsAdapter(run).guardFunctionTools(tools);
+}`;
+        case "langgraph":
+            return `import { paybondAwrapToolCall, paybondToolNode } from "@paybond/kit/langgraph";
+import type { PaybondAgentRun } from "@paybond/kit/agent";
+
+/** LangGraph ToolNode hook — use with \`paybondToolNode(tools, run)\` or \`new ToolNode(tools, { awrapToolCall })\` when supported. */
+export function createLangGraphToolCallWrapper(run: PaybondAgentRun) {
+  return paybondAwrapToolCall(run);
+}
+
+/** Convenience factory around LangGraph \`ToolNode\` with Paybond interceptor wiring. */
+export function createPaybondLangGraphToolNode(
+  run: PaybondAgentRun,
+  tools: Parameters<typeof paybondToolNode>[0],
+) {
+  return paybondToolNode(tools, run);
+}`;
+        case "vercel-ai":
+            return `import { generateText, tool } from "ai";
+import { z } from "zod";
+import {
+  paybondVercelToolApproval,
+  paybondVercelWrapTools,
+} from "@paybond/kit/vercel-ai";
+
+export function createGuardedVercelTools(run: PaybondAgentRun) {
+  const tools = {
+    bookHotel: tool({
+      description: "Book a hotel room",
+      inputSchema: z.object({
+        city: z.string(),
+        estimatedPriceCents: z.number().int().nonnegative(),
+      }),
+      execute: async (args) => bookHotel(args),
+    }),
+    searchWeb: tool({
+      description: "Search the web",
+      inputSchema: z.object({ query: z.string() }),
+      execute: async (args) => searchWeb(args),
+    }),
+  };
+  return paybondVercelWrapTools(run, tools);
+}
+
+/** Example \`generateText\` wiring with Paybond \`toolApproval\` + wrapped tools. */
+export async function runGuardedGenerateText(
+  run: PaybondAgentRun,
+  model: Parameters<typeof generateText>[0]["model"],
+  prompt: string,
+) {
+  const tools = createGuardedVercelTools(run);
+  return generateText({
+    model,
+    tools,
+    toolApproval: paybondVercelToolApproval(run),
+    prompt,
+  });
+}`;
+        default:
+            return `import { createPaybondGenericAgentConfig } from "@paybond/kit/agent";
+
+/** Recommended default when the agent framework is unknown. */
+export function createGenericAgentConfig(
+  run: PaybondAgentRun,
+  tools: Array<{ name: string; execute: (args: unknown) => unknown | Promise<unknown> }>,
+) {
+  return createPaybondGenericAgentConfig(run, tools);
+}
+
+/** Wrap \`{ name, execute }\` tools for any agent-agnostic runtime. */
+export function wrapAgentTools(
+  run: PaybondAgentRun,
+  tools: Array<{ name: string; execute: (args: unknown) => unknown | Promise<unknown> }>,
+) {
+  return createGenericAgentConfig(run, tools).tools;
+}`;
+    }
+}
+function agentMiddlewareTemplate(framework) {
+    const completionPreset = getCompletionPreset("cost_and_completion");
+    const evidenceSchema = jsonLiteral(completionPreset.evidence_schema, 2);
+    return `import fs from "node:fs/promises";
+import { Paybond } from "@paybond/kit";
+import {
+  createPaybondToolRegistry,
+  type PaybondAgentRun,
+  type PaybondAgentRunBindInput,
+} from "@paybond/kit/agent";
+
+${envHelpersBlock()}
+
+// Agent middleware preset maps to completion catalog archetype: cost_and_completion (${completionPreset.harbor_template_id}).
+const COMPLETION_PRESET_ID = "cost_and_completion";
+const DEFAULT_OPERATION = "travel.book_hotel";
+const DEFAULT_REQUESTED_SPEND_CENTS = 20_000;
+
+export type BookHotelArgs = {
+  city: string;
+  estimatedPriceCents: number;
+};
+
+export async function bookHotel(args: BookHotelArgs) {
+  return {
+    reservation: {
+      status: "confirmed" as const,
+      price_cents: args.estimatedPriceCents,
+      city: args.city,
+    },
+  };
+}
+
+export async function searchWeb(args: { query: string }) {
+  return { hits: [{ title: args.query, url: "https://example.com" }] };
+}
+
+export function createAgentToolRegistry() {
+  return createPaybondToolRegistry({
+    sideEffecting: {
+      "travel.book_hotel": {
+        spendCents: (args: BookHotelArgs) => args.estimatedPriceCents,
+        evidencePreset: COMPLETION_PRESET_ID,
+        evidenceMapper: (result: Awaited<ReturnType<typeof bookHotel>>) => ({
+          status: result.reservation.status === "confirmed" ? "completed" : result.reservation.status,
+          cost_cents: result.reservation.price_cents,
+        }),
+      },
+    },
+    defaultDeny: true,
+  });
+}
+
+export type BindAgentRunOptions = {
+  operation?: string;
+  requestedSpendCents?: number;
+  evidenceSchema?: Record<string, unknown>;
+  runId?: string;
+};
+
+export async function bindAgentRun(
+  paybond: Paybond,
+  registry: ReturnType<typeof createAgentToolRegistry>,
+  options: BindAgentRunOptions = {},
+): Promise<PaybondAgentRun> {
+  const bindInput: PaybondAgentRunBindInput = {
+    bootstrap: {
+      kind: "sandbox",
+      operation: options.operation ?? DEFAULT_OPERATION,
+      requestedSpendCents: options.requestedSpendCents ?? DEFAULT_REQUESTED_SPEND_CENTS,
+      completionPreset: COMPLETION_PRESET_ID,
+      evidenceSchema: options.evidenceSchema ?? ${evidenceSchema},
+    },
+    registry,
+    runId: options.runId,
+  };
+  return paybond.agentRun.bind(bindInput);
+}
+
+${agentMiddlewareFrameworkBlock(framework)}
+`;
+}
+function paidToolGuardTemplate(framework) {
+    const completionPreset = getCompletionPreset("cost_and_completion");
+    const evidenceSchema = jsonLiteral(completionPreset.evidence_schema, 2);
+    return `import fs from "node:fs/promises";
+import {
+  Paybond,
+  type SandboxGuardrailBootstrapResult,
+  type SandboxGuardrailEvidenceResult,
+} from "@paybond/kit";
+
+${envHelpersBlock()}
+
+// Paid-tool guardrail preset maps to completion catalog archetype: cost_and_completion (${completionPreset.harbor_template_id}).
+const COMPLETION_PRESET_ID = "cost_and_completion";
+const HARBOR_TEMPLATE_ID = "${completionPreset.harbor_template_id}";
+
+export type CompletionEvidence = {
+  status: string;
+  cost_cents: number;
+};
+
+export function buildCompletionEvidence(fields: CompletionEvidence): Record<string, unknown> {
+  return { ...fields };
 }
 
+// Production: use buildSignedCreateIntentBodyWithPolicyBinding from @paybond/kit after publishing ${completionPreset.harbor_template_id}.
+export const policyBindingStub = {
+  template_id: HARBOR_TEMPLATE_ID,
+  parameters: ${jsonLiteral(completionPreset.parameters, 2)} as const,
+};
+
+const DEFAULT_OPERATION = "paid_tool.operation";
+const DEFAULT_REQUESTED_SPEND_CENTS = 500;
+
+export type PaidToolHandler<TInput, TResult> = (input: TInput) => TResult | Promise<TResult>;
+
+export type SandboxGuardrailIntentOptions = {
+  operation?: string;
+  requestedSpendCents?: number;
+  currency?: string;
+  evidenceSchema?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  idempotencyKey?: string;
+};
+
+export type SubmitSandboxEvidenceOptions = {
+  operation?: string;
+  requestedSpendCents?: number;
+  metadata?: Record<string, unknown>;
+  artifacts?: string[];
+  idempotencyKey?: string;
+};
+
 export async function bootstrapSandboxGuardrailIntent(
   paybond: Paybond,
   options: SandboxGuardrailIntentOptions = {},
@@ -183,14 +490,8 @@ export async function bootstrapSandboxGuardrailIntent(
     operation: options.operation ?? DEFAULT_OPERATION,
     requestedSpendCents: options.requestedSpendCents ?? DEFAULT_REQUESTED_SPEND_CENTS,
     currency: options.currency ?? "usd",
-    evidenceSchema: options.evidenceSchema ?? {
-      type: "object",
-      required: ["confirmation_id", "charged_cents"],
-      properties: {
-        confirmation_id: { type: "string" },
-        charged_cents: { type: "integer" },
-      },
-    },
+    evidenceSchema: options.evidenceSchema ?? ${evidenceSchema},
+    completionPreset: COMPLETION_PRESET_ID,
     metadata: options.metadata,
     idempotencyKey: options.idempotencyKey,
   });
@@ -236,11 +537,20 @@ export async function submitSandboxEvidence(
     idempotencyKey: options.idempotencyKey,
   });
 }
+
+// Prefer buildCompletionEvidence({ status: "completed", cost_cents }) for catalog-aligned evidence.
 `;
 }
+function scaffoldBody(preset, framework) {
+    if (preset === "agent-middleware") {
+        return agentMiddlewareTemplate(normalizeAgentMiddlewareFramework(framework));
+    }
+    return paidToolGuardTemplate(framework);
+}
+function scaffoldLabel(preset) {
+    return preset === "agent-middleware" ? "agent middleware integration" : "guardrail integration";
+}
 async function writeScaffold(out, body, force) {
-    // @ts-expect-error Node builtins are available in the published CLI runtime.
-    const fs = await import("node:fs/promises");
     try {
         await fs.stat(out);
         if (!force) {
@@ -269,13 +579,13 @@ export async function main(argv = process.argv.slice(2)) {
         return 0;
     }
     try {
-        await writeScaffold(parsed.out, template(parsed.framework), parsed.force);
+        await writeScaffold(parsed.out, scaffoldBody(parsed.preset, parsed.framework), parsed.force);
     }
     catch (err) {
         process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
         return 1;
     }
-    process.stdout.write(`Created Paybond guardrail integration: ${parsed.out}\n`);
+    process.stdout.write(`Created Paybond ${scaffoldLabel(parsed.preset)}: ${parsed.out}\n`);
     return 0;
 }
 function normalizeFileURL(url) {
@@ -286,12 +596,6 @@ async function invokedFromCLI() {
     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 {
@@ -301,15 +605,23 @@ 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) => {
+    const argv = process.argv.slice(2);
+    const hasTemplateInit = argv.some((arg, index) => {
+        if (arg === "--template" || arg === "--repo") {
+            return Boolean(argv[index + 1]);
+        }
+        return false;
+    });
+    const initPath = hasTemplateInit ? ["init", ...argv] : ["init", "guardrail", ...argv];
+    runCli(initPath).then((code) => {
         process.exitCode = code;
     }, (err) => {
         process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);

package/dist/langgraph/awrap-tool-call.d.ts

@@ -0,0 +1,25 @@
+import { ToolMessage } from "@langchain/core/messages";
+import { type Command } from "@langchain/langgraph";
+import type { PaybondAgentRun } from "../agent/run.js";
+/** LangGraph `ToolCallRequest`-compatible shape used by Paybond interceptors. */
+export type PaybondLangGraphToolCallRequest = {
+    tool_call: {
+        name: string;
+        id?: string;
+        args?: Record<string, unknown>;
+    };
+};
+export type PaybondLangGraphAwrapToolCall = (request: PaybondLangGraphToolCallRequest, execute: (request: PaybondLangGraphToolCallRequest) => Promise<unknown>) => Promise<unknown>;
+export declare function normalizeLangGraphHookResult(call: {
+    name: string;
+    id?: string;
+}, result: unknown): ToolMessage | Command;
+/**
+ * Build a LangGraph `awrapToolCall` interceptor backed by {@link PaybondToolInterceptor}.
+ *
+ * Prefer this over manual `guardTool` wrappers when the agent run is bound with a tool registry
+ * (registry spend resolvers, auto-evidence, and `defaultDeny`).
+ */
+export declare function paybondAwrapToolCall(run: PaybondAgentRun): PaybondLangGraphAwrapToolCall;
+/** @deprecated Use {@link paybondAwrapToolCall}. */
+export declare const paybondAwrapToolCallCapability: typeof paybondAwrapToolCall;

package/dist/langgraph/awrap-tool-call.js

@@ -0,0 +1,81 @@
+import { ToolMessage } from "@langchain/core/messages";
+import { isCommand } from "@langchain/langgraph";
+import { PaybondAutoEvidenceSubmitError, PaybondUnregisteredSideEffectingToolError, } from "../agent/types.js";
+import { PaybondSpendApprovalRequiredError, PaybondSpendDeniedError, } from "../index.js";
+function toolCallFields(request) {
+    const call = request.tool_call;
+    return {
+        name: String(call.name ?? "").trim(),
+        toolCallId: String(call.id ?? "").trim(),
+        args: (call.args ?? {}),
+    };
+}
+function denyToolMessage(name, toolCallId, content) {
+    return new ToolMessage({
+        content,
+        name: name || "unknown",
+        tool_call_id: toolCallId,
+        status: "error",
+    });
+}
+function isToolMessage(value) {
+    return value instanceof ToolMessage;
+}
+export function normalizeLangGraphHookResult(call, result) {
+    if (isToolMessage(result) || isCommand(result)) {
+        return result;
+    }
+    return new ToolMessage({
+        status: "success",
+        name: call.name,
+        content: typeof result === "string" ? result : JSON.stringify(result),
+        tool_call_id: call.id ?? "",
+    });
+}
+/**
+ * Build a LangGraph `awrapToolCall` interceptor backed by {@link PaybondToolInterceptor}.
+ *
+ * Prefer this over manual `guardTool` wrappers when the agent run is bound with a tool registry
+ * (registry spend resolvers, auto-evidence, and `defaultDeny`).
+ */
+export function paybondAwrapToolCall(run) {
+    return async (request, execute) => {
+        const { name, toolCallId, args } = toolCallFields(request);
+        if (!name) {
+            return denyToolMessage("unknown", toolCallId, "Paybond: tool call missing name");
+        }
+        if (!toolCallId) {
+            return denyToolMessage(name, "", "Paybond: tool call missing id");
+        }
+        try {
+            const wrapped = await run.interceptor.wrapExecute({
+                toolName: name,
+                toolCallId,
+                arguments: args,
+                execute: () => execute(request),
+            });
+            return wrapped.toolResult;
+        }
+        catch (err) {
+            if (err instanceof PaybondUnregisteredSideEffectingToolError) {
+                return denyToolMessage(name, toolCallId, `Paybond capability denied: unregistered side-effecting tool (${err.message})`);
+            }
+            if (err instanceof PaybondSpendApprovalRequiredError) {
+                const decisionId = err.result?.decisionId;
+                const suffix = decisionId ? ` (decision_id=${decisionId})` : "";
+                const msg = err.result?.message ?? err.result?.code ?? "approval required";
+                return denyToolMessage(name, toolCallId, `Paybond capability approval required: ${msg}${suffix}`);
+            }
+            if (err instanceof PaybondSpendDeniedError) {
+                const msg = err.result?.message ?? err.result?.code ?? "capability denied";
+                return denyToolMessage(name, toolCallId, `Paybond capability denied: ${msg}`);
+            }
+            if (err instanceof PaybondAutoEvidenceSubmitError) {
+                return denyToolMessage(name, toolCallId, `Paybond evidence submit failed: ${err.message}`);
+            }
+            throw err;
+        }
+    };
+}
+/** @deprecated Use {@link paybondAwrapToolCall}. */
+export const paybondAwrapToolCallCapability = paybondAwrapToolCall;

package/dist/langgraph/config.d.ts

@@ -0,0 +1,13 @@
+import type { ToolNodeOptions } from "@langchain/langgraph/prebuilt";
+import type { PaybondAgentRun } from "../agent/run.js";
+import { type PaybondLangGraphAwrapToolCall } from "./awrap-tool-call.js";
+import { paybondToolNode } from "./tool-node.js";
+/** LangGraph runner hooks: async tool-call wrapper and guarded `ToolNode` factory. */
+export type PaybondLangGraphHooks = {
+    awrapToolCall: PaybondLangGraphAwrapToolCall;
+    createToolNode: (tools: Parameters<typeof paybondToolNode>[0], options?: ToolNodeOptions) => ReturnType<typeof paybondToolNode>;
+};
+/**
+ * Framework runner helper for LangGraph `ToolNode` and `awrap_tool_call` integration.
+ */
+export declare function createPaybondLangGraphHooks(run: PaybondAgentRun): PaybondLangGraphHooks;