agentfences 0.8.0 → 0.9.1

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.
 
@@ -57,7 +57,7 @@ await context({ user_id: "u_123", session_id: "s_9" }, () => research(question))
 init({ apiKey: process.env.FENCES_API_KEY, endpoint: "https://your-fences-host", environment: "prod", release: "v1.4.2" });
 ```
 
-The server is authoritative for limits and sees spend across processes. If it can't be reached, limits are enforced locally; pass `failClosed: true` to stop instead. A rejected key throws `FencesAuthError` when the run starts, and a key revoked during a run ends it at its next checkpoint (`fences_unreachable`); a quarantined agent throws `AgentQuarantined` before any of its code runs. A cost that isn't a finite number of zero or more throws instead of being counted. In serverless handlers, `await flush()` before returning so queued decisions and spans are sent.
+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. `endpoint` must be an `https://` URL unless the server is on the same machine; `allowHttp: true` permits plain HTTP for a trusted private network (from 0.9.1). A server reply can raise a budget, but can't make a budget set in code unlimited. A rejected key throws `FencesAuthError` when the run starts, and a key revoked during a run ends it at its next checkpoint (`fences_unreachable`); a quarantined agent throws `AgentQuarantined` before any of its code runs. A cost that isn't a finite number of zero or more throws instead of being counted. In serverless handlers, `await flush()` before returning so queued decisions and spans are sent.
 
 ## Live control (from 0.4.0)
 

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,53 @@ 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) };
+        }
+        // Redirects aren't followed: one would carry the API key (and the request) to wherever it points
+        const send = () => fetch(this.endpoint + path, {
+            method: "POST", headers: this.headers, body: json, signal: AbortSignal.timeout(this.timeoutMs), redirect: "manual",
+        });
         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"));
+        if (resp.type === "opaqueredirect" || (resp.status >= 300 && resp.status < 400)) { // not followed: treated as no answer
+            return { network_error: `Fences answered with a redirect (HTTP ${resp.status} to ${JSON.stringify(resp.headers.get("location") ?? "?")}), ` +
+                    "which isn't followed; check the endpoint" };
+        }
         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,18 @@ 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;
+    /**
+     * endpoint must use https://, except on this machine (localhost, 127.0.0.1, ::1): over plain HTTP anyone
+     * on the network path could read the API key and rewrite the server's replies, limits included.
+     * true permits it, for a trusted private network.
+     */
+    allowHttp?: boolean;
 }
 /** 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;
@@ -38,7 +41,9 @@ export function init(options = {}) {
         throw new Error("apiKey is required unless localOnly is set. Use init({ localOnly: true }) for local usage.");
     }
     else {
-        client = new FencesClient(options.apiKey, options.endpoint ?? "http://localhost:8000");
+        const endpoint = options.endpoint ?? "http://localhost:8000";
+        checkEndpoint(endpoint, !!options.allowHttp);
+        client = new FencesClient(options.apiKey, endpoint);
     }
     control.configure(client, { heartbeatS: options.heartbeatS ?? 15, pauseTimeoutS: options.pauseTimeoutS ?? 3600,
         stopGraceS: options.stopGraceS === undefined ? 30 : options.stopGraceS, onStop: options.onStop, onQuarantine: options.onQuarantine });
@@ -50,6 +55,26 @@ export function _setClient(c) {
 }
 /** @internal */
 export const _client = () => client;
+function checkEndpoint(endpoint, allowHttp) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new TypeError(`endpoint must be an https:// URL, not ${JSON.stringify(endpoint)}`);
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password || endpoint.includes("\\")) {
+        throw new TypeError(`endpoint must be an https:// URL with no username or backslash, not ${JSON.stringify(endpoint)}`);
+    }
+    if (url.protocol === "https:")
+        return;
+    const host = url.hostname; // parsed as fetch will: the host checked is the host connected to
+    const local = host === "localhost" || host === "127.0.0.1" || host === "[::1]";
+    if (!local && !allowHttp) {
+        throw new TypeError(`endpoint ${JSON.stringify(endpoint)} uses plain HTTP: the API key and the server's replies, limits ` +
+            "included, would cross the network unencrypted. Use https://, or pass allowHttp: true for a trusted private network.");
+    }
+}
 function requireInit() {
     if (!localOnly && !client) {
         throw new Error("Call agentfences.init() before using Fences. For local usage: init({ localOnly: true })");
@@ -113,6 +138,7 @@ function outcome(run, failed, error) {
 }
 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());
+    run.budgetInCode = limits.budgetUsd != null;
     if (!client) {
         if (run.budgetUsd === null)
             noBudget(agentName, "Set one with governed(fn, { budgetUsd: ... }).");
@@ -130,7 +156,8 @@ async function startRun(agentName, limits) {
     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
-    control.adopt(run, resp.limits ?? {}, control.LIMITS, true);
+    // A null budget (unlimited) is taken only for a run whose code set none: a reply can't lift a budget from the code
+    control.adopt(run, resp.limits ?? {}, control.LIMITS, limits.budgetUsd == null);
     for (const n of resp.notices ?? []) {
         events.warnOnce(`${agentName}:${n.code}`, `${n.message ?? ""}${n.url ? ` ${n.url}` : ""}`);
     }
@@ -182,9 +209,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) {
@@ -240,7 +267,7 @@ function decide(run, resp) {
         control.apply(run, resp.commands);
         // The server is authoritative: adopt its totals and (on a breach) its current limits
         control.adopt(run, resp, control.TOTALS);
-        control.adopt(run, resp, control.LIMITS, true);
+        control.adopt(run, resp, control.LIMITS, !run.budgetInCode);
         // 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");
     }

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/run.d.ts

@@ -60,6 +60,8 @@ export declare class Run {
     reservedUsd: number;
     /** Model calls' worst-case costs (see precheck.ts), released at the next checkpoint once they finish. */
     holds: Hold[];
+    /** governed() set a budget: no server reply can make the run unlimited. */
+    budgetInCode: boolean;
     /** "hold": wait at a limit for someone to raise it (see InitOptions.onBreach). */
     onBreach: "hold" | null;
     private readonly abort;

package/dist/run.js

@@ -28,6 +28,8 @@ export class Run {
     reservedUsd = 0;
     /** Model calls' worst-case costs (see precheck.ts), released at the next checkpoint once they finish. */
     holds = [];
+    /** governed() set a budget: no server reply can make the run unlimited. */
+    budgetInCode = false;
     /** "hold": wait at a limit for someone to raise it (see InitOptions.onBreach). */
     onBreach = null;
     abort = new AbortController();

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.1";

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.1";

package/package.json

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