agentfences 0.7.0 → 0.9.0

package/dist/core.d.ts

@@ -2,80 +2,11 @@ import { FencesClient } from "./client.js";
 import * as control from "./control.js";
 import * as events from "./events.js";
 import { type CustomPrice } from "./pricing.js";
-export interface CheckpointResult {
-    ok: boolean;
-    breached: boolean;
-    /** "budget_exceeded" | "iteration_limit" | "time_limit" | "token_limit" | "stopped_by_user" | ... (see PROTOCOL.md) */
-    breachType: string | null;
-    /** First-person text, ready to return to the user. */
-    message: string;
-    /** An instruction to give the model so it wraps up. */
-    systemPrompt: string;
-    /** The run's total spend so far. */
-    spentUsd: number;
-}
-/** Every limit is optional; see governed(). */
-export interface Limits {
-    /** Maximum spend for the run in USD. None anywhere: unlimited spend, with a warning. */
-    budgetUsd?: number | null;
-    /** Maximum checkpoints (steps). Default 100. */
-    maxIterations?: number | null;
-    /** Maximum wall-clock time in milliseconds. Default 300000 (5 minutes). */
-    maxDurationMs?: number | null;
-    /** Maximum tokens (input + output). 0 or unset: no limit. */
-    maxTokens?: number | null;
-}
-export declare const MAX_EVENTS_PER_RUN = 1000;
-export interface Span {
-    name: string;
-    start_ts: number;
-    end_ts: number;
-    status: "ok" | "error";
-    attributes: Record<string, unknown>;
-}
-export declare class Run {
-    readonly agentName: string;
-    budgetUsd: number | null;
-    maxIterations: number;
-    maxDurationMs: number;
-    maxTokens: number;
-    readonly context: Record<string, string>;
-    readonly runId: `${string}-${string}-${string}-${string}-${string}`;
-    costUsd: number;
-    iterations: number;
-    tokensUsed: number;
-    readonly startedAt: number;
-    readonly decisions: {
-        timestamp: number;
-        iteration: number;
-        reasoning: string;
-        action: string | null;
-    }[];
-    /** Tool and model calls as OpenTelemetry-shaped spans, newest 1,000 kept. */
-    readonly events: Span[];
-    lastBreach: string | null;
-    exception?: events.ExceptionInfo;
-    warned: boolean;
-    /** Live control from the dashboard (see control.ts). */
-    readonly control: control.Control;
-    /** Held by guarded tools that are running. */
-    reservedUsd: number;
-    /** "hold": wait at a limit for someone to raise it (see InitOptions.onBreach). */
-    onBreach: "hold" | null;
-    private readonly abort;
-    /**
-     * 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(): AbortSignal;
-    /** @internal */
-    _abort(reason: unknown): void;
-    constructor(agentName: string, budgetUsd: number | null, maxIterations: number, maxDurationMs: number, maxTokens: number, context: Record<string, string>);
-    get durationMs(): number;
-}
-/** The run in progress in this async context, if any. */
-export declare function getActiveRun(): Run | null;
+import { type ToolArguments } from "./spans.js";
+import { type CheckpointResult } from "./results.js";
+import { Run, type Limits } from "./run.js";
+export type { CheckpointResult } from "./results.js";
+export { Run, getActiveRun, type Limits, type Span } from "./run.js";
 export interface InitOptions {
     /** Your Fences API key (fc_...). Required unless localOnly. */
     apiKey?: string;
@@ -118,6 +49,12 @@ export interface InitOptions {
      * wait, and after pauseTimeoutS the breach is returned as usual. Cloud only; override per agent in governed().
      */
     onBreach?: "hold" | null;
+    /**
+     * What a recorded tool call carries of its arguments: "names" (the default: `query, limit`),
+     * "full" (the arguments as JSON, capped) or "none". A guarded tool's check and an approval request
+     * still send the values, which rules and approvers need; the redact hook can change or drop them.
+     */
+    toolArguments?: ToolArguments;
 }
 /** Call once at startup, before any governed function runs. */
 export declare function init(options?: InitOptions): void;
@@ -156,6 +93,8 @@ export interface Extra {
  * Never throws for a breach. Outside a governed run it does nothing.
  */
 export declare function checkpoint(response?: unknown, extra?: Extra): Promise<CheckpointResult>;
+/** @internal A cost or count must be a finite number, zero or more: a NaN or negative one would switch the budget off. */
+export declare function checkAmount(value: unknown, what: string): number;
 /** @internal The breach the run is in by local rules, if any. */
 export declare function localBreach(run: Run): string | null;
 /**

package/dist/core.js

@@ -1,93 +1,20 @@
-import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * 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 { randomUUID } from "node:crypto";
 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 { setToolArguments } from "./spans.js";
+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;
@@ -101,6 +28,7 @@ function checkOnBreach(value) {
 }
 /** Call once at startup, before any governed function runs. */
 export function init(options = {}) {
+    setToolArguments(options.toolArguments ?? "names");
     setCustomPrices(options.prices);
     events.configure(options.environment, options.release, options.redact);
     localOnly = !!options.localOnly;
@@ -130,11 +58,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 +114,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 +133,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,13 +179,15 @@ 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, {
-        cost_delta_usd: stepCost, tokens_used: stepTokens, iterations: run.iterations, duration_ms: run.durationMs
-    }) : null;
+    // A step_id per step: a retried checkpoint is counted once on servers that support it
+    const resp = client ? await client.checkpoint(run.runId, { cost_delta_usd: stepCost, tokens_used: stepTokens,
+        iterations: run.iterations, duration_ms: run.durationMs, step_id: randomUUID().replaceAll("-", "") }) : null;
     const result = decide(run, resp);
     // onBreach "hold": wait here for someone to raise the limit. Only a breach the server decided: an unreachable one can't be raised
     if (result.breachType && control.HOLDABLE.has(result.breachType) && control.holds(run) && resp && !resp.network_error) {
@@ -281,6 +206,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 +230,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 +242,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 +259,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 +278,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 +307,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,10 +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,8 +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.js

@@ -1,4 +1,4 @@
-import { getActiveRun } from "./core.js";
+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 {
@@ -29,12 +29,12 @@ export function wrap(client, options = {}) {
         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 ? () => Number((typeof c === "function" ? c(args) : c) ?? 0) : null, approve.has(name), async () => {
+            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;
-            });
+            }, Object.keys(args).join(", "));
         }
         catch (e) {
             if (e instanceof MCPToolError)

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 */ }
+    }
+}