@stigg/agent-sdk-js 0.7.5 → 0.7.7

package/README.md

@@ -154,7 +154,11 @@ closed, and conflating them is how an outage takes an application down.
 | --- | --- | --- | --- |
 | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/bedrock.svg" width="18" alt=""> | Amazon Bedrock | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/litellm.png" width="18" alt=""> | LiteLLM |
 | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/cloudflare.svg" width="18" alt=""> | Cloudflare Workers AI | <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/openrouter.svg" width="18" alt=""> | OpenRouter |
-| <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/databricks.svg" width="18" alt=""> | Databricks | | |
+| <img src="https://raw.githubusercontent.com/stiggio/stigg-agent-sdk-ts/main/docs/logos/databricks.svg" width="18" alt=""> | Databricks | | agentgateway (incl. Solo.io Enterprise) |
+
+A gateway called with plain HTTP rather than through an SDK is governed the same way:
+`stigg.wrapFetch({ baseUrl, recipe })` hands back a `fetch` that is checked and metered per
+request.
 
 **Orchestrators** — every agent in a graph checked and metered as itself, its tools included:
 
@@ -175,6 +179,7 @@ rather than handing back a client that quietly meters nothing.
 | You want to | Use |
 | --- | --- |
 | Govern a client | `stigg.wrap(client, { stiggContext })` |
+| Govern plain HTTP calls to a gateway | `stigg.wrapFetch({ baseUrl, recipe, stiggContext })` |
 | Gate without a client to wrap | `stigg.check(context)` |
 | Meter something you measured yourself | `stigg.report(context, metrics)` |
 | Give an agent its own budget | `stigg.register({ customerId, agentId, budget })` |

package/dist/bindings/client/core/wrap-client.d.ts

@@ -11,3 +11,13 @@ export declare function isGoverned(client: object): boolean;
  * for Cloudflare's `ai.run(model, inputs)`.
  */
 export declare function modelOf(...sources: unknown[]): string | undefined;
+/**
+ * How much to ask permission for, with the one answer a gate must never send.
+ *
+ * `estimate` is the application's own callback - a gateway recipe takes it as an option - and a
+ * negative one is worse than a wrong one: `remaining >= requestedUsage` is true at any balance,
+ * so an unaffordable call is granted by a budget that had nothing left. `NaN` and `Infinity` fail
+ * the same comparison in the other direction. Zero and fractions are left alone: a credit
+ * currency is spent in fractions, and asking for nothing is a legitimate "may I at all".
+ */
+export declare function requestedUnits(estimate: (params: any) => number, params: any): number;

package/dist/bindings/client/core/wrap-client.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.wrapClient = wrapClient;
 exports.isGoverned = isGoverned;
 exports.modelOf = modelOf;
+exports.requestedUnits = requestedUnits;
 /**
  * The client binding: a drop-in wrapper that gates before the call and meters after it.
  *

package/dist/bindings/client/gateways/agentgateway/agentgateway-recipe.d.ts

@@ -0,0 +1,10 @@
+import { AGENTGATEWAY_METRICS } from '../../../shared/token-usage';
+import type { AgentgatewayRecipeOptions } from './types';
+import type { ClientRecipe, MetricsFor, MetricsOf } from '../../core/types';
+type AgentgatewayMetric = (typeof AGENTGATEWAY_METRICS)[number];
+export declare function agentgatewayRecipe(options?: AgentgatewayRecipeOptions): ClientRecipe<AgentgatewayMetric>;
+/** One of the metric names agentgateway can report, across every wire it serves. */
+export type AgentgatewayMetricName = MetricsOf<ReturnType<typeof agentgatewayRecipe>>;
+/** What a mapper reads off a call through agentgateway: those names, each possibly absent. */
+export type AgentgatewayMetrics = MetricsFor<ReturnType<typeof agentgatewayRecipe>>;
+export {};

