@paybond/kit 0.10.0 → 0.11.0

package/dist/agent/instrument.d.ts

@@ -0,0 +1,156 @@
+import type { PaybondPolicy, PaybondPolicyLoadSource } from "../policy/load.js";
+import type { PaybondPolicyDocumentV1 } from "../policy/schema.js";
+import { type PaybondInstrumentAgentOptions } from "./discover.js";
+import { type CreateGuardedAgentInput, type GuardedAgentFramework } from "./guarded-agent.js";
+import { type PaybondAgentHooks, type PaybondWrapToolsOptions } from "./facade.js";
+import { PaybondAgentRun, type PaybondAgentRunHost } from "./run.js";
+import type { PaybondRunBinding, PaybondRunBindingAttachInput, PaybondRunProductionEvidenceCredentials, PaybondTraceSink } from "./types.js";
+/** Production attach from console env vars or an explicit funded-intent binding. */
+export type PaybondInstrumentAttachInput = PaybondRunBindingAttachInput | "env";
+/** Simplified inline policy for tutorials and quick examples. */
+export type PaybondInlinePolicy = {
+    name?: string;
+    budget?: string | {
+        max_spend_usd?: number;
+        currency?: string;
+        period?: string;
+    };
+    approve?: readonly string[];
+    deny?: readonly string[];
+};
+/** Intent + capability for a single agent session, HTTP request, or task. */
+export type PaybondInstrumentContext = {
+    intentId: string;
+    capabilityToken: string;
+    /** Optional operator or end-user id for audit attribution (`agentSubject` on intercept). */
+    userId?: string;
+    allowedTools?: readonly string[];
+    productionEvidence?: PaybondRunProductionEvidenceCredentials;
+    sandbox?: PaybondRunBinding["sandbox"];
+};
+/** Resolves request-local intent binding on each tool execution. */
+export type PaybondInstrumentContextProvider = () => PaybondInstrumentContext | Promise<PaybondInstrumentContext>;
+/** Static bind object or per-request provider passed to {@link instrumentPaybondAgent}. */
+export type PaybondInstrumentContextInput = PaybondInstrumentContext | PaybondInstrumentContextProvider;
+/**
+ * Where the active intent comes from — inspect via `.binding` or `.status` on any instrument surface.
+ */
+export type PaybondInstrumentBinding = {
+    phase: "deferred";
+} | {
+    phase: "lazy";
+} | {
+    phase: "bound";
+    mode: "sandbox" | "attach";
+    intentId: string;
+    capabilityToken: string;
+    tenantId: string;
+    userId?: string;
+};
+export type { PaybondAgentInstrumentation, PaybondInstrumentAgentOptions, } from "./discover.js";
+export { PaybondUnboundContextError, wrapDeferredTools } from "./deferred-tools.js";
+export { PaybondLazyContextError, wrapLazyContextTools, type LazyRuntimeResolver, } from "./lazy-context-tools.js";
+export { discoverPolicyFromAgent, discoverToolsFromAgent, isInstrumentableAgentObject, readPaybondAgentInstrumentation, } from "./discover.js";
+type PaybondInstrumentBaseInput<TTools = unknown> = Omit<CreateGuardedAgentInput<TTools>, "framework" | "policy" | "tools" | "attach"> & {
+    policy?: PaybondPolicyLoadSource | PaybondInlinePolicy | PaybondPolicy;
+    tools?: TTools;
+    framework?: GuardedAgentFramework;
+    /** Bootstrap a sandbox intent immediately (local dev). Default is deferred bind via {@link PaybondInstrumented.bind}. */
+    sandbox?: boolean;
+    /**
+     * Attach a funded production intent from console env vars (`attach: "env"`) or an explicit binding object.
+     * Returns a bound {@link PaybondInstrumentRuntime} immediately.
+     */
+    attach?: PaybondInstrumentAttachInput;
+    /**
+     * Attach a funded intent during `instrument()` and return a bound {@link PaybondInstrumentRuntime},
+     * or pass a provider function for lazy per-execution binding (request-local context).
+     */
+    context?: PaybondInstrumentContextInput;
+};
+/** Input for {@link instrumentPaybondAgent} — pass `{ policy, tools }` or a framework agent instance. */
+export type PaybondInstrumentInput<TTools = unknown> = PaybondInstrumentBaseInput<TTools>;
+export declare function isInlinePolicy(value: unknown): value is PaybondInlinePolicy;
+export declare function discoverToolNames(tools: unknown): string[];
+export declare function inlinePolicyToDocument(inline: PaybondInlinePolicy, tools: unknown): PaybondPolicyDocumentV1;
+/**
+ * Bound Paybond runtime for one agent session — immutable; create a new runtime per request.
+ */
+export declare class PaybondInstrumentRuntime<TTools = unknown> {
+    readonly tools: TTools;
+    readonly run: PaybondAgentRun;
+    readonly policy: PaybondPolicy;
+    readonly hooks: PaybondAgentHooks;
+    readonly binding: Extract<PaybondInstrumentBinding, {
+        phase: "bound";
+    }>;
+    constructor(tools: TTools, run: PaybondAgentRun, policy: PaybondPolicy, hooks: PaybondAgentHooks, binding: Extract<PaybondInstrumentBinding, {
+        phase: "bound";
+    }>);
+    /** Alias for {@link PaybondInstrumentRuntime.binding}. */
+    get status(): PaybondInstrumentBinding;
+    /** Release hooks for this runtime (no-op today; reserved for long-lived sessions). */
+    close(): void;
+}
+/**
+ * Static instrumentation: policy + tool shells. Call {@link PaybondInstrumented.bind}
+ * per session, or pass a `context` provider for lazy per-execution binding.
+ */
+export declare class PaybondInstrumented<TTools = unknown> {
+    readonly tools: TTools;
+    readonly policy: PaybondPolicy;
+    readonly binding: Extract<PaybondInstrumentBinding, {
+        phase: "deferred";
+    } | {
+        phase: "lazy";
+    }>;
+    private readonly paybond;
+    private readonly rawTools;
+    private readonly framework;
+    private readonly contextProvider?;
+    private readonly traceSink?;
+    private readonly runtimeCache;
+    constructor(paybond: PaybondAgentRunHost, policy: PaybondPolicy, rawTools: TTools, framework: GuardedAgentFramework, options?: {
+        contextProvider?: PaybondInstrumentContextProvider;
+        traceSink?: PaybondTraceSink;
+    });
+    /** Alias for {@link PaybondInstrumented.binding}. */
+    get status(): PaybondInstrumentBinding;
+    private resolveRuntime;
+    private resolveRuntimeFromProvider;
+    /**
+     * Bind a per-request intent and capability. Returns a new immutable runtime — safe for concurrent sessions.
+     */
+    bind(context: PaybondInstrumentContext): Promise<PaybondInstrumentRuntime<TTools>>;
+    /** @deprecated Use {@link PaybondInstrumented.bind}. */
+    withContext(context: PaybondInstrumentContext): Promise<PaybondInstrumentRuntime<TTools>>;
+}
+/** Fluent builder: `paybond.policy("./paybond.policy.yaml").instrument(tools)`. */
+export declare class PaybondInstrumentBuilder<TTools = unknown> {
+    private readonly paybond;
+    private readonly policy;
+    private readonly framework?;
+    constructor(paybond: PaybondAgentRunHost, policy: PaybondPolicyLoadSource | PaybondInlinePolicy, framework?: GuardedAgentFramework | undefined);
+    instrument(tools: TTools, options?: {
+        sandbox?: boolean;
+        context?: PaybondInstrumentContextInput;
+    }): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+    withFramework(framework: GuardedAgentFramework): PaybondInstrumentBuilder<TTools>;
+}
+export declare function instrumentPaybondAgent<TTools>(paybond: PaybondAgentRunHost, input: PaybondInstrumentInput<TTools>, options?: PaybondWrapToolsOptions & PaybondInstrumentAgentOptions): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+export declare function instrumentPaybondAgent<TAgent extends object>(paybond: PaybondAgentRunHost, agent: TAgent, options?: PaybondWrapToolsOptions & PaybondInstrumentAgentOptions): Promise<TAgent>;
+export declare function instrumentPaybondLangGraph<TTools>(paybond: PaybondAgentRunHost, input: Omit<PaybondInstrumentBaseInput<TTools>, "framework"> & {
+    tools: TTools;
+}): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+export declare function instrumentPaybondOpenAI<TTools>(paybond: PaybondAgentRunHost, input: Omit<PaybondInstrumentBaseInput<TTools>, "framework"> & {
+    tools: TTools;
+}): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+export declare function instrumentPaybondVercel<TTools>(paybond: PaybondAgentRunHost, input: Omit<PaybondInstrumentBaseInput<TTools>, "framework"> & {
+    tools: TTools;
+}): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+export declare function instrumentPaybondClaudeAgents<TTools>(paybond: PaybondAgentRunHost, input: Omit<PaybondInstrumentBaseInput<TTools>, "framework"> & {
+    tools: TTools;
+}): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;
+export declare function instrumentPaybondMCP<TTools>(paybond: PaybondAgentRunHost, input: Omit<PaybondInstrumentBaseInput<TTools>, "framework"> & {
+    tools: TTools;
+}): Promise<PaybondInstrumented<TTools> | PaybondInstrumentRuntime<TTools>>;

