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

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

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groqRecipe = void 0;
+/**
+ * The Groq recipe - a provider that speaks the OpenAI wire format.
+ *
+ * Groq invoices the customer directly and runs the weights on its own hardware. Its model ids are
+ * sometimes namespaced (`meta-llama/llama-4-scout-17b-16e-instruct`, `openai/gpt-oss-120b`) but
+ * that prefix is the model's *author*, not a route to someone else's API - no upstream maker is in
+ * the billing path. So: a provider, not a gateway, and there is no `cost` on the response to
+ * recover, only tokens and timings.
+ *
+ * ## What this buys over `openAIRecipe`
+ *
+ * Shape alone cannot tell Groq from any other OpenAI-compatible endpoint - a `groq-sdk` client and
+ * an `OpenAI` client both have `chat.completions.create` - so the hostname is the discriminator,
+ * the same way `isOpenRouter` works. What the dedicated recipe adds is a vendor name of its own:
+ * `groq.chat.completions.create` rather than `openai.chat.completions.create`, so a raw-events
+ * meter and a per-provider budget can tell Groq traffic apart without the caller having to attach
+ * a dimension by hand. The counters themselves are the OpenAI ones, under the OpenAI names.
+ *
+ * Both routes land here, which is the point of matching on the host rather than the client: the
+ * native `groq-sdk` defaults to `https://api.groq.com`, and an `OpenAI` client is pointed at
+ * `https://api.groq.com/openai/v1`. Same hostname, so one guard claims both.
+ *
+ * ## One surface, deliberately
+ *
+ * Only `chat.completions.create` is gated, because it is the only generation surface Groq serves.
+ * `groq-sdk` exposes `chat`, `completions` (an empty namespace holding a type), `embeddings`,
+ * `audio`, `models`, `batches` and `files` - there is no `responses` module, and Groq's API has no
+ * Responses endpoint for an `OpenAI` client to reach either.
+ *
+ * That is a departure from the OpenRouter and LiteLLM recipes, which declare *both* OpenAI
+ * surfaces precisely because they are matched ahead of `openAIRecipe` and an undeclared surface
+ * would be left ungated. The reasoning does not carry over here: the surface those recipes are
+ * protecting is a billable one, and `responses.create` on a client pointed at Groq is unreachable -
+ * it answers 404. Declaring it would publish `groq.responses.create`, an event name that can never
+ * fire, and event names are permanent once a customer's meter filters on them.
+ *
+ * Not gated, and billable: `audio.transcriptions`/`translations` (charged by audio duration) and
+ * `embeddings` (a different price list). Meter one by naming your own recipe at
+ * `wrap(client, { recipe })`.
+ *
+ * ## Where the counters are
+ *
+ * Buffered, at `response.usage` - a clean OpenAI shape. Streamed, at `x_groq.usage` on the final
+ * chunk, because Groq's chunks carry no top-level `usage` of their own. Both reads come from the
+ * OpenAI surfaces this recipe reuses, so there is one implementation of each; see
+ * `openai-recipe.ts` for why that read lives there and `./types.ts` for the shapes, including the
+ * per-model `usage_breakdown` this SDK cannot express and does not meter.
+ */
+const token_usage_1 = require("../../../shared/token-usage");
+const openai_recipe_1 = require("../openai/openai-recipe");
+const base_url_1 = require("../../../shared/base-url");
+/** The one surface Groq serves, as the OpenAI recipe addresses it. */
+const CHAT_PATH = ['chat', 'completions', 'create'];
+/**
+ * `baseURL` is a public field on both clients that reach Groq, and the only thing that says which
+ * vendor is on the other end.
+ *
+ * Narrow on purpose, exactly as `isOpenRouter` is: the host, not a substring, because
+ * `api.groq.com.example.com` is somebody else's domain and claiming it would meter an unrelated
+ * client as Groq. A Groq deployment on another base URL - `GROQ_BASE_URL` set to a regional
+ * endpoint, or a proxy in front of it - is not claimed here and is governed by `openAIRecipe`
+ * instead, which still reads its streamed counters. Name this recipe at
+ * `wrap(client, { recipe: groqRecipe })` to attribute such a client to Groq explicitly.
+ */
+function isGroq(client) {
+    const baseUrl = (0, base_url_1.baseUrlOf)(client);
+    return baseUrl !== undefined && (0, base_url_1.matchesHost)(baseUrl, 'api.groq.com');
+}
+exports.groqRecipe = {
+    vendor: 'groq',
+    // The OpenAI chat counters, under the OpenAI names - Groq reports that block verbatim. The
+    // timings beside it (`queue_time`, `prompt_time`, ...) are floats and are not metrics.
+    metrics: token_usage_1.OPENAI_CHAT_METRICS,
+    totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+    matches: (client) => openai_recipe_1.openAIRecipe.matches(client) && isGroq(client),
+    // Built from the OpenAI recipe's own chat surface, so the extractor and the streamed reader -
+    // including the `x_groq` fallback - have one implementation shared with it rather than a copy.
+    methods: openai_recipe_1.openAIRecipe.methods
+        .filter((method) => method.path.join('.') === CHAT_PATH.join('.'))
+        .map((method) => ({ ...method, path: [...CHAT_PATH] })),
+};

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

