@paybond/kit 0.9.8 → 0.11.0

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,
+    };
+}

package/dist/openai-agents/sandbox-demo.d.ts

@@ -0,0 +1,34 @@
+import type { Paybond } from "../index.js";
+export type RunOpenAIAgentsSandboxDemoInput = {
+    paybond: Paybond;
+    operation?: string;
+    requestedSpendCents?: number;
+    evidencePreset?: string;
+    toolCallId?: string;
+};
+export type RunOpenAIAgentsSandboxDemoResult = {
+    bind: {
+        run_id: string;
+        tenant_id: string;
+        intent_id: string;
+        capability_token: string;
+        operation: string;
+        sandbox_lifecycle_status?: string;
+    };
+    guardrail: {
+        behavior: string;
+    };
+    execute: {
+        tool_result?: unknown;
+        evidence?: {
+            submitted: boolean;
+            sandbox_lifecycle_status?: string;
+            predicate_passed?: boolean | null;
+        };
+    };
+};
+/**
+ * No-LLM OpenAI Agents SDK sandbox demo: input guardrail pre-check + guarded
+ * `invoke` + auto-evidence.
+ */
+export declare function runOpenAIAgentsSandboxDemo(input: RunOpenAIAgentsSandboxDemoInput): Promise<RunOpenAIAgentsSandboxDemoResult>;

package/dist/openai-agents/sandbox-demo.js

@@ -0,0 +1,118 @@
+import { createPaybondToolRegistry } from "../agent/registry.js";
+import { createPaybondOpenAIAgentsConfig } from "./index.js";
+function makePaidFunctionTool(name) {
+    return {
+        type: "function",
+        name,
+        description: `Paid operation ${name}`,
+        parameters: {
+            type: "object",
+            properties: {
+                estimatedPriceCents: { type: "integer", minimum: 0 },
+            },
+            required: ["estimatedPriceCents"],
+            additionalProperties: false,
+        },
+        strict: false,
+        invoke: async (_runContext, input) => {
+            const args = JSON.parse(input);
+            return JSON.stringify({
+                status: "completed",
+                cost_cents: args.estimatedPriceCents,
+            });
+        },
+        needsApproval: async () => false,
+        isEnabled: async () => true,
+    };
+}
+/**
+ * No-LLM OpenAI Agents SDK sandbox demo: input guardrail pre-check + guarded
+ * `invoke` + auto-evidence.
+ */
+export async function runOpenAIAgentsSandboxDemo(input) {
+    const operation = (input.operation ?? "paid-tool").trim();
+    const requestedSpendCents = input.requestedSpendCents ?? 100;
+    const evidencePreset = (input.evidencePreset ?? "cost_and_completion").trim();
+    const toolCallId = (input.toolCallId ?? "openai-demo-1").trim();
+    const registry = createPaybondToolRegistry({
+        defaultDeny: true,
+        sideEffecting: {
+            [operation]: {
+                operation,
+                evidencePreset,
+                spendCents: (args) => typeof args === "object" &&
+                    args !== null &&
+                    "estimatedPriceCents" in args &&
+                    typeof args.estimatedPriceCents === "number"
+                    ? args.estimatedPriceCents
+                    : requestedSpendCents,
+                evidenceMapper: (result) => {
+                    const payload = result;
+                    return {
+                        status: payload.status,
+                        cost_cents: payload.cost_cents,
+                    };
+                },
+            },
+        },
+    });
+    const run = await input.paybond.agentRun.bind({
+        bootstrap: {
+            kind: "sandbox",
+            operation,
+            requestedSpendCents,
+            completionPreset: evidencePreset,
+        },
+        registry,
+    });
+    const paidTool = makePaidFunctionTool(operation);
+    const config = createPaybondOpenAIAgentsConfig(run, [paidTool]);
+    const guarded = config.tools[0];
+    if (!guarded) {
+        throw new Error("openai-agents sandbox demo missing guarded tool");
+    }
+    const toolCall = {
+        type: "function_call",
+        name: operation,
+        callId: toolCallId,
+        arguments: JSON.stringify({ estimatedPriceCents: requestedSpendCents }),
+    };
+    const guardrail = guarded.inputGuardrails?.[0];
+    const guardrailResult = guardrail
+        ? await guardrail.run({
+            agent: {},
+            context: {},
+            toolCall,
+        })
+        : undefined;
+    const output = (await guarded.invoke({}, JSON.stringify({ estimatedPriceCents: requestedSpendCents }), { toolCall }));
+    let toolResult;
+    try {
+        toolResult = JSON.parse(output);
+    }
+    catch {
+        toolResult = output;
+    }
+    const sandboxStatus = run.binding.sandbox?.sandboxLifecycleStatus;
+    return {
+        bind: {
+            run_id: run.runId,
+            tenant_id: run.tenantId,
+            intent_id: run.intentId,
+            capability_token: run.capabilityToken,
+            operation,
+            sandbox_lifecycle_status: sandboxStatus,
+        },
+        guardrail: {
+            behavior: guardrailResult?.behavior.type ?? "not-applicable",
+        },
+        execute: {
+            tool_result: toolResult,
+            evidence: {
+                submitted: true,
+                sandbox_lifecycle_status: sandboxStatus,
+                predicate_passed: true,
+            },
+        },
+    };
+}

