@paybond/kit 0.7.0 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # `@paybond/kit`
 
-Paybond Kit for TypeScript is the npm package for tenant-bound Paybond integrations. It opens hosted Gateway sessions, verifies capability tokens, signs intent and evidence payloads, uses Stripe Connect or x402 / USDC-on-Base settlement rails, and reads tenant-scoped Signal, fraud, ledger, protocol, and A2A data.
+Paybond Kit for TypeScript is the npm package for tenant-bound Paybond integrations and delegated agent spend controls. It opens hosted Gateway sessions, verifies capability tokens, authorizes tool-call spend, signs intent and evidence payloads, uses Stripe Connect or x402 / USDC-on-Base settlement rails, reads tenant-scoped Signal, fraud, ledger, protocol, and A2A data, and includes agent-runtime integrations.
 
 ## Install
 
@@ -18,7 +18,6 @@ npm install @paybond/kit
 
 - Node.js 22+
 - A `paybond_sk_sandbox_...` or `paybond_sk_live_...` service-account API key
-- For capability verification: a funded intent id and a capability token minted for that intent
 - For intent creation or evidence submission: 32-byte Ed25519 signing seeds owned by your application
 
 Minimal environment for the quick start:
@@ -27,13 +26,6 @@ Minimal environment for the quick start:
 export PAYBOND_API_KEY="paybond_sk_sandbox_..."
 ```
 
-Optional, if you want the quick start to verify a capability:
-
-```bash
-export PAYBOND_INTENT_ID="00000000-0000-0000-0000-000000000000"
-export PAYBOND_CAPABILITY="base64-biscuit-token"
-```
-
 ## Tenant isolation
 
 Every session is bound to the tenant realm echoed by gateway-authenticated service-account introspection.
@@ -62,27 +54,32 @@ const paybond = await Paybond.open({
 
 try {
   console.log("tenant realm:", paybond.harbor.tenantId);
-
-  const intentId = process.env.PAYBOND_INTENT_ID;
-  const capability = process.env.PAYBOND_CAPABILITY;
-  if (intentId && capability) {
-    const verified = await paybond.harbor.verifyCapability({
-      intentId,
-      token: capability,
-      operation: "payments.capture",
-      requestedSpendCents: 18_700,
-    });
-
-    if (!verified.allow) {
-      throw new Error(`verify denied: ${verified.code ?? "deny"} ${verified.message ?? ""}`);
-    }
-    console.log("capability verified:", verified.auditId);
-  }
 } finally {
   await paybond.aclose();
 }
 ```
 
+## Agent spend controls
+
+Use Paybond Kit when an agent workflow needs delegated spend guardrails, tool-call budget checks, paid API or vendor action approval, evidence, release/refund logic, disputes, or audit-ready receipts.
+
+```ts
+import { PaybondCapabilityBinding, PaybondSpendGuard } from "@paybond/kit";
+
+const binding = new PaybondCapabilityBinding(paybond.harbor, intentId, capabilityToken);
+const guard = new PaybondSpendGuard(binding);
+const guardedTool = guard.guardTool(
+  { operation: "travel.book_hotel", requestedSpendCents: 20_000 },
+  async (input) => bookHotel(input),
+);
+```
+
+Scaffold a wrapper:
+
+```bash
+npx -p @paybond/kit paybond-init --framework provider-agnostic --out paybond-spend-guard.ts
+```
+
 ## What the package includes
 
 Core SDK:
@@ -91,6 +88,8 @@ Core SDK:
 - `HarborClient` for capability verification, intent creation, x402 funding, evidence submission, and ledger reads
 - `paybond.signal` and `paybond.fraud` on `Paybond` sessions opened from one service-account API key
 - `PaybondIntents` helpers for principal-signed intent creation, x402 funding, and payee-signed evidence submission
