agentfences 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,83 @@
-# 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.
+
+## Live control (from 0.4.0)
+
+From version 0.4.0, which isn't on npm yet: in cloud mode a heartbeat (every 15 seconds, `init({ heartbeatS })`) lets whoever is on call act on a running agent from the dashboard:
+
+- **Stop:** the next `checkpoint()` returns `breachType: "stopped_by_user"`, so the agent wraps up gracefully.
+- **Pause and resume:** a paused run waits inside its next `checkpoint()` until it's resumed; after `pauseTimeoutS` (default one hour) it returns `breachType: "paused"`.
+- **Limits** changed in the dashboard apply to the run immediately. **Quarantine** makes the governed call throw `AgentQuarantined` before any agent code runs.
+
+An agent can ask a person before doing something risky:
+
+```ts
+import { requestApproval } from "agentfences";
+
+const approval = await requestApproval("Refund $240 to order 1182?", { amountUsd: 240, timeoutS: 600 });
+if (!approval.granted) return `I didn't issue the refund: ${approval.note}`;
+```
+
+An approved amount raises the run's budget. It never hangs or throws: in local mode, outside a run, or on a server without approvals it's denied right away, and with no answer it's denied after `timeoutS`. The heartbeat's timer never keeps your process alive on its own.
+
+## 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. Everything here follows the same server protocol ([PROTOCOL.md](../PROTOCOL.md)).

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+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>;
+    /** Report live runs; the reply may carry commands for them. */
+    heartbeat(runs: 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.
+     */
+    post(path: string, payload: unknown, optional?: boolean): Promise<Reply>;
+}

package/dist/client.js

@@ -0,0 +1,62 @@
+/** 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); }
+    /** Report live runs; the reply may carry commands for them. */
+    heartbeat(runs) { return this.post("/api/heartbeat", { runs }, 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.
+     */
+    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/control.d.ts

@@ -0,0 +1,43 @@
+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;
+}
+/** Live-control state a run carries. */
+export interface Control {
+    stopped: boolean;
+    paused: boolean;
+    pauseExpired: boolean;
+    /** approval id -> the answer, or null while waiting */
+    approvals: Map<string, Approval | null>;
+    awaiting: number;
+}
+export declare const newControl: () => Control;
+export declare let pauseTimeoutMs: number;
+export declare function configure(c: FencesClient | null, heartbeatS: number, pauseTimeoutS: number): void;
+export declare function register(run: Run): void;
+export declare function unregister(run: Run): void;
+/** Apply the commands addressed to this run (from a heartbeat or a checkpoint reply). Each is safe to apply twice. */
+export declare function apply(run: Run, commands: Reply[] | undefined): void;
+/** 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

@@ -0,0 +1,162 @@
+/**
+ * Live control from the Fences dashboard: a heartbeat that reports live runs and brings back
+ * commands (stop, pause, resume, limits, approval answers), pausing at checkpoints, 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";
+const FAST_MS = 2000; // heartbeat interval while a run is paused or waiting for an approval
+export const newControl = () => ({ stopped: false, paused: false, pauseExpired: false, approvals: new Map(), awaiting: 0 });
+const live = new Map(); // run id -> runs in progress
+let client = null;
+let intervalMs = 15_000;
+export let pauseTimeoutMs = 3_600_000;
+const supported = { heartbeat: true, approvals: true };
+let timer = null;
+let beating = false;
+export function configure(c, heartbeatS, pauseTimeoutS) {
+    client = c;
+    intervalMs = heartbeatS * 1000;
+    pauseTimeoutMs = pauseTimeoutS * 1000;
+    supported.heartbeat = supported.approvals = true;
+    schedule(0); // a new client or interval takes effect now, not after the old wait
+}
+export function register(run) {
+    live.set(run.runId, run);
+    if (!timer)
+        schedule(nextDelay());
+}
+export function unregister(run) {
+    live.delete(run.runId);
+}
+function unsupported(kind, what, consequence) {
+    if (!supported[kind])
+        return;
+    supported[kind] = false;
+    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" };
+/** Apply the commands addressed to this run (from a heartbeat or a checkpoint reply). Each is safe to apply twice. */
+export function apply(run, commands) {
+    for (const c of commands ?? []) {
+        if (c.run_id !== undefined && c.run_id !== run.runId)
+            continue;
+        const ctl = run.control;
+        if (c.type === "stop") {
+            ctl.stopped = true;
+            ctl.paused = false;
+        }
+        else if (c.type === "pause") {
+            ctl.paused = true;
+            schedule(0);
+        }
+        else if (c.type === "resume") {
+            ctl.paused = false;
+        }
+        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
+            }
+        }
+        else if (c.type === "approval" && 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 });
+        }
+    }
+}
+const busy = () => [...live.values()].some((r) => r.control.paused || r.control.awaiting > 0);
+const nextDelay = () => (busy() ? Math.min(FAST_MS, intervalMs) : intervalMs); // faster while busy, never slower
+function schedule(delayMs) {
+    if (timer)
+        clearTimeout(timer);
+    timer = null;
+    if (!client || !supported.heartbeat || !live.size)
+        return;
+    timer = setTimeout(beat, delayMs);
+    timer.unref(); // the heartbeat never keeps the process alive on its own
+}
+async function beat() {
+    timer = null;
+    if (beating || !client || !live.size)
+        return schedule(nextDelay());
+    beating = true;
+    try {
+        const runs = [...live.values()];
+        const resp = await client.heartbeat(runs.map((r) => ({ run_id: r.runId, iterations: r.iterations, spent_usd: r.costUsd,
+            tokens_used: r.tokensUsed, paused: r.control.paused })));
+        if (resp.unsupported) {
+            unsupported("heartbeat", "the heartbeat", "a stop from the dashboard applies at the next checkpoint and pause isn't available");
+            return;
+        }
+        for (const run of runs)
+            apply(run, resp.commands?.filter((c) => c.run_id === run.runId));
+    }
+    catch { /* a failed heartbeat is retried next time */ }
+    finally {
+        beating = false;
+    }
+    schedule(nextDelay());
+}
+// ── Pausing ───────────────────────────────────────────────────────────────────
+/** Hold the agent at its checkpoint while its run is paused, up to pauseTimeoutS. */
+export async function waitIfPaused(run) {
+    const deadline = Date.now() + pauseTimeoutMs;
+    while (run.control.paused) {
+        if (Date.now() >= deadline) {
+            run.control.paused = false;
+            run.control.pauseExpired = true;
+            return;
+        }
+        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" };
+    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

@@ -0,0 +1,130 @@
+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;
+    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;
+    /** Seconds between heartbeats reporting live runs (cloud mode). Default 15. */
+    heartbeatS?: number;
+    /** How long a paused run waits at its checkpoint before stopping with breach "paused". Default 3600. */
+    pauseTimeoutS?: number;
+}
+/** 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;