margin-meter 0.1.0 → 0.2.0

package/README.md

@@ -15,17 +15,24 @@ authenticated with a per-project ingest key.
 
 ## Install
 
-Published as a git-installable subpath of the Margin repo (no npm registry
-account needed pre-launch):
+From the npm registry:
 
 ```bash
 npm install margin-meter
-# or, pinning the subdirectory with your package manager of choice, e.g. pnpm:
-# pnpm add "https://gitpkg.now.sh/subhsubh24/Margin.ai/sdk/ts?main"
 ```
 
-Most TS projects import the source directly (their bundler compiles it); the
-package `exports` point at `src/index.ts` with types.
+> **Check the version you get.** This package ships from the registry, and the
+> registry can lag the repo. Confirm with `npm ls margin-meter`, and compare it
+> against `sdk/ts/package.json` on `main`. An older release silently omits newer
+> capture (e.g. `substrate`, reasoning tokens), which under-reports your spend
+> rather than failing loudly — the one failure mode this SDK exists to prevent.
+
+Unlike the [Python SDK](../python), this package is **not** git-installable:
+npm has no equivalent of pip's `#subdirectory=`, `dist/` is a build artifact
+that is not committed, and the entry points resolve to `./dist`. Installing
+from a clone or a git URL therefore yields a package with no entry point. Use
+the registry, or publish a new version from `sdk/ts` (`npm publish` runs the
+build via `prepublishOnly`).
 
 ## Configure
 
