@paybond/kit 0.11.0 → 0.11.1

package/README.md

@@ -14,6 +14,23 @@ npm install @paybond/kit
 
 `@paybond/kit` is an ESM-only package for modern Node.js runtimes. Use `import` from a Node ESM / `NodeNext` project or a compatible bundler.
 
+### Optional framework integrations
+
+The core package is enough for Harbor sessions, spend guards, policy files, and `paybond agent sandbox smoke`. Install optional peers only when you import a framework subpath:
+
+| Subpath | Peer dependency |
+| --- | --- |
+| `@paybond/kit/vercel-ai` | `ai` |
+| `@paybond/kit/openai-agents` | `@openai/agents` |
+| `@paybond/kit/langgraph` | `@langchain/core`, `@langchain/langgraph` |
+| `@paybond/kit/claude-agents` | `@anthropic-ai/claude-agent-sdk` |
+
+```bash
+npm install ai @openai/agents @langchain/core @langchain/langgraph @anthropic-ai/claude-agent-sdk
+```
+
+Thin npm wrappers (`@paybond/vercel-ai`, `@paybond/langgraph`, `@paybond/openai-agents`, `@paybond/claude-agents`, `@paybond/agent`, `@paybond/mcp`) re-export the same subpaths for discoverability.
+
 ## Open source
 
 `@paybond/kit` is distributed as open-source software under the Apache 2.0 license. The published npm package includes the full license text in `LICENSE`.
@@ -32,9 +49,42 @@ npx -p @paybond/kit paybond login
 
 `paybond login` writes a sandbox `PAYBOND_API_KEY` to `.env.local` with file mode `0600`, adds the default `.env.local` target to `.gitignore` when needed, and refuses to overwrite an existing key unless `--force` is passed. Custom env-file paths inside a git repo must already be ignored. Live production keys are created by tenant admins in Console and stored in deployment secret managers.
 
+## CLI
+
+The package ships the `paybond` CLI (`paybond`, `paybond-init`, `paybond-kit-login`, `paybond-mcp-server`).
+
+Scaffold a starter project from bundled templates:
+
+```bash
+npx -p @paybond/kit paybond init --template travel-agent
+npm install
+npm run smoke
+```
+
+End-to-end sandbox smoke (bind + execute + evidence) with no app code:
+
+```bash
+npx -p @paybond/kit paybond agent sandbox smoke \
+  --policy-file paybond.policy.yaml \
+  --operation travel.book_hotel \
+  --requested-spend-cents 18700 \
+  --evidence-preset cost_and_completion \
+  --result-body '{"status":"completed","cost_cents":18700}' \
+  --format json
+```
+
+`agent sandbox smoke` only requires `@paybond/kit`. Framework demo commands (`agent demo vercel-ai smoke`, etc.) load their optional peers on demand.
+
+Offline local dev loop and trace dashboard:
+
+```bash
+npx -p @paybond/kit paybond dev loop --offline
+npx -p @paybond/kit paybond dev trace
+```
+
 ## First guardrail scaffold
 
