agentfences 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# agentfences (TypeScript / JavaScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The TypeScript SDK for [Fences](https://github.com/bhaviksardar/fences), on-call for AI agents: limits your agents can't raise, cost tracking from real usage, a decision trail, and a stop button. Works offline too: local limits, no account. Node 18+, no dependencies.
+
+```bash
+npm install agentfences
+```
+
+## Quickstart (no account needed)
+
+```ts
+import { init, governed, checkpoint, logDecision } from "agentfences";
+
+init({ localOnly: true });
+
+const research = governed(async (question: string) => {
+  for (;;) {
+    logDecision("asking the model for the next step", "llm_call");
+    const response = await openai.chat.completions.create({ model: "gpt-4o", messages });
+    const result = await checkpoint(response);   // Fences reads the usage and prices the call
+    if (result.breached) return result.message;  // "I've reached my budget limit (spent $0.5100 of $0.5000)..."
+    // ...
+  }
+}, { budgetUsd: 0.5, maxIterations: 20 });
+```
+
+`checkpoint()` never throws for a breach: it returns a result with `ok`, `breached`, `breachType`, `message` (ready for the user), `systemPrompt` (to give the model so it wraps up) and `spentUsd`.
+
+## Cost tracking
+
+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 } } })`.
+- Extra costs, or no response at all: `checkpoint(response, { costDeltaUsd: 0.01 })` or `checkpoint(null, { costDeltaUsd: 0.02, tokensUsed: 450 })`.
+
+## Limits
+
+`budgetUsd`, `maxIterations` (default 100), `maxDurationMs` (default 5 minutes) and `maxTokens` (default none). All are optional. A limit trips once it's exceeded, not when reached. With no budget anywhere, the run's spend isn't capped and Fences warns once per agent. On Fences Cloud, limits left out come from the agent's page in the dashboard.
+
+## Tools, context, errors and redaction
+
+```ts
+import { tool, context } from "agentfences";
+
+const webSearch = tool(async ({ query }: { query: string }) => search(query));   // each call recorded as a span
+
+await context({ user_id: "u_123", session_id: "s_9" }, () => research(question));  // tags every run inside
+```
+
+- Tool and model calls are recorded as OpenTelemetry-shaped spans (`execute_tool webSearch`, `gen_ai.*` attributes), on `getActiveRun().events`.
+- When a governed run throws, Fences records the error's type, message and stack with the run; the error still reaches your code.
+- `init({ redact: (event) => ... })` sees everything before it leaves the process and can change or drop it.
+
+## Fences Cloud
+
+```ts
+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.
+
+## Not yet in the TypeScript SDK
+
+The Python SDK also has live control from the dashboard (pause, approvals), automatic recording of OpenAI/Anthropic calls (`instrument`), and LangGraph / OpenAI Agents integrations. They're next. Everything here follows the same server protocol ([PROTOCOL.md](../PROTOCOL.md)).

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+export type Reply = Record<string, any>;
+export declare class FencesClient {
+    readonly endpoint: string;
+    private readonly timeoutMs;
+    private readonly headers;
+    constructor(apiKey: string, endpoint: string, timeoutMs?: number);
+    startRun(body: Record<string, unknown>): Promise<Reply>;
+    checkpoint(runId: string, body: Record<string, unknown>): Promise<Reply>;
+    logDecision(runId: string, body: Record<string, unknown>): Promise<Reply>;
+    endRun(runId: string, body: Record<string, unknown>): Promise<Reply>;
+    logSpans(runId: string, spans: 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.
+     */
+    post(path: string, payload: unknown, optional?: boolean): Promise<Reply>;
+}

package/dist/client.js

@@ -0,0 +1,59 @@
+/** HTTP calls to a Fences server, as specified in PROTOCOL.md. Uses the fetch built into Node 18+. */
+import { FencesAuthError } from "./errors.js";
+import { VERSION } from "./version.js";
+export class FencesClient {
+    endpoint;
+    timeoutMs;
+    headers;
+    constructor(apiKey, endpoint, timeoutMs = 3000) {
+        this.endpoint = endpoint;
+        this.timeoutMs = timeoutMs;
+        this.endpoint = endpoint.replace(/\/+$/, "");
+        // 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); }
+    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); }
+    logSpans(runId, spans) { return this.post(`/api/runs/${runId}/spans`, { spans }, true); }
+    /**
+     * optional: an endpoint older servers may not have. A missing route returns
+     * { unsupported: true } and nothing throws, not even a rejected key.
+     */
+    async post(path, payload, optional = false) {
+        let resp;
+        try {
+            resp = await fetch(this.endpoint + path, {
+                method: "POST", headers: this.headers, body: JSON.stringify(payload), signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (e) {
+            return { network_error: String(e) };
+        }
+        const text = await resp.text().catch(() => "");
+        let body = {}, isJson = false;
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed === "object")
+                [body, isJson] = [parsed, true];
+        }
+        catch { /* not JSON: the status code still decides */ }
+        const detail = typeof body.detail === "string" ? body.detail : "";
+        if (optional) {
+            if ((resp.status === 404 || resp.status === 405) && (detail === "Not Found" || detail === "Method Not Allowed")) {
+                return { unsupported: true };
+            }
+            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 === 423)
+            return { ok: false, quarantined: true, detail }; // the agent is quarantined: the run must not start
+        if (resp.status === 409)
+            return { ok: false, conflict: detail }; // e.g. checkpoint on a run already fenced
+        if (!resp.ok || !isJson)
+            return { network_error: resp.ok ? "response was not JSON" : `HTTP ${resp.status}` };
+        return body;
+    }
+}

package/dist/core.d.ts

@@ -0,0 +1,123 @@
+import { FencesClient } from "./client.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;
+    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;
+export interface InitOptions {
+    /** Your Fences API key (fc_...). Required unless localOnly. */
+    apiKey?: string;
+    /** Your Fences server. Defaults to http://localhost:8000. */
+    endpoint?: string;
+    /** Enforce limits in-process only: no account, nothing leaves the process. */
+    localOnly?: boolean;
+    /** Treat an unreachable server as a breach (fences_unreachable) instead of enforcing locally. */
+    failClosed?: boolean;
+    /** Add or override model prices, USD per 1M tokens. */
+    prices?: Record<string, CustomPrice>;
+    /** Tag every run, e.g. "prod". */
+    environment?: string;
+    /** Tag every run, e.g. "v1.4.2". */
+    release?: string;
+    /** Sees every outgoing event and returns it (changed or not), or null to drop it. */
+    redact?: events.RedactHook;
+}
+/** Call once at startup, before any governed function runs. */
+export declare function init(options?: InitOptions): void;
+/** @internal For tests: point the SDK at a fake server client. */
+export declare function _setClient(c: FencesClient | null): void;
+/**
+ * Make each call of fn a governed run with these limits:
+ *
+ *     const research = governed(async (q: string) => { ... }, { budgetUsd: 0.5, maxIterations: 20 });
+ *
+ * Every limit is optional. On Fences Cloud, a limit left out comes from the agent's page in
+ * the dashboard. The run is named after the function (or `name`). checkpoint() never throws:
+ * a crossed limit comes back as a breached result, so the agent can wrap up gracefully.
+ */
+export declare function governed<A extends unknown[], R>(fn: (...args: A) => R | Promise<R>, options?: Limits & {
+    name?: string;
+}): (...args: A) => Promise<Awaited<R>>;
+export interface Extra {
+    /** Extra spend for this step in USD, e.g. a paid tool call. Without a response, the step's whole cost. */
+    costDeltaUsd?: number;
+    /** Extra tokens for this step. */
+    tokensUsed?: number;
+}
+/**
+ * Record one step, then check every limit. Pass the model's response and Fences works out
+ * the cost from its model and token usage:
+ *
+ *     const response = await openai.chat.completions.create({ ... });
+ *     const result = await checkpoint(response);
+ *     if (result.breached) return result.message;
+ *
+ * Without a response: checkpoint(null, { costDeltaUsd: 0.02, tokensUsed: 450 }).
+ * Never throws for a breach. Outside a governed run it does nothing.
+ */
+export declare function checkpoint(response?: unknown, extra?: Extra): Promise<CheckpointResult>;
+/** Wait up to timeoutMs for queued decisions and spans to reach the server. Call before a serverless handler returns. */
+export declare function flush(timeoutMs?: number): Promise<void>;
+/** Record the agent's reasoning at this step. Does nothing outside a governed run. */
+export declare function logDecision(reasoning: string, action?: string | null): void;
+/**
+ * Add a tool or model call to the active run as an OpenTelemetry-shaped span (GenAI
+ * semantic conventions): kept on the run, and sent through the redact hook in cloud mode.
+ */
+export declare function recordSpan(name: string, elapsedMs: number, attributes: Record<string, unknown>, error?: unknown): void;

package/dist/core.js

@@ -0,0 +1,342 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { FencesClient } from "./client.js";
+import { AgentQuarantined, FencesStop } from "./errors.js";
+import * as events from "./events.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;
+    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;
+}
+let client = null;
+let localOnly = false;
+let failClosed = false;
+/** Call once at startup, before any governed function runs. */
+export function init(options = {}) {
+    setCustomPrices(options.prices);
+    events.configure(options.environment, options.release, options.redact);
+    localOnly = !!options.localOnly;
+    failClosed = !!options.failClosed;
+    if (localOnly) {
+        client = null;
+        return;
+    }
+    if (!options.apiKey) {
+        throw new Error("apiKey is required unless localOnly is set. Use init({ localOnly: true }) for local usage.");
+    }
+    client = new FencesClient(options.apiKey, options.endpoint ?? "http://localhost:8000");
+}
+/** @internal For tests: point the SDK at a fake server client. */
+export function _setClient(c) { client = c; }
+function requireInit() {
+    if (!localOnly && !client) {
+        throw new Error("Call agentfences.init() before using Fences. For local usage: init({ localOnly: true })");
+    }
+}
+function warnUnreachable(run, err) {
+    if (run.warned)
+        return;
+    run.warned = true;
+    console.warn(`agentfences: Fences backend unreachable for run ${run.runId} (${err}); enforcing limits locally`);
+}
+// ── governed ──────────────────────────────────────────────────────────────────
+/**
+ * Make each call of fn a governed run with these limits:
+ *
+ *     const research = governed(async (q: string) => { ... }, { budgetUsd: 0.5, maxIterations: 20 });
+ *
+ * Every limit is optional. On Fences Cloud, a limit left out comes from the agent's page in
+ * the dashboard. The run is named after the function (or `name`). checkpoint() never throws:
+ * a crossed limit comes back as a breached result, so the agent can wrap up gracefully.
+ */
+export function governed(fn, options = {}) {
+    const name = options.name ?? (fn.name || "agent");
+    return async (...args) => {
+        requireInit();
+        const run = await startRun(name, options);
+        let error, failed = false;
+        try {
+            return await store.run(run, () => fn(...args));
+        }
+        catch (e) {
+            [error, failed] = [e, true];
+            throw e;
+        }
+        finally {
+            await endRun(run, ...outcome(run, failed, error));
+        }
+    };
+}
+function outcome(run, failed, error) {
+    if (!failed)
+        return [run.lastBreach ? "breached" : "success", null];
+    if (error instanceof FencesStop)
+        return ["breached", null]; // a framework integration halted the agent
+    run.exception = events.exceptionInfo(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) {
+        if (run.budgetUsd === null)
+            noBudget(agentName, "Set one with governed(fn, { budgetUsd: ... }).");
+        return run;
+    }
+    // The run must start even if redaction drops its context: limits depend on it
+    const sent = Object.keys(run.context).length
+        ? events.redact({ type: "run_start", agent_name: agentName, context: { ...run.context } }) : null;
+    // Limits left out in code go as null: the server fills them from the agent's dashboard settings
+    const body = { run_id: run.runId, agent_name: agentName, budget_usd: limits.budgetUsd ?? null,
+        max_iterations: limits.maxIterations ?? null, max_duration_ms: limits.maxDurationMs ?? null, max_tokens: limits.maxTokens ?? null };
+    if (sent?.context)
+        body.context = sent.context;
+    const resp = await client.startRun(body);
+    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
+    }
+    for (const n of resp.notices ?? []) {
+        events.warnOnce(`${agentName}:${n.code}`, `${n.message ?? ""}${n.url ? ` ${n.url}` : ""}`);
+    }
+    if (!("limits" in resp) && run.budgetUsd === null && !resp.network_error) {
+        noBudget(agentName, "Set one on its page in the Fences dashboard.");
+    }
+    if (resp.network_error)
+        warnUnreachable(run, resp.network_error);
+    return run;
+}
+function noBudget(agentName, how) {
+    events.warnOnce(`${agentName}:no_budget`, `${agentName} has no budget, so its spend isn't capped. ${how}`);
+}
+async function endRun(run, status, error) {
+    if (!client)
+        return;
+    // The run must end even if redaction drops its error details
+    const sent = error ? events.redact({ type: "run_end", status, error, exception: run.exception }) : null;
+    const body = { status, error: sent?.error ?? null };
+    if (sent?.exception)
+        body.exception = sent.exception;
+    await client.endRun(run.runId, body);
+}
+/**
+ * Record one step, then check every limit. Pass the model's response and Fences works out
+ * the cost from its model and token usage:
+ *
+ *     const response = await openai.chat.completions.create({ ... });
+ *     const result = await checkpoint(response);
+ *     if (result.breached) return result.message;
+ *
+ * Without a response: checkpoint(null, { costDeltaUsd: 0.02, tokensUsed: 450 }).
+ * Never throws for a breach. Outside a governed run it does nothing.
+ */
+export async function checkpoint(response, extra = {}) {
+    const run = getActiveRun();
+    if (!run)
+        return okResult();
+    if (typeof response === "number") {
+        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;
+    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;
+    return decide(run, resp);
+}
+function localBreach(run) {
+    // Limits trip only once exceeded, same rule as the server; round away float drift (0.02*5 != 0.10)
+    if (run.budgetUsd !== null && Math.round(run.costUsd * 1e9) / 1e9 > run.budgetUsd)
+        return "budget_exceeded";
+    if (run.iterations > run.maxIterations)
+        return "iteration_limit";
+    if (run.durationMs > run.maxDurationMs)
+        return "time_limit";
+    if (run.maxTokens > 0 && run.tokensUsed > run.maxTokens)
+        return "token_limit";
+    return null;
+}
+function decide(run, resp) {
+    if (!resp || resp.network_error) {
+        if (resp) {
+            warnUnreachable(run, resp.network_error);
+            if (failClosed) {
+                run.lastBreach = "fences_unreachable";
+                return breachResult(run.lastBreach, run);
+            }
+        }
+        run.lastBreach = localBreach(run);
+    }
+    else {
+        // 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
+        }
+        // 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");
+    }
+    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. Call before a serverless handler returns. */
+export async function flush(timeoutMs = 5000) {
+    if (!draining)
+        return;
+    await Promise.race([draining, new Promise((r) => setTimeout(r, timeoutMs).unref())]);
+}
+/** Record the agent's reasoning at this step. Does nothing outside a governed run. */
+export function logDecision(reasoning, action = null) {
+    const run = getActiveRun();
+    if (!run)
+        return;
+    run.decisions.push({ timestamp: Date.now() / 1000, iteration: run.iterations, reasoning, action });
+    if (!client)
+        return;
+    const sent = events.redact({ type: "decision", reasoning, action });
+    if (sent && typeof sent.reasoning === "string" && sent.reasoning) {
+        enqueue({ kind: "decision", runId: run.runId,
+            body: { iteration: run.iterations, reasoning: sent.reasoning, action: sent.action ?? null } });
+    }
+}
+/**
+ * Add a tool or model call to the active run as an OpenTelemetry-shaped span (GenAI
+ * semantic conventions): kept on the run, and sent through the redact hook in cloud mode.
+ */
+export function recordSpan(name, elapsedMs, attributes, error) {
+    const run = getActiveRun();
+    if (!run)
+        return;
+    const end = Date.now() / 1000;
+    const attrs = {};
+    for (const [k, v] of Object.entries(attributes))
+        if (v !== null && v !== undefined)
+            attrs[k] = v;
+    attrs["fences.iteration"] = run.iterations;
+    if (error !== undefined) {
+        attrs["error.type"] = events.errorType(error);
+        attrs["fences.error.message"] = events.errorText(error);
+        const status = error?.status; // the OpenAI and Anthropic JS SDKs put the HTTP status here
+        if (typeof status === "number")
+            attrs["http.response.status_code"] = status;
+    }
+    const span = { name, start_ts: end - elapsedMs / 1000, end_ts: end, status: error === undefined ? "ok" : "error", attributes: attrs };
+    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)
+        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 });
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+import type { CheckpointResult } from "./core.js";
+export declare class FencesError extends Error {
+    constructor(message: string);
+}
+/** The Fences server rejected the API key. Thrown so a bad key is noticed, not silently ignored. */
+export declare class FencesAuthError extends FencesError {
+}
+/** A governed function was called for an agent quarantined in the dashboard. No agent code ran. */
+export declare class AgentQuarantined extends FencesError {
+    readonly agentName: string;
+    constructor(agentName: string, detail?: string);
+}
+/**
+ * Thrown by framework integrations when a limit is crossed, because a framework callback
+ * can't hand a result back to the agent. Carries the same fields as a breached CheckpointResult.
+ */
+export declare class FencesStop extends FencesError {
+    readonly result: CheckpointResult;
+    readonly breachType: string | null;
+    readonly systemPrompt: string;
+    constructor(result: CheckpointResult);
+}

