@bondedhq/sdk 0.1.3 → 0.1.5

package/dist/langchain.js

@@ -1,5 +1,6 @@
 import { DynamicStructuredTool } from "@langchain/core/tools";
 import { resolveTools, resultText } from "./mcp.js";
+import { guardPayments, isPaymentRefusal } from "./payments.js";
 import { bondedVaultTools } from "./vault-tools.js";
 /**
  * The episode's tools as LangChain `StructuredTool`s, for LangChain and LangGraph agents
@@ -50,4 +51,37 @@ export function bondedVaultLangChainTools(options) {
         func: async (args) => resultText(await t.call(args ?? {})),
     }));
 }
+/**
+ * Your own LangChain pay tool, with every call checked against the payment mandate first (see
+ * `PaymentGuard`). Same name, description and schema. When the guard refuses (Enforce mode
+ * blocked it, the guard is frozen, or it can't read the payment) your tool is not called and the
+ * model gets `Error: ...` naming the rules broken, so it can react. In Monitor mode a breaking
+ * payment goes through and the guard's `onBreach` reports it. A local check: no receipts.
+ *
+ * ```ts
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * const tools = [...readOnlyTools, guardLangChainPayTool(payInvoice, { guard })];
+ * ```
+ *
+ * The payment is read from the tool's arguments: `{ account, amountUsd, invoiceReference }` unless
+ * you pass `toPayment`.
+ */
+export function guardLangChainPayTool(payTool, options) {
+    const guarded = guardPayments((args, config) => payTool.invoke(args, config), options);
+    return new DynamicStructuredTool({
+        name: payTool.name,
+        description: payTool.description,
+        schema: payTool.schema,
+        func: async (args, _runManager, config) => {
+            try {
+                return await guarded(args ?? {}, config);
+            }
+            catch (error) {
+                if (isPaymentRefusal(error))
+                    return `Error: ${error.message}`;
+                throw error;
+            }
+        },
+    });
+}
 //# sourceMappingURL=langchain.js.map

package/dist/mcp.d.ts

@@ -1,7 +1,10 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import type { DoneRequest } from "@bondedhq/shared";
+import { type GuardPaymentsOptions } from "./payments.js";
 export { isBondedEpisode } from "./episode.js";
 export { finishEpisode } from "./done.js";
+export type { GuardPaymentsOptions } from "./payments.js";
 /**
  * Where an episode's tools are. A `BondedEpisode` (from `fromBondedEnv`, or the one an Agent URL
  * handler hands you) has these, and so does the runner protocol's `EpisodeMessage`.
@@ -128,4 +131,21 @@ export declare function mcpConfigJson(episode?: {
         mcp: string;
     };
 }, options?: McpConfigOptions): string;
+/**
+ * Your MCP server's pay tool handler, with every call checked against the payment mandate first
+ * (see `PaymentGuard`). Register the result in its place:
+ *
+ * ```ts
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * server.registerTool("pay_invoice", config, guardMcpPayHandler(payInvoice, { guard }));
+ * ```
+ *
+ * When the guard refuses (Enforce mode blocked it, the guard is frozen, or it can't read the
+ * payment) your handler is not called and the client gets an error result (`isError: true`)
+ * naming the rules broken, so the model can react. In Monitor mode a breaking payment goes
+ * through and the guard's `onBreach` reports it. The payment is read from the tool's arguments:
+ * `{ account, amountUsd, invoiceReference }` unless you pass `toPayment`. A local check: no
+ * receipts.
+ */
+export declare function guardMcpPayHandler<I, Rest extends unknown[]>(handler: (args: I, ...rest: Rest) => CallToolResult | Promise<CallToolResult>, options: GuardPaymentsOptions<I>): (args: I, ...rest: Rest) => Promise<CallToolResult>;
 //# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.js

@@ -3,6 +3,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { BondedError } from "./errors.js";
 import { finishEpisode } from "./done.js";
 import { fromBondedEnv } from "./episode.js";