package/dist/bindings/client/gateways/agentgateway/agentgateway-recipe.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentgatewayRecipe = agentgatewayRecipe;
+/**
+ * The agentgateway recipe - the open-source AI gateway (and the builds on it: Solo.io's enterprise
+ * edition, Gloo AI Gateway), a gateway you call that states no price.
+ *
+ * Its OpenAI routes fit `openAIRecipe` by shape and its Anthropic route fits `anthropicRecipe`, so
+ * the recipe has to justify itself, and it does on two counts:
+ *
+ *  - **A vendor name of its own.** Without this, traffic through the gateway meters as `openai.*`
+ *    or `anthropic.*` - indistinguishable from a direct call, so no meter and no per-provider
+ *    budget can tell the gateway's traffic apart. Worse on the Anthropic wire: `anthropicRecipe`
+ *    has no base-URL guard, so an `Anthropic` client pointed here would be claimed by it and
+ *    reported as direct Anthropic traffic.
+ *  - **The model that actually served.** The gateway can rewrite the model a request named - an
+ *    alias, a provider prefix, a failover priority group - and the response body names the one
+ *    that answered. The bare recipes drop it; this one attributes it.
+ *
+ * One vendor across every wire, because the gateway is one deployment whichever client reached it,
+ * and the wire is already in the event name (`agentgateway.chat.completions.create` against
+ * `agentgateway.messages.create`). The gateway translates where it needs to, so each route reports
+ * in the vocabulary of the wire it answered on - OpenAI's names on the OpenAI routes, Anthropic's
+ * on Messages - and `metrics` is the union, which is what `metrics` is defined to be.
+ *
+ * No `cost`, and that is the defining fact rather than an oversight. The gateway is self-hosted and
+ * states no price on any response; whatever the upstream charged is invoiced by the upstream, out
+ * of band. Never declare a metric the platform cannot report.
+ *
+ * Self-hosted, so there is no public hostname to recognise. The base URL handed to
+ * `agentgatewayRecipe({ baseUrl })` is the reliable discriminator; without one the matcher falls
+ * back to a guess on the hostname - see {@link isAgentgateway} for what it claims.
+ *
+ * The same surfaces govern raw HTTP too: `stigg.wrapFetch` routes a request by its path to the
+ * method here that names it, so a `fetch` to the gateway is metered by exactly these readers.
+ */
+const meter_stream_1 = require("../../../shared/meter-stream");
+const token_usage_1 = require("../../../shared/token-usage");
+const base_url_1 = require("../../../shared/base-url");
+const openai_recipe_1 = require("../../providers/openai/openai-recipe");
+const anthropic_recipe_1 = require("../../providers/anthropic/anthropic-recipe");
+const types_1 = require("../../../../types");
+/**
+ * The name that identifies the gateway in an ordinary deployment: the Kubernetes service or
+ * namespace (`agentgateway-proxy.agentgateway-system.svc`) or a hostname an operator chose to say
+ * so with (`agentgateway.acme.internal`). A dot-separated label matches when it *is* this name or
+ * *starts with* it and a hyphen - which is how a default install names both its service and its
+ * namespace. Never a substring or a later segment: `myagentgateway` and `my-agentgateway` are
+ * somebody else's host.
+ *
+ * Only this one. `solo` and `gloo` are words a customer picks for their own resources
+ * (`solo-prod.openai.azure.com`, `litellm.gloo-system.svc`), and this recipe sits ahead of
+ * LiteLLM, Databricks and OpenAI - so guessing on them would move those calls to `agentgateway.*`
+ * and out of the meters counting them. Solo's and Gloo's builds name the gateway by `baseUrl`.
+ */
+const HOST_LABEL = 'agentgateway';
+/** What only the gateway knows, folded onto whatever the wire's own reader produced. */
+function withGatewayFacts(measured, result, modelDimension) {
+    const served = typeof result?.model === 'string' ? result.model : undefined;
+    return {
+        ...measured,
+        dimensions: served
+            ? { ...measured.dimensions, [modelDimension]: served }
+            : measured.dimensions,
+        // The upstream's completion id, carried back through the gateway. It is what a replayed
+        // response repeats, which a local step counter cannot be.
+        idempotencyKey: measured.idempotencyKey ?? (typeof result?.id === 'string' ? result.id : undefined),
+    };
+}
+function agentgatewayRecipe(options = {}) {
+    const estimate = options.estimate ?? (() => 1);
+    const modelDimension = options.modelDimension ?? 'model';
+    /**
+     * One wire's surface, wrapped.
+     *
+     * The wire recipes' own extractors are reused rather than reimplemented: the gateway answers in
+     * that wire's shape, so that wire's reader is by definition the right one - and Anthropic's
+     * streamed usage in particular accumulates across two event types, which is not logic worth
+     * having a second copy of.
+     */
+    const surfaceOf = (base) => ({
+        // Spread first so anything the base declares and this wrapper does not know about - like
+        // `contextArg` - survives being wrapped.
+        ...base,
+        estimate,
+        extractUsage: (result, response) => {
+            const measured = base.extractUsage?.(result, response);
+            return measured === undefined ? undefined : withGatewayFacts((0, types_1.toMeasurement)(measured), result, modelDimension);
+        },
+        attachStream: base.attachStream
+            ? (stream, ingest, response) => {
+                // A second tap, purely for attribution: the wire readers carry out counters and nothing
+                // else. Each wire states the model in its own envelope - Anthropic on
+                // `message_start.message`, the Responses API on `response`, Chat Completions at the chunk
+                // root. `meterStream` captures what it patches before patching, so two observers each
+                // see every chunk exactly once.
+                let seen = {};
+                (0, meter_stream_1.meterStream)(stream, (chunk) => {
+                    const envelope = chunk?.message ?? chunk?.response ?? chunk;
+                    if (envelope?.model)
+                        seen = { ...seen, model: envelope.model };
+                    if (envelope?.id)
+                        seen = { ...seen, id: envelope.id };
+                }, () => { });
+                base.attachStream(stream, (measurement) => ingest(withGatewayFacts((0, types_1.toMeasurement)(measurement), seen, modelDimension)), response);
+            }
+            : undefined,
+    });
+    return {
+        vendor: 'agentgateway',
+        metrics: token_usage_1.AGENTGATEWAY_METRICS,
+        // Every wire here spells its total `total_tokens` - Anthropic's is computed from its disjoint
+        // counters by the reader this reuses, OpenAI's is stated.
+        totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+        // The base URL decides, because shape cannot: an `OpenAI` client and an `Anthropic` client
+        // pointed at the gateway look exactly like direct clients.
+        matches: (client) => isAgentgateway(client, options.baseUrl) && (openai_recipe_1.openAIRecipe.matches(client) || anthropic_recipe_1.anthropicRecipe.matches(client)),
+        // Every wire it serves. A surface left undeclared here is not metered by something else - it
+        // is ungated, because this recipe is matched ahead of both of the ones that would have claimed
+        // it.
+        methods: [...openai_recipe_1.openAIRecipe.methods.map(surfaceOf), ...anthropic_recipe_1.anthropicRecipe.methods.map(surfaceOf)],
+    };
+}
+/**
+ * `baseURL` is a public field on both clients. Shape cannot answer this and a wrong guess silently
+ * changes which vendor an event names, so the check is narrow on purpose.
+ *
+ * Given a `baseUrl`, the endpoint is compared one path segment at a time, so `.../v1` cannot claim
+ * `.../v10`. Without one, the hostname is split on dots and claimed only when a label is, or starts
+ * with, `agentgateway-` - the name a default install puts in its service and namespace.
+ * An unrelated endpoint whose hostname carries one of those labels is claimed too and reports
+ * under `agentgateway.*`; name `recipe: openAIRecipe` (or `anthropicRecipe`) at `wrap` to settle it.
+ */
+function isAgentgateway(client, baseUrl) {
+    const clientBase = (0, base_url_1.baseUrlOf)(client);
+    if (clientBase === undefined)
+        return false;
+    if (baseUrl)
+        return (0, base_url_1.withinBaseUrl)(baseUrl, clientBase);
+    return (0, base_url_1.hostOf)(clientBase)
+        .split('.')
+        .some((label) => label.split('-')[0] === HOST_LABEL);
+}

package/dist/bindings/client/gateways/agentgateway/types.d.ts

@@ -0,0 +1,24 @@
+export type AgentgatewayRecipeOptions = {
+    /**
+     * How much to ask permission for before the call, in whatever unit `meter` bills.
+     *
+     * The default asks for 1 - "is there any budget left at all?" - and lets the ingest afterwards
+     * settle the balance. No `unitsPer…` beside it, because there is nothing fractional to
+     * denominate: the gateway is self-hosted and puts no price on any response, so a run here bills
+     * token counters, which arrive whole.
+     */
+    estimate?: (params: any) => number;
+    /**
+     * Dimension the model that actually served is attributed to, so routing drift is visible in
+     * Stigg. The gateway can rewrite the model a request named - an alias, a provider prefix, a
+     * failover priority group - and the response body names the one that answered.
+     */
+    modelDimension?: string;
+    /**
+     * The gateway this recipe is for. agentgateway is self-hosted - a proxy in your own cluster - so
+     * unlike a public gateway there is no fixed host to recognise. Give it the same base URL the
+     * client was built with, and `matches` compares against exactly that. Without it the matcher
+     * falls back to a guess on the hostname; see the recipe for what that guess claims.
+     */
+    baseUrl?: string;
+};

