agentfences 0.9.0 → 0.9.1

package/README.md

@@ -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.js

@@ -94,8 +94,9 @@ export class FencesClient {
             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),
+            method: "POST", headers: this.headers, body: json, signal: AbortSignal.timeout(this.timeoutMs), redirect: "manual",
         });
         let resp;
         try {
@@ -115,6 +116,10 @@ export class FencesClient {
         }
         // 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/core.d.ts

@@ -55,6 +55,12 @@ export interface InitOptions {
      * 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

@@ -41,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 });
@@ -53,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 })");
@@ -116,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: ... }).");
@@ -133,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}` : ""}`);
     }
@@ -243,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/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/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.9.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.9.0";
+export const VERSION = "0.9.1";

package/package.json

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