+import { guardPayments, isPaymentRefusal } from "./payments.js";
 export { isBondedEpisode } from "./episode.js";
 export { finishEpisode } from "./done.js";
 /**
@@ -108,4 +109,33 @@ export function mcpConfig(episode = fromBondedEnv(), options = {}) {
 export function mcpConfigJson(episode = fromBondedEnv(), options = {}) {
     return `${JSON.stringify(mcpConfig(episode, options), null, 2)}\n`;
 }
+/**
+ * Your MCP server's pay tool handler, with every call checked against the payment mandate first
+ * (see `PaymentGuard`). Register the result in its place:
+ *
+ * ```ts
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * server.registerTool("pay_invoice", config, guardMcpPayHandler(payInvoice, { guard }));
+ * ```
+ *
+ * When the guard refuses (Enforce mode blocked it, the guard is frozen, or it can't read the
+ * payment) your handler is not called and the client gets an error result (`isError: true`)
+ * naming the rules broken, so the model can react. In Monitor mode a breaking payment goes
+ * through and the guard's `onBreach` reports it. The payment is read from the tool's arguments:
+ * `{ account, amountUsd, invoiceReference }` unless you pass `toPayment`. A local check: no
+ * receipts.
+ */
+export function guardMcpPayHandler(handler, options) {
+    const guarded = guardPayments(handler, options);
+    return async (args, ...rest) => {
+        try {
+            return await guarded(args, ...rest);
+        }
+        catch (error) {
+            if (isPaymentRefusal(error))
+                return { content: [{ type: "text", text: error.message }], isError: true };
+            throw error;
+        }
+    };
+}
 //# sourceMappingURL=mcp.js.map

package/dist/openai-agents.d.ts

@@ -0,0 +1,33 @@
+import { type GuardPaymentsOptions } from "./payments.js";
+export type { GuardPaymentsOptions } from "./payments.js";
+/**
+ * The part of an OpenAI Agents SDK function tool (`tool()` from `@openai/agents`) the guard needs.
+ * The SDK calls `invoke` with the run context and the model's arguments as a JSON string.
+ */
+export interface OpenAiAgentsFunctionTool {
+    type: "function";
+    name: string;
+    invoke: (runContext: never, input: string, details?: never) => Promise<unknown>;
+}
+/**
+ * Your own OpenAI Agents SDK pay tool, with every call checked against the payment mandate first
+ * (see `PaymentGuard`, or pass the hosted `PaymentGate` as `guard`). Same name, description,
+ * parameters, approval setting and guardrails. When the guard refuses (Enforce mode blocked it,
+ * the guard is frozen, the gate couldn't be reached, or it can't read the payment) your tool is not
+ * called and the model gets `Error: ...` naming the rules broken, so it can react. In Monitor mode
+ * a breaking payment goes through and the guard's `onBreach` reports it.
+ *
+ * ```ts
+ * import { Agent, tool } from "@openai/agents";
+ * import { guardOpenAiAgentsPayTool } from "@bondedhq/sdk/openai-agents";
+ *
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * const agent = new Agent({ name: "AP clerk", tools: [...readOnlyTools, guardOpenAiAgentsPayTool(payInvoice, { guard })] });
+ * ```
+ *
+ * The payment is read from the tool's arguments: `{ account, amountUsd, invoiceReference }` unless
+ * you pass `toPayment`. If the tool needs a person's approval, the run stops for it before the
+ * guard is asked, so an approved payment can still be blocked.
+ */
+export declare function guardOpenAiAgentsPayTool<T extends OpenAiAgentsFunctionTool>(payTool: T, options: GuardPaymentsOptions<Record<string, unknown>>): T;
+//# sourceMappingURL=openai-agents.d.ts.map

package/dist/openai-agents.js