package/dist/agent/instrument.js

@@ -0,0 +1,442 @@
+import { PaybondPolicy as PaybondPolicyClass } from "../policy/load.js";
+import { wrapDeferredTools } from "./deferred-tools.js";
+import { PaybondLazyContextError, wrapLazyContextTools } from "./lazy-context-tools.js";
+import { attachPaybondAgentInstrumentation, discoverPolicyFromAgent, discoverToolsFromAgent, isInstrumentableAgentObject, } from "./discover.js";
+import { createGuardedAgent, } from "./guarded-agent.js";
+import { toPaybondAgentResult, wrapPaybondTools, } from "./facade.js";
+import { PaybondAgentRun } from "./run.js";
+import { resolveAttachContextFromEnv, } from "./attach-bundle.js";
+export { PaybondUnboundContextError, wrapDeferredTools } from "./deferred-tools.js";
+export { PaybondLazyContextError, wrapLazyContextTools, } from "./lazy-context-tools.js";
+export { discoverPolicyFromAgent, discoverToolsFromAgent, isInstrumentableAgentObject, readPaybondAgentInstrumentation, } from "./discover.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isFullPolicyDocument(value) {
+    return (typeof value.version === "number" ||
+        typeof value.default_deny === "boolean" ||
+        (isRecord(value.tools) &&
+            Object.values(value.tools).some((entry) => isRecord(entry) && typeof entry.side_effecting === "boolean")));
+}
+export function isInlinePolicy(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (isFullPolicyDocument(value)) {
+        return false;
+    }
+    return "budget" in value || "approve" in value || "deny" in value;
+}
+function globPatternToRegExp(pattern) {
+    const escaped = pattern
+        .trim()
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`);
+}
+function matchesAnyGlob(value, patterns) {
+    return patterns.some((pattern) => globPatternToRegExp(pattern).test(value));
+}
+function parseBudgetString(budget) {
+    const trimmed = budget.trim();
+    const match = /^\$?([\d,]+(?:\.\d+)?)(?:\s*\/\s*(day|week|month|year))?$/i.exec(trimmed);
+    if (!match) {
+        throw new Error(`inline policy budget must look like "$500/day" (got ${JSON.stringify(budget)})`);
+    }
+    const amount = Number.parseFloat(match[1].replace(/,/g, ""));
+    const period = match[2]?.toLowerCase();
+    return {
+        currency: "usd",
+        max_spend_usd: amount,
+        ...(period ? { period } : {}),
+    };
+}
+function resolveInlineBudget(budget) {
+    if (budget === undefined) {
+        return undefined;
+    }
+    if (typeof budget === "string") {
+        return parseBudgetString(budget);
+    }
+    return {
+        currency: budget.currency ?? "usd",
+        ...(budget.max_spend_usd !== undefined ? { max_spend_usd: budget.max_spend_usd } : {}),
+        ...(budget.period ? { period: budget.period } : {}),
+    };
+}
+export function discoverToolNames(tools) {
+    if (Array.isArray(tools)) {
+        const names = [];
+        for (const tool of tools) {
+            if (!isRecord(tool) || typeof tool.name !== "string" || !tool.name.trim()) {
+                throw new TypeError("discovered tool array entries must include a non-empty name");
+            }
+            names.push(tool.name.trim());
+        }
+        return names;
+    }
+    if (isRecord(tools)) {
+        return Object.keys(tools).filter((key) => key.trim().length > 0);
+    }
+    throw new TypeError("could not discover tool names; pass an object map or { name, execute }[]");
+}
+export function inlinePolicyToDocument(inline, tools) {
+    const toolNames = discoverToolNames(tools);
+    const approve = inline.approve ?? ["*"];
+    const deny = inline.deny ?? [];
+    const allowedTools = [];
+    const toolsSection = {};
+    for (const toolName of toolNames) {
+        if (deny.length > 0 && matchesAnyGlob(toolName, deny)) {
+            continue;
+        }
+        if (!matchesAnyGlob(toolName, approve)) {
+            continue;
+        }
+        allowedTools.push(toolName);
+        toolsSection[toolName] = {
+            side_effecting: true,
+            evidence_preset: "cost_and_completion",
+        };
+    }
+    if (allowedTools.length === 0) {
+        throw new Error("inline policy matched no tools; widen approve patterns or pass explicit tools");
+    }
+    const budget = resolveInlineBudget(inline.budget);
+    return {
+        version: 1,
+        name: inline.name ?? "inline-policy",
+        default_deny: true,
+        tools: toolsSection,
+        intent: {
+            allowed_tools: allowedTools,
+            ...(budget ? { budget } : {}),
+        },
+    };
+}
+function isContextProvider(value) {
+    return typeof value === "function";
+}
+function runtimeCacheKey(context) {
+    return `${context.intentId}\0${context.capabilityToken}\0${context.userId ?? ""}`;
+}
+function assertInstrumentContext(context) {
+    if (!context.intentId?.trim() || !context.capabilityToken?.trim()) {
+        throw new PaybondLazyContextError();
+    }
+}
+function resolveInstrumentAttachContext(attach, env = process.env) {
+    if (attach === undefined) {
+        return undefined;
+    }
+    if (attach === "env") {
+        const resolved = resolveAttachContextFromEnv(env);
+        return {
+            intentId: resolved.intentId,
+            capabilityToken: resolved.capabilityToken,
+            productionEvidence: resolved.productionEvidence,
+        };
+    }
+    return {
+        intentId: attach.intentId,
+        capabilityToken: attach.capabilityToken,
+        allowedTools: attach.allowedTools,
+        productionEvidence: attach.productionEvidence,
+        sandbox: attach.sandbox,
+    };
+}
+function normalizeInstrumentConfig(input) {
+    if (input.tools === undefined) {
+        throw new Error("instrument() requires tools when using { policy, tools } config");
+    }
+    if (input.policy === undefined) {
+        throw new Error("instrument() requires policy when using { policy, tools } config");
+    }
+    if (input.sandbox && (input.context !== undefined || input.attach !== undefined)) {
+        throw new Error('instrument() accepts either sandbox: true, attach, or context — not multiple bind modes');
+    }
+    if (input.attach !== undefined && input.context !== undefined) {
+        throw new Error('instrument() accepts either attach or context, not both');
+    }
+    return { ...input, tools: input.tools };
+}
+async function resolveInstrumentPolicy(policySource, tools) {
+    if (policySource instanceof PaybondPolicyClass) {
+        return policySource;
+    }
+    if (policySource === undefined) {
+        throw new Error("instrument() requires policy (file path, preset id, inline object, or PaybondPolicy)");
+    }
+    if (isInlinePolicy(policySource)) {
+        return PaybondPolicyClass.fromDocument(inlinePolicyToDocument(policySource, tools));
+    }
+    return PaybondPolicyClass.load(policySource);
+}
+function bindingFromRun(run, mode, userId) {
+    return {
+        phase: "bound",
+        mode,
+        intentId: run.binding.intentId,
+        capabilityToken: run.binding.capabilityToken,
+        tenantId: run.binding.tenantId,
+        ...(userId ? { userId } : {}),
+    };
+}
+function hooksFromGuardedResult(result) {
+    return toPaybondAgentResult(result).hooks;
+}
+function wrapToolsForFramework(run, rawTools, framework, guarded) {
+    if (framework === "langgraph") {
+        return rawTools;
+    }
+    if (guarded) {
+        return guarded.agentTools;
+    }
+    return wrapPaybondTools(run, rawTools, { framework });
+}
+/**
+ * Bound Paybond runtime for one agent session — immutable; create a new runtime per request.
+ */
+export class PaybondInstrumentRuntime {
+    tools;
+    run;
+    policy;
+    hooks;
+    binding;
+    constructor(tools, run, policy, hooks, binding) {
+        this.tools = tools;
+        this.run = run;
+        this.policy = policy;
+        this.hooks = hooks;
+        this.binding = binding;
+    }
+    /** Alias for {@link PaybondInstrumentRuntime.binding}. */
+    get status() {
+        return this.binding;
+    }
+    /** Release hooks for this runtime (no-op today; reserved for long-lived sessions). */
+    close() { }
+}
+/**
+ * Static instrumentation: policy + tool shells. Call {@link PaybondInstrumented.bind}
+ * per session, or pass a `context` provider for lazy per-execution binding.
+ */
+export class PaybondInstrumented {
+    tools;
+    policy;
+    binding;
+    paybond;
+    rawTools;
+    framework;
+    contextProvider;
+    traceSink;
+    runtimeCache = new Map();
+    constructor(paybond, policy, rawTools, framework, options) {
+        this.paybond = paybond;
+        this.policy = policy;
+        this.rawTools = rawTools;
+        this.framework = framework;
+        this.contextProvider = options?.contextProvider;
+        this.traceSink = options?.traceSink;
+        this.binding = options?.contextProvider ? { phase: "lazy" } : { phase: "deferred" };
+        this.tools = options?.contextProvider
+            ? wrapLazyContextTools(rawTools, { resolve: () => this.resolveRuntimeFromProvider() })
+            : wrapDeferredTools(rawTools);
+    }
+    /** Alias for {@link PaybondInstrumented.binding}. */
+    get status() {
+        return this.binding;
+    }
+    async resolveRuntime(context) {
+        assertInstrumentContext(context);
+        const key = runtimeCacheKey(context);
+        const cached = this.runtimeCache.get(key);
+        if (cached) {
+            return cached;
+        }
+        const runtime = await createBoundRuntime(this.paybond, this.policy, this.rawTools, this.framework, context, "attach", this.traceSink);
+        this.runtimeCache.set(key, runtime);
+        return runtime;
+    }
+    async resolveRuntimeFromProvider() {
+        if (!this.contextProvider) {
+            throw new Error("lazy context resolution requires a context provider on instrument()");
+        }
+        const context = await this.contextProvider();
+        return this.resolveRuntime(context);
+    }
+    /**
+     * Bind a per-request intent and capability. Returns a new immutable runtime — safe for concurrent sessions.
+     */
+    bind(context) {
+        return createBoundRuntime(this.paybond, this.policy, this.rawTools, this.framework, context, "attach", this.traceSink);
+    }
+    /** @deprecated Use {@link PaybondInstrumented.bind}. */
+    withContext(context) {
+        return this.bind(context);
+    }
+}
+async function createBoundRuntime(paybond, policy, rawTools, framework, context, bindMode, traceSink) {
+    if (bindMode === "sandbox") {
+        const result = await createGuardedAgent(paybond, {
+            policy,
+            framework,
+            tools: rawTools,
+            traceSink,
+        });
+        return toPaybondInstrumentRuntime(result, rawTools, result.run.binding.sandbox ? "sandbox" : "attach", context.userId);
+    }
+    const attach = {
+        intentId: context.intentId,
+        capabilityToken: context.capabilityToken,
+        allowedTools: context.allowedTools,
+        productionEvidence: context.productionEvidence,
+        sandbox: context.sandbox,
+    };
+    const run = await PaybondAgentRun.bind(paybond, {
+        registry: policy.toToolRegistry(),
+        attach,
+        traceSink,
+    });
+    const tools = wrapToolsForFramework(run, rawTools, framework);
+    const hooks = hooksFromGuardedResult({
+        run,
+        policy,
+        registry: policy.toToolRegistry(),
+        framework,
+        agentTools: tools,
+    });
+    return new PaybondInstrumentRuntime(tools, run, policy, hooks, bindingFromRun(run, "attach", context.userId));
+}
+function toPaybondInstrumentRuntime(result, rawTools, bindMode, userId) {
+    const agentResult = toPaybondAgentResult(result);
+    return new PaybondInstrumentRuntime(agentResult.tools, agentResult.run, agentResult.policy, agentResult.hooks, bindingFromRun(agentResult.run, bindMode, userId));
+}
+function createDeferredInstrumented(paybond, policy, rawTools, framework, options) {
+    return new PaybondInstrumented(paybond, policy, rawTools, framework, options);
+}
+function resolveInstrumentFramework(framework) {
+    return framework ?? "generic";
+}
+/** Fluent builder: `paybond.policy("./paybond.policy.yaml").instrument(tools)`. */
+export class PaybondInstrumentBuilder {
+    paybond;
+    policy;
+    framework;
+    constructor(paybond, policy, framework) {
+        this.paybond = paybond;
+        this.policy = policy;
+        this.framework = framework;
+    }
+    instrument(tools, options) {
+        return instrumentPaybondAgent(this.paybond, {
+            policy: this.policy,
+            tools,
+            framework: this.framework,
+            sandbox: options?.sandbox,
+            context: options?.context,
+        });
+    }
+    withFramework(framework) {
+        return new PaybondInstrumentBuilder(this.paybond, this.policy, framework);
+    }
+}
+function instrumentationFromRuntime(runtime) {
+    return {
+        run: runtime.run,
+        policy: runtime.policy,
+        hooks: runtime.hooks,
+        tools: runtime.tools,
+        binding: runtime.binding,
+        status: runtime.status,
+    };
+}
+function instrumentationFromInstrumented(agent, instrumented) {
+    const surface = {
+        policy: instrumented.policy,
+        hooks: {},
+        tools: instrumented.tools,
+        binding: instrumented.binding,
+        status: instrumented.status,
+        bind: async (context) => {
+            const runtime = await instrumented.bind(context);
+            const bound = instrumentationFromRuntime(runtime);
+            attachPaybondAgentInstrumentation(agent, bound, runtime.tools);
+            return bound;
+        },
+        withContext: async (context) => surface.bind(context),
+    };
+    return surface;
+}
+async function instrumentAgentObject(paybond, agent, options) {
+    const rawTools = discoverToolsFromAgent(agent);
+    const policySource = discoverPolicyFromAgent(agent, options);
+    const framework = resolveInstrumentFramework(options?.framework);
+    const policy = await resolveInstrumentPolicy(policySource, rawTools);
+    const traceSink = options?.traceSink ?? options?.onTrace;
+    if (options?.sandbox) {
+        const runtime = await createBoundRuntime(paybond, policy, rawTools, framework, { intentId: "", capabilityToken: "" }, "sandbox", traceSink);
+        attachPaybondAgentInstrumentation(agent, instrumentationFromRuntime(runtime), runtime.tools);
+        return agent;
+    }
+    if (options?.context) {
+        if (isContextProvider(options.context)) {
+            const instrumented = createDeferredInstrumented(paybond, policy, rawTools, framework, {
+                contextProvider: options.context,
+                traceSink,
+            });
+            attachPaybondAgentInstrumentation(agent, instrumentationFromInstrumented(agent, instrumented), instrumented.tools);
+            return agent;
+        }
+        const runtime = await createBoundRuntime(paybond, policy, rawTools, framework, options.context, "attach", traceSink);
+        attachPaybondAgentInstrumentation(agent, instrumentationFromRuntime(runtime), runtime.tools);
+        return agent;
+    }
+    const instrumented = createDeferredInstrumented(paybond, policy, rawTools, framework, { traceSink });
+    attachPaybondAgentInstrumentation(agent, instrumentationFromInstrumented(agent, instrumented), instrumented.tools);
+    return agent;
+}
+export async function instrumentPaybondAgent(paybond, input, options) {
+    if (isInstrumentableAgentObject(input)) {
+        return instrumentAgentObject(paybond, input, options);
+    }
+    const normalized = normalizeInstrumentConfig(input);
+    const framework = resolveInstrumentFramework(options?.framework ?? normalized.framework);
+    const policy = await resolveInstrumentPolicy(normalized.policy, normalized.tools);
+    const traceSink = normalized.traceSink ?? normalized.onTrace;
+    const sandbox = normalized.sandbox ?? options?.sandbox ?? false;
+    const attachContext = resolveInstrumentAttachContext(normalized.attach ?? options?.attach);
+    const context = attachContext ?? normalized.context ?? options?.context;
+    if (sandbox) {
+        return createBoundRuntime(paybond, policy, normalized.tools, framework, { intentId: "", capabilityToken: "" }, "sandbox", traceSink);
+    }
+    if (context !== undefined) {
+        if (isContextProvider(context)) {
+            return createDeferredInstrumented(paybond, policy, normalized.tools, framework, {
+                contextProvider: context,
+                traceSink,
+            });
+        }
+        return createBoundRuntime(paybond, policy, normalized.tools, framework, context, "attach", traceSink);
+    }
+    return createDeferredInstrumented(paybond, policy, normalized.tools, framework, { traceSink });
+}
+function frameworkInstrument(paybond, framework, input) {
+    return instrumentPaybondAgent(paybond, { ...input, framework });
+}
+export function instrumentPaybondLangGraph(paybond, input) {
+    return frameworkInstrument(paybond, "langgraph", input);
+}
+export function instrumentPaybondOpenAI(paybond, input) {
+    return frameworkInstrument(paybond, "openai-agents", input);
+}
+export function instrumentPaybondVercel(paybond, input) {
+    return frameworkInstrument(paybond, "vercel-ai", input);
+}
+export function instrumentPaybondClaudeAgents(paybond, input) {
+    return frameworkInstrument(paybond, "claude-agents", input);
+}
+export function instrumentPaybondMCP(paybond, input) {
+    return frameworkInstrument(paybond, "generic", input);
+}

package/dist/agent/interceptor.d.ts

@@ -0,0 +1,24 @@
+import type { PaybondAgentRunHost } from "./run.js";
+import { PaybondAuthorizeToolCallInput, PaybondInterceptWrapExecuteInput, PaybondInterceptWrapExecuteResult, PaybondRunBinding, PaybondToolInputGuardDecision } from "./types.js";
+export { PaybondAutoEvidenceSubmitError, PaybondEvidenceSubmitError } from "./types.js";
+/**
+ * Pre/post intercept for side-effecting tools: authorize, execute, finalize spend, auto-evidence.
+ */
+export declare class PaybondToolInterceptor {
+    private readonly binding;
+    private readonly host;
+    private readonly authorizedCalls;
+    private _inFlightCount;
+    constructor(binding: PaybondRunBinding, host: PaybondAgentRunHost);
+    /** Active in-flight authorize/execute cycles (blocks policy reload until zero). */
+    get inFlightCount(): number;
+    private beginInFlight;
+    private endInFlight;
+    private emitTrace;
+    /** Authorize-only pre-execution check for framework tool input guardrails. */
+    authorizeToolCall(input: PaybondAuthorizeToolCallInput): Promise<PaybondToolInputGuardDecision>;
+    /** Run one tool through the middleware authorize → execute → evidence cycle. */
+    wrapExecute<TResult>(input: PaybondInterceptWrapExecuteInput<TResult>): Promise<PaybondInterceptWrapExecuteResult<TResult>>;
+    private resolveSideEffectingCall;
+    private submitAutoEvidence;
+}