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

package/dist/bindings/proxy/headers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The gateway binding is generic on purpose: a gateway sees HTTP requests, not SDK calls, so
+ * there is nothing vendor-specific to adapt. What travels is attribution.
+ */
+export { GOVERNANCE_HEADERS, parseGovernanceHeaders } from '../../headers';
+export type { GovernanceHeaders, ParsedGovernanceHeaders } from '../../headers';

package/dist/bindings/proxy/headers.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = void 0;
+/**
+ * The gateway binding is generic on purpose: a gateway sees HTTP requests, not SDK calls, so
+ * there is nothing vendor-specific to adapt. What travels is attribution.
+ */
+var headers_1 = require("../../headers");
+Object.defineProperty(exports, "GOVERNANCE_HEADERS", { enumerable: true, get: function () { return headers_1.GOVERNANCE_HEADERS; } });
+Object.defineProperty(exports, "parseGovernanceHeaders", { enumerable: true, get: function () { return headers_1.parseGovernanceHeaders; } });
+// Attribution to send with a request is `run.headers()` on the handle itself - the run owns the
+// three values, so a free function here could only copy them back out of it.

package/dist/bindings/proxy/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Ingest-only, by design.
+ *
+ * A gateway is out-of-process and sees requests, not runs: it cannot provision, cannot check
+ * against run-scoped state, and cannot archive. What works is splitting the lifecycle across the
+ * boundary - the application provisions and checks in-process, the attribution travels as
+ * headers, and the gateway ingests against it. Governance never leaves the process.
+ *
+ * Both halves of that are methods, not free functions: `run.headers()` writes the attribution and
+ * `stigg.ingestFromHeaders(...)` reads it back. This module is the header contract and the input
+ * shape they agree on.
+ */
+export { GOVERNANCE_HEADERS, parseGovernanceHeaders } from './headers';
+export type { GovernanceHeaders, ParsedGovernanceHeaders } from './headers';
+export type * from './types';
+/**
+ * The proxy's one vendor-shaped decision, re-exported from where it is implemented so it sits
+ * beside the call that takes it. A proxy has no response object to adapt - there is no recipe out
+ * here - so naming the shape it observed is the whole of what it can say about the vendor.
+ */
+export type { ObservedVendor } from '../shared/token-usage';

package/dist/bindings/proxy/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGovernanceHeaders = exports.GOVERNANCE_HEADERS = void 0;
+/**
+ * Ingest-only, by design.
+ *
+ * A gateway is out-of-process and sees requests, not runs: it cannot provision, cannot check
+ * against run-scoped state, and cannot archive. What works is splitting the lifecycle across the
+ * boundary - the application provisions and checks in-process, the attribution travels as
+ * headers, and the gateway ingests against it. Governance never leaves the process.
+ *
+ * Both halves of that are methods, not free functions: `run.headers()` writes the attribution and
+ * `stigg.ingestFromHeaders(...)` reads it back. This module is the header contract and the input
+ * shape they agree on.
+ */
+var headers_1 = require("./headers");
+Object.defineProperty(exports, "GOVERNANCE_HEADERS", { enumerable: true, get: function () { return headers_1.GOVERNANCE_HEADERS; } });
+Object.defineProperty(exports, "parseGovernanceHeaders", { enumerable: true, get: function () { return headers_1.parseGovernanceHeaders; } });

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

@@ -0,0 +1,8 @@
+/** What this binding accepts: the run's context, plus what only the request itself can say. */
+import type { IngestContext } from '../../types';
+export type ProxyIngestInput = IngestContext & {
+    /** Whatever the vendor reported; the shape is recognised on the way in. */
+    usage: unknown;
+    /** The gateway's own request id is the natural key - it is stable across its retries. */
+    idempotencyKey: string;
+};

package/dist/bindings/proxy/types.js

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

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

