agentfences 0.7.0 → 0.8.0

package/README.md

@@ -30,7 +30,7 @@ const research = governed(async (question: string) => {
 
 Pass the model's response to `checkpoint()` and Fences works out what the call cost from its model and token usage, including cache reads and writes. It understands results from the OpenAI and Anthropic SDKs, the Vercel AI SDK (`generateText`), Gemini and LangChain.js, or any object with the same usage fields. Prices come from a built-in table of about 290 models (the same one as the Python SDK).
 
-- Unknown model: its tokens are counted and Fences warns once. Add prices in USD per 1M tokens: `init({ localOnly: true, prices: { "my-finetune": { input: 2, output: 6 } } })`.
+- Unknown model: its tokens are counted and Fences warns once. Add prices in USD per 1M tokens: `init({ localOnly: true, prices: { "my-finetune": { input: 2, output: 6 } } })`. Both prices are required; an invalid one throws at `init()`.
 - Extra costs, or no response at all: `checkpoint(response, { costDeltaUsd: 0.01 })` or `checkpoint(null, { costDeltaUsd: 0.02, tokensUsed: 450 })`.
 
 ## Limits
@@ -57,7 +57,7 @@ await context({ user_id: "u_123", session_id: "s_9" }, () => research(question))
 init({ apiKey: process.env.FENCES_API_KEY, endpoint: "https://your-fences-host", environment: "prod", release: "v1.4.2" });
 ```
 
-The server is authoritative for limits and sees spend across processes. If it can't be reached, limits are enforced locally; pass `failClosed: true` to stop instead. A rejected key throws `FencesAuthError`; a quarantined agent throws `AgentQuarantined` before any of its code runs. In serverless handlers, `await flush()` before returning so queued decisions and spans are sent.
+The server is authoritative for limits and sees spend across processes. If it can't be reached, limits are enforced locally; pass `failClosed: true` to stop instead. A rejected key throws `FencesAuthError` when the run starts, and a key revoked during a run ends it at its next checkpoint (`fences_unreachable`); a quarantined agent throws `AgentQuarantined` before any of its code runs. A cost that isn't a finite number of zero or more throws instead of being counted. In serverless handlers, `await flush()` before returning so queued decisions and spans are sent.
 
 ## Live control (from 0.4.0)
 
@@ -117,6 +117,23 @@ mcp.wrap(client, { guard: ["send_email"], costUsd: { refund: (args) => args.amou
 
 `guard: true` guards every tool, and `approve: [...]` names tools a person approves first. A result with `isError` is recorded as a failed call and still comes back to the agent.
 
+## Model calls (from 0.8.0)
+
+`instrument(client)` records every OpenAI and Anthropic call made inside a governed run (model, tokens, cost, latency, errors) and checks it against the budget **before** it's sent:
+
+```ts
+import OpenAI from "openai";
+import { instrument } from "agentfences";
+
+const openai = instrument(new OpenAI());  // one call covers every client of that SDK
+```
+
+- If a call's worst case could take the run past its budget, it rejects with `FencesStop` (`budget_exceeded`) and never reaches the provider. The worst case is the request's input, estimated high, plus its output cap: `max_tokens` (or `max_completion_tokens`, `max_output_tokens`) if set, otherwise the model's whole output limit, so **set `max_tokens` on calls in runs with small budgets**.
+- Each call's worst case is held while it's in flight, so parallel calls can't overspend together. A failed call is released; a finished one is replaced by its actual cost, and the next `checkpoint()` releases it. With `onBreach: "hold"`, a call that doesn't fit waits for someone to raise the budget.
+- Calls are recorded, not counted as steps: keep calling `checkpoint(response)`, which adds the cost and checks the other limits.
+- The SDK's own promise comes back, with `.withResponse()` and `.asResponse()`. After `.asResponse()` the call is recorded without usage, and its worst case stays held until the next checkpoint.
+- OpenAI: `chat.completions.create` and `responses.create`, including OpenAI-compatible clients. Anthropic: `messages.create`. Streams are recorded when they start; pass the final usage to `checkpoint()`.
+
 ## Not yet in the TypeScript SDK
 
-The Python SDK also records OpenAI/Anthropic calls automatically (`instrument`) and integrates with LangGraph and the OpenAI Agents SDK. Those are also how it checks a model call against the budget **before** it's sent, so the TypeScript SDK doesn't do that yet: a model call is checked afterwards, by `checkpoint()`, and a run can go over its budget by one call. Everything here follows the same server protocol ([PROTOCOL.md](../PROTOCOL.md)).
+The Python SDK also integrates with LangGraph and the OpenAI Agents SDK. Model calls made without `instrument(client)` are checked afterwards, by `checkpoint()`, so a run can go over its budget by one such call. Everything here follows the same server protocol ([PROTOCOL.md](../PROTOCOL.md)).

package/dist/approvals.d.ts

@@ -0,0 +1,24 @@
+export interface Approval {
+    granted: boolean;
+    /** Who answered, as the dashboard reports it. */
+    by?: string | null;
+    /** Their note, or why no one could answer. */
+    note?: string | null;
+    /** The amount approved, if one was asked for. */
+    amountUsd?: number | null;
+    approvalId?: string | null;
+}
+/**
+ * Ask a person, through the Fences dashboard, to approve something, and wait for the answer:
+ *
+ *     const approval = await requestApproval("Refund $240 to order 1182?", { amountUsd: 240 });
+ *     if (!approval.granted) return `I didn't issue the refund: ${approval.note}`;
+ *
+ * If an amount is approved, the run's budget goes up by that much. Returns denied right away in
+ * local mode, outside a run, or when the server can't take requests, and denied after timeoutS
+ * (default 600) with no answer: it never hangs and never throws.
+ */
+export declare function requestApproval(reason: string, options?: {
+    amountUsd?: number;
+    timeoutS?: number;
+}): Promise<Approval>;

package/dist/approvals.js

@@ -0,0 +1,57 @@
+/** Approval requests: ask a person, through the Fences dashboard, and wait for the answer. */
+import { randomUUID } from "node:crypto";
+import * as control from "./control.js";
+import { recordSpan } from "./core.js";
+import { getActiveRun } from "./run.js";
+/**
+ * Ask a person, through the Fences dashboard, to approve something, and wait for the answer:
+ *
+ *     const approval = await requestApproval("Refund $240 to order 1182?", { amountUsd: 240 });
+ *     if (!approval.granted) return `I didn't issue the refund: ${approval.note}`;
+ *
+ * If an amount is approved, the run's budget goes up by that much. Returns denied right away in
+ * local mode, outside a run, or when the server can't take requests, and denied after timeoutS
+ * (default 600) with no answer: it never hangs and never throws.
+ */
+export async function requestApproval(reason, options = {}) {
+    const run = getActiveRun(), client = control._client();
+    const timeoutS = options.timeoutS ?? 600, amountUsd = options.amountUsd ?? null;
+    if (!run)
+        return { granted: false, note: "requestApproval() was called outside a governed run" };
+    if (!client)
+        return { granted: false, note: "Local mode: there is no one to approve this request" };
+    if (!control.supported.approvals)
+        return { granted: false, note: "This Fences server doesn't support approvals" };
+    const approvalId = randomUUID(), started = performance.now();
+    // timeout_s lets the server expire the request when we stop waiting
+    const resp = await client.requestApproval(run.runId, { approval_id: approvalId, reason, amount_usd: amountUsd, timeout_s: timeoutS });
+    if (resp.unsupported) {
+        control.unsupported("approvals", "approval requests", "they are denied");
+        return { granted: false, note: "This Fences server doesn't support approvals" };
+    }
+    if (resp.network_error)
+        return { granted: false, note: "Couldn't reach Fences to ask for approval" };
+    if (resp.ok === false)
+        return { granted: false, note: `Fences didn't accept the approval request (HTTP ${resp.status})` }; // no one will be asked
+    run.control.approvals.set(approvalId, null);
+    run.control.awaiting += 1;
+    control.schedule(0); // poll fast while someone decides
+    const deadline = Date.now() + timeoutS * 1000;
+    while (run.control.approvals.get(approvalId) === null && Date.now() < deadline) {
+        await new Promise((ok) => setTimeout(ok, 100));
+    }
+    run.control.awaiting -= 1;
+    const c = run.control.approvals.get(approvalId); // the dashboard's approval command, or null: no answer in time
+    run.control.approvals.delete(approvalId);
+    const answer = c
+        ? { granted: !!c.granted, by: c.by ?? null, note: c.note ?? null, amountUsd: c.amount_usd ?? null, approvalId }
+        : { granted: false, note: "No answer before the timeout", approvalId };
+    if (answer.granted && answer.amountUsd && run.budgetUsd !== null)
+        run.budgetUsd += answer.amountUsd; // an unlimited run stays unlimited
+    recordSpan("fences.approval", performance.now() - started, {
+        "fences.approval.id": approvalId, "fences.approval.reason": reason, "fences.approval.amount_usd": amountUsd,
+        "fences.approval.granted": answer.granted, "fences.approval.by": answer.by, "fences.approval.note": answer.note,
+        "fences.approval.granted_usd": answer.amountUsd,
+    });
+    return answer;
+}

package/dist/client.d.ts

@@ -15,8 +15,10 @@ export declare class FencesClient {
     guard(runId: string, body: Record<string, unknown>): Promise<Reply>;
     requestApproval(runId: string, body: Record<string, unknown>): Promise<Reply>;
     /**
-     * optional: an endpoint older servers may not have. A missing route returns
-     * { unsupported: true } and nothing throws, not even a rejected key.
+     * optional: an endpoint older servers may not have. A missing route returns { unsupported: true },
+     * and any other error { ok: false, status }.
+     * start: a rejected key throws FencesAuthError, before any agent code runs. Later in a run it
+     * returns { network_error, auth_rejected: true }: throwing there would replace the agent's own result or error.
      */
-    post(path: string, payload: unknown, optional?: boolean): Promise<Reply>;
+    post(path: string, payload: unknown, optional?: boolean, start?: boolean): Promise<Reply>;
 }

package/dist/client.js

@@ -1,4 +1,7 @@
-/** HTTP calls to a Fences server, as specified in PROTOCOL.md. Uses the fetch built into Node 18+. */
+/**
+ * HTTP calls to a Fences server, as specified in PROTOCOL.md, with the fetch built into Node 18+.
+ * Nothing throws except a rejected key at run start.
+ */
 import { FencesAuthError } from "./errors.js";
 import { VERSION } from "./version.js";
 export class FencesClient {
@@ -12,7 +15,7 @@ export class FencesClient {
         // The server uses the SDK version to warn about old SDKs and to skip commands they don't understand
         this.headers = { "Content-Type": "application/json", "X-API-Key": apiKey, "X-Fences-SDK": `js/${VERSION}` };
     }
-    startRun(body) { return this.post("/api/runs/start", body); }
+    startRun(body) { return this.post("/api/runs/start", body, false, true); }
     checkpoint(runId, body) { return this.post(`/api/runs/${runId}/checkpoint`, body); }
     logDecision(runId, body) { return this.post(`/api/runs/${runId}/decisions`, body); }
     endRun(runId, body) { return this.post(`/api/runs/${runId}/end`, body); }
@@ -25,10 +28,12 @@ export class FencesClient {
     guard(runId, body) { return this.post(`/api/runs/${runId}/guard`, body, true); }
     requestApproval(runId, body) { return this.post(`/api/runs/${runId}/approvals`, body, true); }
     /**
-     * optional: an endpoint older servers may not have. A missing route returns
-     * { unsupported: true } and nothing throws, not even a rejected key.
+     * optional: an endpoint older servers may not have. A missing route returns { unsupported: true },
+     * and any other error { ok: false, status }.
+     * start: a rejected key throws FencesAuthError, before any agent code runs. Later in a run it
+     * returns { network_error, auth_rejected: true }: throwing there would replace the agent's own result or error.
      */
-    async post(path, payload, optional = false) {
+    async post(path, payload, optional = false, start = false) {
         let resp;
         try {
             resp = await fetch(this.endpoint + path, {
@@ -42,8 +47,8 @@ export class FencesClient {
         let body = {}, isJson = false;
         try {
             const parsed = JSON.parse(text);
-            if (parsed && typeof parsed === "object")
-                [body, isJson] = [parsed, true];
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                [body, isJson] = [parsed, true]; // a list isn't a Fences reply
         }
         catch { /* not JSON: the status code still decides */ }
         const detail = typeof body.detail === "string" ? body.detail : "";
@@ -53,8 +58,11 @@ export class FencesClient {
             }
             return resp.ok ? body : { ok: false, status: resp.status };
         }
-        if (resp.status === 401 || resp.status === 403)
-            throw new FencesAuthError(`Fences API key rejected: ${text}`);
+        if (resp.status === 401 || resp.status === 403) {
+            if (start)
+                throw new FencesAuthError(`Fences API key rejected: ${detail || text.slice(0, 200)}`);
+            return { network_error: `API key rejected (HTTP ${resp.status})`, auth_rejected: true };
+        }
         if (resp.status === 423)
             return { ok: false, quarantined: true, detail }; // the agent is quarantined: the run must not start
         if (resp.status === 409)

package/dist/control.d.ts

@@ -1,15 +1,12 @@
+/**
+ * Live control from the Fences dashboard: a heartbeat that reports live runs and brings back
+ * commands (stop, pause, resume, quarantine, limits, approval answers) and acknowledges them,
+ * containment hooks, pausing at checkpoints, waiting at a limit, and cancelling a run stuck after
+ * a stop. Cloud mode only; a server without these endpoints gets one warning and runs carry
+ * on as before. Same behaviour as the Python SDK (PROTOCOL.md, "Live control").
+ */
 import type { FencesClient, Reply } from "./client.js";
-import type { Run } from "./core.js";
-export interface Approval {
-    granted: boolean;
-    /** Who answered, as the dashboard reports it. */
-    by?: string | null;
-    /** Their note, or why no one could answer. */
-    note?: string | null;
-    /** The amount approved, if one was asked for. */
-    amountUsd?: number | null;
-    approvalId?: string | null;
-}
+import type { Run } from "./run.js";
 /** What onStop and onQuarantine receive. */
 export interface ControlEvent {
     type: "stop" | "quarantine";
@@ -36,13 +33,15 @@ export interface Control {
     quarantined: boolean;
     /** While waiting at a limit: "breach" or "budget". */
     held: "breach" | "budget" | null;
-    /** approval id -> the answer, or null while waiting */
-    approvals: Map<string, Approval | null>;
+    /** approval id -> the dashboard's answer (an approval command), or null while waiting */
+    approvals: Map<string, Reply | null>;
     awaiting: number;
     /** command ids already acknowledged */
     acked: Set<string>;
 }
 export declare const newControl: () => Control;
+/** @internal */
+export declare const _client: () => FencesClient | null;
 export declare let pauseTimeoutMs: number;
 export declare const supported: {
     heartbeat: boolean;
@@ -60,6 +59,19 @@ export declare function configure(c: FencesClient | null, o: ControlOptions): vo
 export declare function register(run: Run): void;
 export declare function unregister(run: Run): void;
 export declare function unsupported(kind: keyof typeof supported, what: string, consequence: string): void;
+export declare const LIMITS: {
+    readonly budget_usd: "budgetUsd";
+    readonly max_iterations: "maxIterations";
+    readonly max_duration_ms: "maxDurationMs";
+    readonly max_tokens: "maxTokens";
+};
+export declare const TOTALS: {
+    readonly spent_usd: "costUsd";
+    readonly iterations: "iterations";
+    readonly tokens_used: "tokensUsed";
+};
+/** Set the run's fields from a server reply: numbers only, so a null or odd value can't break local enforcement. nullBudget: a null budget_usd means unlimited spend. */
+export declare function adopt(run: Run, reply: Reply, fields: Record<string, string>, nullBudget?: boolean): void;
 /** Apply the commands addressed to this run (from a heartbeat or a checkpoint reply), and acknowledge them. Each is safe to apply twice. */
 export declare function apply(run: Run, commands: Reply[] | undefined): void;
 /**
@@ -68,6 +80,8 @@ export declare function apply(run: Run, commands: Reply[] | undefined): void;
  * its containment, and says so.
  */
 export declare function drain(timeoutMs?: number): Promise<void>;
+/** @internal Send a heartbeat after delayMs (0: now), replacing the one scheduled. */
+export declare function schedule(delayMs: number): void;
 /** Breaches a person can lift by raising a limit, so onBreach "hold" waits at them. */
 export declare const HOLDABLE: Set<string>;
 export declare const BUDGET_BREACHES: Set<string>;
@@ -79,17 +93,3 @@ export declare function startHold(run: Run, kind: "breach" | "budget"): void;
 export declare function endHold(run: Run): "released" | "stopped" | "timeout";
 /** Hold the agent at its checkpoint while its run is paused, up to pauseTimeoutS. */
 export declare function waitIfPaused(run: Run): Promise<void>;
-/**
- * Ask a person, through the Fences dashboard, to approve something, and wait for the answer:
- *
- *     const approval = await requestApproval("Refund $240 to order 1182?", { amountUsd: 240 });
- *     if (!approval.granted) return `I didn't issue the refund: ${approval.note}`;
- *
- * If an amount is approved, the run's budget goes up by that much. Returns denied right away in
- * local mode, outside a run, or when the server can't take requests, and denied after timeoutS
- * (default 600) with no answer: it never hangs and never throws.
- */
-export declare function requestApproval(reason: string, options?: {
-    amountUsd?: number;
-    timeoutS?: number;
-}): Promise<Approval>;

package/dist/control.js

@@ -1,11 +1,3 @@
-/**
- * Live control from the Fences dashboard: a heartbeat that reports live runs and brings back
- * commands (stop, pause, resume, quarantine, limits, approval answers) and acknowledges them,
- * containment hooks, pausing at checkpoints, cancelling a run stuck after a stop, and approval
- * requests. Cloud mode only; a server without these endpoints gets one warning and runs carry
- * on as before. Same behaviour as the Python SDK (PROTOCOL.md, "Live control").
- */
-import { randomUUID } from "node:crypto";
 /** Heartbeat statuses whose acks go again with the next heartbeat: rate limited, or a server error. */
 const retryable = (status) => status === undefined || status === 429 || status >= 500;
 const FAST_MS = 2000; // heartbeat interval while a run is paused, waiting for an approval, or stopping
@@ -16,6 +8,8 @@ export const newControl = () => ({
 });
 const live = new Map(); // run id -> runs in progress
 let client = null;
+/** @internal */
+export const _client = () => client;
 let intervalMs = 15_000;
 export let pauseTimeoutMs = 3_600_000;
 let stopGraceMs = 30_000;
@@ -51,7 +45,17 @@ export function unsupported(kind, what, consequence) {
     console.warn(`agentfences: this Fences server doesn't support ${what} yet, so ${consequence}`);
 }
 // ── Commands ──────────────────────────────────────────────────────────────────
-const LIMITS = { budget_usd: "budgetUsd", max_iterations: "maxIterations", max_duration_ms: "maxDurationMs", max_tokens: "maxTokens" };
+export const LIMITS = { budget_usd: "budgetUsd", max_iterations: "maxIterations", max_duration_ms: "maxDurationMs", max_tokens: "maxTokens" };
+export const TOTALS = { spent_usd: "costUsd", iterations: "iterations", tokens_used: "tokensUsed" };
+/** Set the run's fields from a server reply: numbers only, so a null or odd value can't break local enforcement. nullBudget: a null budget_usd means unlimited spend. */
+export function adopt(run, reply, fields, nullBudget = false) {
+    for (const [wire, field] of Object.entries(fields)) {
+        const v = reply[wire];
+        if ((typeof v === "number" && !Number.isNaN(v)) || (nullBudget && wire === "budget_usd" && v === null)) {
+            run[field] = v; // eslint-disable-line @typescript-eslint/no-explicit-any
+        }
+    }
+}
 /** Apply the commands addressed to this run (from a heartbeat or a checkpoint reply), and acknowledge them. Each is safe to apply twice. */
 export function apply(run, commands) {
     // Limits first: a resume in the same reply may release a call held for budget, which re-checks against them at once
@@ -69,8 +73,10 @@ export function apply(run, commands) {
             ctl.paused = ctl.quarantined = false;
         }
         else if (c.type === "pause" || c.type === "quarantine") { // a quarantined agent's runs hold at their next checkpoint
-            ctl.paused = true;
-            schedule(0);
+            if (!ctl.paused) { // only a change wakes the heartbeat: a quarantine is re-sent on every reply while it lasts
+                ctl.paused = true;
+                schedule(0);
+            }
             if (c.type === "quarantine") {
                 ctl.quarantined = true; // guarded tools are blocked here too, even if the server can't be reached
                 hook("quarantine", run, c);
@@ -80,15 +86,11 @@ export function apply(run, commands) {
             ctl.paused = ctl.quarantined = false; // releasing a quarantine resumes its runs
         }
         else if (c.type === "limits") {
-            for (const [wire, field] of Object.entries(LIMITS)) {
-                if (c[wire] !== undefined && c[wire] !== null)
-                    run[field] = c[wire]; // eslint-disable-line @typescript-eslint/no-explicit-any
-            }
+            adopt(run, c, LIMITS);
         }
         else if (c.type === "approval") {
-            if (ctl.approvals.has(c.approval_id)) {
-                ctl.approvals.set(c.approval_id, { granted: !!c.granted, by: c.by ?? null, note: c.note ?? null, amountUsd: c.amount_usd ?? null });
-            }
+            if (ctl.approvals.has(c.approval_id))
+                ctl.approvals.set(c.approval_id, c); // approvals.ts turns it into the answer
         }
         else {
             continue; // unknown: ignored, and not acknowledged
@@ -174,7 +176,8 @@ if (typeof process?.on === "function") { // edge runtimes have no process events
 const unseenStop = (r) => r.control.stopped && !r.control.stopSeen && !r.control.cancelled && r.control.onCancel !== null;
 const busy = () => [...live.values()].some((r) => r.control.paused || r.control.awaiting > 0 || unseenStop(r));
 const nextDelay = () => (busy() ? Math.min(FAST_MS, intervalMs, stopGraceMs ?? FAST_MS) : intervalMs); // faster while busy, never slower
-function schedule(delayMs) {
+/** @internal Send a heartbeat after delayMs (0: now), replacing the one scheduled. */
+export function schedule(delayMs) {
     if (timer)
         clearTimeout(timer);
     timer = null;
@@ -266,53 +269,3 @@ export async function waitIfPaused(run) {
         await new Promise((ok) => setTimeout(ok, 200));
     }
 }
-// ── Approvals ─────────────────────────────────────────────────────────────────
-/**
- * Ask a person, through the Fences dashboard, to approve something, and wait for the answer:
- *
- *     const approval = await requestApproval("Refund $240 to order 1182?", { amountUsd: 240 });
- *     if (!approval.granted) return `I didn't issue the refund: ${approval.note}`;
- *
- * If an amount is approved, the run's budget goes up by that much. Returns denied right away in
- * local mode, outside a run, or when the server can't take requests, and denied after timeoutS
- * (default 600) with no answer: it never hangs and never throws.
- */
-export async function requestApproval(reason, options = {}) {
-    const { getActiveRun, recordSpan } = await import("./core.js");
-    const run = getActiveRun();
-    const timeoutS = options.timeoutS ?? 600, amountUsd = options.amountUsd ?? null;
-    if (!run)
-        return { granted: false, note: "requestApproval() was called outside a governed run" };
-    if (!client)
-        return { granted: false, note: "Local mode: there is no one to approve this request" };
-    if (!supported.approvals)
-        return { granted: false, note: "This Fences server doesn't support approvals" };
-    const approvalId = randomUUID(), started = performance.now();
-    // timeout_s lets the server expire the request when we stop waiting
-    const resp = await client.requestApproval(run.runId, { approval_id: approvalId, reason, amount_usd: amountUsd, timeout_s: timeoutS });
-    if (resp.unsupported) {
-        unsupported("approvals", "approval requests", "they are denied");
-        return { granted: false, note: "This Fences server doesn't support approvals" };
-    }
-    if (resp.network_error)
-        return { granted: false, note: "Couldn't reach Fences to ask for approval" };
-    run.control.approvals.set(approvalId, null);
-    run.control.awaiting += 1;
-    schedule(0); // poll fast while someone decides
-    const deadline = Date.now() + timeoutS * 1000;
-    while (run.control.approvals.get(approvalId) === null && Date.now() < deadline) {
-        await new Promise((ok) => setTimeout(ok, 100));
-    }
-    run.control.awaiting -= 1;
-    const answer = run.control.approvals.get(approvalId) ?? { granted: false, note: "No answer before the timeout" };
-    answer.approvalId = approvalId;
-    run.control.approvals.delete(approvalId);
-    if (answer.granted && answer.amountUsd && run.budgetUsd !== null)
-        run.budgetUsd += answer.amountUsd; // an unlimited run stays unlimited
-    recordSpan("fences.approval", performance.now() - started, {
-        "fences.approval.id": approvalId, "fences.approval.reason": reason, "fences.approval.amount_usd": amountUsd,
-        "fences.approval.granted": answer.granted, "fences.approval.by": answer.by, "fences.approval.note": answer.note,
-        "fences.approval.granted_usd": answer.amountUsd,
-    });
-    return answer;
-}

package/dist/core.d.ts

@@ -1,81 +1,16 @@
+/**
+ * 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 * 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 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;
@@ -156,6 +91,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;
 /**