@stigg/agent-sdk-js 1.0.1 → 2.0.0

package/dist/bindings/client/gateways/openrouter/openrouter-recipe.js

@@ -23,16 +23,33 @@ exports.openrouterRecipe = openrouterRecipe;
 const meter_stream_1 = require("../../../shared/meter-stream");
 const openai_recipe_1 = require("../../providers/openai/openai-recipe");
 const token_usage_1 = require("../../../shared/token-usage");
+const registry_1 = require("../../core/registry");
+const sdk_usage_1 = require("./sdk-usage");
 /** Float noise: 0.00108 * 1e6 is 1080.0000000000002, and ceil would bill the extra unit. */
 const toUnits = (cost, unitsPerCredit) => Math.max(1, Math.ceil(Number((cost * unitsPerCredit).toPrecision(12))));
 /**
  * Tokens and cost, from one response.
  *
  * A gateway states both, they are different features, and reporting both is what lets one meter
- * the tokens and the other the money. A streamed call simply carries no `cost` - the header went
- * out before the first token existed - so the key is absent rather than substituted.
+ * the tokens and the other the money.
+ *
+ * OpenRouter writes the money in the body, which is why a streamed call can still be billed on it:
+ * the usage object arrives on the last chunk, cost included, provided the request asked for usage
+ * (`stream_options.include_usage`, or `streamOptions.includeUsage` through the first-party SDK).
+ * A caller who does not ask gets a stream that states nothing, and the key is then absent rather
+ * than substituted - billing a guess is the one thing a cost-truth adapter must not do. LiteLLM is
+ * the gateway that genuinely cannot state it, because its cost rides a header that went out before
+ * the first token existed.
  */
