agentfences 0.6.0 → 0.8.0

package/dist/core.js

@@ -1,93 +1,18 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import { randomUUID } from "node:crypto";
+/**
+ * init(), governed() and checkpoint(): starting and ending runs, checking every step against
+ * its limits (the server decides in cloud mode, the same rules apply here otherwise), and
+ * recording decisions and spans.
+ */
 import { FencesClient } from "./client.js";
 import * as control from "./control.js";
 import { AgentQuarantined, FencesStop } from "./errors.js";
 import * as events from "./events.js";
+import * as outbox from "./outbox.js";
+import * as precheck from "./precheck.js";
 import { costOf, setCustomPrices } from "./pricing.js";
-const SUMMARY = "I'll summarize what I found so far.";
-const WRAP_UP = "Stop your current task immediately and summarize what you have found or completed so far.";
-const money = (x) => `$${x.toFixed(4)}`;
-const count = (n) => n.toLocaleString("en-US");
-function breachResult(type, run) {
-    const spent = run.costUsd, limit = run.budgetUsd ?? 0;
-    const text = {
-        budget_exceeded: [`I've reached my budget limit (spent ${money(spent)} of ${money(limit)}). ${SUMMARY}`,
-            `You have reached your budget limit (${money(spent)} of ${money(limit)} spent). Stop your current task immediately ` +
-                "and provide a clear summary of what you have found or completed so far. Tell the user you stopped due to budget and what you accomplished."],
-        iteration_limit: [`I've reached my iteration limit (${run.iterations} steps). ${SUMMARY}`,
-            `You have reached your iteration limit (${run.iterations} steps). ${WRAP_UP} Tell the user you stopped due to the iteration limit.`],
-        time_limit: [`I've reached my time limit (${run.durationMs}ms). ${SUMMARY}`,
-            `You have reached your time limit. ${WRAP_UP} Tell the user you stopped due to the time limit.`],
-        token_limit: [`I've reached my token limit (${count(run.tokensUsed)} tokens). ${SUMMARY}`,
-            `You have reached your token limit (${count(run.tokensUsed)} tokens used). ${WRAP_UP} Tell the user you stopped due to the token limit.`],
-        stopped_by_user: [`I was stopped from the Fences dashboard. ${SUMMARY}`,
-            `A person stopped this run from the Fences dashboard. ${WRAP_UP} Tell the user you were stopped by an operator.`],
-        key_daily_budget: [`My daily spending cap has been reached. ${SUMMARY}`,
-            `Your daily spending cap, across all of your runs, has been reached. ${WRAP_UP} Tell the user you stopped because the daily cap was reached.`],
-        key_monthly_budget: [`My monthly spending cap has been reached. ${SUMMARY}`,
-            `Your monthly spending cap, across all of your runs, has been reached. ${WRAP_UP} Tell the user you stopped because the monthly cap was reached.`],
-        fences_unreachable: [`I can't reach Fences to confirm I'm within my limits, so I'm stopping to be safe. ${SUMMARY}`,
-            `Your governance service can't be reached and you are configured to stop when that happens. ${WRAP_UP}`],
-        paused: [`I was paused from the Fences dashboard and not resumed in time. ${SUMMARY}`,
-            `A person paused this run from the Fences dashboard and it was not resumed in time. Stop your current task and summarize ` +
-                "what you have found or completed so far. Tell the user the run was paused by an operator."],
-    };
-    const [message, systemPrompt] = text[type] ??
-        ["Governance limit reached.", "A governance limit has been reached. Summarize what you have done so far."];
-    return { ok: false, breached: true, breachType: type, message, systemPrompt, spentUsd: run.costUsd };
-}
-const okResult = (spentUsd = 0) => ({ ok: true, breached: false, breachType: null, message: "", systemPrompt: "", spentUsd });
-const DEFAULTS = { maxIterations: 100, maxDurationMs: 300_000, maxTokens: 0 };
-export const MAX_EVENTS_PER_RUN = 1000;
-export class Run {
-    agentName;
-    budgetUsd;
-    maxIterations;
-    maxDurationMs;
-    maxTokens;
-    context;
-    runId = randomUUID();
-    costUsd = 0;
-    iterations = 0;
-    tokensUsed = 0;
-    startedAt = Date.now();
-    decisions = [];
-    /** Tool and model calls as OpenTelemetry-shaped spans, newest 1,000 kept. */
-    events = [];
-    lastBreach = null;
-    exception;
-    warned = false;
-    /** Live control from the dashboard (see control.ts). */
-    control = control.newControl();
-    /** Held by guarded tools that are running. */
-    reservedUsd = 0;
-    /** "hold": wait at a limit for someone to raise it (see InitOptions.onBreach). */
-    onBreach = null;
-    abort = new AbortController();
-    /**
-     * Aborts when Fences halts the run after a stop it didn't reach a checkpoint for (see
-     * stopGraceS). Pass it to fetch and other cancellable work so a stuck run really stops:
-     *     await fetch(url, { signal: getActiveRun()?.signal });
-     */
-    get signal() { return this.abort.signal; }
-    /** @internal */
-    _abort(reason) { this.abort.abort(reason); }
-    constructor(agentName, budgetUsd, maxIterations, maxDurationMs, maxTokens, context) {
-        this.agentName = agentName;
-        this.budgetUsd = budgetUsd;
-        this.maxIterations = maxIterations;
-        this.maxDurationMs = maxDurationMs;
-        this.maxTokens = maxTokens;
-        this.context = context;
-    }
-    get durationMs() { return Date.now() - this.startedAt; }
-}
-const store = new AsyncLocalStorage();
-/** The run in progress in this async context, if any. */
-export function getActiveRun() {
-    return store.getStore() ?? null;
-}
+import { breachResult, okResult } from "./results.js";
+import { DEFAULTS, MAX_EVENTS_PER_RUN, Run, getActiveRun, store } from "./run.js";
+export { Run, getActiveRun } from "./run.js";
 let client = null;
 let localOnly = false;
 let failClosed = false;
