@cohortapp/agent-sdk 2.3.0

package/lib/model-router/ledger.mjs

@@ -0,0 +1,402 @@
+/**
+ * lib/model-router/ledger.mjs — cost ledger v2 + catalog-priced cost estimation.
+ *
+ * Two responsibilities:
+ *
+ *   1. estimateCost(catalog, usage) — price a unit of work PER MODEL from the
+ *      catalog's `cost` block ($/MTok), cache-ratio aware. This fixes W7 (the v1
+ *      estimator priced from a single backend `pricing` object regardless of the
+ *      resolved model). It is the budgeting figure the resolve lane stamps onto a
+ *      RouteDecision.estCostUSD and that budget-guard sums.
+ *
+ *   2. writeLedgerRow / buildLedgerRow — emit a ledger v2 row to
+ *      state/cost-tracking/<date>.jsonl. CRITICAL COMPATIBILITY CONTRACT:
+ *      lib/budget-guard.mjs sums `row.estimated_usd` and counts each row as one
+ *      session. We therefore ALWAYS emit `estimated_usd` alongside the richer v2
+ *      fields (total_cost_usd, estimated, per-model token breakdown). Breaking
+ *      `estimated_usd` would silently zero out the daily budget — do not.
+ *
+ * Volatile pricing rule (graft #12): a row whose cost_provenance.volatile is true
+ * (DeepSeek/Kimi/Qwen — promo-cycle prone) is BUDGETED at its steady-state
+ * (higher) figure, never the promo sticker. The steady-state numbers live in
+ * row.cost.tiered[] as `{ kind: "steady_state", input, output, cache_read }`.
+ * When a volatile row has no steady_state tier we fall back to the sticker (and
+ * the caller still sees `volatile:true` in the returned breakdown).
+ *
+ * Tiered-by-prompt-size rule (Qwen hazard, §5.1): a row whose tiered[] entries
+ * are `{ kind: "input_range", min_input_tokens, max_input_tokens, input, output }`
+ * is priced at the bracket whose [min,max) range contains the actual input token
+ * count (cache-read + miss input combined).
+ *
+ * House style (lib/rate-guard.mjs, lib/cadence-bus.mjs): ESM .mjs, Node builtins
+ * only beyond the catalog import, everything injectable (`deps.now`,
+ * `deps.ledgerDir`, `deps.agentRoot`), and the WRITE path never throws (a ledger
+ * we can't persist degrades silently rather than crashing a spawn).
+ *
+ * @module lib/model-router/ledger
+ */
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { lookupModel } from "./catalog.mjs";
+import { appendJsonl } from "../fs-atomic.mjs";
+
+const MTOK = 1e6;
+
+// ---------------------------------------------------------------------------
+// Pricing selection (volatile -> steady-state; tiered-by-prompt-size)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pick the effective per-MTok rates for a row given the input token count and
+ * whether we are BUDGETING (volatile -> steady-state) or pricing actuals.
+ *
+ * @param {object} row              normalised catalog row (cost block)
+ * @param {number} inputTokens      total input tokens (cache_read + miss)
+ * @param {boolean} budget          true = budgeting (project volatile high)
+ * @returns {{input:number|null, output:number|null, cache_read:number|null,
+ *            cache_write:number|null, basis:string, volatile:boolean}}
+ */
+function selectRates(row, inputTokens, budget) {
+  const cost = (row && row.cost) || {};
+  const volatile = !!(row && row.cost_provenance && row.cost_provenance.volatile);
+  let input = cost.input ?? null;
+  let output = cost.output ?? null;
+  let cache_read = cost.cache_read ?? null;
+  let cache_write = cost.cache_write ?? null;
+  let basis = "sticker";
+
+  const tiered = Array.isArray(cost.tiered) ? cost.tiered : [];
+
+  // 1. Prompt-size tiering (applies to actuals AND budget alike).
+  const rangeTiers = tiered.filter((t) => t && t.kind === "input_range");
+  if (rangeTiers.length) {
+    const tier = pickInputRangeTier(rangeTiers, inputTokens);
+    if (tier) {
+      if (tier.input != null) input = tier.input;
+      if (tier.output != null) output = tier.output;
+      if (tier.cache_read !== undefined) cache_read = tier.cache_read;
+      if (tier.cache_write !== undefined) cache_write = tier.cache_write;
+      basis = "input_range";
+    }
+  }
+
+  // 2. Volatile budgeting: project at the steady-state (higher) figure.
+  if (budget && volatile) {
+    const steady = tiered.find((t) => t && t.kind === "steady_state");
+    if (steady) {
+      if (steady.input != null) input = Math.max(input ?? 0, steady.input);
+      if (steady.output != null) output = Math.max(output ?? 0, steady.output);
+      if (steady.cache_read != null) cache_read = Math.max(cache_read ?? 0, steady.cache_read);
+      if (steady.cache_write != null) cache_write = Math.max(cache_write ?? 0, steady.cache_write);
+      basis = "steady_state";
+    } else {
+      // No explicit steady-state tier: keep sticker but flag the basis so the
+      // caller knows the projection is unhedged.
+      basis = basis === "input_range" ? "input_range:volatile" : "sticker:volatile";
+    }
+  }
+
+  return { input, output, cache_read, cache_write, basis, volatile };
+}
+
+function pickInputRangeTier(tiers, inputTokens) {
+  const n = Number.isFinite(inputTokens) ? inputTokens : 0;
+  // tiers expected sorted ascending by min; tolerate unsorted input.
+  let best = null;
+  for (const t of tiers) {
+    const min = Number(t.min_input_tokens ?? 0);
+    const max = t.max_input_tokens == null ? Infinity : Number(t.max_input_tokens);
+    if (n >= min && n < max) {
+      if (!best || min > Number(best.min_input_tokens ?? 0)) best = t;
+    }
+  }
+  // If nothing matched (n beyond the top bracket's max), use the highest tier.
+  if (!best && tiers.length) {
+    best = tiers.reduce((a, b) =>
+      Number(b.min_input_tokens ?? 0) > Number(a.min_input_tokens ?? 0) ? b : a
+    );
+  }
+  return best;
+}
+
+// ---------------------------------------------------------------------------
+// estimateCost — the public pricing function
+// ---------------------------------------------------------------------------
+
+/**
+ * Estimate the USD cost of a unit of work, catalog-priced per MODEL and
+ * cache-ratio aware. NEVER throws — returns `{ usd: null, ... }` when the row
+ * or its prices are missing.
+ *
+ * Token semantics:
+ *   inputTokens      = total input tokens (INCLUDING cache reads), i.e. the full
+ *                      prompt size. The cache_read portion is re-priced at the
+ *                      cheaper cache_read rate; the remainder at the input rate.
+ *                      This matches Anthropic's billing model and the v1
+ *                      estimator's `cache_hit_ratio` intent (W7-correct now).
+ *   cacheReadTokens  = how many of `inputTokens` hit the cache.
+ *   cacheWriteTokens = tokens written to cache this call (priced at cache_write,
+ *                      which on Anthropic rows is the 1h-write premium).
+ *   outputTokens     = generated tokens.
+ *
+ * @param {object} catalog  result of loadCatalog (or its .catalog) — anything
+ *                          lookupModel accepts
+ * @param {object} usage
+ *   @param {string} usage.provider
+ *   @param {string} usage.model       (or pass usage.ref = "provider/model")
+ *   @param {string} [usage.ref]
+ *   @param {number} [usage.inputTokens=0]
+ *   @param {number} [usage.outputTokens=0]
+ *   @param {number} [usage.cacheReadTokens=0]
+ *   @param {number} [usage.cacheWriteTokens=0]
+ *   @param {boolean} [usage.budget=true]  true = budget projection (volatile
+ *                                         priced at steady-state). Pass false to
+ *                                         price observed actuals at sticker.
+ * @returns {{
+ *   usd: number|null, ref: string|null, basis: string, volatile: boolean,
+ *   breakdown: { inputUsd:number, cacheReadUsd:number, cacheWriteUsd:number,
+ *                outputUsd:number }
+ * }}
+ */
+export function estimateCost(catalog, usage = {}) {
+  const ref = usage.ref || (usage.provider && usage.model ? `${usage.provider}/${usage.model}` : null);
+  const empty = {
+    usd: null,
+    ref,
+    basis: "no-row",
+    volatile: false,
+    breakdown: { inputUsd: 0, cacheReadUsd: 0, cacheWriteUsd: 0, outputUsd: 0 },
+  };
+  if (!ref) return empty;
+  const row = lookupModel(catalog, ref);
+  if (!row) return empty;
+
+  const inputTokens = nonNeg(usage.inputTokens);
+  const outputTokens = nonNeg(usage.outputTokens);
+  const cacheReadTokens = Math.min(nonNeg(usage.cacheReadTokens), inputTokens);
+  const cacheWriteTokens = nonNeg(usage.cacheWriteTokens);
+  const missInputTokens = Math.max(0, inputTokens - cacheReadTokens);
+  const budget = usage.budget !== false;
+
+  const rates = selectRates(row, inputTokens, budget);
+
+  // If we have no input/output price at all, we cannot estimate.
+  if (rates.input == null && rates.output == null) {
+    return { ...empty, basis: rates.basis, volatile: rates.volatile };
+  }
+
+  const inputRate = rates.input ?? 0;
+  // cache_read price: a `none` cache_control row (or missing rate) is priced
+  // cache-blind — every input token at the full input rate (G8 / §6.5 rule 4).
+  const cacheControl = (row.compat && row.compat.cache_control) || "none";
+  const cacheReadRate =
+    rates.cache_read != null ? rates.cache_read : cacheControl === "none" ? inputRate : 0;
+  const cacheWriteRate = rates.cache_write ?? 0;
+  const outputRate = rates.output ?? 0;
+
+  const inputUsd = (missInputTokens / MTOK) * inputRate;
+  const cacheReadUsd = (cacheReadTokens / MTOK) * cacheReadRate;
+  const cacheWriteUsd = (cacheWriteTokens / MTOK) * cacheWriteRate;
+  const outputUsd = (outputTokens / MTOK) * outputRate;
+
+  const usd = round6(inputUsd + cacheReadUsd + cacheWriteUsd + outputUsd);
+
+  return {
+    usd,
+    ref,
+    basis: rates.basis,
+    volatile: rates.volatile,
+    breakdown: {
+      inputUsd: round6(inputUsd),
+      cacheReadUsd: round6(cacheReadUsd),
+      cacheWriteUsd: round6(cacheWriteUsd),
+      outputUsd: round6(outputUsd),
+    },
+  };
+}
+
+function nonNeg(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+function round6(n) {
+  return Number(n.toFixed(6));
+}
+
+// ---------------------------------------------------------------------------
+// Ledger row v2 — builder + writer (budget-guard compatible)
+// ---------------------------------------------------------------------------
+
+function ledgerDir(deps) {
+  if (deps && deps.ledgerDir) return resolve(deps.ledgerDir);
+  const root =
+    (deps && deps.agentRoot) ||
+    process.env.AGENT_ROOT ||
+    process.env.AGENT_DIR ||
+    process.cwd();
+  return join(resolve(root), "state", "cost-tracking");
+}
+
+function todayUtc(deps) {
+  const now = (deps && typeof deps.now === "function" ? deps.now : Date.now)();
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+function ledgerFile(deps) {
+  return join(ledgerDir(deps), `${todayUtc(deps)}.jsonl`);
+}
+
+/**
+ * Build a ledger v2 row (§4.7) WITHOUT writing it. Pure; safe to inspect/test.
+ *
+ * The cost is taken from `entry.totalCostUSD` when supplied (e.g. the
+ * `total_cost_usd` field of a `--output-format json` result — the authoritative
+ * Anthropic figure), otherwise computed via estimateCost from the catalog.
+ *
+ * @param {object} catalog
+ * @param {object} entry
+ *   @param {string} entry.agent
+ *   @param {string} [entry.session_id]
+ *   @param {string} [entry.decision_id]
+ *   @param {string} [entry.task_class]
+ *   @param {string} [entry.source]
+ *   @param {string} [entry.lane]
+ *   @param {string} [entry.harness]
+ *   @param {string} entry.provider          (or entry.ref)
+ *   @param {string} entry.model
+ *   @param {string} [entry.ref]
+ *   @param {number} [entry.inputTokens]
+ *   @param {number} [entry.outputTokens]
+ *   @param {number} [entry.cacheReadTokens]
+ *   @param {number} [entry.cacheWriteTokens]
+ *   @param {number} [entry.totalCostUSD]    authoritative cost from result-json
+ *   @param {number} [entry.durationMs]
+ *   @param {string} [entry.exitReason]      taxonomy reason or "ok"
+ * @param {object} [deps]  { now }
+ * @returns {object} ledger row (includes the load-bearing `estimated_usd`)
+ */
+export function buildLedgerRow(catalog, entry = {}, deps = {}) {
+  const ref = entry.ref || (entry.provider && entry.model ? `${entry.provider}/${entry.model}` : null);
+  const [provider, ...idParts] = (ref || "/").split("/");
+  const model = entry.model || idParts.join("/") || null;
+
+  const inputTokens = nonNeg(entry.inputTokens);
+  const outputTokens = nonNeg(entry.outputTokens);
+  const cacheReadTokens = nonNeg(entry.cacheReadTokens);
+  const cacheWriteTokens = nonNeg(entry.cacheWriteTokens);
+
+  const hasAuthoritative =
+    typeof entry.totalCostUSD === "number" && Number.isFinite(entry.totalCostUSD);
+
+  // For the ledger we want the BUDGETING figure when estimating (volatile rows
+  // projected at steady-state) so budget-guard never under-counts.
+  const est = estimateCost(catalog, {
+    ref,
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+    budget: true,
+  });
+
+  const totalCostUSD = hasAuthoritative ? round6(entry.totalCostUSD) : est.usd;
+  const estimated = !hasAuthoritative;
+  // Load-bearing: budget-guard sums `estimated_usd`. Use the authoritative cost
+  // when present, else the estimate. Never null here (default 0) so a row always
+  // counts as a session with a finite spend.
+  const estimated_usd = totalCostUSD == null ? 0 : totalCostUSD;
+
+  const now = (deps && typeof deps.now === "function" ? deps.now : Date.now)();
+
+  return {
+    ts: new Date(now).toISOString(),
+    agent: entry.agent ?? null,
+    session_id: entry.session_id ?? null,
+    decision_id: entry.decision_id ?? null,
+    task_class: entry.task_class ?? null,
+    source: entry.source ?? null,
+    lane: entry.lane ?? null,
+    harness: entry.harness ?? null,
+    backend: provider || null,
+    model,
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cache_read_tokens: cacheReadTokens,
+    cache_creation_tokens: cacheWriteTokens,
+    total_cost_usd: totalCostUSD,
+    // --- budget-guard compatibility (DO NOT REMOVE) ---
+    estimated_usd,
+    // ---------------------------------------------------
+    estimated,
+    cost_basis: est.basis,
+    volatile: est.volatile,
+    duration_ms: entry.durationMs ?? null,
+    exit_reason: entry.exitReason ?? "ok",
+  };
+}
+
+/**
+ * Append a ledger v2 row to state/cost-tracking/<date>.jsonl. NEVER throws
+ * (uses appendJsonl, which returns false on IO failure). Returns the row that
+ * was written (or attempted) plus a `written` flag.
+ *
+ * @param {object} catalog
+ * @param {object} entry  see buildLedgerRow
+ * @param {object} [deps] { now, ledgerDir, agentRoot }
+ * @returns {{ row: object, written: boolean, path: string }}
+ */
+export function writeLedgerRow(catalog, entry = {}, deps = {}) {
+  const row = buildLedgerRow(catalog, entry, deps);
+  const path = ledgerFile(deps);
+  try {
+    mkdirSync(ledgerDir(deps), { recursive: true });
+  } catch {
+    /* best-effort */
+  }
+  const written = appendJsonl(path, row);
+  return { row, written, path };
+}
+
+/**
+ * Sum today's ledger the SAME way budget-guard does (reads `estimated_usd`),
+ * for tests / `maestro cost report`. NEVER throws.
+ *
+ * @param {object} [deps] { now, ledgerDir, agentRoot }
+ * @returns {{ spentUSD:number, sessions:number, byModel:Record<string,number> }}
+ */
+export function sumLedgerToday(deps = {}) {
+  const file = ledgerFile(deps);
+  const out = { spentUSD: 0, sessions: 0, byModel: {} };
+  if (!existsSync(file)) return out;
+  let body;
+  try {
+    body = readFileSync(file, "utf-8");
+  } catch {
+    return out;
+  }
+  for (const line of body.split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const usd = Number(row.estimated_usd);
+    if (Number.isFinite(usd)) {
+      out.spentUSD += usd;
+      const key = row.model || row.backend || "unknown";
+      out.byModel[key] = round6((out.byModel[key] || 0) + usd);
+    }
+    out.sessions += 1;
+  }
+  out.spentUSD = round6(out.spentUSD);
+  return out;
+}
+
+export const _internals = { selectRates, pickInputRangeTier, ledgerFile, MTOK };
+
+export default { estimateCost, buildLedgerRow, writeLedgerRow, sumLedgerToday };