agentfences 0.6.0 → 0.7.0

package/README.md

@@ -107,6 +107,16 @@ const deploy = tool(deployImpl, { guard: true, timeoutS: 30 });
 
 A guarded or timed tool always returns a promise. What each part guarantees: [ENFORCEMENT.md](../ENFORCEMENT.md).
 
+**MCP tools** (from 0.7.0): wrap an MCP `Client` and every `callTool` is recorded, with no `tool()` per tool. The tools you name are guarded as above:
+
+```ts
+import { mcp } from "agentfences";
+
+mcp.wrap(client, { guard: ["send_email"], costUsd: { refund: (args) => args.amount as number } });
+```
+
+`guard: true` guards every tool, and `approve: [...]` names tools a person approves first. A result with `isError` is recorded as a failed call and still comes back to the agent.
+
 ## 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. Those are also how it checks a model call against the budget **before** it's sent, so the TypeScript SDK doesn't do that yet: a model call is checked afterwards, by `checkpoint()`, and a run can go over its budget by one call. Everything here follows the same server protocol ([PROTOCOL.md](../PROTOCOL.md)).

package/dist/index.d.ts

@@ -10,3 +10,4 @@ export { priceOf } from "./pricing.js";
 export type { CustomPrice } from "./pricing.js";
 export { FencesError, FencesAuthError, AgentQuarantined, FencesStop, ToolBlocked } from "./errors.js";
 export { VERSION } from "./version.js";
+export * as mcp from "./mcp.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export { requestApproval } from "./control.js";
 export { priceOf } from "./pricing.js";
 export { FencesError, FencesAuthError, AgentQuarantined, FencesStop, ToolBlocked } from "./errors.js";
 export { VERSION } from "./version.js";
+export * as mcp from "./mcp.js";

package/dist/mcp.d.ts

@@ -0,0 +1,40 @@
+type Args = Record<string, unknown>;
+interface CallToolClient {
+    callTool(params: {
+        name: string;
+        arguments?: Args;
+    }, ...rest: any[]): Promise<any>;
+}
+export interface WrapOptions {
+    /** Tool names to check with Fences before each call, or true for every tool. */
+    guard?: boolean | string[];
+    /** Per tool, what a call costs the run: a number or a function of its arguments. Such a tool is guarded. */
+    costUsd?: Record<string, number | ((args: Args) => number)>;
+    /** Tool names a person approves from the dashboard first. Such a tool is guarded. */
+    approve?: string[];
+}
+/** An MCP tool answered with isError: recorded as the call's error, the result still goes back. */
+export declare class MCPToolError extends Error {
+    readonly result: {
+        content?: {
+            text?: string;
+        }[];
+    };
+    constructor(result: {
+        content?: {
+            text?: string;
+        }[];
+    });
+}
+/**
+ * Record every tool call an MCP client makes, and guard the ones you name:
+ *
+ *     mcp.wrap(client, { guard: ["refund", "send_email"], costUsd: { refund: (a) => a.amount as number } });
+ *
+ * Patches client.callTool in place and returns the client. Each call inside a governed run
+ * becomes a tool span, with no tool() per tool. A result with isError counts as a failed call.
+ * Guarded tools go through the same check and settle as tool(fn, { guard: true }); a refused
+ * one throws ToolBlocked and never reaches the MCP server. Outside a governed run calls pass straight through.
+ */
+export declare function wrap<C extends CallToolClient>(client: C, options?: WrapOptions): C;
+export {};

package/dist/mcp.js

