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

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 });

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

@@ -0,0 +1,20 @@
+import { GATEWAY_METRICS } from '../../../shared/token-usage';
+import type { OpenRouterRecipeOptions } 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. OpenRouter normalizes Anthropic, OpenAI and the rest to the
+ * same wire shape, so the response never changes form - `model` is just a field saying who served.
+ *
+ * It also covers both ways of reaching OpenRouter from Node: the OpenAI SDK pointed at the
+ * gateway's base URL, and OpenRouter's own `@openrouter/sdk`. Those are different objects with
+ * different method names reporting the same call, and a recipe that governed only the first would
+ * meter nothing at all for an application that took OpenRouter's own documented advice.
+ */
+export declare function openrouterRecipe(options?: OpenRouterRecipeOptions): ClientRecipe<GatewayMetric>;
+/** One of the metric names OpenRouter reports. */
+export type OpenRouterMetric = MetricsOf<ReturnType<typeof openrouterRecipe>>;
+/** What a mapper reads off an OpenRouter call: those names, each possibly absent. */
+export type OpenRouterMetrics = MetricsFor<ReturnType<typeof openrouterRecipe>>;
+export {};

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

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openrouterRecipe = openrouterRecipe;
+/**
+ * The OpenRouter recipe - a gateway you call rather than one you operate.
+ *
+ * OpenRouter speaks the OpenAI wire format, so `openAIRecipe` already fits it by shape. What that
+ * recipe cannot express is the two things a gateway knows and a client-side wrapper cannot: the
+ * credits it actually charged (`usage.cost`) and which model actually served after fallback
+ * routing (`response.model`). Both are on the response, and both are dropped by a projection down
+ * to four token counters - so this recipe bills the real number and attributes it to the model
+ * that earned it.
+ *
+ * It is registered by default, because reading a response is not a pricing decision. It reports
+ * what the gateway stated - the same token counters `openAIRecipe` would, plus `cost` and the
+ * model that served - and what any of that is worth is the run's mapper to decide:
+ * `weightedMetrics(openrouterRecipe(), 'credits', { cost: 1 })` bills the money and ignores the
+ * tokens. The SDK must not infer that from a base URL, which is why it is not inferred at all.
+ *
+ * The other topology - a proxy you run yourself, fronting services that may not even be Node -
+ * has no client object to wrap and stays with the ingest-only gateway binding.
+ */
+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");
+const registry_1 = require("../../core/registry");
+const sdk_usage_1 = require("./sdk-usage");
+/** Float noise: 0.00108 * 1e6 is 1080.0000000000002, and ceil would bill the extra unit. */
+const toUnits = (cost, unitsPerCredit) => Math.max(1, Math.ceil(Number((cost * unitsPerCredit).toPrecision(12))));
+/**
+ * Tokens and cost, from one response.
+ *
+ * A gateway states both, they are different features, and reporting both is what lets one meter
+ * the tokens and the other the money.
+ *
+ * OpenRouter writes the money in the body, which is why a streamed call can still be billed on it:
+ * the usage object arrives on the last chunk, cost included, provided the request asked for usage
+ * (`stream_options.include_usage`, or `streamOptions.includeUsage` through the first-party SDK).
+ * A caller who does not ask gets a stream that states nothing, and the key is then absent rather
+ * than substituted - billing a guess is the one thing a cost-truth adapter must not do. LiteLLM is
+ * the gateway that genuinely cannot state it, because its cost rides a header that went out before
+ * the first token existed.
+ */
+function measure(usage, parse, keys, model, id, options, 
+/**
+ * What the vendor itself stated, when that is not the object being read.
+ *
+ * The first-party SDK hands back camelCased counters, which are translated to the wire's own
+ * spelling before anything meters them - but an event should carry what OpenRouter said, not
+ * what this file rewrote it to, so the original rides along unchanged.
+ */
+stated) {
+    if (!usage)
+        return undefined;
+    const cost = usage.cost;
+    const metrics = (0, token_usage_1.pickMetrics)(usage, keys);
+    // `cost` is the gateway's own field name, so it obeys the same rule as every other metric.
+    if (typeof cost === 'number' && cost > 0)
+        metrics.cost = toUnits(cost, options.unitsPerCredit);
+    return {
+        metrics,
+        usage: parse(usage),
+        // What the gateway 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.
+        raw: stated ?? usage,
+        // The gateway's own request id: stable across its retries, which a local step counter is not.
+        dimensions: model ? { [options.modelDimension]: model } : undefined,
+        idempotencyKey: id,
+    };
+}
+/**
+ * The first-party SDK's two surfaces, built the same way the OpenAI-shaped ones are.
+ *
+ * `@openrouter/sdk` is generated from the OpenAPI spec, so it shares nothing with `openai-node`
+ * but the service behind it: the method is `chat.send` rather than `chat.completions.create`, the
+ * request nests under `chatRequest`, and the counters come back camelCased. Only the last of
+ * those reaches a meter, and `sdk-usage.ts` undoes it so both clients report the same metric
+ * names for the same call.
+ *
+ * `responses.send` is here for the reason the comment on `methods` gives: a surface this recipe
+ * declines to declare is not metered by something else, it is simply ungated - and a client this
+ * recipe claims to govern must not have a billable method left open on it.
+ */
+function sdkSurfaces(resolved) {
+    const surfaces = [
+        { path: ['chat', 'send'], read: sdk_usage_1.fromSdkChatUsage, parse: token_usage_1.fromOpenAIUsage, keys: token_usage_1.METRIC_PATHS.openaiChat },
+        {
+            path: ['responses', 'send'],
+            read: sdk_usage_1.fromSdkResponsesUsage,
+            parse: token_usage_1.fromResponsesUsage,
+            keys: token_usage_1.METRIC_PATHS.openaiResponses,
+        },
+    ];
+    return surfaces.map(({ path, read, parse, keys }) => {
+        /** The vendor's own object translated, with the original kept for the event to carry. */
+        const measureSdk = (usage, model, id) => measure(read(usage), parse, keys, model, id, resolved, usage);
+        return {
+            path: [...path],
+            estimate: resolved.estimate,
+            extractUsage: (result) => measureSdk(result?.usage, result?.model, result?.id),
+            // A streamed call resolves to an `EventStream`, which is a `ReadableStream` subclass: async
+            // iterable, and with no `next`/`return` of its own for `meterStream` to patch. So the
+            // metered path is `for await`, which is how the SDK documents consuming one. A caller who
+            // takes `getReader()` instead bypasses the wrapper - the same hole every streaming binding
+            // has, and the reason the non-streamed surface is the one the example leans on.
+            attachStream: (stream, ingest) => {
+                let usage;
+                let model;
+                let id;
+                (0, meter_stream_1.meterStream)(stream, (chunk) => {
+                    // Usage arrives once, on the last chunk; `model` and `id` ride every one of them.
+                    if (chunk?.usage)
+                        usage = chunk.usage;
+                    if (chunk?.model)
+                        model = chunk.model;
+                    if (chunk?.id)
+                        id = chunk.id;
+                }, () => {
+                    const measurement = measureSdk(usage, model, id);
+                    if (measurement)
+                        ingest(measurement);
+                });
+            },
+        };
+    });
+}
+/**
+ * One recipe covers every upstream. OpenRouter normalizes Anthropic, OpenAI and the rest to the
+ * same wire shape, so the response never changes form - `model` is just a field saying who served.
+ *
+ * It also covers both ways of reaching OpenRouter from Node: the OpenAI SDK pointed at the
+ * gateway's base URL, and OpenRouter's own `@openrouter/sdk`. Those are different objects with
+ * different method names reporting the same call, and a recipe that governed only the first would
+ * meter nothing at all for an application that took OpenRouter's own documented advice.
+ */
+function openrouterRecipe(options = {}) {
+    const resolved = {
+        estimate: options.estimate ?? (() => 1),
+        unitsPerCredit: positiveDenomination(options.unitsPerCredit, 'unitsPerCredit'),
+        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: 'openrouter',
+        // Two clients, recognised two different ways - see each guard for why they cannot share one.
+        // The OpenAI-shaped client is OpenAI-shaped, so only its base URL says which gateway it talks
+        // to; OpenRouter's own SDK is unmistakable by shape and may legitimately point anywhere.
+        matches: (client) => (openai_recipe_1.openAIRecipe.matches(client) && isOpenRouter(client)) || isOpenRouterSdk(client),
+        // Built from the OpenAI recipe's own surfaces. A gateway speaks that API, so the methods worth
+        // governing are the same ones - and because this recipe is matched ahead of it, any surface it
+        // failed to declare would be left ungated rather than falling through.
+        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) => measure(result?.usage, parse, keys, result?.model, result?.id, resolved),
+                    // Usage arrives once, at the end; `model` and `id` ride every chunk.
+                    attachStream: (stream, ingest) => {
+                        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, resolved);
+                            if (measurement)
+                                ingest(measurement);
+                        });
+                    },
+                };
+            }),
+            ...sdkSurfaces(resolved),
+        ],
+    };
+}
+/**
+ * `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: an OpenRouter-compatible
+ * endpoint on another host takes the recipe explicitly, via `wrap(client, run, { recipe })`.
+ */
+function isOpenRouter(client) {
+    const baseUrl = client?.baseURL;
+    if (typeof baseUrl !== 'string')
+        return false;
+    // The host, not a substring of the URL: `openrouter.ai.example.com` is somebody else's domain,
+    // and claiming it would meter an unrelated client as a gateway.
+    const host = hostOf(baseUrl);
+    return host === 'openrouter.ai' || host.endsWith('.openrouter.ai');
+}
+/**
+ * Whether this is OpenRouter's own SDK client, which carries no base URL to recognise it by.
+ *
+ * The OpenAI-shaped client is identified by where it points, because its shape says only
+ * "OpenAI-compatible" and half the industry is. This one is the opposite: `chat.send` is not a
+ * shape anyone else has, and the namespaces beside it - `credits`, `generations`, the gateway's
+ * own billing and routing APIs - are OpenRouter's product rather than an API style someone could
+ * implement by accident. So shape is the whole discriminator here, and there is no URL to check:
+ * an application may point the SDK at a proxy, which is still OpenRouter's SDK and still speaks
+ * its format.
+ *
+ * `in` rather than a property read, because every namespace on that client is a lazy getter that
+ * constructs a sub-client - and merely asking whether a recipe fits must not build three of them.
+ */
+function isOpenRouterSdk(client) {
+    if (!client || typeof client !== 'object')
+        return false;
+    if (!(0, registry_1.hasMethod)(client, ['chat', 'send']) && !(0, registry_1.hasMethod)(client, ['responses', 'send']))
+        return false;
+    return 'credits' in client && 'generations' in client;
+}
+/** The hostname, lowercased, or '' when the URL is not one this can reason about. */
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * 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/openrouter/sdk-usage.d.ts

