@stigg/agent-sdk-js 0.0.0-stage → 1.0.0

package/dist/bindings/client/core/registry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Which recipe fits a given client.
+ *
+ * Recipes are matched by the shape of the client rather than by a name the caller has to supply,
+ * so `wrap()` takes one argument and adding a provider is a registry entry - core never learns
+ * about a vendor. An unmatched client fails loudly and names what is supported, because a silent
+ * no-op here would mean a client that quietly meters nothing.
+ */
+import type { ClientRecipe, ClientRegistry } from './types';
+export declare function createClientRegistry(recipes?: ClientRecipe[]): ClientRegistry;
+/** True when every segment of the path exists on the client and the last one is callable. */
+export declare function hasMethod(client: unknown, path: readonly string[]): boolean;

package/dist/bindings/client/core/registry.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClientRegistry = createClientRegistry;
+exports.hasMethod = hasMethod;
+function createClientRegistry(recipes = []) {
+    const entries = [...recipes];
+    return {
+        register: (recipe) => {
+            entries.push(recipe);
+        },
+        find: (client) => entries.find((recipe) => recipe.matches?.(client) ?? false),
+        vendors: () => entries.map((recipe) => recipe.vendor),
+    };
+}
+/** True when every segment of the path exists on the client and the last one is callable. */
+// `readonly`, because the paths a caller has to hand are a recipe's own - and `MethodRecipe.path`
+// is readonly so a literal tuple survives assignment. Taking a mutable array made the exported
+// guard unusable with the exported type.
+function hasMethod(client, path) {
+    const target = path.reduce((node, key) => (node == null ? node : node[key]), client);
+    return typeof target === 'function';
+}