-function measure(usage, parse, keys, model, id, options) {
+function measure(usage, parse, keys, model, id, options, 
+/**
+ * What the vendor itself stated, when that is not the object being read.
+ *
+ * The first-party SDK hands back camelCased counters, which are translated to the wire's own
+ * spelling before anything meters them - but an event should carry what OpenRouter said, not
+ * what this file rewrote it to, so the original rides along unchanged.
+ */
+stated) {
     if (!usage)
         return undefined;
     const cost = usage.cost;
@@ -45,15 +62,76 @@ function measure(usage, parse, keys, model, id, options) {
         usage: parse(usage),
         // What the gateway stated, before `cost` was scaled into whole units - an event can carry the
         // fraction as it was, which is the honest number and the one that reconciles with the bill.
-        raw: usage,
+        raw: stated ?? usage,
         // The gateway's own request id: stable across its retries, which a local step counter is not.
         dimensions: model ? { [options.modelDimension]: model } : undefined,
         idempotencyKey: id,
     };
 }
+/**
+ * The first-party SDK's two surfaces, built the same way the OpenAI-shaped ones are.
+ *
+ * `@openrouter/sdk` is generated from the OpenAPI spec, so it shares nothing with `openai-node`
+ * but the service behind it: the method is `chat.send` rather than `chat.completions.create`, the
+ * request nests under `chatRequest`, and the counters come back camelCased. Only the last of
+ * those reaches a meter, and `sdk-usage.ts` undoes it so both clients report the same metric
+ * names for the same call.
+ *
+ * `responses.send` is here for the reason the comment on `methods` gives: a surface this recipe
+ * declines to declare is not metered by something else, it is simply ungated - and a client this
+ * recipe claims to govern must not have a billable method left open on it.
+ */
+function sdkSurfaces(resolved) {
+    const surfaces = [
+        { path: ['chat', 'send'], read: sdk_usage_1.fromSdkChatUsage, parse: token_usage_1.fromOpenAIUsage, keys: token_usage_1.METRIC_PATHS.openaiChat },
+        {
+            path: ['responses', 'send'],
+            read: sdk_usage_1.fromSdkResponsesUsage,
+            parse: token_usage_1.fromResponsesUsage,
+            keys: token_usage_1.METRIC_PATHS.openaiResponses,
+        },
+    ];
+    return surfaces.map(({ path, read, parse, keys }) => {
+        /** The vendor's own object translated, with the original kept for the event to carry. */
+        const measureSdk = (usage, model, id) => measure(read(usage), parse, keys, model, id, resolved, usage);
+        return {
+            path: [...path],
+            estimate: resolved.estimate,
+            extractUsage: (result) => measureSdk(result?.usage, result?.model, result?.id),
+            // A streamed call resolves to an `EventStream`, which is a `ReadableStream` subclass: async
+            // iterable, and with no `next`/`return` of its own for `meterStream` to patch. So the
+            // metered path is `for await`, which is how the SDK documents consuming one. A caller who
+            // takes `getReader()` instead bypasses the wrapper - the same hole every streaming binding
+            // has, and the reason the non-streamed surface is the one the example leans on.
+            attachStream: (stream, ingest) => {
+                let usage;
+                let model;
+                let id;
+                (0, meter_stream_1.meterStream)(stream, (chunk) => {
+                    // Usage arrives once, on the last chunk; `model` and `id` ride every one of them.
+                    if (chunk?.usage)
+                        usage = chunk.usage;
+                    if (chunk?.model)
+                        model = chunk.model;
+                    if (chunk?.id)
+                        id = chunk.id;
+                }, () => {
+                    const measurement = measureSdk(usage, model, id);
+                    if (measurement)
+                        ingest(measurement);
+                });
+            },
+        };
+    });
+}
 /**
  * One recipe covers every upstream. OpenRouter normalizes Anthropic, OpenAI and the rest to the
  * same wire shape, so the response never changes form - `model` is just a field saying who served.
+ *
+ * It also covers both ways of reaching OpenRouter from Node: the OpenAI SDK pointed at the
+ * gateway's base URL, and OpenRouter's own `@openrouter/sdk`. Those are different objects with
+ * different method names reporting the same call, and a recipe that governed only the first would
+ * meter nothing at all for an application that took OpenRouter's own documented advice.
  */
 function openrouterRecipe(options = {}) {
     const resolved = {
@@ -66,39 +144,43 @@ function openrouterRecipe(options = {}) {
         // The OpenAI shape it speaks, so the OpenAI name for the total.
         totalTokensMetric: token_usage_1.TOTAL_TOKENS,
         vendor: 'openrouter',
-        // Shape alone cannot separate this from any other OpenAI-compatible client, so the base URL
-        // is the discriminator - it is the one thing that says which gateway is on the other end.
-        matches: (client) => openai_recipe_1.openAIRecipe.matches(client) && isOpenRouter(client),
+        // Two clients, recognised two different ways - see each guard for why they cannot share one.
+        // The OpenAI-shaped client is OpenAI-shaped, so only its base URL says which gateway it talks
+        // to; OpenRouter's own SDK is unmistakable by shape and may legitimately point anywhere.
+        matches: (client) => (openai_recipe_1.openAIRecipe.matches(client) && isOpenRouter(client)) || isOpenRouterSdk(client),
         // Built from the OpenAI recipe's own surfaces. A gateway speaks that API, so the methods worth
         // governing are the same ones - and because this recipe is matched ahead of it, any surface it
         // failed to declare would be left ungated rather than falling through.
-        methods: openai_recipe_1.openAIRecipe.methods.map((base) => {
-            const { parse, keys, streamed } = (0, openai_recipe_1.openAISurface)(base.path);
-            return {
-                path: base.path,
-                estimate: resolved.estimate,
-                extractUsage: (result) => measure(result?.usage, parse, keys, result?.model, result?.id, resolved),
-                // Usage arrives once, at the end; `model` and `id` ride every chunk.
-                attachStream: (stream, ingest) => {
-                    let usage;
-                    let model;
-                    let id;
-                    (0, meter_stream_1.meterStream)(stream, (chunk) => {
-                        const seen = streamed(chunk);
-                        if (seen)
-                            usage = seen;
-                        if (chunk?.model)
-                            model = chunk.model;
-                        if (chunk?.id)
-                            id = chunk.id;
-                    }, () => {
-                        const measurement = measure(usage, parse, keys, model, id, resolved);
-                        if (measurement)
-                            ingest(measurement);
-                    });
-                },
-            };
-        }),
+        methods: [
+            ...openai_recipe_1.openAIRecipe.methods.map((base) => {
+                const { parse, keys, streamed } = (0, openai_recipe_1.openAISurface)(base.path);
+                return {
+                    path: base.path,
+                    estimate: resolved.estimate,
+                    extractUsage: (result) => measure(result?.usage, parse, keys, result?.model, result?.id, resolved),
+                    // Usage arrives once, at the end; `model` and `id` ride every chunk.
+                    attachStream: (stream, ingest) => {
+                        let usage;
+                        let model;
+                        let id;
+                        (0, meter_stream_1.meterStream)(stream, (chunk) => {
+                            const seen = streamed(chunk);
+                            if (seen)
+                                usage = seen;
+                            if (chunk?.model)
+                                model = chunk.model;
+                            if (chunk?.id)
+                                id = chunk.id;
+                        }, () => {
+                            const measurement = measure(usage, parse, keys, model, id, resolved);
+                            if (measurement)
+                                ingest(measurement);
+                        });
+                    },
+                };
+            }),
+            ...sdkSurfaces(resolved),
+        ],
     };
 }
 /**
@@ -115,6 +197,27 @@ function isOpenRouter(client) {
     const host = hostOf(baseUrl);
     return host === 'openrouter.ai' || host.endsWith('.openrouter.ai');
 }
+/**
+ * Whether this is OpenRouter's own SDK client, which carries no base URL to recognise it by.
+ *
+ * The OpenAI-shaped client is identified by where it points, because its shape says only
+ * "OpenAI-compatible" and half the industry is. This one is the opposite: `chat.send` is not a
+ * shape anyone else has, and the namespaces beside it - `credits`, `generations`, the gateway's
+ * own billing and routing APIs - are OpenRouter's product rather than an API style someone could
+ * implement by accident. So shape is the whole discriminator here, and there is no URL to check:
+ * an application may point the SDK at a proxy, which is still OpenRouter's SDK and still speaks
+ * its format.
+ *
+ * `in` rather than a property read, because every namespace on that client is a lazy getter that
+ * constructs a sub-client - and merely asking whether a recipe fits must not build three of them.
+ */
+function isOpenRouterSdk(client) {
+    if (!client || typeof client !== 'object')
+        return false;
+    if (!(0, registry_1.hasMethod)(client, ['chat', 'send']) && !(0, registry_1.hasMethod)(client, ['responses', 'send']))
+        return false;
+    return 'credits' in client && 'generations' in client;
+}
 /** The hostname, lowercased, or '' when the URL is not one this can reason about. */
 function hostOf(url) {
     try {

package/dist/bindings/client/gateways/openrouter/sdk-usage.d.ts

@@ -0,0 +1,37 @@
+/**
+ * OpenRouter's first-party SDK counts the same tokens under different names.
+ *
+ * `@openrouter/sdk` is generated from the OpenAPI spec and camelCases every field on the way in,
+ * so a response that arrived as `prompt_tokens` reaches the caller as `promptTokens`. Nothing
+ * about the call changed - same gateway, same wire format, same bill - only the spelling the
+ * parse handed back.
+ *
+ * That matters more than it looks. A metric name is a **feature id**: it is what the mapper
+ * prices and what Stigg meters. If the same gateway reported `prompt_tokens` through one client
+ * and `promptTokens` through another, one customer's calls would land on two different features
+ * depending on which SDK the application happened to import - and the second of them exists in
+ * nobody's catalog, so those calls would report to a feature that cannot be billed.
+ *
+ * So the spelling is undone here rather than carried through: each reader below returns the
+ * OpenAI-shaped object the wire actually carried, and everything downstream - `pickMetrics`,
+ * `fromOpenAIUsage`, the metric names in `GATEWAY_METRICS` - is the code that already serves the
+ * OpenAI-shaped client, reading the names it already knows. The vendor's own object is still what
+ * rides along as `raw`, so an event carries what OpenRouter said, spelled the way OpenRouter
+ * spelled it.
+ */
+import type { OpenRouterSdkChatUsage, OpenRouterSdkResponsesUsage, OpenRouterUsage } from './types';
+/**
+ * `chat.send` - the Chat Completions shape, camelCased.
+ *
+ * `cost` keeps its name across both spellings, because it is OpenRouter's own field rather than
+ * one inherited from OpenAI, and the generator had no snake_case original to convert.
+ */
+export declare function fromSdkChatUsage(usage: OpenRouterSdkChatUsage | null | undefined): OpenRouterUsage | undefined;
+/**
+ * `responses.send` - the Responses API shape, camelCased.
+ *
+ * The same tokens again under the third set of names this SDK can hand back: `inputTokens` rather
+ * than `promptTokens`, with the cache detail one level along. Read with the chat reader it would
+ * find none of them and meter the call at zero, which is why the two surfaces get a reader each.
+ */
+export declare function fromSdkResponsesUsage(usage: OpenRouterSdkResponsesUsage | null | undefined): OpenRouterUsage | undefined;

package/dist/bindings/client/gateways/openrouter/sdk-usage.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromSdkChatUsage = fromSdkChatUsage;
+exports.fromSdkResponsesUsage = fromSdkResponsesUsage;
+/** Drops what the SDK models as nullable, so an absent counter stays absent rather than null. */
+const num = (value) => (typeof value === 'number' ? value : undefined);
+/**
+ * `{ key: value }` when there is a value, and nothing at all when there is not.
+ *
+ * Absent and zero are different: `pickMetrics` skips a counter that is not a positive number, and
+ * a nested detail object that exists with nothing in it reads as a vendor that reported a cache
+ * and found none - which is not the same as a vendor that reported no cache at all.
+ */
+const maybe = (key, value) => value === undefined ? {} : { [key]: value };
+/** Nothing, rather than an empty object, when a whole detail group was absent. */
+const group = (fields) => Object.keys(fields).length > 0 ? fields : undefined;
+/**
+ * `chat.send` - the Chat Completions shape, camelCased.
+ *
+ * `cost` keeps its name across both spellings, because it is OpenRouter's own field rather than
+ * one inherited from OpenAI, and the generator had no snake_case original to convert.
+ */
+function fromSdkChatUsage(usage) {
+    if (!usage)
+        return undefined;
+    const promptDetails = group({
+        ...maybe('cached_tokens', num(usage.promptTokensDetails?.cachedTokens)),
+        ...maybe('cache_write_tokens', num(usage.promptTokensDetails?.cacheWriteTokens)),
+    });
+    const completionDetails = group({
+        ...maybe('reasoning_tokens', num(usage.completionTokensDetails?.reasoningTokens)),
+    });
+    return {
+        ...maybe('prompt_tokens', num(usage.promptTokens)),
+        ...maybe('completion_tokens', num(usage.completionTokens)),
+        ...maybe('total_tokens', num(usage.totalTokens)),
+        ...maybe('cost', num(usage.cost)),
+        ...maybe('prompt_tokens_details', promptDetails),
+        ...maybe('completion_tokens_details', completionDetails),
+    };
+}
+/**
+ * `responses.send` - the Responses API shape, camelCased.
+ *
+ * The same tokens again under the third set of names this SDK can hand back: `inputTokens` rather
+ * than `promptTokens`, with the cache detail one level along. Read with the chat reader it would
+ * find none of them and meter the call at zero, which is why the two surfaces get a reader each.
+ */
+function fromSdkResponsesUsage(usage) {
+    if (!usage)
+        return undefined;
+    const inputDetails = group({
+        ...maybe('cached_tokens', num(usage.inputTokensDetails?.cachedTokens)),
+        ...maybe('cache_write_tokens', num(usage.inputTokensDetails?.cacheWriteTokens)),
+    });
+    return {
+        ...maybe('input_tokens', num(usage.inputTokens)),
+        ...maybe('output_tokens', num(usage.outputTokens)),
+        ...maybe('total_tokens', num(usage.totalTokens)),
+        ...maybe('cost', num(usage.cost)),
+        ...maybe('input_tokens_details', inputDetails),
+    };
+}

package/dist/bindings/client/gateways/openrouter/types.d.ts

@@ -2,6 +2,55 @@ import type { OpenAILikeUsage } from '../../../shared/types';
 /** OpenRouter extends the OpenAI usage object with the credits it actually charged. */
 export type OpenRouterUsage = OpenAILikeUsage & {
     cost?: number | null;
+    /**
+     * The Responses-API counters, for the one client that can report either shape.
+     *
+     * `@openrouter/sdk` reaches both of OpenRouter's surfaces, and they count the same tokens under
+     * different names - so the object a reader hands back may carry one set or the other. Optional
+     * on both sides rather than a union, because the reader that produced it already knows which
+     * surface it read, and the metric list it is picked with is the surface's own.
+     */
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    input_tokens_details?: {
+        cached_tokens?: number | null;
+        cache_write_tokens?: number | null;
+    } | null;
+};
+/**
+ * What `@openrouter/sdk` hands back for `chat.send`, in the SDK's own spelling.
+ *
+ * Declared structurally rather than imported from `@openrouter/sdk`: the package is a devDependency
+ * of the examples, and a recipe that imported its types would make it a dependency of the SDK
+ * itself - every consumer installing a client they may not use. Only the counters are named here,
+ * which is all a meter reads; see `sdk-usage.ts` for why the spelling is undone rather than kept.
+ */
+export type OpenRouterSdkChatUsage = {
+    promptTokens?: number | null;
+    completionTokens?: number | null;
+    totalTokens?: number | null;
+    cost?: number | null;
+    promptTokensDetails?: {
+        cachedTokens?: number | null;
+        cacheWriteTokens?: number | null;
+    } | null;
+    completionTokensDetails?: {
+        reasoningTokens?: number | null;
+    } | null;
+};
+/** The same, for `responses.send` - the Responses API's names, camelCased the same way. */
+export type OpenRouterSdkResponsesUsage = {
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+    totalTokens?: number | null;
+    cost?: number | null;
+    inputTokensDetails?: {
+        cachedTokens?: number | null;
+        cacheWriteTokens?: number | null;
+    } | null;
+    outputTokensDetails?: {
+        reasoningTokens?: number | null;
+    } | null;
 };
 export type OpenRouterRecipeOptions = {
     /**

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

@@ -1,6 +1,10 @@
 import type { Measurement } from '../../../../types';
 import type { MetricsFor, MetricsOf } from '../../core/types';
-/** `message_delta` restates the whole message's running totals, input included, so its counters replace `message_start`'s rather than add to them. */
+/**
+ * Accumulates usage across raw stream events: Anthropic sends the input counts on
+ * `message_start` and restates them, with the output count, on `message_delta` - so one completed
+ * stream produces one measurement rather than one per event.
+ */
 declare function observeStream(stream: any, ingest: (measurement: Measurement) => void): void;
 export declare const anthropicRecipe: {
     vendor: string;

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

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

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

@@ -7,7 +7,7 @@
  * `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';
+import type { BedrockLikeUsage, 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;
 /**
@@ -16,6 +16,20 @@ export declare function fromOpenAIUsage(usage: OpenAILikeUsage | null | undefine
  * 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`
@@ -74,6 +88,20 @@ export declare const TYPESAFE_METRICS: readonly ["input_tokens", "output_tokens"
 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;
 /**
@@ -107,6 +135,7 @@ export declare const METRIC_PATHS: {
     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"];
 };
 /**
  * Reads the named keys off a vendor's usage object, dotted paths included.