@@ -0,0 +1,27 @@
+/**
+ * Turning a vendor's own request parameters into "how many units should this call ask for".
+ *
+ * Every vendor states a ceiling for the answer it is about to generate, under its own name -
+ * `max_tokens`, `config.maxOutputTokens`, a document whose length stands in for one - and what
+ * happens to that number afterwards is identical: divide by the rate, round up, never ask for
+ * less than one. Only the reading differs, so only the reading stays with the recipe.
+ *
+ * All of these are opt-in. The default asks for a single unit, because an estimate that
+ * overshoots denies calls the budget could have afforded, and the ingest that follows corrects
+ * the balance anyway.
+ */
+/**
+ * Refuses a rate that cannot divide, where it is configured rather than where it is used.
+ *
+ * Zero divides to `Infinity` and a negative to less than one; `requestedUnits` in the wrapper
+ * clamps both back to asking for a single unit, so a misconfigured rate would gate on nothing and
+ * never say so. Failing here makes that a startup error instead of a quiet one, per call, forever.
+ */
+export declare function requirePositiveRate(name: string, value: number): void;
+/**
+ * The shared half: a rate, a reading, and the arithmetic between them.
+ *
+ * `read` returns the vendor's ceiling in tokens, or 0 where the call named none - which lands on
+ * the same floor of one unit rather than needing a case of its own.
+ */
+export declare function estimateUnits(read: (params: any) => number, tokensPerUnit: number): (params: any) => number;

