agentfences 0.8.0 → 0.9.0

package/README.md

@@ -47,7 +47,7 @@ const webSearch = tool(async ({ query }: { query: string }) => search(query));
 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`.
+- Tool and model calls are recorded as OpenTelemetry-shaped spans (`execute_tool webSearch`, `gen_ai.*` attributes), on `getActiveRun().events`. A tool call carries its argument names (`query, limit`), not their values; `init({ toolArguments: "full" })` records the values as JSON (300 characters at most), `"none"` neither (from 0.9.0). A guarded tool's check and an approval request still send the values.
 - 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.
 

package/dist/client.d.ts

@@ -1,10 +1,28 @@
 export type Reply = Record<string, any>;
+export declare const FAILURES_TO_OPEN = 3;
+/**
+ * A circuit breaker: after FAILURES_TO_OPEN failed calls in a row (no connection, a timeout, a 5xx,
+ * or a 429 on anything but the heartbeat), skip calls for about 30 seconds, then let one through to test the server. While it's open
+ * a call fails at once instead of after the timeout: checkpoints are enforced locally and guarded
+ * tools are blocked, without adding seconds to every step.
+ */
+export declare class Breaker {
+    failures: number;
+    openUntil: number;
+    private probing;
+    allow(): boolean;
+    record(ok: boolean): void;
+}
 export declare class FencesClient {
     readonly endpoint: string;
     private readonly timeoutMs;
     private readonly headers;
+    readonly breaker: Breaker;
+    /** The server echoed a step_id: it counts a repeated step once, so retrying a checkpoint is safe. */
+    dedupesSteps: boolean;
     constructor(apiKey: string, endpoint: string, timeoutMs?: number);
     startRun(body: Record<string, unknown>): Promise<Reply>;
+    /** body.step_id, if set, lets the server count the step once however often it's sent. */
     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>;
@@ -19,6 +37,8 @@ export declare class FencesClient {
      * and any other error { ok: false, status }.
      * start: a rejected key throws FencesAuthError, before any agent code runs. Later in a run it
      * returns { network_error, auth_rejected: true }: throwing there would replace the agent's own result or error.
+     * retry: a call that's safe to repeat goes once more after a connection error (not after a timeout,
+     * which would double the wait).
      */
-    post(path: string, payload: unknown, optional?: boolean, start?: boolean): Promise<Reply>;
+    post(path: string, payload: unknown, optional?: boolean, start?: boolean, retry?: boolean): Promise<Reply>;
 }

package/dist/client.js

@@ -4,10 +4,52 @@
  */
 import { FencesAuthError } from "./errors.js";
 import { VERSION } from "./version.js";
+export const FAILURES_TO_OPEN = 3; // failed calls in a row before the breaker opens
+const OPEN_MS = 30_000; // how long calls are skipped once it's open (with jitter), before one goes through to test
+/**
+ * A circuit breaker: after FAILURES_TO_OPEN failed calls in a row (no connection, a timeout, a 5xx,
+ * or a 429 on anything but the heartbeat), skip calls for about 30 seconds, then let one through to test the server. While it's open
+ * a call fails at once instead of after the timeout: checkpoints are enforced locally and guarded
+ * tools are blocked, without adding seconds to every step.
+ */
+export class Breaker {
+    failures = 0;
+    openUntil = 0;
+    probing = false;
+    allow() {
+        if (this.failures < FAILURES_TO_OPEN)
+            return true;
+        if (this.probing || Date.now() < this.openUntil)
+            return false;
+        this.probing = true; // one test call at a time
+        return true;
+    }
+    record(ok) {
+        const wasOpen = this.failures >= FAILURES_TO_OPEN;
+        this.probing = false;
+        if (ok) {
+            this.failures = 0;
+            if (wasOpen)
+                console.warn("agentfences: Fences is reachable again");
+            return;
+        }
+        this.failures += 1;
+        if (this.failures < FAILURES_TO_OPEN)
+            return;
+        this.openUntil = Date.now() + OPEN_MS * (0.75 + Math.random() / 2); // jitter: SDKs cut off together don't all come back at once
+        if (!wasOpen) {
+            console.warn(`agentfences: Fences failed ${this.failures} calls in a row; skipping calls for about ${OPEN_MS / 1000}s ` +
+                "(limits enforced locally, guarded tools blocked)");
+        }
+    }
+}
 export class FencesClient {
     endpoint;
     timeoutMs;
     headers;
+    breaker = new Breaker();
+    /** The server echoed a step_id: it counts a repeated step once, so retrying a checkpoint is safe. */
+    dedupesSteps = false;
     constructor(apiKey, endpoint, timeoutMs = 3000) {
         this.endpoint = endpoint;
         this.timeoutMs = timeoutMs;
@@ -16,7 +58,13 @@ export class FencesClient {
         this.headers = { "Content-Type": "application/json", "X-API-Key": apiKey, "X-Fences-SDK": `js/${VERSION}` };
     }
     startRun(body) { return this.post("/api/runs/start", body, false, true); }
-    checkpoint(runId, body) { return this.post(`/api/runs/${runId}/checkpoint`, body); }
+    /** body.step_id, if set, lets the server count the step once however often it's sent. */
+    async checkpoint(runId, body) {
+        const resp = await this.post(`/api/runs/${runId}/checkpoint`, body, false, false, !!body.step_id && this.dedupesSteps);
+        if (body.step_id && resp.step_id === body.step_id)
+            this.dedupesSteps = true;
+        return resp;
+    }
     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); }
@@ -25,24 +73,48 @@ export class FencesClient {
         return this.post("/api/heartbeat", acks.length ? { runs, acks } : { runs }, true);
     }
     /** Check a guarded tool call before it runs ({ phase: "check" }), or settle it after ({ phase: "settle" }). */
-    guard(runId, body) { return this.post(`/api/runs/${runId}/guard`, body, true); }
+    guard(runId, body) { return this.post(`/api/runs/${runId}/guard`, body, true, false, true); } // guard_id: safe to repeat
     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 any other error { ok: false, status }.
      * start: a rejected key throws FencesAuthError, before any agent code runs. Later in a run it
      * returns { network_error, auth_rejected: true }: throwing there would replace the agent's own result or error.
+     * retry: a call that's safe to repeat goes once more after a connection error (not after a timeout,
+     * which would double the wait).
      */
-    async post(path, payload, optional = false, start = false) {
+    async post(path, payload, optional = false, start = false, retry = false) {
+        if (!this.breaker.allow())
+            return { network_error: "Fences unreachable: calls paused after repeated failures" };
+        let json;
+        try {
+            json = JSON.stringify(payload);
+        }
+        catch (e) { // a payload JSON can't encode: not the server's fault
+            this.breaker.record(true);
+            return { network_error: String(e) };
+        }
+        const send = () => fetch(this.endpoint + path, {
+            method: "POST", headers: this.headers, body: json, signal: AbortSignal.timeout(this.timeoutMs),
+        });
         let resp;
         try {
-            resp = await fetch(this.endpoint + path, {
-                method: "POST", headers: this.headers, body: JSON.stringify(payload), signal: AbortSignal.timeout(this.timeoutMs),
-            });
+            try {
+                resp = await send();
+            }
+            catch (e) {
+                if (!retry || e?.name === "TimeoutError")
+                    throw e;
+                await new Promise((ok) => setTimeout(ok, 100 + Math.random() * 200)); // a blip: once more, after a moment
+                resp = await send();
+            }
         }
         catch (e) {
+            this.breaker.record(false);
             return { network_error: String(e) };
         }
+        // A 429 on the heartbeat is its own budget, not an outage: it mustn't cut off checkpoints
+        this.breaker.record(resp.status < 500 && (resp.status !== 429 || path === "/api/heartbeat"));
         const text = await resp.text().catch(() => "");
         let body = {}, isJson = false;
         try {

package/dist/control.js

@@ -2,6 +2,7 @@
 const retryable = (status) => status === undefined || status === 429 || status >= 500;
 const FAST_MS = 2000; // heartbeat interval while a run is paused, waiting for an approval, or stopping
 const HOOK_TIMEOUT_MS = 30_000; // a hook still running after this is reported as timed out
+const MAX_BACKOFF_MS = 60_000; // longest wait between heartbeats after failures (jittered)
 export const newControl = () => ({
     stopped: false, stoppedAt: 0, stopSeen: false, cancelled: false, onCancel: null, paused: false, pauseExpired: false,
     quarantined: false, held: null, approvals: new Map(), awaiting: 0, acked: new Set(),
@@ -17,6 +18,7 @@ const hooks = { stop: null, quarantine: null };
 export const supported = { heartbeat: true, approvals: true, guard: true };
 let timer = null;
 let beating = false;
+const backoff = { failed: 0, nextTry: 0 }; // heartbeats failed in a row, and when the next may go
 let acks = []; // acknowledgements waiting for the next heartbeat
 const hooked = new Set(); // quarantine ids whose hook has run in this process
 const runningHooks = new Set();
@@ -28,6 +30,7 @@ export function configure(c, o) {
     hooks.stop = o.onStop ?? null;
     hooks.quarantine = o.onQuarantine ?? null;
     supported.heartbeat = supported.approvals = supported.guard = true;
+    Object.assign(backoff, { failed: 0, nextTry: 0 });
     schedule(0); // a new client or interval takes effect now, not after the old wait
 }
 export function register(run) {
@@ -186,6 +189,13 @@ export function schedule(delayMs) {
     timer = setTimeout(beat, delayMs);
     timer.unref(); // the heartbeat never keeps the process alive on its own
 }
+/** After a failed heartbeat: wait longer before the next, doubling from the shortest interval in use, with jitter,
+ *  so SDKs coming back from the same outage don't all beat at once. */
+function backOff() {
+    backoff.failed += 1;
+    const wait = Math.min(Math.min(FAST_MS, intervalMs) * 2 ** (backoff.failed - 1), MAX_BACKOFF_MS);
+    backoff.nextTry = Date.now() + wait * (0.5 + Math.random() / 2);
+}
 /** Halt governed calls that haven't reached a checkpoint within stopGraceS of a stop. */
 function cancelOverdue() {
     if (stopGraceMs === null)
@@ -199,8 +209,8 @@ function cancelOverdue() {
 }
 async function beat() {
     timer = null;
-    cancelOverdue();
-    if (beating || !client || !(live.size || acks.length))
+    cancelOverdue(); // local, so it keeps its schedule while heartbeats back off
+    if (beating || !client || !(live.size || acks.length) || Date.now() < backoff.nextTry)
         return schedule(nextDelay());
     beating = true;
     const runs = [...live.values()], batch = acks;
@@ -210,20 +220,24 @@ async function beat() {
             tokens_used: r.tokensUsed, paused: r.control.paused, stopped: r.control.stopped,
             ...(r.control.held ? { held: r.control.held } : {}) })), batch);
         if (resp.network_error || (resp.ok === false && !resp.unsupported)) {
-            if (resp.network_error || retryable(resp.status))
+            if (resp.network_error || retryable(resp.status)) {
                 acks = [...batch, ...acks]; // at least once; any other 4xx won't get better
+                backOff();
+            }
         }
         else if (resp.unsupported) {
             unsupported("heartbeat", "the heartbeat", "a stop from the dashboard applies at the next checkpoint and pause isn't available");
             return;
         }
         else {
+            Object.assign(backoff, { failed: 0, nextTry: 0 });
             for (const run of runs)
                 apply(run, resp.commands?.filter((c) => c.run_id === run.runId));
         }
     }
     catch {
         acks = [...batch, ...acks]; // a failed heartbeat is retried next time
+        backOff();
     }
     finally {
         beating = false;

package/dist/core.d.ts

@@ -1,12 +1,8 @@
-/**
- * init(), governed() and checkpoint(): starting and ending runs, checking every step against
- * its limits (the server decides in cloud mode, the same rules apply here otherwise), and
- * recording decisions and spans.
- */
 import { FencesClient } from "./client.js";
 import * as control from "./control.js";
 import * as events from "./events.js";
 import { type CustomPrice } from "./pricing.js";
+import { type ToolArguments } from "./spans.js";
 import { type CheckpointResult } from "./results.js";
 import { Run, type Limits } from "./run.js";
 export type { CheckpointResult } from "./results.js";
@@ -53,6 +49,12 @@ export interface InitOptions {
      * wait, and after pauseTimeoutS the breach is returned as usual. Cloud only; override per agent in governed().
      */
     onBreach?: "hold" | null;
+    /**
+     * What a recorded tool call carries of its arguments: "names" (the default: `query, limit`),
+     * "full" (the arguments as JSON, capped) or "none". A guarded tool's check and an approval request
+     * still send the values, which rules and approvers need; the redact hook can change or drop them.
+     */
+    toolArguments?: ToolArguments;
 }
 /** Call once at startup, before any governed function runs. */
 export declare function init(options?: InitOptions): void;

package/dist/core.js

@@ -3,6 +3,7 @@
  * its limits (the server decides in cloud mode, the same rules apply here otherwise), and
  * recording decisions and spans.
  */
+import { randomUUID } from "node:crypto";
 import { FencesClient } from "./client.js";
 import * as control from "./control.js";
 import { AgentQuarantined, FencesStop } from "./errors.js";
@@ -10,6 +11,7 @@ import * as events from "./events.js";
 import * as outbox from "./outbox.js";
 import * as precheck from "./precheck.js";
 import { costOf, setCustomPrices } from "./pricing.js";
+import { setToolArguments } from "./spans.js";
 import { breachResult, okResult } from "./results.js";
 import { DEFAULTS, MAX_EVENTS_PER_RUN, Run, getActiveRun, store } from "./run.js";
 export { Run, getActiveRun } from "./run.js";
@@ -26,6 +28,7 @@ function checkOnBreach(value) {
 }
 /** Call once at startup, before any governed function runs. */
 export function init(options = {}) {
+    setToolArguments(options.toolArguments ?? "names");
     setCustomPrices(options.prices);
     events.configure(options.environment, options.release, options.redact);
     localOnly = !!options.localOnly;
@@ -182,9 +185,9 @@ export async function checkpoint(response, extra = {}) {
     precheck.releaseFinished(run);
     run.tokensUsed += stepTokens;
     run.iterations += 1;
-    const resp = client ? await client.checkpoint(run.runId, {
-        cost_delta_usd: stepCost, tokens_used: stepTokens, iterations: run.iterations, duration_ms: run.durationMs
-    }) : null;
+    // A step_id per step: a retried checkpoint is counted once on servers that support it
+    const resp = client ? await client.checkpoint(run.runId, { cost_delta_usd: stepCost, tokens_used: stepTokens,
+        iterations: run.iterations, duration_ms: run.durationMs, step_id: randomUUID().replaceAll("-", "") }) : null;
     const result = decide(run, resp);
     // onBreach "hold": wait here for someone to raise the limit. Only a breach the server decided: an unreachable one can't be raised
     if (result.breachType && control.HOLDABLE.has(result.breachType) && control.holds(run) && resp && !resp.network_error) {

package/dist/mcp.js

@@ -34,7 +34,7 @@ export function wrap(client, options = {}) {
                 if (result?.isError)
                     throw new MCPToolError(result);
                 return result;
-            });
+            }, Object.keys(args).join(", "));
         }
         catch (e) {
             if (e instanceof MCPToolError)

package/dist/spans.d.ts

@@ -1,11 +1,21 @@
 export declare const MAX_ARGS = 300;
+export type ToolArguments = "names" | "full" | "none";
+/** init({ toolArguments }): what tool call spans carry of the arguments. */
+export declare let toolArguments: ToolArguments;
+/** @internal */
+export declare function setToolArguments(value: unknown): void;
 /** 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. */
+/**
+ * An `execute_tool {name}` span. args is a short summary of the call's arguments and opts.argNames
+ * just their names: the span carries the names by default, the values only with
+ * init({ toolArguments: "full" }), and neither with "none".
+ */
 export declare function recordToolCall(name: string, args: string, started: number, error?: unknown, opts?: {
     callId?: string;
     integration?: string;
+    argNames?: string;
 }): void;

package/dist/spans.js

@@ -5,6 +5,15 @@
 import { recordSpan } from "./core.js";
 import { costOf, readUsage } from "./pricing.js";
 export const MAX_ARGS = 300; // characters of a tool call's argument summary
+/** init({ toolArguments }): what tool call spans carry of the arguments. */
+export let toolArguments = "names";
+/** @internal */
+export function setToolArguments(value) {
+    if (value !== "names" && value !== "full" && value !== "none") {
+        throw new TypeError(`toolArguments must be "names", "full" or "none", not ${JSON.stringify(value)}`);
+    }
+    toolArguments = value;
+}
 /** 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,
@@ -25,11 +34,16 @@ export function recordLlmCall(provider, requestModel, started, response, error,
     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. */
+/**
+ * An `execute_tool {name}` span. args is a short summary of the call's arguments and opts.argNames
+ * just their names: the span carries the names by default, the values only with
+ * init({ toolArguments: "full" }), and neither with "none".
+ */
 export function recordToolCall(name, args, started, error, opts = {}) {
+    const sent = toolArguments === "full" ? args : toolArguments === "names" ? opts.argNames : undefined;
     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) + "…",
+        "gen_ai.tool.call.arguments": sent === undefined || sent.length <= MAX_ARGS ? sent : sent.slice(0, MAX_ARGS - 1) + "…",
         "fences.integration": opts.integration,
     }, error);
 }

package/dist/tools.d.ts

@@ -1,8 +1,11 @@
 import { type Run } from "./core.js";
+/** `query, limit` (one object argument: its keys), or `0, 1` (positions): what a tool call span carries by default. */
+export declare function argNames(args: unknown[]): string;
 /** `{"query":"cats","limit":5}`: the arguments as compact JSON (one object argument on its own), capped. */
 export declare function argsSummary(args: unknown[]): string;
 /** Record an async tool call; cost is null for an unguarded call, else a function giving its amount. */
-export declare function callAsync<R>(run: Run, name: string, summary: string, cost: (() => number) | null, needsApproval: boolean, call: () => Promise<R>): Promise<R>;
+/** summary (the values) goes to the guard and an approval request; the span gets names. */
+export declare function callAsync<R>(run: Run, name: string, summary: string, cost: (() => number) | null, needsApproval: boolean, call: () => Promise<R>, names?: string): Promise<R>;
 interface ToolFields<A extends unknown[]> {
     name?: string;
     /** Reject with a TimeoutError if the call takes longer. JS can't stop the tool's code; pass run.signal to its fetches. */

package/dist/tools.js

@@ -5,6 +5,13 @@ import { _client, checkAmount, getActiveRun, localBreach } from "./core.js";
 import { ToolBlocked } from "./errors.js";
 import * as events from "./events.js";
 import { MAX_ARGS, recordToolCall } from "./spans.js";
+/** `query, limit` (one object argument: its keys), or `0, 1` (positions): what a tool call span carries by default. */
+export function argNames(args) {
+    const [only] = args;
+    if (args.length === 1 && only && typeof only === "object" && !Array.isArray(only))
+        return Object.keys(only).join(", ");
+    return args.map((_, i) => String(i)).join(", ");
+}
 /** `{"query":"cats","limit":5}`: the arguments as compact JSON (one object argument on its own), capped. */
 export function argsSummary(args) {
     let text;
@@ -112,7 +119,8 @@ async function settle(run, guardId, amount, error, failed) {
     await _client()?.guard(run.runId, { guard_id: guardId, phase: "settle", outcome, cost_usd: charged });
 }
 /** Record an async tool call; cost is null for an unguarded call, else a function giving its amount. */
-export async function callAsync(run, name, summary, cost, needsApproval, call) {
+/** summary (the values) goes to the guard and an approval request; the span gets names. */
+export async function callAsync(run, name, summary, cost, needsApproval, call, names) {
     const started = performance.now();
     let gate = null;
     try {
@@ -121,13 +129,13 @@ export async function callAsync(run, name, summary, cost, needsApproval, call) {
             gate = [await open(run, name, summary, amount, needsApproval), amount];
         }
         const out = await call();
-        recordToolCall(name, summary, started);
+        recordToolCall(name, summary, started, undefined, { argNames: names });
         if (gate)
             await settle(run, ...gate, undefined, false);
         return out;
     }
     catch (e) {
-        recordToolCall(name, summary, started, e);
+        recordToolCall(name, summary, started, e, { argNames: names });
         if (gate)
             await settle(run, ...gate, e, true);
         throw e;
@@ -151,25 +159,25 @@ export function tool(fn, options = {}) {
             if (!run)
                 return timed(Promise.resolve().then(() => fn(...args)), options.timeoutS, name);
             const c = options.costUsd;
-            return callAsync(run, name, argsSummary(args), guarded ? () => (typeof c === "function" ? c(...args) : c) ?? 0 : null, !!options.approve, () => timed(Promise.resolve().then(() => fn(...args)), options.timeoutS, name));
+            return callAsync(run, name, argsSummary(args), guarded ? () => (typeof c === "function" ? c(...args) : c) ?? 0 : null, !!options.approve, () => timed(Promise.resolve().then(() => fn(...args)), options.timeoutS, name), argNames(args));
         };
     }
     return (...args) => {
         if (!getActiveRun())
             return fn(...args);
-        const summary = argsSummary(args), started = performance.now();
+        const summary = argsSummary(args), started = performance.now(), opts = { argNames: argNames(args) };
         let out;
         try {
             out = fn(...args);
         }
         catch (e) {
-            recordToolCall(name, summary, started, e);
+            recordToolCall(name, summary, started, e, opts);
             throw e;
         }
         if (out instanceof Promise) {
-            return out.then((v) => { recordToolCall(name, summary, started); return v; }, (e) => { recordToolCall(name, summary, started, e); throw e; });
+            return out.then((v) => { recordToolCall(name, summary, started, undefined, opts); return v; }, (e) => { recordToolCall(name, summary, started, e, opts); throw e; });
         }
-        recordToolCall(name, summary, started);
+        recordToolCall(name, summary, started, undefined, opts);
         return out;
     };
 }

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.8.0";
+export declare const VERSION = "0.9.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.8.0";
+export const VERSION = "0.9.0";

package/package.json

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