@paybond/kit 0.8.0 → 0.9.1

package/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+Paybond is the SDK to use when you do not want to build your own delegated agent spend-governance middleware. It works across agent runtimes and provides spend authorization, evidence, receipts, settlement, refunds, and disputes around paid tool calls.
+
 ## Install
 
 ```bash
@@ -64,16 +66,34 @@ try {
 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";
+import { Paybond } from "@paybond/kit";
+
+const paybond = await Paybond.open({
+  apiKey: process.env.PAYBOND_API_KEY!,
+  expectedEnvironment: "sandbox",
+});
 
-const binding = new PaybondCapabilityBinding(paybond.harbor, intentId, capabilityToken);
-const guard = new PaybondSpendGuard(binding);
+const created = await paybond.intents.create({
+  // principal, payee, budget, predicate, evidence schema, deadline...
+  allowedTools: ["travel.book_hotel"],
+  settlementRail: "stripe_connect",
+});
+
+const intentId = String(created.intent_id);
+const capabilityToken = String(created.capability_token ?? "");
+if (!capabilityToken) {
+  throw new Error("fund the intent before guarding tools");
+}
+
+const guard = paybond.spendGuard(intentId, capabilityToken);
 const guardedTool = guard.guardTool(
   { operation: "travel.book_hotel", requestedSpendCents: 20_000 },
   async (input) => bookHotel(input),
 );
 ```
 
+The `paybond.harbor` client is created by `Paybond.open(...)` and bound to the tenant resolved from the service-account API key. Normal integrations read `capability_token` from `paybond.intents.create(...)`, or from `paybond.intents.fund(...)` after an `x402_usdc_base` payment challenge is satisfied.
+
 Scaffold a wrapper:
 
 ```bash
@@ -89,7 +109,8 @@ Core SDK:
 - `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`
+- Runtime-neutral and framework aliases: `paybondAgentToolSpendGuard`, `paybondRuntimeNeutralToolSpendGuard`, `paybondLangGraphToolSpendGuard`, and `paybondMCPToolSpendGuard`
+- `paybondRuntimeToolCallAdapter` for agent SDKs and custom runtimes that expose a tool-call object plus an application-owned executor
 
 Gateway and trust helpers:
 
@@ -116,7 +137,7 @@ Gateway-backed protocol helpers throw `ProtocolHttpError` with parsed `errorCode
 ## What it does not include
 
 - No operator-tier settlement or console workflows
-- No model-provider-specific TypeScript agent wrapper; use the documented app-side wrapper pattern with `PaybondCapabilityBinding`
+- No model-provider-specific TypeScript agent wrapper; use the documented app-side wrapper pattern with `paybond.spendGuard(...)`
 - No model-provider-specific MCP wrapper; the MCP server is host-agnostic and works with any MCP-compatible runtime
 
 ## Docs

package/dist/index.d.ts

