@paybond/kit 0.10.0 → 0.11.1

package/dist/agent/adapter.js

@@ -0,0 +1,66 @@
+function isGenericToolDefinition(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    return (typeof record.name === "string" &&
+        record.name.trim().length > 0 &&
+        typeof record.execute === "function");
+}
+function assertGenericTools(tools) {
+    if (!Array.isArray(tools)) {
+        throw new TypeError("generic tool adapter expects an array of { name, execute } tool definitions");
+    }
+    for (const tool of tools) {
+        if (!isGenericToolDefinition(tool)) {
+            throw new TypeError("each generic tool must have a non-empty name and an execute function");
+        }
+    }
+    return tools;
+}
+function wrapGenericTool(run, tool) {
+    const { execute: originalExecute, ...rest } = tool;
+    return {
+        ...rest,
+        name: tool.name,
+        execute: async (call) => run.interceptor.wrapExecute({
+            toolName: call.toolName,
+            toolCallId: call.toolCallId,
+            arguments: call.arguments,
+            execute: () => originalExecute(call.arguments),
+            operation: call.operation,
+            requestedSpendCents: call.requestedSpendCents,
+            vendorId: call.vendorId,
+            taskId: call.taskId,
+            workflowId: call.workflowId,
+            currency: call.currency,
+            agentSubject: call.agentSubject,
+            approvalToken: call.approvalToken,
+            idempotencyKey: call.idempotencyKey,
+        }),
+    };
+}
+const genericToolExecutorAdapter = {
+    name: "generic",
+    wrapTools(run, tools) {
+        return assertGenericTools(tools).map((tool) => wrapGenericTool(run, tool));
+    },
+};
+/** Provider-agnostic framework adapter for `{ name, execute }` tool definitions. */
+export function createGenericToolExecutor() {
+    return genericToolExecutorAdapter;
+}
+/** Singleton generic adapter instance. */
+export const paybondGenericToolExecutorAdapter = genericToolExecutorAdapter;
+/** Build a run-scoped tool input guard adapter (framework-neutral). */
+export function createToolInputGuardAdapter(run) {
+    return {
+        name: "tool-input-guard",
+        evaluate: (input) => run.interceptor.authorizeToolCall(input),
+        wrapExecutors: (tools) => assertGenericTools(tools).map((tool) => wrapGenericTool(run, tool)),
+    };
+}
+/** Convenience alias for {@link createToolInputGuardAdapter}. */
+export function paybondToolInputGuardAdapter(run) {
+    return createToolInputGuardAdapter(run);
+}

package/dist/agent/attach-bundle.d.ts

@@ -0,0 +1,37 @@
+import type { PaybondRunProductionEvidenceCredentials } from "./types.js";
+/** Attach bundle wire prefix (`ab1.`). */
+export declare const PAYBOND_ATTACH_BUNDLE_PREFIX = "ab1.";
+export declare const PAYBOND_ATTACH_INTENT_ID_ENV = "PAYBOND_ATTACH_INTENT_ID";
+export declare const PAYBOND_CAPABILITY_TOKEN_ENV = "PAYBOND_CAPABILITY_TOKEN";
+export declare const PAYBOND_ATTACH_BUNDLE_ENV = "PAYBOND_ATTACH_BUNDLE";
+/** Cleartext credential payload sealed inside {@link PAYBOND_ATTACH_BUNDLE_ENV}. */
+export type PaybondAttachBundlePayloadV1 = Readonly<{
+    v: 1;
+    payee_did: string;
+    payee_signing_seed_hex: string;
+    agent_recognition_key_id: string;
+    agent_recognition_signing_seed_hex: string;
+}>;
+/** Seal production signing material into an opaque attach bundle for env injection. */
+export declare function sealPaybondAttachBundle(payload: PaybondAttachBundlePayloadV1): string;
+/** Open a console-minted attach bundle and return the sealed credential payload. */
+export declare function openPaybondAttachBundle(bundle: string): PaybondAttachBundlePayloadV1;
+/** Map attach bundle payload bytes into run-scoped production evidence credentials. */
+export declare function productionEvidenceFromAttachBundle(payload: PaybondAttachBundlePayloadV1): PaybondRunProductionEvidenceCredentials;
+export type PaybondAttachEnvRecord = Readonly<Record<string, string | undefined>>;
+/**
+ * Resolve funded-intent attach context from standard production env vars.
+ * Requires {@link PAYBOND_ATTACH_INTENT_ID_ENV}, {@link PAYBOND_CAPABILITY_TOKEN_ENV},
+ * and {@link PAYBOND_ATTACH_BUNDLE_ENV}.
+ */
+export declare function resolveAttachContextFromEnv(env?: PaybondAttachEnvRecord): {
+    intentId: string;
+    capabilityToken: string;
+    productionEvidence: PaybondRunProductionEvidenceCredentials;
+};
+/** Format the console one-time env snippet for copy/paste into a secrets manager. */
+export declare function formatPaybondAttachEnvSnippet(input: {
+    intentId: string;
+    capabilityToken: string;
+    attachBundle: string;
+}): string;