-Use this first when you have a paid tool and want Paybond guardrails in the sandbox:
+Use this when you have a paid tool and want Paybond guardrails in the sandbox:
 
 ```bash
 npx -p @paybond/kit paybond-init \
@@ -114,15 +164,6 @@ await paybond.guardrails.submitSandboxEvidence({
 
 The `paybond.harbor` and `paybond.guardrails` clients are created by `Paybond.open(...)` and bound to the tenant resolved from the service-account API key. Production integrations read `capability_token` from `paybond.intents.create(...)`, or from `paybond.intents.fund(...)` after an `x402_usdc_base` payment challenge is satisfied.
 
-Scaffold a guardrail integration:
-
-```bash
-npx -p @paybond/kit paybond-init \
-  --preset paid-tool-guard \
-  --framework provider-agnostic \
-  --out paybond-paid-tool-guard.ts
-```
-
 ## What the package includes
 
 Core SDK:
@@ -135,6 +176,12 @@ Core SDK:
 - 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
 
+Agent middleware (`@paybond/kit/agent`) and framework subpaths (`vercel-ai`, `openai-agents`, `langgraph`, `claude-agents`, `mcp`, `policy`):
+
+- `PaybondAgentRun`, tool registry, interceptor, and policy-file binding
+- Framework adapters with optional peer dependencies (see table above)
+- `paybond init`, `paybond agent run bind`, `paybond agent tool execute`, and `paybond agent sandbox smoke`
+
 Gateway and trust helpers:
 
 - `GatewaySignalClient` and `ServiceAccountSignalSession` for tenant-scoped Signal reads and signed portfolio artifacts
@@ -146,10 +193,6 @@ Gateway and trust helpers:
 
 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.
 
-Advanced exports:
-
-- Low-level signing helpers for callers that need to pre-build signed request bodies or evidence payloads
-
 `allowedTools` values are your own tool or operation names, not a Paybond-owned catalog. Harbor enforces string matching against whatever names you chose when creating the intent.
 
 `settlementRail` on intent creation is a principal-signed rail request. Stripe destinations and x402 receive addresses stay tenant-owned server-side config and are never supplied by the SDK caller.
@@ -161,12 +204,13 @@ 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 `paybond.spendGuard(...)`
+- No bundled LLM or model runtime — bring your own agent framework and install optional peers when needed
 - No model-provider-specific MCP wrapper; the MCP server is host-agnostic and works with any MCP-compatible runtime
 
 ## Docs
 
 - Long-form docs: https://paybond.ai/docs/kit
+- Agent quickstart: https://paybond.ai/docs/kit/quickstart-agent
 - One-command guardrails: https://paybond.ai/docs/kit/one-command-guardrails
 - TypeScript quickstart: https://paybond.ai/docs/kit/quickstart-typescript
 - TypeScript SDK reference: https://paybond.ai/docs/kit/sdk-reference-typescript

package/dist/cli/agent/demo-loaders.d.ts

@@ -0,0 +1,4 @@
+export declare function loadRunVercelAiSandboxDemo(): Promise<typeof import("../../vercel-ai/sandbox-demo.js").runVercelAiSandboxDemo>;
+export declare function loadRunLangGraphSandboxDemo(): Promise<typeof import("../../langgraph/sandbox-demo.js").runLangGraphSandboxDemo>;
+export declare function loadRunClaudeAgentsSandboxDemo(): Promise<typeof import("../../claude-agents/sandbox-demo.js").runClaudeAgentsSandboxDemo>;
+export declare function loadRunOpenAIAgentsSandboxDemo(): Promise<typeof import("../../openai-agents/sandbox-demo.js").runOpenAIAgentsSandboxDemo>;

package/dist/cli/agent/demo-loaders.js

@@ -0,0 +1,66 @@
+import { CliError } from "../types.js";
+function missingPeerDependencyError(packageName, integration) {
+    return new CliError(`${integration} demo requires the optional peer dependency "${packageName}"; install it with: npm install ${packageName}`, {
+        category: "validation",
+        code: "cli.agent.missing_peer_dependency",
+        exitCode: 1,
+        details: { package: packageName, integration },
+    });
+}
+function isMissingModuleError(err, packageName) {
+    if (!(err instanceof Error)) {
+        return false;
+    }
+    const code = "code" in err ? String(err.code) : "";
+    return (code === "ERR_MODULE_NOT_FOUND" &&
+        err.message.includes(`'${packageName}'`));
+}
+export async function loadRunVercelAiSandboxDemo() {
+    try {
+        const mod = await import("../../vercel-ai/sandbox-demo.js");
+        return mod.runVercelAiSandboxDemo;
+    }
+    catch (err) {
+        if (isMissingModuleError(err, "ai")) {
+            throw missingPeerDependencyError("ai", "vercel-ai");
+        }
+        throw err;
+    }
+}
+export async function loadRunLangGraphSandboxDemo() {
+    try {
+        const mod = await import("../../langgraph/sandbox-demo.js");
+        return mod.runLangGraphSandboxDemo;
+    }
+    catch (err) {
+        if (isMissingModuleError(err, "@langchain/core") ||
+            isMissingModuleError(err, "@langchain/langgraph")) {
+            throw missingPeerDependencyError("@langchain/core @langchain/langgraph", "langgraph");
+        }
+        throw err;
+    }
+}
+export async function loadRunClaudeAgentsSandboxDemo() {
+    try {
+        const mod = await import("../../claude-agents/sandbox-demo.js");
+        return mod.runClaudeAgentsSandboxDemo;
+    }
+    catch (err) {
+        if (isMissingModuleError(err, "@anthropic-ai/claude-agent-sdk")) {
+            throw missingPeerDependencyError("@anthropic-ai/claude-agent-sdk", "claude-agents");
+        }
+        throw err;
+    }
+}
+export async function loadRunOpenAIAgentsSandboxDemo() {
+    try {
+        const mod = await import("../../openai-agents/sandbox-demo.js");
+        return mod.runOpenAIAgentsSandboxDemo;
+    }
+    catch (err) {
+        if (isMissingModuleError(err, "@openai/agents")) {
+            throw missingPeerDependencyError("@openai/agents", "openai-agents");
+        }
+        throw err;
+    }
+}

package/dist/cli/commands/agent.js

@@ -1,11 +1,8 @@
 import { resolve } from "node:path";
 import { readFile } from "node:fs/promises";
 import { PaybondAgentRun, PaybondAutoEvidenceSubmitError, PaybondToolRegistryValidationError, PaybondUnregisteredSideEffectingToolError, } from "../../agent/index.js";
-import { runVercelAiSandboxDemo } from "../../vercel-ai/sandbox-demo.js";
-import { runLangGraphSandboxDemo } from "../../langgraph/sandbox-demo.js";
 import { runGenericSandboxDemo } from "../../agent/generic-sandbox-demo.js";
-import { runClaudeAgentsSandboxDemo } from "../../claude-agents/sandbox-demo.js";
-import { runOpenAIAgentsSandboxDemo } from "../../openai-agents/sandbox-demo.js";
+import { loadRunClaudeAgentsSandboxDemo, loadRunLangGraphSandboxDemo, loadRunOpenAIAgentsSandboxDemo, loadRunVercelAiSandboxDemo, } from "../agent/demo-loaders.js";
 import { buildSmokeRegistry, loadAgentRegistryFile, validateAgentRegistryDocument, } from "../../agent/registry-file.js";
 import { createPaybondToolRegistry } from "../../agent/registry.js";
 import { devTraceStepsFromEvents, devTraceUrl, findDevTraceEventForRun, resolveDevTraceSink, recordSmokeTraceEvent, } from "../../dev/trace-buffer.js";
@@ -817,6 +814,7 @@ export async function handleAgentDemoVercelAiSmoke(ctx, argv) {
     }
     const requestedSpendCents = parseRequiredNonNegativeInt(spendFlag.value, "--requested-spend-cents");
     return withPaybondAgentCli(ctx, productionFlag.present, async (session) => {
+        const runVercelAiSandboxDemo = await loadRunVercelAiSandboxDemo();
         const demo = await runVercelAiSandboxDemo({
             paybond: session.paybond,
             operation: operationFlag.value,
@@ -858,6 +856,7 @@ export async function handleAgentDemoLanggraphSmoke(ctx, argv) {
     }
     const requestedSpendCents = parseRequiredNonNegativeInt(spendFlag.value, "--requested-spend-cents");
     return withPaybondAgentCli(ctx, productionFlag.present, async (session) => {
+        const runLangGraphSandboxDemo = await loadRunLangGraphSandboxDemo();
         const demo = await runLangGraphSandboxDemo({
             paybond: session.paybond,
             operation: operationFlag.value,
@@ -940,6 +939,7 @@ export async function handleAgentDemoClaudeAgentsSmoke(ctx, argv) {
     }
     const requestedSpendCents = parseRequiredNonNegativeInt(spendFlag.value, "--requested-spend-cents");
     return withPaybondAgentCli(ctx, productionFlag.present, async (session) => {
+        const runClaudeAgentsSandboxDemo = await loadRunClaudeAgentsSandboxDemo();
         const demo = await runClaudeAgentsSandboxDemo({
             paybond: session.paybond,
             operation: operationFlag.value,
@@ -976,6 +976,7 @@ export async function handleAgentDemoOpenAIAgentsSmoke(ctx, argv) {
     }
     const requestedSpendCents = parseRequiredNonNegativeInt(spendFlag.value, "--requested-spend-cents");
     return withPaybondAgentCli(ctx, productionFlag.present, async (session) => {
+        const runOpenAIAgentsSandboxDemo = await loadRunOpenAIAgentsSandboxDemo();
         const demo = await runOpenAIAgentsSandboxDemo({
             paybond: session.paybond,
             operation: operationFlag.value,

package/dist/dev/trace-buffer.js

@@ -306,7 +306,7 @@ export function recordSmokeTraceEvent(input, cwd) {
                 durationMs: 0,
                 recordedAt: new Date().toISOString(),
             },
-            ...((input.execute.evidence_submitted ?? input.execute.evidence)
+            ...(input.execute.evidence_submitted ?? input.execute.evidence
                 ? [
                     {
                         type: "evidence_submitted",

package/dist/mcp-server.js

@@ -13,7 +13,7 @@ import { McpCapabilityTokenCache, mcpToolStoresCapabilityToken, parseMcpCapabili
 import { createMcpPolicyGatewayAdapter, McpPolicyReloadGate, parseMcpPolicyReloadConfig, } from "./mcp-policy-reload.js";
 import { DEFAULT_PAYBOND_GATEWAY_BASE_URL, GatewayFraudClient, GatewaySignalClient, } from "./index.js";
 const SERVER_NAME = "Paybond MCP";
-const SERVER_VERSION = "0.11.0";
+const SERVER_VERSION = "0.11.1";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
 const DEFAULT_RECOGNITION_VERIFIER_ID = "paybond-gateway";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paybond/kit",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "mcpName": "io.github.nonameuserd/paybond",
   "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",

package/templates/manifest.json

@@ -13,7 +13,7 @@
       "evidence_preset": "cost_and_completion",
       "smoke_result_body": { "status": "completed", "cost_cents": 18700 },
       "dependencies": {
-        "@paybond/kit": "^0.11.0",
+        "@paybond/kit": "^0.11.1",
         "@langchain/core": "^1.2.1",
         "@langchain/langgraph": "^1.4.7",
         "zod": "^4.2.0"
@@ -33,7 +33,7 @@
       "evidence_preset": "cost_and_completion",
       "smoke_result_body": { "status": "completed", "cost_cents": 4500 },
       "dependencies": {
-        "@paybond/kit": "^0.11.0",
+        "@paybond/kit": "^0.11.1",
         "ai": "^5.0.0",
         "zod": "^4.2.0"
       },
@@ -52,7 +52,7 @@
       "evidence_preset": "cost_and_completion",
       "smoke_result_body": { "status": "completed", "cost_cents": 2900 },
       "dependencies": {
-        "@paybond/kit": "^0.11.0",
+        "@paybond/kit": "^0.11.1",
         "@openai/agents": "^0.4.0",
         "zod": "^4.2.0"
       },
@@ -71,7 +71,7 @@
       "evidence_preset": "cost_and_completion",
       "smoke_result_body": { "status": "completed", "cost_cents": 4500 },
       "dependencies": {
-        "@paybond/kit": "^0.11.0",
+        "@paybond/kit": "^0.11.1",
         "@openai/agents": "^0.4.0",
         "zod": "^4.2.0"
       },
@@ -90,7 +90,7 @@
       "evidence_preset": "cost_and_completion",
       "smoke_result_body": { "status": "completed", "cost_cents": 18700 },
       "dependencies": {
-        "@paybond/kit": "^0.11.0",
+        "@paybond/kit": "^0.11.1",
         "@anthropic-ai/claude-agent-sdk": "^0.2.100",
         "zod": "^4.2.0"
       },
@@ -110,7 +110,7 @@
       "evidence_preset": "cost_and_completion",
       "smoke_result_body": { "status": "completed", "cost_cents": 500 },
       "dependencies": {
-        "@paybond/kit": "^0.11.0"
+        "@paybond/kit": "^0.11.1"
       },
       "mcp_tool_policy": "spend-write"
     },
@@ -127,7 +127,7 @@
       "evidence_preset": "cost_and_completion",
       "smoke_result_body": { "status": "completed", "cost_cents": 12000 },
       "dependencies": {
-        "@paybond/kit": "^0.11.0"
+        "@paybond/kit": "^0.11.1"
       },
       "demo_mode": "generic"
     },
@@ -143,7 +143,7 @@
       "evidence_preset": "cost_and_completion",
       "smoke_result_body": { "status": "completed", "cost_cents": 12500 },
       "dependencies": {
-        "@paybond/kit": "^0.11.0"
+        "@paybond/kit": "^0.11.1"
       },
       "demo_mode": "generic"
     },
@@ -159,7 +159,7 @@
       "evidence_preset": "cost_and_completion",
       "smoke_result_body": { "status": "completed", "cost_cents": 2900 },
       "python_dependencies": {
-        "paybond-kit": ">=0.11.0",
+        "paybond-kit": ">=0.11.1",
         "langgraph": ">=1.2.0"
       },
       "demo_import": "paybond_kit.langgraph_sandbox_demo",

package/templates/openai-shopping-agent/.github/workflows/smoke.yml

@@ -14,7 +14,7 @@ jobs:
         with:
           node-version: "22"
           cache: npm
-      - run: npm install
+      - run: npm ci
       - run: npm run smoke
         env:
           PAYBOND_API_KEY: ${{ secrets.PAYBOND_SANDBOX_API_KEY }}