@@ -655,6 +655,11 @@ export declare class PaybondCapabilityBinding {
     verifySpendCapability(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
     authorizeSpend(input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
 }
+export type PaybondSpendGuardInit = {
+    harbor: Pick<HarborClient | GatewayHarborClient, "tenantId" | "verifyCapability">;
+    intentId: string;
+    capabilityToken: string;
+};
 export type PaybondSpendAuthorizationInput = {
     operation: string;
     requestedSpendCents?: number;
@@ -666,23 +671,33 @@ export declare class PaybondSpendDeniedError extends Error {
 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);
+    readonly harbor: Pick<HarborClient | GatewayHarborClient, "tenantId" | "verifyCapability">;
+    readonly intentId: string;
+    readonly capabilityToken: string;
+    constructor(init: PaybondSpendGuardInit | 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 function authorizeSpend(source: PaybondSpendGuardInit | PaybondCapabilityBinding, input: PaybondSpendAuthorizationInput): Promise<VerifyCapabilityResult>;
+export declare function guardTool<TArgs extends unknown[], TResult>(source: PaybondSpendGuardInit | PaybondCapabilityBinding, input: PaybondSpendAuthorizationInput, handler: PaybondToolHandler<TArgs, TResult>): PaybondGuardedToolHandler<TArgs, TResult>;
+export declare const paybondAgentToolSpendGuard: typeof guardTool;
+export declare const paybondRuntimeNeutralToolSpendGuard: typeof guardTool;
 export declare const paybondLangGraphToolSpendGuard: typeof guardTool;
 export declare const paybondMCPToolSpendGuard: typeof guardTool;
+export type PaybondRuntimeOperation<TCall> = string | ((call: TCall) => string);
+export type PaybondRuntimeSpendCents<TCall> = number | ((call: TCall) => number | undefined);
+export type PaybondRuntimeToolExecutor<TCall, TResult> = (call: TCall) => TResult | Promise<TResult>;
+export type PaybondRuntimeDenyHandler<TCall, TResult> = (result: VerifyCapabilityResult, call: TCall) => TResult | Promise<TResult>;
+export type PaybondRuntimeToolCallAdapterInit<TCall, TResult> = {
+    source: PaybondSpendGuardInit | PaybondCapabilityBinding;
+    operation: PaybondRuntimeOperation<TCall>;
+    execute: PaybondRuntimeToolExecutor<TCall, TResult>;
+    requestedSpendCents?: PaybondRuntimeSpendCents<TCall>;
+    onDeny?: PaybondRuntimeDenyHandler<TCall, TResult>;
+};
+export declare function paybondRuntimeToolCallAdapter<TCall, TResult>(init: PaybondRuntimeToolCallAdapterInit<TCall, TResult>): (call: TCall) => Promise<Awaited<TResult>>;
 export type PaybondOpenOptions = {
     apiKey: string;
     gatewayBaseUrl?: string;

package/dist/index.js

@@ -178,15 +178,24 @@ export class PaybondSpendDeniedError extends Error {
     }
 }
 export class PaybondSpendGuard {
-    binding;
-    constructor(binding) {
-        this.binding = binding;
+    harbor;
+    intentId;
+    capabilityToken;
+    constructor(init) {
+        this.harbor = init.harbor;
+        this.intentId = init.intentId;
+        this.capabilityToken = init.capabilityToken;
     }
     async verifySpendCapability(input) {
-        return this.binding.verifySpendCapability(input);
+        return this.harbor.verifyCapability({
+            intentId: this.intentId,
+            token: this.capabilityToken,
+            operation: input.operation,
+            requestedSpendCents: input.requestedSpendCents,
+        });
     }
     async authorizeSpend(input) {
-        return this.binding.authorizeSpend(input);
+        return this.verifySpendCapability(input);
     }
     async assertSpendAuthorized(input) {
         const result = await this.authorizeSpend(input);
@@ -202,20 +211,45 @@ export class PaybondSpendGuard {
         };
     }
 }
-export async function authorizeSpend(binding, input) {
-    return binding.authorizeSpend(input);
+export async function authorizeSpend(source, input) {
+    return new PaybondSpendGuard(source).authorizeSpend(input);
 }
-export function guardTool(binding, input, handler) {
-    return new PaybondSpendGuard(binding).guardTool(input, handler);
+export function guardTool(source, input, handler) {
+    return new PaybondSpendGuard(source).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 paybondAgentToolSpendGuard = guardTool;
+export const paybondRuntimeNeutralToolSpendGuard = guardTool;
 export const paybondLangGraphToolSpendGuard = guardTool;
 export const paybondMCPToolSpendGuard = guardTool;
+function resolveRuntimeOperation(operation, call) {
+    const value = typeof operation === "function" ? operation(call) : operation;
+    const trimmed = String(value).trim();
+    if (!trimmed) {
+        throw new Error("Paybond operation must be a non-empty string");
+    }
+    return trimmed;
+}
+function resolveRuntimeSpendCents(requestedSpendCents, call) {
+    if (requestedSpendCents === undefined) {
+        return undefined;
+    }
+    return typeof requestedSpendCents === "function" ? requestedSpendCents(call) : requestedSpendCents;
+}
+export function paybondRuntimeToolCallAdapter(init) {
+    const guard = new PaybondSpendGuard(init.source);
+    return async (call) => {
+        const operation = resolveRuntimeOperation(init.operation, call);
+        const requestedSpendCents = resolveRuntimeSpendCents(init.requestedSpendCents, call);
+        const result = await guard.authorizeSpend({ operation, requestedSpendCents });
+        if (!result.allow) {
+            if (init.onDeny) {
+                return await init.onDeny(result, call);
+            }
+            throw new PaybondSpendDeniedError(result);
+        }
+        return await init.execute(call);
+    };
+}
 /**
  * HTTP client for Harbor: capability verify, intents, evidence, and tenant-scoped ledger reads
  * (`GET /ledger/v1/*`, PAYBOND-007).
@@ -1790,7 +1824,7 @@ export class Paybond {
         await Promise.resolve();
     }
     spendGuard(intentId, capabilityToken) {
-        return new PaybondSpendGuard(new PaybondCapabilityBinding(this.harbor, intentId, capabilityToken));
+        return new PaybondSpendGuard({ harbor: this.harbor, intentId, capabilityToken });
     }
     async authorizeSpend(input) {
         return this.harbor.authorizeSpend(input);

package/dist/init.js

@@ -2,7 +2,7 @@
 const FRAMEWORKS = new Set([
     "generic",
     "provider-agnostic",
-    "openai-agents",
+    "openai",
     "claude",
     "anthropic",
     "gemini",
@@ -14,7 +14,7 @@ const FRAMEWORKS = new Set([
 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.",
+    openai: "Call the guarded handler before the OpenAI tool call performs paid or external work.",
     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.",
@@ -25,7 +25,7 @@ const FRAMEWORK_NOTES = {
 };
 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]",
+        "Usage: paybond-init [--framework generic|provider-agnostic|openai|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");
@@ -68,32 +68,58 @@ function parseArgs(argv) {
     return { framework, out, force };
 }
 function template(framework) {
-    return `import { Paybond, PaybondCapabilityBinding, PaybondSpendGuard } from "@paybond/kit";
+    return `import { Paybond, type FundIntentResult } from "@paybond/kit";
 
 type ToolInput = {
   city: string;
   maxPriceCents: number;
 };
 
+type FundedIntent = {
+  intentId: string;
+  capabilityToken: string;
+};
+
+export async function openPaybond(): Promise<Paybond> {
+  return Paybond.open({
+    apiKey: process.env.PAYBOND_API_KEY!,
+    expectedEnvironment: "sandbox",
+  });
+}
+
+export function fundedIntentFromCreate(created: Record<string, unknown>): FundedIntent {
+  const intentId = String(created["intent_id"] ?? "");
+  const capabilityToken = String(created["capability_token"] ?? "");
+  if (!intentId) {
+    throw new Error("intent create response missing intent_id");
+  }
+  if (!capabilityToken) {
+    throw new Error("intent is not funded yet; call paybond.intents.fund(...) before guarding tools");
+  }
+  return { intentId, capabilityToken };
+}
+
+export function fundedIntentFromFund(funded: FundIntentResult): FundedIntent {
+  if (!funded.capabilityToken) {
+    throw new Error("intent funding did not return a capabilityToken yet");
+  }
+  return { intentId: funded.intentId, capabilityToken: funded.capabilityToken };
+}
+
 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: {
+  paybond: Paybond;
   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);
+  if (!params.capabilityToken.trim()) {
+    throw new Error("fund the intent before guarding tools");
+  }
+  const guard = params.paybond.spendGuard(params.intentId, params.capabilityToken);
 
   // ${FRAMEWORK_NOTES[framework]}
   return guard.guardTool(

package/dist/mcp-server.js

@@ -364,6 +364,8 @@ export class PaybondMCPServer {
                             version: SERVER_VERSION,
                         },
                         instructions: "This MCP server is tenant-bound to the configured Paybond service-account API key. " +
+                            "Use paybond_create_spend_intent or paybond_fund_intent to obtain the intent_id and " +
+                            "capability_token, then call paybond_authorize_agent_spend before side-effecting tools. " +
                             "It works with any MCP-compatible host and does not assume a specific model provider.",
                     },
                 };
@@ -447,10 +449,13 @@ export class PaybondMCPServer {
             },
             {
                 name: "paybond_verify_capability",
-                description: "Verify a capability token for one tenant-bound Harbor intent through the gateway compatibility route.",
+                description: "Verify a capability token returned by a created or funded Paybond intent for one tenant-bound Harbor intent.",
                 inputSchema: objectSchema({
                     intent_id: { type: "string", description: "Canonical Harbor intent UUID." },
-                    token: { type: "string", description: "Capability token to verify." },
+                    token: {
+                        type: "string",
+                        description: "Capability token returned by paybond_create_spend_intent or paybond_fund_intent.",
+                    },
                     operation: { type: "string", description: "Delegated operation or tool name." },
                     requested_spend_cents: {
                         type: "integer",
@@ -468,10 +473,13 @@ export class PaybondMCPServer {
             },
             {
                 name: "paybond_authorize_agent_spend",
-                description: "Authorize delegated agent spend before a side-effecting tool, paid API, vendor action, or settlement workflow executes.",
+                description: "Provider-agnostic spend gate: verify the funded intent's capability token 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." },
+                    token: {
+                        type: "string",
+                        description: "Capability token returned by paybond_create_spend_intent or paybond_fund_intent.",
+                    },
                     operation: { type: "string", description: "Delegated operation or tool name." },
                     requested_spend_cents: {
                         type: "integer",
@@ -653,7 +661,7 @@ export class PaybondMCPServer {
             },
             {
                 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.",
+                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. If the selected rail funds immediately, use the returned intent_id and capability_token with paybond_authorize_agent_spend.",
                 inputSchema: objectSchema({
                     body: { type: "object", additionalProperties: true },
                     recognition_proof: { type: "object", additionalProperties: true },
@@ -667,7 +675,7 @@ export class PaybondMCPServer {
             },
             {
                 name: "paybond_fund_intent",
-                description: "Advance Harbor funding through the gateway /harbor path with a replay-safe recognition proof.",
+                description: "Advance Harbor funding through the gateway /harbor path with a replay-safe recognition proof. When funding succeeds, use the returned capability_token with intent_id in paybond_authorize_agent_spend.",
                 inputSchema: objectSchema({
                     intent_id: { type: "string" },
                     recognition_proof: { type: "object", additionalProperties: true },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@paybond/kit",
-  "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.",
+  "version": "0.9.1",
+  "description": "Paybond Kit for TypeScript: agent spend governance for paid tool calls with spend authorization, evidence receipts, refunds, disputes, hosted Gateway sessions, and settlement.",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -42,12 +42,17 @@
     "kit",
     "agents",
     "agent-runtime",
+    "agent-spend-governance",
     "agent-spend-controls",
     "ai-agent-budget",
+    "paid-tool-calls",
+    "spend-authorization",
+    "evidence-receipts",
+    "refunds",
+    "disputes",
     "delegated-spend",
     "spend-guardrails",
     "tool-call-spend-limits",
-    "openai-agents",
     "gemini",
     "claude",
     "anthropic",