@@ -0,0 +1,37 @@
+/**
+ * OpenRouter's first-party SDK counts the same tokens under different names.
+ *
+ * `@openrouter/sdk` is generated from the OpenAPI spec and camelCases every field on the way in,
+ * so a response that arrived as `prompt_tokens` reaches the caller as `promptTokens`. Nothing
+ * about the call changed - same gateway, same wire format, same bill - only the spelling the
+ * parse handed back.
+ *
+ * That matters more than it looks. A metric name is a **feature id**: it is what the mapper
+ * prices and what Stigg meters. If the same gateway reported `prompt_tokens` through one client
+ * and `promptTokens` through another, one customer's calls would land on two different features
+ * depending on which SDK the application happened to import - and the second of them exists in
+ * nobody's catalog, so those calls would report to a feature that cannot be billed.
+ *
+ * So the spelling is undone here rather than carried through: each reader below returns the
+ * OpenAI-shaped object the wire actually carried, and everything downstream - `pickMetrics`,
+ * `fromOpenAIUsage`, the metric names in `GATEWAY_METRICS` - is the code that already serves the
+ * OpenAI-shaped client, reading the names it already knows. The vendor's own object is still what
+ * rides along as `raw`, so an event carries what OpenRouter said, spelled the way OpenRouter
+ * spelled it.
+ */
+import type { OpenRouterSdkChatUsage, OpenRouterSdkResponsesUsage, OpenRouterUsage } from './types';
+/**
+ * `chat.send` - the Chat Completions shape, camelCased.
+ *
+ * `cost` keeps its name across both spellings, because it is OpenRouter's own field rather than
+ * one inherited from OpenAI, and the generator had no snake_case original to convert.
+ */
+export declare function fromSdkChatUsage(usage: OpenRouterSdkChatUsage | null | undefined): OpenRouterUsage | undefined;
+/**
+ * `responses.send` - the Responses API shape, camelCased.
+ *
+ * The same tokens again under the third set of names this SDK can hand back: `inputTokens` rather
+ * than `promptTokens`, with the cache detail one level along. Read with the chat reader it would
+ * find none of them and meter the call at zero, which is why the two surfaces get a reader each.
+ */
+export declare function fromSdkResponsesUsage(usage: OpenRouterSdkResponsesUsage | null | undefined): OpenRouterUsage | undefined;