package/dist/bindings/client/gateways/agentgateway/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/bindings/fetch/types.d.ts

@@ -0,0 +1,40 @@
+import type { ClientRecipe } from '../client/core/types';
+import type { StiggContext } from '../../core/context';
+import type { SessionHooks } from '../../core/session';
+import type { ClientContext, ClientGovernance } from '../../types';
+/** Whatever `fetch` the application already uses. Defaults to the global one. */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** `fetch`'s own second argument, plus the per-call context a wrapped client reads off its params. */
+export type GovernedRequestInit = RequestInit & {
+    /** Overrides the context `wrapFetch` was given, for this request only. Never sent on the wire. */
+    stiggContext?: StiggContext;
+};
+export type FetchOptions = {
+    /**
+     * The endpoint whose calls are governed - the gateway's base URL. A request outside it, or to a
+     * path no recipe method answers, goes through untouched: this is a `fetch`, and an application
+     * reaches more than its gateway with one.
+     */
+    baseUrl: string;
+    /**
+     * What the responses mean. Required, unlike at `wrap`: there is no client object to recognise a
+     * vendor by, and guessing from a URL is exactly the decision that bills the wrong party. Any
+     * recipe over the OpenAI or Anthropic wire works - `agentgatewayRecipe()`, `litellmRecipe()`,
+     * `openAIRecipe` - because the request path says which of its methods a call is.
+     */
+    recipe: ClientRecipe;
+    /** The `fetch` to govern. Defaults to `globalThis.fetch`. */
+    fetch?: FetchLike;
+    /** Everything this fetch reports back while it works. See {@link SessionHooks}. */
+    hooks?: SessionHooks;
+    /** The default context for every governed request. Any request may override it. */
+    stiggContext?: ClientContext;
+};
+/**
+ * A `fetch` bound to this environment: a request to a governed route is checked before it leaves
+ * and metered from its response, exactly as the same call through a wrapped SDK client would be.
+ */
+export type GovernedFetch = ((input: string | URL | Request, init?: GovernedRequestInit) => Promise<Response>) & {
+    /** What this fetch did, and what is still in flight. The same handle a wrapped client carries. */
+    readonly stigg: ClientGovernance;
+};

package/dist/bindings/fetch/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/bindings/fetch/wrap-fetch.d.ts

@@ -0,0 +1,5 @@
+import { type ResolvedContext } from '../../core/context';
+import type { GovernanceSession } from '../../core/session';
+import { type ClientRecipe } from '../client/core/types';
+import type { FetchLike, GovernedRequestInit } from './types';
+export declare function wrapFetch(fetchFn: FetchLike, recipe: ClientRecipe, baseUrl: string, session: GovernanceSession, base: ResolvedContext): (input: string | URL | Request, init?: GovernedRequestInit) => Promise<Response>;

package/dist/bindings/fetch/wrap-fetch.js

