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

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 } : {}) }));
+        },
+    })),
+};

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

@@ -0,0 +1,44 @@
+import type { MetricsFor, MetricsOf } from '../../core/types';
+export declare const typesafeRecipe: {
+    vendor: string;
+    metrics: readonly ["input_tokens", "output_tokens", "total_tokens"];
+    totalTokensMetric: "total_tokens";
+    /**
+     * `systemOne` is the whole surface - unlike Anthropic there is no second call style to prove,
+     * because it is the only thing that reaches the wire carrying usage.
+     *
+     * The exclusion names the one client that collides: `ollama` ships a `systemone` method whose
+     * request and response are the *same shape* as this one, so casing would otherwise be the only
+     * thing between them. Excluding that client by its own three-marker guard - rather than
+     * demanding extra methods here - keeps this recipe claiming anything that exposes `systemOne`,
+     * a thin adapter or a test double included, while making the two guards mutually exclusive
+     * whatever order a registry consults them in.
+     */
+    matches: (client: unknown) => boolean;
+    methods: {
+        path: string[];
+        extractUsage: (result: any) => {
+            metrics: import("../../../..").Metrics;
+            usage: import("../../../..").TokenUsage;
+            raw: any;
+        } | undefined;
+    }[];
+};
+/**
+ * A pre-call estimate from the size of the document being asked about.
+ *
+ * Opt-in, like every estimate here, but note what makes this one different from a chat vendor's:
+ * there is no `max_tokens` to read, and the output is not where the money goes. A batch of
+ * questions against one document runs input-heavy by a wide margin - the document is sent once
+ * and each question adds almost nothing - so the state is the only part worth estimating, and
+ * estimating it is unusually reliable because it is already in hand before the call.
+ *
+ * `charsPerToken` is the usual rough divisor for English prose. Deliberately a floor: an estimate
+ * that overshoots denies calls the budget could have afforded, and the ingest that follows
+ * corrects the balance either way.
+ */
+export declare const estimateFromState: (tokensPerUnit?: number, charsPerToken?: number) => (params: any) => number;
+/** One of the metric names TypeSafe reports. */
+export type TypeSafeMetric = MetricsOf<typeof typesafeRecipe>;
+/** What a mapper reads off a TypeSafe call: those names, each possibly absent. */
+export type TypeSafeMetrics = MetricsFor<typeof typesafeRecipe>;

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

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateFromState = exports.typesafeRecipe = void 0;
+/**
+ * The TypeSafe recipe - the smallest one here, and worth reading for what it leaves out.
+ *
+ * TypeSafe is not chat-shaped. One `systemOne` call carries a document and a whole set of typed
+ * questions and comes back, once, with every answer and a single usage record. So there is one
+ * method to gate, no second call style reaching the wire through it, and no `attachStream`:
+ * nothing streams, so there is no later report to accumulate.
+ *
+ * The metrics are the two the API reports. That was checked against the wire, not inferred from
+ * the SDK's types - the response body carries `model`, `answers` and `usage`, and `usage` carries
+ * `input_tokens` and `output_tokens` and nothing else. No cache counters, because there is no
+ * prompt to cache across turns; no `cost`, because TypeSafe is not a gateway reselling someone
+ * else's model.
+ */
+const token_usage_1 = require("../../../shared/token-usage");
+const estimate_1 = require("../../../shared/estimate");
+const registry_1 = require("../../core/registry");
+const ollama_recipe_1 = require("../ollama/ollama-recipe");
+exports.typesafeRecipe = {
+    vendor: 'typesafe',
+    metrics: token_usage_1.TYPESAFE_METRICS,
+    totalTokensMetric: token_usage_1.TOTAL_TOKENS,
+    /**
+     * `systemOne` is the whole surface - unlike Anthropic there is no second call style to prove,
+     * because it is the only thing that reaches the wire carrying usage.
+     *
+     * The exclusion names the one client that collides: `ollama` ships a `systemone` method whose
+     * request and response are the *same shape* as this one, so casing would otherwise be the only
+     * thing between them. Excluding that client by its own three-marker guard - rather than
+     * demanding extra methods here - keeps this recipe claiming anything that exposes `systemOne`,
+     * a thin adapter or a test double included, while making the two guards mutually exclusive
+     * whatever order a registry consults them in.
+     */
+    matches: (client) => (0, registry_1.hasMethod)(client, ['systemOne']) && !ollama_recipe_1.ollamaRecipe.matches(client),
+    methods: [
+        {
+            path: ['systemOne'],
+            // Both views of the call: TypeSafe's own names, which is what gets reported, and the
+            // normalized counters. The flat reader covers this shape exactly - the two cache counters
+            // it also looks for are absent here, which reads as zero, which is true.
+            extractUsage: (result) => result?.usage
+                ? {
+                    // No total is published here either, so one is added up from the two counters
+                    // that 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.METRIC_PATHS.typesafe), token_usage_1.COMPUTED_TOTALS.typesafe),
+                    usage: (0, token_usage_1.fromFlatTokenUsage)(result.usage),
+                    // Kept whole for an event to carry, the same as every other recipe.
+                    raw: result.usage,
+                }
+                : undefined,
+        },
+    ],
+};
+/**
+ * A pre-call estimate from the size of the document being asked about.
+ *
+ * Opt-in, like every estimate here, but note what makes this one different from a chat vendor's:
+ * there is no `max_tokens` to read, and the output is not where the money goes. A batch of
+ * questions against one document runs input-heavy by a wide margin - the document is sent once
+ * and each question adds almost nothing - so the state is the only part worth estimating, and
+ * estimating it is unusually reliable because it is already in hand before the call.
+ *
+ * `charsPerToken` is the usual rough divisor for English prose. Deliberately a floor: an estimate
+ * that overshoots denies calls the budget could have afforded, and the ingest that follows
+ * corrects the balance either way.
+ */
+const estimateFromState = (tokensPerUnit = 1, charsPerToken = 4) => {
+    // Its own divisor, refused on the same terms as the rate: a zero here divides inside the
+    // reading, which `requestedUnits` would clamp back to one unit just as quietly.
+    (0, estimate_1.requirePositiveRate)('charsPerToken', charsPerToken);
+    return (0, estimate_1.estimateUnits)((params) => {
+        const state = params?.state;
+        // Nothing to measure lands on the floor of one unit, like a call that named no ceiling.
+        if (state == null)
+            return 0;
+        const characters = typeof state === 'string' ? state.length : JSON.stringify(state).length;
+        return characters / charsPerToken;
+    }, tokensPerUnit);
+};
+exports.estimateFromState = estimateFromState;