agentfences 0.3.0 → 0.4.0

package/README.md

@@ -59,6 +59,25 @@ init({ apiKey: process.env.FENCES_API_KEY, endpoint: "https://your-fences-host",
 
 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 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)).
+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

@@ -9,6 +9,9 @@ export declare class FencesClient {
     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.

package/dist/client.js

@@ -17,6 +17,9 @@ export class FencesClient {
     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.

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

@@ -1,4 +1,5 @@
 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 {
@@ -55,6 +56,8 @@ export declare class Run {
     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;
 }
@@ -77,6 +80,10 @@ export interface InitOptions {
     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;

package/dist/core.js

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { FencesClient } from "./client.js";
+import * as control from "./control.js";
 import { AgentQuarantined, FencesStop } from "./errors.js";
 import * as events from "./events.js";
 import { costOf, setCustomPrices } from "./pricing.js";
@@ -57,6 +58,8 @@ export class Run {
     lastBreach = null;
     exception;
     warned = false;
+    /** Live control from the dashboard (see control.ts). */
+    control = control.newControl();
     constructor(agentName, budgetUsd, maxIterations, maxDurationMs, maxTokens, context) {
         this.agentName = agentName;
         this.budgetUsd = budgetUsd;
@@ -83,15 +86,17 @@ export function init(options = {}) {
     failClosed = !!options.failClosed;
     if (localOnly) {
         client = null;
-        return;
     }
-    if (!options.apiKey) {
+    else 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");
+    else {
+        client = new FencesClient(options.apiKey, options.endpoint ?? "http://localhost:8000");
+    }
+    control.configure(client, options.heartbeatS ?? 15, options.pauseTimeoutS ?? 3600);
 }
 /** @internal For tests: point the SDK at a fake server client. */
-export function _setClient(c) { client = c; }
+export function _setClient(c) { client = c; control.configure(c, 15, 3600); }
 function requireInit() {
     if (!localOnly && !client) {
         throw new Error("Call agentfences.init() before using Fences. For local usage: init({ localOnly: true })");
@@ -118,6 +123,7 @@ export function governed(fn, options = {}) {
     return async (...args) => {
         requireInit();
         const run = await startRun(name, options);
+        control.register(run);
         let error, failed = false;
         try {
             return await store.run(run, () => fn(...args));
@@ -179,6 +185,7 @@ 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) {
+    control.unregister(run);
     if (!client)
         return;
     // The run must end even if redaction drops its error details
@@ -214,7 +221,12 @@ export async function checkpoint(response, extra = {}) {
     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);
+    const result = decide(run, resp);
+    if (run.control.paused && !result.breached) { // paused from the dashboard: wait here until resumed
+        await control.waitIfPaused(run);
+        return finalResult(run);
+    }
+    return result;
 }
 function localBreach(run) {
     // Limits trip only once exceeded, same rule as the server; round away float drift (0.02*5 != 0.10)
@@ -240,6 +252,7 @@ function decide(run, resp) {
         run.lastBreach = localBreach(run);
     }
     else {
+        control.apply(run, resp.commands);
         // The server is authoritative: adopt its totals and (on a breach) its current limits
         run.costUsd = resp.spent_usd ?? run.costUsd;
         run.iterations = resp.iterations ?? run.iterations;
@@ -251,6 +264,13 @@ function decide(run, resp) {
         // 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 finalResult(run);
+}
+function finalResult(run) {
+    if (run.control.stopped)
+        run.lastBreach = "stopped_by_user"; // a stop from the dashboard sticks, whatever a later reply says
+    else if (run.control.pauseExpired)
+        run.lastBreach = "paused";
     return run.lastBreach ? breachResult(run.lastBreach, run) : okResult(run.costUsd);
 }
 // ── Decision trail and spans ──────────────────────────────────────────────────

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export type { CheckpointResult, InitOptions, Limits, Extra, Span } from "./core.
 export { context } from "./events.js";
 export type { RedactHook, Event } from "./events.js";
 export { tool } from "./tools.js";
+export { requestApproval } from "./control.js";
+export type { Approval } from "./control.js";
 export { priceOf } from "./pricing.js";
 export type { CustomPrice } from "./pricing.js";
 export { FencesError, FencesAuthError, AgentQuarantined, FencesStop } from "./errors.js";

package/dist/index.js

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

package/dist/version.d.ts

@@ -1,2 +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";
+export declare const VERSION = "0.4.0";

package/dist/version.js

@@ -1,2 +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";
+export const VERSION = "0.4.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfences",
-  "version": "0.3.0",
+  "version": "0.4.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",