@@ -0,0 +1,46 @@
+import { getActiveRun } from "./core.js";
+import { argsSummary, callAsync } from "./tools.js";
+/** An MCP tool answered with isError: recorded as the call's error, the result still goes back. */
+export class MCPToolError extends Error {
+    result;
+    constructor(result) {
+        super((result.content ?? []).map((c) => c.text ?? "").join(" ").trim() || "isError");
+        this.result = result;
+        this.name = "MCPToolError";
+    }
+}
+/**
+ * Record every tool call an MCP client makes, and guard the ones you name:
+ *
+ *     mcp.wrap(client, { guard: ["refund", "send_email"], costUsd: { refund: (a) => a.amount as number } });
+ *
+ * Patches client.callTool in place and returns the client. Each call inside a governed run
+ * becomes a tool span, with no tool() per tool. A result with isError counts as a failed call.
+ * Guarded tools go through the same check and settle as tool(fn, { guard: true }); a refused
+ * one throws ToolBlocked and never reaches the MCP server. Outside a governed run calls pass straight through.
+ */
+export function wrap(client, options = {}) {
+    const original = client.callTool.bind(client), costs = options.costUsd ?? {}, approve = new Set(options.approve);
+    const named = new Set(Array.isArray(options.guard) ? options.guard : []);
+    client.callTool = async (params, ...rest) => {
+        const run = getActiveRun();
+        if (!run)
+            return original(params, ...rest);
+        const { name } = params, args = params.arguments ?? {}, c = Object.hasOwn(costs, name) ? costs[name] : undefined;
+        const guarded = options.guard === true || named.has(name) || c !== undefined || approve.has(name);
+        try {
+            return await callAsync(run, name, argsSummary([args]), guarded ? () => Number((typeof c === "function" ? c(args) : c) ?? 0) : null, approve.has(name), async () => {
+                const result = await original(params, ...rest);
+                if (result?.isError)
+                    throw new MCPToolError(result);
+                return result;
+            });
+        }
+        catch (e) {
+            if (e instanceof MCPToolError)
+                return e.result;
+            throw e;
+        }
+    };
+    return client;
+}

package/dist/tools.d.ts

@@ -1,5 +1,8 @@
+import { type Run } from "./core.js";
 /** `{"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>;
 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

@@ -108,6 +108,28 @@ async function settle(run, guardId, amount, error, failed) {
     run.costUsd += charged;
     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) {
+    const started = performance.now();
+    let gate = null;
+    try {
+        if (cost) {
+            const amount = cost();
+            gate = [await open(run, name, summary, amount, needsApproval), amount];
+        }
+        const out = await call();
+        recordToolCall(name, summary, started);
+        if (gate)
+            await settle(run, ...gate, undefined, false);
+        return out;
+    }
+    catch (e) {
+        recordToolCall(name, summary, started, e);
+        if (gate)
+            await settle(run, ...gate, e, true);
+        throw e;
+    }
+}
 function timed(p, timeoutS, name) {
     if (timeoutS === undefined)
         return p;
@@ -125,25 +147,8 @@ export function tool(fn, options = {}) {
             const run = getActiveRun();
             if (!run)
                 return timed(Promise.resolve().then(() => fn(...args)), options.timeoutS, name);
-            const summary = argsSummary(args), started = performance.now();
-            let gate = null;
-            try {
-                if (guarded) {
-                    const c = options.costUsd, amount = Number((typeof c === "function" ? c(...args) : c) ?? 0);
-                    gate = [await open(run, name, summary, amount, !!options.approve), amount];
-                }
-                const out = await timed(Promise.resolve().then(() => fn(...args)), options.timeoutS, name);
-                recordToolCall(name, summary, started);
-                if (gate)
-                    await settle(run, ...gate, undefined, false);
-                return out;
-            }
-            catch (e) {
-                recordToolCall(name, summary, started, e);
-                if (gate)
-                    await settle(run, ...gate, e, true);
-                throw e;
-            }
+            const c = options.costUsd;
+            return callAsync(run, name, argsSummary(args), guarded ? () => Number((typeof c === "function" ? c(...args) : c) ?? 0) : null, !!options.approve, () => timed(Promise.resolve().then(() => fn(...args)), options.timeoutS, name));
         };
     }
     return (...args) => {

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.6.0";
+export declare const VERSION = "0.7.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.6.0";
+export const VERSION = "0.7.0";

package/package.json

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