@ngockhoale/ukit 3.4.23 → 3.4.25

package/scripts/audit/subagent-cost/reader.mjs

@@ -0,0 +1,320 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { createHash } from 'node:crypto';
+
+const sha1 = (value) => createHash('sha1').update(value).digest('hex').slice(0, 12);
+const timestampMs = (value) => {
+  const result = typeof value === 'number' ? value : Date.parse(value);
+  return Number.isFinite(result) ? result : null;
+};
+const estimateTokens = (text) => (text ? Math.ceil(text.length / 4) : 0);
+const contentText = (content) => {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.filter((part) => part?.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text).join('\n');
+};
+
+async function readJsonl(file, stats, consume) {
+  const stream = fs.createReadStream(file, { encoding: 'utf8' });
+  const lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
+  try {
+    for await (const line of lines) {
+      stats.lines += 1;
+      if (!line.trim()) continue;
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        stats.malformed += 1;
+        continue;
+      }
+      consume(record);
+    }
+  } finally {
+    lines.close();
+    stream.destroy();
+  }
+}
+
+function transcriptFiles(root) {
+  const files = [];
+  const rootEntries = fs.readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of rootEntries) {
+    const entryPath = path.join(root, entry.name);
+    if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+      files.push({ file: entryPath, sessionId: entry.name.slice(0, -'.jsonl'.length), isAgent: false });
+    }
+  }
+  for (const entry of rootEntries) {
+    if (!entry.isDirectory()) continue;
+    const sessionDir = path.join(root, entry.name);
+    const subagentsDir = path.join(sessionDir, 'subagents');
+    let subagentEntries;
+    try {
+      subagentEntries = fs.readdirSync(subagentsDir, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') continue;
+      throw error;
+    }
+    for (const agentEntry of subagentEntries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!agentEntry.isFile() || !agentEntry.name.endsWith('.jsonl')) continue;
+      const stem = agentEntry.name.slice(0, -'.jsonl'.length);
+      files.push({
+        file: path.join(subagentsDir, agentEntry.name),
+        metaFile: path.join(subagentsDir, `${stem}.meta.json`),
+        sessionId: entry.name,
+        agentId: stem.replace(/^agent-/, ''),
+        isAgent: true,
+      });
+    }
+  }
+  return files;
+}
+
+async function readMeta(file) {
+  try {
+    const value = JSON.parse(await fs.promises.readFile(file, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function makeCall(record, sessionId, agentId, agentType, depth, ts, priorTs) {
+  const message = record.message ?? {};
+  const usage = message.usage ?? {};
+  const input = Number(usage.input_tokens) || 0;
+  const cacheRead = Number(usage.cache_read_input_tokens ?? usage.cache_read_tokens) || 0;
+  const cacheWrite = Number(usage.cache_creation_input_tokens ?? usage.cache_creation_tokens) || 0;
+  const output = Number(usage.output_tokens) || 0;
+  const key = message.id ?? record.requestId ?? record.uuid;
+  return {
+    id: key == null ? null : String(key),
+    sessionId,
+    turnId: null,
+    agentId: agentId ?? null,
+    agentType: agentType ?? null,
+    model: message.model ?? record.model ?? null,
+    ts,
+    latencyMs: ts != null && priorTs != null && ts >= priorTs ? ts - priorTs : null,
+    input,
+    cacheRead,
+    cacheWrite,
+    output,
+    zero: input === 0 && cacheRead === 0 && cacheWrite === 0 && output === 0,
+    depth,
+    _dedupeKey: key == null ? null : String(key),
+  };
+}
+
+function hashFinalReferences(finalText, parentText) {
+  if (!finalText || !parentText) return null;
+  const words = (text) => text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+  const finalWords = words(finalText);
+  const parentWords = words(parentText);
+  if (finalWords.length < 5 || parentWords.length < 5) return null;
+  const grams = new Set();
+  for (let i = 0; i <= parentWords.length - 5; i += 1) {
+    grams.add(sha1(parentWords.slice(i, i + 5).join(' ')));
+  }
+  let matches = 0;
+  let total = 0;
+  for (let i = 0; i <= finalWords.length - 5; i += 1) {
+    total += 1;
+    if (grams.has(sha1(finalWords.slice(i, i + 5).join(' ')))) matches += 1;
+  }
+  return total ? matches / total : null;
+}
+
+export async function loadCorpus(root, { since = null, until = null } = {}) {
+  let rootStat;
+  try {
+    rootStat = fs.statSync(root);
+  } catch {
+    throw new Error(`root not found: ${root}`);
+  }
+  if (!rootStat.isDirectory()) throw new Error(`root not found: ${root}`);
+
+  const stats = {
+    files: 0, lines: 0, malformed: 0, zeroUsage: 0, dupIds: 0,
+    missingMeta: 0, noParent: 0, unattributed: 0,
+  };
+  const files = transcriptFiles(root);
+  const mainFilesBySession = new Map();
+  const agentFiles = [];
+  const promptRecordsBySession = new Map();
+  const toolUsesBySession = new Map();
+  const calls = [];
+  const agents = [];
+  const turns = [];
+  const sinceMs = since == null ? null : timestampMs(since);
+  const untilMs = until == null ? null : timestampMs(until);
+
+  for (const fileInfo of files) {
+    stats.files += 1;
+    const meta = fileInfo.isAgent ? await readMeta(fileInfo.metaFile) : null;
+    if (fileInfo.isAgent && !meta) stats.missingMeta += 1;
+    const agentType = fileInfo.isAgent ? (meta?.agentType ?? null) : null;
+    const depth = fileInfo.isAgent
+      ? (Number.isFinite(meta?.spawnDepth) ? meta.spawnDepth : 1)
+      : 0;
+    const deduped = new Map();
+    const userRecords = [];
+    let previousTs = null;
+    let finalAssistantText = null;
+
+    await readJsonl(fileInfo.file, stats, (record) => {
+      const ts = timestampMs(record.timestamp);
+      if (!fileInfo.isAgent && record.type === 'user' && !record.isSidechain) {
+        const body = contentText(record.message?.content ?? record.content);
+        if (body.trim()) userRecords.push({ ts, body });
+      }
+      if (record.type !== 'assistant') return;
+
+      const call = makeCall(
+        record,
+        fileInfo.sessionId,
+        fileInfo.isAgent ? fileInfo.agentId : null,
+        fileInfo.isAgent ? (agentType ?? record.attributionAgent ?? 'unknown') : null,
+        depth,
+        ts,
+        previousTs,
+      );
+      previousTs = ts;
+      const key = call._dedupeKey ?? `line:${stats.lines}`;
+      if (deduped.has(key) && call._dedupeKey != null) stats.dupIds += 1;
+      deduped.set(key, { call, record });
+
+      if (fileInfo.isAgent) {
+        const text = contentText(record.message?.content);
+        if (text) finalAssistantText = text;
+      } else {
+        for (const part of record.message?.content ?? []) {
+          if (part?.type !== 'tool_use' || typeof part.id !== 'string') continue;
+          if (!toolUsesBySession.has(fileInfo.sessionId)) toolUsesBySession.set(fileInfo.sessionId, new Map());
+          toolUsesBySession.get(fileInfo.sessionId).set(part.id, { ts, record, tool: part });
+        }
+      }
+    });
+
+    const records = [...deduped.values()];
+    if (fileInfo.isAgent) {
+      agentFiles.push({ fileInfo, meta, agentType, depth, records, finalAssistantText });
+    } else {
+      mainFilesBySession.set(fileInfo.sessionId, records);
+      promptRecordsBySession.set(fileInfo.sessionId, userRecords);
+    }
+  }
+
+  const turnsBySession = new Map();
+  for (const [sessionId, prompts] of promptRecordsBySession) {
+    prompts.sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
+    const sessionTurns = prompts.map((prompt, index) => ({
+      turnId: `${sessionId}#${index + 1}`,
+      sessionId,
+      ts: prompt.ts,
+      promptHash: sha1(prompt.body),
+      promptTokensEst: estimateTokens(prompt.body),
+    }));
+    turnsBySession.set(sessionId, sessionTurns);
+    turns.push(...sessionTurns);
+  }
+
+  function turnForTime(sessionId, ts) {
+    const sessionTurns = turnsBySession.get(sessionId) ?? [];
+    let selected = null;
+    for (const turn of sessionTurns) {
+      if (ts == null || turn.ts == null || turn.ts <= ts) selected = turn;
+      else break;
+    }
+    return selected;
+  }
+
+  const parentTextBySessionTurn = new Map();
+  for (const [sessionId, records] of mainFilesBySession) {
+    let latestTurn = null;
+    const assistantTextsByTurn = new Map();
+    for (const { call, record } of records) {
+      const turn = turnForTime(sessionId, call.ts);
+      if (turn) latestTurn = turn;
+      call.turnId = latestTurn?.turnId ?? `${sessionId}#unattributed`;
+      if (record.message?.content) {
+        const text = contentText(record.message.content);
+        if (text) assistantTextsByTurn.set(call.turnId, text);
+      }
+      calls.push(call);
+    }
+    for (const [turnId, text] of assistantTextsByTurn) {
+      parentTextBySessionTurn.set(`${sessionId}\u0000${turnId}`, text);
+    }
+  }
+
+  agentFiles.sort((a, b) => {
+    const aTs = a.records[0]?.call.ts ?? 0;
+    const bTs = b.records[0]?.call.ts ?? 0;
+    return aTs - bTs || a.fileInfo.agentId.localeCompare(b.fileInfo.agentId);
+  });
+  const agentsById = new Map();
+  for (const { fileInfo, meta, agentType, depth, records, finalAssistantText } of agentFiles) {
+    const toolUseId = meta?.toolUseId ?? null;
+    const parent = toolUseId == null ? null : toolUsesBySession.get(fileInfo.sessionId)?.get(toolUseId) ?? null;
+    if (!parent) stats.noParent += 1;
+    const turn = parent ? turnForTime(fileInfo.sessionId, parent.ts) : null;
+    const turnId = turn?.turnId ?? `${fileInfo.sessionId}#unattributed`;
+    if (!turn) stats.unattributed += 1;
+
+    const delegatedPrompt = typeof parent?.tool?.input?.prompt === 'string' ? parent.tool.input.prompt : '';
+    const description = typeof meta?.description === 'string' ? meta.description : '';
+    const segments = delegatedPrompt.split(/\n\s*\n/)
+      .map((segment) => segment.trim())
+      .filter((segment) => segment.length >= 200)
+      .map((segment) => ({ h: sha1(segment), t: estimateTokens(segment) }));
+    const firstTs = records.reduce((value, item) => item.call.ts == null ? value : value == null ? item.call.ts : Math.min(value, item.call.ts), null);
+    const lastTs = records.reduce((value, item) => item.call.ts == null ? value : value == null ? item.call.ts : Math.max(value, item.call.ts), null);
+    const parentText = parentTextBySessionTurn.get(`${fileInfo.sessionId}\u0000${turnId}`) ?? '';
+    const agent = {
+      agentId: fileInfo.agentId,
+      sessionId: fileInfo.sessionId,
+      turnId,
+      agentType: agentType ?? records.find((item) => item.record.attributionAgent)?.record.attributionAgent ?? 'unknown',
+      descriptionHash: description ? sha1(description) : null,
+      toolUseId,
+      depth,
+      parentAgentId: meta?.parentAgentId ?? null,
+      metaModel: meta?.model ?? null,
+      hasMeta: Boolean(meta),
+      promptHash: delegatedPrompt ? sha1(delegatedPrompt) : null,
+      promptTokensEst: delegatedPrompt ? estimateTokens(delegatedPrompt) : null,
+      segments,
+      finalTokensEst: finalAssistantText ? estimateTokens(finalAssistantText) : null,
+      finalRefRatio: hashFinalReferences(finalAssistantText, parentText),
+      firstTs,
+      lastTs,
+    };
+    agents.push(agent);
+    agentsById.set(`${fileInfo.sessionId}\u0000${fileInfo.agentId}`, agent);
+    for (const { call } of records) {
+      call.turnId = turnId;
+      calls.push(call);
+    }
+  }
+
+  // Resolve explicit parent-agent links when the parent transcript is present; retain null for unknown links.
+  for (const agent of agents) {
+    if (agent.parentAgentId != null) {
+      const parent = agentsById.get(`${agent.sessionId}\u0000${agent.parentAgentId}`);
+      if (parent && agent.turnId.endsWith('#unattributed')) agent.turnId = parent.turnId;
+    }
+  }
+
+  stats.zeroUsage = calls.reduce((count, call) => count + (call.zero ? 1 : 0), 0);
+  const filteredCalls = calls.filter((call) =>
+    (sinceMs == null || (call.ts != null && call.ts >= sinceMs)) &&
+    (untilMs == null || (call.ts != null && call.ts <= untilMs)));
+  for (const call of filteredCalls) {
+    delete call._dedupeKey;
+  }
+  return { calls: filteredCalls, turns, agents, stats };
+}

package/scripts/audit/subagent-cost/render.mjs

@@ -0,0 +1,34 @@
+const fmt = (value) => value == null || !Number.isFinite(value) ? 'N/A' : Number(value).toLocaleString('en-US', { maximumFractionDigits: 3 });
+const table = (headers, rows) => [`| ${headers.join(' | ')} |`, `| ${headers.map(() => '---').join(' | ')} |`, ...rows.map((row) => `| ${row.map((cell) => String(cell ?? 'N/A').replaceAll('|', '\\|').replaceAll('\n', ' ')).join(' | ')} |`)].join('\n');
+
+export function renderMarkdown(report) {
+  const m = report.metrics ?? {};
+  const d = report.duplicates ?? {};
+  const totals = m.totals ?? {};
+  const typeRows = Object.entries(m.byType ?? {}).sort(([a], [b]) => a.localeCompare(b))
+    .map(([type, value]) => [type, value.agents, value.calls, fmt(value.inputSide), fmt(value.uncached), fmt(value.output), fmt(value.latencyP50)]);
+  const topRows = (items, key) => (items ?? []).map((item) => [item[key], item.agentType ?? 'N/A', item.calls, fmt(item.uncached), fmt(item.inputSide), fmt(item.output)]);
+  const flowRows = (m.tokenFlow ?? []).flatMap((turn) => turn.calls.map((call) => [turn.turnId, new Date(call.ts).toISOString(), call.agentType ?? 'main', call.depth, fmt(call.input), fmt(call.cacheRead), fmt(call.cacheWrite), fmt(call.output)]));
+  const flags = (value) => (value?.turnIds ?? []).map((turnId) => [turnId]);
+  return [
+    '# Sub-agent cost audit report',
+    '',
+    `Generated: ${report.generatedAt}`, `Root: ${report.root}`, `Window: ${report.window?.since ?? 'all'} — ${report.window?.until ?? 'all'}`,
+    '', '## Totals', '',
+    table(['Group', 'Calls', 'Input', 'Cache read', 'Cache write', 'Output', 'Uncached', 'Input-side'], ['main', 'sub'].map((key) => { const t = totals[key] ?? {}; return [key, t.calls, fmt(t.input), fmt(t.cacheRead), fmt(t.cacheWrite), fmt(t.output), fmt(t.uncached), fmt(t.inputSide)]; })),
+    '', '## Main vs sub-agent', '', table(['Metric', 'Value'], Object.entries(m.share ?? {}).map(([key, value]) => [key, fmt(value)])),
+    '', '## By type', '', table(['Type', 'Agents', 'Calls', 'Input-side', 'Uncached', 'Output', 'Latency p50 ms'], typeRows),
+    '', '## Fan-out', '', table(['Metric', 'Value'], [['Maximum', m.fanout?.max], ['p90', fmt(m.fanout?.p90)], ...Object.entries(m.fanout?.histogram ?? {}).map(([count, turns]) => [`${count} agents`, turns])]),
+    '', '## Cache', '', table(['Group', 'Hit rate', 'Cache read', 'Input-side'], ['main', 'sub'].map((key) => { const c = m.cache?.[key] ?? {}; return [key, fmt(c.hitRate), fmt(c.cacheRead), fmt(c.inputSide)]; })),
+    '', '## Top agents (20)', '', table(['Agent', 'Type', 'Calls', 'Uncached', 'Input-side', 'Output'], topRows(m.topAgents, 'agentId')),
+    '', '## Top turns (20)', '', table(['Turn', 'Type', 'Calls', 'Uncached', 'Input-side', 'Output'], topRows(m.topTurns, 'turnId')),
+    '', '## Token flow (5 costliest turns)', '', table(['Turn', 'Timestamp', 'Type', 'Depth', 'Input', 'Cache read', 'Cache write', 'Output'], flowRows),
+    '', '## N+1 flags', '', table(['Turn'], flags(m.nPlusOne)),
+    '', '## Retry flags', '', table(['Turn'], flags(m.retryLoops)),
+    '', '## Repeated-loop flags', '', table(['Turn'], flags(m.loops)),
+    '', '## Heavy calls and replay hypothesis', '', table(['Metric', 'Value'], [['Heavy calls', m.heavyCalls?.count], ['Heavy share', fmt(m.heavyCalls?.share)], ['Replay verdict', d.replayHypothesis?.verdict], ['Replay share', fmt(d.replayHypothesis?.share)]]),
+    '', '## Context duplication', '', table(['Metric', 'Value'], [['Amplification', fmt(d.amplification)], ['Duplicate context ratio', fmt(d.duplicateRatio)], ['Within-turn ratio', fmt(d.withinTurn?.ratio)], ['Cross-turn ratio', fmt(d.crossTurn?.ratio)]]),
+    '', '## Missing telemetry', '', ...(report.missing ?? []).map((item) => `- ${item}`),
+    '',
+  ].join('\n');
+}

package/src/cli/commands/telemetry.js

@@ -3,6 +3,7 @@
 //
 //   collect          ingestStoredTelemetry → flush → maybeRefreshSupport (canary+)
 //   status [--json]  stage, segments, counters, support lag, crashes
+//   usage [--json]   read-only usage-readiness report over the segment store
 //   digest [--json]  rebuildIndex → anomalies + digest markdown
 //   export-support   projectSupport now (explicit user act — works below canary)
 //   import <path>    validateSupportBundle on a received bundle
@@ -29,6 +30,10 @@ import { ingestStoredTelemetry } from '../../core/observability/adapters/ingest.
 import { listSegments, totalSegmentBytes } from '../../core/observability/segments/internal.js';
 import { readSegments } from '../../core/observability/segments/readSegments.js';
 import { rebuildIndex } from '../../core/observability/analytics/rebuild.js';
+import {
+  buildUsageReadiness,
+  renderUsageReadiness,
+} from '../../core/observability/analytics/usageReadiness.js';
 import { renderStoreDigest } from '../../core/observability/analytics/storeDigest.js';
 import { renderTraceDigest } from '../../core/observability/analytics/digest.js';
 import {
@@ -43,8 +48,8 @@ import { isValidOperationId } from '../../core/agentRuntime/eventStore.js';
 import { runEvaluation } from '../../core/observability/evaluation/runner.js';
 
 const HELP_FLAGS = new Set(['--help', '-h', 'help']);
-const SUBCOMMANDS = new Set(['collect', 'status', 'digest', 'export-support', 'export-run', 'import', 'evaluate']);
-const JSON_SUBCOMMANDS = new Set(['status', 'digest', 'evaluate']);
+const SUBCOMMANDS = new Set(['collect', 'status', 'usage', 'digest', 'export-support', 'export-run', 'import', 'evaluate']);
+const JSON_SUBCOMMANDS = new Set(['status', 'usage', 'digest', 'evaluate']);
 
 // The automatic support refresh's canary gate lives in schedule.js via
 // resolveSeamStages (projector seam minimum) — the CLI does not pre-gate.
@@ -61,6 +66,7 @@ function printUsage() {
   console.log('  collect          Ingest stored telemetry into the flight recorder,');
   console.log('                   flush it, and refresh the support view (stage canary+)');
   console.log('  status           Show stage, segments, counters, support lag, crashes');
+  console.log('  usage            Read-only usage readiness report over the segment store');
   console.log('  digest           Rebuild the trace index; print anomalies + digest markdown');
   console.log('  export-support   Write the sanitized UKit Support bundle now');
   console.log('  export-run <op>  Write a sanitized per-run support bundle (V-06)');
@@ -68,7 +74,7 @@ function printUsage() {
   console.log('  evaluate         Run the AI evaluator lane (needs observability.evaluator config)');
   console.log('');
   console.log('Options:');
-  console.log('  --json           JSON output (status, digest, evaluate)');
+  console.log('  --json           JSON output (status, usage, digest, evaluate)');
   console.log('  -h, --help       Show this help');
 }
 
@@ -337,6 +343,59 @@ async function digestCommand({ projectRoot, json }) {
   console.log(out.join('\n'));
 }
 
+// --- usage --------------------------------------------------------------------
+
+// Scan cap (SPEC FR-07): at most 200,000 records feed the report; the reader
+// limit is one higher so a 200001st record can mark the scan as truncated.
+const USAGE_SCAN_LIMIT = 200_000;
+
+// Read-only readiness scan (TASK-C98-006, SPEC §5 FR-07): never getRecorder,
+// never a flush, never mkdir, never a quarantine — the store looks after
+// `usage` exactly as it looked before. Dispatched before loadConfig so the
+// report cannot create a runtime config either.
+async function usageCommand({ projectRoot, json }) {
+  const root = segmentsRoot(projectRoot);
+  const stream = readSegments(root, { readOnly: true, limit: USAGE_SCAN_LIMIT + 1 });
+  const records = [];
+  let truncated = false;
+  for await (const record of stream) {
+    if (records.length === USAGE_SCAN_LIMIT) {
+      truncated = true;
+      break;
+    }
+    records.push(record);
+  }
+  const report = buildUsageReadiness(records, {
+    coverage: stream.coverage,
+    truncated,
+    scanLimit: USAGE_SCAN_LIMIT,
+  });
+  if (json) console.log(JSON.stringify(report));
+  else console.log(renderUsageReadiness(report));
+
+  // Segment-level degradation stays exit 0 — the report itself declares the
+  // gap (unquarantined segments, degraded entries). Only a root-level degrade
+  // (the segments root itself unreadable, e.g. io_enotdir on a file at that
+  // path) is this command's typed failure; the resolveRoot io_enoent on a
+  // not-yet-existing tree is the missing-store success, not a failure
+  // (SPEC FR-07). resolveRoot reports the realpath'd root (macOS /var →
+  // /private/var), so compare against both spellings.
+  const degraded = Array.isArray(stream.coverage.degraded) ? stream.coverage.degraded : [];
+  let realRoot = root;
+  try {
+    realRoot = await fs.realpath(root);
+  } catch {
+    // Root absent (empty store) — the literal spelling is the only one.
+  }
+  const rootDegrade = degraded.find(
+    (e) => e && (e.file === root || e.file === realRoot) && e.reason !== 'io_enoent',
+  );
+  if (rootDegrade) {
+    console.error(`[UKit] telemetry usage failed: ${rootDegrade.reason}`);
+    process.exitCode = 2;
+  }
+}
+
 // --- export-support / import --------------------------------------------------
 
 async function exportSupportCommand({ projectRoot, config }) {
@@ -506,9 +565,13 @@ export async function runTelemetry({ projectRoot, packageRoot, argv = [] }) {
     return;
   }
 
-  const config = await loadConfig(projectRoot);
   const json = flags.includes('--json');
 
+  // Read-only scan — config is not needed and must not be created (FR-07).
+  if (sub === 'usage') return usageCommand({ projectRoot, json });
+
+  const config = await loadConfig(projectRoot);
+
   if (sub === 'collect') return collectCommand({ projectRoot, config });
   if (sub === 'status') return statusCommand({ projectRoot, config, json });
   if (sub === 'digest') return digestCommand({ projectRoot, json });

package/src/cli/index.js

@@ -141,7 +141,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('  memory             Inspect shared UKit memory');
     console.log('  playbook           List/show playbooks (project > user > builtin)');
     console.log('  metrics            Telemetry roll-up (route outcomes, failure patterns, memory)');
-    console.log('  telemetry          Flight recorder (collect/status/digest/export-support/import/evaluate)');
+    console.log('  telemetry          Flight recorder (collect/status/usage/digest/export-support/import/evaluate)');
     console.log('  feedback           Record or list wrong-route feedback labels');
     console.log('  self-improve       Run the automatic learn/tune/collect pass now (hooks run it)');
     console.log('  vm                 Agent VM driver (list/show/status/shadow-run/evidence)');

package/src/core/observability/adapters/routeAdapter.js

@@ -29,9 +29,22 @@ import {
   createAdapterContext,
   emitRecord,
 } from './common.js';
+import { USAGE_CATEGORY_KEYS, USAGE_CATEGORIES_FIELD } from '../schema/constants.js';
 
 const RESOURCE_SOURCES = new Set(['PROVIDER', 'LOCAL_TOKENIZER', 'ESTIMATED', 'UNKNOWN']);
 
+// C98 FR-05 producer contract (SPEC §5): `ledger.model.usage.categories`
+// carries camelCase counts normalized by the producer (freshInput/cacheRead/
+// cacheWrite/output/reasoning); the adapter maps them to the schema category
+// keys without interpreting provider-native names.
+const USAGE_CATEGORY_INPUT_KEYS = Object.freeze({
+  freshInput: 'fresh_input_tokens',
+  cacheRead: 'cache_read_tokens',
+  cacheWrite: 'cache_write_tokens',
+  output: 'output_tokens',
+  reasoning: 'reasoning_tokens',
+});
+
 function normalizeRow(row) {
   if (!isPlainObject(row)) return null;
   const audit = isPlainObject(row.audit) ? row.audit : row;
@@ -79,6 +92,29 @@ function modelResource(model) {
   return { value, source };
 }
 
+// C98 FR-05: categories are provider-reported or unknown. A numeric value is
+// accepted only when usage.source === 'PROVIDER'; any other source (incl.
+// missing/UNKNOWN/ESTIMATED/LOCAL_TOKENIZER), absent key, or non-integer
+// value stays `{ value: null, source: 'UNKNOWN' }` — never 0, never derived
+// from the aggregate, never estimated. Returns null when no categories
+// object is supplied, so the payload field is omitted entirely.
+function usageCategories(model) {
+  const usage = isPlainObject(model.usage) ? model.usage : {};
+  if (!isPlainObject(usage.categories)) return null;
+  const categories = {};
+  for (const key of USAGE_CATEGORY_KEYS) {
+    categories[key] = { value: null, source: 'UNKNOWN' };
+  }
+  if (usage.source !== 'PROVIDER') return categories;
+  for (const [inputKey, categoryKey] of Object.entries(USAGE_CATEGORY_INPUT_KEYS)) {
+    const value = usage.categories[inputKey];
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
+      categories[categoryKey] = { value, source: 'PROVIDER' };
+    }
+  }
+  return categories;
+}
+
 export function adaptRouteOutcomes(rows, options = {}) {
   if (!Array.isArray(rows)) return [];
   const ctx = createAdapterContext({ writerId: 'adapter-route', ...options });
@@ -113,19 +149,22 @@ export function adaptRouteOutcomes(rows, options = {}) {
     const model = isPlainObject(ledger.model) ? ledger.model : null;
     if (model) {
       const resource = modelResource(model);
+      const categories = usageCategories(model);
       const failed = model.failed === true || asString(model.status) === 'failed';
+      const modelPayload = {
+        request_key: requestKey,
+        duration_ms:
+          typeof model.durationMs === 'number' && Number.isFinite(model.durationMs)
+            ? model.durationMs
+            : null,
+        resource,
+        telemetry_complete: resource.source !== 'UNKNOWN',
+      };
+      if (categories) modelPayload[USAGE_CATEGORIES_FIELD] = categories;
       const modelRecord = emitRecord(ctx, {
         semantic_name: failed ? 'model.failed' : 'model.completed',
         wall_time_utc: asIsoTime(audit.ts) ?? asIsoTime(ledger.updatedAt),
-        payload: {
-          request_key: requestKey,
-          duration_ms:
-            typeof model.durationMs === 'number' && Number.isFinite(model.durationMs)
-              ? model.durationMs
-              : null,
-          resource,
-          telemetry_complete: resource.source !== 'UNKNOWN',
-        },
+        payload: modelPayload,
       });
       if (modelRecord) records.push(modelRecord);
     }