package/dist/errors.js

@@ -0,0 +1,33 @@
+export class FencesError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** The Fences server rejected the API key. Thrown so a bad key is noticed, not silently ignored. */
+export class FencesAuthError extends FencesError {
+}
+/** A governed function was called for an agent quarantined in the dashboard. No agent code ran. */
+export class AgentQuarantined extends FencesError {
+    agentName;
+    constructor(agentName, detail) {
+        super(`Agent '${agentName}' is quarantined in Fences, so this run was not started` +
+            (detail && detail !== "quarantined" ? `: ${detail}` : ""));
+        this.agentName = agentName;
+    }
+}
+/**
+ * Thrown by framework integrations when a limit is crossed, because a framework callback
+ * can't hand a result back to the agent. Carries the same fields as a breached CheckpointResult.
+ */
+export class FencesStop extends FencesError {
+    result;
+    breachType;
+    systemPrompt;
+    constructor(result) {
+        super(result.message);
+        this.result = result;
+        this.breachType = result.breachType;
+        this.systemPrompt = result.systemPrompt;
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,38 @@
+export declare const MAX_CONTEXT_KEYS = 32;
+export declare const MAX_CONTEXT_VALUE = 256;
+export declare const MAX_MESSAGE = 1000;
+export declare const MAX_FRAMES = 15;
+export type Event = {
+    type: string;
+    [key: string]: unknown;
+};
+export type RedactHook = (event: Event) => Event | null | undefined;
+/** Log a warning once per key per process. */
+export declare function warnOnce(key: string, message: string): void;
+export declare function configure(environment?: string, release?: string, redact?: RedactHook): void;
+/**
+ * Tag every run started inside fn, e.g. with the end user or session it serves:
+ *
+ *     await context({ user_id: "u_123", session_id: "s_9" }, () => supportAgent(question))
+ *
+ * Calls nest; inner values win. Values are stored as strings (up to 256 characters,
+ * 32 keys); null and undefined leave a key out.
+ */
+export declare function context<T>(values: Record<string, unknown>, fn: () => T): T;
+export declare function currentContext(): Record<string, string>;
+/** `Type: message`, or just the type when there's no message. */
+export declare function errorText(e: unknown): string;
+export declare function errorType(e: unknown): string;
+export interface ExceptionInfo {
+    type: string;
+    message: string;
+    stack: string[];
+}
+/** Type, message and the last frames of the stack (innermost last), for the run's error report. */
+export declare function exceptionInfo(e: unknown): ExceptionInfo;
+/**
+ * Pass an outgoing event through the user's redact hook. Returns the event to send, or
+ * null to drop it. If the hook throws or returns something else, the event is dropped:
+ * never send unredacted data, and never crash the agent.
+ */
+export declare function redact(event: Event): Event | null;

package/dist/events.js

@@ -0,0 +1,102 @@
+/**
+ * What a run carries besides numbers: its context (environment, release, user, session),
+ * the error that ended it, and the redact hook every outgoing event passes through.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+export const MAX_CONTEXT_KEYS = 32;
+export const MAX_CONTEXT_VALUE = 256;
+export const MAX_MESSAGE = 1000;
+export const MAX_FRAMES = 15;
+const processContext = {}; // environment / release, from init()
+const contextStore = new AsyncLocalStorage();
+let redactHook;
+let redactFailed = false;
+const warned = new Set();
+/** Log a warning once per key per process. */
+export function warnOnce(key, message) {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    console.warn(`agentfences: ${message}`);
+}
+export function configure(environment, release, redact) {
+    for (const k of Object.keys(processContext))
+        delete processContext[k];
+    if (environment)
+        processContext.environment = environment.slice(0, MAX_CONTEXT_VALUE);
+    if (release)
+        processContext.release = release.slice(0, MAX_CONTEXT_VALUE);
+    redactHook = redact;
+    redactFailed = false;
+}
+/**
+ * Tag every run started inside fn, e.g. with the end user or session it serves:
+ *
+ *     await context({ user_id: "u_123", session_id: "s_9" }, () => supportAgent(question))
+ *
+ * Calls nest; inner values win. Values are stored as strings (up to 256 characters,
+ * 32 keys); null and undefined leave a key out.
+ */
+export function context(values, fn) {
+    const merged = { ...(contextStore.getStore() ?? {}) };
+    for (const [k, v] of Object.entries(values)) {
+        if (v !== null && v !== undefined)
+            merged[k] = String(v).slice(0, MAX_CONTEXT_VALUE);
+    }
+    if (Object.keys(merged).length > MAX_CONTEXT_KEYS) {
+        throw new RangeError(`agentfences.context() takes at most ${MAX_CONTEXT_KEYS} keys`);
+    }
+    return contextStore.run(merged, fn);
+}
+export function currentContext() {
+    return { ...processContext, ...(contextStore.getStore() ?? {}) };
+}
+/** `Type: message`, or just the type when there's no message. */
+export function errorText(e) {
+    const type = errorType(e);
+    const message = e instanceof Error ? e.message : e === undefined ? "" : String(e);
+    return (message ? `${type}: ${message}` : type).slice(0, MAX_MESSAGE);
+}
+export function errorType(e) {
+    if (e instanceof Error)
+        return e.name && e.name !== "Error" ? e.name : e.constructor.name;
+    return typeof e;
+}
+/** Type, message and the last frames of the stack (innermost last), for the run's error report. */
+export function exceptionInfo(e) {
+    const frames = e instanceof Error && e.stack
+        ? e.stack.split("\n").slice(1).map((l) => l.trim()).filter((l) => l.startsWith("at ")).map((l) => {
+            const m = l.match(/^at (?:(.+?) \()?(.+?):(\d+):\d+\)?$/); // "at fn (file:line:col)" or "at file:line:col"
+            return m ? `${m[2]}:${m[3]} in ${m[1] ?? "<anonymous>"}` : l.slice(3);
+        })
+        : [];
+    return {
+        type: errorType(e),
+        message: (e instanceof Error ? e.message : String(e)).slice(0, MAX_MESSAGE),
+        stack: frames.reverse().slice(-MAX_FRAMES),
+    };
+}
+/**
+ * Pass an outgoing event through the user's redact hook. Returns the event to send, or
+ * null to drop it. If the hook throws or returns something else, the event is dropped:
+ * never send unredacted data, and never crash the agent.
+ */
+export function redact(event) {
+    if (!redactHook)
+        return event;
+    try {
+        const out = redactHook(structuredClone(event));
+        if (out === null || out === undefined)
+            return null;
+        if (typeof out !== "object" || Array.isArray(out))
+            throw new TypeError(`returned ${typeof out}, not an object or null`);
+        return out;
+    }
+    catch (e) {
+        if (!redactFailed) {
+            redactFailed = true;
+            console.warn(`agentfences: redact hook failed (${errorText(e)}); dropping events it fails on`);
+        }
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { init, governed, checkpoint, logDecision, flush, getActiveRun, Run } from "./core.js";
+export type { CheckpointResult, InitOptions, Limits, Extra, Span } from "./core.js";
+export { context } from "./events.js";
+export type { RedactHook, Event } from "./events.js";
+export { tool } from "./tools.js";
+export { priceOf } from "./pricing.js";
+export type { CustomPrice } from "./pricing.js";
+export { FencesError, FencesAuthError, AgentQuarantined, FencesStop } from "./errors.js";
+export { VERSION } from "./version.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { init, governed, checkpoint, logDecision, flush, getActiveRun, Run } from "./core.js";
+export { context } from "./events.js";
+export { tool } from "./tools.js";
+export { priceOf } from "./pricing.js";
+export { FencesError, FencesAuthError, AgentQuarantined, FencesStop } from "./errors.js";
+export { VERSION } from "./version.js";

package/dist/prices.generated.d.ts

@@ -0,0 +1,11 @@
+export declare const PRICES: Record<string, PriceEntry>;
+export interface Rates {
+    in: number;
+    out: number;
+    cache_read?: number;
+    cache_write?: number;
+}
+export interface PriceEntry extends Rates {
+    above?: number;
+    tier?: Rates;
+}

package/dist/prices.generated.js

@@ -0,0 +1,3 @@
+// Generated by scripts/prices.mjs from sdk/agentfences/prices.json. Do not edit.
+// LiteLLM model_prices_and_context_window.json, MIT License, Copyright (c) 2023 Berri AI, fetched 2026-10-09
+export const PRICES = { "chat-latest": { "in": 0.000005, "out": 0.00003, "cache_read": 5e-7 }, "claude-fable-5": { "in": 0.00001, "out": 0.00005, "cache_read": 0.000001, "cache_write": 0.0000125 }, "claude-fable-5-1": { "in": 0.00001, "out": 0.00005, "cache_read": 2.5e-7, "cache_write": 0.0000125 }, "claude-haiku-4-5": { "in": 0.000001, "out": 0.000005, "cache_read": 1e-7, "cache_write": 0.00000125 }, "claude-haiku-4-5-20251001": { "in": 0.000001, "out": 0.000005, "cache_read": 1e-7, "cache_write": 0.00000125 }, "claude-haiku-5-5": { "in": 1e-7, "out": 5e-7, "cache_read": 1e-8, "cache_write": 1.25e-7 }, "claude-mythos-5": { "in": 0.00001, "out": 0.00005, "cache_read": 0.000001, "cache_write": 0.0000125 }, "claude-mythos-5-1": { "in": 0.00001, "out": 0.00005, "cache_read": 2.5e-7, "cache_write": 0.0000125 }, "claude-mythos-preview": { "in": 0.00001, "out": 0.00005, "cache_read": 0.000001, "cache_write": 0.0000125 }, "claude-opus-4-5": { "in": 0.000005, "out": 0.000025, "cache_read": 5e-7, "cache_write": 0.00000625 }, "claude-opus-4-5-20251101": { "in": 0.000005, "out": 0.000025, "cache_read": 5e-7, "cache_write": 0.00000625 }, "claude-opus-4-6": { "in": 0.000005, "out": 0.000025, "cache_read": 5e-7, "cache_write": 0.00000625 }, "claude-opus-4-6-20260205": { "in": 0.000005, "out": 0.000025, "cache_read": 5e-7, "cache_write": 0.00000625 }, "claude-opus-4-7": { "in": 0.000005, "out": 0.000025, "cache_read": 5e-7, "cache_write": 0.00000625 }, "claude-opus-4-7-20260416": { "in": 0.000005, "out": 0.000025, "cache_read": 5e-7, "cache_write": 0.00000625 }, "claude-opus-4-8": { "in": 0.000005, "out": 0.000025, "cache_read": 5e-7, "cache_write": 0.00000625 }, "claude-opus-5": { "in": 0.000005, "out": 0.000025, "cache_read": 5e-7, "cache_write": 0.00000625 }, "claude-opus-5-5": { "in": 0.000004, "out": 0.00002, "cache_read": 2e-7, "cache_write": 0.000005 }, "claude-sonnet-4-5": { "in": 0.000003, "out": 0.000015, "cache_read": 3e-7, "cache_write": 0.00000375 }, "claude-sonnet-4-5-20250929": { "in": 0.000003, "out": 0.000015, "cache_read": 3e-7, "cache_write": 0.00000375 }, "claude-sonnet-4-6": { "in": 0.000003, "out": 0.000015, "cache_read": 3e-7, "cache_write": 0.00000375 }, "claude-sonnet-5": { "in": 0.000002, "out": 0.00001, "cache_read": 2e-7, "cache_write": 0.0000025 }, "claude-sonnet-5-5": { "in": 0.000002, "out": 0.00001, "cache_read": 1e-7, "cache_write": 0.0000025 }, "codestral-2508": { "in": 3e-7, "out": 9e-7, "cache_read": 3e-8 }, "codestral-latest": { "in": 3e-7, "out": 9e-7, "cache_read": 3e-8 }, "codestral-mamba-latest": { "in": 2.5e-7, "out": 2.5e-7, "cache_read": 2.5e-8 }, "computer-use-preview": { "in": 0.000003, "out": 0.000012 }, "daybreak-blue-latest": { "in": 0.000004, "out": 0.00002, "cache_read": 4e-7, "cache_write": 0.000005, "above": 272000, "tier": { "in": 0.000008, "out": 0.00003, "cache_read": 8e-7, "cache_write": 0.00001 } }, "daybreak-red-latest": { "in": 0.0000125, "out": 0.000075, "cache_read": 0.00000125, "cache_write": 0.000015625, "above": 272000, "tier": { "in": 0.000025, "out": 0.0001125, "cache_read": 0.0000025, "cache_write": 0.00003125 } }, "deep-research-max-preview-04-2026": { "in": 0.000002, "out": 0.000012 }, "deep-research-preview-04-2026": { "in": 0.000002, "out": 0.000012 }, "deep-research-pro-preview-12-2025": { "in": 0.000002, "out": 0.000012 }, "deepseek-chat": { "in": 2.8e-7, "out": 4.2e-7, "cache_read": 2.8e-8 }, "deepseek-coder": { "in": 1.4e-7, "out": 2.8e-7, "cache_read": 1.4e-8 }, "deepseek-flash": { "in": 3e-7, "out": 0.0000012, "cache_read": 6e-9, "cache_write": 0 }, "deepseek-r1": { "in": 5.5e-7, "out": 0.00000219, "cache_read": 1.4e-7 }, "deepseek-reasoner": { "in": 2.8e-7, "out": 4.2e-7, "cache_read": 2.8e-8 }, "deepseek-v3": { "in": 2.7e-7, "out": 0.0000011, "cache_read": 7e-8, "cache_write": 0 }, "deepseek-v3.2": { "in": 2.8e-7, "out": 4e-7, "cache_read": 2.8e-8 }, "deepseek-v4-flash": { "in": 3e-7, "out": 0.0000012, "cache_read": 6e-9, "cache_write": 0 }, "deepseek-v4-flash-vision-exp": { "in": 3e-7, "out": 0.0000012, "cache_read": 6e-9, "cache_write": 0 }, "deepseek-v4-pro": { "in": 0.00000132, "out": 0.00000396, "cache_read": 4.4e-8, "cache_write": 0 }, "devstral-latest": { "in": 4e-7, "out": 0.000002, "cache_read": 4e-8 }, "devstral-medium-latest": { "in": 4e-7, "out": 0.000002, "cache_read": 4e-8 }, "devstral-small-latest": { "in": 1e-7, "out": 3e-7, "cache_read": 1e-8 }, "ft:gpt-3.5-turbo": { "in": 0.000003, "out": 0.000006 }, "ft:gpt-3.5-turbo-0125": { "in": 0.000003, "out": 0.000006 }, "ft:gpt-3.5-turbo-0613": { "in": 0.000003, "out": 0.000006 }, "ft:gpt-3.5-turbo-1106": { "in": 0.000003, "out": 0.000006 }, "ft:gpt-4-0613": { "in": 0.00003, "out": 0.00006 }, "ft:gpt-4.1-2025-04-14": { "in": 0.000003, "out": 0.000012, "cache_read": 7.5e-7 }, "ft:gpt-4.1-mini-2025-04-14": { "in": 8e-7, "out": 0.0000032, "cache_read": 2e-7 }, "ft:gpt-4.1-nano-2025-04-14": { "in": 2e-7, "out": 8e-7, "cache_read": 5e-8 }, "ft:gpt-4o-2024-08-06": { "in": 0.00000375, "out": 0.000015, "cache_read": 0.000001875 }, "ft:gpt-4o-2024-11-20": { "in": 0.00000375, "out": 0.000015, "cache_write": 0.000001875 }, "ft:gpt-4o-mini-2024-07-18": { "in": 3e-7, "out": 0.0000012, "cache_read": 1.5e-7 }, "ft:o4-mini-2025-04-16": { "in": 0.000004, "out": 0.000016, "cache_read": 0.000001 }, "gemini-2.5-computer-use-preview-10-2025": { "in": 0.00000125, "out": 0.00001, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000015 } }, "gemini-2.5-flash": { "in": 3e-7, "out": 0.0000025, "cache_read": 3e-8 }, "gemini-2.5-flash-lite": { "in": 1e-7, "out": 4e-7, "cache_read": 1e-8 }, "gemini-2.5-flash-lite-preview-09-2025": { "in": 1e-7, "out": 4e-7, "cache_read": 1e-8 }, "gemini-2.5-flash-preview-09-2025": { "in": 3e-7, "out": 0.0000025, "cache_read": 3e-8 }, "gemini-2.5-pro": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000015, "cache_read": 2.5e-7 } }, "gemini-2.5-pro-preview-tts": { "in": 0.000001, "out": 0.00002, "cache_read": 1.25e-7 }, "gemini-3-flash-preview": { "in": 5e-7, "out": 0.000003, "cache_read": 5e-8 }, "gemini-3.1-flash-lite": { "in": 2.5e-7, "out": 0.0000015, "cache_read": 2.5e-8 }, "gemini-3.1-flash-lite-preview": { "in": 2.5e-7, "out": 0.0000015, "cache_read": 2.5e-8 }, "gemini-3.1-pro-preview": { "in": 0.000002, "out": 0.000012, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.000004, "out": 0.000018, "cache_read": 4e-7 } }, "gemini-3.1-pro-preview-customtools": { "in": 0.000002, "out": 0.000012, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.000004, "out": 0.000018, "cache_read": 4e-7 } }, "gemini-3.5-flash": { "in": 0.0000015, "out": 0.000009, "cache_read": 1.5e-7 }, "gemini-3.5-flash-lite": { "in": 3e-7, "out": 0.0000025, "cache_read": 3e-8 }, "gemini-3.6-flash": { "in": 7.5e-7, "out": 0.00000375, "cache_read": 7.5e-8 }, "gemini-3.7-flash": { "in": 7.5e-7, "out": 0.00000375, "cache_read": 7.5e-8 }, "gemini-3.8-flash": { "in": 7.5e-7, "out": 0.00000375, "cache_read": 7.5e-8 }, "gemini-3.8-flash-cyber": { "in": 0.0000015, "out": 0.0000075, "cache_read": 1.5e-7 }, "gemini-exp-1114": { "in": 0, "out": 0 }, "gemini-exp-1206": { "in": 0, "out": 0 }, "gemini-flash-latest": { "in": 7.5e-7, "out": 0.00000375, "cache_read": 7.5e-8 }, "gemini-flash-lite-latest": { "in": 3e-7, "out": 0.0000025, "cache_read": 3e-8 }, "gemini-gemma-2-27b-it": { "in": 3.5e-7, "out": 0.00000105 }, "gemini-gemma-2-9b-it": { "in": 3.5e-7, "out": 0.00000105 }, "gemini-omni-1.1-flash": { "in": 0.0000015, "out": 0.000009 }, "gemini-omni-flash-preview": { "in": 0.0000015, "out": 0.000009 }, "gemini-pro-latest": { "in": 0.000002, "out": 0.000012, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.000004, "out": 0.000018, "cache_read": 4e-7 } }, "gemini-robotics-er-1.5-preview": { "in": 3e-7, "out": 0.0000025, "cache_read": 0 }, "gemini-robotics-er-2-preview": { "in": 0.000001, "out": 0.000005, "cache_read": 1e-7 }, "gemini-robotics-er-2-streaming-preview": { "in": 0.000001, "out": 0.000005 }, "gemma-3-27b-it": { "in": 0, "out": 0 }, "gemma-4-26b-a4b-it": { "in": 0, "out": 0 }, "gemma-4-31b-it": { "in": 0, "out": 0 }, "glm-5-2": { "in": 0.0000014, "out": 0.0000044, "cache_read": 1.4e-7 }, "gpt-3.5-turbo": { "in": 5e-7, "out": 0.0000015 }, "gpt-3.5-turbo-0125": { "in": 5e-7, "out": 0.0000015 }, "gpt-3.5-turbo-1106": { "in": 0.000001, "out": 0.000002 }, "gpt-3.5-turbo-16k": { "in": 0.000003, "out": 0.000004 }, "gpt-4": { "in": 0.00003, "out": 0.00006 }, "gpt-4-0613": { "in": 0.00003, "out": 0.00006 }, "gpt-4-1106-preview": { "in": 0.00001, "out": 0.00003 }, "gpt-4-turbo": { "in": 0.00001, "out": 0.00003 }, "gpt-4-turbo-2024-04-09": { "in": 0.00001, "out": 0.00003 }, "gpt-4.1": { "in": 0.000002, "out": 0.000008, "cache_read": 5e-7 }, "gpt-4.1-2025-04-14": { "in": 0.000002, "out": 0.000008, "cache_read": 5e-7 }, "gpt-4.1-mini": { "in": 4e-7, "out": 0.0000016, "cache_read": 1e-7 }, "gpt-4.1-mini-2025-04-14": { "in": 4e-7, "out": 0.0000016, "cache_read": 1e-7 }, "gpt-4.1-nano": { "in": 1e-7, "out": 4e-7, "cache_read": 2.5e-8 }, "gpt-4.1-nano-2025-04-14": { "in": 1e-7, "out": 4e-7, "cache_read": 2.5e-8 }, "gpt-4o": { "in": 0.0000025, "out": 0.00001, "cache_read": 0.00000125 }, "gpt-4o-2024-05-13": { "in": 0.000005, "out": 0.000015 }, "gpt-4o-2024-08-06": { "in": 0.0000025, "out": 0.00001, "cache_read": 0.00000125 }, "gpt-4o-2024-11-20": { "in": 0.0000025, "out": 0.00001, "cache_read": 0.00000125 }, "gpt-4o-audio-preview-2024-12-17": { "in": 0.0000025, "out": 0.00001 }, "gpt-4o-audio-preview-2025-06-03": { "in": 0.0000025, "out": 0.00001 }, "gpt-4o-mini": { "in": 1.5e-7, "out": 6e-7, "cache_read": 7.5e-8 }, "gpt-4o-mini-2024-07-18": { "in": 1.5e-7, "out": 6e-7, "cache_read": 7.5e-8 }, "gpt-4o-mini-audio-preview-2024-12-17": { "in": 1.5e-7, "out": 6e-7 }, "gpt-4o-mini-search-preview": { "in": 1.5e-7, "out": 6e-7, "cache_read": 7.5e-8 }, "gpt-4o-search-preview": { "in": 0.0000025, "out": 0.00001, "cache_read": 0.00000125 }, "gpt-5": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5-2025-08-07": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5-chat": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5-chat-latest": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5-codex": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5-mini": { "in": 2.5e-7, "out": 0.000002, "cache_read": 2.5e-8 }, "gpt-5-mini-2025-08-07": { "in": 2.5e-7, "out": 0.000002, "cache_read": 2.5e-8 }, "gpt-5-nano": { "in": 5e-8, "out": 4e-7, "cache_read": 5e-9 }, "gpt-5-nano-2025-08-07": { "in": 5e-8, "out": 4e-7, "cache_read": 5e-9 }, "gpt-5-pro": { "in": 0.000015, "out": 0.00012 }, "gpt-5-pro-2025-10-06": { "in": 0.000015, "out": 0.00012 }, "gpt-5-search-api": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5-search-api-2025-10-14": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5.1": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5.1-2025-11-13": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5.1-chat-latest": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5.1-codex": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5.1-codex-max": { "in": 0.00000125, "out": 0.00001, "cache_read": 1.25e-7 }, "gpt-5.1-codex-mini": { "in": 2.5e-7, "out": 0.000002, "cache_read": 2.5e-8 }, "gpt-5.2": { "in": 0.00000175, "out": 0.000014, "cache_read": 1.75e-7 }, "gpt-5.2-2025-12-11": { "in": 0.00000175, "out": 0.000014, "cache_read": 1.75e-7 }, "gpt-5.2-chat-latest": { "in": 0.00000175, "out": 0.000014, "cache_read": 1.75e-7 }, "gpt-5.2-codex": { "in": 0.00000175, "out": 0.000014, "cache_read": 1.75e-7 }, "gpt-5.2-pro": { "in": 0.000021, "out": 0.000168 }, "gpt-5.2-pro-2025-12-11": { "in": 0.000021, "out": 0.000168 }, "gpt-5.3-chat-latest": { "in": 0.00000175, "out": 0.000014, "cache_read": 1.75e-7 }, "gpt-5.3-codex": { "in": 0.00000175, "out": 0.000014, "cache_read": 1.75e-7 }, "gpt-5.4": { "in": 0.0000025, "out": 0.000015, "cache_read": 2.5e-7, "above": 272000, "tier": { "in": 0.000005, "out": 0.0000225, "cache_read": 5e-7 } }, "gpt-5.4-2026-03-05": { "in": 0.0000025, "out": 0.000015, "cache_read": 2.5e-7, "above": 272000, "tier": { "in": 0.000005, "out": 0.0000225, "cache_read": 5e-7 } }, "gpt-5.4-mini": { "in": 7.5e-7, "out": 0.0000045, "cache_read": 7.5e-8 }, "gpt-5.4-mini-2026-03-17": { "in": 7.5e-7, "out": 0.0000045, "cache_read": 7.5e-8 }, "gpt-5.4-nano": { "in": 2e-7, "out": 0.00000125, "cache_read": 2e-8 }, "gpt-5.4-nano-2026-03-17": { "in": 2e-7, "out": 0.00000125, "cache_read": 2e-8 }, "gpt-5.4-pro": { "in": 0.00003, "out": 0.00018, "above": 272000, "tier": { "in": 0.00006, "out": 0.00027 } }, "gpt-5.4-pro-2026-03-05": { "in": 0.00003, "out": 0.00018, "above": 272000, "tier": { "in": 0.00006, "out": 0.00027 } }, "gpt-5.5": { "in": 0.000005, "out": 0.00003, "cache_read": 5e-7, "above": 272000, "tier": { "in": 0.00001, "out": 0.000045, "cache_read": 0.000001 } }, "gpt-5.5-2026-04-23": { "in": 0.000005, "out": 0.00003, "cache_read": 5e-7, "above": 272000, "tier": { "in": 0.00001, "out": 0.000045, "cache_read": 0.000001 } }, "gpt-5.5-cyber": { "in": 0.0000125, "out": 0.000075, "cache_read": 0.00000125 }, "gpt-5.5-pro": { "in": 0.00003, "out": 0.00018, "above": 272000, "tier": { "in": 0.00006, "out": 0.00027 } }, "gpt-5.5-pro-2026-04-23": { "in": 0.00003, "out": 0.00018, "above": 272000, "tier": { "in": 0.00006, "out": 0.00027 } }, "gpt-5.6": { "in": 0.000004, "out": 0.00002, "cache_read": 4e-7, "cache_write": 0.000005, "above": 272000, "tier": { "in": 0.000008, "out": 0.00003, "cache_read": 8e-7, "cache_write": 0.00001 } }, "gpt-5.6-cyber": { "in": 0.0000125, "out": 0.000075, "cache_read": 0.00000125, "cache_write": 0.000015625, "above": 272000, "tier": { "in": 0.000025, "out": 0.0001125, "cache_read": 0.0000025, "cache_write": 0.00003125 } }, "gpt-5.6-luna": { "in": 2e-7, "out": 0.0000012, "cache_read": 2e-8, "cache_write": 2.5e-7, "above": 272000, "tier": { "in": 4e-7, "out": 0.0000018, "cache_read": 4e-8, "cache_write": 5e-7 } }, "gpt-5.6-sol": { "in": 0.000004, "out": 0.00002, "cache_read": 4e-7, "cache_write": 0.000005, "above": 272000, "tier": { "in": 0.000008, "out": 0.00003, "cache_read": 8e-7, "cache_write": 0.00001 } }, "gpt-5.6-terra": { "in": 0.000002, "out": 0.000012, "cache_read": 2e-7, "cache_write": 0.0000025, "above": 272000, "tier": { "in": 0.000004, "out": 0.000018, "cache_read": 4e-7, "cache_write": 0.000005 } }, "gpt-6-astra": { "in": 0.00001, "out": 0.00005, "cache_read": 0.000001, "cache_write": 0.0000125, "above": 272000, "tier": { "in": 0.00002, "out": 0.000075, "cache_read": 0.000002, "cache_write": 0.000025 } }, "gpt-6-luna": { "in": 1e-7, "out": 5e-7, "cache_read": 1e-8, "cache_write": 1.25e-7, "above": 272000, "tier": { "in": 2e-7, "out": 7.5e-7, "cache_read": 2e-8, "cache_write": 2.5e-7 } }, "gpt-6-sol": { "in": 0.000002, "out": 0.00001, "cache_read": 2e-7, "cache_write": 0.0000025, "above": 272000, "tier": { "in": 0.000004, "out": 0.000015, "cache_read": 4e-7, "cache_write": 0.000005 } }, "gpt-6.1-sol": { "in": 0.000002, "out": 0.00001, "cache_read": 1e-7, "cache_write": 0.0000025, "above": 272000, "tier": { "in": 0.000004, "out": 0.000015, "cache_read": 2e-7, "cache_write": 0.000005 } }, "gpt-audio": { "in": 0.0000025, "out": 0.00001 }, "gpt-audio-1.5": { "in": 0.0000025, "out": 0.00001 }, "gpt-audio-2025-08-28": { "in": 0.0000025, "out": 0.00001 }, "gpt-audio-mini": { "in": 6e-7, "out": 0.0000024 }, "gpt-audio-mini-2025-12-15": { "in": 6e-7, "out": 0.0000024 }, "gpt-daybreak-blue-latest": { "in": 0.000004, "out": 0.00002, "cache_read": 4e-7, "cache_write": 0.000005, "above": 272000, "tier": { "in": 0.000008, "out": 0.00003, "cache_read": 8e-7, "cache_write": 0.00001 } }, "gpt-daybreak-red-latest": { "in": 0.0000125, "out": 0.000075, "cache_read": 0.00000125, "cache_write": 0.000015625, "above": 272000, "tier": { "in": 0.000025, "out": 0.0001125, "cache_read": 0.0000025, "cache_write": 0.00003125 } }, "gpt-oss-120b": { "in": 1.5e-7, "out": 6e-7, "cache_read": 7.5e-8 }, "gpt-oss-20b": { "in": 7.5e-8, "out": 3e-7, "cache_read": 3.75e-8 }, "gpt-oss-safeguard-20b": { "in": 7.5e-8, "out": 3e-7, "cache_read": 3.7e-8 }, "gpt-rosalind-discovery": { "in": 0.000005, "out": 0.000025, "cache_read": 5e-7 }, "gpt-rosalind-research": { "in": 0.000005, "out": 0.000025, "cache_read": 5e-7 }, "grok-4.20": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-0309": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-0309-non-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-0309-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-beta": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-beta-0309": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-beta-0309-non-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-beta-0309-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-beta-latest": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-beta-latest-non-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-beta-latest-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-beta-non-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-beta-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-experimental-beta-0304": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-experimental-beta-0304-non-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-experimental-beta-0304-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-experimental-beta-latest": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-experimental-beta-non-reasoning-latest": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-experimental-beta-reasoning-latest": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-multi-agent": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-multi-agent-0309": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-multi-agent-beta-0309": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-multi-agent-beta-latest": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-multi-agent-experimental-beta-0304": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-multi-agent-experimental-beta-latest": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-multi-agent-latest": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-non-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-non-reasoning-gv2": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-non-reasoning-latest": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-reasoning": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-reasoning-gv2": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.20-reasoning-latest": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.3": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.3-latest": { "in": 0.00000125, "out": 0.0000025, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.0000025, "out": 0.000005, "cache_read": 4e-7 } }, "grok-4.5": { "in": 0.000002, "out": 0.000006, "cache_read": 3e-7, "above": 200000, "tier": { "in": 0.000004, "out": 0.000012, "cache_read": 6e-7 } }, "grok-4.5-latest": { "in": 0.000002, "out": 0.000006, "cache_read": 3e-7, "above": 200000, "tier": { "in": 0.000004, "out": 0.000012, "cache_read": 6e-7 } }, "grok-4.6": { "in": 0.000002, "out": 0.000006, "cache_read": 5e-7, "above": 200000, "tier": { "in": 0.000004, "out": 0.000012, "cache_read": 0.000001 } }, "grok-4.7": { "in": 0.000002, "out": 0.000006, "cache_read": 5e-7, "above": 200000, "tier": { "in": 0.000004, "out": 0.000012, "cache_read": 0.000001 } }, "grok-build-0.1": { "in": 0.000001, "out": 0.000002, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.000002, "out": 0.000004, "cache_read": 4e-7 } }, "grok-build-latest": { "in": 0.000002, "out": 0.000006, "cache_read": 3e-7, "above": 200000, "tier": { "in": 0.000004, "out": 0.000012, "cache_read": 6e-7 } }, "grok-code-fast": { "in": 0.000001, "out": 0.000002, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.000002, "out": 0.000004, "cache_read": 4e-7 } }, "grok-code-fast-1": { "in": 0.000001, "out": 0.000002, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.000002, "out": 0.000004, "cache_read": 4e-7 } }, "grok-code-fast-1-0825": { "in": 0.000001, "out": 0.000002, "cache_read": 2e-7, "above": 200000, "tier": { "in": 0.000002, "out": 0.000004, "cache_read": 4e-7 } }, "labs-leanstral-1-5": { "in": 0, "out": 0 }, "labs-leanstral-1-5-1": { "in": 0, "out": 0 }, "learnlm-1.5-pro-experimental": { "in": 0, "out": 0 }, "llama-guard-3-8b": { "in": 2e-7, "out": 2e-7 }, "llama-prompt-guard-2-22m": { "in": 3e-8, "out": 3e-8 }, "llama-prompt-guard-2-86m": { "in": 4e-8, "out": 4e-8 }, "lyria-3-clip-preview": { "in": 0, "out": 0 }, "lyria-3-pro-preview": { "in": 0, "out": 0 }, "lyria-3.5": { "in": 0, "out": 0 }, "lyria-3.5-clip-preview": { "in": 0, "out": 0 }, "lyria-3.5-pro-preview": { "in": 0, "out": 0 }, "lyria-realtime-exp": { "in": 0, "out": 0 }, "magistral-medium-latest": { "in": 0.0000015, "out": 0.0000075, "cache_read": 1.5e-7 }, "magistral-small-latest": { "in": 1.5e-7, "out": 6e-7, "cache_read": 1.5e-8 }, "ministral-14b-2512": { "in": 2e-7, "out": 2e-7, "cache_read": 2e-8 }, "ministral-14b-latest": { "in": 2e-7, "out": 2e-7, "cache_read": 2e-8 }, "ministral-3-14b-2512": { "in": 2e-7, "out": 2e-7, "cache_read": 2e-8 }, "ministral-3-3b-2512": { "in": 1e-7, "out": 1e-7, "cache_read": 1e-8 }, "ministral-3-8b-2512": { "in": 1.5e-7, "out": 1.5e-7, "cache_read": 1.5e-8 }, "ministral-3b-2512": { "in": 1e-7, "out": 1e-7, "cache_read": 1e-8 }, "ministral-3b-latest": { "in": 1e-7, "out": 1e-7, "cache_read": 1e-8 }, "ministral-8b-2512": { "in": 1.5e-7, "out": 1.5e-7, "cache_read": 1.5e-8 }, "ministral-8b-latest": { "in": 1.5e-7, "out": 1.5e-7, "cache_read": 1.5e-8 }, "mistral-code-agent-latest": { "in": 4e-7, "out": 0.000002, "cache_read": 4e-8 }, "mistral-code-fim-latest": { "in": 3e-7, "out": 9e-7, "cache_read": 3e-8 }, "mistral-code-latest": { "in": 3e-7, "out": 9e-7, "cache_read": 3e-8 }, "mistral-large-2512": { "in": 5e-7, "out": 0.0000015, "cache_read": 5e-8 }, "mistral-large-3": { "in": 5e-7, "out": 0.0000015, "cache_read": 5e-8 }, "mistral-large-4": { "in": 6.8e-7, "out": 0.00000209, "cache_read": 6.8e-8 }, "mistral-large-4-0": { "in": 6.8e-7, "out": 0.00000209, "cache_read": 6.8e-8 }, "mistral-large-latest": { "in": 5e-7, "out": 0.0000015, "cache_read": 5e-8 }, "mistral-medium": { "in": 0.0000015, "out": 0.0000075, "cache_read": 1.5e-7 }, "mistral-medium-2604": { "in": 0.0000015, "out": 0.0000075, "cache_read": 1.5e-7 }, "mistral-medium-3": { "in": 0.0000015, "out": 0.0000075, "cache_read": 1.5e-7 }, "mistral-medium-3-5": { "in": 0.0000015, "out": 0.0000075, "cache_read": 1.5e-7 }, "mistral-medium-3.5": { "in": 0.0000015, "out": 0.0000075, "cache_read": 1.5e-7 }, "mistral-medium-latest": { "in": 0.0000015, "out": 0.0000075, "cache_read": 1.5e-7 }, "mistral-small": { "in": 1e-7, "out": 3e-7, "cache_read": 1e-8 }, "mistral-small-2603": { "in": 1.5e-7, "out": 6e-7, "cache_read": 1.5e-8 }, "mistral-small-latest": { "in": 1.5e-7, "out": 6e-7, "cache_read": 1.5e-8 }, "mistral-tiny": { "in": 2.5e-7, "out": 2.5e-7, "cache_read": 2.5e-8 }, "mistral-vibe-cli-fast": { "in": 1.5e-7, "out": 6e-7, "cache_read": 1.5e-8 }, "mistral-vibe-cli-latest": { "in": 0.0000015, "out": 0.0000075, "cache_read": 1.5e-7 }, "mistral-vibe-cli-with-tools": { "in": 0.0000015, "out": 0.0000075, "cache_read": 1.5e-7 }, "o1": { "in": 0.000015, "out": 0.00006, "cache_read": 0.0000075 }, "o1-2024-12-17": { "in": 0.000015, "out": 0.00006, "cache_read": 0.0000075 }, "o1-pro": { "in": 0.00015, "out": 0.0006 }, "o1-pro-2025-03-19": { "in": 0.00015, "out": 0.0006 }, "o3": { "in": 0.000002, "out": 0.000008, "cache_read": 5e-7 }, "o3-2025-04-16": { "in": 0.000002, "out": 0.000008, "cache_read": 5e-7 }, "o3-deep-research": { "in": 0.00001, "out": 0.00004, "cache_read": 0.0000025 }, "o3-mini": { "in": 0.0000011, "out": 0.0000044, "cache_read": 5.5e-7 }, "o3-mini-2025-01-31": { "in": 0.0000011, "out": 0.0000044, "cache_read": 5.5e-7 }, "o3-pro": { "in": 0.00002, "out": 0.00008 }, "o3-pro-2025-06-10": { "in": 0.00002, "out": 0.00008 }, "o4-mini": { "in": 0.0000011, "out": 0.0000044, "cache_read": 2.75e-7 }, "o4-mini-2025-04-16": { "in": 0.0000011, "out": 0.0000044, "cache_read": 2.75e-7 }, "o4-mini-deep-research": { "in": 0.000002, "out": 0.000008, "cache_read": 5e-7 }, "open-mistral-nemo": { "in": 3e-7, "out": 3e-7, "cache_read": 3e-8 }, "pixtral-large-latest": { "in": 0.000002, "out": 0.000006, "cache_read": 2e-7 }, "qwen3.8-27b": { "in": 8e-7, "out": 0.000004 }, "voxtral-small-2507": { "in": 1e-7, "out": 4e-7, "cache_read": 1e-8 }, "voxtral-small-latest": { "in": 1e-7, "out": 4e-7, "cache_read": 1e-8 }, "zai-glm-5": { "in": 0.0000014, "out": 0.0000044, "cache_read": 1.4e-7 }, "zai-glm-5-2": { "in": 0.0000014, "out": 0.0000044, "cache_read": 1.4e-7 }, "zai-glm-5-3": { "in": 0.0000014, "out": 0.0000044, "cache_read": 1.4e-7 }, "zai-glm-latest": { "in": 0.0000014, "out": 0.0000044, "cache_read": 1.4e-7 } };