+- `PaybondSpendGuard`, `authorizeSpend`, and `guardTool` for spend-named wrappers around capability verification
+- Provider and framework aliases: `paybondOpenAIToolSpendGuard`, `paybondGeminiToolSpendGuard`, `paybondClaudeToolSpendGuard`, `paybondAnthropicToolSpendGuard`, `paybondGoogleAIToolSpendGuard`, `paybondVercelAIToolSpendGuard`, `paybondLangGraphToolSpendGuard`, and `paybondMCPToolSpendGuard`
 
 Gateway and trust helpers:
 
@@ -98,6 +97,7 @@ Gateway and trust helpers:
 - `GatewayFraudClient` and `ServiceAccountFraudSession` for tenant-scoped fraud assessments, review queues, review events, metrics, and release-gate config
 - Protocol-v2 helpers for mandate verification, replay-safe recognition proof verification, receipt reads, and A2A discovery
 - `paybond-mcp-server` for tenant-bound MCP tool exposure to any MCP-compatible host
+- `paybond-init` for generating a small spend guard wrapper
 
 Agent-facing surfaces are model-provider agnostic. Paybond verifies tool operations and tenant scope, not whether a tool call came from OpenAI, Anthropic, Gemini, a local model, or another runtime.
 

package/dist/index.d.ts