package/dist/bindings/client/gateways/openrouter/sdk-usage.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromSdkChatUsage = fromSdkChatUsage;
+exports.fromSdkResponsesUsage = fromSdkResponsesUsage;
+/** Drops what the SDK models as nullable, so an absent counter stays absent rather than null. */
+const num = (value) => (typeof value === 'number' ? value : undefined);
+/**
+ * `{ key: value }` when there is a value, and nothing at all when there is not.
+ *
+ * Absent and zero are different: `pickMetrics` skips a counter that is not a positive number, and
+ * a nested detail object that exists with nothing in it reads as a vendor that reported a cache
+ * and found none - which is not the same as a vendor that reported no cache at all.
+ */
+const maybe = (key, value) => value === undefined ? {} : { [key]: value };
+/** Nothing, rather than an empty object, when a whole detail group was absent. */
+const group = (fields) => Object.keys(fields).length > 0 ? fields : undefined;
+/**
+ * `chat.send` - the Chat Completions shape, camelCased.
+ *
+ * `cost` keeps its name across both spellings, because it is OpenRouter's own field rather than
+ * one inherited from OpenAI, and the generator had no snake_case original to convert.
+ */
+function fromSdkChatUsage(usage) {
+    if (!usage)
+        return undefined;
+    const promptDetails = group({
+        ...maybe('cached_tokens', num(usage.promptTokensDetails?.cachedTokens)),
+        ...maybe('cache_write_tokens', num(usage.promptTokensDetails?.cacheWriteTokens)),
+    });
+    const completionDetails = group({
+        ...maybe('reasoning_tokens', num(usage.completionTokensDetails?.reasoningTokens)),
+    });
+    return {
+        ...maybe('prompt_tokens', num(usage.promptTokens)),
+        ...maybe('completion_tokens', num(usage.completionTokens)),
+        ...maybe('total_tokens', num(usage.totalTokens)),
+        ...maybe('cost', num(usage.cost)),
+        ...maybe('prompt_tokens_details', promptDetails),
+        ...maybe('completion_tokens_details', completionDetails),
+    };
+}
+/**
+ * `responses.send` - the Responses API shape, camelCased.
+ *
+ * The same tokens again under the third set of names this SDK can hand back: `inputTokens` rather
+ * than `promptTokens`, with the cache detail one level along. Read with the chat reader it would
+ * find none of them and meter the call at zero, which is why the two surfaces get a reader each.
+ */
+function fromSdkResponsesUsage(usage) {
+    if (!usage)
+        return undefined;
+    const inputDetails = group({
+        ...maybe('cached_tokens', num(usage.inputTokensDetails?.cachedTokens)),
+        ...maybe('cache_write_tokens', num(usage.inputTokensDetails?.cacheWriteTokens)),
+    });
+    return {
+        ...maybe('input_tokens', num(usage.inputTokens)),
+        ...maybe('output_tokens', num(usage.outputTokens)),
+        ...maybe('total_tokens', num(usage.totalTokens)),
+        ...maybe('cost', num(usage.cost)),
+        ...maybe('input_tokens_details', inputDetails),
+    };
+}

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