package/dist/payee-evidence.js

@@ -3,28 +3,9 @@
  */
 import { sign, getPublicKey } from "@noble/ed25519";
 import { createHash } from "blake3";
-import { parse as parseUuid } from "uuid";
 import { ensureEd25519Sha512Sync } from "./ed25519-sync.js";
 import { jsonValueDigest } from "./json-digest.js";
-function concatBytes(...parts) {
-    const n = parts.reduce((a, p) => a + p.length, 0);
-    const out = new Uint8Array(n);
-    let o = 0;
-    for (const p of parts) {
-        out.set(p, o);
-        o += p.length;
-    }
-    return out;
-}
-function encodeU64(n) {
-    const b = new Uint8Array(8);
-    new DataView(b.buffer).setBigUint64(0, BigInt(n), true);
-    return b;
-}
-function encodeBincodeString(s) {
-    const utf8 = new TextEncoder().encode(s);
-    return concatBytes(encodeU64(utf8.length), utf8);
-}
+import { concatBytes, encodeBincodeString, encodeBincodeUuid, encodeFixed32, encodeU8, EVIDENCE_SIGN_VERSION, } from "./bincode-wire.js";
 /** BLAKE3 digest of concatenated artifact hashes (empty list matches Harbor / `paybond-evidence`). */
 export function artifactsDigest(artifactHashes32) {
     const h = createHash();
@@ -35,15 +16,7 @@ export function artifactsDigest(artifactHashes32) {
     return new Uint8Array(buf);
 }
 function encodeEvidenceSignV1(input) {
-    const version = new Uint8Array([1]);
-    const intentBytes = parseUuid(input.intentId);
-    if (intentBytes.length !== 16) {
-        throw new Error("intentId must be a UUID string");
-    }
-    if (input.payloadDigest.length !== 32 || input.artifactsDigest.length !== 32) {
-        throw new Error("digest must be 32 bytes");
-    }
-    return concatBytes(version, encodeBincodeString(input.tenantId), encodeU64(16), intentBytes, encodeBincodeString(input.payeeDid), input.payloadDigest, input.artifactsDigest, encodeBincodeString(input.submittedAtRfc3339));
+    return concatBytes(encodeU8(EVIDENCE_SIGN_VERSION), encodeBincodeString(input.tenantId), encodeBincodeUuid(input.intentId), encodeBincodeString(input.payeeDid), encodeFixed32(input.payloadDigest), encodeFixed32(input.artifactsDigest), encodeBincodeString(input.submittedAtRfc3339));
 }
 function bytesToBase64(bytes) {
     let binary = "";

package/dist/policy/catalog.d.ts

@@ -0,0 +1,31 @@
+import { listGuardrailCatalogEntries } from "./guardrail-spec.js";
+export type PolicyDomainCatalogEntry = {
+    id: string;
+    title: string;
+    layered: boolean;
+};
+export type PolicyPresetCatalogEntry = {
+    id: string;
+    kind: "composed" | "flat";
+    layered: boolean;
+};
+export type PolicySolutionCatalogEntry = {
+    id: string;
+    title: string;
+    domain: string;
+    guardrails: string[];
+    primary_operation: string;
+};
+/** List bundled domain layers for CLI and docs. */
+export declare function listPolicyDomainCatalog(): PolicyDomainCatalogEntry[];
+/** List flat and composed policy presets. */
+export declare function listPolicyPresetCatalog(): PolicyPresetCatalogEntry[];
+/** List bundled solution manifests. */
+export declare function listPolicySolutionCatalog(): PolicySolutionCatalogEntry[];
+/** Combined catalog payload for `paybond policy presets list`. */
+export declare function listPolicyPresetsCatalog(): {
+    domains: PolicyDomainCatalogEntry[];
+    guardrails: ReturnType<typeof listGuardrailCatalogEntries>;
+    solutions: PolicySolutionCatalogEntry[];
+    presets: PolicyPresetCatalogEntry[];
+};

package/dist/policy/catalog.js

@@ -0,0 +1,48 @@
+import { LAYERED_POLICY_PRESET_IDS } from "./compose.js";
+import { listGuardrailCatalogEntries } from "./guardrail-spec.js";
+import { isLayeredPolicyPresetId, listPolicyPresetIds } from "./presets.js";
+import { listSolutionIds, loadSolutionManifest } from "../solutions/catalog.js";
+const DOMAIN_TITLES = {
+    travel: "Travel booking",
+    shopping: "Shopping checkout",
+    saas: "SaaS provisioning",
+    aws: "AWS operator",
+};
+/** List bundled domain layers for CLI and docs. */
+export function listPolicyDomainCatalog() {
+    return LAYERED_POLICY_PRESET_IDS.map((id) => ({
+        id,
+        title: DOMAIN_TITLES[id] ?? id,
+        layered: true,
+    }));
+}
+/** List flat and composed policy presets. */
+export function listPolicyPresetCatalog() {
+    return listPolicyPresetIds().map((id) => ({
+        id,
+        kind: isLayeredPolicyPresetId(id) ? "composed" : "flat",
+        layered: isLayeredPolicyPresetId(id),
+    }));
+}
+/** List bundled solution manifests. */
+export function listPolicySolutionCatalog() {
+    return listSolutionIds().map((id) => {
+        const manifest = loadSolutionManifest(id);
+        return {
+            id: manifest.id,
+            title: manifest.title,
+            domain: manifest.policy_default.domain,
+            guardrails: [...manifest.policy_default.guardrails],
+            primary_operation: manifest.primary_operation,
+        };
+    });
+}
+/** Combined catalog payload for `paybond policy presets list`. */
+export function listPolicyPresetsCatalog() {
+    return {
+        domains: listPolicyDomainCatalog(),
+        guardrails: listGuardrailCatalogEntries(),
+        solutions: listPolicySolutionCatalog(),
+        presets: listPolicyPresetCatalog(),
+    };
+}

package/dist/policy/compose-utils.d.ts

@@ -0,0 +1,3 @@
+import type { PaybondPolicyToolEntry } from "./schema.js";
+/** Clone a tool registry entry for compose merges. */
+export declare function cloneToolEntry(entry: PaybondPolicyToolEntry): PaybondPolicyToolEntry;

package/dist/policy/compose-utils.js

@@ -0,0 +1,4 @@
+/** Clone a tool registry entry for compose merges. */
+export function cloneToolEntry(entry) {
+    return { ...entry };
+}

package/dist/policy/compose.d.ts

@@ -0,0 +1,20 @@
+import { type PolicyGuardrailLayer } from "./guardrails.js";
+import { type PolicyPresetId } from "./presets.js";
+import { type PaybondPolicyDocumentV1 } from "./schema.js";
+export declare const LAYERED_POLICY_PRESET_IDS: readonly ["travel", "shopping", "saas", "aws"];
+export type LayeredPolicyPresetId = (typeof LAYERED_POLICY_PRESET_IDS)[number];
+/** Stack a domain document with one or more guardrail layers (same-tenant compose, not org inheritance). */
+export declare function composePolicyLayers(domainDocument: PaybondPolicyDocumentV1, ...layers: PolicyGuardrailLayer[]): PaybondPolicyDocumentV1;
+/** True when a bundled preset is composed from domain + guardrails layers. */
+export declare function isLayeredPolicyPreset(presetId: string): presetId is LayeredPolicyPresetId;
+/** Merge domain and guardrail YAML objects (bundled preset file generation). */
+export declare function composePolicyPresetLayers(domain: Record<string, unknown>, guardrails: Record<string, unknown>): Record<string, unknown>;
+/** Default bundled guardrail layers for a vertical preset id. */
+export declare function bundledDefaultGuardrails(presetId: LayeredPolicyPresetId): PolicyGuardrailLayer[];
+/** Compose the shipped default for a vertical preset (domain + bundled guardrails). */
+export declare function composeBundledPresetDefault(presetId: LayeredPolicyPresetId): PaybondPolicyDocumentV1;
+/** Load and compose a layered vertical preset (domain + guardrails YAML files). */
+export declare function composeLayeredPolicyPresetDocument(presetId: LayeredPolicyPresetId): Record<string, unknown>;
+/** Compare composed layered presets with bundled flat preset files (tests). */
+export declare function assertLayeredPresetMatchesFlat(presetId: PolicyPresetId): void;
+export { readPresetLayerYaml } from "./layers-io.js";