package/dist/pricing.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Turns a model response into [cost in USD, tokens]. Prices come from the same table as the
+ * Python SDK (sdk/agentfences/prices.json, a snapshot of LiteLLM's MIT-licensed price list).
+ */
+import { type PriceEntry } from "./prices.generated.js";
+/** Per-1M-token prices for models the table doesn't know, from init({ prices }). */
+export interface CustomPrice {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+export declare function setCustomPrices(prices?: Record<string, CustomPrice>): void;
+export declare function priceOf(model: string): PriceEntry | undefined;
+export interface Usage {
+    model: string;
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+    reportedCost: number | null;
+}
+/**
+ * Normalise usage from the common response shapes: OpenAI (Chat Completions, Responses),
+ * Anthropic, Gemini, the Vercel AI SDK and LangChain.js, or any object with the same fields.
+ * Returns null if the response carries no usage.
+ */
+export declare function readUsage(response: unknown): Usage | null;
+/** [cost in USD, tokens] for one model response. Warns once for a model it can't price. */
+export declare function costOf(response: unknown): [number, number];

package/dist/pricing.js

@@ -0,0 +1,103 @@
+/**
+ * Turns a model response into [cost in USD, tokens]. Prices come from the same table as the
+ * Python SDK (sdk/agentfences/prices.json, a snapshot of LiteLLM's MIT-licensed price list).
+ */
+import { PRICES } from "./prices.generated.js";
+import { warnOnce } from "./events.js";
+const custom = {};
+export function setCustomPrices(prices = {}) {
+    for (const k of Object.keys(custom))
+        delete custom[k];
+    for (const [model, p] of Object.entries(prices)) {
+        const e = { in: p.input / 1e6, out: p.output / 1e6 };
+        if (p.cacheRead !== undefined)
+            e.cache_read = p.cacheRead / 1e6;
+        if (p.cacheWrite !== undefined)
+            e.cache_write = p.cacheWrite / 1e6;
+        custom[model.toLowerCase()] = e;
+    }
+}
+export function priceOf(model) {
+    const name = model.toLowerCase().split("/").pop() ?? ""; // "models/gemini-2.5-pro", "openai/gpt-4o"
+    const undated = name.replace(/-(\d{4}-\d{2}-\d{2}|\d{8})$/, ""); // "claude-sonnet-4-5-20250929"
+    for (const candidate of [name, undated]) {
+        const hit = custom[candidate] ?? PRICES[candidate];
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+const num = (...values) => {
+    for (const v of values)
+        if (typeof v === "number" && Number.isFinite(v))
+            return v;
+    return 0;
+};
+/**
+ * Normalise usage from the common response shapes: OpenAI (Chat Completions, Responses),
+ * Anthropic, Gemini, the Vercel AI SDK and LangChain.js, or any object with the same fields.
+ * Returns null if the response carries no usage.
+ */
+export function readUsage(response) {
+    const r = response;
+    if (!r || typeof r !== "object")
+        return null;
+    const model = r.model ?? r.modelVersion ?? r.model_version ?? r.response?.modelId
+        ?? r.response_metadata?.model_name ?? r.response_metadata?.model ?? "";
+    const u = r.usage;
+    if (u && typeof u === "object") {
+        const reported = typeof u.cost === "number" ? u.cost : null; // gateways like OpenRouter report the billed cost
+        if (u.inputTokens !== undefined || u.outputTokens !== undefined) { // Vercel AI SDK: input includes cached
+            const read = num(u.cachedInputTokens, u.inputTokenDetails?.cacheReadTokens);
+            const write = num(r.providerMetadata?.anthropic?.cacheCreationInputTokens, u.inputTokenDetails?.cacheWriteTokens);
+            return { model, input: num(u.inputTokens) - read - write, cacheRead: read, cacheWrite: write,
+                output: num(u.outputTokens), reportedCost: reported };
+        }
+        const openai = u.prompt_tokens !== undefined ? [u.prompt_tokens_details, u.prompt_tokens, u.completion_tokens] // Chat Completions
+            : u.input_tokens_details !== undefined ? [u.input_tokens_details, u.input_tokens, u.output_tokens] : null; // Responses API
+        if (openai) { // OpenAI: the input total includes cache reads and writes
+            const [details, total, out] = openai;
+            const read = num(details?.cached_tokens), write = num(details?.cache_write_tokens);
+            return { model, input: num(total) - read - write, cacheRead: read, cacheWrite: write, output: num(out), reportedCost: reported };
+        }
+        return { model, input: num(u.input_tokens), cacheRead: num(u.cache_read_input_tokens), // Anthropic: input excludes cache
+            cacheWrite: num(u.cache_creation_input_tokens), output: num(u.output_tokens), reportedCost: reported };
+    }
+    const g = r.usageMetadata ?? r.usage_metadata;
+    if (!g || typeof g !== "object")
+        return null;
+    if (g.promptTokenCount !== undefined || g.prompt_token_count !== undefined) { // Gemini: thinking billed as output
+        const read = num(g.cachedContentTokenCount, g.cached_content_token_count);
+        return { model, input: num(g.promptTokenCount, g.prompt_token_count) - read, cacheRead: read, cacheWrite: 0,
+            output: num(g.candidatesTokenCount, g.candidates_token_count) + num(g.thoughtsTokenCount, g.thoughts_token_count),
+            reportedCost: null };
+    }
+    const read = num(g.input_token_details?.cache_read), write = num(g.input_token_details?.cache_creation); // LangChain.js
+    return { model, input: num(g.input_tokens) - read - write, cacheRead: read, cacheWrite: write, output: num(g.output_tokens),
+        reportedCost: null };
+}
+/** [cost in USD, tokens] for one model response. Warns once for a model it can't price. */
+export function costOf(response) {
+    const u = readUsage(response);
+    if (!u) {
+        const kind = response?.constructor?.name ?? typeof response;
+        warnOnce(`no-usage:${kind}`, `${kind} has no token usage, so this step costs $0. For streams, pass the final ` +
+            "message or a chunk that includes usage.");
+        return [0, 0];
+    }
+    const tokens = u.input + u.cacheRead + u.cacheWrite + u.output;
+    if (u.reportedCost !== null)
+        return [u.reportedCost, tokens];
+    const p = u.model ? priceOf(u.model) : undefined;
+    if (!p) {
+        warnOnce(`no-price:${u.model}`, `no price for model '${u.model}'. Its tokens are counted but its cost isn't, so ` +
+            `budgetUsd can't stop it. Add it with init({ prices: { "${u.model || "model-name"}": { input: ..., output: ... } } }) ` +
+            "(USD per 1M tokens).");
+        return [0, tokens];
+    }
+    const prompt = u.input + u.cacheRead + u.cacheWrite;
+    const rates = p.above !== undefined && p.tier && prompt > p.above ? { ...p, ...p.tier } : p; // long-context pricing
+    const cost = u.input * rates.in + u.cacheRead * (rates.cache_read ?? rates.in)
+        + u.cacheWrite * (rates.cache_write ?? rates.in) + u.output * rates.out;
+    return [cost, tokens];
+}

package/dist/spans.d.ts

@@ -0,0 +1,11 @@
+export declare const MAX_ARGS = 300;
+/** A `chat {model}` span. started is a performance.now() reading; response carries the usage. */
+export declare function recordLlmCall(provider: string, requestModel: string | undefined, started: number, response?: unknown, error?: unknown, opts?: {
+    stream?: boolean;
+    integration?: string;
+}): void;
+/** An `execute_tool {name}` span; args is a short summary of the call's arguments. */
+export declare function recordToolCall(name: string, args: string, started: number, error?: unknown, opts?: {
+    callId?: string;
+    integration?: string;
+}): void;

package/dist/spans.js

@@ -0,0 +1,35 @@
+/**
+ * Attributes for model and tool call spans, named as in the OpenTelemetry GenAI semantic
+ * conventions (gen_ai.*), plus Fences' own (fences.*). Same format as the Python SDK.
+ */
+import { recordSpan } from "./core.js";
+import { costOf, readUsage } from "./pricing.js";
+export const MAX_ARGS = 300; // characters of a tool call's argument summary
+/** A `chat {model}` span. started is a performance.now() reading; response carries the usage. */
+export function recordLlmCall(provider, requestModel, started, response, error, opts = {}) {
+    const attrs = { "gen_ai.operation.name": "chat", "gen_ai.provider.name": provider,
+        "gen_ai.request.model": requestModel, "fences.integration": opts.integration };
+    if (opts.stream)
+        attrs["gen_ai.request.stream"] = true; // usage arrives with the stream, so none is recorded here
+    const usage = response !== undefined && error === undefined ? readUsage(response) : null;
+    if (usage) {
+        Object.assign(attrs, {
+            "gen_ai.response.model": usage.model || undefined,
+            "gen_ai.usage.input_tokens": usage.input + usage.cacheRead + usage.cacheWrite, // OTel counts cached input in the total
+            "gen_ai.usage.cache_read.input_tokens": usage.cacheRead,
+            "gen_ai.usage.cache_write.input_tokens": usage.cacheWrite,
+            "gen_ai.usage.output_tokens": usage.output,
+            "fences.cost_usd": costOf(response)[0],
+        });
+    }
+    const model = attrs["gen_ai.response.model"] || requestModel || "unknown";
+    recordSpan(`chat ${model}`, performance.now() - started, attrs, error);
+}
+/** An `execute_tool {name}` span; args is a short summary of the call's arguments. */
+export function recordToolCall(name, args, started, error, opts = {}) {
+    recordSpan(`execute_tool ${name}`, performance.now() - started, {
+        "gen_ai.operation.name": "execute_tool", "gen_ai.tool.name": name, "gen_ai.tool.call.id": opts.callId,
+        "gen_ai.tool.call.arguments": args.length <= MAX_ARGS ? args : args.slice(0, MAX_ARGS - 1) + "…",
+        "fences.integration": opts.integration,
+    }, error);
+}

package/dist/tools.d.ts

@@ -0,0 +1,15 @@
+/** `{"query":"cats","limit":5}`: the arguments as compact JSON (one object argument on its own), capped. */
+export declare function argsSummary(args: unknown[]): string;
+/**
+ * Record every call of an agent tool on the active run:
+ *
+ *     const webSearch = tool(async (query: string) => { ... });
+ *     const fetchPage = tool(fetchPageImpl, { name: "fetch" });
+ *
+ * Records the tool's name, a short summary of its arguments, whether it succeeded (and the
+ * error if not) and how long it took. Errors still reach the caller; sync tools stay sync.
+ * Outside a governed run it just calls the function.
+ */
+export declare function tool<A extends unknown[], R>(fn: (...args: A) => R, options?: {
+    name?: string;
+}): (...args: A) => R;

package/dist/tools.js

@@ -0,0 +1,44 @@
+import { getActiveRun } from "./core.js";
+import { MAX_ARGS, recordToolCall } from "./spans.js";
+/** `{"query":"cats","limit":5}`: the arguments as compact JSON (one object argument on its own), capped. */
+export function argsSummary(args) {
+    let text;
+    try {
+        text = JSON.stringify(args.length === 1 ? args[0] : args, (_k, v) => typeof v === "bigint" ? String(v) : v) ?? "";
+    }
+    catch {
+        text = args.map(String).join(", "); // circular or odd values
+    }
+    return text.length <= MAX_ARGS ? text : text.slice(0, MAX_ARGS - 1) + "…";
+}
+/**
+ * Record every call of an agent tool on the active run:
+ *
+ *     const webSearch = tool(async (query: string) => { ... });
+ *     const fetchPage = tool(fetchPageImpl, { name: "fetch" });
+ *
+ * Records the tool's name, a short summary of its arguments, whether it succeeded (and the
+ * error if not) and how long it took. Errors still reach the caller; sync tools stay sync.
+ * Outside a governed run it just calls the function.
+ */
+export function tool(fn, options = {}) {
+    const name = options.name ?? (fn.name || "tool");
+    return (...args) => {
+        if (!getActiveRun())
+            return fn(...args);
+        const summary = argsSummary(args), started = performance.now();
+        let out;
+        try {
+            out = fn(...args);
+        }
+        catch (e) {
+            recordToolCall(name, summary, started, e);
+            throw e;
+        }
+        if (out instanceof Promise) {
+            return out.then((v) => { recordToolCall(name, summary, started); return v; }, (e) => { recordToolCall(name, summary, started, e); throw e; });
+        }
+        recordToolCall(name, summary, started);
+        return out;
+    };
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The one place the version lives; sent to Fences on every request. Keep in step with package.json. */
+export declare const VERSION = "0.3.0";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** The one place the version lives; sent to Fences on every request. Keep in step with package.json. */
+export const VERSION = "0.3.0";

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "agentfences",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "On-call for AI agents: limits your agents can't raise, cost tracking, a decision trail, and a stop button",
+  "license": "MIT",
+  "author": "Bhavik Sardar",
+  "homepage": "https://github.com/bhaviksardar/fences",
+  "repository": { "type": "git", "url": "git+https://github.com/bhaviksardar/fences.git", "directory": "sdk-js" },
+  "keywords": ["ai", "agents", "governance", "llm", "budget", "on-call"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "node scripts/prices.mjs && tsc",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}