@@ -130,11 +55,11 @@ function requireInit() {
         throw new Error("Call agentfences.init() before using Fences. For local usage: init({ localOnly: true })");
     }
 }
-function warnUnreachable(run, err) {
+function warnUnreachable(run, err, ending = false) {
     if (run.warned)
         return;
     run.warned = true;
-    console.warn(`agentfences: Fences backend unreachable for run ${run.runId} (${err}); enforcing limits locally`);
+    console.warn(`agentfences: Fences backend unreachable for run ${run.runId} (${err}); ${ending ? "ending the run" : "enforcing limits locally"}`);
 }
 // ── governed ──────────────────────────────────────────────────────────────────
 /**
@@ -186,7 +111,6 @@ function outcome(run, failed, error) {
     const e = run.exception;
     return ["error", e.message ? `${e.type}: ${e.message}` : e.type];
 }
-const LIMIT_KEYS = { budget_usd: "budgetUsd", max_iterations: "maxIterations", max_duration_ms: "maxDurationMs", max_tokens: "maxTokens" };
 async function startRun(agentName, limits) {
     const run = new Run(agentName, limits.budgetUsd ?? null, limits.maxIterations ?? DEFAULTS.maxIterations, limits.maxDurationMs ?? DEFAULTS.maxDurationMs, limits.maxTokens ?? DEFAULTS.maxTokens, events.currentContext());
     if (!client) {
@@ -206,11 +130,7 @@ async function startRun(agentName, limits) {
     if (resp.quarantined)
         throw new AgentQuarantined(agentName, resp.detail);
     // The server caps limits at the agent's ceilings: enforce the same numbers if it becomes unreachable later
-    for (const [wire, field] of Object.entries(LIMIT_KEYS)) {
-        const v = resp.limits?.[wire];
-        if (typeof v === "number" || (wire === "budget_usd" && v === null))
-            run[field] = v; // eslint-disable-line @typescript-eslint/no-explicit-any
-    }
+    control.adopt(run, resp.limits ?? {}, control.LIMITS, true);
     for (const n of resp.notices ?? []) {
         events.warnOnce(`${agentName}:${n.code}`, `${n.message ?? ""}${n.url ? ` ${n.url}` : ""}`);
     }
@@ -256,8 +176,10 @@ export async function checkpoint(response, extra = {}) {
         throw new TypeError("checkpoint() takes the model's response first; pass a cost as checkpoint(null, { costDeltaUsd })");
     }
     const [cost, tokens] = response === undefined || response === null ? [0, 0] : costOf(response);
-    const stepCost = cost + (extra.costDeltaUsd ?? 0), stepTokens = tokens + (extra.tokensUsed ?? 0);
-    run.costUsd += stepCost;
+    const stepCost = cost + checkAmount(extra.costDeltaUsd ?? 0, "costDeltaUsd");
+    const stepTokens = tokens + checkAmount(extra.tokensUsed ?? 0, "tokensUsed");
+    run.costUsd += stepCost; // the actual cost replaces the holds of model calls that finished
+    precheck.releaseFinished(run);
     run.tokensUsed += stepTokens;
     run.iterations += 1;
     const resp = client ? await client.checkpoint(run.runId, {
@@ -281,6 +203,14 @@ export async function checkpoint(response, extra = {}) {
     }
     return result;
 }
+/** @internal A cost or count must be a finite number, zero or more: a NaN or negative one would switch the budget off. */
+export function checkAmount(value, what) {
+    if (typeof value !== "number" || Number.isNaN(value))
+        throw new TypeError(`${what} must be a number, not ${String(value)}`);
+    if (value < 0 || value === Infinity)
+        throw new RangeError(`${what} must be zero or more and finite, not ${value}`);
+    return value;
+}
 /** @internal The breach the run is in by local rules, if any. */
 export function localBreach(run) {
     // Limits trip only once exceeded, same rule as the server; round away float drift (0.02*5 != 0.10)
@@ -297,10 +227,11 @@ export function localBreach(run) {
 function decide(run, resp) {
     if (!resp || resp.network_error) {
         if (resp) {
-            warnUnreachable(run, resp.network_error);
-            if (failClosed) {
+            const ending = failClosed || !!resp.auth_rejected; // a key revoked mid-run: the run can't go on unchecked
+            warnUnreachable(run, resp.network_error, ending);
+            if (ending) {
                 run.lastBreach = "fences_unreachable";
-                return breachResult(run.lastBreach, run);
+                return finalResult(run);
             }
         }
         run.lastBreach = localBreach(run);
@@ -308,13 +239,8 @@ function decide(run, resp) {
     else {
         control.apply(run, resp.commands);
         // The server is authoritative: adopt its totals and (on a breach) its current limits
-        run.costUsd = resp.spent_usd ?? run.costUsd;
-        run.iterations = resp.iterations ?? run.iterations;
-        run.tokensUsed = resp.tokens_used ?? run.tokensUsed;
-        for (const [wire, field] of Object.entries(LIMIT_KEYS)) {
-            if (wire in resp)
-                run[field] = resp[wire]; // eslint-disable-line @typescript-eslint/no-explicit-any
-        }
+        control.adopt(run, resp, control.TOTALS);
+        control.adopt(run, resp, control.LIMITS, true);
         // A fresh breach, or a 409 because the run is still fenced from an earlier one
         run.lastBreach = resp.ok ? null : (resp.breach ?? run.lastBreach ?? "limit_reached");
     }
@@ -330,47 +256,13 @@ function finalResult(run) {
     return run.lastBreach ? breachResult(run.lastBreach, run) : okResult(run.costUsd);
 }
 // ── Decision trail and spans ──────────────────────────────────────────────────
-const SPAN_BATCH = 50;
-const outbox = [];
-let draining = null;
-let spansSupported = true;
-function enqueue(item) {
-    outbox.push(item);
-    draining ??= drain().finally(() => { draining = null; });
-}
-/** Decisions and spans go to the server in the background, in order; consecutive spans of a run go together. */
-async function drain() {
-    while (outbox.length) {
-        const item = outbox.shift();
-        const c = client;
-        if (!c)
-            continue;
-        try {
-            if (item.kind === "decision") {
-                await c.logDecision(item.runId, item.body);
-                continue;
-            }
-            const batch = [item.span];
-            while (outbox[0]?.kind === "span" && outbox[0].runId === item.runId && batch.length < SPAN_BATCH) {
-                batch.push(outbox.shift().span);
-            }
-            if (spansSupported && (await c.logSpans(item.runId, batch)).unsupported) {
-                spansSupported = false;
-                console.warn("agentfences: this Fences server doesn't accept tool and model call spans yet; " +
-                    "they're kept on the run locally but not sent");
-            }
-        }
-        catch { /* never let delivery break the agent */ }
-    }
-}
 /**
  * Wait up to timeoutMs for queued decisions and spans to reach the server, and for onStop and
  * onQuarantine hooks to finish. Call before a serverless handler returns.
  */
 export async function flush(timeoutMs = 5000) {
     const deadline = Date.now() + timeoutMs;
-    if (draining)
-        await Promise.race([draining, new Promise((r) => setTimeout(r, timeoutMs).unref())]);
+    await outbox.wait(timeoutMs);
     await control.drain(Math.max(0, deadline - Date.now()));
 }
 /** Record the agent's reasoning at this step. Does nothing outside a governed run. */
@@ -383,7 +275,7 @@ export function logDecision(reasoning, action = null) {
         return;
     const sent = events.redact({ type: "decision", reasoning, action });
     if (sent && typeof sent.reasoning === "string" && sent.reasoning) {
-        enqueue({ kind: "decision", runId: run.runId,
+        outbox.enqueue({ kind: "decision", client, runId: run.runId,
             body: { iteration: run.iterations, reasoning: sent.reasoning, action: sent.action ?? null } });
     }
 }
@@ -412,11 +304,11 @@ export function recordSpan(name, elapsedMs, attributes, error) {
     run.events.push(span);
     if (run.events.length > MAX_EVENTS_PER_RUN)
         run.events.shift(); // a runaway agent can't eat memory
-    if (!client || !spansSupported)
+    if (!client || !outbox.spansSupported)
         return;
     const sent = events.redact({ type: "span", ...span });
     if (sent) {
         const { type: _, ...redacted } = sent; // the type key is for the redact hook only
-        enqueue({ kind: "span", runId: run.runId, span: redacted });
+        outbox.enqueue({ kind: "span", client, runId: run.runId, span: redacted });
     }
 }

package/dist/index.d.ts

@@ -4,9 +4,12 @@ export { context } from "./events.js";
 export type { RedactHook, Event } from "./events.js";
 export { tool } from "./tools.js";
 export type { GuardedToolOptions } from "./tools.js";
-export { requestApproval } from "./control.js";
-export type { Approval, ControlEvent, Hook } from "./control.js";
+export { requestApproval } from "./approvals.js";
+export type { Approval } from "./approvals.js";
+export type { ControlEvent, Hook } from "./control.js";
 export { priceOf } from "./pricing.js";
 export type { CustomPrice } from "./pricing.js";
 export { FencesError, FencesAuthError, AgentQuarantined, FencesStop, ToolBlocked } from "./errors.js";
 export { VERSION } from "./version.js";
+export * as mcp from "./mcp.js";
+export { instrument } from "./instrument.js";

package/dist/index.js

@@ -1,7 +1,9 @@
 export { init, governed, checkpoint, logDecision, flush, getActiveRun, Run } from "./core.js";
 export { context } from "./events.js";
 export { tool } from "./tools.js";
-export { requestApproval } from "./control.js";
+export { requestApproval } from "./approvals.js";
 export { priceOf } from "./pricing.js";
 export { FencesError, FencesAuthError, AgentQuarantined, FencesStop, ToolBlocked } from "./errors.js";
 export { VERSION } from "./version.js";
+export * as mcp from "./mcp.js";
+export { instrument } from "./instrument.js";

package/dist/instrument.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Patch the SDK behind this client so every model call inside a governed run is recorded and,
+ * with a budget, prechecked:
+ *
+ *     import OpenAI from "openai";
+ *     const openai = instrument(new OpenAI());
+ *
+ * Takes an OpenAI client (chat.completions and responses, including OpenAI-compatible clients)
+ * or an Anthropic one (messages). One call covers every client of that SDK; calling it again
+ * does nothing. Returns the client.
+ */
+export declare function instrument<C extends object>(client: C): C;

package/dist/instrument.js

@@ -0,0 +1,124 @@
+/**
+ * Record every OpenAI and Anthropic model call made inside a governed run, with no other code
+ * changes: model, tokens, cost, latency, and the error if it failed. Calls don't count as
+ * checkpoints and don't add to the run's spend (checkpoint(response) does), but in a run with a
+ * budget each one is prechecked: refused with FencesStop if its worst case doesn't fit.
+ */
+import * as precheck from "./precheck.js";
+import { getActiveRun, store } from "./run.js";
+import { recordLlmCall } from "./spans.js";
+const PATCHED = Symbol.for("agentfences.instrumented");
+/**
+ * Patch the SDK behind this client so every model call inside a governed run is recorded and,
+ * with a budget, prechecked:
+ *
+ *     import OpenAI from "openai";
+ *     const openai = instrument(new OpenAI());
+ *
+ * Takes an OpenAI client (chat.completions and responses, including OpenAI-compatible clients)
+ * or an Anthropic one (messages). One call covers every client of that SDK; calling it again
+ * does nothing. Returns the client.
+ */
+export function instrument(client) {
+    const c = client;
+    const provider = c.chat ? "openai" : "anthropic";
+    const resources = [c.chat?.completions, c.responses, c.messages].filter((r) => typeof r?.create === "function");
+    if (!resources.length)
+        throw new TypeError("instrument() takes an OpenAI or Anthropic client");
+    for (const r of resources) {
+        const proto = Object.getPrototypeOf(r);
+        if (typeof proto?.create === "function" && !proto.create[PATCHED])
+            proto.create = wrap(proto.create, provider);
+    }
+    return client;
+}
+function wrap(create, provider) {
+    const wrapped = function (...args) {
+        const run = getActiveRun();
+        if (!run)
+            return create.apply(this, args);
+        const body = (args[0] ?? {});
+        const prepared = precheck.prepare(body.model, body, body);
+        if (!prepared)
+            return send(this, create, args, provider, run, null);
+        let hold;
+        try {
+            hold = precheck.holdNow(prepared); // FencesStop if the call might not fit the budget
+        }
+        catch (e) {
+            return refused(e);
+        }
+        if (hold !== "wait")
+            return send(this, create, args, provider, run, hold);
+        // onBreach "hold": wait for a raised budget, then send. Boxed, so nothing awaits the SDK's promise before the caller does
+        return later(precheck.holdAsync(prepared).then((h) => ({ out: send(this, create, args, provider, run, h) })));
+    };
+    wrapped[PATCHED] = true;
+    return wrapped;
+}
+/** A call sent once a hold is released: awaitable, with the SDK promise's methods, each forwarded once it's sent. */
+function later(sent) {
+    const value = () => sent.then(({ out }) => out);
+    return {
+        then: (ok, ko) => value().then(ok, ko),
+        catch: (ko) => value().catch(ko),
+        finally: (fn) => value().finally(fn),
+        withResponse: () => sent.then(({ out }) => out.withResponse()),
+        asResponse: () => sent.then(({ out }) => out.asResponse()),
+    };
+}
+/** A refused call rejects like the SDK's own promise would, never throwing synchronously, and keeps its methods. */
+function refused(error) {
+    const p = Promise.reject(error);
+    p.withResponse = p.asResponse = () => p;
+    return p;
+}
+/**
+ * Make the call and return the SDK's own promise (an APIPromise, with .withResponse()) unchanged,
+ * except that awaiting it, or calling withResponse() or asResponse(), also records the call and
+ * settles its hold. Nothing reads the response before the caller does: after asResponse(), whose
+ * body the caller reads, the call is recorded without usage and its worst case stays held until
+ * the next checkpoint.
+ */
+function send(self, create, args, provider, run, hold) {
+    const body = (args[0] ?? {});
+    const started = performance.now();
+    let done = false;
+    const record = (response, error) => {
+        if (done)
+            return;
+        done = true;
+        store.run(run, () => {
+            if (hold)
+                precheck.finish(run, hold, response, error !== undefined);
+            recordLlmCall(provider, body.model, started, response, error, { stream: !!body.stream });
+        });
+    };
+    let out;
+    try {
+        out = create.apply(self, args);
+    }
+    catch (e) {
+        record(undefined, e);
+        throw e;
+    }
+    if (!out || typeof out.then !== "function") {
+        record(out);
+        return out;
+    }
+    const then = out.then.bind(out);
+    out.then = (ok, ko) => then((v) => { record(v); return ok ? ok(v) : v; }, (e) => { record(undefined, e); if (ko)
+        return ko(e); throw e; });
+    // APIPromise has its own catch and finally, which skip then: route them through the one above
+    out.catch = (ko) => Promise.prototype.catch.call(out, ko);
+    out.finally = (fn) => Promise.prototype.finally.call(out, fn);
+    if (typeof out.asResponse === "function") { // the caller reads the body: the call is recorded without usage
+        const asResponse = out.asResponse.bind(out);
+        out.asResponse = () => asResponse().then((r) => { record(); return r; }, (e) => { record(undefined, e); throw e; });
+    }
+    if (typeof out.withResponse === "function") {
+        const withResponse = out.withResponse.bind(out);
+        out.withResponse = () => withResponse().then((r) => { record(r?.data); return r; }, (e) => { record(undefined, e); throw e; });
+    }
+    return out;
+}

package/dist/mcp.d.ts

@@ -0,0 +1,40 @@
+type Args = Record<string, unknown>;
+interface CallToolClient {
+    callTool(params: {
+        name: string;
+        arguments?: Args;
+    }, ...rest: any[]): Promise<any>;
+}
+export interface WrapOptions {
+    /** Tool names to check with Fences before each call, or true for every tool. */
+    guard?: boolean | string[];
+    /** Per tool, what a call costs the run: a number or a function of its arguments. Such a tool is guarded. */
+    costUsd?: Record<string, number | ((args: Args) => number)>;
+    /** Tool names a person approves from the dashboard first. Such a tool is guarded. */
+    approve?: string[];
+}
+/** An MCP tool answered with isError: recorded as the call's error, the result still goes back. */
+export declare class MCPToolError extends Error {
+    readonly result: {
+        content?: {
+            text?: string;
+        }[];
+    };
+    constructor(result: {
+        content?: {
+            text?: string;
+        }[];
+    });
+}
+/**
+ * Record every tool call an MCP client makes, and guard the ones you name:
+ *
+ *     mcp.wrap(client, { guard: ["refund", "send_email"], costUsd: { refund: (a) => a.amount as number } });
+ *
+ * Patches client.callTool in place and returns the client. Each call inside a governed run
+ * becomes a tool span, with no tool() per tool. A result with isError counts as a failed call.
+ * Guarded tools go through the same check and settle as tool(fn, { guard: true }); a refused
+ * one throws ToolBlocked and never reaches the MCP server. Outside a governed run calls pass straight through.
+ */
+export declare function wrap<C extends CallToolClient>(client: C, options?: WrapOptions): C;
+export {};

package/dist/mcp.js

@@ -0,0 +1,46 @@
+import { getActiveRun } from "./run.js";
+import { argsSummary, callAsync } from "./tools.js";
+/** An MCP tool answered with isError: recorded as the call's error, the result still goes back. */
+export class MCPToolError extends Error {
+    result;
+    constructor(result) {
+        super((result.content ?? []).map((c) => c.text ?? "").join(" ").trim() || "isError");
+        this.result = result;
+        this.name = "MCPToolError";
+    }
+}
+/**
+ * Record every tool call an MCP client makes, and guard the ones you name:
+ *
+ *     mcp.wrap(client, { guard: ["refund", "send_email"], costUsd: { refund: (a) => a.amount as number } });
+ *
+ * Patches client.callTool in place and returns the client. Each call inside a governed run
+ * becomes a tool span, with no tool() per tool. A result with isError counts as a failed call.
+ * Guarded tools go through the same check and settle as tool(fn, { guard: true }); a refused
+ * one throws ToolBlocked and never reaches the MCP server. Outside a governed run calls pass straight through.
+ */
+export function wrap(client, options = {}) {
+    const original = client.callTool.bind(client), costs = options.costUsd ?? {}, approve = new Set(options.approve);
+    const named = new Set(Array.isArray(options.guard) ? options.guard : []);
+    client.callTool = async (params, ...rest) => {
+        const run = getActiveRun();
+        if (!run)
+            return original(params, ...rest);
+        const { name } = params, args = params.arguments ?? {}, c = Object.hasOwn(costs, name) ? costs[name] : undefined;
+        const guarded = options.guard === true || named.has(name) || c !== undefined || approve.has(name);
+        try {
+            return await callAsync(run, name, argsSummary([args]), guarded ? () => (typeof c === "function" ? c(args) : c) ?? 0 : null, approve.has(name), async () => {
+                const result = await original(params, ...rest);
+                if (result?.isError)
+                    throw new MCPToolError(result);
+                return result;
+            });
+        }
+        catch (e) {
+            if (e instanceof MCPToolError)
+                return e.result;
+            throw e;
+        }
+    };
+    return client;
+}

package/dist/outbox.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Decisions and spans go to the server in the background, in order, so logDecision() and
+ * recorded calls never wait on a network round trip. Consecutive spans of a run go together.
+ */
+import type { FencesClient } from "./client.js";
+import type { Span } from "./run.js";
+type Item = {
+    kind: "decision";
+    client: FencesClient;
+    runId: string;
+    body: Record<string, unknown>;
+} | {
+    kind: "span";
+    client: FencesClient;
+    runId: string;
+    span: Span;
+};
+/** Off once a server says it has no spans endpoint. */
+export declare let spansSupported: boolean;
+export declare function enqueue(item: Item): void;
+/** Wait up to timeoutMs for everything queued to be sent. */
+export declare function wait(timeoutMs: number): Promise<void>;
+export {};

package/dist/outbox.js

@@ -0,0 +1,35 @@
+const SPAN_BATCH = 50;
+const queue = [];
+let draining = null;
+/** Off once a server says it has no spans endpoint. */
+export let spansSupported = true;
+export function enqueue(item) {
+    queue.push(item);
+    draining ??= drain().finally(() => { draining = null; });
+}
+/** Wait up to timeoutMs for everything queued to be sent. */
+export async function wait(timeoutMs) {
+    if (draining)
+        await Promise.race([draining, new Promise((r) => setTimeout(r, timeoutMs).unref())]);
+}
+async function drain() {
+    while (queue.length) {
+        const item = queue.shift();
+        try {
+            if (item.kind === "decision") {
+                await item.client.logDecision(item.runId, item.body);
+                continue;
+            }
+            const batch = [item.span];
+            while (queue[0]?.kind === "span" && queue[0].runId === item.runId && batch.length < SPAN_BATCH) {
+                batch.push(queue.shift().span);
+            }
+            if (spansSupported && (await item.client.logSpans(item.runId, batch)).unsupported) {
+                spansSupported = false;
+                console.warn("agentfences: this Fences server doesn't accept tool and model call spans yet; " +
+                    "they're kept on the run locally but not sent");
+            }
+        }
+        catch { /* never let delivery break the agent */ }
+    }
+}

package/dist/precheck.d.ts

@@ -0,0 +1,33 @@
+import { type Hold, type Run } from "./run.js";
+type Params = Record<string, unknown>;
+/** The output-token cap a request sets, if any. */
+export declare function maxOut(params: Params): number | null;
+/**
+ * The most a call could cost: its input, estimated high from the request's size, at the dearest
+ * input rate, plus its output cap (or the model's) at the output rate. null for a model with no
+ * known price, which can't be prechecked.
+ */
+export declare function worstCaseUsd(model: unknown, request: unknown, outCap?: number | null, n?: number): number | null;
+export interface Prepared {
+    run: Run;
+    worst: number;
+    outCap: number | null;
+}
+/** The call to check, or null when there's nothing to check (no run, no budget, a model with no known price). */
+export declare function prepare(model: unknown, request: unknown, params?: Params): Prepared | null;
+/**
+ * Before a model call, without waiting: hold its worst case, or throw FencesStop if it doesn't fit.
+ * Returns "wait" when it doesn't fit but the run waits at a limit (onBreach "hold"): then use holdAsync.
+ */
+export declare function holdNow(p: Prepared): Hold | "wait";
+/** The same, waiting (onBreach "hold") for someone to raise the budget while the call doesn't fit. */
+export declare function holdAsync(p: Prepared): Promise<Hold>;
+/**
+ * After the call. A failed call isn't billed, so its hold is released now. Otherwise the hold
+ * shrinks to the response's actual cost (a stream without usage keeps its worst case), and the
+ * next checkpoint, which records that cost, releases it.
+ */
+export declare function finish(run: Run, h: Hold, response?: unknown, failed?: boolean): void;
+/** At a checkpoint, which records the actual cost: release the holds of calls that have finished. */
+export declare function releaseFinished(run: Run): void;
+export {};