package/dist/bindings/shared/estimate.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Turning a vendor's own request parameters into "how many units should this call ask for".
+ *
+ * Every vendor states a ceiling for the answer it is about to generate, under its own name -
+ * `max_tokens`, `config.maxOutputTokens`, a document whose length stands in for one - and what
+ * happens to that number afterwards is identical: divide by the rate, round up, never ask for
+ * less than one. Only the reading differs, so only the reading stays with the recipe.
+ *
+ * All of these are opt-in. The default asks for a single unit, because an estimate that
+ * overshoots denies calls the budget could have afforded, and the ingest that follows corrects
+ * the balance anyway.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requirePositiveRate = requirePositiveRate;
+exports.estimateUnits = estimateUnits;
+/**
+ * Refuses a rate that cannot divide, where it is configured rather than where it is used.
+ *
+ * Zero divides to `Infinity` and a negative to less than one; `requestedUnits` in the wrapper
+ * clamps both back to asking for a single unit, so a misconfigured rate would gate on nothing and
+ * never say so. Failing here makes that a startup error instead of a quiet one, per call, forever.
+ */
+function requirePositiveRate(name, value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${name} must be a finite positive number - got ${value}, which estimates every call wrongly.`);
+    }
+}
+/**
+ * The shared half: a rate, a reading, and the arithmetic between them.
+ *
+ * `read` returns the vendor's ceiling in tokens, or 0 where the call named none - which lands on
+ * the same floor of one unit rather than needing a case of its own.
+ */
+function estimateUnits(read, tokensPerUnit) {
+    requirePositiveRate('tokensPerUnit', tokensPerUnit);
+    return (params) => Math.max(1, Math.ceil(read(params) / tokensPerUnit));
+}

package/dist/bindings/shared/meter-stream.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Wrapping a stream so it can be metered, which every vendor needs and none of them differ on.
+ *
+ * What they *do* differ on is where the usage is: Anthropic accumulates it across two event types,
+ * Chat Completions puts it on the last chunk, the Responses API nests it under a completion event,
+ * and a gateway adds a cost and the model that served. So the mechanism is shared and the reading
+ * stays with the recipe that knows the shape.
+ *
+ * Two properties this owes every recipe, both of which it once got wrong:
+ *
+ *  - **One completed stream meters once.** `onComplete` fires on the first ending and never
+ *    again, however many times the object is iterated.
+ *  - **Every way out of the stream is metered.** `for await` is the usual one, but an async
+ *    generator - which is exactly what Gemini's `generateContentStream` resolves to - also
+ *    exposes `next()` as public API, and a caller driving it by hand used to be metered at
+ *    nothing at all.
+ */
+export declare function meterStream(stream: any, collect: (chunk: any) => void, onComplete: () => void): void;

package/dist/bindings/shared/meter-stream.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.meterStream = meterStream;
+/**
+ * Wrapping a stream so it can be metered, which every vendor needs and none of them differ on.
+ *
+ * What they *do* differ on is where the usage is: Anthropic accumulates it across two event types,
+ * Chat Completions puts it on the last chunk, the Responses API nests it under a completion event,
+ * and a gateway adds a cost and the model that served. So the mechanism is shared and the reading
+ * stays with the recipe that knows the shape.
+ *
+ * Two properties this owes every recipe, both of which it once got wrong:
+ *
+ *  - **One completed stream meters once.** `onComplete` fires on the first ending and never
+ *    again, however many times the object is iterated.
+ *  - **Every way out of the stream is metered.** `for await` is the usual one, but an async
+ *    generator - which is exactly what Gemini's `generateContentStream` resolves to - also
+ *    exposes `next()` as public API, and a caller driving it by hand used to be metered at
+ *    nothing at all.
+ */
+function meterStream(stream, collect, onComplete) {
+    if (!stream)
+        return;
+    // Captured before anything is patched, so the patched methods below can drive the vendor's own
+    // iterator without re-entering themselves. A bare generator's `[Symbol.asyncIterator]()`
+    // returns *itself*, so without this the loop would call whatever `next` currently holds - by
+    // then the patched one - and either recurse or count every chunk twice.
+    const iterate = typeof stream[Symbol.asyncIterator] === 'function' ? stream[Symbol.asyncIterator].bind(stream) : undefined;
+    const advance = typeof stream.next === 'function' ? stream.next.bind(stream) : undefined;
+    // Closing by hand ends a stream as surely as running it out, so these are captured too - and
+    // for the same reason: `source()` drives them, and binding them after the patch would have it
+    // calling itself.
+    const closers = ['return', 'throw']
+        .map((key) => ({ key, original: typeof stream[key] === 'function' ? stream[key].bind(stream) : undefined }))
+        .filter((entry) => !!entry.original);
+    if (!iterate && !advance)
+        return;
+    /** Fires once. A stream iterated twice is still one completed stream, and one measurement. */
+    let completed = false;
+    const finish = () => {
+        if (completed)
+            return;
+        completed = true;
+        onComplete();
+    };
+    // Reading a chunk is instrumentation: a vendor that changes shape must not break the loop the
+    // caller is standing in. The recipe reports what it could not read.
+    const observe = (value) => {
+        try {
+            collect(value);
+        }
+        catch {
+            // Deliberately swallowed - `onComplete` still runs, and meters whatever was collected.
+        }
+    };
+    /**
+     * The vendor's own iterator, resolved once and shared by both patched paths - so a caller that
+     * takes a few chunks by hand and then falls into a `for await` keeps reading one stream rather
+     * than opening a second.
+     *
+     * Lazy on purpose: for the vendors whose `[Symbol.asyncIterator]()` builds a reader, calling it
+     * eagerly would open a connection for a stream the caller may never consume.
+     */
+    let inner;
+    /** Whether reading ever began. Closing a stream nobody read meters nothing, not a zero. */
+    const started = () => inner !== undefined;
+    const source = () => {
+        if (!inner) {
+            const it = iterate ? iterate() : stream;
+            inner =
+                // A generator hands back itself, and its `next` is patched below - so drive the original.
+                it === stream
+                    ? { next: advance, return: closers.find((entry) => entry.key === 'return')?.original }
+                    : { next: it.next.bind(it), return: typeof it.return === 'function' ? it.return.bind(it) : undefined };
+        }
+        return inner;
+    };
+    if (advance) {
+        // The hand-driven path. Public API on any generator, and metered at nothing until now.
+        stream.next = async (...args) => {
+            try {
+                const result = await source().next(...args);
+                if (result?.done)
+                    finish();
+                else
+                    observe(result?.value);
+                return result;
+            }
+            catch (err) {
+                // The stream ended, badly - but what it produced before it failed was still produced,
+                // and still cost the customer. `for await` meters that through its own `finally`; this
+                // path had no equivalent and dropped the whole measurement on the floor.
+                finish();
+                throw err;
+            }
+        };
+    }
+    // `return()` and `throw()` are how a hand-driven consumer stops early, and either one is the
+    // end of the stream. Without this the usage read up to that point was never reported.
+    for (const { key, original } of closers) {
+        stream[key] = async (...args) => {
+            try {
+                return await original(...args);
+            }
+            finally {
+                if (started())
+                    finish();
+            }
+        };
+    }
+    if (iterate) {
+        stream[Symbol.asyncIterator] = async function* metered() {
+            const it = source();
+            // Whether the source ran itself out, as opposed to the consumer walking away from it. Only
+            // the second case owes it a `return()` - see the `finally`.
+            let exhausted = false;
+            try {
+                while (true) {
+                    const { value, done } = await it.next();
+                    if (done) {
+                        exhausted = true;
+                        return;
+                    }
+                    observe(value);
+                    yield value;
+                }
+            }
+            finally {
+                // Closes the vendor's stream when the consumer broke out early, which is what `for await`
+                // did on the way out. Without it an abandoned stream holds its connection open.
+                //
+                // Only then, though. The iteration protocol closes an iterator on *abrupt* completion and
+                // deliberately not when it ran itself out, so a source that already finished is never
+                // asked to close - driving `next()` by hand means saying that explicitly rather than
+                // inheriting it. Calling `return()` on a spent iterator is a no-op for a plain generator,
+                // but a vendor is free to implement it as "abort the request", and aborting a stream that
+                // has already delivered its last chunk is a cancellation nobody asked for.
+                if (!exhausted) {
+                    try {
+                        await it.return?.();
+                    }
+                    catch {
+                        // A source that objects to being closed must not mask the caller's own exit path.
+                    }
+                }
+                // Meter what was actually produced, even if the consumer broke out of the loop early.
+                finish();
+            }
+        };
+    }
+}

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

@@ -0,0 +1,240 @@
+/**
+ * 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 { BedrockLikeUsage, FlatTokenUsage, GeminiLikeUsage, LangChainLikeUsage, MistralLikeUsage, OllamaLikeUsage, 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;
+/**
+ * Bedrock's Converse usage, whose four counters are disjoint.
+ *
+ * Nothing is subtracted, unlike the OpenAI and Gemini readers: AWS states that `inputTokens`
+ * already excludes whatever was read from or written to the cache, so taking the cache back out
+ * would charge the call for less than it used.
+ *
+ * The total is read, not recomputed, like every other vendor that publishes one - but it is worth
+ * knowing what it covers. AWS documents `totalTokens` as the input and output of the call, and
+ * documents `inputTokens` as cache-exclusive, so on a cached call the stated total can be smaller
+ * than the four counters add up to. Both are reported: price the breakdown if the cache matters to
+ * you, the total if it does not, and see the README's overlap table before pricing both.
+ */
+export declare function fromBedrockUsage(usage: BedrockLikeUsage | 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;
+/**
+ * Mistral's `UsageInfo` - the OpenAI three, camelCased by a generated SDK.
+ *
+ * Counts the same way OpenAI's chat usage does, so the arithmetic is the same: the vendor states
+ * its own total and it is read rather than recomputed. There is no cache counter to subtract -
+ * `UsageInfo` carries none, so unlike `fromOpenAIUsage` nothing is nested inside the prompt count.
+ */
+export declare function fromMistralUsage(usage: MistralLikeUsage | null | undefined): TokenUsage;
+/**
+ * Ollama's two counters, read off the response root rather than out of a `usage` block.
+ *
+ * Disjoint - the prompt evaluation and the generation are separate work - so their sum is the
+ * whole call and computing a total from them is the vendor's own arithmetic rather than ours.
+ * Ollama publishes no total of its own, which is why there is one to compute.
+ */
+export declare function fromOllamaUsage(usage: OllamaLikeUsage | 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"];
+/**
+ * Where Mistral's counters are **read** and what each is **reported** as - the only vocabulary
+ * here where those are different strings.
+ *
+ * Every other vendor is reported under the key it was read from, which is why `METRIC_PATHS` is a
+ * list and `metricName` just takes the last segment. Mistral's generated SDK renames the wire on
+ * the way in - the API sends `prompt_tokens`, the client hands you `promptTokens` - so following
+ * that convention would report a camelCase feature id that matches nothing on Mistral's own
+ * dashboard, and would differ from what the same account reports through an `OpenAI` client
+ * pointed at `api.mistral.ai/v1`. One account, one invoice, one vocabulary: the wire's.
+ *
+ * So the map runs read-key -> reported-name, and `pickRenamedMetrics` is what applies it.
+ */
+export declare const MISTRAL_METRIC_NAME_MAP: {
+    readonly promptTokens: "prompt_tokens";
+    readonly completionTokens: "completion_tokens";
+    readonly totalTokens: "total_tokens";
+};
+/**
+ * Mistral's three, under the wire's own names.
+ *
+ * No cache counter: `UsageInfo` carries none. The cache and reasoning detail the v2 SDK models
+ * lives on a different type that chat responses do not use, so declaring it here would type a
+ * pricing table against a number that never arrives.
+ */
+export declare const MISTRAL_METRICS: readonly ["prompt_tokens", "completion_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"];
+/**
+ * Ollama's two. Flat on the response root, so the paths are the names.
+ *
+ * No cache counter and no cost: Ollama is self-hosted, so there is no invoice behind these at all
+ * - they measure the customer's own capacity rather than a vendor's charge. The durations beside
+ * them on the response are nanoseconds, not tokens, and are deliberately absent from this list.
+ */
+export declare const OLLAMA_COMPONENT_METRICS: readonly ["prompt_eval_count", "eval_count"];
+/** Those two, plus the total this SDK adds up for them. */
+export declare const OLLAMA_METRICS: readonly ["prompt_eval_count", "eval_count", "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"];
+/**
+ * Bedrock's five, under its own names and with no price among them.
+ *
+ * Reported verbatim rather than translated into the OpenAI spelling, which is the rule everywhere
+ * except where one service is reachable through two different clients - see `sdk-usage.ts` for
+ * that exception. Bedrock is reached one way, so its own names are the honest ones, and a reader
+ * comparing a Stigg meter against an AWS bill is comparing like with like.
+ *
+ * No `cost`: Bedrock states no price on the response, which is the thing that most separates it
+ * from the other two gateways here. See the recipe for what that costs a run.
+ */
+export declare const BEDROCK_PATHS: readonly ["inputTokens", "outputTokens", "cacheReadInputTokens", "cacheWriteInputTokens", "totalTokens"];
+/** Those five. Flat, so the paths are the names. */
+export declare const BEDROCK_METRICS: readonly ["inputTokens", "outputTokens", "cacheReadInputTokens", "cacheWriteInputTokens", "totalTokens"];
+/** 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"];
+    readonly bedrock: readonly ["inputTokens", "outputTokens", "cacheReadInputTokens", "cacheWriteInputTokens", "totalTokens"];
+    readonly ollama: readonly ["prompt_eval_count", "eval_count"];
+};
+/**
+ * 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;
+/**
+ * Reads each key of a read -> reported map off a usage object, reporting under the mapped name.
+ *
+ * The counterpart to {@link pickMetrics} for a vendor whose SDK spells its counters differently
+ * from its own wire. Same guards, and for the same reasons: anything absent, fractional or not a
+ * number is skipped, because a metric the vendor did not report is not a zero and Stigg rejects
+ * fractions. Flat keys only - no vendor needing this nests its counters, and a dotted read here
+ * would make the map ambiguous about which half of the arrow the dot belongs to.
+ */
+export declare function pickRenamedMetrics(usage: unknown, map: Record<string, 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;