@paybond/kit 0.10.0 → 0.11.1

package/dist/mcp-server.js

@@ -4,11 +4,16 @@ import { readFileSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { requireSecureGatewayUrl } from "./gateway-url.js";
 import { runCli } from "./cli/router.js";
-import { MCP_TOOL_ALLOWLIST_ENV, MCP_TOOL_POLICY_ENV, mergeMcpToolPolicy, parseMcpToolAllowlist, parseMcpToolPolicy, toolAllowedByPolicy, } from "./cli/mcp-policy.js";
-import { GatewayAuthError, GatewayFraudClient, GatewaySignalClient, SignalHttpError, DEFAULT_PAYBOND_GATEWAY_BASE_URL, } from "./index.js";
+import { redactSensitiveFields } from "./cli/redact.js";
+import { MCP_TOOL_ALLOWLIST_ENV, MCP_TOOL_POLICY_ENV, mergeMcpToolPolicy, parseMcpToolAllowlist, parseMcpToolPolicy, resolveMcpToolPolicy, toolAllowedByPolicy, } from "./cli/mcp-policy.js";
+import { MCP_EVIDENCE_POLICY_ENV, McpEvidenceValidationGate, completionEvidenceValidationOk, extractHarborEvidenceValidationInput, extractSandboxGuardrailValidationInput, parseMcpEvidencePolicy, } from "./mcp-evidence-policy.js";
+import { McpCapabilityTokenCache, mcpToolStoresCapabilityToken, parseMcpCapabilityTokenCacheConfig, } from "./mcp-capability-token-cache.js";
+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.10.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";
@@ -98,6 +103,22 @@ const TOOL_SELECTION_METADATA = {
             "sandbox_lifecycle_status",
         ]),
     },
+    paybond_validate_completion_evidence: {
+        title: "Validate Completion Evidence",
+        description: "Pre-validates vendor and canonical completion evidence against catalog JSON Schemas and preset forbidden_evidence_fields. " +
+            "Required before evidence submit tools when PAYBOND_MCP_EVIDENCE_POLICY=strict. Harbor remains authoritative at submit time.",
+        annotations: readOnlyToolAnnotations("Validate Completion Evidence"),
+        outputSchema: outputObjectSchema({
+            preset_id: { type: "string" },
+            ok: { type: "boolean" },
+            vendor_schema_ok: { type: "boolean" },
+            canonical_schema_ok: { type: "boolean" },
+            quality_fields_missing: { type: "array", items: { type: "string" } },
+            forbidden_fields_present: { type: "array", items: { type: "string" } },
+            pack_stale: { type: "boolean" },
+            drift_kinds: { type: "array", items: { type: "string" } },
+        }, ["preset_id", "ok"]),
+    },
     paybond_submit_sandbox_guardrail_evidence: {
         title: "Submit Sandbox Guardrail Evidence",
         description: "Use this when a sandbox guardrail intent needs evidence to complete simulator settlement or predicate checks. " +
@@ -330,6 +351,13 @@ const TOOL_SELECTION_METADATA = {
         }),
     },
 };