@@ -0,0 +1,52 @@
+import { BondedError } from "./errors.js";
+import { guardPayments, isPaymentRefusal } from "./payments.js";
+/**
+ * Your own OpenAI Agents SDK pay tool, with every call checked against the payment mandate first
+ * (see `PaymentGuard`, or pass the hosted `PaymentGate` as `guard`). Same name, description,
+ * parameters, approval setting and guardrails. When the guard refuses (Enforce mode blocked it,
+ * the guard is frozen, the gate couldn't be reached, or it can't read the payment) your tool is not
+ * called and the model gets `Error: ...` naming the rules broken, so it can react. In Monitor mode
+ * a breaking payment goes through and the guard's `onBreach` reports it.
+ *
+ * ```ts
+ * import { Agent, tool } from "@openai/agents";
+ * import { guardOpenAiAgentsPayTool } from "@bondedhq/sdk/openai-agents";
+ *
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * const agent = new Agent({ name: "AP clerk", tools: [...readOnlyTools, guardOpenAiAgentsPayTool(payInvoice, { guard })] });
+ * ```
+ *
+ * The payment is read from the tool's arguments: `{ account, amountUsd, invoiceReference }` unless
+ * you pass `toPayment`. If the tool needs a person's approval, the run stops for it before the
+ * guard is asked, so an approved payment can still be blocked.
+ */
+export function guardOpenAiAgentsPayTool(payTool, options) {
+    if (payTool?.type !== "function" || typeof payTool.invoke !== "function")
+        throw new BondedError("CONFIG", "guardOpenAiAgentsPayTool needs a function tool");
+    const invoke = payTool.invoke.bind(payTool);
+    const guarded = guardPayments((_args, runContext, input, details) => invoke(runContext, input, details), options);
+    return {
+        ...payTool,
+        invoke: (async (runContext, input, details) => {
+            let args;
+            try {
+                args = JSON.parse(input || "{}");
+            }
+            catch {
+                return "Error: the payment's arguments are not valid JSON; no payment was made";
+            }
+            // A custom toPayment reads fields: null or an array would throw before the guard answers.
+            if (!args || typeof args !== "object" || Array.isArray(args))
+                return "Error: the payment's arguments must be an object; no payment was made";
+            try {
+                return await guarded(args, runContext, input, details);
+            }
+            catch (error) {
+                if (isPaymentRefusal(error))
+                    return `Error: ${error.message}`;
+                throw error;
+            }
+        }),
+    };
+}
+//# sourceMappingURL=openai-agents.js.map

package/dist/payments.d.ts