@@ -0,0 +1,78 @@
+import type { OpenAILikeUsage } from '../../../shared/types';
+/** OpenRouter extends the OpenAI usage object with the credits it actually charged. */
+export type OpenRouterUsage = OpenAILikeUsage & {
+    cost?: number | null;
+    /**
+     * The Responses-API counters, for the one client that can report either shape.
+     *
+     * `@openrouter/sdk` reaches both of OpenRouter's surfaces, and they count the same tokens under
+     * different names - so the object a reader hands back may carry one set or the other. Optional
+     * on both sides rather than a union, because the reader that produced it already knows which
+     * surface it read, and the metric list it is picked with is the surface's own.
+     */
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    input_tokens_details?: {
+        cached_tokens?: number | null;
+        cache_write_tokens?: number | null;
+    } | null;
+};
+/**
+ * What `@openrouter/sdk` hands back for `chat.send`, in the SDK's own spelling.
+ *
+ * Declared structurally rather than imported from `@openrouter/sdk`: the package is a devDependency
+ * of the examples, and a recipe that imported its types would make it a dependency of the SDK
+ * itself - every consumer installing a client they may not use. Only the counters are named here,
+ * which is all a meter reads; see `sdk-usage.ts` for why the spelling is undone rather than kept.
+ */
+export type OpenRouterSdkChatUsage = {
+    promptTokens?: number | null;
+    completionTokens?: number | null;
+    totalTokens?: number | null;
+    cost?: number | null;
+    promptTokensDetails?: {
+        cachedTokens?: number | null;
+        cacheWriteTokens?: number | null;
+    } | null;
+    completionTokensDetails?: {
+        reasoningTokens?: number | null;
+    } | null;
+};
+/** The same, for `responses.send` - the Responses API's names, camelCased the same way. */
+export type OpenRouterSdkResponsesUsage = {
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+    totalTokens?: number | null;
+    cost?: number | null;
+    inputTokensDetails?: {
+        cachedTokens?: number | null;
+        cacheWriteTokens?: number | null;
+    } | null;
+    outputTokensDetails?: {
+        reasoningTokens?: number | null;
+    } | null;
+};
+export type OpenRouterRecipeOptions = {
+    /**
+     * How much to ask permission for before the call.
+     *
+     * 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-credits 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 credit. OpenRouter charges fractional credits 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-credits; set it to match however the Stigg currency is defined.
+     */
+    unitsPerCredit?: number;
+    /** Dimension the served model is attributed to, so routing drift is visible in Stigg. */
+    modelDimension?: string;
+};

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

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