@@ -0,0 +1,316 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapFetch = wrapFetch;
+/**
+ * The fetch binding: the client binding's gate and meter, for a call made with plain HTTP.
+ *
+ * A gateway is often called with no SDK at all - a service posts JSON to `/v1/chat/completions`
+ * and reads the reply - and `wrap` has nothing to hold on to there. The proxy binding does not
+ * help either: it ingests what a proxy *you* operate observed, and a third-party gateway never
+ * calls Stigg. So this wraps the one object such a caller does hold, its `fetch`.
+ *
+ * Nothing about reading a response is new here. A request is matched to a recipe method by its
+ * path - `/chat/completions` is `chat.completions.create` on every OpenAI-wire SDK, `/messages`
+ * is Anthropic's `messages.create` - and from then on it is that method's call: the same
+ * `estimate`, the same `extractUsage` on a JSON reply, the same `attachStream` on an SSE one, and
+ * the same event name. A recipe is written once and governs both ways of reaching its vendor.
+ *
+ * Three things differ from a wrapped client, all because a `fetch` is a lower-level door:
+ *
+ *  - **Only routes the recipe declares are governed.** Anything else - another host, `GET
+ *    /models`, embeddings - passes through untouched. A `fetch` reaches more than one endpoint,
+ *    and refusing or metering a call nothing describes would be guessing.
+ *  - **A stream is metered as the caller reads it.** The body is observed in place, not teed, so
+ *    nothing is buffered on the caller's behalf - and, as with an SDK stream, a body nobody reads
+ *    to the end meters what was read.
+ *  - **A streamed reply comes back as a new `Response`** around the observed body, carrying the
+ *    original status and headers. `url` and `redirected` are not carried, because a constructed
+ *    `Response` cannot have them.
+ */
+const errors_1 = require("../../errors");
+const context_1 = require("../../core/context");
+const types_1 = require("../../types");
+const base_url_1 = require("../shared/base-url");
+const types_2 = require("../client/core/types");
+const wrap_client_1 = require("../client/core/wrap-client");
+/**
+ * Where each SDK method posts. The same on every vendor that speaks the wire - which is why a
+ * gateway can be OpenAI-compatible at all - so it lives here once rather than on every recipe.
+ */
+const ROUTES = {
+    'chat.completions.create': '/chat/completions',
+    'responses.create': '/responses',
+    'messages.create': '/messages',
+};
+function wrapFetch(fetchFn, recipe, baseUrl, session, base) {
+    const routes = recipe.methods.flatMap((method) => {
+        const suffix = ROUTES[method.path.join('.')];
+        return suffix ? [{ suffix, method, eventName: (0, types_2.eventNameFor)(recipe, method) }] : [];
+    });
+    // The same refusal `wrap` makes for a recipe that gates nothing on the client it was handed: a
+    // fetch that looks governed and meters nothing is worse than an error now.
+    if (routes.length === 0) {
+        throw new Error(`The ${recipe.vendor} recipe gates ${recipe.methods.map((m) => m.path.join('.')).join(', ')}, and none of ` +
+            `those has an HTTP route this binding knows (${Object.values(ROUTES).join(', ')}). Nothing would be ` +
+            'checked or metered, so this is refused rather than handed back looking governed.');
+    }
+    // A relative or malformed one matches nothing, so every request would pass through ungoverned.
+    if (!URL.canParse(baseUrl))
+        throw new Error(`wrapFetch needs an absolute base URL, got "${baseUrl}".`);
+    return async function governedFetch(input, init) {
+        // Taken off before anything else sees the request, governed or not - `fetch` ignores an
+        // unknown field today, but it is not this binding's to forward.
+        let requestInit = init;
+        let override;
+        // Presence, not value: an explicit `stiggContext: undefined` is still not the wire's.
+        if (init && 'stiggContext' in init) {
+            const { stiggContext, ...rest } = init;
+            requestInit = rest;
+            override = stiggContext;
+        }
+        const route = routeOf(input, requestInit, baseUrl, routes);
+        if (!route)
+            return fetchFn(input, requestInit);
+        const params = await paramsOf(input, requestInit);
+        if (route.method.passthrough?.(params, undefined))
+            return fetchFn(input, requestInit);
+        const defaults = base.eventName ? base : { ...base, eventName: { name: route.eventName } };
+        // Presence, as `wrap` tests it: a `null` override is validated and refused, not ignored.
+        const context = override !== undefined ? (0, context_1.overrideContext)(defaults, override) : defaults;
+        if (!context.customerId)
+            throw (0, context_1.noCustomer)();
+        if ((0, context_1.isEnforced)(context)) {
+            const decision = await session.check(context, (0, wrap_client_1.requestedUnits)(route.method.estimate ?? (() => 1), params));
+            if (!decision.hasAccess)
+                throw new errors_1.AccessDeniedError(decision);
+        }
+        const startedAt = Date.now();
+        const response = await fetchFn(input, requestInit);
+        // An error body carries no usage, and the gateway billed nothing for a refusal of its own.
+        if (!response.ok)
+            return response;
+        let data;
+        let served;
+        const ingest = (measured) => {
+            const measurement = (0, types_1.toMeasurement)(measured);
+            // What an AUDR record names and the measurement does not, as `wrap` adds it: the reply's
+            // model before the request's, since the gateway can serve another.
+            const traced = {
+                ...context,
+                audr: { provider: recipe.vendor, model: (0, wrap_client_1.modelOf)(served, data, params), startedAt },
+            };
+            void session.ingestMeasurement(traced, measurement);
+            if (measurement.incomplete)
+                session.failedToMeasure(context, new Error(measurement.incomplete));
+        };
+        try {
+            if (isEventStream(response))
+                return meteredStream(response, route.method, ingest, (err) => session.failedToMeasure(context, err), 
+                // The model that served, from the first event that names it - a Chat Completions chunk,
+                // Anthropic's `message_start`, a Responses event - so a stream's record matches a reply's.
+                (event) => (served ??= (0, wrap_client_1.modelOf)(event, event?.message, event?.response)));
+            // A copy, read here, so the caller gets a body nobody has touched. Awaited rather than left
+            // running, so the ingest is in flight - and `flush()` waits for it - by the time the caller
+            // has the response.
+            data = await response.clone().json();
+            const measured = route.method.extractUsage?.(data, response);
+            if (measured)
+                ingest(measured);
+        }
+        catch (err) {
+            // The gateway already answered. A reply this cannot read is a metering failure, not the
+            // caller's - turning it into a rejection would fail a request that worked. A parse error
+            // quotes the body it choked on, so it is replaced rather than handed to the logger.
+            session.failedToMeasure(context, err instanceof SyntaxError
+                ? new Error('The gateway’s reply was not JSON, so its usage could not be read.')
+                : err);
+        }
+        return response;
+    };
+}
+/** The route a request takes, or undefined for one this binding leaves alone. */
+function routeOf(input, init, baseUrl, routes) {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    if (!(0, base_url_1.withinBaseUrl)(baseUrl, url))
+        return undefined;
+    const method = (init?.method ?? (typeof input === 'object' && 'method' in input ? input.method : 'GET')).toUpperCase();
+    if (method !== 'POST')
+        return undefined;
+    // Read from the base URL down, so `/messages` is the gateway's own route and not the tail of
+    // `/v1/threads/{id}/messages` (OpenAI Assistants), and `/messages/count_tokens` - free, and not
+    // generation - is not one either. An optional `/v1`, for a base URL given without it.
+    const path = (0, base_url_1.pathOf)(url).slice((0, base_url_1.pathOf)(baseUrl).length);
+    return routes.find((route) => path === route.suffix || path === `/v1${route.suffix}`);
+}
+/**
+ * The request's JSON, which is what a recipe's `estimate` and `passthrough` read - the same object
+ * an SDK method would have been handed. An empty object for a body that is not JSON text (a stream,
+ * form data, text that does not parse), so an estimate like `(p) => p.max_tokens` falls back to
+ * its default instead of throwing - and failing a request before it is sent.
+ */
+async function paramsOf(input, init) {
+    let text;
+    const body = init?.body;
+    if (typeof body === 'string')
+        text = body;
+    else if (body instanceof ArrayBuffer || ArrayBuffer.isView(body))
+        text = new TextDecoder().decode(body);
+    // A Blob is immutable, so reading it here leaves the body `fetch` sends untouched.
+    else if (body instanceof Blob)
+        text = await body.text();
+    else if (body == null && input instanceof Request)
+        text = await input.clone().text();
+    if (!text)
+        return {};
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+const isEventStream = (response) => 
+// Media types are case-insensitive, and a JSON parse of a live stream would wait for it to end.
+(response.headers.get('content-type') ?? '').toLowerCase().includes('text/event-stream') && response.body !== null;
+/**
+ * The reply, with its body observed in place.
+ *
+ * The recipe's stream reader is written against an async iterable of parsed events - what an SDK
+ * stream yields - so this parses the SSE as the caller reads it and feeds a channel the reader is
+ * attached to. Every recipe's existing reader works unchanged: Anthropic accumulating across two
+ * event types, Chat Completions reading the last chunk, Responses its completion event.
+ */
+function meteredStream(response, method, ingest, failed, seen) {
+    const events = channel();
+    if (!method.attachStream)
+        return response;
+    method.attachStream(events, ingest, response);
+    // Drives the iterator the recipe patched, which is what runs its accounting. Started by the
+    // first event rather than up front, because the recipe reads a started stream that closes as a
+    // zero - and a body cancelled before anything was read measured nothing, not nothing used.
+    let consumed;
+    const consume = () => (consumed ??= (async () => {
+        try {
+            for await (const _event of events)
+                void _event;
+        }
+        catch (err) {
+            failed(err);
+        }
+    })());
+    const body = observeSse(response.body, (event) => {
+        seen(event);
+        events.push(event);
+        void consume();
+    }, () => {
+        events.close();
+        return consumed;
+    });
+    return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+/** A one-reader queue: pushed to as the body is read, drained by the recipe's stream reader. */
+function channel() {
+    const queue = [];
+    let wake;
+    let closed = false;
+    return {
+        push: (event) => {
+            queue.push(event);
+            wake?.();
+        },
+        close: () => {
+            closed = true;
+            wake?.();
+        },
+        async *[Symbol.asyncIterator]() {
+            while (true) {
+                if (queue.length) {
+                    yield queue.shift();
+                    continue;
+                }
+                if (closed)
+                    return;
+                await new Promise((resolve) => (wake = resolve));
+                wake = undefined;
+            }
+        },
+    };
+}
+/**
+ * Passes the bytes through unchanged and hands each complete SSE event's `data` to `onEvent`,
+ * parsed. `[DONE]` and anything that is not JSON are skipped - they carry no usage. `onEnd` fires
+ * once, however the body ends: run out, errored, or cancelled by the caller - and what it returns
+ * is awaited before the caller sees that end, so the final ingest is pending, and `flush()` waits
+ * for it, by the time `response.text()` resolves or rejects, or `cancel()` returns.
+ */
+function observeSse(source, onEvent, onEnd) {
+    const decoder = new TextDecoder();
+    const reader = source.getReader();
+    let buffer = '';
+    let ended = false;
+    const end = () => {
+        if (ended)
+            return undefined;
+        ended = true;
+        return onEnd();
+    };
+    const emit = (block) => {
+        const data = block
+            .split('\n')
+            .filter((line) => line.startsWith('data:'))
+            .map((line) => line.slice(5).replace(/^ /, ''))
+            .join('\n');
+        if (!data || data === '[DONE]')
+            return;
+        try {
+            onEvent(JSON.parse(data));
+        }
+        catch {
+            // Not an event this binding can read; the caller still gets the bytes.
+        }
+    };
+    const drain = (final) => {
+        // A `\r` at the very end may be the first half of a `\r\n` split across two reads, and
+        // normalising it early would turn that one line break into an event boundary.
+        buffer = buffer.replace(final ? /\r\n?/g : /\r\n|\r(?=[\s\S])/g, '\n');
+        let at;
+        while ((at = buffer.indexOf('\n\n')) !== -1) {
+            emit(buffer.slice(0, at));
+            buffer = buffer.slice(at + 2);
+        }
+        if (final && buffer.trim()) {
+            emit(buffer);
+            buffer = '';
+        }
+    };
+    // A high-water mark of zero, so the source is read only when the caller asks: nothing is metered
+    // ahead of what the caller has, and a cancel stops at what was handed over.
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const { value, done } = await reader.read();
+                if (done) {
+                    buffer += decoder.decode();
+                    drain(true);
+                    await end();
+                    controller.close();
+                    return;
+                }
+                buffer += decoder.decode(value, { stream: true });
+                drain(false);
+                controller.enqueue(value);
+            }
+            catch (err) {
+                // Awaited, as on a body that ran out, so what was read is pending before the caller hears.
+                await end();
+                controller.error(err);
+            }
+        },
+        async cancel(reason) {
+            const ended = end();
+            await reader.cancel(reason);
+            await ended;
+        },
+    }, { highWaterMark: 0 });
+}