package/dist/agent/attach-bundle.js

@@ -0,0 +1,118 @@
+import { createDecipheriv, createCipheriv, randomBytes } from "node:crypto";
+/** Attach bundle wire prefix (`ab1.`). */
+export const PAYBOND_ATTACH_BUNDLE_PREFIX = "ab1.";
+export const PAYBOND_ATTACH_INTENT_ID_ENV = "PAYBOND_ATTACH_INTENT_ID";
+export const PAYBOND_CAPABILITY_TOKEN_ENV = "PAYBOND_CAPABILITY_TOKEN";
+export const PAYBOND_ATTACH_BUNDLE_ENV = "PAYBOND_ATTACH_BUNDLE";
+function base64UrlEncode(bytes) {
+    return Buffer.from(bytes).toString("base64url");
+}
+function base64UrlDecode(encoded) {
+    return new Uint8Array(Buffer.from(encoded, "base64url"));
+}
+function parseSeed32Hex(raw, field) {
+    const hex = raw.trim().replace(/^0x/i, "");
+    if (!/^[0-9a-fA-F]{64}$/.test(hex)) {
+        throw new Error(`${field} must be a 32-byte Ed25519 seed (64 hex characters)`);
+    }
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+/** Seal production signing material into an opaque attach bundle for env injection. */
+export function sealPaybondAttachBundle(payload) {
+    if (payload.v !== 1) {
+        throw new Error("attach bundle payload version must be 1");
+    }
+    const bundleKey = randomBytes(32);
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", bundleKey, nonce);
+    const plaintext = Buffer.from(JSON.stringify(payload), "utf8");
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+    const envelope = {
+        v: 1,
+        alg: "aes-256-gcm",
+        k: base64UrlEncode(bundleKey),
+        n: base64UrlEncode(nonce),
+        c: base64UrlEncode(ciphertext),
+    };
+    return PAYBOND_ATTACH_BUNDLE_PREFIX + Buffer.from(JSON.stringify(envelope), "utf8").toString("base64url");
+}
+/** Open a console-minted attach bundle and return the sealed credential payload. */
+export function openPaybondAttachBundle(bundle) {
+    const trimmed = bundle.trim();
+    if (!trimmed.startsWith(PAYBOND_ATTACH_BUNDLE_PREFIX)) {
+        throw new Error(`attach bundle must start with ${PAYBOND_ATTACH_BUNDLE_PREFIX}`);
+    }
+    const encoded = trimmed.slice(PAYBOND_ATTACH_BUNDLE_PREFIX.length);
+    let envelope;
+    try {
+        envelope = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new Error("attach bundle envelope is not valid base64url JSON");
+    }
+    if (envelope.v !== 1 || envelope.alg !== "aes-256-gcm") {
+        throw new Error("unsupported attach bundle envelope");
+    }
+    const bundleKey = base64UrlDecode(envelope.k);
+    const nonce = base64UrlDecode(envelope.n);
+    const ciphertext = base64UrlDecode(envelope.c);
+    if (bundleKey.length !== 32 || nonce.length !== 12 || ciphertext.length < 16) {
+        throw new Error("attach bundle envelope fields are malformed");
+    }
+    const authTag = ciphertext.slice(ciphertext.length - 16);
+    const encrypted = ciphertext.slice(0, ciphertext.length - 16);
+    const decipher = createDecipheriv("aes-256-gcm", bundleKey, nonce);
+    decipher.setAuthTag(authTag);
+    const plaintext = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+    const payload = JSON.parse(plaintext.toString("utf8"));
+    if (payload.v !== 1) {
+        throw new Error("attach bundle payload version must be 1");
+    }
+    return payload;
+}
+/** Map attach bundle payload bytes into run-scoped production evidence credentials. */
+export function productionEvidenceFromAttachBundle(payload) {
+    return {
+        payeeDid: payload.payee_did.trim(),
+        payeeSigningSeed: parseSeed32Hex(payload.payee_signing_seed_hex, "payee_signing_seed_hex"),
+        agentRecognitionKeyId: payload.agent_recognition_key_id.trim(),
+        agentRecognitionSigningSeed: parseSeed32Hex(payload.agent_recognition_signing_seed_hex, "agent_recognition_signing_seed_hex"),
+    };
+}
+/**
+ * Resolve funded-intent attach context from standard production env vars.
+ * Requires {@link PAYBOND_ATTACH_INTENT_ID_ENV}, {@link PAYBOND_CAPABILITY_TOKEN_ENV},
+ * and {@link PAYBOND_ATTACH_BUNDLE_ENV}.
+ */
+export function resolveAttachContextFromEnv(env = process.env) {
+    const intentId = env[PAYBOND_ATTACH_INTENT_ID_ENV]?.trim() ?? "";
+    const capabilityToken = env[PAYBOND_CAPABILITY_TOKEN_ENV]?.trim() ?? "";
+    const bundle = env[PAYBOND_ATTACH_BUNDLE_ENV]?.trim() ?? "";
+    if (!intentId) {
+        throw new Error(`${PAYBOND_ATTACH_INTENT_ID_ENV} is required when attach is "env"`);
+    }
+    if (!capabilityToken) {
+        throw new Error(`${PAYBOND_CAPABILITY_TOKEN_ENV} is required when attach is "env"`);
+    }
+    if (!bundle) {
+        throw new Error(`${PAYBOND_ATTACH_BUNDLE_ENV} is required when attach is "env"`);
+    }
+    const payload = openPaybondAttachBundle(bundle);
+    return {
+        intentId,
+        capabilityToken,
+        productionEvidence: productionEvidenceFromAttachBundle(payload),
+    };
+}
+/** Format the console one-time env snippet for copy/paste into a secrets manager. */
+export function formatPaybondAttachEnvSnippet(input) {
+    return [
+        `${PAYBOND_ATTACH_INTENT_ID_ENV}=${input.intentId}`,
+        `${PAYBOND_CAPABILITY_TOKEN_ENV}=${input.capabilityToken}`,
+        `${PAYBOND_ATTACH_BUNDLE_ENV}=${input.attachBundle}`,
+    ].join("\n");
+}

package/dist/agent/authorization-cache.d.ts

@@ -0,0 +1,22 @@
+/** Max age for authorize → wrapExecute cache reuse (seconds). */
+export declare const AUTHORIZATION_CACHE_TTL_SEC = 120;
+export type CachedAuthorizationEntry<TAuth> = {
+    auth: TAuth;
+    policyDigest?: string;
+    operation: string;
+    requestedSpendCents: number;
+    toolName: string;
+    cachedAtMs: number;
+};
+export type AuthorizationCacheExpectation = {
+    operation: string;
+    requestedSpendCents: number;
+    toolName: string;
+};
+/** Drop expired entries before inserting a new authorization. */
+export declare function evictExpiredAuthorizationCache<TAuth>(cache: Map<string, CachedAuthorizationEntry<TAuth>>, ttlSec?: number, nowMs?: number): void;
+/**
+ * Remove and return a cached authorization when it is fresh and matches the
+ * wrapExecute call (operation, spend, tool name).
+ */
+export declare function takeValidCachedAuthorization<TAuth>(cache: Map<string, CachedAuthorizationEntry<TAuth>>, cacheKey: string, expected: AuthorizationCacheExpectation, ttlSec?: number, nowMs?: number): CachedAuthorizationEntry<TAuth> | undefined;

package/dist/agent/authorization-cache.js

@@ -0,0 +1,36 @@
+/** Max age for authorize → wrapExecute cache reuse (seconds). */
+export const AUTHORIZATION_CACHE_TTL_SEC = 120;
+/** Drop expired entries before inserting a new authorization. */
+export function evictExpiredAuthorizationCache(cache, ttlSec = AUTHORIZATION_CACHE_TTL_SEC, nowMs = Date.now()) {
+    const ttlMs = ttlSec * 1000;
+    for (const [key, entry] of cache) {
+        if (nowMs - entry.cachedAtMs > ttlMs) {
+            cache.delete(key);
+        }
+    }
+}
+/**
+ * Remove and return a cached authorization when it is fresh and matches the
+ * wrapExecute call (operation, spend, tool name).
+ */
+export function takeValidCachedAuthorization(cache, cacheKey, expected, ttlSec = AUTHORIZATION_CACHE_TTL_SEC, nowMs = Date.now()) {
+    const cached = cache.get(cacheKey);
+    if (!cached) {
+        return undefined;
+    }
+    cache.delete(cacheKey);
+    const ttlMs = ttlSec * 1000;
+    if (nowMs - cached.cachedAtMs > ttlMs) {
+        return undefined;
+    }
+    if (cached.operation !== expected.operation) {
+        return undefined;
+    }
+    if (cached.requestedSpendCents !== expected.requestedSpendCents) {
+        return undefined;
+    }
+    if (cached.toolName !== expected.toolName) {
+        return undefined;
+    }
+    return cached;
+}

package/dist/agent/deferred-tools.d.ts

@@ -0,0 +1,11 @@
+export declare const PAYBOND_BIND_CONTEXT_MESSAGE = "Call instrumented.bind({ intentId, capabilityToken }) to attach a funded intent before executing side-effecting tools.";
+/** Thrown when a deferred tool executes before {@link PaybondInstrumented.bind}. */
+export declare class PaybondUnboundContextError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string);
+}
+/**
+ * Wrap tools for static instrumentation — safe to register with agent frameworks.
+ * Side-effecting execution throws until {@link PaybondInstrumented.bind} supplies a runtime.
+ */
+export declare function wrapDeferredTools<TTools>(rawTools: TTools): TTools;