package/dist/bindings/client/core/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * What a client binding needs to know about one vendor - and nothing more.
+ *
+ * Everything vendor-specific lives in a recipe: which methods to gate, how to read usage off a
+ * response, how a streamed response reports it later. The wrapper itself stays generic, so a new
+ * provider is a recipe file rather than a second copy of the gate.
+ */
+import type { Measurement, TokenUsage } from '../../../types';
+/**
+ * Just enough of a fetch `Response` for a recipe that has to read a header off it.
+ *
+ * Structural on purpose: core must not depend on a vendor's response class, nor on the DOM lib.
+ * Most vendors put everything a meter needs in the body, but not all - LiteLLM computes the cost
+ * and reports it beside the body, in `x-litellm-response-cost`, so a body-only extractor cannot
+ * see the one number that matters.
+ */
+export type MeteredResponse = {
+    headers?: {
+        get: (name: string) => string | null;
+    };
+};
+/** A single method to gate, addressed by its property path from the client root. */
+export type MethodRecipe = {
+    /**
+     * e.g. `['messages', 'create']` - the owner object is everything but the last segment.
+     *
+     * The method must return the vendor's request promise - an `APIPromise`, in both SDKs' terms:
+     * a promise that also offers `asResponse()` and `withResponse()`. The gate cannot hand over the
+     * vendor's own object, because the check it runs first is asynchronous and the object does not
+     * exist until it has passed, so it returns a stand-in shaped like one. A method that returns
+     * anything else - a paginated list, a stream helper, a bare value - would lose whatever that
+     * shape offers beyond a promise.
+     */
+    path: readonly string[];
+    /**
+     * True when this call is an internal leg of another wrapped method and must not be gated
+     * twice. Vendors mark these differently, so only the recipe can tell.
+     */
+    passthrough?: (params: any, options: any) => boolean;
+    /** Units to ask for before the call. Defaults to 1 - "is there any budget left at all?". */
+    estimate?: (params: any) => number;
+    /**
+     * Read straight off a completed response. Undefined when the result is a stream.
+     *
+     * `response` is the transport response the body came in on, for the vendors that report spend
+     * in a header rather than in the body. It is absent when the client's promise exposes no
+     * `withResponse()`, so a recipe that needs it must say what it does without it.
+     */
+    extractUsage?: (result: any, response?: MeteredResponse) => TokenUsage | Measurement | undefined;
+    /**
+     * Hooks a result that reports usage later. Wrap the iterator in place and call `ingest` once
+     * the stream completes, so one completed response emits exactly one measurement.
+     */
+    attachStream?: (result: any, ingest: (measurement: TokenUsage | Measurement) => void, response?: MeteredResponse) => void;
+    /**
+     * The event name for this call, when async ingest should report it as something other than the
+     * derived `vendor.path` - a proxy standing in for another vendor's API, say.
+     */
+    event?: string;
+};
+export type ClientRecipe<M extends string = string> = {
+    vendor: string;
+    /**
+     * The *name* of whichever metric is this vendor's total - not the number, which rides the
+     * measurement as `TokenUsage.total`.
+     *
+     * Declared rather than inferred, because the name differs per vendor - `totalTokenCount` for
+     * Gemini, `total_tokens` for everyone else - and a caller pricing metrics otherwise has no way
+     * to tell the total apart from the counters underneath it except by knowing each vendor by
+     * heart. Which matters: billing this *and* a component double-charges those tokens.
+     *
+     * Absent for a vendor that publishes no total and whose counters overlap, where there is
+     * nothing honest to put here.
+     */
+    totalTokensMetric?: M;
+    /**
+     * Every metric name this recipe can report, across all of its surfaces.
+     *
+     * What a mapper of your own can price, and what `weightedMetrics` types its table against. The
+     * union rather than one list per surface: a client speaks whichever API it likes, and a table
+     * covering both prices either - a name the call did not report is simply absent.
+     */
+    metrics: readonly M[];
+    methods: MethodRecipe[];
+    /**
+     * Duck-typed guard: does this recipe fit that client? Lets `wrap(client)` take one argument
+     * instead of asking the caller to name a vendor it can see for itself.
+     */
+    matches?: (client: unknown) => boolean;
+};
+/** The metric names a recipe reports, for naming the union without repeating it. */
+export type MetricsOf<R> = R extends ClientRecipe<infer M> ? M : never;
+/**
+ * What a mapper reads for that recipe: its metric names, each possibly absent.
+ *
+ * Partial because a counter the response did not carry is missing rather than zero - a vendor
+ * reports cache reads only when there were some. Each client binding exports this ready-made for
+ * its own vendor, so a hand-written mapper names the shape instead of building it.
+ */
+export type MetricsFor<R> = Partial<Record<MetricsOf<R>, number>>;
+/** The set of recipes a client can be matched against. */
+export interface ClientRegistry {
+    register(recipe: ClientRecipe): void;
+    find(client: unknown): ClientRecipe | undefined;
+    vendors(): string[];
+}
+/**
+ * What one call is called, for the event an async ingest reports.
+ *
+ * The vendor's own words for its own call - `anthropic.messages.create` - because the name is not
+ * an internal label: a Stigg raw-events meter filters on it, so it has to be something whoever
+ * configures that meter would recognise and could have guessed. Derived from what the recipe
+ * already declares, so a new binding names its events by existing.
+ */
+export declare const eventNameFor: (recipe: {
+    vendor: string;
+}, method: MethodRecipe) => string;

package/dist/bindings/client/core/types.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventNameFor = void 0;
+/**
+ * What one call is called, for the event an async ingest reports.
+ *
+ * The vendor's own words for its own call - `anthropic.messages.create` - because the name is not
+ * an internal label: a Stigg raw-events meter filters on it, so it has to be something whoever
+ * configures that meter would recognise and could have guessed. Derived from what the recipe
+ * already declares, so a new binding names its events by existing.
+ */
+const eventNameFor = (recipe, method) => method.event ?? `${recipe.vendor}.${method.path.join('.')}`;
+exports.eventNameFor = eventNameFor;

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

