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

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

@@ -0,0 +1,15 @@
+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.
+ */
+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,141 @@
+"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");
+/** 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. A streamed call simply carries no `cost` - the header went
+ * out before the first token existed - so the key is absent rather than substituted.
+ */
+function measure(usage, parse, keys, model, id, options) {
+    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: 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,
+    };
+}
+/**
+ * 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.
+ */
+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',
+        // 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) && isOpenRouter(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);
+                    });
+                },
+            };
+        }),
+    };
+}
+/**
+ * `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');
+}
+/** 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/types.d.ts

@@ -0,0 +1,29 @@
+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;
+};
+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 });

package/dist/bindings/client/providers/anthropic/anthropic-recipe.d.ts

@@ -0,0 +1,34 @@
+import { type Measurement, type Metrics } from '../../../../types';
+import type { MetricsFor, MetricsOf } from '../../core/types';
+/**
+ * Accumulates usage across raw stream events: Anthropic sends the input counts on
+ * `message_start` and the output count on `message_delta`, so one completed stream produces one
+ * measurement rather than one per event.
+ */
+declare function observeStream(stream: any, ingest: (measurement: Measurement) => void): void;
+export declare const anthropicRecipe: {
+    vendor: string;
+    metrics: readonly ["input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    matches: (client: unknown) => boolean;
+    methods: {
+        path: string[];
+        extractUsage: (result: any) => {
+            metrics: Metrics;
+            usage: import("../../../../types").TokenUsage;
+            raw: any;
+        } | undefined;
+        attachStream: typeof observeStream;
+    }[];
+};
+/**
+ * A pre-call estimate based on the requested output ceiling. Opt-in: the default asks for a
+ * single unit, because an estimate that overshoots denies calls the budget could have afforded,
+ * and the ingest that follows corrects the balance anyway.
+ */
+export declare const estimateFromMaxTokens: (tokensPerUnit?: number) => (params: any) => number;
+/** One of the metric names Anthropic reports. */
+export type AnthropicMetric = MetricsOf<typeof anthropicRecipe>;
+/** What a mapper reads off an Anthropic call: those names, each possibly absent. */
+export type AnthropicMetrics = MetricsFor<typeof anthropicRecipe>;
+export {};

package/dist/bindings/client/providers/anthropic/anthropic-recipe.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateFromMaxTokens = exports.anthropicRecipe = void 0;
+/**
+ * The Anthropic recipe.
+ *
+ * Only `messages.create` is gated, because `messages.stream()` routes through it - so one patch
+ * covers both call styles, and `stream()` keeps its synchronous signature (callers attach
+ * listeners to the returned object before awaiting anything). A denial raised inside the create
+ * leg surfaces as a rejection from `finalMessage()`/`done()`, which is where a stream caller
+ * already handles failure.
+ */
+const token_usage_1 = require("../../../shared/token-usage");
+const token_usage_2 = require("../../../shared/token-usage");
+const types_1 = require("../../../../types");
+const estimate_1 = require("../../../shared/estimate");
+const registry_1 = require("../../core/registry");
+/**
+ * Accumulates usage across raw stream events: Anthropic sends the input counts on
+ * `message_start` and the output count on `message_delta`, so one completed stream produces one
+ * measurement rather than one per event.
+ */
+function observeStream(stream, ingest) {
+    if (!stream || typeof stream[Symbol.asyncIterator] !== 'function')
+        return;
+    const iterate = stream[Symbol.asyncIterator].bind(stream);
+    stream[Symbol.asyncIterator] = async function* gatedIterator() {
+        let total = (0, types_1.emptyTokenUsage)();
+        // Accumulated beside the normalized counters: a stream states its own names across two
+        // events, and what the run reports by default is those names.
+        let metrics = {};
+        try {
+            for await (const event of iterate()) {
+                if (event?.type === 'message_start') {
+                    total = (0, token_usage_2.addTokenUsage)(total, (0, token_usage_1.fromFlatTokenUsage)(event.message?.usage));
+                    metrics = (0, token_usage_1.addMetrics)(metrics, (0, token_usage_1.pickMetrics)(event.message?.usage, token_usage_1.ANTHROPIC_COMPONENT_METRICS));
+                }
+                if (event?.type === 'message_delta') {
+                    total = (0, token_usage_2.addTokenUsage)(total, (0, token_usage_1.fromFlatTokenUsage)(event.usage));
+                    metrics = (0, token_usage_1.addMetrics)(metrics, (0, token_usage_1.pickMetrics)(event.usage, token_usage_1.ANTHROPIC_COMPONENT_METRICS));
+                }
+                yield event;
+            }
+        }
+        finally {
+            // Meter what was actually produced, even if the consumer broke out of the loop early.
+            //
+            // No `raw` here, deliberately, and this is the one vendor that cannot have one: the counters
+            // arrive split across `message_start` and `message_delta`, so there is no single usage block
+            // on the wire to carry. The Gemini and OpenAI streams each report one whole block and do
+            // pass it on; anything passed here would be an object this stream never actually sent.
+            // The total is added here rather than per event: these counters arrive across two of
+            // them, so summing a half-read call would report a total that was never true of it.
+            ingest({ metrics: (0, token_usage_1.withComputedTotal)(metrics, token_usage_1.COMPUTED_TOTALS.anthropic), usage: total });
+        }
+    };
+}
+exports.anthropicRecipe = {
+    vendor: 'anthropic',
+    metrics: token_usage_1.ANTHROPIC_METRICS,
+    totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+    matches: (client) => (0, registry_1.hasMethod)(client, ['messages', 'create']) && (0, registry_1.hasMethod)(client, ['messages', 'stream']),
+    methods: [
+        {
+            // `messages.stream()` reaches the wire through this same method, so gating it here covers
+            // both call styles - and leaves `stream()` synchronous, which its callers rely on.
+            path: ['messages', 'create'],
+            // Both views of the call: what Anthropic called it, which is what gets reported, and the
+            // normalized counters a mapper of your own would write against.
+            extractUsage: (result) => result?.usage
+                ? {
+                    // Anthropic publishes no total of its own, so one is added up from the four it
+                    // does publish - which are disjoint, so the sum is the whole call.
+                    metrics: (0, token_usage_1.withComputedTotal)((0, token_usage_1.pickMetrics)(result.usage, token_usage_1.ANTHROPIC_COMPONENT_METRICS), token_usage_1.COMPUTED_TOTALS.anthropic),
+                    usage: (0, token_usage_1.fromFlatTokenUsage)(result.usage),
+                    // The block as it arrived, for an event to state in full - including the counters
+                    // this recipe does not name, which a meter can then read without an SDK release.
+                    raw: result.usage,
+                }
+                : undefined,
+            attachStream: observeStream,
+        },
+    ],
+};
+/**
+ * A pre-call estimate based on the requested output ceiling. Opt-in: the default asks for a
+ * single unit, because an estimate that overshoots denies calls the budget could have afforded,
+ * and the ingest that follows corrects the balance anyway.
+ */
+const estimateFromMaxTokens = (tokensPerUnit = 1) => (0, estimate_1.estimateUnits)((params) => params?.max_tokens ?? 0, tokensPerUnit);
+exports.estimateFromMaxTokens = estimateFromMaxTokens;

package/dist/bindings/client/providers/gemini/gemini-recipe.d.ts

@@ -0,0 +1,54 @@
+import { type Measurement } from '../../../../types';
+import type { MetricsFor, MetricsOf } from '../../core/types';
+/** The one-shot surface: `ai.models.generateContent` and its streaming twin. */
+export declare const geminiRecipe: {
+    vendor: string;
+    metrics: readonly ["promptTokenCount", "candidatesTokenCount", "cachedContentTokenCount", "thoughtsTokenCount", "toolUsePromptTokenCount", "totalTokenCount"];
+    totalTokensMetric: "totalTokenCount";
+    matches: (client: unknown) => boolean;
+    methods: ({
+        path: readonly ["models", "generateContent"];
+        extractUsage: (result: any) => Measurement | undefined;
+        attachStream: (stream: any, ingest: (measurement: Measurement) => void) => void;
+    } | {
+        path: readonly ["models", "generateContentStream"];
+        extractUsage: (result: any) => Measurement | undefined;
+        attachStream: (stream: any, ingest: (measurement: Measurement) => void) => void;
+    })[];
+};
+/**
+ * The conversational surface: one `Chat`, as `ai.chats.create(...)` hands it back.
+ *
+ * Matched on all three of its own methods rather than on `sendMessage` alone - that name is far
+ * too common for a duck-typed registry to claim on sight, and a wrong match here would wrap
+ * somebody else's object and meter its calls as Gemini traffic.
+ */
+export declare const geminiChatRecipe: {
+    vendor: string;
+    metrics: readonly ["promptTokenCount", "candidatesTokenCount", "cachedContentTokenCount", "thoughtsTokenCount", "toolUsePromptTokenCount", "totalTokenCount"];
+    totalTokensMetric: "totalTokenCount";
+    matches: (client: unknown) => boolean;
+    methods: ({
+        path: readonly ["sendMessage"];
+        event: string;
+        extractUsage: (result: any) => Measurement | undefined;
+        attachStream: (stream: any, ingest: (measurement: Measurement) => void) => void;
+    } | {
+        path: readonly ["sendMessageStream"];
+        event: string;
+        extractUsage: (result: any) => Measurement | undefined;
+        attachStream: (stream: any, ingest: (measurement: Measurement) => void) => void;
+    })[];
+};
+/**
+ * A pre-call estimate based on the requested output ceiling, which Gemini nests under `config`.
+ *
+ * Opt-in, on the same terms as the Anthropic one: the default asks for a single unit, because an
+ * estimate that overshoots denies calls the budget could have afforded, and the ingest that
+ * follows corrects the balance anyway.
+ */
+export declare const estimateFromMaxOutputTokens: (tokensPerUnit?: number) => (params: any) => number;
+/** One of the metric names Gemini reports. */
+export type GeminiMetric = MetricsOf<typeof geminiRecipe>;
+/** What a mapper reads off a Gemini call: those names, each possibly absent. */
+export type GeminiMetrics = MetricsFor<typeof geminiRecipe>;

package/dist/bindings/client/providers/gemini/gemini-recipe.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateFromMaxOutputTokens = exports.geminiChatRecipe = exports.geminiRecipe = void 0;
+/**
+ * The Gemini recipe - `@google/genai`, the GA SDK that replaced `@google/generative-ai`.
+ *
+ * Two recipes, because the two call styles share no code path. `new GoogleGenAI()` builds its
+ * chat module as `new Chats(this.models, ...)` and each `Chat` keeps that reference privately, so
+ * a chat created from a wrapped client still calls the original, unpatched `models.generateContent`.
+ * Gating `models.*` alone would leave every conversation ungoverned while the client looked
+ * governed, so a chat is wrapped in its own right:
+ *
+ *     const chat = stigg.wrap(ai.chats.create({ model }));
+ *
+ * Nothing meters twice: the chat reaches the unwrapped module by construction.
+ *
+ * Generation only. `models.embedContent`, `generateImages`, `generateVideos`, `countTokens`,
+ * `batches.*`, `caches.*` and `live.*` are billable and **not** gated here - each counts in a unit
+ * these metrics do not describe. Meter one by naming your own recipe at `wrap(client, { recipe })`.
+ */
+const token_usage_1 = require("../../../shared/token-usage");
+const meter_stream_1 = require("../../../shared/meter-stream");
+const types_1 = require("../../../../types");
+const estimate_1 = require("../../../shared/estimate");
+const registry_1 = require("../../core/registry");
+/**
+ * Both views of a completed response: what Gemini called the counters, which is what gets
+ * reported, and the normalized ones a mapper of your own would write against.
+ *
+ * Returns undefined for a streamed call - `generateContentStream` resolves to an async generator
+ * with no `usageMetadata` on it - which is what hands the result to `attachStream` below.
+ */
+/**
+ * How many model calls one `generateContent` made.
+ *
+ * With a callable tool the SDK drives the tool loop itself - up to `maximumRemoteCalls`, 10 by
+ * default - and returns only the last response. Each round that called a tool leaves its reply in
+ * `automaticFunctionCallingHistory`, which is `Content` and carries no token counts: the rounds
+ * can be counted, not priced.
+ */
+function afcRounds(result) {
+    const history = result?.automaticFunctionCallingHistory;
+    if (!Array.isArray(history))
+        return 1;
+    const toolReplies = history.filter((content) => Array.isArray(content?.parts) && content.parts.some((part) => part?.functionResponse)).length;
+    return toolReplies + 1;
+}
+/**
+ * What a call whose earlier rounds were never reported can honestly say about itself.
+ *
+ * `generateContent` reassigns `response` each iteration and returns the last, so the earlier
+ * rounds are gone before it returns and no arithmetic here recovers them. Measured: two rounds
+ * billed at 126 and 171, of which the response carries 171. The streamed surface has no such gap.
+ */
+const partialAfcReason = (rounds, measured) => `Gemini ran ${rounds} model calls for one generateContent (automatic function calling), and the ` +
+    `response carries usage for the last one only - ${measured} tokens, out of a total this SDK ` +
+    `cannot see. The earlier rounds were billed by the vendor and are not in the response, so they ` +
+    `are not in this measurement. To meter every round: stream the call, or set ` +
+    `\`automaticFunctionCalling: { disable: true }\` and drive the tool loop yourself, which makes ` +
+    `each round a call this SDK gates and meters on its own.`;
+const extractUsage = (result) => result?.usageMetadata
+    ? {
+        metrics: (0, token_usage_1.pickMetrics)(result.usageMetadata, token_usage_1.GEMINI_METRICS),
+        usage: (0, token_usage_1.fromGeminiUsage)(result.usageMetadata),
+        // The vendor's own id, so one turn reported twice is one turn. The fallback is a step
+        // counter off the run, which is stable only within a process.
+        ...(typeof result.responseId === 'string' ? { idempotencyKey: result.responseId } : {}),
+        ...afcShortfall(result),
+        // The block as it arrived, for an event to state in full - including `totalTokenCount`
+        // and the per-modality breakdowns this recipe does not name, which a meter can then read
+        // without waiting for an SDK release.
+        raw: result.usageMetadata,
+    }
+    : undefined;
+/** The rounds this call made and what went unmeasured, for the calls where any did. */
+function afcShortfall(result) {
+    const rounds = afcRounds(result);
+    if (rounds < 2)
+        return {};
+    return {
+        dimensions: { gemini_afc_rounds: String(rounds) },
+        incomplete: partialAfcReason(rounds, n(result?.usageMetadata?.totalTokenCount)),
+    };
+}
+const n = (value) => (typeof value === 'number' ? value : 0);
+/**
+ * Meters a streamed call: the last block of each round, summed across rounds.
+ *
+ * **Within a round** `usageMetadata` repeats on every chunk as a running total, so the last block
+ * is the whole round and summing the chunks bills it many times over. **Across rounds** automatic
+ * function calling yields several rounds through one generator, each counting from zero, so
+ * keeping only the last block bills one round of several. Measured: 305 charged, 175 from the last
+ * block alone, 556 from summing every chunk.
+ *
+ * The boundary is `responseId`, shared by a round's chunks and changed by the next, and it is
+ * trusted on its own. Measured rather than assumed: `promptTokenCount` changing is **not** a
+ * boundary - it moves within a round too (92 -> 131 on the wire) - and neither is a counter
+ * *failing* to drop, since a round that ended on a function call is easily smaller than the first
+ * chunk of the one after it. Where no id is reported, a counter running backwards stands in,
+ * being the only evidence left that a round restarted.
+ */
+const attachStream = (stream, ingest) => {
+    /** Rounds already finished, which never change again. */
+    let banked = (0, types_1.emptyTokenUsage)();
+    let bankedMetrics = {};
+    /** The round being read, replaced by each block it reports because they are running totals. */
+    let round;
+    let roundMetrics = {};
+    /** What the round being read calls itself, which is what makes the boundary exact. */
+    let roundId;
+    /** Undefined until a chunk states one. A counter nobody has reported cannot have gone down. */
+    let candidates;
+    let thoughts;
+    /**
+     * The block as it arrived, for an event to state in full - kept only while the stream turns
+     * out to be a single round. Copied rather than referenced, because it is held until the stream
+     * ends and the chunk it came from is the consumer's: a reference would let the dimensions
+     * reported disagree with the metrics computed beside them. (`extractUsage` needs no copy -
+     * there the block is flattened in the same tick it is read.)
+     */
+    let raw;
+    let lastId;
+    let rounds = 0;
+    (0, meter_stream_1.meterStream)(stream, (chunk) => {
+        const reported = chunk?.usageMetadata;
+        if (!reported)
+            return;
+        const id = typeof chunk.responseId === 'string' ? chunk.responseId : undefined;
+        const nextCandidates = typeof reported.candidatesTokenCount === 'number' ? reported.candidatesTokenCount : undefined;
+        const nextThoughts = typeof reported.thoughtsTokenCount === 'number' ? reported.thoughtsTokenCount : undefined;
+        // Both values must be present for a decrease to mean anything: an absent counter read as
+        // zero looks like a restart, and banks a round that never ended.
+        const dropped = (next, previous) => next !== undefined && previous !== undefined && next < previous;
+        // The id decides, on its own, wherever one is reported: a `responseId` identifies one
+        // response, and one response is one round. Requiring a counter to drop as well looked
+        // safer and was not - it misses a boundary whenever the new round's first usage chunk
+        // already carries more output than the whole of the previous round, which is the normal
+        // shape when a round ends on a function call. Measured: 223 billed as 147.
+        //
+        // The counters are the fallback for a stream that names nothing, where a counter running
+        // backwards is the only evidence a round restarted.
+        const restarted = dropped(nextCandidates, candidates) || dropped(nextThoughts, thoughts);
+        const endsRound = id !== undefined && roundId !== undefined ? id !== roundId : restarted;
+        // A round ended: bank what it finally reported before the new one starts from zero.
+        let ended = false;
+        if (round !== undefined && endsRound) {
+            ended = true;
+            banked = (0, token_usage_1.addTokenUsage)(banked, round);
+            bankedMetrics = (0, token_usage_1.addMetrics)(bankedMetrics, roundMetrics);
+            rounds += 1;
+        }
+        round = (0, token_usage_1.fromGeminiUsage)(reported);
+        roundMetrics = (0, token_usage_1.pickMetrics)(reported, token_usage_1.GEMINI_METRICS);
+        raw = { ...reported };
+        roundId = id;
+        // The last round's id names the call: one measurement goes out, and this is the id that is
+        // still the same if the stream is read again.
+        if (id !== undefined)
+            lastId = id;
+        // Within a round an omitted counter keeps its last value; across one the baselines are
+        // replaced, absence included. Carrying the old round's figure made the next chunk stating
+        // that counter look like a further restart, banking a round mid-round.
+        if (ended) {
+            candidates = nextCandidates;
+            thoughts = nextThoughts;
+        }
+        else {
+            if (nextCandidates !== undefined)
+                candidates = nextCandidates;
+            if (nextThoughts !== undefined)
+                thoughts = nextThoughts;
+        }
+    }, () => {
+        const usage = round ? (0, token_usage_1.addTokenUsage)(banked, round) : banked;
+        const metrics = round ? (0, token_usage_1.addMetrics)(bankedMetrics, roundMetrics) : bankedMetrics;
+        // One round, one block, and `raw` describes the whole measurement. Several rounds and no
+        // block does: each states only its own round, so passing the last would hand a meter
+        // dimensions that disagree with the metrics beside them. Reported instead is how many
+        // rounds there were, which is the thing a reader would otherwise have no way to see.
+        const single = rounds === 0 && raw;
+        ingest({
+            metrics,
+            usage,
+            ...(single ? { raw } : {}),
+            ...(lastId ? { idempotencyKey: lastId } : {}),
+            ...(rounds ? { dimensions: { gemini_afc_rounds: String(rounds + 1) } } : {}),
+        });
+    });
+};
+/** The one-shot surface: `ai.models.generateContent` and its streaming twin. */
+exports.geminiRecipe = {
+    vendor: 'gemini',
+    metrics: token_usage_1.GEMINI_METRICS,
+    // Gemini's own name for it, which is the one its invoice shows.
+    totalTokensMetric: 'totalTokenCount',
+    // Either is enough on its own, the way the OpenAI recipe treats its two surfaces. Both methods
+    // sit on the same module today, so requiring both would pass anyway - and would start refusing
+    // clients the day the vendor splits them, which is a guard failing for a reason nobody intended.
+    matches: (client) => (0, registry_1.hasMethod)(client, ['models', 'generateContent']) || (0, registry_1.hasMethod)(client, ['models', 'generateContentStream']),
+    // `as const` on each path, which is what `PathsOf` reads: a recipe named explicitly at
+    // `wrap(client, { recipe })` then overlays the per-call context on exactly the methods it
+    // gates, rather than falling back to the shipped vendors' list. It matters most for the chat
+    // recipe below - see there - and both are written the same way so neither drifts.
+    methods: [
+        { path: ['models', 'generateContent'], extractUsage, attachStream },
+        { path: ['models', 'generateContentStream'], extractUsage, attachStream },
+    ],
+};
+/**
+ * The conversational surface: one `Chat`, as `ai.chats.create(...)` hands it back.
+ *
+ * Matched on all three of its own methods rather than on `sendMessage` alone - that name is far
+ * too common for a duck-typed registry to claim on sight, and a wrong match here would wrap
+ * somebody else's object and meter its calls as Gemini traffic.
+ */
+exports.geminiChatRecipe = {
+    vendor: 'gemini',
+    metrics: token_usage_1.GEMINI_METRICS,
+    // Gemini's own name for it, which is the one its invoice shows.
+    totalTokensMetric: 'totalTokenCount',
+    matches: (client) => (0, registry_1.hasMethod)(client, ['sendMessage']) && (0, registry_1.hasMethod)(client, ['sendMessageStream']) && (0, registry_1.hasMethod)(client, ['getHistory']),
+    // Literal paths, so naming this recipe explicitly types the context onto these two methods
+    // whatever the client looks like. Without it the overlay fell back to `ChatOf<T>`, which keys
+    // off `getHistory` - right for detection, wrong here: an explicit recipe never consults
+    // `matches`, so `wrapClient` patches and strips the context on a two-method client the types
+    // were refusing it on.
+    methods: [
+        // Named for where the call comes from rather than for the object it was reached through: a
+        // bare `gemini.sendMessage` says nothing about which API it is, and the event name is what
+        // somebody has to recognise when configuring a meter to filter on it.
+        { path: ['sendMessage'], event: 'gemini.chats.sendMessage', extractUsage, attachStream },
+        { path: ['sendMessageStream'], event: 'gemini.chats.sendMessageStream', extractUsage, attachStream },
+    ],
+};
+/**
+ * A pre-call estimate based on the requested output ceiling, which Gemini nests under `config`.
+ *
+ * Opt-in, on the same terms as the Anthropic one: the default asks for a single unit, because an
+ * estimate that overshoots denies calls the budget could have afforded, and the ingest that
+ * follows corrects the balance anyway.
+ */
+const estimateFromMaxOutputTokens = (tokensPerUnit = 1) => (0, estimate_1.estimateUnits)((params) => params?.config?.maxOutputTokens ?? 0, tokensPerUnit);
+exports.estimateFromMaxOutputTokens = estimateFromMaxOutputTokens;