@@ -79,6 +86,51 @@ const res = await meter.recordCall({
 if (!res.ok) console.warn(`margin ingest failed: ${res.error} (${res.statusCode})`);
 ```
 
+## Auto-instrument (a few lines for a whole repo)
+
+To instrument an existing agent you didn't write, don't edit every call site.
+Point the meter at the client the agent already constructed and every model call
+is timed and metered automatically — tokens are read straight off each
+provider's response, so there's no `setTokens` bookkeeping:
+
+```ts
+import OpenAI from "openai";
+import { MarginMeter, instrumentOpenAI } from "margin-meter";
+
+const client = new OpenAI();
+const meter = new MarginMeter();
+const undo = instrumentOpenAI(client, meter, { workflowId: "aider-fix" });
+
+// ... the agent's normal client.chat.completions.create(...) calls are metered ...
+
+await meter.recordOutcome({ workflowId: "aider-fix", passed: testsGreen });
+undo(); // restore the original method
+```
+
+`instrumentAnthropic(client, …)` patches `messages.create`;
+`instrumentGemini(model, …)` patches a `GenerativeModel`'s `generateContent`
+(recovering the model id off the instance). Each returns an `undo()` and throws
+`MarginInstrumentError` if the client shape has moved.
+
+Two lower-level primitives when you want tighter control:
+
+```ts
+// Wrap ONE call (no monkeypatch) — returns a drop-in replacement.
+const create = meter.wrap(client.chat.completions.create.bind(client.chat.completions), {
+  workflowId: "cart-parse",
+  provider: "openai",
+});
+const resp = await create({ model: "gpt-4o-mini", messages: [/* … */] }); // metered; resp untouched
+
+// Or meter a response you already have.
+await meter.recordResponse({ workflowId: "cart-parse", response: resp, provider: "openai" });
+```
+
+Honesty: tokens are read verbatim from the real response (`extractUsage`) —
+cache reads are billed separately, never double-counted as fresh input — and a
+metering failure is fail-safe (your call still returns / still throws). A failed
+provider call is still recorded with `status:"error"` so it appears in the chain.
+
 ## API
 
 | Method | Emits to | Notes |
@@ -86,6 +138,9 @@ if (!res.ok) console.warn(`margin ingest failed: ${res.error} (${res.statusCode}
 | `recordCall(input)` | `POST /api/ingest/calls` | cost computed from the pricing table when `costUsd` omitted |
 | `recordOutcome(input)` | `POST /api/ingest/outcomes` | `qualityMethod` records HOW the score was graded |
 | `measure(input, fn)` | `recordCall` on completion | times latency; `status:"error"` + rethrow if `fn` throws; returns `fn`'s value, emit result on `m.result` |
+| `recordResponse(input)` | `recordCall` | meters straight off a provider response — no manual tokens |
+| `wrap(fn, opts)` | `recordCall` per call | returns an auto-metered drop-in for any LLM call |
+| `instrumentOpenAI` / `instrumentAnthropic` / `instrumentGemini` | — | monkeypatch a client instance's create method |
 
 Every method resolves to an `IngestResult { ok, statusCode, body?, error? }`.
 `ok` is true only on HTTP 200; `body` holds `call_id`/`outcome_id` + `source`.

package/dist/index.d.ts

@@ -21,6 +21,12 @@
  *    written `source` is forced server-side to the key's project slug — the
  *    client cannot spoof another project's economics.
  */
+import { type ProviderName } from "./providers.ts";
+import { type Substrate } from "./substrate.ts";
+export * from "./providers.ts";
+export * from "./instrument.ts";
+export * as substrate from "./substrate.ts";
+export type { Substrate } from "./substrate.ts";
 export declare const CALLS_PATH = "/api/ingest/calls";
 export declare const OUTCOMES_PATH = "/api/ingest/outcomes";
 export declare const KEY_HEADER = "X-Margin-Key";
@@ -84,13 +90,62 @@ export interface RecordCallInput {
     inputTokens?: number;
     outputTokens?: number;
     cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    /** The 1-hour-TTL portion of cache creation (Anthropic bills it ~2x input, not
+     *  the 5-minute ~1.25x). Disjoint from cacheCreationTokens; omit/0 when a call
+     *  uses only the default cache. */
+    cacheCreation1hTokens?: number;
+    /** The hidden-thinking share of outputTokens (Gemini thoughts, OpenAI
+     *  reasoning_tokens). A SUBSET of output, already priced at the output rate —
+     *  never priced separately. Carried only so the reasoning-effort lever can be
+     *  isolated; omit/0 on a non-reasoning call. */
+    reasoningTokens?: number;
     latencyMs?: number;
     status?: string;
     isRetry?: boolean;
     sessionId?: string;
     promptId?: string;
+    /** The STEP within a multi-operation workflow this call belongs to (a
+     *  supply-chain node label the Money Map decomposes by, e.g. "extract"). Omit
+     *  for a single-call workflow. */
+    operation?: string;
     costUsd?: number;
     isSimulated?: boolean;
+    /** Idempotency key baked into the emitted payload. Defaults to a fresh uuid
+     *  per call, so a redelivery of THIS exact emit (a transport retry) collapses
+     *  to one row server-side instead of double-counting spend. Distinct calls get
+     *  distinct ids, so real volume is never deduped away. */
+    eventId?: string;
+    /** The provider billing tier. "standard" (the default) is a normal synchronous
+     *  call; "batch" is a call routed through the async Batch API, which the server
+     *  prices at the ~50%-off tier — pricing a real batch call standard would
+     *  over-state its cost. Omit for standard; the field is sent only when "batch". */
+    billingTier?: "standard" | "batch";
+    /** This call's own node in an agent tree. A branching run is otherwise a flat
+     *  list of calls sharing a sessionId — enough to total the run, never enough to
+     *  ask what one BRANCH cost. Omit for a single-agent call. */
+    spanId?: string;
+    /** The node that spawned this one; omit at the root. Requires `spanId` (a parent
+     *  link with no node of its own is an edge to nowhere, and the server rejects
+     *  it). */
+    parentSpanId?: string;
+    /** The orchestration shape THIS call performed, on the node that did the
+     *  orchestrating — not on its branches. The set is closed server-side so shapes
+     *  stay comparable across runs. */
+    orchestrationPattern?: "pipeline" | "barrier" | "panel" | "loop_until_dry";
+    /** How many branches the orchestration opened. */
+    branchWidth?: number;
+    /** The rule that ended the orchestration, free text (e.g. "majority of 3"). */
+    stoppingRule?: string;
+    /** Which PATH this call took to reach the model — the vendor's own API
+     *  ("direct"), a router ("openrouter", "litellm"), a cloud reseller ("azure",
+     *  "bedrock", "vertex"), or an unrecognised proxy ("gateway"). Independent of
+     *  `provider`, which says who owns the model and bills for it: the same
+     *  openai/gpt-4o call can arrive over four different paths, and comparing them
+     *  is something a single-substrate router structurally cannot do. Omit it when
+     *  the path is not actually known — an unmeasured dimension belongs empty, not
+     *  defaulted to "direct". The set is closed server-side. */
+    substrate?: "direct" | "openrouter" | "litellm" | "azure" | "bedrock" | "vertex" | "gateway";
 }
 export interface RecordOutcomeInput {
     workflowId: string;
@@ -99,6 +154,9 @@ export interface RecordOutcomeInput {
     qualityMethod?: string;
     link?: string;
     isSimulated?: boolean;
+    /** Idempotency key (see RecordCallInput.eventId): a redelivered outcome does
+     *  not double-count the cost-per-outcome denominator. Defaults to a fresh uuid. */
+    eventId?: string;
 }
 /** A per-project client that emits measured economics to a Margin ingest API. */
 export declare class MarginMeter {
@@ -122,17 +180,83 @@ export declare class MarginMeter {
      * value `fn` produced; the emit's `IngestResult` is available as `m.result`.
      */
     measure<T>(input: Omit<RecordCallInput, "latencyMs" | "status">, fn: (m: Measurement) => Promise<T> | T): Promise<T>;
+    /**
+     * Meter one call by reading tokens straight off its provider `response`
+     * (OpenAI / Anthropic / Gemini result). The no-bookkeeping counterpart to
+     * `recordCall`: the `(provider, model, tokens)` are recovered by
+     * `extractUsage`. `provider` is optional when the shape is unambiguous but the
+     * instrumenter always passes it; `model` overrides a response that omits it
+     * (Gemini). Numbers are read verbatim. Never throws unless `raiseOnError`.
+     */
+    recordResponse(input: RecordResponseInput): Promise<IngestResult>;
+    /**
+     * Return `fn` wrapped so every call is timed and auto-metered. The core
+     * auto-instrumentation primitive: give it any async LLM call
+     * (`client.chat.completions.create`, `client.messages.create`,
+     * `model.generateContent` …) and it returns a drop-in replacement that times
+     * the call, emits its economics from the returned response, and hands the
+     * ORIGINAL response back untouched. On a throw the call is metered with
+     * `status="error"` and the error re-thrown (never swallowed); a metering
+     * failure is fail-safe and never breaks the wrapped call. `provider` is
+     * required for a shape the extractor can't disambiguate; `model` supplies a
+     * model the response omits (Gemini); `resolveModel(args)` derives it per call
+     * (e.g. off a bound Gemini model). Signature-agnostic (`...args`).
+     */
+    wrap<F extends (...args: never[]) => Promise<unknown>>(fn: F, opts: WrapOptions): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;
+}
+/** Input to `recordResponse` — meter off a provider response object. */
+export interface RecordResponseInput {
+    workflowId: string;
+    response: unknown;
+    provider?: ProviderName;
+    model?: string;
+    latencyMs?: number;
+    status?: string;
+    isRetry?: boolean;
+    sessionId?: string;
+    promptId?: string;
+    operation?: string;
+    isSimulated?: boolean;
+    /** The delivery path the call took (see `substrate.ts`); omit when unknown. */
+    substrate?: Substrate;
+}
+/** Options for `wrap` — how to meter every call to the wrapped fn. */
+export interface WrapOptions {
+    workflowId: string;
+    provider?: ProviderName;
+    model?: string;
+    operation?: string;
+    sessionId?: string;
+    isRetry?: boolean;
+    isSimulated?: boolean;
+    /** Derive the model per call (e.g. off a bound Gemini model); a truthy return
+     *  overrides the static `model`. Receives the wrapped call's args. */
+    resolveModel?: (args: unknown[]) => string | undefined;
+    /** OpenAI omits usage from a stream unless asked; when set (only by the OpenAI
+     *  chat instrumenter), a `stream: true` call gets `stream_options.include_usage`
+     *  injected so its final chunk carries the count the accumulator meters. */
+    streamIncludeUsage?: boolean;
+    /** Which DELIVERY PATH this wrapper's calls take (see `substrate.ts`). The JS
+     *  instrumenters patch a specific client instance, so the endpoint is known at
+     *  patch time and every call through this wrapper travelled it. Leave unset when
+     *  the endpoint could not be read — an unmeasured dimension belongs empty, never
+     *  defaulted to "direct". Never touches the cost math. */
+    substrate?: Substrate;
 }
 /** Token accumulator passed into `measure`'s callback. */
 export declare class Measurement {
     inputTokens: number;
     outputTokens: number;
     cacheReadTokens: number;
+    cacheCreationTokens: number;
+    cacheCreation1hTokens: number;
     result?: IngestResult;
     setTokens(tokens: {
         inputTokens?: number;
         outputTokens?: number;
         cacheReadTokens?: number;
+        cacheCreationTokens?: number;
+        cacheCreation1hTokens?: number;
     }): void;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -21,11 +21,30 @@
  *    written `source` is forced server-side to the key's project slug — the
  *    client cannot spoof another project's economics.
  */
+import { extractUsage, StreamUsageAccumulator, } from "./providers.js";
+export * from "./providers.js";
+export * from "./instrument.js";
+// Namespaced, not flattened: `BEDROCK` means two different things here — the
+// provider that bills for the model and the path the request took — and merging
+// them into one barrel would collide the names and blur the distinction the
+// substrate dimension exists to draw. `substrate.BEDROCK` reads as the path.
+export * as substrate from "./substrate.js";
 export const CALLS_PATH = "/api/ingest/calls";
 export const OUTCOMES_PATH = "/api/ingest/outcomes";
 export const KEY_HEADER = "X-Margin-Key";
 export const DEFAULT_INGEST_URL = "http://127.0.0.1:8000";
 export const DEFAULT_TIMEOUT_MS = 10_000;
+/** A fresh idempotency key per emit. Uses the platform crypto UUID (Node 16.7+,
+ *  modern browsers); falls back to a random-hex id where crypto is absent, which
+ *  is still unique enough to key a single call's dedup. */
+function newEventId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return (Date.now().toString(16) +
+        Math.random().toString(16).slice(2) +
+        Math.random().toString(16).slice(2));
+}
 /** Raised (only in strict mode) when a row is rejected by the ingest API. */
 export class MarginIngestError extends Error {
     statusCode;
@@ -115,17 +134,57 @@ export class MarginMeter {
             input_tokens: input.inputTokens ?? 0,
             output_tokens: input.outputTokens ?? 0,
             cache_read_tokens: input.cacheReadTokens ?? 0,
+            cache_creation_tokens: input.cacheCreationTokens ?? 0,
             latency_ms: input.latencyMs ?? 0,
             status: input.status ?? "ok",
             is_retry: input.isRetry ?? false,
             is_simulated: input.isSimulated ?? false,
+            event_id: input.eventId ?? newEventId(),
         };
         if (input.sessionId !== undefined)
             payload.session_id = input.sessionId;
         if (input.promptId !== undefined)
             payload.prompt_id = input.promptId;
+        if (input.operation !== undefined)
+            payload.operation = input.operation;
         if (input.costUsd !== undefined)
             payload.cost_usd = input.costUsd;
+        // Only send a non-default tier: a synchronous call omits it (the server
+        // defaults "standard"), keeping the wire minimal and an older server that
+        // predates the field unaffected.
+        if (input.billingTier !== undefined && input.billingTier !== "standard") {
+            payload.billing_tier = input.billingTier;
+        }
+        // Only send the 1-hour cache-write bucket when a call used one: the common
+        // single-TTL call omits it (the server reads 0 and prices its whole cache
+        // creation at the 5-minute rate, unchanged), keeping the wire minimal and an
+        // older server that predates the field unaffected.
+        if (input.cacheCreation1hTokens) {
+            payload.cache_creation_1h_tokens = input.cacheCreation1hTokens;
+        }
+        // Only send the reasoning subset when a call spent thinking tokens: a
+        // non-reasoning call omits it (server reads 0). It never changes cost — it is a
+        // share of output already priced at the output rate.
+        if (input.reasoningTokens) {
+            payload.reasoning_tokens = input.reasoningTokens;
+        }
+        // The agent-tree fields ride only when a call belongs to one, so a
+        // single-agent call's wire is unchanged and an older server that predates them
+        // is unaffected. They carry structure, never money — no cost branch reads them.
+        if (input.spanId !== undefined)
+            payload.span_id = input.spanId;
+        if (input.parentSpanId !== undefined)
+            payload.parent_span_id = input.parentSpanId;
+        if (input.orchestrationPattern !== undefined) {
+            payload.orchestration_pattern = input.orchestrationPattern;
+        }
+        if (input.branchWidth !== undefined)
+            payload.branch_width = input.branchWidth;
+        if (input.stoppingRule !== undefined)
+            payload.stopping_rule = input.stoppingRule;
+        // The delivery path, sent only when it was actually determined.
+        if (input.substrate !== undefined)
+            payload.substrate = input.substrate;
         return await this.emit(CALLS_PATH, payload);
     }
     /** Emit one outcome (a unit of productivity). `qualityMethod` records HOW the
@@ -135,6 +194,7 @@ export class MarginMeter {
             workflow_id: input.workflowId,
             passed: input.passed,
             is_simulated: input.isSimulated ?? false,
+            event_id: input.eventId ?? newEventId(),
         };
         if (input.qualityScore !== undefined)
             payload.quality_score = input.qualityScore;
@@ -169,22 +229,275 @@ export class MarginMeter {
                 inputTokens: m.inputTokens,
                 outputTokens: m.outputTokens,
                 cacheReadTokens: m.cacheReadTokens,
+                cacheCreationTokens: m.cacheCreationTokens,
+                cacheCreation1hTokens: m.cacheCreation1hTokens,
                 latencyMs,
                 status: threw ? "error" : "ok",
             });
         }
     }
+    // --------------------------------------------------------------------- //
+    // Auto-instrumentation — meter straight off a provider response, no manual
+    // setTokens(). The "few lines to instrument a repo" path.
+    // --------------------------------------------------------------------- //
+    /**
+     * Meter one call by reading tokens straight off its provider `response`
+     * (OpenAI / Anthropic / Gemini result). The no-bookkeeping counterpart to
+     * `recordCall`: the `(provider, model, tokens)` are recovered by
+     * `extractUsage`. `provider` is optional when the shape is unambiguous but the
+     * instrumenter always passes it; `model` overrides a response that omits it
+     * (Gemini). Numbers are read verbatim. Never throws unless `raiseOnError`.
+     */
+    async recordResponse(input) {
+        const usage = extractUsage(input.response, {
+            provider: input.provider,
+            model: input.model,
+        });
+        return await this.recordCall({
+            workflowId: input.workflowId,
+            provider: usage.provider,
+            model: usage.model ?? "",
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            cacheReadTokens: usage.cacheReadTokens,
+            cacheCreationTokens: usage.cacheCreationTokens,
+            cacheCreation1hTokens: usage.cacheCreation1hTokens,
+            reasoningTokens: usage.reasoningTokens,
+            latencyMs: input.latencyMs,
+            status: input.status ?? "ok",
+            isRetry: input.isRetry,
+            sessionId: input.sessionId,
+            promptId: input.promptId,
+            operation: input.operation,
+            isSimulated: input.isSimulated,
+            substrate: input.substrate,
+        });
+    }
+    /**
+     * Return `fn` wrapped so every call is timed and auto-metered. The core
+     * auto-instrumentation primitive: give it any async LLM call
+     * (`client.chat.completions.create`, `client.messages.create`,
+     * `model.generateContent` …) and it returns a drop-in replacement that times
+     * the call, emits its economics from the returned response, and hands the
+     * ORIGINAL response back untouched. On a throw the call is metered with
+     * `status="error"` and the error re-thrown (never swallowed); a metering
+     * failure is fail-safe and never breaks the wrapped call. `provider` is
+     * required for a shape the extractor can't disambiguate; `model` supplies a
+     * model the response omits (Gemini); `resolveModel(args)` derives it per call
+     * (e.g. off a bound Gemini model). Signature-agnostic (`...args`).
+     */
+    wrap(fn, opts) {
+        const meter = this;
+        return async function (...args) {
+            let callModel = opts.model;
+            if (opts.resolveModel) {
+                try {
+                    const resolved = opts.resolveModel(args);
+                    if (resolved)
+                        callModel = resolved;
+                }
+                catch {
+                    /* a resolver hiccup never breaks the wrapped call */
+                }
+            }
+            // Ask OpenAI to include usage on a streamed call so the final chunk carries
+            // the count the accumulator needs (only when this is an OpenAI chat patch).
+            maybeInjectIncludeUsage(args, opts);
+            const start = now();
+            let response;
+            try {
+                response = (await fn(...args));
+            }
+            catch (e) {
+                const latencyMs = Math.round(now() - start);
+                try {
+                    await meter.recordCall({
+                        workflowId: opts.workflowId,
+                        provider: opts.provider ?? "unknown",
+                        model: callModel ?? "",
+                        latencyMs,
+                        status: "error",
+                        isRetry: opts.isRetry,
+                        sessionId: opts.sessionId,
+                        operation: opts.operation,
+                        isSimulated: opts.isSimulated,
+                        substrate: opts.substrate,
+                    });
+                }
+                catch {
+                    /* metering must never mask the host's real exception */
+                }
+                throw e;
+            }
+            // A streamed call resolves to an async-iterable of chunks, not a `.usage`
+            // response. Reading it here would throw and drop the call; instead hand back
+            // a transparent proxy that meters ONCE as the host consumes the stream.
+            if (isAsyncIterable(response)) {
+                return meteredStream(response, meter, opts, callModel, start);
+            }
+            const latencyMs = Math.round(now() - start);
+            try {
+                await meter.recordResponse({
+                    workflowId: opts.workflowId,
+                    response,
+                    provider: opts.provider,
+                    model: callModel,
+                    latencyMs,
+                    isRetry: opts.isRetry,
+                    sessionId: opts.sessionId,
+                    operation: opts.operation,
+                    isSimulated: opts.isSimulated,
+                    substrate: opts.substrate,
+                });
+            }
+            catch {
+                /* fail-safe: an unreadable response must not break the host call */
+            }
+            return response;
+        };
+    }
+}
+/** True when `x` is an async-iterable (a provider stream), never a plain response
+ *  object, string, or array. The clean discriminator between a streamed call and
+ *  a normal one after the wrapped fn resolves. */
+function isAsyncIterable(x) {
+    return (x != null &&
+        (typeof x === "object" || typeof x === "function") &&
+        typeof x[Symbol.asyncIterator] === "function");
+}
+/** When this wrapper is an OpenAI chat patch (`streamIncludeUsage`) AND the call
+ *  requests `stream: true`, add `stream_options.include_usage` so OpenAI emits its
+ *  usage on the final chunk. Clones the params object (never mutates the caller's),
+ *  and fills only when absent so an explicit caller choice is respected. */
+function maybeInjectIncludeUsage(args, opts) {
+    if (!opts.streamIncludeUsage)
+        return;
+    const params = args[0];
+    if (params == null || typeof params !== "object")
+        return;
+    const p = params;
+    if (p.stream !== true)
+        return;
+    const existing = p.stream_options;
+    if (existing == null) {
+        args[0] = { ...p, stream_options: { include_usage: true } };
+    }
+    else if (typeof existing === "object" &&
+        !("include_usage" in existing)) {
+        args[0] = {
+            ...p,
+            stream_options: { ...existing, include_usage: true },
+        };
+    }
+}
+/**
+ * A transparent proxy over a provider stream that meters on completion.
+ *
+ * The TS twin of `margin_meter`'s `_MeteredStream`. It hands every chunk to the
+ * host UNCHANGED while feeding it to a `StreamUsageAccumulator`; when the stream
+ * is exhausted, the host breaks early (its iterator's `return()`), or a chunk
+ * throws, it meters exactly once with the accumulated usage — or nothing when the
+ * stream carried no usage at all (an OpenAI stream without `include_usage`), since
+ * a zero-token row would misreport a real call as free. Every other property/method
+ * delegates to the wrapped stream, so `for await (const c of stream)`, `.tee()`,
+ * and the rest work unchanged. Fail-safe: a metering hiccup never breaks iteration.
+ */
+function meteredStream(stream, meter, opts, callModel, start) {
+    const acc = new StreamUsageAccumulator(opts.provider, callModel);
+    let finished = false;
+    const finish = async () => {
+        if (finished)
+            return;
+        finished = true;
+        const usage = acc.finalize();
+        // Honest: a stream that carried no usage is NOT recorded — there is no real
+        // token count and a zero-token row would report the call as free.
+        if (usage === undefined)
+            return;
+        const latencyMs = Math.round(now() - start);
+        try {
+            await meter.recordCall({
+                workflowId: opts.workflowId,
+                provider: usage.provider ?? opts.provider ?? "unknown",
+                model: usage.model ?? callModel ?? "",
+                inputTokens: usage.inputTokens,
+                outputTokens: usage.outputTokens,
+                cacheReadTokens: usage.cacheReadTokens,
+                cacheCreationTokens: usage.cacheCreationTokens,
+                cacheCreation1hTokens: usage.cacheCreation1hTokens,
+                reasoningTokens: usage.reasoningTokens,
+                latencyMs,
+                status: "ok",
+                isRetry: opts.isRetry,
+                sessionId: opts.sessionId,
+                operation: opts.operation,
+                isSimulated: opts.isSimulated,
+                substrate: opts.substrate,
+            });
+        }
+        catch {
+            /* metering must never mask the host's real result */
+        }
+    };
+    return new Proxy(stream, {
+        get(target, prop, receiver) {
+            if (prop === Symbol.asyncIterator) {
+                return function meteredAsyncIterator() {
+                    const inner = target[Symbol.asyncIterator]();
+                    return {
+                        async next() {
+                            let r;
+                            try {
+                                r = await inner.next();
+                            }
+                            catch (e) {
+                                await finish(); // a mid-stream error still banks the partial usage seen
+                                throw e;
+                            }
+                            if (r.done) {
+                                await finish(); // metered once, cleanly, at the end of the stream
+                            }
+                            else {
+                                try {
+                                    acc.observe(r.value);
+                                }
+                                catch {
+                                    /* a malformed chunk never breaks the host's read */
+                                }
+                            }
+                            return r;
+                        },
+                        async return(value) {
+                            await finish(); // the host broke early — meter what was seen
+                            if (typeof inner.return === "function") {
+                                return inner.return(value);
+                            }
+                            return { done: true, value };
+                        },
+                    };
+                };
+            }
+            const val = Reflect.get(target, prop, receiver);
+            return typeof val === "function"
+                ? val.bind(target)
+                : val;
+        },
+    });
 }
 /** Token accumulator passed into `measure`'s callback. */
 export class Measurement {
     inputTokens = 0;
     outputTokens = 0;
     cacheReadTokens = 0;
+    cacheCreationTokens = 0;
+    cacheCreation1hTokens = 0;
     result;
     setTokens(tokens) {
         this.inputTokens = tokens.inputTokens ?? 0;
         this.outputTokens = tokens.outputTokens ?? 0;
         this.cacheReadTokens = tokens.cacheReadTokens ?? 0;
+        this.cacheCreationTokens = tokens.cacheCreationTokens ?? 0;
+        this.cacheCreation1hTokens = tokens.cacheCreation1hTokens ?? 0;
     }
 }
 async function extractDetail(resp) {