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

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

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

@@ -0,0 +1,34 @@
+import type { Measurement } from '../../../../types';
+import type { MetricsFor, MetricsOf } from '../../core/types';
+/**
+ * Accumulates usage across raw stream events: Anthropic sends the input counts on
+ * `message_start` and restates them, with 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: import("../../../../types").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,169 @@
+"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 estimate_1 = require("../../../shared/estimate");
+const registry_1 = require("../../core/registry");
+/**
+ * Characters per output token, for the one case where the vendor states no count.
+ *
+ * Approximate on purpose and deliberately not tuned: it is only ever reached for a stream that
+ * was abandoned, where the alternative is reporting nothing for text the customer read and the
+ * vendor billed. Roughly four characters to a token holds well enough across English prose for
+ * the estimate to be the closer of the two answers. Anything reported from it is marked
+ * `estimated` so it is never mistaken for a counter Anthropic stated.
+ */
+const CHARS_PER_OUTPUT_TOKEN = 4;
+/** The characters a delta contributed, or 0 for the events that generate nothing. */
+function generatedChars(delta) {
+    if (!delta)
+        return 0;
+    const produced = delta.type === 'text_delta'
+        ? delta.text
+        : delta.type === 'thinking_delta'
+            ? delta.thinking
+            : delta.type === 'input_json_delta'
+                ? delta.partial_json
+                : undefined;
+    return typeof produced === 'string' ? produced.length : 0;
+}
+/**
+ * Whether a wire value is a count at all.
+ *
+ * Whole and non-negative, because a counter that *replaces* another has to be checked before it
+ * is trusted: a negative or fractional one is not a token count, and letting it overwrite a real
+ * count reads back as zero.
+ */
+const isCount = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 0;
+/**
+ * The counters a stream has most recently stated - each event replacing what it names, rather
+ * than adding to it.
+ *
+ * Anthropic restates cumulatively. `message_delta.usage.input_tokens` is "the *cumulative* number
+ * of input tokens which were used", in the vendor's own words, and the same holds for both cache
+ * counters and for `output_tokens`. None of them is a delta despite the event's name, so summing
+ * the two events bills every input counter twice.
+ *
+ * Per counter rather than by replacing the block wholesale, because the two events do not carry
+ * the same fields: on older API versions `message_start` is the only one that states the input
+ * counts, and a wholesale replace would make the opposite billing error.
+ *
+ * The key list is {@link ANTHROPIC_COMPONENT_METRICS} rather than one of its own: these are the
+ * same four counters under the same four names, and a second list would be free to disagree with
+ * the one that decides what gets reported.
+ */
+function restate(into, stated) {
+    if (!stated)
+        return into;
+    const merged = { ...into };
+    for (const key of token_usage_1.ANTHROPIC_COMPONENT_METRICS) {
+        const value = stated[key];
+        // Only a whole, non-negative number counts as a statement. `null` is how this wire says
+        // "not this event", and a malformed or negative one is not a count - letting either through
+        // would erase a count an earlier event did state.
+        if (isCount(value))
+            merged[key] = value;
+    }
+    return merged;
+}
+/**
+ * Accumulates usage across raw stream events: Anthropic sends the input counts on
+ * `message_start` and restates them, with 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() {
+        // What the stream has said so far, in the vendor's own shape. Kept flat rather than converted
+        // per event: both views of the call - the vendor's names and the normalized counters - are
+        // derived from it once at the end, so neither can be accumulated out of step with the other.
+        let stated = {};
+        // Whether the stream ever stated a final output count. `message_start` carries a placeholder
+        // `output_tokens: 1`, so the presence of the counter says nothing - only `message_delta` does.
+        let hasStatedOutputTokens = false;
+        // What the stream actually produced, for the case where it never gets to say.
+        let chars = 0;
+        try {
+            for await (const event of iterate()) {
+                if (event?.type === 'message_start')
+                    stated = restate(stated, event.message?.usage);
+                if (event?.type === 'message_delta') {
+                    stated = restate(stated, event.usage);
+                    hasStatedOutputTokens ||= typeof event.usage?.output_tokens === 'number';
+                }
+                if (event?.type === 'content_block_delta')
+                    chars += generatedChars(event.delta);
+                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; `stated` is this SDK's reconstruction across two events, not an object the
+            // stream ever actually sent, so passing it would be a claim about the wire that is not true.
+            //
+            // A stream the consumer walked away from never reaches `message_delta`, the only event
+            // that states a final output count - so without this the text it did produce meters at the
+            // placeholder `output_tokens: 1` from `message_start`. The customer read that text and
+            // Anthropic billed for generating it, so one token is a hole rather than caution. What it
+            // produced is estimated instead, and the measurement says so.
+            const estimated = !hasStatedOutputTokens && chars > 0;
+            const final = estimated
+                ? restate(stated, { output_tokens: Math.max(1, Math.ceil(chars / CHARS_PER_OUTPUT_TOKEN)) })
+                : stated;
+            ingest({
+                metrics: (0, token_usage_1.withComputedTotal)((0, token_usage_1.pickMetrics)(final, token_usage_1.ANTHROPIC_COMPONENT_METRICS), token_usage_1.COMPUTED_TOTALS.anthropic),
+                usage: (0, token_usage_1.fromFlatTokenUsage)(final),
+                ...(estimated ? { estimated: true } : {}),
+            });
+        }
+    };
+}
+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;

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

@@ -0,0 +1,20 @@
+import type { MetricsFor, MetricsOf } from '../../core/types';
+export declare const groqRecipe: {
+    vendor: string;
+    metrics: readonly ["prompt_tokens", "completion_tokens", "cached_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    matches: (client: unknown) => boolean;
+    methods: {
+        path: ("create" | "chat" | "completions")[];
+        extractUsage: (result: any) => {
+            metrics: import("../../../..").Metrics;
+            usage: import("../../../..").TokenUsage;
+            raw: any;
+        } | undefined;
+        attachStream: (stream: any, ingest: (measurement: import("../../../..").Measurement) => void) => void;
+    }[];
+};
+/** One of the metric names Groq reports. */
+export type GroqMetric = MetricsOf<typeof groqRecipe>;
+/** What a mapper reads off a Groq call: those names, each possibly absent. */
+export type GroqMetrics = MetricsFor<typeof groqRecipe>;