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

package/dist/bindings/shared/token-usage.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Provider usage objects -> the SDK's neutral `TokenUsage`.
+ *
+ * The inputs are typed structurally rather than against each vendor's SDK, so this handful of
+ * readers covers a direct client, a gateway response and an orchestrator callback - and adding a
+ * provider whose response happens to match costs nothing. Hence the shape-named reader below:
+ * `fromFlatTokenUsage` is read by every vendor that counts that way, not by one of them.
+ */
+import { type Measurement, type Metrics, type MetricsMapper, type TokenUsage } from '../../types';
+import type { FlatTokenUsage, GeminiLikeUsage, LangChainLikeUsage, OpenAILikeUsage, ResponsesLikeUsage } from './types';
+export declare function fromFlatTokenUsage(usage: FlatTokenUsage | null | undefined): TokenUsage;
+export declare function fromOpenAIUsage(usage: OpenAILikeUsage | null | undefined): TokenUsage;
+/**
+ * OpenAI's Responses API, which counts the same tokens under different names - `input_tokens`
+ * rather than `prompt_tokens`, and the cache detail one level along. Reading it with the Chat
+ * Completions extractor finds none of them and meters the call at zero.
+ */
+export declare function fromResponsesUsage(usage: ResponsesLikeUsage | null | undefined): TokenUsage;
+export declare function fromLangChainUsage(usage: LangChainLikeUsage | null | undefined): TokenUsage;
+/**
+ * Gemini's `usageMetadata`, whose two overlaps run in opposite directions - see `GeminiLikeUsage`
+ * for the vendor's own wording on each.
+ *
+ * The arithmetic is checked by the one invariant the vendor publishes: the four counters below
+ * add back up to `totalTokenCount`, which is why neither overlap may be read the other way.
+ */
+export declare function fromGeminiUsage(usage: GeminiLikeUsage | null | undefined): TokenUsage;
+/**
+ * Any of the three shapes above, recognised by its own fields. Vendors disagree on names but not
+ * enough to be ambiguous, so the caller can pass whatever the response carried.
+ */
+export declare function normalizeUsage(usage: unknown): TokenUsage;
+export declare const addTokenUsage: (into: TokenUsage, add: TokenUsage) => TokenUsage;
+/**
+ * The name a computed total is reported under, for the vendors that publish none of their own.
+ *
+ * `total_tokens` rather than a name of ours, because it is what OpenAI calls the same number and
+ * what a reader expects to find - but it is worth knowing which vendors state it and which get it
+ * from {@link COMPUTED_TOTALS}: Anthropic and TypeSafe publish no total at all, so theirs is the
+ * SDK's arithmetic over counters the vendor *did* state, not a figure off their dashboard.
+ */
+export declare const TOTAL_TOKENS = "total_tokens";
+/** Anthropic's four counters. Disjoint - cache reads and writes are not inside `input_tokens`. */
+export declare const ANTHROPIC_COMPONENT_METRICS: readonly ["input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+/** Those four, plus the total this SDK adds up for them. */
+export declare const ANTHROPIC_METRICS: readonly ["input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "total_tokens"];
+/**
+ * Gemini's five. Two of them overlap in opposite directions and both are reported verbatim, the
+ * way every vendor's are, because a number published under a vendor's field name has to reconcile
+ * against that vendor's own dashboard: `cachedContentTokenCount` is already *inside*
+ * `promptTokenCount`, while `thoughtsTokenCount` and `toolUsePromptTokenCount` sit *outside* the
+ * two headline counters. Price accordingly - or price `normalizedMetrics` instead, which is
+ * disjoint by construction.
+ */
+export declare const GEMINI_METRICS: readonly ["promptTokenCount", "candidatesTokenCount", "cachedContentTokenCount", "thoughtsTokenCount", "toolUsePromptTokenCount", "totalTokenCount"];
+/** What identifies a Gemini usage object: its breakdown, never its total. */
+export declare const GEMINI_COMPONENT_METRICS: readonly ["promptTokenCount", "candidatesTokenCount", "cachedContentTokenCount", "thoughtsTokenCount", "toolUsePromptTokenCount"];
+/**
+ * Chat Completions. `prompt_tokens` **includes** `cached_tokens`, so these two overlap - reported
+ * as the vendor states them, which is what reconciles against its invoice. Whoever prices
+ * `prompt_tokens` must know the cached ones are already inside it.
+ */
+export declare const OPENAI_CHAT_METRICS: readonly ["prompt_tokens", "completion_tokens", "cached_tokens", "total_tokens"];
+/** The Responses API, which overlaps the same way under its own names. */
+export declare const OPENAI_RESPONSES_METRICS: readonly ["input_tokens", "output_tokens", "cached_tokens", "total_tokens"];
+/**
+ * TypeSafe's two. No cache counters and no cost: the API reports what it charged for and stops
+ * there, which was confirmed against the wire rather than inferred from the SDK's types.
+ */
+export declare const TYPESAFE_COMPONENT_METRICS: readonly ["input_tokens", "output_tokens"];
+/** Those two, plus the total this SDK adds up for them. */
+export declare const TYPESAFE_METRICS: readonly ["input_tokens", "output_tokens", "total_tokens"];
+/** Both OpenAI surfaces, which is what one client can report across its two APIs. */
+export declare const OPENAI_METRICS: readonly ["prompt_tokens", "completion_tokens", "input_tokens", "output_tokens", "cached_tokens", "total_tokens"];
+/** A gateway speaks the OpenAI shape and adds the price it charged, under its own field name. */
+export declare const GATEWAY_METRICS: readonly ["prompt_tokens", "completion_tokens", "input_tokens", "output_tokens", "cached_tokens", "total_tokens", "cost"];
+/** The leaf a dotted path reports under - `prompt_tokens_details.cached_tokens` -> `cached_tokens`. */
+export declare const metricName: (path: string) => string;
+/**
+ * Which counters are summed to produce a vendor's total, for the vendors that publish none.
+ *
+ * Only ever disjoint sets: Anthropic's four do not overlap and neither do TypeSafe's two, so the
+ * sum is the whole call and nothing is counted twice. A vendor whose counters overlap - Gemini's
+ * cached tokens sit inside its prompt count, OpenAI's inside theirs - is not in this table,
+ * because adding those up would be arithmetic the vendor never agreed to. Those vendors state a
+ * total themselves and it is read, not computed.
+ */
+export declare const COMPUTED_TOTALS: Record<string, readonly string[]>;
+/**
+ * Adds the computed total to a metrics object, for a vendor that states none of its own.
+ *
+ * Absent rather than zero when nothing was counted, like every other metric here: a call that
+ * measured nothing reports nothing, instead of a zero somebody has to interpret.
+ */
+export declare function withComputedTotal(metrics: Metrics, keys: readonly string[]): Metrics;
+/**
+ * Whether a path list and a name list agree, for the test that keeps them from drifting.
+ *
+ * Two lists describing one thing is the cost of separating where a counter lives from what it is
+ * called. This is what makes that cost a compile-and-test problem rather than a billing one.
+ */
+export declare const metricNamesMatchPaths: (paths: readonly string[], names: readonly string[]) => boolean;
+/** The read paths, for the tests that hold them in step with the names above. */
+export declare const METRIC_PATHS: {
+    readonly anthropic: readonly ["input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
+    readonly openaiChat: readonly ["prompt_tokens", "completion_tokens", "prompt_tokens_details.cached_tokens", "total_tokens"];
+    readonly openaiResponses: readonly ["input_tokens", "output_tokens", "input_tokens_details.cached_tokens", "total_tokens"];
+    readonly typesafe: readonly ["input_tokens", "output_tokens"];
+    readonly gemini: readonly ["promptTokenCount", "candidatesTokenCount", "cachedContentTokenCount", "thoughtsTokenCount", "toolUsePromptTokenCount", "totalTokenCount"];
+};
+/**
+ * Reads the named keys off a vendor's usage object, dotted paths included.
+ *
+ * A nested key reports under its leaf - `prompt_tokens_details.cached_tokens` becomes
+ * `cached_tokens` - because the leaf is the vendor's own name for it and a feature id with a dot
+ * in it reads badly everywhere. Anything absent, fractional or not a number is skipped: a metric
+ * the vendor did not report is not a zero, and Stigg rejects fractions.
+ */
+export declare function pickMetrics(usage: unknown, keys: readonly string[]): Metrics;
+/** Accumulates metrics across a stream, which reports its counters in more than one chunk. */
+export declare const addMetrics: (into: Metrics, add: Metrics) => Metrics;
+/**
+ * The SDK's own four counters, under SDK-owned names, from the normalized measurement.
+ *
+ * The opt-out from vendor names, for an application running more than one provider: these are
+ * disjoint and mean the same thing whoever served the call, so one set of Stigg features covers
+ * every vendor. Pass it as a run's `metrics`.
+ */
+export declare const normalizedMetrics: MetricsMapper;
+/** The shapes a gateway can be told it observed, since guessing reports to the wrong features. */
+/**
+ * The shapes a proxy can be told it observed.
+ *
+ * Named for the vendor rather than for the shape, because a proxy operator knows what is behind
+ * them and not what its usage object looks like - but it is the shape that is being selected,
+ * which is why OpenAI appears twice. Its two APIs spell the same counters differently, and
+ * `openai-responses` is that surface rather than a vendor of its own.
+ */
+export type ObservedVendor = 'anthropic' | 'typesafe' | 'openai' | 'openai-responses' | 'gemini';
+/**
+ * Both views of a usage object a proxy observed, for the ingest path that has no recipe.
+ *
+ * The vendor is named rather than sniffed. `normalizeUsage` guesses from the object's own fields
+ * and says itself that Anthropic and the Responses API are ambiguous - both count `input_tokens`.
+ * A wrong guess would report to another meter entirely, which nothing downstream can undo - so
+ * an unnamed vendor reports nothing raw and leaves the normalized counters to a mapper.
+ */
+export declare function observedMeasurement(usage: unknown, vendor?: ObservedVendor): Measurement;

package/dist/bindings/shared/token-usage.js

@@ -0,0 +1,414 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizedMetrics = exports.addMetrics = exports.METRIC_PATHS = exports.metricNamesMatchPaths = exports.COMPUTED_TOTALS = exports.metricName = exports.GATEWAY_METRICS = exports.OPENAI_METRICS = exports.TYPESAFE_METRICS = exports.TYPESAFE_COMPONENT_METRICS = exports.OPENAI_RESPONSES_METRICS = exports.OPENAI_CHAT_METRICS = exports.GEMINI_COMPONENT_METRICS = exports.GEMINI_METRICS = exports.ANTHROPIC_METRICS = exports.ANTHROPIC_COMPONENT_METRICS = exports.TOTAL_TOKENS = exports.addTokenUsage = void 0;
+exports.fromFlatTokenUsage = fromFlatTokenUsage;
+exports.fromOpenAIUsage = fromOpenAIUsage;
+exports.fromResponsesUsage = fromResponsesUsage;
+exports.fromLangChainUsage = fromLangChainUsage;
+exports.fromGeminiUsage = fromGeminiUsage;
+exports.normalizeUsage = normalizeUsage;
+exports.withComputedTotal = withComputedTotal;
+exports.pickMetrics = pickMetrics;
+exports.observedMeasurement = observedMeasurement;
+/**
+ * Provider usage objects -> the SDK's neutral `TokenUsage`.
+ *
+ * The inputs are typed structurally rather than against each vendor's SDK, so this handful of
+ * readers covers a direct client, a gateway response and an orchestrator callback - and adding a
+ * provider whose response happens to match costs nothing. Hence the shape-named reader below:
+ * `fromFlatTokenUsage` is read by every vendor that counts that way, not by one of them.
+ */
+const types_1 = require("../../types");
+const n = (value) => (typeof value === 'number' && value > 0 ? value : 0);
+function fromFlatTokenUsage(usage) {
+    if (!usage)
+        return (0, types_1.emptyTokenUsage)();
+    const counted = {
+        input: n(usage.input_tokens),
+        output: n(usage.output_tokens),
+        cacheRead: n(usage.cache_read_input_tokens),
+        cacheCreate: n(usage.cache_creation_input_tokens),
+    };
+    // No vendor on this shape publishes a total, and these four are disjoint - cache reads and
+    // writes sit beside the input count rather than inside it - so their sum is the whole call.
+    return { ...counted, ...withTotal(counted.input + counted.output + counted.cacheRead + counted.cacheCreate) };
+}
+/** `{ total }` when there is one to state, and nothing at all when there is not. */
+const withTotal = (total) => (total > 0 ? { total } : {});
+function fromOpenAIUsage(usage) {
+    if (!usage)
+        return (0, types_1.emptyTokenUsage)();
+    const cacheRead = n(usage.prompt_tokens_details?.cached_tokens);
+    return {
+        // OpenAI states its own, and a stated total beats one reassembled from the parts.
+        ...withTotal(n(usage.total_tokens)),
+        // OpenAI counts cached prompt tokens inside prompt_tokens, so subtract to avoid double-count.
+        input: Math.max(0, n(usage.prompt_tokens) - cacheRead),
+        output: n(usage.completion_tokens),
+        cacheRead,
+        cacheCreate: n(usage.prompt_tokens_details?.cache_write_tokens),
+    };
+}
+/**
+ * OpenAI's Responses API, which counts the same tokens under different names - `input_tokens`
+ * rather than `prompt_tokens`, and the cache detail one level along. Reading it with the Chat
+ * Completions extractor finds none of them and meters the call at zero.
+ */
+function fromResponsesUsage(usage) {
+    if (!usage)
+        return (0, types_1.emptyTokenUsage)();
+    const cacheRead = n(usage.input_tokens_details?.cached_tokens);
+    return {
+        ...withTotal(n(usage.total_tokens)),
+        // As with chat completions, cached tokens are counted inside the input total.
+        input: Math.max(0, n(usage.input_tokens) - cacheRead),
+        output: n(usage.output_tokens),
+        cacheRead,
+        // The surface reports no cache writes of its own.
+        cacheCreate: 0,
+    };
+}
+function fromLangChainUsage(usage) {
+    if (!usage)
+        return (0, types_1.emptyTokenUsage)();
+    const cacheRead = n(usage.input_token_details?.cache_read);
+    const cacheCreate = n(usage.input_token_details?.cache_creation);
+    return {
+        input: Math.max(0, n(usage.input_tokens) - cacheRead - cacheCreate),
+        output: n(usage.output_tokens),
+        cacheRead,
+        cacheCreate,
+    };
+}
+/**
+ * Gemini's `usageMetadata`, whose two overlaps run in opposite directions - see `GeminiLikeUsage`
+ * for the vendor's own wording on each.
+ *
+ * The arithmetic is checked by the one invariant the vendor publishes: the four counters below
+ * add back up to `totalTokenCount`, which is why neither overlap may be read the other way.
+ */
+function fromGeminiUsage(usage) {
+    if (!usage)
+        return (0, types_1.emptyTokenUsage)();
+    const cacheRead = n(usage.cachedContentTokenCount);
+    return {
+        // Gemini's own, under its own name. Never recomputed from the counters below: they overlap,
+        // and the vendor's figure is the one its invoice will show.
+        ...withTotal(n(usage.totalTokenCount)),
+        // Cached content is counted inside the prompt total, so subtract it rather than bill it
+        // twice. Tool-use prompt tokens are not inside it - `totalTokenCount` adds them alongside -
+        // so they are input this would otherwise drop entirely.
+        input: Math.max(0, n(usage.promptTokenCount) - cacheRead) + n(usage.toolUsePromptTokenCount),
+        // Thinking tokens are billed as output and counted beside the candidates, not within them.
+        output: n(usage.candidatesTokenCount) + n(usage.thoughtsTokenCount),
+        cacheRead,
+        // Nothing to read: an explicit cache is written by `caches.create`, a separate call whose own
+        // response carries the token count for it. A generation reports only what it read.
+        cacheCreate: 0,
+    };
+}
+/**
+ * Any of the three shapes above, recognised by its own fields. Vendors disagree on names but not
+ * enough to be ambiguous, so the caller can pass whatever the response carried.
+ */
+function normalizeUsage(usage) {
+    if (!usage || typeof usage !== 'object')
+        return (0, types_1.emptyTokenUsage)();
+    const raw = usage;
+    // Already normalized - a caller doing its own accounting. Recognised by any of the four, not
+    // only the cache pair: an application that counts input and output and has no cache to report
+    // used to fall past this to the flat vendor reader, which looks for `input_tokens` and finds
+    // none - so `{ input: 600, output: 400 }` normalized to zeroes and metered the turn as nothing.
+    //
+    // Rebuilt from all four either way: a partial object leaves the rest undefined, and
+    // `undefined + number` is NaN, which the mapper would pass on as a measurement of nothing.
+    if (typeof raw.cacheRead === 'number' ||
+        typeof raw.cacheCreate === 'number' ||
+        typeof raw.input === 'number' ||
+        typeof raw.output === 'number') {
+        return { input: n(raw.input), output: n(raw.output), cacheRead: n(raw.cacheRead), cacheCreate: n(raw.cacheCreate) };
+    }
+    if ('prompt_tokens' in raw || 'completion_tokens' in raw)
+        return fromOpenAIUsage(raw);
+    // Any one of Gemini's counters identifies it - they share no name with the shapes above, and
+    // one is all a caller may send. Read off the component list so the two cannot drift, and keyed
+    // on a *numeric* value: `in` is true for a key whose value is `undefined`, which a payload
+    // built by spreading optional fields carries, and that read someone else's counts as zero.
+    if (exports.GEMINI_COMPONENT_METRICS.some((key) => typeof raw[key] === 'number'))
+        return fromGeminiUsage(raw);
+    if ('input_token_details' in raw)
+        return fromLangChainUsage(raw);
+    // Three shapes count `input_tokens`/`output_tokens` - the flat one, the Responses API and
+    // LangChain - so the fallback reads any of them happily. Both nested shapes are claimed above
+    // by the detail key they carry, because falling through to the flat reader would silently drop
+    // the cache detail and overstate the input it was hiding inside.
+    if ('input_tokens_details' in raw)
+        return fromResponsesUsage(raw);
+    return fromFlatTokenUsage(raw);
+}
+/** Nothing counted and nothing stated: an accumulator before its first round, not a round. */
+const isNeutral = (usage) => usage.total === undefined && !usage.input && !usage.output && !usage.cacheRead && !usage.cacheCreate;
+const addTokenUsage = (into, add) => {
+    // Summed across the rounds of one call, but only while every round states one. A round that
+    // stated none makes the call's total unstateable, and passing the other round's on as if it
+    // were the whole understates the call silently - the failure this file exists to avoid. An
+    // empty accumulator is not a round, so it does not count as one that said nothing.
+    const total = isNeutral(into)
+        ? add.total
+        : isNeutral(add)
+            ? into.total
+            : into.total !== undefined && add.total !== undefined
+                ? into.total + add.total
+                : undefined;
+    return {
+        input: into.input + add.input,
+        output: into.output + add.output,
+        cacheRead: into.cacheRead + add.cacheRead,
+        cacheCreate: into.cacheCreate + add.cacheCreate,
+        ...(total !== undefined ? { total } : {}),
+    };
+};
+exports.addTokenUsage = addTokenUsage;
+// ---------------------------------------------------------------------------------------------
+// The vendor's own names, for the reports a run sends by default.
+//
+// Explicit key lists, never a walk over the response. A blind walk would report `cost` (a float
+// Stigg rejects) or `service_tier` (a string) - and worse, the day a vendor adds a counter the
+// SDK would start reporting a feature the customer's catalog has never heard of, failing every
+// call from then on. A vendor's changelog must not be able to inject feature ids into a bill.
+//
+// Every vendor reports a **total** as well as its breakdown, and the two deliberately overlap.
+// The breakdown answers "what did this call spend it on" and the total answers "what did it
+// cost"; only the customer's catalog knows which of those it bills, so both are sent and neither
+// is chosen on their behalf. Pricing a total *and* a component underneath it bills those tokens
+// twice - `normalizedMetrics` is the disjoint alternative for anyone who would rather not think
+// about it, and the README's overlap table says which counters nest inside which.
+//
+// Where the vendor publishes a total it is read, never recomputed. Where it publishes none -
+// Anthropic and TypeSafe - it is summed from counters that are disjoint, which is the only case
+// where adding them up is the vendor's own arithmetic rather than ours. See `COMPUTED_TOTALS`.
+// ---------------------------------------------------------------------------------------------
+// Where a counter is read and what it ends up called are the same string for Anthropic and are
+// not for OpenAI, which nests its cache detail. One list cannot be both, so the paths stay
+// private to the surface that reads them and only the reported names are exported - those are
+// what a mapper receives, and what Stigg meters. `metricNamesMatchPaths` holds the two in step.
+/** Where to read each counter off an Anthropic response. Flat, so the paths are the names. */
+const ANTHROPIC_PATHS = [
+    'input_tokens',
+    'output_tokens',
+    'cache_read_input_tokens',
+    'cache_creation_input_tokens',
+];
+/** TypeSafe reports two flat counters and nothing else, so the paths are the names again. */
+const TYPESAFE_PATHS = ['input_tokens', 'output_tokens'];
+/**
+ * The counters Gemini breaks a call down into. Flat, so the paths are the names.
+ *
+ * Kept apart from the reported list because these are also what *identifies* a Gemini usage
+ * object to `normalizeUsage`. A total is not identifying - more than one vendor has one - so
+ * recognising a payload by `totalTokenCount` would route an object that counted its tokens some
+ * other way into the Gemini reader, which finds none of these and meters it at zero.
+ */
+const GEMINI_COMPONENT_PATHS = [
+    'promptTokenCount',
+    'candidatesTokenCount',
+    'cachedContentTokenCount',
+    'thoughtsTokenCount',
+    'toolUsePromptTokenCount',
+];
+/** Those, plus the vendor's own total. */
+const GEMINI_PATHS = [...GEMINI_COMPONENT_PATHS, 'totalTokenCount'];
+/** Chat Completions keeps its cache detail one level down; the leaf is what gets reported. */
+const OPENAI_CHAT_PATHS = [
+    'prompt_tokens',
+    'completion_tokens',
+    'prompt_tokens_details.cached_tokens',
+    'total_tokens',
+];
+/** The Responses API counts the same tokens under different names, nested the same way. */
+const OPENAI_RESPONSES_PATHS = [
+    'input_tokens',
+    'output_tokens',
+    'input_tokens_details.cached_tokens',
+    'total_tokens',
+];
+/**
+ * The name a computed total is reported under, for the vendors that publish none of their own.
+ *
+ * `total_tokens` rather than a name of ours, because it is what OpenAI calls the same number and
+ * what a reader expects to find - but it is worth knowing which vendors state it and which get it
+ * from {@link COMPUTED_TOTALS}: Anthropic and TypeSafe publish no total at all, so theirs is the
+ * SDK's arithmetic over counters the vendor *did* state, not a figure off their dashboard.
+ */
+exports.TOTAL_TOKENS = 'total_tokens';
+/** Anthropic's four counters. Disjoint - cache reads and writes are not inside `input_tokens`. */
+exports.ANTHROPIC_COMPONENT_METRICS = [
+    'input_tokens',
+    'output_tokens',
+    'cache_read_input_tokens',
+    'cache_creation_input_tokens',
+];
+/** Those four, plus the total this SDK adds up for them. */
+exports.ANTHROPIC_METRICS = [...exports.ANTHROPIC_COMPONENT_METRICS, exports.TOTAL_TOKENS];
+/**
+ * Gemini's five. Two of them overlap in opposite directions and both are reported verbatim, the
+ * way every vendor's are, because a number published under a vendor's field name has to reconcile
+ * against that vendor's own dashboard: `cachedContentTokenCount` is already *inside*
+ * `promptTokenCount`, while `thoughtsTokenCount` and `toolUsePromptTokenCount` sit *outside* the
+ * two headline counters. Price accordingly - or price `normalizedMetrics` instead, which is
+ * disjoint by construction.
+ */
+exports.GEMINI_METRICS = GEMINI_PATHS;
+/** What identifies a Gemini usage object: its breakdown, never its total. */
+exports.GEMINI_COMPONENT_METRICS = GEMINI_COMPONENT_PATHS;
+/**
+ * Chat Completions. `prompt_tokens` **includes** `cached_tokens`, so these two overlap - reported
+ * as the vendor states them, which is what reconciles against its invoice. Whoever prices
+ * `prompt_tokens` must know the cached ones are already inside it.
+ */
+exports.OPENAI_CHAT_METRICS = ['prompt_tokens', 'completion_tokens', 'cached_tokens', 'total_tokens'];
+/** The Responses API, which overlaps the same way under its own names. */
+exports.OPENAI_RESPONSES_METRICS = ['input_tokens', 'output_tokens', 'cached_tokens', 'total_tokens'];
+/**
+ * TypeSafe's two. No cache counters and no cost: the API reports what it charged for and stops
+ * there, which was confirmed against the wire rather than inferred from the SDK's types.
+ */
+exports.TYPESAFE_COMPONENT_METRICS = ['input_tokens', 'output_tokens'];
+/** Those two, plus the total this SDK adds up for them. */
+exports.TYPESAFE_METRICS = [...exports.TYPESAFE_COMPONENT_METRICS, exports.TOTAL_TOKENS];
+/** Both OpenAI surfaces, which is what one client can report across its two APIs. */
+exports.OPENAI_METRICS = [
+    'prompt_tokens',
+    'completion_tokens',
+    'input_tokens',
+    'output_tokens',
+    'cached_tokens',
+    'total_tokens',
+];
+/** A gateway speaks the OpenAI shape and adds the price it charged, under its own field name. */
+exports.GATEWAY_METRICS = [...exports.OPENAI_METRICS, 'cost'];
+/** The leaf a dotted path reports under - `prompt_tokens_details.cached_tokens` -> `cached_tokens`. */
+const metricName = (path) => path.split('.').pop();
+exports.metricName = metricName;
+/**
+ * Which counters are summed to produce a vendor's total, for the vendors that publish none.
+ *
+ * Only ever disjoint sets: Anthropic's four do not overlap and neither do TypeSafe's two, so the
+ * sum is the whole call and nothing is counted twice. A vendor whose counters overlap - Gemini's
+ * cached tokens sit inside its prompt count, OpenAI's inside theirs - is not in this table,
+ * because adding those up would be arithmetic the vendor never agreed to. Those vendors state a
+ * total themselves and it is read, not computed.
+ */
+exports.COMPUTED_TOTALS = {
+    anthropic: exports.ANTHROPIC_COMPONENT_METRICS,
+    typesafe: exports.TYPESAFE_COMPONENT_METRICS,
+};
+/**
+ * Adds the computed total to a metrics object, for a vendor that states none of its own.
+ *
+ * Absent rather than zero when nothing was counted, like every other metric here: a call that
+ * measured nothing reports nothing, instead of a zero somebody has to interpret.
+ */
+function withComputedTotal(metrics, keys) {
+    const total = keys.reduce((sum, key) => sum + (metrics[key] ?? 0), 0);
+    return total > 0 ? { ...metrics, [exports.TOTAL_TOKENS]: total } : metrics;
+}
+/**
+ * Whether a path list and a name list agree, for the test that keeps them from drifting.
+ *
+ * Two lists describing one thing is the cost of separating where a counter lives from what it is
+ * called. This is what makes that cost a compile-and-test problem rather than a billing one.
+ */
+const metricNamesMatchPaths = (paths, names) => {
+    const fromPaths = [...new Set(paths.map(exports.metricName))];
+    return fromPaths.length === names.length && fromPaths.every((name) => names.includes(name));
+};
+exports.metricNamesMatchPaths = metricNamesMatchPaths;
+/** The read paths, for the tests that hold them in step with the names above. */
+exports.METRIC_PATHS = {
+    anthropic: ANTHROPIC_PATHS,
+    openaiChat: OPENAI_CHAT_PATHS,
+    openaiResponses: OPENAI_RESPONSES_PATHS,
+    typesafe: TYPESAFE_PATHS,
+    gemini: GEMINI_PATHS,
+};
+/**
+ * Reads the named keys off a vendor's usage object, dotted paths included.
+ *
+ * A nested key reports under its leaf - `prompt_tokens_details.cached_tokens` becomes
+ * `cached_tokens` - because the leaf is the vendor's own name for it and a feature id with a dot
+ * in it reads badly everywhere. Anything absent, fractional or not a number is skipped: a metric
+ * the vendor did not report is not a zero, and Stigg rejects fractions.
+ */
+function pickMetrics(usage, keys) {
+    if (!usage || typeof usage !== 'object')
+        return {};
+    const metrics = {};
+    for (const key of keys) {
+        const value = key.split('.').reduce((node, part) => (node == null ? node : node[part]), usage);
+        if (typeof value === 'number' && Number.isInteger(value) && value > 0) {
+            metrics[key.split('.').pop()] = value;
+        }
+    }
+    return metrics;
+}
+/** Accumulates metrics across a stream, which reports its counters in more than one chunk. */
+const addMetrics = (into, add) => {
+    const summed = { ...into };
+    for (const [key, value] of Object.entries(add))
+        summed[key] = (summed[key] ?? 0) + value;
+    return summed;
+};
+exports.addMetrics = addMetrics;
+/**
+ * The SDK's own four counters, under SDK-owned names, from the normalized measurement.
+ *
+ * The opt-out from vendor names, for an application running more than one provider: these are
+ * disjoint and mean the same thing whoever served the call, so one set of Stigg features covers
+ * every vendor. Pass it as a run's `metrics`.
+ */
+const normalizedMetrics = ({ usage }) => {
+    if (!usage)
+        return {};
+    const metrics = {};
+    if (usage.input > 0)
+        metrics.stigg_input_tokens = usage.input;
+    if (usage.output > 0)
+        metrics.stigg_output_tokens = usage.output;
+    if (usage.cacheRead > 0)
+        metrics.stigg_cache_read_tokens = usage.cacheRead;
+    if (usage.cacheCreate > 0)
+        metrics.stigg_cache_creation_tokens = usage.cacheCreate;
+    return metrics;
+};
+exports.normalizedMetrics = normalizedMetrics;
+// Read paths, not reported names: OpenAI keeps its cache detail nested, so the name alone finds
+// nothing there. Anthropic and TypeSafe share the flat shape and differ only in how much of it
+// they fill in, so a proxy fronting either reads the same paths - but it still has to be able to
+// say which, rather than being told to pass the other vendor's name and know why.
+const METRIC_KEYS = {
+    anthropic: exports.METRIC_PATHS.anthropic,
+    typesafe: exports.METRIC_PATHS.typesafe,
+    openai: exports.METRIC_PATHS.openaiChat,
+    'openai-responses': exports.METRIC_PATHS.openaiResponses,
+    gemini: exports.METRIC_PATHS.gemini,
+};
+/**
+ * Both views of a usage object a proxy observed, for the ingest path that has no recipe.
+ *
+ * The vendor is named rather than sniffed. `normalizeUsage` guesses from the object's own fields
+ * and says itself that Anthropic and the Responses API are ambiguous - both count `input_tokens`.
+ * A wrong guess would report to another meter entirely, which nothing downstream can undo - so
+ * an unnamed vendor reports nothing raw and leaves the normalized counters to a mapper.
+ */
+function observedMeasurement(usage, vendor) {
+    return {
+        metrics: vendor ? pickMetrics(usage, METRIC_KEYS[vendor]) : {},
+        usage: normalizeUsage(usage),
+        // Kept whole for an event to carry, and it does not depend on naming the vendor: a dimension
+        // is something a meter reads deliberately, not a feature id a wrong guess could invent.
+        // An array is an object and is not this: `Object.entries` would flatten it to `raw.0`,
+        // `raw.1`, ... - dimensions named after positions in a list nobody meant to send.
+        raw: usage && typeof usage === 'object' && !Array.isArray(usage) ? usage : undefined,
+    };
+}

package/dist/bindings/shared/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The vendor response shapes these converters read.
+ *
+ * Typed structurally rather than against each vendor's SDK, so the same handful of functions cover
+ * a direct client, a gateway response and an orchestrator callback - and adding a provider whose
+ * response happens to match costs nothing.
+ */
+/**
+ * A flat `usage` object whose cache counters sit BESIDE the input count rather than inside it.
+ *
+ * Named for the shape, not for a vendor, because more than one reports it: Anthropic's Messages
+ * API and TypeSafe's System One, which carries only the first two. The distinction from the two
+ * shapes below is the whole reason this is a separate reader - they spell the same two counters
+ * the same way but count their cached tokens *within* the input total, so reading one as the
+ * other double-counts in one direction or overstates in the other.
+ */
+export type FlatTokenUsage = {
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
+    cache_creation_input_tokens?: number | null;
+};
+/** OpenAI-compatible `usage` - also what OpenRouter and most gateways return. */
+export type OpenAILikeUsage = {
+    prompt_tokens?: number | null;
+    completion_tokens?: number | null;
+    /** The vendor's own total. `prompt_tokens + completion_tokens`; cached tokens are inside the first. */
+    total_tokens?: number | null;
+    prompt_tokens_details?: {
+        cached_tokens?: number | null;
+        cache_write_tokens?: number | null;
+    } | null;
+};
+/** OpenAI's Responses API `usage` - the same counts as above under different names. */
+export type ResponsesLikeUsage = {
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    /** The vendor's own total, under the same name the Chat Completions shape uses. */
+    total_tokens?: number | null;
+    input_tokens_details?: {
+        cached_tokens?: number | null;
+    } | null;
+};
+/** LangChain's `usage_metadata`, as carried on an AIMessage. */
+export type LangChainLikeUsage = {
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    input_token_details?: {
+        cache_read?: number | null;
+        cache_creation?: number | null;
+    } | null;
+};
+/**
+ * Gemini's `usageMetadata`, which counts in its own names and overlaps in two directions at once.
+ *
+ * Both overlaps are quoted from the vendor's own field docs, because each one is a doubled or
+ * halved bill if read the other way round:
+ *
+ * - `promptTokenCount` - "when `cached_content` is set, this **also includes** the number of
+ *   tokens in the cached content", so `cachedContentTokenCount` is counted *inside* it, the way
+ *   OpenAI nests `cached_tokens` inside `prompt_tokens`.
+ * - `totalTokenCount` - "the sum of `prompt_token_count`, `candidates_token_count`,
+ *   `tool_use_prompt_token_count`, and `thoughts_token_count`", so the last two sit *beside* the
+ *   first two rather than within them. Thinking tokens in particular are billed as output and
+ *   are **not** inside `candidatesTokenCount`: a reader that ignores them undercounts the output
+ *   of every reasoning model this vendor sells.
+ */
+export type GeminiLikeUsage = {
+    /**
+     * The vendor's own total: `promptTokenCount + candidatesTokenCount + toolUsePromptTokenCount +
+     * thoughtsTokenCount`, with the cached count already inside the first. Read, never recomputed.
+     */
+    totalTokenCount?: number | null;
+    promptTokenCount?: number | null;
+    candidatesTokenCount?: number | null;
+    cachedContentTokenCount?: number | null;
+    thoughtsTokenCount?: number | null;
+    toolUsePromptTokenCount?: number | null;
+};

package/dist/bindings/shared/types.js

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