@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/wire/usage.mjs

@@ -0,0 +1,192 @@
+/**
+ * lib/engine/wire/usage.mjs — token-usage normalisation for both wires (pure).
+ *
+ * The engine reports usage in the ONE record shape the Cohort Compute design
+ * fixes (hq docs/cohort-llm/design.md §4.5), so the gateway's meter, the
+ * engine's JSON result and maestro's ledger never disagree about what a token
+ * class means:
+ *
+ *   { inputUncached, cacheRead, cacheWrite5m, cacheWrite1h, output, reasoning,
+ *     usageSource: 'provider' | 'provider_partial' | 'estimated' }
+ *
+ * The two wires count differently, and getting that wrong double-bills cache:
+ *   · Anthropic Messages — `input_tokens` EXCLUDES cache; the cache classes are
+ *     reported beside it. Stream usage is cumulative: the last value wins.
+ *   · OpenAI Chat (DeepInfra) — `prompt_tokens` INCLUDES
+ *     `prompt_tokens_details.cached_tokens` and DeepInfra's `cache_write_tokens`,
+ *     so uncached input is the remainder. Usage lands on the finish chunk or a
+ *     trailing chunk: the last one wins.
+ *
+ * `reasoning` is informational: reasoning tokens are already inside `output`
+ * on both wires and are billed as output. It is never added to a total.
+ *
+ * All counts are non-negative integers. Garbage in (strings, negatives, NaN)
+ * is clamped to 0 rather than thrown — a malformed usage object from an
+ * upstream must not crash a run, and the gateway, not the engine, is the
+ * billing authority.
+ *
+ * @module lib/engine/wire/usage
+ */
+
+/**
+ * @typedef {Object} NormalisedUsage
+ * @property {number} inputUncached
+ * @property {number} cacheRead
+ * @property {number} cacheWrite5m
+ * @property {number} cacheWrite1h
+ * @property {number} output
+ * @property {number} reasoning
+ * @property {'provider'|'provider_partial'|'estimated'} usageSource
+ */
+
+/** @param {unknown} v @returns {number} */
+function count(v) {
+  const n = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN;
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+}
+
+/** @returns {NormalisedUsage} */
+export function emptyUsage(usageSource = "provider") {
+  return { inputUncached: 0, cacheRead: 0, cacheWrite5m: 0, cacheWrite1h: 0, output: 0, reasoning: 0, usageSource };
+}
+
+/** The `usageSource` values the design fixes. Anything else is not trusted as stated. */
+const USAGE_SOURCES = new Set(["provider", "provider_partial", "estimated"]);
+
+/**
+ * Read the `usage` object the gateway puts on its terminal `event: cohort`
+ * frame (CF-158).
+ *
+ * MEASURED against the live gateway on 2026-09-22
+ * (`req_bf94feaab6405214071532a5`, cohort-fast, Anthropic wire): the frame's
+ * `usage` is EXACTLY this module's {@link NormalisedUsage} shape — all six
+ * counts plus `usageSource: "provider"` — not a wire-shaped usage object.
+ *
+ *   "usage": {"inputUncached":109,"cacheRead":0,"cacheWrite5m":0,
+ *             "cacheWrite1h":0,"output":66,"reasoning":0,"usageSource":"provider"}
+ *
+ * It is NOT in hq's design §4.8 contract (see docs/engine/eval.md §3), so it is
+ * read defensively and never depended on: a missing or malformed object yields
+ * `null` rather than zeros, so a caller can tell "the gateway said nothing"
+ * from "the gateway said zero". Unknown fields are ignored, every count is
+ * clamped to a non-negative integer, and an unstated or unrecognised
+ * `usageSource` is downgraded to `provider_partial` rather than claimed as
+ * `provider`. Nothing here throws.
+ *
+ * @param {unknown} u
+ * @returns {NormalisedUsage|null} null when there is no usable object
+ */
+export function readFrameUsage(u) {
+  if (!u || typeof u !== "object" || Array.isArray(u)) return null;
+  const o = /** @type {any} */ (u);
+  return {
+    inputUncached: count(o.inputUncached),
+    cacheRead: count(o.cacheRead),
+    cacheWrite5m: count(o.cacheWrite5m),
+    cacheWrite1h: count(o.cacheWrite1h),
+    output: count(o.output),
+    reasoning: count(o.reasoning),
+    usageSource: typeof o.usageSource === "string" && USAGE_SOURCES.has(o.usageSource) ? o.usageSource : "provider_partial",
+  };
+}
+
+/**
+ * Normalise an Anthropic Messages `usage` object.
+ * @param {any} u
+ * @returns {NormalisedUsage}
+ */
+export function normaliseAnthropicUsage(u) {
+  if (!u || typeof u !== "object") return emptyUsage("estimated");
+  const split = u.cache_creation && typeof u.cache_creation === "object" ? u.cache_creation : null;
+  let cacheWrite5m;
+  let cacheWrite1h;
+  if (split) {
+    cacheWrite5m = count(split.ephemeral_5m_input_tokens);
+    cacheWrite1h = count(split.ephemeral_1h_input_tokens);
+  } else {
+    // No TTL split reported: the default ephemeral TTL is 5 minutes.
+    cacheWrite5m = count(u.cache_creation_input_tokens);
+    cacheWrite1h = 0;
+  }
+  return {
+    inputUncached: count(u.input_tokens),
+    cacheRead: count(u.cache_read_input_tokens),
+    cacheWrite5m,
+    cacheWrite1h,
+    output: count(u.output_tokens),
+    reasoning: 0,
+    usageSource: u.input_tokens === undefined || u.output_tokens === undefined ? "provider_partial" : "provider",
+  };
+}
+
+/**
+ * Normalise an OpenAI Chat `usage` object (DeepInfra / OpenRouter dialect).
+ * @param {any} u
+ * @returns {NormalisedUsage}
+ */
+export function normaliseOpenAIUsage(u) {
+  if (!u || typeof u !== "object") return emptyUsage("estimated");
+  const details = u.prompt_tokens_details && typeof u.prompt_tokens_details === "object" ? u.prompt_tokens_details : {};
+  const prompt = count(u.prompt_tokens);
+  const cacheRead = count(details.cached_tokens);
+  const cacheWrite = count(details.cache_write_tokens ?? u.cache_write_tokens);
+  const completionDetails =
+    u.completion_tokens_details && typeof u.completion_tokens_details === "object" ? u.completion_tokens_details : {};
+  // A provider reporting more cached than prompt tokens is inconsistent; never
+  // let uncached input go negative (that would under-count, silently).
+  const inputUncached = Math.max(0, prompt - cacheRead - cacheWrite);
+  return {
+    inputUncached,
+    cacheRead,
+    cacheWrite5m: cacheWrite,
+    cacheWrite1h: 0,
+    output: count(u.completion_tokens),
+    reasoning: count(completionDetails.reasoning_tokens),
+    usageSource:
+      u.prompt_tokens === undefined || u.completion_tokens === undefined || cacheRead + cacheWrite > prompt
+        ? "provider_partial"
+        : "provider",
+  };
+}
+
+/**
+ * Sum two normalised records (per-turn usage → per-run usage). The source is
+ * the weakest of the two: one estimated turn makes the run estimated.
+ * @param {NormalisedUsage} a @param {NormalisedUsage} b @returns {NormalisedUsage}
+ */
+export function addUsage(a, b) {
+  const rank = { provider: 0, provider_partial: 1, estimated: 2 };
+  const src = rank[b.usageSource] > rank[a.usageSource] ? b.usageSource : a.usageSource;
+  return {
+    inputUncached: a.inputUncached + b.inputUncached,
+    cacheRead: a.cacheRead + b.cacheRead,
+    cacheWrite5m: a.cacheWrite5m + b.cacheWrite5m,
+    cacheWrite1h: a.cacheWrite1h + b.cacheWrite1h,
+    output: a.output + b.output,
+    reasoning: a.reasoning + b.reasoning,
+    usageSource: src,
+  };
+}
+
+/**
+ * Total tokens a normalised record accounts for (reasoning excluded — it is
+ * inside output).
+ * @param {NormalisedUsage} n @returns {number}
+ */
+export function totalTokens(n) {
+  return n.inputUncached + n.cacheRead + n.cacheWrite5m + n.cacheWrite1h + n.output;
+}
+
+/**
+ * Project onto the `usage` block of the claude `--print` JSON result, which
+ * maestro's dispatcher, responder and ledger already parse.
+ * @param {NormalisedUsage} n
+ */
+export function toResultUsage(n) {
+  return {
+    input_tokens: n.inputUncached,
+    output_tokens: n.output,
+    cache_read_input_tokens: n.cacheRead,
+    cache_creation_input_tokens: n.cacheWrite5m + n.cacheWrite1h,
+  };
+}