agent-accelerator 0.3.0 → 0.4.5

package/src/session/store.ts

@@ -24,7 +24,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { Message, ContentPart } from "../types/message.ts";
-import type { TokenUsage, ThinkingLevel, CacheConfig } from "../types/core.ts";
+import type { TokenUsage, CacheConfig, ServiceTier } from "../types/core.ts";
+import type { ModelSpec } from "../types/model.ts";
 import type { AgentResponse } from "../types/response.ts";
 import { base64ToBytes } from "../utils/base64.ts";
 import { getModelFromCatalog } from "../models/catalog.ts";
@@ -111,7 +112,10 @@ function specFor(modelStr: string): ReturnType<typeof getModelFromCatalog> {
   }
 }
 
-/** Context window for telemetry display. Falls back to 1M like the chat CLI. */
+/** Context window for telemetry display. Falls back to 1M like the chat CLI.
+ * @deprecated (Q-34) Kept for compat; new code should use
+ * `getSessionContextWindowOrUndefined` and handle `undefined` explicitly.
+ */
 export function getSessionContextWindow(modelStr: string): number {
   try {
     const spec = specFor(modelStr);
@@ -127,20 +131,11 @@ export function computeSessionTurnCost(usage: TokenUsage, modelStr: string): num
   if (reported > 0) return reported;
   try {
     const spec = specFor(modelStr);
-    const inputP = spec?.pricing?.inputPerMillion ?? spec?.cost?.input ?? 0;
-    const outputP = spec?.pricing?.outputPerMillion ?? spec?.cost?.output ?? 0;
-    const crP = spec?.pricing?.cacheReadPerMillion ?? spec?.cost?.cache_read ?? 0;
-    const cwP = spec?.pricing?.cacheWritePerMillion ?? spec?.cost?.cache_write ?? 0;
-    if (!inputP && !outputP && !crP && !cwP) return 0;
-    const cr = usage.cachedTokens ?? usage.cacheReadTokens ?? 0;
-    const uncachedIn = Math.max(0, (usage.inputTokens ?? 0) - cr);
-    return (
-      (uncachedIn / 1e6) * inputP +
-      (cr / 1e6) * crP +
-      ((usage.cacheWriteTokens ?? 0) / 1e6) * cwP +
-      ((usage.outputTokens ?? 0) / 1e6) * outputP
-    );
+    const priced = priceUsage(usage, spec);
+    if (priced && typeof priced.totalCost === "number" && priced.totalCost > 0) return priced.totalCost;
+    return 0;
   } catch {
+    // why: cost is observability-only — pricing failures must never break turns.
     return 0;
   }
 }
@@ -404,6 +399,8 @@ export function serializeSession(data: PersistedAgentSession): string {
 export function deserializeSession(raw: string): PersistedAgentSession | null {
   const text = (raw ?? "").trim();
   if (!text) return null;
+  // Q-10: reject oversized payloads (>10MB JSON) — return null, no console.
+  if (text.length > MAX_SESSION_JSON_BYTES) return null;
   try {
     // Legacy JSONL: lines shaped {type: session|mainModel|subagentModel|metrics|message|...}
     if (text.startsWith('{"type"')) {
@@ -456,6 +453,8 @@ export function deserializeSession(raw: string): PersistedAgentSession | null {
         }
       }
       if (!sessionId && messages.length === 0) return null;
+      // Q-10: oversize guard — return null, no console.
+      if (messages.length > MAX_SESSION_MESSAGES) return null;
       return {
         version: 1,
         sessionId: sessionId || `accel-${Date.now()}`,
@@ -474,8 +473,12 @@ export function deserializeSession(raw: string): PersistedAgentSession | null {
     }
     const obj: any = JSON.parse(text);
     if (!obj || typeof obj !== "object") return null;
+    // Q-10: version check — reject unknown versions, accept legacy shapes
+    // that predate versioning (no version field).
+    if ("version" in obj && (obj as { version?: unknown }).version !== 1) return null;
     // Very old single-JSON shape without version: {sessionId, model, context:{messages}}
     if (obj.context && Array.isArray(obj.context.messages) && !Array.isArray(obj.messages)) {
+      if ((obj.context.messages as unknown[]).length > MAX_SESSION_MESSAGES) return null;
       return {
         version: 1,
         sessionId: obj.sessionId ?? obj.id ?? `accel-${Date.now()}`,
@@ -493,6 +496,9 @@ export function deserializeSession(raw: string): PersistedAgentSession | null {
       };
     }
     if (!obj.sessionId && !Array.isArray(obj.messages)) return null;
+    if (Array.isArray(obj.messages) && (obj.messages as unknown[]).length > MAX_SESSION_MESSAGES) return null;
+    if ("sessionId" in obj && obj.sessionId !== undefined && typeof obj.sessionId !== "string") return null;
+    if ("messages" in obj && obj.messages !== undefined && !Array.isArray(obj.messages)) return null;
     return {
       version: 1,
       sessionId: obj.sessionId ?? `accel-${Date.now()}`,
@@ -528,20 +534,29 @@ export function loadSessionFile(filePath: string): PersistedAgentSession | null
 export function writeFileAtomic(filePath: string, content: string): void {
   const dir = path.dirname(filePath);
   try {
-    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   } catch {}
   let tag = "tmp";
   try {
     const pid = (globalThis as any)?.process?.pid;
-    tag = `${typeof pid === "number" ? pid : "np"}-${Math.random().toString(36).slice(2, 8)}`;
+    const rand = (globalThis as any)?.crypto?.randomUUID?.().slice(0, 8) ?? Math.random().toString(36).slice(2, 8);
+    tag = `${typeof pid === "number" ? pid : "np"}-${rand}`;
   } catch {
     tag = Math.random().toString(36).slice(2, 8);
   }
   const tmp = `${filePath}.tmp-${tag}`;
-  fs.writeFileSync(tmp, content, "utf8");
+  fs.writeFileSync(tmp, content, { encoding: "utf8", mode: 0o600 });
+  try { fs.chmodSync(tmp, 0o600); } catch {}
   fs.renameSync(tmp, filePath);
 }
 
+/** Session id grammar: no traversal, no slashes, no hidden files. */
+export function assertValidSessionId(sessionId: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(sessionId)) {
+    throw new Error(`[Agent Accelerator] Invalid sessionId "${sessionId}": must match /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/`);
+  }
+}
+
 /** Saves an agent + telemetry snapshot as a pretty-printed `.json` document (2-space indent). */
 export function saveSessionFile(
   filePath: string,
@@ -549,6 +564,18 @@ export function saveSessionFile(
   telemetry?: SessionTelemetry | SessionTotals | null
 ): void {
   const resolved = path.resolve(filePath);
+  // Q-28-partial: never overwrite a corrupt file in place — quarantine it
+  // as `*.corrupt-<ts>` first (load returns null for corrupt payloads).
+  try {
+    if (fs.existsSync(resolved)) {
+      try {
+        const raw = fs.readFileSync(resolved, "utf8");
+        if (raw.trim().length > 0 && deserializeSession(raw) === null) {
+          try { fs.renameSync(resolved, `${resolved}.corrupt-${Date.now()}`); } catch {}
+        }
+      } catch {}
+    }
+  } catch {}
   const data = buildSessionData(agent, telemetry);
   try {
     writeFileAtomic(resolved, serializeSession(data) + "\n");
@@ -633,9 +660,21 @@ export function extractMediaToDir(
   sessionDir: string
 ): { messages: Message[]; wrote: string[] } {
   const cloned = cloneMessages(messages);
-  const mediaDir = path.join(sessionDir, "media");
+  const root = path.resolve(sessionDir);
+  const mediaDir = path.resolve(root, "media");
+  if (!mediaDir.startsWith(root + path.sep) && mediaDir !== root) {
+    throw new Error("[Agent Accelerator] Media dir escapes session dir");
+  }
   try {
-    fs.rmSync(mediaDir, { recursive: true, force: true });
+    fs.mkdirSync(mediaDir, { recursive: true, mode: 0o700 });
+  } catch {}
+  // Never rm -rf: remove only previously written media files matching our pattern.
+  try {
+    for (const f of fs.readdirSync(mediaDir)) {
+      if (/^(image|audio|video|file)-\d+\.[a-z0-9]{1,5}$/.test(f)) {
+        try { fs.unlinkSync(path.join(mediaDir, f)); } catch {}
+      }
+    }
   } catch {}
   const wrote: string[] = [];
   const counters: Record<string, number> = {};
@@ -669,8 +708,11 @@ export function extractMediaToDir(
       const ext = extForMedia(mimeType, typeof p.filename === "string" ? p.filename : undefined);
       const file = `${key}-${String(n).padStart(3, "0")}.${ext}`;
       try {
-        fs.mkdirSync(mediaDir, { recursive: true });
-        fs.writeFileSync(path.join(mediaDir, file), bytes);
+        fs.mkdirSync(mediaDir, { recursive: true, mode: 0o700 });
+        const dest = path.resolve(mediaDir, file);
+        if (!dest.startsWith(mediaDir + path.sep)) continue;
+        fs.writeFileSync(dest, bytes, { mode: 0o600 });
+        try { fs.chmodSync(dest, 0o600); } catch {}
       } catch {
         continue;
       }
@@ -680,22 +722,17 @@ export function extractMediaToDir(
     }
   }
 
-  // No embedded bytes: don't leave an empty media/ behind.
-  if (!hasBinary) {
-    try {
-      fs.rmSync(mediaDir, { recursive: true, force: true });
-    } catch {}
-  }
   return { messages: cloned, wrote };
 }
 
 /**
  * Resolves `media/…` relative refs to absolute paths anchored at the session
  * folder, so a resumed session runs from any cwd. Absolute paths, URLs, and
- * non-media strings pass through untouched.
+ * non-media strings pass through untouched. Rejects traversal outside dir.
  */
 export function resolveMediaPaths(messages: Message[], sessionDir: string): Message[] {
   const cloned = cloneMessages(messages);
+  const root = path.resolve(sessionDir);
   for (const msg of cloned) {
     if (!Array.isArray((msg as Message).content)) continue;
     for (const part of (msg as Message).content as ContentPart[]) {
@@ -704,16 +741,26 @@ export function resolveMediaPaths(messages: Message[], sessionDir: string): Mess
       if (!(MEDIA_PART_KEYS as readonly string[]).includes(p.type)) continue;
       const v = p[p.type] as unknown;
       if (typeof v === "string" && (v === "media" || v.startsWith("media/"))) {
-        p[p.type] = path.join(sessionDir, v);
+        if (v.includes("..") || path.isAbsolute(v)) continue;
+        const resolved = path.resolve(root, v);
+        if (!resolved.startsWith(root + path.sep) && resolved !== root) continue;
+        p[p.type] = resolved;
       }
     }
   }
   return cloned;
 }
 
-/** `<rootDir>/<sessionId>` — one folder per session. */
+/** `<rootDir>/<sessionId>` — one folder per session. Validates traversal. */
 export function sessionDirFor(rootDir: string, sessionId: string): string {
-  return path.join(path.resolve(rootDir), sessionId);
+  assertValidSessionId(sessionId);
+  const root = path.resolve(rootDir);
+  const dir = path.resolve(root, sessionId);
+  const rel = path.relative(root, dir);
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(`[Agent Accelerator] Session dir escapes root: ${sessionId}`);
+  }
+  return dir;
 }
 
 /**
@@ -726,6 +773,7 @@ export function saveSessionDir(
   agent: SessionAgentLike,
   telemetry?: SessionTelemetry | SessionTotals | null
 ): string {
+  // Q-28-partial: sessionDirFor already enforces assertValidSessionId.
   const sessionDir = sessionDirFor(rootDir, agent.sessionId);
   try {
     fs.mkdirSync(sessionDir, { recursive: true });
@@ -736,7 +784,19 @@ export function saveSessionDir(
     telemetry
   );
   try {
-    writeFileAtomic(path.join(sessionDir, "session.json"), serializeSession(data) + "\n");
+    const target = path.join(sessionDir, "session.json");
+    // Q-28-partial: quarantine corrupt targets instead of overwriting.
+    try {
+      if (fs.existsSync(target)) {
+        try {
+          const raw = fs.readFileSync(target, "utf8");
+          if (raw.trim().length > 0 && deserializeSession(raw) === null) {
+            try { fs.renameSync(target, `${target}.corrupt-${Date.now()}`); } catch {}
+          }
+        } catch {}
+      }
+    } catch {}
+    writeFileAtomic(target, serializeSession(data) + "\n");
   } catch {
     // persistence must never crash a chat turn
   }
@@ -804,3 +864,431 @@ export function findLatestSessionDir(rootDir: string): string | null {
     return null;
   }
 }
+
+// ---------------------------------------------------------------------------
+// Q-10: session validation (append-only; deserializeSession above only gained
+// size/version guards, no behavior change otherwise).
+// ---------------------------------------------------------------------------
+
+/** Max messages accepted in a session snapshot (Q-10). */
+export const MAX_SESSION_MESSAGES = 5000;
+/** Max raw JSON bytes accepted in deserializeSession (Q-10). */
+export const MAX_SESSION_JSON_BYTES = 10 * 1024 * 1024;
+
+function sessionLoadError(message: string): Error {
+  const e = new Error(`[Agent Accelerator] Invalid session: ${message}`);
+  e.name = "SessionLoadError";
+  return e;
+}
+
+/**
+ * Manual Zod-like validation for session snapshots (Q-10, no new deps).
+ * Checks `version===1`, string `sessionId`, array `messages`, and oversize
+ * (>5000 messages or >10MB JSON). Throws a `SessionLoadError`-named Error
+ * on failure; returns the typed session on success.
+ */
+export function validateSessionData(data: unknown): PersistedAgentSession {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw sessionLoadError("expected an object");
+  }
+  const obj = data as Record<string, unknown>;
+  if (obj.version !== 1) {
+    throw sessionLoadError(`unsupported version ${String((obj as { version?: unknown }).version)} (expected 1)`);
+  }
+  if (typeof obj.sessionId !== "string" || obj.sessionId.length === 0) {
+    throw sessionLoadError("sessionId must be a non-empty string");
+  }
+  if (!Array.isArray(obj.messages)) {
+    throw sessionLoadError("messages must be an array");
+  }
+  if ((obj.messages as unknown[]).length > MAX_SESSION_MESSAGES) {
+    throw sessionLoadError(`too many messages (${(obj.messages as unknown[]).length} > ${MAX_SESSION_MESSAGES})`);
+  }
+  let approxBytes = 0;
+  try {
+    approxBytes = JSON.stringify(data)?.length ?? 0;
+  } catch {
+    throw sessionLoadError("session is not JSON-serializable");
+  }
+  if (approxBytes > MAX_SESSION_JSON_BYTES) {
+    throw sessionLoadError(`session JSON too large (${approxBytes} > ${MAX_SESSION_JSON_BYTES} bytes)`);
+  }
+  return data as PersistedAgentSession;
+}
+
+// ---------------------------------------------------------------------------
+// Q-34: context-window lookup without the legacy 1M fallback.
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the catalog context window for a model, or `undefined` when unknown
+ * (Q-34). Prefer this over `getSessionContextWindow` for new code.
+ */
+export function getSessionContextWindowOrUndefined(modelStr: string): number | undefined {
+  try {
+    const spec = specFor(modelStr);
+    if (spec?.limit?.context) return spec.limit.context;
+    if (spec?.contextWindow) return spec.contextWindow;
+  } catch {
+    // why: catalog lookup is best-effort — unknown models yield undefined.
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Q-41: telemetry bus (no console.* in library code).
+// ---------------------------------------------------------------------------
+
+/** Telemetry event emitted via the in-process bus (Q-41). */
+export interface TelemetryEvent {
+  code: string;
+  message: string;
+  level?: "info" | "warn" | "error";
+  data?: unknown;
+  timestamp: number;
+}
+
+/** Listener subscribed via `telemetryBus.onEvent`. */
+export type TelemetryListener = (event: TelemetryEvent) => void;
+
+interface TelemetryBus {
+  /** Subscribes to telemetry events. Returns an unsubscribe function. Default: no-op delivery (no listeners, no console). */
+  onEvent(listener: TelemetryListener): () => void;
+  /** Emits a warning (level `warn`). Never throws, never logs to console. */
+  emitWarning(code: string, message: string, data?: unknown): void;
+  /** Emits a generic event. Never throws, never logs to console. */
+  emit(event: Omit<TelemetryEvent, "timestamp"> & { timestamp?: number }): void;
+  /** Removes all listeners (useful in tests). */
+  clear(): void;
+}
+
+/**
+ * In-process telemetry bus (Q-41). Library code routes warnings/anomalies
+ * here instead of `console.*`. Default has zero listeners so emission is a
+ * no-op; CLIs/tests attach a pretty logger via `onEvent`.
+ */
+export const telemetryBus: TelemetryBus = (() => {
+  const listeners = new Set<TelemetryListener>();
+  const deliver = (event: TelemetryEvent): void => {
+    for (const l of [...listeners]) {
+      try { l(event); } catch {
+        // why: a faulty telemetry listener must not break the emitting run.
+      }
+    }
+  };
+  return {
+    onEvent(listener: TelemetryListener): () => void {
+      listeners.add(listener);
+      return () => { listeners.delete(listener); };
+    },
+    emitWarning(code: string, message: string, data?: unknown): void {
+      try {
+        deliver({ code, message, level: "warn", data, timestamp: Date.now() });
+      } catch {
+        // why: telemetry emission is observability-only.
+      }
+    },
+    emit(event: Omit<TelemetryEvent, "timestamp"> & { timestamp?: number }): void {
+      try {
+        deliver({ level: "info", ...event, timestamp: event.timestamp ?? Date.now() });
+      } catch {
+        // why: telemetry emission is observability-only.
+      }
+    },
+    clear(): void {
+      listeners.clear();
+    },
+  };
+})();
+
+/** Reports a usage/cost anomaly via the global hook + telemetry bus (Q-35). Never logs. */
+export function reportUsageAnomaly(detail: { type: string; [k: string]: unknown }): void {
+  try {
+    (globalThis as unknown as { __agentAccelAnomaly?: (d: unknown) => void }).__agentAccelAnomaly?.(detail);
+  } catch {
+    // why: anomaly hooks are third-party — must never throw into the loop.
+  }
+  try {
+    telemetryBus.emitWarning(detail.type, `usage anomaly: ${detail.type}`, detail);
+  } catch {
+    // why: telemetry emission is observability-only.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Q-35: canonical usage invariants.
+// ---------------------------------------------------------------------------
+/**
+ * Canonical usage invariants (provider-agnostic, Q-35):
+ * - all token counts are finite integers >= 0;
+ * - `cachedTokens` / `cacheReadTokens` are a SUBSET of `inputTokens`
+ *   (cache hits cannot exceed input; aggregates clamp — see `accumulateUsage`
+ *   in `agent/loop.ts`), so hit rates never exceed 100%;
+ * - `thinkingTokens` is a SUBSET of `outputTokens` when both are reported
+ *   (reasoning is generated output); providers that omit one side are
+ *   accepted, only impossible `thinking > output` with both present fails.
+ *
+ * Test helper: throws an Error describing the first violation, returns void
+ * when invariants hold. Not called in hot paths (validation only).
+ */
+export function assertUsageInvariants(usage: TokenUsage): void {
+  const fail = (msg: string): never => {
+    throw new Error(`[Agent Accelerator] Invalid usage: ${msg}`);
+  };
+  const ints: Array<[string, unknown]> = [
+    ["inputTokens", usage.inputTokens],
+    ["outputTokens", usage.outputTokens],
+    ["totalTokens", usage.totalTokens],
+  ];
+  for (const [k, v] of ints) {
+    if (typeof v !== "number" || !Number.isFinite(v as number) || (v as number) < 0) {
+      fail(`${k} must be a finite number >= 0 (got ${String(v)})`);
+    }
+  }
+  const optional: Array<[string, unknown]> = [
+    ["cachedTokens", usage.cachedTokens],
+    ["cacheReadTokens", usage.cacheReadTokens],
+    ["cacheWriteTokens", usage.cacheWriteTokens],
+    ["thinkingTokens", usage.thinkingTokens],
+  ];
+  for (const [k, v] of optional) {
+    if (v === undefined) continue;
+    if (typeof v !== "number" || !Number.isFinite(v as number) || (v as number) < 0) {
+      fail(`${k} must be a finite number >= 0 when present (got ${String(v)})`);
+    }
+  }
+  const input = usage.inputTokens ?? 0;
+  for (const k of ["cachedTokens", "cacheReadTokens"] as const) {
+    const v = usage[k] ?? 0;
+    if (v > input) fail(`${k} (${v}) exceeds inputTokens (${input})`);
+  }
+  if (usage.thinkingTokens !== undefined && usage.outputTokens !== undefined) {
+    if (usage.thinkingTokens > usage.outputTokens) {
+      fail(`thinkingTokens (${usage.thinkingTokens}) exceeds outputTokens (${usage.outputTokens})`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Q-36: one cost model — integer micro-USD accumulation.
+// ---------------------------------------------------------------------------
+
+/** Where a priced cost came from (Q-36). Unknown stays unknown, never 0. */
+export type CostSource = "provider" | "catalog" | "unknown";
+
+/** Integer micro-USD breakdown behind a priced cost (Q-36). */
+export interface CostBreakdown {
+  inputMicroUSD: number;
+  outputMicroUSD: number;
+  cacheReadMicroUSD: number;
+  cacheWriteMicroUSD: number;
+  audioMicroUSD: number;
+  totalMicroUSD: number;
+  /** Which price tier applied (`base` or e.g. `context_over_200k` / `tiers:<size>`). */
+  tier: string;
+  /** Multiplier applied for the service tier (estimate — see below). */
+  serviceTierMultiplier: number;
+  serviceTier?: string;
+}
+
+/** Cost result of `priceUsage`: compat cost fields + source + breakdown. */
+export type PricedCost = NonNullable<TokenUsage["cost"]> & {
+  source: CostSource;
+  breakdown: CostBreakdown;
+};
+
+/**
+ * Service-tier price multipliers (Q-36). Aligned with pi
+ * (`api/openai-responses.ts:387`): `flex` trades latency for ~0.5x price,
+ * `priority`/`fast` reserve capacity at ~2x (`2.5x` for `gpt-5.5`).
+ * Standard/default is 1.0. Estimates because vendors do not publish exact
+ * tier multipliers in the catalog.
+ */
+const SERVICE_TIER_MULTIPLIERS: Record<string, number> = {
+  flex: 0.5,
+  priority: 2,
+  fast: 2,
+};
+
+function serviceTierMultiplier(serviceTier?: string, modelId?: string): { multiplier: number; tier?: string } {
+  if (!serviceTier) return { multiplier: 1 };
+  const lower = serviceTier.toLowerCase();
+  if (lower === "priority" || lower === "fast") {
+    if (typeof modelId === "string" && modelId.includes("gpt-5.5")) {
+      return { multiplier: 2.5, tier: serviceTier };
+    }
+    return { multiplier: 2, tier: serviceTier };
+  }
+  const m = SERVICE_TIER_MULTIPLIERS[lower];
+  return m !== undefined ? { multiplier: m, tier: serviceTier } : { multiplier: 1, tier: serviceTier };
+}
+
+function toDollars(microUSD: number): number {
+  return microUSD / 1_000_000;
+}
+
+/**
+ * Resolves effective per-1M pricing for a usage snapshot (Q-36). When
+ * `usage.inputTokens > 200_000` and the catalog carries `cost.tiers` or
+ * `cost.context_over_200k`, the over-200k tier prices apply; otherwise base
+ * `pricing.*` (falling back to legacy `cost.*`) applies.
+ */
+function resolveEffectivePricing(
+  spec: ModelSpec | undefined,
+  inputTokens: number
+): { input: number; output: number; cacheRead: number; cacheWrite: number; audio: number; tier: string } {
+  const base = {
+    input: spec?.pricing?.inputPerMillion ?? (spec?.cost?.input as number | undefined) ?? 0,
+    output: spec?.pricing?.outputPerMillion ?? (spec?.cost?.output as number | undefined) ?? 0,
+    cacheRead: spec?.pricing?.cacheReadPerMillion ?? (spec?.cost?.cache_read as number | undefined) ?? 0,
+    cacheWrite: spec?.pricing?.cacheWritePerMillion ?? (spec?.cost?.cache_write as number | undefined) ?? 0,
+    audio:
+      spec?.pricing?.inputAudioPerMillion ?? (spec?.cost as { input_audio?: number } | undefined)?.input_audio ?? 0,
+  };
+  if (!spec || inputTokens <= 200_000) return { ...base, tier: "base" };
+  const over = spec.cost?.context_over_200k as { input?: number; output?: number; cache_read?: number } | undefined;
+  if (over && (over.input || over.output || over.cache_read)) {
+    return {
+      input: over.input ?? base.input,
+      output: over.output ?? base.output,
+      cacheRead: over.cache_read ?? base.cacheRead,
+      cacheWrite: base.cacheWrite,
+      audio: base.audio,
+      tier: "context_over_200k",
+    };
+  }
+  const tiers = spec.cost?.tiers;
+  if (Array.isArray(tiers) && tiers.length > 0) {
+    let best: { input: number; output: number; cache_read?: number; size: number } | undefined;
+    for (const t of tiers as Array<{ tier?: { type?: string; size?: number }; input?: number; output?: number; cache_read?: number }>) {
+      const size = typeof t?.tier?.size === "number" ? t.tier.size : undefined;
+      if (size === undefined || size > inputTokens) continue;
+      const type = String(t?.tier?.type ?? "").toLowerCase();
+      if (type && type !== "context" && !type.includes("context")) continue;
+      if (!best || size > best.size) {
+        best = { input: t.input ?? base.input, output: t.output ?? base.output, cache_read: t.cache_read, size };
+      }
+    }
+    if (best) {
+      return {
+        input: best.input,
+        output: best.output,
+        cacheRead: best.cache_read ?? base.cacheRead,
+        cacheWrite: base.cacheWrite,
+        audio: base.audio,
+        tier: `tiers:${best.size}`,
+      };
+    }
+  }
+  return { ...base, tier: "base" };
+}
+
+/**
+ * Prices one usage snapshot with integer micro-USD accumulation (Q-36).
+ *
+ * - Provider-reported `usage.cost.totalCost > 0` wins (source `provider`).
+ * - Else catalog pricing via `resolveEffectivePricing` (source `catalog`).
+ * - Else returns `undefined` (source `unknown` is implicit) — unknown stays
+ *   unknown, never a fabricated 0 object.
+ * - Audio tokens (`usage.audioTokens` / `usage.inputAudioTokens` when present)
+ *   price at `pricing.inputAudioPerMillion` / `cost.input_audio` and fold into
+ *   the total (separately itemized in `breakdown.audioMicroUSD`).
+ * - `opts.serviceTier` (`flex` ~0.5x, `priority` ~1.5x, estimates) scales the
+ *   catalog total; provider-reported costs are never rescaled.
+ */
+export function priceUsage(
+  usage: TokenUsage,
+  spec?: ModelSpec,
+  opts?: { serviceTier?: ServiceTier | string; modelId?: string }
+): PricedCost | undefined {
+  const reported = usage?.cost;
+  if (reported && typeof reported.totalCost === "number" && reported.totalCost > 0) {
+    const micro = (d?: number): number => (typeof d === "number" && d > 0 ? Math.round(d * 1_000_000) : 0);
+    const inputMicroUSD = micro(reported.inputCost);
+    const outputMicroUSD = micro(reported.outputCost);
+    const cacheReadMicroUSD = micro(reported.cacheReadCost);
+    const cacheWriteMicroUSD = micro(reported.cacheWriteCost);
+    const totalMicroUSD = Math.round(reported.totalCost * 1_000_000);
+    return {
+      inputCost: reported.inputCost,
+      outputCost: reported.outputCost,
+      cacheReadCost: reported.cacheReadCost,
+      cacheWriteCost: reported.cacheWriteCost,
+      totalCost: reported.totalCost,
+      source: "provider",
+      breakdown: {
+        inputMicroUSD,
+        outputMicroUSD,
+        cacheReadMicroUSD,
+        cacheWriteMicroUSD,
+        audioMicroUSD: 0,
+        totalMicroUSD,
+        tier: "provider-reported",
+        serviceTierMultiplier: 1,
+      },
+    };
+  }
+  if (!spec) return undefined;
+  const inputTokens = usage.inputTokens ?? 0;
+  const outputTokens = usage.outputTokens ?? 0;
+  const cachedTokens = usage.cachedTokens ?? usage.cacheReadTokens ?? 0;
+  const cacheWriteTokens = usage.cacheWriteTokens ?? 0;
+  const audioTokens =
+    (usage as { audioTokens?: unknown }).audioTokens ??
+    (usage as { inputAudioTokens?: unknown }).inputAudioTokens ??
+    0;
+  const audioCount = typeof audioTokens === "number" && Number.isFinite(audioTokens) && audioTokens > 0 ? Math.round(audioTokens) : 0;
+  const pricing = resolveEffectivePricing(spec, inputTokens);
+  if (!pricing.input && !pricing.output && !pricing.cacheRead && !pricing.cacheWrite && !pricing.audio) {
+    return undefined;
+  }
+  const { multiplier, tier: serviceTier } = serviceTierMultiplier(opts?.serviceTier, opts?.modelId ?? spec?.id);
+  const nonCachedInput = Math.max(0, inputTokens - cachedTokens);
+  // Integer micro-USD accumulation: microUSD = tokens * pricePerMillion
+  // ($P per 1M tokens == $P/1e6 per token == P micro-USD per token).
+  const inputMicroUSD = Math.round(nonCachedInput * pricing.input * multiplier);
+  const cacheReadMicroUSD = Math.round(cachedTokens * pricing.cacheRead * multiplier);
+  const cacheWriteMicroUSD = Math.round(cacheWriteTokens * pricing.cacheWrite * multiplier);
+  const outputMicroUSD = Math.round(outputTokens * pricing.output * multiplier);
+  const audioMicroUSD = Math.round(audioCount * pricing.audio * multiplier);
+  const totalMicroUSD = inputMicroUSD + cacheReadMicroUSD + cacheWriteMicroUSD + outputMicroUSD + audioMicroUSD;
+  return {
+    inputCost: toDollars(inputMicroUSD),
+    outputCost: toDollars(outputMicroUSD + audioMicroUSD),
+    cacheReadCost: toDollars(cacheReadMicroUSD),
+    cacheWriteCost: toDollars(cacheWriteMicroUSD),
+    totalCost: toDollars(totalMicroUSD),
+    source: "catalog",
+    breakdown: {
+      inputMicroUSD,
+      outputMicroUSD,
+      cacheReadMicroUSD,
+      cacheWriteMicroUSD,
+      audioMicroUSD,
+      totalMicroUSD,
+      tier: pricing.tier,
+      serviceTierMultiplier: multiplier,
+      ...(serviceTier ? { serviceTier } : {}),
+    },
+  };
+}
+
+/**
+ * Computes and attaches catalog pricing to a usage snapshot (Q-36).
+ * Keeps provider-reported costs untouched; returns the cost (or undefined
+ * when unknown). Never fabricates a 0 object for unknown pricing.
+ */
+export function addCostToUsage(
+  usage: TokenUsage,
+  spec?: ModelSpec,
+  opts?: { serviceTier?: ServiceTier | string }
+): TokenUsage["cost"] | undefined {
+  if (usage?.cost && typeof usage.cost.totalCost === "number" && usage.cost.totalCost > 0) {
+    return usage.cost;
+  }
+  const priced = priceUsage(usage, spec, opts);
+  if (!priced) return usage.cost;
+  const { source: _source, breakdown: _breakdown, ...cost } = priced;
+  usage.cost = cost;
+  return usage.cost;
+}