package/dist/agent/deferred-tools.js

@@ -0,0 +1,62 @@
+export const PAYBOND_BIND_CONTEXT_MESSAGE = "Call instrumented.bind({ intentId, capabilityToken }) to attach a funded intent before executing side-effecting tools.";
+/** Thrown when a deferred tool executes before {@link PaybondInstrumented.bind}. */
+export class PaybondUnboundContextError extends Error {
+    toolName;
+    constructor(toolName) {
+        super(`Tool "${toolName}" requires a bound Paybond context. ${PAYBOND_BIND_CONTEXT_MESSAGE}`);
+        this.name = "PaybondUnboundContextError";
+        this.toolName = toolName;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isGenericToolDefinition(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return typeof value.name === "string" && value.name.trim().length > 0 && typeof value.execute === "function";
+}
+function deferredExecute(toolName) {
+    throw new PaybondUnboundContextError(toolName);
+}
+/**
+ * Wrap tools for static instrumentation — safe to register with agent frameworks.
+ * Side-effecting execution throws until {@link PaybondInstrumented.bind} supplies a runtime.
+ */
+export function wrapDeferredTools(rawTools) {
+    if (Array.isArray(rawTools)) {
+        return rawTools.map((tool) => {
+            if (!isGenericToolDefinition(tool)) {
+                return tool;
+            }
+            const { execute: _ignored, ...rest } = tool;
+            return {
+                ...rest,
+                name: tool.name,
+                execute: async (_call) => deferredExecute(tool.name),
+            };
+        });
+    }
+    if (isRecord(rawTools)) {
+        const wrapped = {};
+        for (const [name, tool] of Object.entries(rawTools)) {
+            if (typeof tool === "function") {
+                wrapped[name] = async () => deferredExecute(name);
+                continue;
+            }
+            if (isGenericToolDefinition(tool)) {
+                const { execute: _ignored, ...rest } = tool;
+                wrapped[name] = {
+                    ...rest,
+                    name: tool.name?.trim() || name,
+                    execute: async (_call) => deferredExecute(tool.name?.trim() || name),
+                };
+                continue;
+            }
+            wrapped[name] = tool;
+        }
+        return wrapped;
+    }
+    return rawTools;
+}

package/dist/agent/discover.d.ts

@@ -0,0 +1,41 @@
+import type { PaybondInlinePolicy } from "./instrument.js";
+import type { PaybondPolicyLoadSource } from "../policy/load.js";
+import type { PaybondTraceSink } from "./types.js";
+/** Metadata attached to framework agent instances after {@link instrumentPaybondAgent}. */
+export type PaybondAgentInstrumentation = {
+    run?: import("./run.js").PaybondAgentRun;
+    policy: import("../policy/load.js").PaybondPolicy;
+    hooks: import("./facade.js").PaybondAgentHooks;
+    tools?: unknown;
+    binding: import("./instrument.js").PaybondInstrumentBinding;
+    status?: import("./instrument.js").PaybondInstrumentBinding;
+    bind?: (context: import("./instrument.js").PaybondInstrumentContext) => Promise<PaybondAgentInstrumentation>;
+    /** @deprecated Use {@link PaybondAgentInstrumentation.bind}. */
+    withContext?: (context: import("./instrument.js").PaybondInstrumentContext) => Promise<PaybondAgentInstrumentation>;
+};
+export type PaybondInstrumentAgentOptions = {
+    policy?: PaybondPolicyLoadSource | PaybondInlinePolicy;
+    framework?: import("./guarded-agent.js").GuardedAgentFramework;
+    sandbox?: boolean;
+    attach?: import("./instrument.js").PaybondInstrumentAttachInput;
+    context?: import("./instrument.js").PaybondInstrumentContextInput;
+    traceSink?: PaybondTraceSink;
+    /** @deprecated Use {@link PaybondInstrumentAgentOptions.traceSink}. */
+    onTrace?: PaybondTraceSink;
+};
+/**
+ * Discover tools from a framework agent instance.
+ * Supports tool maps, `{ name, execute }[]`, and common SDK property names.
+ */
+export declare function discoverToolsFromAgent(agent: unknown): unknown;
+/**
+ * Resolve policy for agent instrumentation.
+ * Order: explicit option → agent.policy → agent.paybondPolicy → PAYBOND_POLICY env → ./paybond.policy.yaml
+ */
+export declare function discoverPolicyFromAgent(agent: unknown, options?: PaybondInstrumentAgentOptions): PaybondPolicyLoadSource | PaybondInlinePolicy;
+/** True when `value` is a framework agent object rather than an explicit `{ policy, tools }` config. */
+export declare function isInstrumentableAgentObject(value: unknown): value is Record<string, unknown>;
+/** Read Paybond instrumentation previously attached to an agent instance. */
+export declare function readPaybondAgentInstrumentation(agent: unknown): PaybondAgentInstrumentation | undefined;
+/** Attach guarded tools and Paybond metadata to a framework agent instance (in place). */
+export declare function attachPaybondAgentInstrumentation(agent: object, instrumentation: PaybondAgentInstrumentation, guardedTools: unknown): void;

package/dist/agent/discover.js

@@ -0,0 +1,147 @@
+const INSTRUMENT_CONFIG_KEYS = new Set([
+    "policy",
+    "tools",
+    "framework",
+    "bootstrap",
+    "attach",
+    "runId",
+    "validatePolicy",
+    "openAIAgentsOptions",
+    "sandbox",
+    "context",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isPlainInstrumentConfig(value) {
+    if (!("policy" in value) || !("tools" in value)) {
+        return false;
+    }
+    return Object.keys(value).every((key) => INSTRUMENT_CONFIG_KEYS.has(key));
+}
+function hasAgentRuntimeShape(value) {
+    if (Object.getPrototypeOf(value) !== Object.prototype) {
+        return true;
+    }
+    return ("model" in value ||
+        "run" in value ||
+        "invoke" in value ||
+        "execute" in value ||
+        "stream" in value ||
+        "mcpServer" in value ||
+        "paybond" in value);
+}
+/**
+ * Discover tools from a framework agent instance.
+ * Supports tool maps, `{ name, execute }[]`, and common SDK property names.
+ */
+export function discoverToolsFromAgent(agent) {
+    if (!isRecord(agent)) {
+        throw new TypeError("instrument(agent) requires an object with discoverable tools");
+    }
+    const candidates = [
+        agent.tools,
+        agent.functionTools,
+        agent.function_tools,
+        agent.toolDefinitions,
+        agent.tool_definitions,
+    ];
+    for (const candidate of candidates) {
+        if (candidate === undefined) {
+            continue;
+        }
+        if (Array.isArray(candidate) && candidate.length === 0) {
+            continue;
+        }
+        if (Array.isArray(candidate) || isRecord(candidate)) {
+            return candidate;
+        }
+    }
+    throw new TypeError("could not discover tools on agent; expected .tools, .functionTools, or a tool map/array");
+}
+/**
+ * Resolve policy for agent instrumentation.
+ * Order: explicit option → agent.policy → agent.paybondPolicy → PAYBOND_POLICY env → ./paybond.policy.yaml
+ */
+export function discoverPolicyFromAgent(agent, options) {
+    if (options?.policy !== undefined) {
+        return options.policy;
+    }
+    if (isRecord(agent)) {
+        if (agent.policy !== undefined) {
+            return agent.policy;
+        }
+        if (agent.paybondPolicy !== undefined) {
+            return agent.paybondPolicy;
+        }
+    }
+    const envPolicy = typeof process !== "undefined" ? process.env.PAYBOND_POLICY?.trim() : "";
+    if (envPolicy) {
+        return envPolicy;
+    }
+    return "./paybond.policy.yaml";
+}
+/** True when `value` is a framework agent object rather than an explicit `{ policy, tools }` config. */
+export function isInstrumentableAgentObject(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (isPlainInstrumentConfig(value) && !hasAgentRuntimeShape(value)) {
+        return false;
+    }
+    if (hasExplicitInstrumentOnlyFields(value)) {
+        return false;
+    }
+    try {
+        discoverToolsFromAgent(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasExplicitInstrumentOnlyFields(value) {
+    return (("attach" in value || "bootstrap" in value || "validatePolicy" in value) &&
+        !("tools" in value && hasAgentRuntimeShape(value)));
+}
+const PAYBOND_AGENT_SYMBOL = Symbol.for("paybond.agent.instrumentation");
+/** Read Paybond instrumentation previously attached to an agent instance. */
+export function readPaybondAgentInstrumentation(agent) {
+    if (!isRecord(agent)) {
+        return undefined;
+    }
+    const attached = agent[PAYBOND_AGENT_SYMBOL];
+    if (attached) {
+        return attached;
+    }
+    const legacy = agent.paybond;
+    return legacy;
+}
+/** Attach guarded tools and Paybond metadata to a framework agent instance (in place). */
+export function attachPaybondAgentInstrumentation(agent, instrumentation, guardedTools) {
+    const record = agent;
+    if ("tools" in record) {
+        record.tools = guardedTools;
+    }
+    else if ("functionTools" in record) {
+        record.functionTools = guardedTools;
+    }
+    else if ("function_tools" in record) {
+        record.function_tools = guardedTools;
+    }
+    else {
+        record.tools = guardedTools;
+    }
+    Object.defineProperty(agent, PAYBOND_AGENT_SYMBOL, {
+        value: instrumentation,
+        writable: true,
+        configurable: true,
+        enumerable: false,
+    });
+    Object.defineProperty(agent, "paybond", {
+        value: instrumentation,
+        writable: true,
+        configurable: true,
+        enumerable: false,
+    });
+}

package/dist/agent/evidence.d.ts

@@ -0,0 +1,9 @@
+import { PaybondSideEffectingToolEntry, PaybondToolCallContext } from "./types.js";
+export type BuiltAutoEvidence = {
+    payload: Record<string, unknown>;
+    vendorPayload?: Record<string, unknown>;
+};
+/**
+ * Build canonical evidence payloads from a tool result using the completion catalog.
+ */
+export declare function buildAutoEvidencePayload(entry: Pick<PaybondSideEffectingToolEntry, "evidencePreset" | "evidenceMapper">, toolResult: unknown, ctx: PaybondToolCallContext): Record<string, unknown>;

package/dist/agent/evidence.js

@@ -0,0 +1,28 @@
+import { getCompletionPreset, } from "../completion-catalog.js";
+import { isVendorPack, mapVendorEvidenceToCanonical, resolveCompletionPreset, } from "../completion-resolve.js";
+function assertEvidenceRecord(value, message) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(message);
+    }
+    return value;
+}
+/**
+ * Build canonical evidence payloads from a tool result using the completion catalog.
+ */
+export function buildAutoEvidencePayload(entry, toolResult, ctx) {
+    if (entry.evidenceMapper) {
+        return assertEvidenceRecord(entry.evidenceMapper(toolResult, ctx), "evidenceMapper must return a JSON object payload");
+    }
+    const resolved = resolveCompletionPreset(entry.evidencePreset);
+    const preset = resolved.preset;
+    if (isVendorPack(preset)) {
+        if (typeof toolResult === "object" && toolResult !== null && !Array.isArray(toolResult)) {
+            return mapVendorEvidenceToCanonical(preset, toolResult);
+        }
+        throw new Error(`side-effecting tool "${ctx.toolName}" uses vendor pack preset "${entry.evidencePreset}"; provide evidenceMapper when tool result is not a JSON object`);
+    }
+    if (typeof toolResult === "object" && toolResult !== null && !Array.isArray(toolResult)) {
+        return { ...toolResult };
+    }
+    return { ...getCompletionPreset(resolved.archetype.preset_id).sample_evidence };
+}

package/dist/agent/facade.d.ts

@@ -0,0 +1,48 @@
+import type { ClaudeAgentsConfig } from "../claude-agents/index.js";
+import type { PaybondLangGraphHooks } from "../langgraph/config.js";
+import { createOpenAIAgentsAdapter } from "../openai-agents/index.js";
+import type { PaybondPolicy } from "../policy/load.js";
+import type { PaybondPolicyLoadSource } from "../policy/load.js";
+import { paybondVercelToolApproval } from "../vercel-ai/tool-approval.js";
+import type { PaybondToolInputGuardAdapter } from "./adapter.js";
+import { type CreateGuardedAgentResult, type GuardedAgentFramework } from "./guarded-agent.js";
+import { type PaybondInstrumentInput } from "./instrument.js";
+import type { PaybondAgentRun, PaybondAgentRunHost } from "./run.js";
+/**
+ * Resolve a policy preset id (for example `travel`) or pass through file paths and in-memory documents.
+ */
+export declare function resolveAgentPolicySource(policy: PaybondPolicyLoadSource): PaybondPolicyLoadSource;
+export type PaybondAgentInput<TTools = unknown> = PaybondInstrumentInput<TTools> & {
+    policy: PaybondPolicyLoadSource;
+};
+/** Framework-native wiring returned by {@link createPaybondAgent} / {@link Paybond.agent}. */
+export type PaybondAgentHooks = {
+    inputGuard?: PaybondToolInputGuardAdapter;
+    toolApproval?: ReturnType<typeof paybondVercelToolApproval>;
+    awrapToolCall?: PaybondLangGraphHooks["awrapToolCall"];
+    createToolNode?: PaybondLangGraphHooks["createToolNode"];
+    runConfig?: ReturnType<typeof createOpenAIAgentsAdapter>["runConfig"];
+    openAIAgentsAdapter?: ReturnType<typeof createOpenAIAgentsAdapter>;
+    mcpServer?: ClaudeAgentsConfig["mcpServer"];
+    allowedTools?: ClaudeAgentsConfig["allowedTools"];
+};
+/** Opinionated quickstart result: guarded tools plus framework hooks. */
+export type PaybondAgentResult<TTools = unknown> = {
+    run: PaybondAgentRun;
+    tools: TTools;
+    hooks: PaybondAgentHooks;
+    policy: PaybondPolicy;
+};
+/** Normalize {@link CreateGuardedAgentResult} into the quickstart `{ run, tools, hooks, policy }` shape. */
+export declare function toPaybondAgentResult<TTools>(result: CreateGuardedAgentResult<TTools>): PaybondAgentResult<TTools>;
+/** Opinionated quickstart: resolve named presets, then delegate to {@link instrumentPaybondAgent}. */
+export declare function createPaybondAgent<TTools>(paybond: PaybondAgentRunHost, input: PaybondAgentInput<TTools>): Promise<PaybondAgentResult<TTools>>;
+export type PaybondWrapToolsOptions = {
+    framework?: GuardedAgentFramework;
+    sandbox?: boolean;
+    attach?: import("./instrument.js").PaybondInstrumentAttachInput;
+    context?: import("./instrument.js").PaybondInstrumentContextInput;
+};
+/** Wrap tools for an existing bound run without reloading policy. */
+export declare function wrapPaybondTools(run: PaybondAgentRun, tools: unknown, options?: PaybondWrapToolsOptions): unknown;
+export type { PaybondInstrumentInput } from "./instrument.js";