@@ -0,0 +1,227 @@
+import { type BudgetTerms, type GateRule, type PaidPayment, type PayableInvoice, type PayableRefund, type PaymentAttempt, type PaymentLimits, type SignedGateReceipt, type VerifiedChange } from "@bondedhq/shared";
+import { type BudgetRequest, type PaymentBudget } from "./budget.js";
+import { BondedError, PaymentBlockedError, PaymentFrozenError, PaymentGateError } from "./errors.js";
+/** The off-chain payment mandate an agent's payments are checked against. */
+export interface PaymentMandate extends PaymentLimits {
+    /** Monitor lets a breaking payment through and reports it; Enforce blocks it. */
+    mode: "monitor" | "enforce";
+    /** After the first breach, refuse every payment until a person unfreezes the guard. */
+    freezeOnBreach: boolean;
+    /**
+     * False when your payments have no invoices: a payment needs a vendor on the list and to stay
+     * within the limits, and its reference is optional. Refunds still need an approved refund.
+     */
+    invoiceMatching?: boolean;
+    /** Payments allowed in any hour, with invoice matching off. No limit unless set. */
+    maxPaymentsPerHour?: number;
+}
+/** A supplier as your vendor master holds it. Its account is one the agent may pay. */
+export interface PaymentVendor {
+    id: string;
+    /** Bank account (an IBAN or account number). Compared without spaces, case-insensitively. */
+    account: string;
+    name?: string;
+}
+/** A list the guard reads on every check: fixed, or read from your own system each time. */
+export type PaymentSource<T> = readonly T[] | (() => readonly T[] | Promise<readonly T[]>);
+/** What the guard remembers between payments. Persist it to keep it across restarts. */
+export interface PaymentGuardState {
+    /** Payments made through the guard (and any made before it, if you restore them), oldest first. */
+    payments: PaidPayment[];
+    /** Frozen after a breach: every payment is refused until `unfreeze()`. */
+    frozen: boolean;
+    /**
+     * Bank changes made without a verified ticket (let through in Monitor mode). The vendor master
+     * may now show these accounts, but they never count as the vendor's: paying one is
+     * `unknown_payee`.
+     */
+    unverifiedChanges: VerifiedChange[];
+    /**
+     * Open budgets (`budget()`): their terms and what was counted against them. Each one's whole
+     * amount is in `payments` until it closes. Absent in state saved before budgets existed.
+     */
+    budgets?: LocalBudgetState[];
+    /** When budget payments were made in the last hour (Unix milliseconds), for the hourly limit. */
+    budgetSpends?: number[];
+}
+/** An open local budget, as the guard's state keeps it. */
+export interface LocalBudgetState {
+    id: string;
+    terms: BudgetTerms;
+    spentMicros: number;
+    payments: number;
+}
+/** One payment (or bank change) that broke the mandate, as the guard reports it. */
+export interface PaymentBreach {
+    kind: "invoice" | "refund" | "vendor_change" | "budget";
+    /** Every rule broken, most serious first. */
+    rules: GateRule[];
+    /** Each rule in plain words (`GATE_RULE_WORDS`), in the same order. */
+    reasons: string[];
+    /** Enforce mode stopped it: the pay function was not called. */
+    blocked: boolean;
+    account: string;
+    /** The invoice or refund reference; empty for a bank change or a budget. */
+    reference: string;
+    /** The vendor whose verified account this is (or, for a bank change, the vendor changed). */
+    vendorId: string | null;
+    amountUsd: number;
+    /** If it went out: paid to an account outside the vendor master, gone for good. */
+    lossUsd: number;
+    /** If it went out: paid to a known payee beyond what it was owed, claimable back. */
+    overpaidUsd: number;
+    /** UTC day it counts against, YYYY-MM-DD. */
+    day: string;
+    /** From the hosted gate (`PaymentGate`): the decision's id in its log. */
+    decisionId?: string;
+    /** From the hosted gate: Bonded's signed receipt for the decision. */
+    receipt?: SignedGateReceipt;
+}
+/** The rule verdict for a payment, without making it. */
+export interface PaymentVerdict {
+    /** Every rule the payment breaks, most serious first. Empty when it is allowed. */
+    rules: GateRule[];
+    reasons: string[];
+    amountUsd: number;
+    reference: string;
+    vendorId: string | null;
+    lossUsd: number;
+    overpaidUsd: number;
+    /** The guard is frozen: the payment would be refused whatever the rules say. */
+    frozen: boolean;
+}
+export interface PaymentGuardOptions {
+    mandate: PaymentMandate;
+    /** The vendor master: each vendor's account on file. */
+    vendors: PaymentSource<PaymentVendor>;
+    /** Invoices the business approved for payment. */
+    invoices?: PaymentSource<PayableInvoice>;
+    /** Customer refunds finance approved. */
+    refunds?: PaymentSource<PayableRefund>;
+    /**
+     * Bank changes finance verified out of band (a call to the number on file). A ticket's account
+     * is a known payee for its vendor, and the only way a vendor's account may change.
+     */
+    changes?: PaymentSource<VerifiedChange>;
+    /** State to start from, as `onStateChange` last saved it (or `state()` returned). */
+    state?: PaymentGuardState;
+    /** Called with the new state after every change, inside the guard's lock. Save it here. */
+    onStateChange?: (state: PaymentGuardState) => void | Promise<void>;
+    /**
+     * Called with every breach before the guard acts on it: blocked in Enforce mode, let through
+     * in Monitor mode. If it throws, the payment is not made.
+     */
+    onBreach?: (breach: PaymentBreach) => void | Promise<void>;
+    now?: () => Date;
+}
+/**
+ * The payment mandate, checked inside your own process: the same rules (`@bondedhq/shared`'s
+ * payment mandate) the Arena rates agents against, with no network and no model. You give it the
+ * mandate and your vendor master, approved invoices and refunds, and verified bank changes; it
+ * keeps the payments made and the frozen flag, and hands them to `onStateChange` to persist.
+ *
+ * Wrap your pay function with `guardPayments` (or a framework helper) so every payment is checked
+ * first. In Enforce mode a payment that breaks a rule throws `PaymentBlockedError` and your pay
+ * function is never called; in Monitor mode it goes through and `onBreach` reports it. A frozen
+ * guard refuses everything (`PaymentFrozenError`).
+ *
+ * It is a local check: the agent's code can still call the pay function without it, and it makes
+ * no receipts. Payments are checked and made one at a time, so two at once can't both pass the
+ * duplicate or daily checks.
+ */
+export declare class PaymentGuard {
+    #private;
+    readonly mandate: Readonly<PaymentMandate>;
+    constructor(options: PaymentGuardOptions);
+    get frozen(): boolean;
+    /** A copy of what the guard remembers, to persist or inspect. */
+    state(): PaymentGuardState;
+    /** Lets payments through again after a freeze. For a person who reviewed the breach. */
+    unfreeze(): Promise<void>;
+    /** The rule verdict for a payment, without making or recording it. */
+    check(attempt: PaymentAttempt, kind?: "invoice" | "refund"): Promise<PaymentVerdict>;
+    /**
+     * Checks a payment, then calls `pay` if the mandate allows it (or Monitor mode lets it through)
+     * and records it once `pay` returns. Throws `PaymentBlockedError` (Enforce), `PaymentFrozenError`
+     * or `BondedError` `INVALID_PAYMENT` without calling `pay`. A `pay` that throws records nothing.
+     */
+    pay<R>(attempt: PaymentAttempt, pay: () => R | Promise<R>, kind?: "invoice" | "refund"): Promise<R>;
+    /**
+     * Checks a vendor bank change, then calls `update` if a verified ticket covers that vendor and
+     * account (or Monitor mode lets it through). An unverified change breaks
+     * `unverified_vendor_change`; let through in Monitor mode, its account still never counts as
+     * the vendor's.
+     */
+    changeVendorAccount<R>(request: {
+        vendorId: string;
+        account: string;
+    }, update: () => R | Promise<R>): Promise<R>;
+    /**
+     * Opens a budget: one check for many small payments to one payee (see `PaymentBudget`). Needs
+     * `invoiceMatching: false`. The payee must be a vendor's account (`unknown_payee`), the whole
+     * budget must fit in what's left of the day's limit (`over_daily_cap`), and with
+     * `maxPaymentsPerHour` there must be room for a payment (`over_hourly_limit`); the budget then
+     * covers what's left of the hour. Enforce mode throws `PaymentBlockedError`; Monitor mode opens it
+     * and reports the breach. The whole budget counts toward the day until `close()`, when what was
+     * spent (rounded up to the cent) counts instead. A budget past its end is closed the next time
+     * one is opened.
+     */
+    budget(request: BudgetRequest): Promise<PaymentBudget>;
+}
+/** A payment guard: see `PaymentGuard`. */
+export declare function paymentGuard(options: PaymentGuardOptions): PaymentGuard;
+export interface GuardPaymentsOptions<I> {
+    /**
+     * A `PaymentGuard`, or the hosted `PaymentGate`. Share one between your invoice and refund
+     * functions, so limits and freezes are shared.
+     */
+    guard: Pick<PaymentGuard, "pay">;
+    /** `invoice` (the default) pays approved invoices; `refund` pays approved customer refunds. */
+    kind?: "invoice" | "refund";
+    /**
+     * Reads the payment from your function's first argument. Default: `{ account, amountUsd,
+     * invoiceReference }` (or `reference`), the Arena's `pay_invoice` and `issue_refund` arguments.
+     */
+    toPayment?: (input: I) => PaymentAttempt;
+}
+/**
+ * Wraps your own pay function so every call is checked against the payment mandate first. The
+ * wrapped function takes the same arguments and returns what yours returns. In Enforce mode a
+ * payment that breaks a rule throws `PaymentBlockedError` and your function is not called; in
+ * Monitor mode it is called and the guard's `onBreach` reports the breach. A frozen guard throws
+ * `PaymentFrozenError`.
+ *
+ * ```ts
+ * const guard = paymentGuard({ mandate, vendors, invoices, onBreach: alert });
+ * const pay = guardPayments(bank.pay, { guard });
+ * await pay({ account: "DE89 3704 0044 0532 0130 00", amountUsd: 1840.5, invoiceReference: "ACM-2291" });
+ * ```
+ *
+ * A local check: it makes no receipts, and code that calls your function directly skips it.
+ */
+export declare function guardPayments<I, Rest extends unknown[], R>(pay: (input: I, ...rest: Rest) => R | Promise<R>, options: GuardPaymentsOptions<I>): (input: I, ...rest: Rest) => Promise<R>;
+export interface GuardVendorChangesOptions<I> {
+    /** A `PaymentGuard`, or the hosted `PaymentGate`. */
+    guard: Pick<PaymentGuard, "changeVendorAccount">;
+    /**
+     * Reads the change from your function's first argument. Default: `{ vendorId, account }`, and
+     * `ticket` when there is one (the hosted gate checks it).
+     */
+    toChange?: (input: I) => {
+        vendorId: string;
+        account: string;
+        ticket?: string;
+    };
+}
+/**
+ * Wraps your own "change a vendor's bank account" function: a change no verified ticket covers
+ * breaks `unverified_vendor_change`. Enforce mode throws `PaymentBlockedError` without calling
+ * it; Monitor mode calls it, reports the breach, and never treats the new account as the vendor's.
+ */
+export declare function guardVendorChanges<I, Rest extends unknown[], R>(update: (input: I, ...rest: Rest) => R | Promise<R>, options: GuardVendorChangesOptions<I>): (input: I, ...rest: Rest) => Promise<R>;
+/**
+ * The payment guard or gate refused (blocked, frozen, arguments it can't check, or the gate gave no
+ * answer to act on): no money moved.
+ */
+export declare function isPaymentRefusal(error: unknown): error is PaymentBlockedError | PaymentFrozenError | PaymentGateError | BondedError;
+//# sourceMappingURL=payments.d.ts.map