@@ -0,0 +1,6 @@
+import { type ResolvedContext } from '../../../core/context';
+import type { GovernanceSession } from '../../../core/session';
+import type { ClientRecipe } from './types';
+export declare function wrapClient<T extends object>(client: T, recipe: ClientRecipe, session: GovernanceSession, context: ResolvedContext): T;
+/** Whether this client is one `wrap(...)` handed back. */
+export declare function isGoverned(client: object): boolean;

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

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapClient = wrapClient;
+exports.isGoverned = isGoverned;
+/**
+ * The client binding: a drop-in wrapper that gates before the call and meters after it.
+ *
+ * Two properties matter and pull in opposite directions. Metering must never break the caller's
+ * call, so ingest failures are swallowed into `onError`. Enforcement must never be swallowed, so
+ * a denial is raised. They are deliberately separate code paths here: a failed check becomes a
+ * policy decision, never an accidental "allowed".
+ *
+ * Methods are patched onto a copy rather than proxied or subclassed: a Proxy needs a nested proxy
+ * per namespace and has to keep `this` intact for helpers that re-enter the client, and
+ * subclassing breaks on the next SDK release. The copy is what leaves `wrap()`; the object the
+ * caller built is never mutated, so it keeps working ungoverned.
+ *
+ * ## The per-call context, and why it is read the way it is
+ *
+ * A gated call sits directly in front of a network request the application pays for, so the SDK's
+ * own work has to disappear next to it. The hot path below does exactly this much when a call
+ * carries no `stiggContext`: one property read and one truthiness test. Nothing is destructured,
+ * merged, validated or allocated - the context `wrap` resolved is used as it stands.
+ */
+const errors_1 = require("../../../errors");
+const context_1 = require("../../../core/context");
+const types_1 = require("../../../types");
+const types_2 = require("./types");
+const WRAPPED = Symbol.for('stigg.agent-sdk.wrapped');
+function wrapClient(client, recipe, session, context) {
+    const already = client[WRAPPED];
+    if (already) {
+        throw new Error(`This client is already governed (${already}). Wrap the client you built, not one that ` +
+            '`wrap(...)` handed back - the context travels with each call, so one wrapped client ' +
+            'already serves every customer and agent.');
+    }
+    const copy = Object.create(client);
+    let patched = 0;
+    for (const method of recipe.methods) {
+        if (patch(copy, client, session, context, method, (0, types_2.eventNameFor)(recipe, method)))
+            patched += 1;
+    }
+    // A recipe whose paths resolve to nothing produces a client that is stamped, looks governed,
+    // and gates nothing - the same outcome `wrap` already refuses when no recipe matches at all,
+    // reached by a different road. Partial is fine and expected: `openAIRecipe` declares both
+    // surfaces because one client can speak either, and a client built for one has no other.
+    if (!patched) {
+        throw new Error(`The ${recipe.vendor} recipe gates ${recipe.methods.map((m) => m.path.join('.')).join(', ')}, and this ` +
+            'client has none of them. Nothing would be checked or metered, so this is refused rather ' +
+            'than handed back looking governed. Check the recipe matches the client you passed.');
+    }
+    Object.defineProperty(copy, WRAPPED, { value: recipe.vendor, enumerable: false });
+    return copy;
+}
+/** Whether this client is one `wrap(...)` handed back. */
+function isGoverned(client) {
+    return client[WRAPPED] !== undefined;
+}
+/**
+ * Gives the copy its own objects along one gated path.
+ *
+ * `Object.create(client)` alone is not enough: the copy would *inherit* `messages`, so patching
+ * `copy.messages.create` would write straight into the namespace the original shares. Only the
+ * objects on a gated path are copied; everything else is inherited, so a namespace the vendor
+ * builds lazily still resolves.
+ */
+function ownPath(copy, source, path) {
+    let owner = copy;
+    let realOwner = source;
+    for (const key of path) {
+        const next = realOwner?.[key];
+        if (next === null || typeof next !== 'object')
+            return undefined;
+        if (!Object.prototype.hasOwnProperty.call(owner, key)) {
+            Object.defineProperty(owner, key, {
+                value: Object.create(next),
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+        owner = owner[key];
+        realOwner = next;
+    }
+    return { owner, realOwner };
+}
+function patch(copy, source, session, base, method, eventName) {
+    const resolved = ownPath(copy, source, method.path.slice(0, -1));
+    if (!resolved)
+        return false;
+    const { owner, realOwner } = resolved;
+    const key = method.path[method.path.length - 1];
+    const original = realOwner?.[key];
+    if (typeof original !== 'function')
+        return false;
+    // How much to ask permission for before the call - Stigg's `requestedUsage`. The recipe owns
+    // it: only the adapter can read a cost off that vendor's own parameters. Defaults to 1,
+    // "is there any budget left at all?" - the ingest afterwards is what makes the balance right.
+    const estimate = method.estimate ?? (() => 1);
+    // Folded in once per method rather than per call. The event name is the only part of a context
+    // that depends on which method was gated - it is what a Stigg meter filters on, and one client
+    // can reach two APIs a meter should be able to tell apart - so resolving it here is what lets
+    // the common call read a context with nothing left to decide.
+    const defaults = base.eventName ? base : { ...base, eventName: { name: eventName } };
+    owner[key] = function gated(...args) {
+        // Whatever the vendor's own signature takes. Naming the first two and forwarding only those
+        // would quietly drop the rest of a call the recipe never claimed to reshape.
+        let [params] = args;
+        let context = defaults;
+        // The context rides inside the vendor's own parameter object, so it has to come back out
+        // before anything - the recipe's own hooks included - ever sees those parameters. Both the
+        // copy and the merge happen only for a call that actually carried one.
+        if (params?.stiggContext !== undefined) {
+            const { stiggContext, ...rest } = params;
+            params = rest;
+            args = [rest, ...args.slice(1)];
+            context = (0, context_1.overrideContext)(defaults, stiggContext);
+        }
+        const callOptions = args[1];
+        // The vendor's own object is the receiver, never the copy: an SDK method reading a private
+        // field off `this` would throw on an object that only delegates to the real one.
+        const target = realOwner;
+        if (method.passthrough?.(params, callOptions)) {
+            return original.apply(target, args);
+        }
+        const settled = (async () => {
+            // The one field a call cannot proceed without, refused here rather than three frames down.
+            // `wrap` deliberately allows a client with no customer - its calls each name their own, and
+            // the types say which still owe one - but a type is not a guarantee at runtime, and a
+            // framework that owns the call site cannot satisfy one. Left to reach the engine, the empty
+            // id comes back as a verdict about a customer that is not there, worded as confidently as
+            // any other and attributed to nobody.
+            //
+            // Inside the async body on purpose: this method stands in for the vendor's, which returns a
+            // promise, so a caller's `.catch()` has to see this the way it sees a denial.
+            if (!context.customerId)
+                throw (0, context_1.noCustomer)();
+            // The context owns the check policy; this only decides how much to ask for. A context that
+            // names no entitlement has nothing to ask against, so the gate is skipped outright rather
+            // than asked and ignored: `estimate` is the recipe reading the caller's own parameters, and
+            // paying for one per call to throw the answer away is not what metering-only promises - nor
+            // would a client whose every call checked still report the `checks: 0` an operator reads.
+            if ((0, context_1.isEnforced)(context)) {
+                const decision = await session.check(context, requestedUnits(estimate, params));
+                // No return path here for a structured refusal - the vendor's signature owns the return
+                // type - so this is the one place the SDK raises instead of returning a decision.
+                if (!decision.hasAccess)
+                    throw new errors_1.AccessDeniedError(decision);
+            }
+            const result = await collect(original.apply(target, args), params);
+            // Whatever the recipe reports - tokens for most vendors, real spend plus the model that
+            // served it for one that knows better. The wrapper stays out of that judgement.
+            const ingest = (measured) => {
+                const measurement = (0, types_1.toMeasurement)(measured);
+                void session.ingestMeasurement(context, measurement);
+                // Reported what it could, and said what it could not. A measurement that does not cover
+                // everything the vendor charged for is a metering failure even though the ingest itself
+                // succeeded - so it goes out *and* is raised, rather than one or the other.
+                if (measurement.incomplete)
+                    session.failedToMeasure(context, new Error(measurement.incomplete));
+            };
+            try {
+                const measurement = method.extractUsage?.(result.data, result.response);
+                if (measurement)
+                    ingest(measurement);
+                else
+                    method.attachStream?.(result.data, ingest, result.response);
+            }
+            catch (err) {
+                // The vendor already answered. A recipe that cannot read its response is a metering
+                // failure, not the caller's - turning it into a rejection would fail a call that worked.
+                session.failedToMeasure(context, err);
+            }
+            return result;
+        })();
+        // Marks the inner promise handled; the stand-in below still surfaces the rejection to callers.
+        settled.catch(() => undefined);
+        return gatedPromise(settled);
+    };
+    return true;
+}
+/**
+ * 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".
+ */
+function requestedUnits(estimate, params) {
+    const units = estimate(params);
+    return Number.isFinite(units) && units >= 0 ? units : 1;
+}
+/**
+ * Awaits the vendor's own promise, keeping the caller's response readable where it can.
+ *
+ * A body can be read once, and the recipes need it parsed to find usage in - so a gated call used
+ * to hand `asResponse()` a response nobody could read afterwards. `asResponse()` gives the
+ * response over before anything has touched it, which is early enough to take a copy: the SDK
+ * parses the original exactly as it always did, and the untouched clone is what the caller gets.
+ *
+ * Not for a stream, whose body *is* the stream - copying it would tee an open connection into
+ * memory. Nothing is lost there, because a stream is metered off its own events rather than off
+ * the response.
+ */
+async function collect(pending, params) {
+    if (typeof pending?.withResponse !== 'function')
+        return { data: await pending };
+    // Only a promise that hands over the unparsed response can be copied, and only a body that is
+    // not itself a stream is worth copying.
+    const spare = params?.stream ? undefined : await spareResponse(pending);
+    // `withResponse()` after the copy, so the vendor still supplies its own request id alongside
+    // the parse rather than this having to guess which header it came from.
+    return { ...(await pending.withResponse()), spare };
+}
+async function spareResponse(pending) {
+    if (typeof pending.asResponse !== 'function')
+        return undefined;
+    const response = await pending.asResponse();
+    // The request parameter says what was asked for; the response says what was sent, and only the
+    // second is worth trusting with an open connection. A stream is an event stream, and teeing one
+    // would buffer a live body to serve a copy nobody asked for.
+    if (String(response?.headers?.get?.('content-type') ?? '').includes('event-stream'))
+        return undefined;
+    return typeof response?.clone === 'function' && response.bodyUsed === false ? response.clone() : undefined;
+}
+/**
+ * A real promise, because the gate has to return one before the vendor's exists.
+ *
+ * The check is asynchronous and the vendor is not called until it passes, so at the moment the
+ * caller receives a value there is nothing yet to hand over. What stands in is a `Promise`
+ * subclass carrying the helpers the vendor's own promise declares - a plain object with a `then`
+ * is not a promise: `instanceof Promise` is false on it, and everything past `then`/`catch`
+ * silently does not exist despite the type saying otherwise.
+ */
+class GatedPromise extends Promise {
+    // `then` must hand back a plain promise. The default builds another of these through the
+    // constructor, which has no settled result to hang the helpers off.
+    static get [Symbol.species]() {
+        return Promise;
+    }
+}
+function gatedPromise(settled) {
+    const promise = new GatedPromise((resolve, reject) => {
+        settled.then((result) => resolve(result.data), reject);
+    });
+    // A caller that only wants the response asks `withResponse()` and never touches this one -
+    // Anthropic's stream helper does exactly that. Left alone, a refusal would reject a promise
+    // nobody is holding, which Node reports as unhandled and, by default, exits on. Marking it
+    // handled costs nothing: the rejection is still delivered to whoever does await it.
+    promise.catch(() => undefined);
+    // The copy is ours; the caller is handed it in place of the response the parse consumed.
+    promise.asResponse = () => settled.then((result) => result.spare ?? result.response);
+    promise.withResponse = () => settled.then(({ spare: _spare, ...rest }) => rest);
+    promise._thenUnwrap = (transform) => gatedPromise(settled.then((result) => ({ ...result, data: transform(result.data, result) })));
+    return promise;
+}

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

@@ -0,0 +1,17 @@
+import { GATEWAY_METRICS } from '../../../shared/token-usage';
+import type { LiteLLMRecipeOptions } from './types';
+import type { ClientRecipe, MetricsFor, MetricsOf } from '../../core/types';
+/** Both OpenAI surfaces plus the price the gateway itself charged. */
+type GatewayMetric = (typeof GATEWAY_METRICS)[number];
+/**
+ * One recipe covers every upstream. LiteLLM normalizes Anthropic, OpenAI, Bedrock and the rest to
+ * the same wire shape, so the response never changes form - `model` is just a field saying which
+ * deployment served, which is what makes it worth putting on the ingest as a dimension: the client
+ * asked for a model group, and the group is free to resolve to something else.
+ */
+export declare function litellmRecipe(options?: LiteLLMRecipeOptions): ClientRecipe<GatewayMetric>;
+/** One of the metric names LiteLLM reports. */
+export type LiteLLMMetric = MetricsOf<ReturnType<typeof litellmRecipe>>;
+/** What a mapper reads off a LiteLLM call: those names, each possibly absent. */
+export type LiteLLMMetrics = MetricsFor<ReturnType<typeof litellmRecipe>>;
+export {};

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

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.litellmRecipe = litellmRecipe;
+/**
+ * The LiteLLM recipe - a gateway you call, whose cost arrives beside the body rather than in it.
+ *
+ * LiteLLM Proxy speaks the OpenAI wire format, so `openAIRecipe` already fits it by shape. What
+ * that recipe cannot express is the same pair `openrouterRecipe` exists for: the money actually
+ * spent, and which deployment actually served after routing. LiteLLM knows both - it prices every
+ * call itself - but it reports the cost in a response header, `x-litellm-response-cost`, and never
+ * in the body. A body-only extractor cannot see it, which is why `extractUsage` takes the response.
+ *
+ * That placement has a consequence worth stating plainly, because it is the protocol and not a bug:
+ * headers go on the wire before the model has generated anything, so a STREAMED call can never
+ * carry a cost. Tokens survive it fine - LiteLLM honours `stream_options: {include_usage: true}`
+ * and puts `usage` on the final chunk - so a stream falls back to the token path via
+ * `onMissingCost`. Non-streaming bills real spend; streaming bills tokens. The streaming branch
+ * below still checks for the header, so the day LiteLLM can send one, this recipe already reads it.
+ *
+ * All of that applies to a run that bills `cost` - `weightedMetrics(litellmRecipe({ baseUrl }),
+ * 'credits', { cost: 1 })`. Bill the token counters instead and the split above stops mattering:
+ * one denomination whether or not the call streamed. Either way the recipe is worth naming for a
+ * self-hosted proxy, to give it the base URL its matcher cannot guess.
+ */
+const meter_stream_1 = require("../../../shared/meter-stream");
+const openai_recipe_1 = require("../../providers/openai/openai-recipe");
+const token_usage_1 = require("../../../shared/token-usage");
+/** The cost LiteLLM charged for this call, in USD. Non-streaming responses only. */
+const COST_HEADER = 'x-litellm-response-cost';
+/** The proxy's own id for the call: stable across its retries, which a local step counter is not. */
+const CALL_ID_HEADER = 'x-litellm-call-id';
+/** Float noise: 0.00108 * 1e6 is 1080.0000000000002, and ceil would bill the extra unit. */
+const toUnits = (cost, unitsPerDollar) => Math.max(1, Math.ceil(Number((cost * unitsPerDollar).toPrecision(12))));
+/** The header is a string on the wire, and absent on every streamed response. */
+function costOf(response) {
+    const raw = response?.headers?.get(COST_HEADER);
+    if (raw == null || raw === '')
+        return undefined;
+    const cost = Number(raw);
+    return Number.isFinite(cost) ? cost : undefined;
+}
+function measure(usage, parse, keys, model, id, response, options) {
+    if (!usage)
+        return undefined;
+    // LiteLLM normalizes every upstream (Anthropic, Bedrock, whatever) to the OpenAI wire format,
+    // so the token names are OpenAI's. The cost is the proxy's own, and it rides beside them rather
+    // than instead of them - a streamed call simply has no cost to report, because the header goes
+    // out before the first token exists.
+    const cost = costOf(response);
+    const metrics = (0, token_usage_1.pickMetrics)(usage, keys);
+    if (cost !== undefined && cost > 0)
+        metrics.cost = toUnits(cost, options.unitsPerDollar);
+    return {
+        metrics,
+        usage: parse(usage),
+        // What the proxy stated, before `cost` was scaled into whole units - an event can carry the
+        // fraction as it was, which is the honest number and the one that reconciles with the bill.
+        //
+        // The cost is folded in rather than assumed present: LiteLLM reports it in a header, not in
+        // the body, so unlike OpenRouter the response alone carries no trace of it. Taking the body
+        // as-is left `metrics.cost` rounded up to whole units as the only record of a price the
+        // proxy had stated exactly.
+        raw: cost === undefined ? usage : { ...usage, cost },
+        dimensions: model ? { [options.modelDimension]: model } : undefined,
+        // The proxy's own call id wins over the completion id: it is what its spend logs are keyed on,
+        // so a replay lines up on both sides of the boundary.
+        idempotencyKey: response?.headers?.get(CALL_ID_HEADER) ?? id,
+    };
+}
+/**
+ * One recipe covers every upstream. LiteLLM normalizes Anthropic, OpenAI, Bedrock and the rest to
+ * the same wire shape, so the response never changes form - `model` is just a field saying which
+ * deployment served, which is what makes it worth putting on the ingest as a dimension: the client
+ * asked for a model group, and the group is free to resolve to something else.
+ */
+function litellmRecipe(options = {}) {
+    const resolved = {
+        estimate: options.estimate ?? (() => 1),
+        unitsPerDollar: positiveDenomination(options.unitsPerDollar, 'unitsPerDollar'),
+        modelDimension: options.modelDimension ?? 'model',
+    };
+    return {
+        metrics: token_usage_1.GATEWAY_METRICS,
+        // The OpenAI shape it speaks, so the OpenAI name for the total.
+        totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+        vendor: 'litellm',
+        // Shape alone cannot separate this from any other OpenAI-compatible client, so the base URL
+        // is the discriminator - it is the one thing that says which gateway is on the other end.
+        matches: (client) => openai_recipe_1.openAIRecipe.matches(client) && isLiteLLM(client, options.baseUrl),
+        // Built from the OpenAI recipe's own surfaces, for the same reason as the OpenRouter one: this
+        // recipe is matched ahead of it, so a surface it failed to declare would go ungated.
+        methods: openai_recipe_1.openAIRecipe.methods.map((base) => {
+            const { parse, keys, streamed } = (0, openai_recipe_1.openAISurface)(base.path);
+            return {
+                path: base.path,
+                estimate: resolved.estimate,
+                extractUsage: (result, response) => measure(result?.usage, parse, keys, result?.model, result?.id, response, resolved),
+                // Usage arrives once, at the end; `model` and `id` ride every chunk. The response is
+                // threaded through even though a real stream's headers carry no cost today - the branch
+                // costs nothing and is the whole difference between this being wrong later and right.
+                attachStream: (stream, ingest, response) => {
+                    let usage;
+                    let model;
+                    let id;
+                    (0, meter_stream_1.meterStream)(stream, (chunk) => {
+                        const seen = streamed(chunk);
+                        if (seen)
+                            usage = seen;
+                        if (chunk?.model)
+                            model = chunk.model;
+                        if (chunk?.id)
+                            id = chunk.id;
+                    }, () => {
+                        const measurement = measure(usage, parse, keys, model, id, response, resolved);
+                        if (measurement)
+                            ingest(measurement);
+                    });
+                },
+            };
+        }),
+    };
+}
+/**
+ * `baseURL` is a public field on the OpenAI client. Shape cannot answer this and a wrong guess
+ * silently changes the unit of account, so the check is narrow on purpose.
+ *
+ * A LiteLLM proxy is self-hosted, so there is no `openrouter.ai` to look for: the configured
+ * `baseUrl` is the only reliable answer, and the hostname guess below is a convenience for the
+ * deployments that do say so. A proxy on a host that mentions neither takes the recipe explicitly,
+ * via `wrap(client, run, { recipe })`.
+ */
+function isLiteLLM(client, baseUrl) {
+    const clientBase = client?.baseURL;
+    if (typeof clientBase !== 'string')
+        return false;
+    // A prefix match on the raw string lets `.../v1` claim `.../v10`, which is a different
+    // deployment with a different price list. Compare the endpoint, one path segment at a time.
+    if (baseUrl)
+        return within(baseUrl, clientBase);
+    return clientBase.toLowerCase().includes('litellm');
+}
+/** Whether `candidate` is the configured endpoint, or something under it. */
+function within(configured, candidate) {
+    try {
+        const want = new URL(configured);
+        const got = new URL(candidate);
+        if (want.origin !== got.origin)
+            return false;
+        const base = want.pathname.replace(/\/+$/, '');
+        const path = got.pathname.replace(/\/+$/, '');
+        return path === base || path.startsWith(`${base}/`);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The denomination, refused when it cannot divide a price.
+ *
+ * `NaN` and `Infinity` make `toUnits` produce a value the ingest rejects a call later, and zero or
+ * a negative clamps every cost to the floor of 1 - a bill that looks plausible and is not. Both
+ * are configuration mistakes worth naming where they were made.
+ */
+function positiveDenomination(value, name) {
+    if (value === undefined)
+        return 1_000_000;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${name} must be a finite positive number - got ${value}, which prices every call wrongly.`);
+    }
+    return value;
+}

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

@@ -0,0 +1,30 @@
+export type LiteLLMRecipeOptions = {
+    /**
+     * 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. Billing tokens, the gap that leaves is about one call's worth of units.
+     * Billing `cost` it is not: a call priced in micro-dollars is thousands of units, so a run with
+     * one unit left passes the gate and then spends far past it.
+     *
+     * Nothing here can price a call the gateway has not priced yet, so closing that gap needs a
+     * ceiling only the caller knows - `max_tokens` against a rate they are willing to assume. Give
+     * one and the gate asks for it; leave it and the overshoot is bounded by a single call, which
+     * is the trade the default makes everywhere else.
+     */
+    estimate?: (params: any) => number;
+    /**
+     * Units per dollar. LiteLLM reports fractional USD and Stigg ingests whole units, so the meter
+     * has to be denominated in something small enough not to round every call up to 1. The default
+     * is micro-dollars; set it to match however the Stigg currency is defined.
+     */
+    unitsPerDollar?: number;
+    /** Dimension the served model is attributed to, so routing drift is visible in Stigg. */
+    modelDimension?: string;
+    /**
+     * The proxy this recipe is for. A LiteLLM deployment is self-hosted, so unlike a public gateway
+     * there is no fixed host to recognise - without this, `matches` can only fall back to a narrow
+     * guess at the hostname. Give it the same base URL the client was built with.
+     */
+    baseUrl?: string;
+};

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

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