@@ -652,7 +652,37 @@ export declare class PaybondCapabilityBinding {
     readonly intentId: string;
     readonly capabilityToken: string;
     constructor(harbor: Pick<HarborClient | GatewayHarborClient, "tenantId" | "verifyCapability">, intentId: string, capabilityToken: string);
+    verifySpendCapability(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
+    authorizeSpend(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
 }
+export type PaybondSpendAuthorizationInput = {
+    operation: string;
+    requestedSpendCents?: number;
+};
+export declare class PaybondSpendDeniedError extends Error {
+    readonly result: VerifyCapabilityResult;
+    constructor(result: VerifyCapabilityResult);
+}
+export type PaybondToolHandler<TArgs extends unknown[], TResult> = (...args: TArgs) => TResult | Promise<TResult>;
+export type PaybondGuardedToolHandler<TArgs extends unknown[], TResult> = (...args: TArgs) => Promise<Awaited<TResult>>;
+export declare class PaybondSpendGuard {
+    readonly binding: PaybondCapabilityBinding;
+    constructor(binding: PaybondCapabilityBinding);
+    verifySpendCapability(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
+    authorizeSpend(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
+    assertSpendAuthorized(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
+    guardTool<TArgs extends unknown[], TResult>(input: PaybondSpendAuthorizationInput, handler: PaybondToolHandler<TArgs, TResult>): PaybondGuardedToolHandler<TArgs, TResult>;
+}
+export declare function authorizeSpend(binding: PaybondCapabilityBinding, input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
+export declare function guardTool<TArgs extends unknown[], TResult>(binding: PaybondCapabilityBinding, input: PaybondSpendAuthorizationInput, handler: PaybondToolHandler<TArgs, TResult>): PaybondGuardedToolHandler<TArgs, TResult>;
+export declare const paybondOpenAIToolSpendGuard: typeof guardTool;
+export declare const paybondAnthropicToolSpendGuard: typeof guardTool;
+export declare const paybondClaudeToolSpendGuard: typeof guardTool;
+export declare const paybondGeminiToolSpendGuard: typeof guardTool;
+export declare const paybondGoogleAIToolSpendGuard: typeof guardTool;
+export declare const paybondVercelAIToolSpendGuard: typeof guardTool;
+export declare const paybondLangGraphToolSpendGuard: typeof guardTool;
+export declare const paybondMCPToolSpendGuard: typeof guardTool;
 export type PaybondOpenOptions = {
     apiKey: string;
     gatewayBaseUrl?: string;
@@ -701,6 +731,18 @@ export declare class HarborClient {
         operation: string;
         requestedSpendCents?: number;
     }): Promise<VerifyCapabilityResult>;
+    verifySpendCapability(input: {
+        intentId: string;
+        token: string;
+        operation: string;
+        requestedSpendCents?: number;
+    }): Promise<VerifyCapabilityResult>;
+    authorizeSpend(input: {
+        intentId: string;
+        token: string;
+        operation: string;
+        requestedSpendCents?: number;
+    }): Promise<VerifyCapabilityResult>;
     /**
      * POST `/intents` with a principal-signed `CreateIntentRequest` JSON body.
      *
@@ -787,6 +829,18 @@ export declare class GatewayHarborClient {
         operation: string;
         requestedSpendCents?: number;
     }): Promise<VerifyCapabilityResult>;
+    verifySpendCapability(input: {
+        intentId: string;
+        token: string;
+        operation: string;
+        requestedSpendCents?: number;
+    }): Promise<VerifyCapabilityResult>;
+    authorizeSpend(input: {
+        intentId: string;
+        token: string;
+        operation: string;
+        requestedSpendCents?: number;
+    }): Promise<VerifyCapabilityResult>;
     createIntent(body: Record<string, unknown>, options: GatewayHarborMutationOptions): Promise<Record<string, unknown>>;
     fundIntent(intentId: string, options: GatewayHarborMutationOptions & {
         paymentSignature?: string;
@@ -962,6 +1016,9 @@ export declare class PaybondIntents {
     create(params: PaybondCreateIntentParams & {
         idempotencyKey?: string;
     }): Promise<Record<string, unknown>>;
+    createSpendIntent(params: PaybondCreateIntentParams & {
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
     /**
      * Advance Harbor `/intents/{id}/fund` for x402 / USDC-on-Base intents.
      */
@@ -993,6 +1050,13 @@ export declare class Paybond {
     static open(init: PaybondOpenOptions): Promise<Paybond>;
     /** Reserved for future HTTP client cleanup; safe to call after work completes. */
     aclose(): Promise<void>;
+    spendGuard(intentId: string, capabilityToken: string): PaybondSpendGuard;
+    authorizeSpend(input: {
+        intentId: string;
+        token: string;
+        operation: string;
+        requestedSpendCents?: number;
+    }): Promise<VerifyCapabilityResult>;
 }
 export { normalizeJson, jsonValueDigest } from "./json-digest.js";
 export { buildSignedCreateIntentBody, intentCreationSignBytesRaw, type BuildSignedCreateIntentParams, type SettlementRail, } from "./principal-intent.js";

package/dist/index.js

@@ -156,7 +156,66 @@ export class PaybondCapabilityBinding {
         this.intentId = intentId;
         this.capabilityToken = capabilityToken;
     }
+    async verifySpendCapability(input) {
+        return this.harbor.verifyCapability({
+            intentId: this.intentId,
+            token: this.capabilityToken,
+            operation: input.operation,
+            requestedSpendCents: input.requestedSpendCents,
+        });
+    }
+    async authorizeSpend(input) {
+        return this.verifySpendCapability(input);
+    }
+}
+export class PaybondSpendDeniedError extends Error {
+    result;
+    constructor(result) {
+        const reason = result.message ?? result.code ?? "denied";
+        super(`Paybond spend authorization denied: ${reason}`);
+        this.name = "PaybondSpendDeniedError";
+        this.result = result;
+    }
 }
+export class PaybondSpendGuard {
+    binding;
+    constructor(binding) {
+        this.binding = binding;
+    }
+    async verifySpendCapability(input) {
+        return this.binding.verifySpendCapability(input);
+    }
+    async authorizeSpend(input) {
+        return this.binding.authorizeSpend(input);
+    }
+    async assertSpendAuthorized(input) {
+        const result = await this.authorizeSpend(input);
+        if (!result.allow) {
+            throw new PaybondSpendDeniedError(result);
+        }
+        return result;
+    }
+    guardTool(input, handler) {
+        return async (...args) => {
+            await this.assertSpendAuthorized(input);
+            return await handler(...args);
+        };
+    }
+}
+export async function authorizeSpend(binding, input) {
+    return binding.authorizeSpend(input);
+}
+export function guardTool(binding, input, handler) {
+    return new PaybondSpendGuard(binding).guardTool(input, handler);
+}
+export const paybondOpenAIToolSpendGuard = guardTool;
+export const paybondAnthropicToolSpendGuard = guardTool;
+export const paybondClaudeToolSpendGuard = guardTool;
+export const paybondGeminiToolSpendGuard = guardTool;
+export const paybondGoogleAIToolSpendGuard = guardTool;
+export const paybondVercelAIToolSpendGuard = guardTool;
+export const paybondLangGraphToolSpendGuard = guardTool;
+export const paybondMCPToolSpendGuard = guardTool;
 /**
  * HTTP client for Harbor: capability verify, intents, evidence, and tenant-scoped ledger reads
  * (`GET /ledger/v1/*`, PAYBOND-007).
@@ -329,6 +388,12 @@ export class HarborClient {
             message: body.message,
         };
     }
+    async verifySpendCapability(input) {
+        return this.verifyCapability(input);
+    }
+    async authorizeSpend(input) {
+        return this.verifyCapability(input);
+    }
     /**
      * POST `/intents` with a principal-signed `CreateIntentRequest` JSON body.
      *
@@ -653,6 +718,12 @@ export class GatewayHarborClient {
             message: body.message,
         };
     }
+    async verifySpendCapability(input) {
+        return this.verifyCapability(input);
+    }
+    async authorizeSpend(input) {
+        return this.verifyCapability(input);
+    }
     async createIntent(body, options) {
         const { res, text, url } = await this.postJSON("/harbor/intents", body, this.mutationHeaders("createIntent", options));
         if (!res.ok) {
@@ -1642,6 +1713,9 @@ export class PaybondIntents {
         });
         return this.harbor.createIntent(body, { idempotencyKey, recognitionProof });
     }
+    async createSpendIntent(params) {
+        return this.create(params);
+    }
     /**
      * Advance Harbor `/intents/{id}/fund` for x402 / USDC-on-Base intents.
      */
@@ -1715,6 +1789,12 @@ export class Paybond {
     async aclose() {
         await Promise.resolve();
     }
+    spendGuard(intentId, capabilityToken) {
+        return new PaybondSpendGuard(new PaybondCapabilityBinding(this.harbor, intentId, capabilityToken));
+    }
+    async authorizeSpend(input) {
+        return this.harbor.authorizeSpend(input);
+    }
 }
 export { normalizeJson, jsonValueDigest } from "./json-digest.js";
 export { buildSignedCreateIntentBody, intentCreationSignBytesRaw, } from "./principal-intent.js";

package/dist/init.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<number>;

package/dist/init.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+const FRAMEWORKS = new Set([
+    "generic",
+    "provider-agnostic",
+    "openai-agents",
+    "claude",
+    "anthropic",
+    "gemini",
+    "google-ai",
+    "vercel-ai",
+    "langgraph",
+    "mcp",
+]);
+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.",
+    "openai-agents": "Register the guarded handler where your OpenAI Agents tool handler is defined.",
+    claude: "Call the guarded handler before the Claude tool-use action performs paid or external work.",
+    anthropic: "Call the guarded handler before the Anthropic tool-use action performs paid or external work.",
+    gemini: "Call the guarded handler before the Gemini function call performs paid or external work.",
+    "google-ai": "Call the guarded handler before the Google AI function call performs paid or external work.",
+    "vercel-ai": "Call the guarded handler from your Vercel AI SDK tool execute function.",
+    langgraph: "Call the guarded handler from the LangGraph JS node or tool wrapper that performs paid work.",
+    mcp: "Call the guarded handler inside the MCP tool implementation before paid or external work runs.",
+};
+function usage() {
+    return [
+        "Usage: paybond-init [--framework generic|provider-agnostic|openai-agents|claude|anthropic|gemini|google-ai|vercel-ai|langgraph|mcp] [--out paybond-spend-guard.ts] [--force]",
+        "",
+        "Scaffolds a Paybond spend guard wrapper for delegated agent spend controls.",
+    ].join("\n");
+}
+function parseArgs(argv) {
+    let framework = "generic";
+    let out = "paybond-spend-guard.ts";
+    let force = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            process.stdout.write(`${usage()}\n`);
+            process.exitCode = 0;
+            return { framework, out, force };
+        }
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--framework") {
+            const raw = argv[i + 1];
+            i += 1;
+            if (!raw || !FRAMEWORKS.has(raw)) {
+                throw new Error("invalid --framework");
+            }
+            framework = raw;
+            continue;
+        }
+        if (arg === "--out") {
+            const raw = argv[i + 1];
+            i += 1;
+            if (!raw || raw.startsWith("-")) {
+                throw new Error("invalid --out");
+            }
+            out = raw;
+            continue;
+        }
+        throw new Error(`unknown argument: ${arg}`);
+    }
+    return { framework, out, force };
+}
+function template(framework) {
+    return `import { Paybond, PaybondCapabilityBinding, PaybondSpendGuard } from "@paybond/kit";
+
+type ToolInput = {
+  city: string;
+  maxPriceCents: number;
+};
+
+async function bookHotel(input: ToolInput): Promise<{ confirmation: string }> {
+  // Put the side-effecting tool call here.
+  return { confirmation: \`demo-\${input.city}-\${input.maxPriceCents}\` };
+}
+
+export async function buildGuardedHotelTool(params: {
+  intentId: string;
+  capabilityToken: string;
+}): Promise<(input: ToolInput) => Promise<{ confirmation: string }>> {
+  const paybond = await Paybond.open({
+    apiKey: process.env.PAYBOND_API_KEY!,
+    expectedEnvironment: "sandbox",
+  });
+  const binding = new PaybondCapabilityBinding(
+    paybond.harbor,
+    params.intentId,
+    params.capabilityToken,
+  );
+  const guard = new PaybondSpendGuard(binding);
+
+  // ${FRAMEWORK_NOTES[framework]}
+  return guard.guardTool(
+    {
+      operation: "travel.book_hotel",
+      requestedSpendCents: 20_000,
+    },
+    bookHotel,
+  );
+}
+`;
+}
+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) {
+            throw new Error(`${out} already exists; pass --force to overwrite`);
+        }
+    }
+    catch (err) {
+        if (!(err && typeof err === "object" && "code" in err && err.code === "ENOENT")) {
+            if (!force) {
+                throw err;
+            }
+        }
+    }
+    await fs.writeFile(out, body, "utf8");
+}
+export async function main(argv = process.argv.slice(2)) {
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n\n${usage()}\n`);
+        return 1;
+    }
+    if (argv.includes("--help") || argv.includes("-h")) {
+        return 0;
+    }
+    await writeScaffold(parsed.out, template(parsed.framework), parsed.force);
+    process.stdout.write(`Created ${parsed.out}\n`);
+    return 0;
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/mcp-server.js

@@ -466,6 +466,27 @@ export class PaybondMCPServer {
                         : intArg(args.requested_spend_cents, "requested_spend_cents"),
                 }),
             },
+            {
+                name: "paybond_authorize_agent_spend",
+                description: "Authorize delegated agent spend before a side-effecting tool, paid API, vendor action, or settlement workflow executes.",
+                inputSchema: objectSchema({
+                    intent_id: { type: "string", description: "Canonical Harbor intent UUID." },
+                    token: { type: "string", description: "Capability token to verify." },
+                    operation: { type: "string", description: "Delegated operation or tool name." },
+                    requested_spend_cents: {
+                        type: "integer",
+                        description: "Optional requested spend in cents for this tool call.",
+                    },
+                }, ["intent_id", "token", "operation"]),
+                call: async (args) => this.runtime.verifyCapability({
+                    intentId: uuidArg(args.intent_id, "intent_id"),
+                    token: stringArg(args.token, "token"),
+                    operation: stringArg(args.operation, "operation"),
+                    requestedSpendCents: args.requested_spend_cents === undefined
+                        ? 0
+                        : intArg(args.requested_spend_cents, "requested_spend_cents"),
+                }),
+            },
             {
                 name: "paybond_list_intents",
                 description: "List tenant-scoped Harbor intents through the gateway operator view with optional filters.",
@@ -630,6 +651,20 @@ export class PaybondMCPServer {
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
+            {
+                name: "paybond_create_spend_intent",
+                description: "Create a signed Paybond spend intent through the gateway /harbor route. Use this when an agent workflow needs bounded budget, allowed operations, evidence, and settlement review.",
+                inputSchema: objectSchema({
+                    body: { type: "object", additionalProperties: true },
+                    recognition_proof: { type: "object", additionalProperties: true },
+                    idempotency_key: { type: "string" },
+                }, ["body", "recognition_proof"]),
+                call: async (args) => this.runtime.createHarborIntent({
+                    body: ensureObject(args.body, "body"),
+                    recognitionProof: ensureObject(args.recognition_proof, "recognition_proof"),
+                    idempotencyKey: optionalString(args.idempotency_key),
+                }),
+            },
             {
                 name: "paybond_fund_intent",
                 description: "Advance Harbor funding through the gateway /harbor path with a replay-safe recognition proof.",
@@ -662,6 +697,22 @@ export class PaybondMCPServer {
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
+            {
+                name: "paybond_submit_spend_evidence",
+                description: "Submit signed evidence for a Paybond spend intent so release, refund, review, and receipt generation use the same audit-ready record.",
+                inputSchema: objectSchema({
+                    intent_id: { type: "string" },
+                    body: { type: "object", additionalProperties: true },
+                    recognition_proof: { type: "object", additionalProperties: true },
+                    idempotency_key: { type: "string" },
+                }, ["intent_id", "body", "recognition_proof"]),
+                call: async (args) => this.runtime.submitHarborEvidence({
+                    intentId: uuidArg(args.intent_id, "intent_id"),
+                    body: ensureObject(args.body, "body"),
+                    recognitionProof: ensureObject(args.recognition_proof, "recognition_proof"),
+                    idempotencyKey: optionalString(args.idempotency_key),
+                }),
+            },
             {
                 name: "paybond_confirm_settlement",
                 description: "Confirm Harbor settlement through the gateway /harbor path with a replay-safe recognition proof.",

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@paybond/kit",
-  "version": "0.7.0",
-  "description": "Paybond Kit for TypeScript: hosted Gateway sessions, capability verification, signed intent/evidence flows, and Stripe Connect or x402 / USDC-on-Base settlement.",
+  "version": "0.8.0",
+  "description": "Paybond Kit for TypeScript: agent spend controls, hosted Gateway sessions, capability verification, signed intent/evidence flows, and Stripe Connect or x402 / USDC-on-Base settlement.",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
+    "paybond-init": "dist/init.js",
     "paybond-mcp-server": "dist/mcp-server.js"
   },
   "exports": {
@@ -41,6 +42,15 @@
     "kit",
     "agents",
     "agent-runtime",
+    "agent-spend-controls",
+    "ai-agent-budget",
+    "delegated-spend",
+    "spend-guardrails",
+    "tool-call-spend-limits",
+    "openai-agents",
+    "gemini",
+    "claude",
+    "anthropic",
     "agent-payments",
     "escrow",
     "intent-escrow",