@@ -0,0 +1,22 @@
+import { type Measurement } from '../../../../types';
+import type { MistralCompletionResponse } from './types';
+import type { MetricsFor, MetricsOf } from '../../core/types';
+export declare const mistralRecipe: {
+    vendor: string;
+    metrics: readonly ["prompt_tokens", "completion_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    matches: (client: unknown) => boolean;
+    methods: ({
+        path: ("stream" | "chat" | "complete" | "parse" | "parseStream" | "fim" | "agents")[];
+        attachStream: (stream: unknown, ingest: (measurement: Measurement) => void) => void;
+        extractUsage?: undefined;
+    } | {
+        path: ("stream" | "chat" | "complete" | "parse" | "parseStream" | "fim" | "agents")[];
+        extractUsage: (result: MistralCompletionResponse | undefined) => Measurement | undefined;
+        attachStream?: undefined;
+    })[];
+};
+/** One of the metric names Mistral reports. */
+export type MistralMetric = MetricsOf<typeof mistralRecipe>;
+/** What a mapper reads off a Mistral call: those names, each possibly absent. */
+export type MistralMetrics = MetricsFor<typeof mistralRecipe>;

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

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mistralRecipe = void 0;
+/**
+ * The Mistral recipe - `@mistralai/mistralai`, the Speakeasy-generated client.
+ *
+ * ## What is covered
+ *
+ * Every surface that burns tokens and reports them the same way: `chat.complete`, `chat.stream`,
+ * `chat.parse`, `chat.parseStream`, `fim.complete`, `fim.stream`, `agents.complete` and
+ * `agents.stream`. Eight methods, one extractor - `FIMCompletionResponse` and
+ * `ChatCompletionResponse` both carry `usage: UsageInfo`, `ParsedChatCompletionResponse` is a
+ * `ChatCompletionResponse` with its choices retyped, and all four streamed methods resolve to the
+ * same `EventStream<CompletionEvent>`. That was read off the SDK's own types, not assumed.
+ *
+ * Each is its own event name, because a meter filtering on one sees nothing from the others.
+ * `chat.parse` in particular is **not** a wrapper over `chat.complete`: it reaches the wire itself,
+ * so leaving it out would ship a billable path that looks governed.
+ *
+ * ## What is deliberately not covered
+ *
+ * `beta.conversations.*` is declined by name. It reports `ConversationUsageInfo` - the three
+ * counters plus `connectorTokens` and a per-connector map - which is a second vocabulary, and an
+ * event name is permanent once a customer's meter filters on it. Gating it with this extractor
+ * would read the three it shares and silently drop the connector spend, which is the shape of
+ * error this file exists to avoid. It wants its own recipe and its own metric list.
+ *
+ * Also not covered, each counting in units these token metrics do not describe: `embeddings.create`
+ * (tokens, but of a different kind and against a different price list), `ocr.process` (whose
+ * `usageInfo` is `pagesProcessed`, a page count), `audio.transcriptions.*` (`promptAudioSeconds`),
+ * `classifiers.*`, `files.*`, `batch.*` and v2's `workflows.*`. Meter one by naming your own
+ * recipe at `wrap(client, { recipe })`.
+ *
+ * ## Two gaps a caller should know about
+ *
+ * **The standalone functions bypass this entirely.** Every method also exists as a tree-shakable
+ * function taking the client as its first argument - `chatComplete(client, request)` from
+ * `@mistralai/mistralai/funcs/chatComplete.js`. Those do not go through the patched method, so a
+ * call made that way is neither gated nor metered while `wrap()` reports success. Mistral ships an
+ * `SDKHooks` seam that would catch both forms, and it is deliberately not used: holding its
+ * `HookContext` means importing the vendor package into `src/`, which `module-boundaries.test.ts`
+ * forbids outright. A recipe here is data - method paths and duck-typed extractors - and that is
+ * what lets `src/index.ts` export every binding with no vendor SDK at runtime. So this is a real
+ * limit rather than an oversight: call the methods, not the funcs.
+ *
+ * **A stream read through `getReader()` is not metered.** `EventStream` extends `ReadableStream`
+ * *and* overrides `[Symbol.asyncIterator]`, so `meterStream` patches the iterator in place and the
+ * documented `for await` is covered. A consumer that takes a reader instead bypasses it, and the
+ * stream is the caller's own object - it cannot be swapped for a metered copy without breaking
+ * `instanceof`. Stated here rather than left to be discovered.
+ */
+const token_usage_1 = require("../../../shared/token-usage");
+const meter_stream_1 = require("../../../shared/meter-stream");
+const types_1 = require("../../../../types");
+const registry_1 = require("../../core/registry");
+/**
+ * Both views of one usage block: Mistral's counters under the wire's names, and the normalized
+ * four a mapper of your own would read.
+ *
+ * `raw` is the renamed projection rather than the object the SDK handed over, so an event's
+ * `raw.*` dimensions agree with its metrics - and so the same account reports the same strings
+ * whether the application holds a `Mistral` client or an `OpenAI` one pointed at its base URL.
+ */
+function measure(usage) {
+    if (!usage)
+        return undefined;
+    const metrics = (0, token_usage_1.pickRenamedMetrics)(usage, token_usage_1.MISTRAL_METRIC_NAME_MAP);
+    // Nothing readable in it - an absent counter is absent, not zero, so there is no measurement to
+    // report rather than one that says the call cost nothing.
+    if (Object.keys(metrics).length === 0)
+        return undefined;
+    return { metrics, usage: (0, token_usage_1.fromMistralUsage)(usage), raw: { ...metrics } };
+}
+/** Reads the buffered response every gated `complete`/`parse` surface returns. */
+const extractUsage = (result) => measure(result?.usage);
+/** The streamed counterpart, whose counters arrive once and a level down, under `data`. */
+const attachStream = (stream, ingest) => {
+    let metrics = {};
+    let usage = (0, types_1.emptyTokenUsage)();
+    let raw;
+    (0, meter_stream_1.meterStream)(stream, (chunk) => {
+        // Stated whole on the terminating chunk rather than as deltas, so the last one wins.
+        const measured = measure(chunk?.data?.usage);
+        if (measured) {
+            metrics = measured.metrics ?? {};
+            usage = measured.usage ?? (0, types_1.emptyTokenUsage)();
+            raw = measured.raw;
+        }
+    }, 
+    // Absent rather than an empty object when no chunk carried usage, as the other recipes do.
+    () => ingest({ metrics, usage, ...(raw ? { raw } : {}) }));
+};
+/** The surfaces, and whether each one streams. */
+const SURFACES = [
+    { path: ['chat', 'complete'], streams: false },
+    { path: ['chat', 'stream'], streams: true },
+    { path: ['chat', 'parse'], streams: false },
+    { path: ['chat', 'parseStream'], streams: true },
+    { path: ['fim', 'complete'], streams: false },
+    { path: ['fim', 'stream'], streams: true },
+    { path: ['agents', 'complete'], streams: false },
+    { path: ['agents', 'stream'], streams: true },
+];
+exports.mistralRecipe = {
+    vendor: 'mistral',
+    metrics: token_usage_1.MISTRAL_METRICS,
+    // Mistral states its own total, so it is read rather than summed from the parts.
+    totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+    // Two signals, because `complete` on its own is far too common a verb to claim. An `OpenAI`
+    // client pointed at `api.mistral.ai/v1` has neither of these - it speaks `chat.completions.
+    // create` and is governed by `openAIRecipe` as `openai.*`, which the README spells out.
+    matches: (client) => (0, registry_1.hasMethod)(client, ['chat', 'complete']) && (0, registry_1.hasMethod)(client, ['chat', 'stream']),
+    methods: SURFACES.map(({ path, streams }) => streams ? { path: [...path], attachStream } : { path: [...path], extractUsage }),
+};

package/dist/bindings/client/providers/mistral/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * What a Mistral response carries, typed structurally.
+ *
+ * No import from `@mistralai/mistralai` - `module-boundaries.test.ts` would fail on one, and the
+ * package's whole claim is that importing a recipe pulls in no vendor SDK. These are the fields
+ * the recipe reads and nothing more.
+ */
+import type { MistralLikeUsage } from '../../../shared/types';
+/**
+ * The buffered response, shared by every surface this recipe gates.
+ *
+ * `chat.complete`, `fim.complete` and `agents.complete` return three differently-named types in
+ * the SDK - `ChatCompletionResponse`, `FIMCompletionResponse`, `ChatCompletionResponse` again -
+ * and all three carry the same `usage: UsageInfo`. `chat.parse` is `Omit<ChatCompletionResponse,
+ * 'choices'> & { choices? }`, so it keeps `usage` too. That was checked against the SDK's own
+ * types rather than assumed, because one extractor across four surfaces is only safe if the
+ * shapes really are one shape.
+ */
+export type MistralCompletionResponse = {
+    id?: string;
+    model?: string;
+    usage?: MistralLikeUsage | null;
+};
+/**
+ * One streamed event.
+ *
+ * The counters sit a level down, under `data` - all four streamed surfaces resolve to the same
+ * `EventStream<CompletionEvent>`, and `CompletionEvent` is `{ data: CompletionChunk }`. Reading
+ * `chunk.usage` instead of `chunk.data.usage` finds nothing and meters the call at zero, which is
+ * why this is typed rather than reached for inline.
+ */
+export type MistralCompletionEvent = {
+    data?: {
+        id?: string;
+        model?: string;
+        usage?: MistralLikeUsage | null;
+    } | null;
+};

package/dist/bindings/client/providers/mistral/types.js

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

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

@@ -0,0 +1,31 @@
+import { type Measurement } from '../../../../types';
+import type { OllamaResponse } from './types';
+import type { MetricsFor, MetricsOf } from '../../core/types';
+export declare const ollamaRecipe: {
+    vendor: string;
+    metrics: readonly ["prompt_eval_count", "eval_count", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    /**
+     * Three markers, not one.
+     *
+     * `chat` and `generate` are extremely common verbs, and this client has no namespace to make
+     * them distinctive - so a two-signal guard would still claim unrelated objects. `ps` is the
+     * third because it is specific to a model runner. Not matched on the host: Ollama is
+     * self-hosted so there is no fixed hostname, and `proxy: true` leaves `config.host` an empty
+     * string, which a truthiness check would miss.
+     */
+    matches: (client: unknown) => boolean;
+    methods: ({
+        path: readonly ["chat"];
+        extractUsage: (result: OllamaResponse | undefined) => Measurement | undefined;
+        attachStream: (stream: unknown, ingest: (measurement: Measurement) => void) => void;
+    } | {
+        path: readonly ["generate"];
+        extractUsage: (result: OllamaResponse | undefined) => Measurement | undefined;
+        attachStream: (stream: unknown, ingest: (measurement: Measurement) => void) => void;
+    })[];
+};
+/** One of the metric names Ollama reports. */
+export type OllamaMetric = MetricsOf<typeof ollamaRecipe>;
+/** What a mapper reads off an Ollama call: those names, each possibly absent. */
+export type OllamaMetrics = MetricsFor<typeof ollamaRecipe>;

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

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ollamaRecipe = void 0;
+/**
+ * The Ollama recipe - `ollama`, the self-hosted engine's own client.
+ *
+ * ## What these numbers mean, which is not what every other recipe's mean
+ *
+ * Ollama invoices nobody. It is not a provider in the sense the other recipes here are - it bills
+ * nothing, and it serves open-weight models it did not make - so there is no vendor dashboard to
+ * reconcile against and no `cost` to recover. What is being governed is the customer's **own**
+ * capacity: a per-agent or per-team budget over hardware they already pay for. The counters are
+ * reported under Ollama's own names anyway, for the same reason as everywhere else - so a meter
+ * reads one vocabulary - but nobody should expect them to match an invoice, because there is none.
+ *
+ * ## Shape
+ *
+ * The client is **flat**: `chat` and `generate` are methods on the client object itself, not
+ * namespaces. Both take `{ stream: true }` to switch mode, so each declares `extractUsage` *and*
+ * `attachStream` - a streamed call resolves to an `AbortableAsyncIterator` with no counters on it,
+ * `extractUsage` returns undefined, and the wrapper falls through to the stream path. That is the
+ * same dual-mode arrangement `openAIRecipe` uses for `chat.completions.create`.
+ *
+ * The counters sit flat on the response root rather than inside a `usage` object, which is why
+ * `raw` here is an explicit projection of the two counters rather than the response. Passing the
+ * response would flatten `message.content` - the model's own reply text - into event dimensions.
+ *
+ * ## What is deliberately not covered
+ *
+ * `embed` reports `prompt_eval_count` but no `eval_count`: it is a different unit against a
+ * different price list, and metering it with a chat recipe reports a number that is wrong rather
+ * than missing. `embeddings` (the legacy endpoint) reports no counters at all. `pull`, `push` and
+ * `create` move or quantize bytes and report progress, not tokens.
+ *
+ * `systemone` is declined by name even though it genuinely carries tokens. Its block is
+ * `{ input_tokens, output_tokens }` - the identical names `typesafe.systemOne` reports - so gating
+ * it here would emit `ollama.systemone` carrying metrics indistinguishable from TypeSafe's for
+ * anyone metering on metric names rather than event names. One vocabulary per vendor is worth more
+ * than one extra surface; name your own recipe at `wrap(client, { recipe })` if you need it.
+ *
+ * `webSearch` and `webFetch` are the ones worth knowing about: they are **billable**, they are
+ * charged against `OLLAMA_API_KEY` at `ollama.com`, and they ignore `config.host` entirely - so
+ * they are invisible to any host-based reasoning about where this client points. They report no
+ * token counters, so there is nothing honest for this recipe to meter them with.
+ */
+const token_usage_1 = require("../../../shared/token-usage");
+const meter_stream_1 = require("../../../shared/meter-stream");
+const types_1 = require("../../../../types");
+const registry_1 = require("../../core/registry");
+/**
+ * Both views of one response's counters.
+ *
+ * `raw` is built from the picked metrics rather than from the response, deliberately: the counters
+ * are flat on a root that also carries the generated text, and `raw` becomes event dimensions.
+ */
+function measure(result) {
+    // Absent, not zero. The declared type says these are always present and the wire disagrees -
+    // every intermediate stream chunk omits them - so a response with neither has nothing to report.
+    const metrics = (0, token_usage_1.pickMetrics)(result, token_usage_1.METRIC_PATHS.ollama);
+    if (Object.keys(metrics).length === 0)
+        return undefined;
+    return {
+        // Ollama publishes no total, so one is summed from two disjoint counters - the only case where
+        // adding them up is the vendor's own arithmetic rather than ours.
+        metrics: (0, token_usage_1.withComputedTotal)(metrics, token_usage_1.COMPUTED_TOTALS.ollama),
+        usage: (0, token_usage_1.fromOllamaUsage)(result),
+        raw: { ...metrics },
+    };
+}
+/** A buffered `chat`/`generate`. A streamed call resolves to an iterator and reports nothing here. */
+const extractUsage = (result) => measure(result);
+/** The streamed counterpart: the counters ride the final `done: true` chunk and nothing before it. */
+const attachStream = (stream, ingest) => {
+    let metrics = {};
+    let usage = (0, types_1.emptyTokenUsage)();
+    let raw;
+    (0, meter_stream_1.meterStream)(stream, (chunk) => {
+        const measured = measure(chunk);
+        if (measured) {
+            metrics = measured.metrics ?? {};
+            usage = measured.usage ?? (0, types_1.emptyTokenUsage)();
+            raw = measured.raw;
+        }
+    }, 
+    // A stream that ended before its final chunk reports nothing rather than zeroes: it produced
+    // tokens the customer paid for in compute, and a zero would say it produced none.
+    () => ingest({ metrics, usage, ...(raw ? { raw } : {}) }));
+};
+exports.ollamaRecipe = {
+    vendor: 'ollama',
+    metrics: token_usage_1.OLLAMA_METRICS,
+    totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+    /**
+     * Three markers, not one.
+     *
+     * `chat` and `generate` are extremely common verbs, and this client has no namespace to make
+     * them distinctive - so a two-signal guard would still claim unrelated objects. `ps` is the
+     * third because it is specific to a model runner. Not matched on the host: Ollama is
+     * self-hosted so there is no fixed hostname, and `proxy: true` leaves `config.host` an empty
+     * string, which a truthiness check would miss.
+     */
+    matches: (client) => (0, registry_1.hasMethod)(client, ['chat']) && (0, registry_1.hasMethod)(client, ['generate']) && (0, registry_1.hasMethod)(client, ['ps']),
+    methods: [
+        { path: ['chat'], extractUsage, attachStream },
+        { path: ['generate'], extractUsage, attachStream },
+    ],
+};

package/dist/bindings/client/providers/ollama/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What an Ollama response carries, typed structurally.
+ *
+ * No import from `ollama` - `module-boundaries.test.ts` would fail on one.
+ */
+import type { OllamaLikeUsage } from '../../../shared/types';
+/**
+ * A completed `chat` or `generate` response, or the final chunk of a streamed one.
+ *
+ * The counters are flat on the root - there is no `usage` object to reach into - and every one of
+ * them is optional here, against the vendor's own `.d.ts`, which declares them required. The
+ * server marks the whole `Metrics` struct `omitempty`, so an intermediate chunk carries none of
+ * them and the declared type is wrong about it. See `OllamaLikeUsage`.
+ *
+ * `done` is what distinguishes a final chunk from an intermediate one, and is likewise optional
+ * on the wire. The response also carries `message`, `response`, `context` and a set of
+ * nanosecond durations; none is read here, and `message` in particular must never reach `raw` -
+ * it holds the model's reply text, and `raw` becomes event dimensions.
+ */
+export type OllamaResponse = OllamaLikeUsage & {
+    model?: string;
+    done?: boolean;
+    done_reason?: string;
+};

package/dist/bindings/client/providers/ollama/types.js

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

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

@@ -0,0 +1,71 @@
+/**
+ * The OpenAI recipe - the second vendor, and the proof that the generic wrapper carries its
+ * weight: everything below is response-shape knowledge, with no gate logic repeated.
+ *
+ * Works against any OpenAI-compatible endpoint, a gateway included. Note that a gateway usually
+ * wants the ingest-only gateway binding instead: it sees requests, not runs.
+ *
+ * ## Why Groq's own field name is read here, when Groq has a recipe of its own
+ *
+ * `groqRecipe` exists and is matched ahead of this one, so most Groq traffic never reaches here.
+ * The `x_groq.usage` read below stays anyway, and deliberately, for two reasons.
+ *
+ * **It is written once and used twice.** `groqRecipe` builds its methods from these surfaces, the
+ * way the OpenRouter and LiteLLM recipes do, so it reads its own counters through this reader
+ * rather than carrying a copy. Moving the read into that recipe would duplicate it, not relocate
+ * it.
+ *
+ * **A Groq client the host matcher declines still lands here.** That matcher is narrow on purpose -
+ * it compares the hostname, because a wrong guess silently changes who gets billed - so a Groq
+ * deployment reached on any other base URL is not claimed by it: `GROQ_BASE_URL` pointed at a
+ * regional or staging endpoint, or a corporate proxy in front of `api.groq.com`. Those clients are
+ * governed by this recipe, their streamed chunks still carry **no top-level `usage` at all**, and
+ * without this fallback every one of them would be wrapped, stamped governed, and metered at
+ * nothing. That is the bug this read was added to fix, and it is reachable by configuration alone.
+ *
+ * Nothing else is affected: a response from any other OpenAI-compatible vendor has no `x_groq`, so
+ * the fallback yields `undefined` and the behaviour is exactly what it was.
+ *
+ * Mind the trap in that field. `x_groq.usage` means token totals on a **streamed** chunk and
+ * hardware cache statistics - `dram_cached_tokens`, `sram_cached_tokens` - on a buffered response.
+ * Two things keep them apart: only `streamed` consults it at all, and {@link asTokenUsage} refuses
+ * a block that names none of the token counters. Without that guard a buffered response would read
+ * as all-zero counters with cache statistics riding along as `raw` - a measurement of nothing that
+ * looks like data, which is the one failure shape nothing downstream can notice.
+ */
+import { fromOpenAIUsage, fromResponsesUsage } from '../../../shared/token-usage';
+import { type Measurement, type Metrics } from '../../../../types';
+import type { MetricsFor, MetricsOf } from '../../core/types';
+/** The reader for a surface, so a recipe built on top of this one stays in step with it. */
+export declare const openAISurface: (path: readonly string[]) => {
+    readonly path: readonly ["chat", "completions", "create"];
+    readonly parse: typeof fromOpenAIUsage;
+    readonly keys: readonly ["prompt_tokens", "completion_tokens", "prompt_tokens_details.cached_tokens", "total_tokens"];
+    readonly metrics: readonly ["prompt_tokens", "completion_tokens", "cached_tokens", "total_tokens"];
+    readonly streamed: (chunk: any) => any;
+} | {
+    readonly path: readonly ["responses", "create"];
+    readonly parse: typeof fromResponsesUsage;
+    readonly keys: readonly ["input_tokens", "output_tokens", "input_tokens_details.cached_tokens", "total_tokens"];
+    readonly metrics: readonly ["input_tokens", "output_tokens", "cached_tokens", "total_tokens"];
+    readonly streamed: (chunk: any) => any;
+};
+export declare const openAIRecipe: {
+    vendor: string;
+    metrics: readonly ["prompt_tokens", "completion_tokens", "input_tokens", "output_tokens", "cached_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    matches: (client: unknown) => boolean;
+    methods: {
+        path: ("create" | "chat" | "completions" | "responses")[];
+        extractUsage: (result: any) => {
+            metrics: Metrics;
+            usage: import("../../../../types").TokenUsage;
+            raw: any;
+        } | undefined;
+        attachStream: (stream: any, ingest: (measurement: Measurement) => void) => void;
+    }[];
+};
+/** One of the metric names OpenAI reports. */
+export type OpenAIMetric = MetricsOf<typeof openAIRecipe>;
+/** What a mapper reads off an OpenAI call: those names, each possibly absent. */
+export type OpenAIMetrics = MetricsFor<typeof openAIRecipe>;

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

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openAIRecipe = exports.openAISurface = void 0;
+/**
+ * The OpenAI recipe - the second vendor, and the proof that the generic wrapper carries its
+ * weight: everything below is response-shape knowledge, with no gate logic repeated.
+ *
+ * Works against any OpenAI-compatible endpoint, a gateway included. Note that a gateway usually
+ * wants the ingest-only gateway binding instead: it sees requests, not runs.
+ *
+ * ## Why Groq's own field name is read here, when Groq has a recipe of its own
+ *
+ * `groqRecipe` exists and is matched ahead of this one, so most Groq traffic never reaches here.
+ * The `x_groq.usage` read below stays anyway, and deliberately, for two reasons.
+ *
+ * **It is written once and used twice.** `groqRecipe` builds its methods from these surfaces, the
+ * way the OpenRouter and LiteLLM recipes do, so it reads its own counters through this reader
+ * rather than carrying a copy. Moving the read into that recipe would duplicate it, not relocate
+ * it.
+ *
+ * **A Groq client the host matcher declines still lands here.** That matcher is narrow on purpose -
+ * it compares the hostname, because a wrong guess silently changes who gets billed - so a Groq
+ * deployment reached on any other base URL is not claimed by it: `GROQ_BASE_URL` pointed at a
+ * regional or staging endpoint, or a corporate proxy in front of `api.groq.com`. Those clients are
+ * governed by this recipe, their streamed chunks still carry **no top-level `usage` at all**, and
+ * without this fallback every one of them would be wrapped, stamped governed, and metered at
+ * nothing. That is the bug this read was added to fix, and it is reachable by configuration alone.
+ *
+ * Nothing else is affected: a response from any other OpenAI-compatible vendor has no `x_groq`, so
+ * the fallback yields `undefined` and the behaviour is exactly what it was.
+ *
+ * Mind the trap in that field. `x_groq.usage` means token totals on a **streamed** chunk and
+ * hardware cache statistics - `dram_cached_tokens`, `sram_cached_tokens` - on a buffered response.
+ * Two things keep them apart: only `streamed` consults it at all, and {@link asTokenUsage} refuses
+ * a block that names none of the token counters. Without that guard a buffered response would read
+ * as all-zero counters with cache statistics riding along as `raw` - a measurement of nothing that
+ * looks like data, which is the one failure shape nothing downstream can notice.
+ */
+const token_usage_1 = require("../../../shared/token-usage");
+const meter_stream_1 = require("../../../shared/meter-stream");
+const types_1 = require("../../../../types");
+const registry_1 = require("../../core/registry");
+/**
+ * A usage block, or nothing - for the one field that holds something else half the time.
+ *
+ * Groq's `x_groq.usage` carries the token counters while streaming and hardware cache statistics
+ * (`dram_cached_tokens`, `sram_cached_tokens`) when not. Recognised by the counters themselves
+ * rather than by which call produced it, so a block naming none of them is declined outright
+ * instead of being read as three zeroes.
+ */
+const asTokenUsage = (usage) => typeof usage?.prompt_tokens === 'number' ||
+    typeof usage?.completion_tokens === 'number' ||
+    typeof usage?.total_tokens === 'number'
+    ? usage
+    : undefined;
+/**
+ * The two surfaces, and where each keeps its usage.
+ *
+ * Chat Completions and Responses are the same API family with different field names, so the only
+ * thing that varies per surface is which extractor reads the counts and where a stream hides them.
+ */
+const SURFACES = [
+    {
+        path: ['chat', 'completions', 'create'],
+        parse: token_usage_1.fromOpenAIUsage,
+        keys: token_usage_1.METRIC_PATHS.openaiChat,
+        metrics: token_usage_1.OPENAI_CHAT_METRICS,
+        // Reported once, on the final chunk - at the root for OpenAI itself, and under `x_groq` for
+        // Groq, whose chunks carry no top-level `usage` at all. See the header on that second read.
+        streamed: (chunk) => chunk?.usage ?? asTokenUsage(chunk?.x_groq?.usage),
+    },
+    {
+        path: ['responses', 'create'],
+        parse: token_usage_1.fromResponsesUsage,
+        keys: token_usage_1.METRIC_PATHS.openaiResponses,
+        metrics: token_usage_1.OPENAI_RESPONSES_METRICS,
+        // Reported on the completion event, which carries the whole response rather than a delta.
+        streamed: (chunk) => chunk?.response?.usage ?? chunk?.usage,
+    },
+];
+/** The reader for a surface, so a recipe built on top of this one stays in step with it. */
+const openAISurface = (path) => SURFACES.find((surface) => surface.path.join('.') === path.join('.')) ?? SURFACES[0];
+exports.openAISurface = openAISurface;
+exports.openAIRecipe = {
+    vendor: 'openai',
+    metrics: token_usage_1.OPENAI_METRICS,
+    totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+    // Either surface is enough: the recipe governs both, and a client built only for the Responses
+    // API has no `chat.completions` to find.
+    matches: (client) => (0, registry_1.hasMethod)(client, ['chat', 'completions', 'create']) || (0, registry_1.hasMethod)(client, ['responses', 'create']),
+    methods: SURFACES.map(({ path, parse, keys, streamed }) => ({
+        path: [...path],
+        // What OpenAI called it, which is what gets reported, beside the normalized counters. Note
+        // `prompt_tokens` includes the cached tokens reported next to it - the overlap is the
+        // vendor's, kept so the numbers reconcile against its own dashboard.
+        extractUsage: (result) => result?.usage
+            ? { metrics: (0, token_usage_1.pickMetrics)(result.usage, keys), usage: parse(result.usage), raw: result.usage }
+            : undefined,
+        attachStream: (stream, ingest) => {
+            let total = (0, types_1.emptyTokenUsage)();
+            let metrics = {};
+            // As on the non-streamed path, so a streamed turn states its usage just as fully - the
+            // counters this recipe does not name (`total_tokens`, the reasoning-token detail) reach a
+            // meter either way rather than only when the caller happened not to stream.
+            let raw;
+            (0, meter_stream_1.meterStream)(stream, (chunk) => {
+                const usage = streamed(chunk);
+                // Reported once and whole rather than as deltas, so the last one wins outright - which
+                // is also what makes the block safe to keep as it arrived.
+                if (usage) {
+                    total = parse(usage);
+                    metrics = (0, token_usage_1.pickMetrics)(usage, keys);
+                    // Copied, not referenced - it is held until the stream ends, and the chunk it came
+                    // from belongs to the consumer. See the Gemini recipe for the full reasoning.
+                    raw = { ...usage };
+                }
+            }, 
+            // Absent rather than `undefined` when no chunk carried usage - see the Gemini recipe.
+            () => ingest({ metrics, usage: total, ...(raw ? { raw } : {}) }));
+        },
+    })),
+};