+function readIntentAllowedTools(intent) {
+    const raw = intent.allowed_tools;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+}
 function readEnvFileValue(envFile, key) {
     let body;
     try {
@@ -473,7 +501,14 @@ class PaybondMCPRuntime {
     principalValue = null;
     signalValue = null;
     fraudValue = null;
+    capabilityTokenCache;
+    evidenceGate;
+    policyReloadConfig;
+    policyGatePromise = null;
     constructor(settings) {
+        this.evidenceGate = new McpEvidenceValidationGate(settings.evidencePolicy ?? parseMcpEvidencePolicy(undefined));
+        this.capabilityTokenCache = new McpCapabilityTokenCache(settings.capabilityTokenCache);
+        this.policyReloadConfig = settings.policyReload ?? null;
         this.settings = {
             gatewayBaseUrl: settings.gatewayBaseUrl ?? DEFAULT_PAYBOND_GATEWAY_BASE_URL,
             apiKey: settings.apiKey,
@@ -486,6 +521,102 @@ class PaybondMCPRuntime {
             maxRetries: this.settings.maxRetries,
         });
     }
+    async policyGate() {
+        if (!this.policyReloadConfig) {
+            return null;
+        }
+        this.policyGatePromise ??= McpPolicyReloadGate.open(this.policyReloadConfig, {
+            gateway: createMcpPolicyGatewayAdapter(this.gateway),
+        });
+        return this.policyGatePromise;
+    }
+    async getPolicyReloadStatus() {
+        const gate = await this.policyGate();
+        return gate?.status() ?? null;
+    }
+    async beginPolicyToolCall() {
+        const gate = await this.policyGate();
+        gate?.beginToolCall();
+    }
+    async endPolicyToolCall() {
+        const gate = await this.policyGate();
+        gate?.endToolCall();
+    }
+    stopPolicyReload() {
+        void this.policyGatePromise?.then((gate) => gate?.stop());
+        this.policyGatePromise = null;
+    }
+    async authorizeAgentSpend(init) {
+        const gate = await this.policyGate();
+        let operation = init.operation;
+        let requestedSpendCents = init.requestedSpendCents ?? 0;
+        let policyDigest;
+        if (gate) {
+            const intent = await this.getIntent(init.intentId);
+            const allowedTools = readIntentAllowedTools(intent);
+            const gated = gate.assertSpendGate({
+                toolName: init.toolName,
+                operation,
+                allowedTools,
+                requestedSpendCents: init.requestedSpendCents,
+            });
+            operation = gated.operation;
+            requestedSpendCents = gated.requestedSpendCents;
+            policyDigest = gated.policyDigest;
+        }
+        const body = await this.verifyCapability({
+            intentId: init.intentId,
+            token: init.token,
+            operation,
+            requestedSpendCents,
+        });
+        if (policyDigest) {
+            body.policy_digest = policyDigest;
+        }
+        return body;
+    }
+    storeCapabilityToken(intentId, token) {
+        this.capabilityTokenCache.store(intentId, token);
+    }
+    async resolveCapabilityToken(intentId, token) {
+        const explicit = token?.trim();
+        if (explicit) {
+            return explicit;
+        }
+        const stored = this.capabilityTokenCache.resolve(intentId.trim());
+        if (stored) {
+            return stored;
+        }
+        throw new Error(`capability token unavailable or expired for intent ${intentId}; create or bootstrap a funded intent first`);
+    }
+    prepareToolResponse(value, toolName) {
+        if (value === null) {
+            return null;
+        }
+        const intentId = String(value.intent_id ?? "").trim();
+        const token = value.capability_token;
+        if (mcpToolStoresCapabilityToken(toolName) &&
+            intentId &&
+            typeof token === "string" &&
+            token.trim()) {
+            this.storeCapabilityToken(intentId, token);
+        }
+        return redactSensitiveFields(value);
+    }
+    validateCompletionEvidence(input) {
+        const report = this.evidenceGate.validateAndRecord(input);
+        return {
+            ...report,
+            ok: completionEvidenceValidationOk(report),
+        };
+    }
+    requireEvidenceValidation(input) {
+        this.evidenceGate.requirePass(input);
+    }
+    /** Resolve and cache the gateway principal during MCP server startup. */
+    async preloadPrincipal() {
+        await this.principal();
+    }
     async principal() {
         this.principalValue ??= this.gateway.getJSON(this.settings.principalPath);
         const body = await this.principalValue;
@@ -588,6 +719,11 @@ class PaybondMCPRuntime {
         return body;
     }
     async submitSandboxGuardrailEvidence(init) {
+        const extracted = extractSandboxGuardrailValidationInput({
+            payload: init.payload,
+            completionPresetId: init.completionPresetId,
+        });
+        this.requireEvidenceValidation(extracted);
         const expectedTenant = await this.tenantId();
         const payload = {};
         if (init.payload !== undefined) {
@@ -625,7 +761,6 @@ class PaybondMCPRuntime {
         const verifier = {
             tenant_id: await this.tenantId(),
             verifier_id: DEFAULT_RECOGNITION_VERIFIER_ID,
-            ...(init.expectedVerifier ?? {}),
         };
         return this.gateway.postJSON("/protocol/v2/recognition/verify", {
             proof: init.proof,
@@ -690,6 +825,8 @@ class PaybondMCPRuntime {
         }));
     }
     async submitHarborEvidence(init) {
+        const extracted = extractHarborEvidenceValidationInput(init.body, init.completionPresetId);
+        this.requireEvidenceValidation(extracted);
         return this.gateway.postJSON(`/harbor/intents/${encodeURIComponent(init.intentId)}/evidence`, init.body, gatewayMutationHeaders(await this.tenantId(), init.recognitionProof, optionalMutationHeaders(init.idempotencyKey)));
     }
     async confirmHarborSettlement(init) {
@@ -722,7 +859,7 @@ export class PaybondMCPServer {
         if (!settings.apiKey.trim()) {
             throw new Error("PAYBOND_API_KEY is required");
         }
-        this.toolPolicy = settings.toolPolicy ?? { policy: null, allowlist: [] };
+        this.toolPolicy = resolveMcpToolPolicy(settings.toolPolicy ?? { policy: null, allowlist: [] });
         this.runtime = new PaybondMCPRuntime(settings);
         this.tools = this.buildTools(settings).filter((tool) => toolAllowedByPolicy(tool.name, tool.annotations, this.toolPolicy));
     }
@@ -753,15 +890,21 @@ export class PaybondMCPServer {
                 content: [
                     {
                         type: "text",
-                        text: `Tool blocked by ${MCP_TOOL_POLICY_ENV}=${this.toolPolicy.policy ?? "unset"}: ${name}`,
+                        text: `Tool blocked by ${MCP_TOOL_POLICY_ENV}=${this.toolPolicy.policy ?? "spend-write"}: ${name}`,
                     },
                 ],
                 isError: true,
             };
         }
         try {
-            const value = await tool.call(args);
-            return toToolResult(value);
+            await this.runtime.beginPolicyToolCall();
+            try {
+                const value = await tool.call(args);
+                return toToolResult(this.runtime.prepareToolResponse(value === null ? null : value, name));
+            }
+            finally {
+                await this.runtime.endPolicyToolCall();
+            }
         }
         catch (err) {
             return {
@@ -787,6 +930,7 @@ export class PaybondMCPServer {
         }
         switch (method) {
             case "initialize":
+                await this.runtime.preloadPrincipal();
                 return {
                     jsonrpc: "2.0",
                     id: message.id,
@@ -805,9 +949,10 @@ export class PaybondMCPServer {
                             websiteUrl: "https://paybond.ai",
                         },
                         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.",
+                            "Use paybond_create_spend_intent or paybond_bootstrap_sandbox_guardrail to obtain a funded intent_id, " +
+                            "then call paybond_authorize_agent_spend before side-effecting tools. Capability tokens are stored " +
+                            "inside this MCP server and are not returned to agent logs. It works with any MCP-compatible host " +
+                            "and does not assume a specific model provider.",
                     },
                 };
             case "ping":
@@ -910,7 +1055,7 @@ export class PaybondMCPServer {
                     },
                     token: {
                         type: "string",
-                        description: "Capability token returned by paybond_create_spend_intent or paybond_fund_intent.",
+                        description: "Optional capability token override. When omitted, the MCP server uses the token stored for intent_id.",
                     },
                     operation: {
                         type: "string",
@@ -920,15 +1065,19 @@ export class PaybondMCPServer {
                         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"),
-                }),
+                }, ["intent_id", "operation"]),
+                call: async (args) => {
+                    const intentId = uuidArg(args.intent_id, "intent_id");
+                    return this.runtime.authorizeAgentSpend({
+                        intentId,
+                        token: await this.runtime.resolveCapabilityToken(intentId, optionalString(args.token)),
+                        operation: stringArg(args.operation, "operation"),
+                        requestedSpendCents: args.requested_spend_cents === undefined
+                            ? undefined
+                            : intArg(args.requested_spend_cents, "requested_spend_cents"),
+                        toolName: stringArg(args.operation, "operation"),
+                    });
+                },
             },
             {
                 name: "paybond_authorize_agent_spend",
@@ -940,7 +1089,7 @@ export class PaybondMCPServer {
                     },
                     token: {
                         type: "string",
-                        description: "Capability token returned by paybond_create_spend_intent or paybond_fund_intent.",
+                        description: "Optional capability token override. When omitted, the MCP server uses the token stored for intent_id.",
                     },
                     operation: {
                         type: "string",
@@ -950,15 +1099,19 @@ export class PaybondMCPServer {
                         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"),
-                }),
+                }, ["intent_id", "operation"]),
+                call: async (args) => {
+                    const intentId = uuidArg(args.intent_id, "intent_id");
+                    return this.runtime.authorizeAgentSpend({
+                        intentId,
+                        token: await this.runtime.resolveCapabilityToken(intentId, optionalString(args.token)),
+                        operation: stringArg(args.operation, "operation"),
+                        requestedSpendCents: args.requested_spend_cents === undefined
+                            ? undefined
+                            : intArg(args.requested_spend_cents, "requested_spend_cents"),
+                        toolName: stringArg(args.operation, "operation"),
+                    });
+                },
             },
             {
                 name: "paybond_bootstrap_sandbox_guardrail",
@@ -993,6 +1146,30 @@ export class PaybondMCPServer {
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
+            {
+                name: "paybond_validate_completion_evidence",
+                description: "Pre-validates completion evidence against the shared preset catalog. Call this before paybond_submit_*_evidence when PAYBOND_MCP_EVIDENCE_POLICY=strict.",
+                inputSchema: objectSchema({
+                    preset_id: { type: "string" },
+                    vendor_payload: { type: "object", additionalProperties: true },
+                    canonical_payload: { type: "object", additionalProperties: true },
+                    frozen_vendor_api_version: { type: "string" },
+                    frozen_vendor_schema_digest_hex: { type: "string" },
+                    frozen_canonical_schema_digest_hex: { type: "string" },
+                }, ["preset_id"]),
+                call: async (args) => this.runtime.validateCompletionEvidence({
+                    presetId: stringArg(args.preset_id, "preset_id"),
+                    vendorPayload: args.vendor_payload === undefined
+                        ? undefined
+                        : ensureObject(args.vendor_payload, "vendor_payload"),
+                    canonicalPayload: args.canonical_payload === undefined
+                        ? undefined
+                        : ensureObject(args.canonical_payload, "canonical_payload"),
+                    frozenVendorApiVersion: optionalString(args.frozen_vendor_api_version),
+                    frozenVendorSchemaDigestHex: optionalString(args.frozen_vendor_schema_digest_hex),
+                    frozenCanonicalSchemaDigestHex: optionalString(args.frozen_canonical_schema_digest_hex),
+                }),
+            },
             {
                 name: "paybond_submit_sandbox_guardrail_evidence",
                 description: "Submit evidence for a sandbox-only Paybond guardrail intent. Tenant scope is derived from the configured service-account API key and simulator settlement remains sandbox-only.",
@@ -1012,6 +1189,7 @@ export class PaybondMCPServer {
                         description: "Optional sandbox spend amount override for the evidence record.",
                     },
                     metadata: { type: "object", additionalProperties: true },
+                    completion_preset_id: { type: "string" },
                     idempotency_key: { type: "string" },
                 }, ["intent_id"]),
                 call: async (args) => this.runtime.submitSandboxGuardrailEvidence({
@@ -1029,6 +1207,7 @@ export class PaybondMCPServer {
                     metadata: args.metadata === undefined
                         ? undefined
                         : ensureObject(args.metadata, "metadata"),
+                    completionPresetId: optionalString(args.completion_preset_id),
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
@@ -1135,20 +1314,17 @@ export class PaybondMCPServer {
             },
             {
                 name: "paybond_verify_agent_recognition_proof_v1",
-                description: "Verify a replay-safe AgentRecognitionProofV1 against an expected purpose, verifier context, and request envelope.",
+                description: "Verify a replay-safe AgentRecognitionProofV1 against an expected purpose and request envelope. " +
+                    "Verifier context (tenant_id, verifier_id) is derived from the authenticated MCP session only.",
                 inputSchema: objectSchema({
                     proof: { type: "object", additionalProperties: true },
                     expected_purpose: { type: "string" },
                     expected_request: { type: "object", additionalProperties: true },
-                    expected_verifier: { type: "object", additionalProperties: true },
                 }, ["proof", "expected_purpose", "expected_request"]),
                 call: async (args) => this.runtime.verifyAgentRecognitionProofV1({
                     proof: ensureObject(args.proof, "proof"),
                     expectedPurpose: stringArg(args.expected_purpose, "expected_purpose"),
                     expectedRequest: ensureObject(args.expected_request, "expected_request"),
-                    expectedVerifier: args.expected_verifier === undefined
-                        ? undefined
-                        : ensureObject(args.expected_verifier, "expected_verifier"),
                 }),
             },
             {
@@ -1236,12 +1412,14 @@ export class PaybondMCPServer {
                     intent_id: { type: "string" },
                     body: { type: "object", additionalProperties: true },
                     recognition_proof: { type: "object", additionalProperties: true },
+                    completion_preset_id: { type: "string" },
                     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"),
+                    completionPresetId: optionalString(args.completion_preset_id),
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
@@ -1252,12 +1430,14 @@ export class PaybondMCPServer {
                     intent_id: { type: "string" },
                     body: { type: "object", additionalProperties: true },
                     recognition_proof: { type: "object", additionalProperties: true },
+                    completion_preset_id: { type: "string" },
                     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"),
+                    completionPresetId: optionalString(args.completion_preset_id),
                     idempotencyKey: optionalString(args.idempotency_key),
                 }),
             },
@@ -1288,15 +1468,18 @@ export function settingsFromEnv(env = process.env) {
         throw new Error("PAYBOND_API_KEY is required; run paybond login or configure your MCP host environment");
     }
     return {
-        gatewayBaseUrl: optionalEnv(env.PAYBOND_GATEWAY_URL) ??
+        gatewayBaseUrl: requireSecureGatewayUrl(optionalEnv(env.PAYBOND_GATEWAY_URL) ??
             optionalEnv(env.PAYBOND_GATEWAY_BASE_URL) ??
-            DEFAULT_PAYBOND_GATEWAY_BASE_URL,
+            DEFAULT_PAYBOND_GATEWAY_BASE_URL),
         apiKey,
         principalPath: optionalEnv(env.PAYBOND_PRINCIPAL_PATH) ?? DEFAULT_PRINCIPAL_PATH,
         maxRetries: optionalEnv(env.PAYBOND_MCP_MAX_RETRIES)
             ? intArg(optionalEnv(env.PAYBOND_MCP_MAX_RETRIES), "PAYBOND_MCP_MAX_RETRIES")
             : 3,
-        toolPolicy: mergeMcpToolPolicy(parseMcpToolPolicy(optionalEnv(env[MCP_TOOL_POLICY_ENV])), parseMcpToolAllowlist(optionalEnv(env[MCP_TOOL_ALLOWLIST_ENV]))),
+        toolPolicy: resolveMcpToolPolicy(mergeMcpToolPolicy(parseMcpToolPolicy(optionalEnv(env[MCP_TOOL_POLICY_ENV])), parseMcpToolAllowlist(optionalEnv(env[MCP_TOOL_ALLOWLIST_ENV])))),
+        evidencePolicy: parseMcpEvidencePolicy(optionalEnv(env[MCP_EVIDENCE_POLICY_ENV])),
+        policyReload: parseMcpPolicyReloadConfig(env),
+        capabilityTokenCache: parseMcpCapabilityTokenCacheConfig(env),
     };
 }
 export function main(argv = process.argv.slice(2)) {
@@ -1319,7 +1502,7 @@ export function main(argv = process.argv.slice(2)) {
     }
 }
 function normalizeBase(url) {
-    return url.trim().replace(/\/+$/, "");
+    return requireSecureGatewayUrl(url);
 }
 function parseJSONObject(text, context) {
     let parsed;
@@ -1481,10 +1664,7 @@ function optionalEnv(value) {
     return value?.trim() ? value.trim() : undefined;
 }
 function formatError(err) {
-    if (err instanceof Error ||
-        err instanceof GatewayAuthError ||
-        err instanceof GatewayHTTPError ||
-        err instanceof SignalHttpError) {
+    if (err instanceof Error) {
         return err.message;
     }
     return String(err);

package/dist/openai-agents/index.d.ts

@@ -0,0 +1,40 @@
+import { ToolGuardrailFunctionOutputFactory, type FunctionTool, type RunConfig, type ToolInputGuardrailDefinition } from "@openai/agents";
+import { type PaybondAgentRun, type PaybondToolInputGuardDecision } from "../agent/index.js";
+export type PaybondOpenAIAgentsAdapterOptions = {
+    /**
+     * When true, side-effecting registered tools also set `needsApproval: true`
+     * so the OpenAI Agents SDK pauses for human review after Paybond pre-check passes.
+     */
+    bridgeNeedsApproval?: boolean;
+};
+declare function isFunctionTool(value: unknown): value is FunctionTool;
+/** Detect OpenAI Agents SDK function tools (`type: "function"`). */
+export { isFunctionTool as isOpenAIFunctionTool };
+/** Map a framework-neutral Paybond decision to OpenAI tool guardrail output. */
+export declare function mapPaybondDecisionToOpenAIToolGuardrail(decision: PaybondToolInputGuardDecision): ReturnType<typeof ToolGuardrailFunctionOutputFactory.allow>;
+/** RunConfig fragment enabling Paybond verify before OpenAI approval interruptions. */
+export declare const paybondOpenAIAgentsRunConfig: Pick<RunConfig, "toolExecution">;
+/** Translate Paybond middleware into OpenAI Agents SDK tool input guardrails. */
+export declare function createOpenAIAgentsAdapter(run: PaybondAgentRun, options?: PaybondOpenAIAgentsAdapterOptions): {
+    name: "openai-agents";
+    evaluate: (input: import("../agent/types.js").PaybondAuthorizeToolCallInput) => Promise<PaybondToolInputGuardDecision>;
+    wrapExecutors: <T extends import("../agent/adapter.js").PaybondGenericToolDefinition>(tools: T[]) => import("../agent/adapter.js").PaybondGenericWrappedToolDefinition[];
+    runConfig: Pick<RunConfig, "toolExecution">;
+    inputGuardrailFor(toolName: string): ToolInputGuardrailDefinition;
+    guardFunctionTools<TContext>(tools: Array<FunctionTool<TContext>>): Array<FunctionTool<TContext>>;
+};
+/** Convenience alias for {@link createOpenAIAgentsAdapter}. */
+export declare function paybondOpenAIAgentsAdapter(run: PaybondAgentRun, options?: PaybondOpenAIAgentsAdapterOptions): ReturnType<typeof createOpenAIAgentsAdapter>;
+export { runOpenAIAgentsSandboxDemo, type RunOpenAIAgentsSandboxDemoInput, type RunOpenAIAgentsSandboxDemoResult, } from "./sandbox-demo.js";
+/** OpenAI Agents SDK runner config: guarded tools plus `runConfig` for pre-approval guardrails. */
+export type PaybondOpenAIAgentsConfig<TContext = unknown> = {
+    tools: Array<FunctionTool<TContext>>;
+    runConfig: Pick<RunConfig, "toolExecution">;
+};
+/**
+ * Framework runner helper for OpenAI Agents SDK `Runner.run`.
+ *
+ * Returns guarded function tools and the `runConfig` fragment that enables
+ * Paybond verify before approval interruptions.
+ */
+export declare function createPaybondOpenAIAgentsConfig<TContext>(run: PaybondAgentRun, tools: Array<FunctionTool<TContext>>, options?: PaybondOpenAIAgentsAdapterOptions): PaybondOpenAIAgentsConfig<TContext>;

package/dist/openai-agents/index.js

@@ -0,0 +1,151 @@
+import { defineToolInputGuardrail, ToolGuardrailFunctionOutputFactory, } from "@openai/agents";
+import { createToolInputGuardAdapter, } from "../agent/index.js";
+function parseToolArguments(raw) {
+    if (!raw.trim()) {
+        return {};
+    }
+    return JSON.parse(raw);
+}
+function isFunctionTool(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    return record.type === "function" && typeof record.name === "string" && typeof record.invoke === "function";
+}
+/** Detect OpenAI Agents SDK function tools (`type: "function"`). */
+export { isFunctionTool as isOpenAIFunctionTool };
+/** Map a framework-neutral Paybond decision to OpenAI tool guardrail output. */
+export function mapPaybondDecisionToOpenAIToolGuardrail(decision) {
+    if (decision.kind === "allow") {
+        return ToolGuardrailFunctionOutputFactory.allow({
+            paybond: {
+                operation: decision.operation,
+                auditId: decision.auditId,
+                decisionId: decision.decisionId,
+                passthrough: decision.passthrough ?? false,
+            },
+        });
+    }
+    return ToolGuardrailFunctionOutputFactory.rejectContent(decision.message, {
+        paybond: {
+            kind: decision.kind,
+            operation: decision.operation,
+            auditId: decision.auditId,
+            code: decision.code,
+        },
+    });
+}
+function buildPaybondInputGuardrail(run, toolName) {
+    const guard = createToolInputGuardAdapter(run);
+    return defineToolInputGuardrail({
+        name: `paybond_spend_${toolName}`,
+        run: async ({ toolCall }) => {
+            const args = parseToolArguments(toolCall.arguments);
+            const decision = await guard.evaluate({
+                toolName: toolCall.name,
+                toolCallId: toolCall.callId,
+                arguments: args,
+            });
+            return mapPaybondDecisionToOpenAIToolGuardrail(decision);
+        },
+    });
+}
+function resolveToolCallId(details) {
+    const callId = details?.toolCall?.callId?.trim();
+    if (callId) {
+        return callId;
+    }
+    return globalThis.crypto.randomUUID();
+}
+function guardFunctionTool(run, fnTool, options) {
+    if (!run.registry.isSideEffecting(fnTool.name)) {
+        return fnTool;
+    }
+    const paybondGuardrail = buildPaybondInputGuardrail(run, fnTool.name);
+    const originalInvoke = fnTool.invoke.bind(fnTool);
+    const bridgeApproval = options?.bridgeNeedsApproval === true;
+    return {
+        ...fnTool,
+        inputGuardrails: [...(fnTool.inputGuardrails ?? []), paybondGuardrail],
+        needsApproval: bridgeApproval
+            ? async (runContext, input, callId) => {
+                const baseNeedsApproval = typeof fnTool.needsApproval === "function"
+                    ? await fnTool.needsApproval(runContext, input, callId)
+                    : Boolean(fnTool.needsApproval);
+                return baseNeedsApproval || bridgeApproval;
+            }
+            : fnTool.needsApproval,
+        invoke: async (runContext, input, details) => {
+            const args = parseToolArguments(input);
+            const wrapped = await run.interceptor.wrapExecute({
+                toolName: fnTool.name,
+                toolCallId: resolveToolCallId(details),
+                arguments: args,
+                execute: async () => {
+                    const raw = await originalInvoke(runContext, input, details);
+                    if (typeof raw === "string") {
+                        try {
+                            return JSON.parse(raw);
+                        }
+                        catch {
+                            return raw;
+                        }
+                    }
+                    return raw;
+                },
+            });
+            const { toolResult } = wrapped;
+            if (typeof toolResult === "string") {
+                return toolResult;
+            }
+            if (toolResult === undefined || toolResult === null) {
+                return "";
+            }
+            if (typeof toolResult === "object") {
+                return JSON.stringify(toolResult);
+            }
+            return toolResult;
+        },
+    };
+}
+/** RunConfig fragment enabling Paybond verify before OpenAI approval interruptions. */
+export const paybondOpenAIAgentsRunConfig = {
+    toolExecution: {
+        preApprovalInputGuardrails: true,
+    },
+};
+/** Translate Paybond middleware into OpenAI Agents SDK tool input guardrails. */
+export function createOpenAIAgentsAdapter(run, options) {
+    const guard = createToolInputGuardAdapter(run);
+    return {
+        name: "openai-agents",
+        evaluate: guard.evaluate.bind(guard),
+        wrapExecutors: guard.wrapExecutors.bind(guard),
+        runConfig: paybondOpenAIAgentsRunConfig,
+        inputGuardrailFor(toolName) {
+            return buildPaybondInputGuardrail(run, toolName);
+        },
+        guardFunctionTools(tools) {
+            return tools.map((tool) => guardFunctionTool(run, tool, options));
+        },
+    };
+}
+/** Convenience alias for {@link createOpenAIAgentsAdapter}. */
+export function paybondOpenAIAgentsAdapter(run, options) {
+    return createOpenAIAgentsAdapter(run, options);
+}
+export { runOpenAIAgentsSandboxDemo, } from "./sandbox-demo.js";
+/**
+ * Framework runner helper for OpenAI Agents SDK `Runner.run`.
+ *
+ * Returns guarded function tools and the `runConfig` fragment that enables
+ * Paybond verify before approval interruptions.
+ */
+export function createPaybondOpenAIAgentsConfig(run, tools, options) {
+    const adapter = createOpenAIAgentsAdapter(run, options);
+    return {
+        tools: adapter.guardFunctionTools(tools),
+        runConfig: adapter.runConfig,
+    };
+}