package/dist/bindings/shared/token-usage.d.ts

@@ -155,6 +155,14 @@ export declare const GATEWAY_METRICS: readonly ["prompt_tokens", "completion_tok
  * asynchronously.
  */
 export declare const CLOUDFLARE_METRICS: readonly ["prompt_tokens", "completion_tokens", "input_tokens", "output_tokens", "cached_tokens", "total_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+/**
+ * agentgateway, which answers on the OpenAI routes and on Anthropic Messages - each in its
+ * own wire's vocabulary, so the union of the two, like Cloudflare's.
+ *
+ * No `cost`: the gateway is self-hosted and states no price on any response.
+ * Whatever the upstream charged is invoiced by the upstream, out of band.
+ */
+export declare const AGENTGATEWAY_METRICS: readonly ["prompt_tokens", "completion_tokens", "input_tokens", "output_tokens", "cached_tokens", "total_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
 /**
  * Bedrock's five, under its own names and with no price among them.
  *

package/dist/bindings/shared/token-usage.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizedMetrics = exports.addMetrics = exports.METRIC_PATHS = exports.metricNamesMatchPaths = exports.COMPUTED_TOTALS = exports.metricName = exports.WORKERS_AI_METRICS = exports.WORKERS_AI_PATHS = exports.DATABRICKS_QUERY_METRIC_NAME_MAP = exports.DATABRICKS_METRICS = exports.DATABRICKS_RESPONSES_PATHS = exports.DATABRICKS_PATHS = exports.BEDROCK_METRICS = exports.BEDROCK_PATHS = exports.CLOUDFLARE_METRICS = exports.GATEWAY_METRICS = exports.OPENAI_METRICS = exports.OLLAMA_METRICS = exports.OLLAMA_COMPONENT_METRICS = exports.TYPESAFE_METRICS = exports.TYPESAFE_COMPONENT_METRICS = exports.MISTRAL_METRICS = exports.MISTRAL_METRIC_NAME_MAP = exports.OPENAI_RESPONSES_METRICS = exports.OPENAI_CHAT_METRICS = exports.GEMINI_COMPONENT_METRICS = exports.GEMINI_METRICS = exports.ANTHROPIC_METRICS = exports.ANTHROPIC_COMPONENT_METRICS = exports.TOTAL_TOKENS = exports.addTokenUsage = void 0;
+exports.normalizedMetrics = exports.addMetrics = exports.METRIC_PATHS = exports.metricNamesMatchPaths = exports.COMPUTED_TOTALS = exports.metricName = exports.WORKERS_AI_METRICS = exports.WORKERS_AI_PATHS = exports.DATABRICKS_QUERY_METRIC_NAME_MAP = exports.DATABRICKS_METRICS = exports.DATABRICKS_RESPONSES_PATHS = exports.DATABRICKS_PATHS = exports.BEDROCK_METRICS = exports.BEDROCK_PATHS = exports.AGENTGATEWAY_METRICS = exports.CLOUDFLARE_METRICS = exports.GATEWAY_METRICS = exports.OPENAI_METRICS = exports.OLLAMA_METRICS = exports.OLLAMA_COMPONENT_METRICS = exports.TYPESAFE_METRICS = exports.TYPESAFE_COMPONENT_METRICS = exports.MISTRAL_METRICS = exports.MISTRAL_METRIC_NAME_MAP = exports.OPENAI_RESPONSES_METRICS = exports.OPENAI_CHAT_METRICS = exports.GEMINI_COMPONENT_METRICS = exports.GEMINI_METRICS = exports.ANTHROPIC_METRICS = exports.ANTHROPIC_COMPONENT_METRICS = exports.TOTAL_TOKENS = exports.addTokenUsage = void 0;
 exports.fromFlatTokenUsage = fromFlatTokenUsage;
 exports.fromOpenAIUsage = fromOpenAIUsage;
 exports.fromResponsesUsage = fromResponsesUsage;
@@ -425,6 +425,18 @@ exports.CLOUDFLARE_METRICS = [
     'cache_read_input_tokens',
     'cache_creation_input_tokens',
 ];
+/**
+ * agentgateway, which answers on the OpenAI routes and on Anthropic Messages - each in its
+ * own wire's vocabulary, so the union of the two, like Cloudflare's.
+ *
+ * No `cost`: the gateway is self-hosted and states no price on any response.
+ * Whatever the upstream charged is invoiced by the upstream, out of band.
+ */
+exports.AGENTGATEWAY_METRICS = [
+    ...exports.OPENAI_METRICS,
+    'cache_read_input_tokens',
+    'cache_creation_input_tokens',
+];
 /**
  * Bedrock's five, under its own names and with no price among them.
  *

package/dist/engine/engine.d.ts

@@ -122,9 +122,14 @@ export type EntityPlacement = {
     /**
      * Set the budget only when the assignment does not exist yet. An existing one keeps its limit
      * and cadence, so a raise made in the dashboard survives the next run. Mutually exclusive with
-     * `usageLimit` - it costs one extra read, which is why it is not the default.
+     * `usageLimit` - it costs one extra read, which is why a number is never seeded unless asked for.
+     *
+     * `null` seeds an unlimited assignment - the metering-only one, which puts the agent in the tree
+     * and tracks its usage without its own assignment refusing it. It is what a budget with no limit
+     * sends, so that case pays the read on every call. Unlike a numeric seed it still applies the
+     * caller's `cadence` to an existing assignment, as a budget with no limit always has.
      */
-    usageLimitOnCreate?: number;
+    usageLimitOnCreate?: number | null;
     cadence?: string;
     /** The entities the budget is scoped to - its own assignment beside the agent's whole one. */
     scopeEntityIds?: string[];

package/dist/engine/rest-governance-engine.js

@@ -16,6 +16,8 @@ const errors_1 = require("../errors");
 const types_1 = require("../types");
 const sdk_identity_1 = require("../sdk-identity");
 const report_1 = require("./report");
+/** The window an unlimited assignment is created with when the caller named none. */
+const TRACKING_CADENCE = 'P1M';
 /** The governance check endpoint is `/api/v1-beta/` and flagged experimental. */
 class RestGovernanceEngine {
     /**
@@ -116,11 +118,16 @@ class RestGovernanceEngine {
         const scope = scopeOf(placement.scopeEntityIds);
         // Every page: the one with this scope can sit past the first, and missing it would overwrite
         // an admin's limit with the seed.
+        const tracking = placement.usageLimitOnCreate === null;
         for await (const row of this.client.v1Beta.customers.assignments.list(customerId, { entityId, ...capability })) {
-            // Already assigned: leave the limit and its window exactly as they are.
+            // Already assigned: leave the limit and its window exactly as they are - except that a
+            // metering-only call still moves the window it named, as a budget with no limit always did.
             if (scopeOf(row.scopeEntityIds) === scope)
-                return {};
+                return tracking ? cadence : {};
         }
+        // Governance requires a window on create, and a metering-only caller has no reason to pick one.
+        if (tracking)
+            return { usageLimit: null, cadence: placement.cadence ?? TRACKING_CADENCE };
         return { usageLimit: placement.usageLimitOnCreate, ...cadence };
     }
     async check(customerId, { entitlement, requestedUsage, dimensions }) {

package/dist/index.d.ts

@@ -57,6 +57,10 @@ export type { BedrockRecipeOptions } from './bindings/client/gateways/bedrock/ty
 export { cloudflareRecipe } from './bindings/client/gateways/cloudflare/cloudflare-recipe';
 export type { CloudflareMetricName, CloudflareMetrics } from './bindings/client/gateways/cloudflare/cloudflare-recipe';
 export type { CloudflareRecipeOptions } from './bindings/client/gateways/cloudflare/types';
+export { agentgatewayRecipe } from './bindings/client/gateways/agentgateway/agentgateway-recipe';
+export type { AgentgatewayMetricName, AgentgatewayMetrics, } from './bindings/client/gateways/agentgateway/agentgateway-recipe';
+export type { AgentgatewayRecipeOptions } from './bindings/client/gateways/agentgateway/types';
+export type { FetchLike, FetchOptions, GovernedFetch, GovernedRequestInit } from './bindings/fetch/types';
 export { typesafeRecipe, estimateFromState } from './bindings/client/providers/typesafe/typesafe-recipe';
 export type { TypeSafeMetric, TypeSafeMetrics } from './bindings/client/providers/typesafe/typesafe-recipe';
 export { weightedMetrics } from './bindings/shared/weighted-metrics';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeUsage = exports.normalizedMetrics = exports.stiggVercelMiddleware = exports.weightedMetrics = exports.estimateFromState = exports.typesafeRecipe = exports.cloudflareRecipe = exports.bedrockRecipe = exports.databricksExternalRecipe = exports.databricksRecipe = exports.ollamaRecipe = exports.mistralRecipe = exports.groqRecipe = exports.litellmRecipe = exports.openrouterRecipe = exports.estimateFromMaxOutputTokens = exports.geminiChatRecipe = exports.geminiRecipe = exports.openAIRecipe = exports.estimateFromMaxTokens = exports.anthropicRecipe = exports.hasMethod = exports.createClientRegistry = exports.wrapClient = exports.toMeasurement = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = exports.emptyTokenUsage = exports.vendorMetrics = exports.unitsPerTokens = exports.looksLikeGovernanceNotEnabled = exports.isGovernanceNotEnabled = exports.isAccessDenied = exports.isEngineError = exports.GovernanceNotEnabledError = exports.AccessDeniedError = exports.EngineError = exports.STIGG_TRACER_NAME = exports.noopLogger = exports.consoleLogger = exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = exports.remedyMessage = exports.describeDecision = exports.flattenRaw = exports.RAW_PREFIX = exports.StiggAgentSDK = void 0;
+exports.normalizeUsage = exports.normalizedMetrics = exports.stiggVercelMiddleware = exports.weightedMetrics = exports.estimateFromState = exports.typesafeRecipe = exports.agentgatewayRecipe = exports.cloudflareRecipe = exports.bedrockRecipe = exports.databricksExternalRecipe = exports.databricksRecipe = exports.ollamaRecipe = exports.mistralRecipe = exports.groqRecipe = exports.litellmRecipe = exports.openrouterRecipe = exports.estimateFromMaxOutputTokens = exports.geminiChatRecipe = exports.geminiRecipe = exports.openAIRecipe = exports.estimateFromMaxTokens = exports.anthropicRecipe = exports.hasMethod = exports.createClientRegistry = exports.wrapClient = exports.toMeasurement = exports.entitlementRef = exports.entitlementKind = exports.entitlementId = exports.emptyTokenUsage = exports.vendorMetrics = exports.unitsPerTokens = exports.looksLikeGovernanceNotEnabled = exports.isGovernanceNotEnabled = exports.isAccessDenied = exports.isEngineError = exports.GovernanceNotEnabledError = exports.AccessDeniedError = exports.EngineError = exports.STIGG_TRACER_NAME = exports.noopLogger = exports.consoleLogger = exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = exports.remedyMessage = exports.describeDecision = exports.flattenRaw = exports.RAW_PREFIX = exports.StiggAgentSDK = void 0;
 /**
  * Public surface.
  *
@@ -118,6 +118,14 @@ Object.defineProperty(exports, "bedrockRecipe", { enumerable: true, get: functio
 // limitation.
 var cloudflare_recipe_1 = require("./bindings/client/gateways/cloudflare/cloudflare-recipe");
 Object.defineProperty(exports, "cloudflareRecipe", { enumerable: true, get: function () { return cloudflare_recipe_1.cloudflareRecipe; } });
+// agentgateway - the open-source AI gateway (Solo.io's enterprise build and Gloo AI Gateway sit on
+// it). A default, ahead of
+// both wires it serves - OpenAI chat and responses, and Anthropic Messages - so its traffic reports
+// as `agentgateway.*` rather than as a direct call. Self-hosted, so give it your gateway's base URL at
+// `wrap(client, { recipe: agentgatewayRecipe({ baseUrl }) })`; it reports tokens and the model that served,
+// and no `cost`, because the gateway states no price on any response.
+var agentgateway_recipe_1 = require("./bindings/client/gateways/agentgateway/agentgateway-recipe");
+Object.defineProperty(exports, "agentgatewayRecipe", { enumerable: true, get: function () { return agentgateway_recipe_1.agentgatewayRecipe; } });
 var typesafe_recipe_1 = require("./bindings/client/providers/typesafe/typesafe-recipe");
 Object.defineProperty(exports, "typesafeRecipe", { enumerable: true, get: function () { return typesafe_recipe_1.typesafeRecipe; } });
 Object.defineProperty(exports, "estimateFromState", { enumerable: true, get: function () { return typesafe_recipe_1.estimateFromState; } });

package/dist/stigg-agent-sdk.d.ts

@@ -1,5 +1,6 @@
 import { type ResolvedConfig, type StiggAgentSDKOptions } from './config';
 import { type EngineResolution, type GovernanceEngine } from './engine/engine';
+import type { FetchOptions, GovernedFetch } from './bindings/fetch/types';
 import type { StiggContext } from './core/context';
 import type { SessionSummary } from './core/session';
 import type { Metrics, GovernedAgentMiddleware, MiddlewareOptions, ClientOptions, DeregisterInput, AccessDecision, WrappedClient, PathsOf, IngestContext, IngestResult, RegisterInput } from './types';
@@ -250,6 +251,28 @@ export declare class StiggAgentSDK {
      * see {@link GovernanceSession.warmUp} for which cache that is and when there is one at all.
      */
     wrap<T extends object, O extends ClientOptions>(client: T, options?: O): WrappedClient<T, O['stiggContext'], PathsOf<O['recipe'], T>>;
+    /**
+     * Governs plain HTTP calls to a gateway, for an application that posts JSON with `fetch` instead
+     * of holding an SDK client - the same gate and meter `wrap` gives a client, keyed on the request
+     * path rather than on a method.
+     *
+     * ```ts
+     * const gatewayFetch = stigg.wrapFetch({
+     *   baseUrl: 'http://agentgateway.internal:8080',
+     *   recipe: agentgatewayRecipe(),
+     *   stiggContext: { customerId, entitlement: { currencyId: 'credits' } },
+     * });
+     * await gatewayFetch('http://agentgateway.internal:8080/v1/chat/completions', {
+     *   method: 'POST',
+     *   body: JSON.stringify({ model: 'gpt-5-mini', messages }),
+     *   stiggContext: { agentId: 'support-bot' },
+     * });
+     * ```
+     *
+     * The recipe is named rather than detected, because a URL alone cannot say who bills. A request
+     * outside `baseUrl`, or to a route the recipe does not declare, goes through untouched.
+     */
+    wrapFetch(options: FetchOptions): GovernedFetch;
     /**
      * An agent graph's governance middleware - the orchestration counterpart to `wrap`.
      *

package/dist/stigg-agent-sdk.js

@@ -27,6 +27,7 @@ const gemini_recipe_1 = require("./bindings/client/providers/gemini/gemini-recip
 const litellm_recipe_1 = require("./bindings/client/gateways/litellm/litellm-recipe");
 const databricks_recipe_1 = require("./bindings/client/gateways/databricks/databricks-recipe");
 const cloudflare_recipe_1 = require("./bindings/client/gateways/cloudflare/cloudflare-recipe");
+const agentgateway_recipe_1 = require("./bindings/client/gateways/agentgateway/agentgateway-recipe");
 const groq_recipe_1 = require("./bindings/client/providers/groq/groq-recipe");
 const mistral_recipe_1 = require("./bindings/client/providers/mistral/mistral-recipe");
 const ollama_recipe_1 = require("./bindings/client/providers/ollama/ollama-recipe");
@@ -37,6 +38,7 @@ const typesafe_recipe_1 = require("./bindings/client/providers/typesafe/typesafe
 const registry_1 = require("./bindings/client/core/registry");
 const wrap_client_1 = require("./bindings/client/core/wrap-client");
 const agent_middleware_1 = require("./bindings/orchestrator/core/agent-middleware");
+const wrap_fetch_1 = require("./bindings/fetch/wrap-fetch");
 const token_usage_1 = require("./bindings/shared/token-usage");
 const context_1 = require("./core/context");
 const session_1 = require("./core/session");
@@ -65,6 +67,10 @@ exports.DEFAULT_RECIPES = [
     // claim that client and meter gateway traffic as direct Anthropic traffic. The same argument puts
     // it ahead of `openAIRecipe` for its OpenAI-shaped routes and for Workers AI's compatible one.
     (0, cloudflare_recipe_1.cloudflareRecipe)(),
+    // Ahead of `anthropicRecipe` for the same reason as Cloudflare: agentgateway answers on the
+    // Anthropic Messages wire too, and only the base URL tells its `Anthropic` client from a direct
+    // one. Without a configured base URL it matches on a hostname label - see the recipe.
+    (0, agentgateway_recipe_1.agentgatewayRecipe)(),
     anthropic_recipe_1.anthropicRecipe,
     (0, openrouter_recipe_1.openrouterRecipe)(),
     (0, litellm_recipe_1.litellmRecipe)(),
@@ -152,7 +158,8 @@ function toPlacement(input) {
     if (onCreate && typeof input.budget.limit !== 'number') {
         throw new Error(`Agent ${input.agentId} asked to seed a budget with no limit to seed. ` +
             "`budget.apply: 'on-create'` writes a cap the first time and never again, so there is " +
-            'nothing to write without `budget.limit`.');
+            'nothing to write without `budget.limit`. To seed an unlimited, metering-only budget, ' +
+            'leave out both `limit` and `apply`.');
     }
     // Each entry names an entity, and a blank one names none: the budget would be scoped to an
     // entity no request resolves, and apply to nothing.
@@ -160,12 +167,15 @@ function toPlacement(input) {
         throw new Error(`Agent ${input.agentId} has a budget.scope that is not a list of entity ids: ${JSON.stringify(scope)}. ` +
             'Leave it out, or pass [], for the whole budget.');
     }
+    // No limit at all is metering only: an agent with no assignment is in nobody's tree and its usage
+    // is counted against nothing, so it gets an unlimited one - seeded, so a cap set later survives.
+    const tracking = !onCreate && input.budget.limit === undefined;
     return {
         parentId,
         entitlement,
         cadence,
         usageLimit: onCreate ? undefined : input.budget.limit,
-        usageLimitOnCreate: onCreate ? (input.budget.limit ?? undefined) : undefined,
+        usageLimitOnCreate: tracking ? null : onCreate ? (input.budget.limit ?? undefined) : undefined,
         scopeEntityIds: scope?.length ? scope : undefined,
     };
 }
@@ -426,6 +436,49 @@ class StiggAgentSDK {
             void session.warmUp(context);
         return governed;
     }
+    /**
+     * Governs plain HTTP calls to a gateway, for an application that posts JSON with `fetch` instead
+     * of holding an SDK client - the same gate and meter `wrap` gives a client, keyed on the request
+     * path rather than on a method.
+     *
+     * ```ts
+     * const gatewayFetch = stigg.wrapFetch({
+     *   baseUrl: 'http://agentgateway.internal:8080',
+     *   recipe: agentgatewayRecipe(),
+     *   stiggContext: { customerId, entitlement: { currencyId: 'credits' } },
+     * });
+     * await gatewayFetch('http://agentgateway.internal:8080/v1/chat/completions', {
+     *   method: 'POST',
+     *   body: JSON.stringify({ model: 'gpt-5-mini', messages }),
+     *   stiggContext: { agentId: 'support-bot' },
+     * });
+     * ```
+     *
+     * The recipe is named rather than detected, because a URL alone cannot say who bills. A request
+     * outside `baseUrl`, or to a route the recipe does not declare, goes through untouched.
+     */
+    wrapFetch(options) {
+        void this.ensureStarted().catch((err) => this.reportStartupFailure(err));
+        const fetchFn = options.fetch ?? globalThis.fetch;
+        if (typeof fetchFn !== 'function') {
+            throw new Error('No `fetch` to govern: pass `fetch` in the options, or run on Node 22 or later.');
+        }
+        const session = this.newSession(options.hooks);
+        const context = (0, context_1.resolveContext)(options.stiggContext ?? {}, (0, node_crypto_1.randomUUID)(), {
+            requireCustomer: false,
+            defaults: this.contextDefaults,
+        });
+        if (context.customerId && !(0, context_1.isEnforced)(context)) {
+            this.config.logger.warn('[stigg] this fetch named no entitlement, so nothing is checked and no request can be ' +
+                "refused - it meters only. Pass `entitlement: { currencyId: 'credits' }` in " +
+                '`stiggContext`, at the wrap or on a request, to gate it.');
+        }
+        const governed = (0, wrap_fetch_1.wrapFetch)(fetchFn, options.recipe, options.baseUrl, session, context);
+        this.attachGovernance(governed, session, context);
+        if (context.customerId)
+            void session.warmUp(context);
+        return governed;
+    }
     /**
      * An agent graph's governance middleware - the orchestration counterpart to `wrap`.
      *

package/dist/types.d.ts

@@ -509,10 +509,21 @@ export type AgentBudget = {
      * A scoped budget governs only the requests it names: one naming no model, or a model with no
      * budget, is limited by the agent's whole budget and its ancestors' alone - with neither, by
      * nothing. Register the whole budget too.
+     *
+     * A scope with no `limit` meters that scope only: it is created unlimited, like a whole budget
+     * with no limit, so it shows that scope's usage and refuses nothing.
      */
     scope?: string[];
 } & ({
-    /** The limit, written on every call. `null` clears whatever is assigned. */
+    /**
+     * The limit, written on every call. `null` clears whatever is assigned.
+     *
+     * Omitted, the agent is metering only: the first call creates an unlimited assignment, so its
+     * usage is tracked in the governance tree and its own assignment never refuses it - its
+     * ancestors' budgets and the customer's entitlement still can. Later calls leave the limit
+     * assigned by then - a cap set in the dashboard included - untouched, though a `cadence` they
+     * pass is still applied. `cadence` defaults to `'P1M'` on that create.
+     */
     limit?: number | null;
     /** Writes the limit every time. The default. */
     apply?: 'always';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigg/agent-sdk-js",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Stigg agent SDK (JS) - run-lifecycle governance for agentic stacks, with examples per layer",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -49,6 +49,8 @@
     "example-client-ollama": "tsx examples/client/ollama.ts",
     "example-client-openrouter": "tsx examples/client/openrouter.ts",
     "example-client-litellm": "tsx examples/client/litellm.ts",
+    "example-client-agentgateway": "tsx examples/client/agentgateway.ts",
+    "example-client-solo": "tsx examples/client/solo.ts",
     "example-client-databricks": "tsx examples/client/databricks.ts",
     "example-client-typesafe": "tsx examples/client/typesafe.ts",
     "example-two-agents": "tsx examples/client/two-agents.ts",
@@ -61,6 +63,7 @@
     "example-gateway": "tsx examples/gateway/openrouter.ts",
     "example-gateway-openrouter": "tsx examples/gateway/openrouter.ts",
     "example-gateway-litellm": "tsx examples/gateway/litellm.ts",
+    "example-gateway-agentgateway": "tsx examples/gateway/agentgateway.ts",
     "example-gateway-cloudflare": "tsx examples/gateway/cloudflare.ts",
     "example-gateway-bedrock": "tsx examples/gateway/bedrock.ts",
     "example-gateway-databricks": "tsx examples/gateway/databricks.ts"