tokentracker-cli 0.10.1 → 0.11.0

package/src/lib/claude-categorizer.js

@@ -15,6 +15,18 @@ const os = require("node:os");
 const path = require("node:path");
 const readline = require("node:readline");
 
+const {
+  categorizeTool,
+  inferExecCommandKind,
+  sanitizeCommandSignature,
+  getExecutableName,
+  emptyTotals,
+  addInto,
+  roundTotals,
+  buildExecStatsEntry,
+  allocateByLargestRemainder,
+} = require("./categorizer-utils");
+
 const CATEGORY_KEYS = [
   "system_prefix",
   "conversation_history",
@@ -27,14 +39,10 @@ const CATEGORY_KEYS = [
 
 const SUBAGENT_TOOL_NAMES = new Set(["Agent", "Task"]);
 
-function emptyTotals() {
+function emptyToolBreakdown() {
   return {
-    input_tokens: 0,
-    cached_input_tokens: 0,
-    cache_creation_input_tokens: 0,
-    output_tokens: 0,
-    reasoning_output_tokens: 0,
-    total_tokens: 0,
+    total_calls: 0,
+    tools: [],
   };
 }
 
@@ -44,113 +52,281 @@ function emptyCategoryMap() {
   return out;
 }
 
-function addInto(target, source) {
-  target.input_tokens += source.input_tokens || 0;
-  target.cached_input_tokens += source.cached_input_tokens || 0;
-  target.cache_creation_input_tokens += source.cache_creation_input_tokens || 0;
-  target.output_tokens += source.output_tokens || 0;
-  target.reasoning_output_tokens += source.reasoning_output_tokens || 0;
-  target.total_tokens += source.total_tokens || 0;
+function extractExecCommands(content) {
+  const commands = [];
+  for (const block of Array.isArray(content) ? content : []) {
+    if (!block || typeof block !== "object") continue;
+    if (block.type !== "tool_use") continue;
+    if (block.name !== "Bash" && block.name !== "exec_command") continue;
+    const input = block.input || {};
+    const command =
+      typeof input.command === "string" ? input.command
+      : typeof input.cmd === "string" ? input.cmd
+      : "";
+    if (command.trim()) commands.push(command.trim());
+  }
+  return commands;
 }
 
-function defaultClaudeProjectsDir() {
-  return path.join(os.homedir(), ".claude", "projects");
+function ensureExecRow(map, key) {
+  const safeKey = key || "unknown";
+  if (!map.has(safeKey)) map.set(safeKey, { name: safeKey, ...buildExecStatsEntry() });
+  return map.get(safeKey);
 }
 
-function listSessionFiles(rootDir) {
-  const out = [];
-  const stack = [rootDir];
-  while (stack.length > 0) {
-    const dir = stack.pop();
-    let entries;
-    try {
-      entries = fssync.readdirSync(dir, { withFileTypes: true });
-    } catch (_e) {
-      continue;
+function recordExecCommandUsage(execLedger, commands, totals) {
+  if (!execLedger || !Array.isArray(commands) || commands.length === 0) return;
+  const perCommandRows = new Map();
+  for (const command of commands) {
+    if (!perCommandRows.has(command)) perCommandRows.set(command, { calls: 0 });
+    perCommandRows.get(command).calls += 1;
+  }
+  const totalsByCommand = allocateTotalsAcrossRows(totals, perCommandRows);
+
+  for (const [command, row] of perCommandRows.entries()) {
+    const commandTotals = totalsByCommand.get(command) || {};
+    const kind = inferExecCommandKind(command);
+    const executable = getExecutableName(command);
+    const signature = sanitizeCommandSignature(command);
+    const exitKey = "unknown:unknown";
+
+    const targets = [
+      [execLedger.by_type, kind],
+      [execLedger.by_executable, executable],
+      [execLedger.by_command, signature],
+      [execLedger.by_exit, exitKey],
+    ];
+    for (const [map, key] of targets) {
+      const target = ensureExecRow(map, key);
+      target.calls += Math.max(1, Number(row.calls || 0));
+      addInto(target.totals, commandTotals);
     }
-    for (const entry of entries) {
-      const fp = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        stack.push(fp);
-      } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
-        out.push(fp);
-      }
+    execLedger.total_calls += Math.max(1, Number(row.calls || 0));
+  }
+}
+
+function allocateTotalsAcrossRows(totals, rows) {
+  const entries = Array.from(rows?.entries?.() || []);
+  if (entries.length === 0) return new Map();
+  const weights = {};
+  const order = entries.map(([name]) => name).sort();
+  for (const name of order) {
+    const row = rows.get(name) || {};
+    weights[name] = Math.max(0, Number(row.output_tokens || row.calls || 0));
+  }
+  if (order.every((name) => !weights[name])) {
+    for (const name of order) weights[name] = 1;
+  }
+  const out = new Map();
+  for (const name of order) out.set(name, emptyTotals());
+  for (const key of [
+    "input_tokens",
+    "cached_input_tokens",
+    "cache_creation_input_tokens",
+    "output_tokens",
+    "reasoning_output_tokens",
+    "total_tokens",
+  ]) {
+    const alloc = allocateByLargestRemainder(Math.max(0, Number(totals?.[key] || 0)), weights, order);
+    for (const name of order) {
+      out.get(name)[key] = alloc[name] || 0;
     }
   }
   return out;
 }
 
-// Distribute one assistant message's output tokens across categories by the
-// character-length ratio of each content block. Thinking goes to reasoning,
-// tool_use(Agent|Task) → subagents, tool_use(other) → tool_calls, text →
-// assistant_response. If reasoning_output_tokens is reported separately, use
-// that exact figure for reasoning instead of pro-rating.
-function splitOutputByContent(usage, content, breakdown) {
+function extractSkillNames(content) {
+  const names = [];
+  for (const block of Array.isArray(content) ? content : []) {
+    if (!block || typeof block !== "object") continue;
+    if (block.type !== "tool_use" || block.name !== "Skill") continue;
+    const skill = typeof block.input?.skill === "string" ? block.input.skill.trim() : "";
+    if (skill) names.push(skill);
+  }
+  return names;
+}
+
+function recordSkillUsage(skillLedger, skillNames, totals) {
+  if (!skillLedger || !Array.isArray(skillNames) || skillNames.length === 0) return;
+  const perMessageRows = new Map();
+  for (const name of skillNames) {
+    if (!perMessageRows.has(name)) perMessageRows.set(name, { calls: 0 });
+    perMessageRows.get(name).calls += 1;
+  }
+  const totalsByName = allocateTotalsAcrossRows(totals, perMessageRows);
+  for (const [name, row] of perMessageRows.entries()) {
+    if (!skillLedger.by_name.has(name)) {
+      skillLedger.by_name.set(name, { name, calls: 0, totals: emptyTotals() });
+    }
+    const target = skillLedger.by_name.get(name);
+    target.calls += row.calls || 0;
+    addInto(target.totals, totalsByName.get(name) || {});
+  }
+  skillLedger.total_calls += skillNames.length;
+}
+
+function computeOutputTokenBreakdown(usage, content) {
   const total = Math.max(0, Number(usage.output_tokens || 0));
   const reasoningExplicit = Math.max(0, Number(usage.reasoning_output_tokens || 0));
-  if (total === 0) return;
-
   const blocks = Array.isArray(content) ? content : [];
-  const buckets = { reasoning: 0, tool_calls: 0, subagents: 0, assistant_response: 0 };
-  let totalChars = 0;
 
+  if (total === 0) {
+    return {
+      bucket_tokens: { reasoning: 0, tool_calls: 0, subagents: 0, assistant_response: 0 },
+      tool_calls: { total_calls: 0, by_name: new Map() },
+      subagents: { total_calls: 0, by_name: new Map() },
+    };
+  }
+
+  const bucketChars = { reasoning: 0, tool_calls: 0, subagents: 0, assistant_response: 0 };
+  const toolCallChars = new Map();
+  const subagentChars = new Map();
+  const toolCallCounts = new Map();
+  const subagentCounts = new Map();
+
+  let totalChars = 0;
   for (const block of blocks) {
     if (!block || typeof block !== "object") continue;
     const type = block.type;
     let chars = 0;
+
     if (type === "thinking") {
       chars = String(block.thinking || block.text || "").length || 1;
-      buckets.reasoning += chars;
+      bucketChars.reasoning += chars;
     } else if (type === "text") {
       chars = String(block.text || "").length || 1;
-      buckets.assistant_response += chars;
+      bucketChars.assistant_response += chars;
     } else if (type === "tool_use") {
       const inputJson = block.input ? JSON.stringify(block.input) : "";
       chars = (block.name || "").length + inputJson.length + 1;
-      if (SUBAGENT_TOOL_NAMES.has(block.name)) buckets.subagents += chars;
-      else buckets.tool_calls += chars;
+      if (SUBAGENT_TOOL_NAMES.has(block.name)) {
+        bucketChars.subagents += chars;
+        subagentChars.set(block.name, (subagentChars.get(block.name) || 0) + chars);
+        subagentCounts.set(block.name, (subagentCounts.get(block.name) || 0) + 1);
+      } else {
+        bucketChars.tool_calls += chars;
+        toolCallChars.set(block.name, (toolCallChars.get(block.name) || 0) + chars);
+        toolCallCounts.set(block.name, (toolCallCounts.get(block.name) || 0) + 1);
+      }
     } else {
       continue;
     }
+
     totalChars += chars;
   }
 
   if (totalChars === 0) {
-    breakdown.assistant_response.output_tokens += total;
-    breakdown.assistant_response.total_tokens += total;
-    return;
+    return {
+      bucket_tokens: { reasoning: 0, tool_calls: 0, subagents: 0, assistant_response: total },
+      tool_calls: { total_calls: 0, by_name: new Map() },
+      subagents: { total_calls: 0, by_name: new Map() },
+    };
   }
 
-  // If the API reported reasoning tokens explicitly, peel them off first
-  // and pro-rate the rest of the output across the remaining buckets.
-  let nonReasoningOutput = total;
-  if (reasoningExplicit > 0) {
-    const reasoningShare = Math.min(reasoningExplicit, total);
-    breakdown.reasoning.output_tokens += reasoningShare;
-    breakdown.reasoning.reasoning_output_tokens += reasoningShare;
-    breakdown.reasoning.total_tokens += reasoningShare;
-    nonReasoningOutput = total - reasoningShare;
-    // Drop the thinking-char contribution; it was just paid for.
-    totalChars -= buckets.reasoning;
-    buckets.reasoning = 0;
-  }
+  const explicitReasoning = reasoningExplicit > 0 ? Math.min(reasoningExplicit, total) : 0;
+  const nonReasoningOutput = total - explicitReasoning;
 
-  if (nonReasoningOutput <= 0 || totalChars <= 0) return;
+  const allocChars = { ...bucketChars };
+  let allocTotalChars = totalChars;
+  if (explicitReasoning > 0) {
+    allocTotalChars -= allocChars.reasoning;
+    allocChars.reasoning = 0;
+  }
 
-  // Largest-remainder rounding so the four sub-buckets sum exactly to
-  // nonReasoningOutput (no off-by-one drift across thousands of messages).
   const order = ["reasoning", "tool_calls", "subagents", "assistant_response"];
-  const exact = order.map((k) => (buckets[k] / totalChars) * nonReasoningOutput);
-  const floored = exact.map((x) => Math.floor(x));
-  const remainder = nonReasoningOutput - floored.reduce((a, b) => a + b, 0);
-  const remainders = exact
-    .map((x, i) => ({ i, frac: x - Math.floor(x) }))
-    .sort((a, b) => b.frac - a.frac);
-  for (let k = 0; k < remainder; k++) floored[remainders[k % order.length].i] += 1;
-
-  for (let i = 0; i < order.length; i++) {
-    const key = order[i];
-    const tok = floored[i];
+  const prorated = allocateByLargestRemainder(Math.max(0, nonReasoningOutput), allocChars, order);
+
+  const bucketTokens = {
+    reasoning: explicitReasoning + (prorated.reasoning || 0),
+    tool_calls: prorated.tool_calls || 0,
+    subagents: prorated.subagents || 0,
+    assistant_response: prorated.assistant_response || 0,
+  };
+
+  if (allocTotalChars <= 0 && nonReasoningOutput > 0) {
+    bucketTokens.reasoning = explicitReasoning;
+    bucketTokens.tool_calls = 0;
+    bucketTokens.subagents = 0;
+    bucketTokens.assistant_response = nonReasoningOutput;
+  }
+
+  const toolTokensByName = new Map();
+  if (bucketTokens.tool_calls > 0 && toolCallChars.size > 0) {
+    const keys = [...toolCallChars.keys()].sort();
+    const weights = {};
+    for (const k of keys) weights[k] = toolCallChars.get(k) || 0;
+    const alloc = allocateByLargestRemainder(bucketTokens.tool_calls, weights, keys);
+    for (const k of keys) toolTokensByName.set(k, alloc[k] || 0);
+  }
+
+  const subagentTokensByName = new Map();
+  if (bucketTokens.subagents > 0 && subagentChars.size > 0) {
+    const keys = [...subagentChars.keys()].sort();
+    const weights = {};
+    for (const k of keys) weights[k] = subagentChars.get(k) || 0;
+    const alloc = allocateByLargestRemainder(bucketTokens.subagents, weights, keys);
+    for (const k of keys) subagentTokensByName.set(k, alloc[k] || 0);
+  }
+
+  return {
+    bucket_tokens: bucketTokens,
+    tool_calls: {
+      total_calls: [...toolCallCounts.values()].reduce((a, b) => a + b, 0),
+      by_name: new Map(
+        [...toolCallCounts.entries()].map(([name, calls]) => [
+          name,
+          { name, calls, output_tokens: toolTokensByName.get(name) || 0 },
+        ]),
+      ),
+    },
+    subagents: {
+      total_calls: [...subagentCounts.values()].reduce((a, b) => a + b, 0),
+      by_name: new Map(
+        [...subagentCounts.entries()].map(([name, calls]) => [
+          name,
+          { name, calls, output_tokens: subagentTokensByName.get(name) || 0 },
+        ]),
+      ),
+    },
+  };
+}
+
+function defaultClaudeProjectsDir() {
+  return path.join(os.homedir(), ".claude", "projects");
+}
+
+function listSessionFiles(rootDir) {
+  const out = [];
+  const stack = [rootDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fssync.readdirSync(dir, { withFileTypes: true });
+    } catch (_e) {
+      continue;
+    }
+    for (const entry of entries) {
+      const fp = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fp);
+      } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+        out.push(fp);
+      }
+    }
+  }
+  return out;
+}
+
+// Distribute one assistant message's output tokens across categories by the
+// character-length ratio of each content block. Thinking goes to reasoning,
+// tool_use(Agent|Task) → subagents, tool_use(other) → tool_calls, text →
+// assistant_response. If reasoning_output_tokens is reported separately, use
+// that exact figure for reasoning instead of pro-rating.
+function splitOutputByContent(usage, content, breakdown) {
+  const out = computeOutputTokenBreakdown(usage, content);
+  for (const key of ["reasoning", "tool_calls", "subagents", "assistant_response"]) {
+    const tok = out.bucket_tokens[key] || 0;
     if (tok === 0) continue;
     breakdown[key].output_tokens += tok;
     breakdown[key].total_tokens += tok;
@@ -161,7 +337,7 @@ function splitOutputByContent(usage, content, breakdown) {
 // Per-session state lets us pick out the *first* meaningful cache_creation
 // chunk and call that the system_prefix. Subsequent cache_creations are
 // incremental — we attribute them to conversation_history.
-function classifyOneMessage(obj, sessionState, breakdown) {
+function classifyOneMessage(obj, sessionState, breakdown, toolLedger = null, skillLedger = null, execLedger = null) {
   const usage = obj?.message?.usage;
   if (!usage || typeof usage !== "object") return;
 
@@ -195,18 +371,90 @@ function classifyOneMessage(obj, sessionState, breakdown) {
     }
   }
 
+  recordSkillUsage(
+    skillLedger,
+    extractSkillNames(obj?.message?.content),
+    {
+      input_tokens: inputNonCached,
+      cached_input_tokens: cacheRead,
+      cache_creation_input_tokens: cacheCreate,
+      output_tokens: output,
+      reasoning_output_tokens: 0,
+      total_tokens: inputNonCached + cacheRead + cacheCreate + output,
+    },
+  );
+
   // Split output across reasoning / tool_calls / subagents / assistant_response.
   if (output > 0) {
-    splitOutputByContent(
+    const out = computeOutputTokenBreakdown(
       { output_tokens: output, reasoning_output_tokens: usage.reasoning_output_tokens },
       obj?.message?.content,
-      breakdown,
     );
+    for (const key of ["reasoning", "tool_calls", "subagents", "assistant_response"]) {
+      const tok = out.bucket_tokens[key] || 0;
+      if (tok === 0) continue;
+      breakdown[key].output_tokens += tok;
+      breakdown[key].total_tokens += tok;
+      if (key === "reasoning") breakdown[key].reasoning_output_tokens += tok;
+    }
+
+    recordExecCommandUsage(
+      execLedger,
+      extractExecCommands(obj?.message?.content),
+      {
+        input_tokens: inputNonCached,
+        cached_input_tokens: cacheRead,
+        cache_creation_input_tokens: cacheCreate,
+        output_tokens: out.bucket_tokens.tool_calls || 0,
+        reasoning_output_tokens: 0,
+        total_tokens: inputNonCached + cacheRead + cacheCreate + (out.bucket_tokens.tool_calls || 0),
+      },
+    );
+
+    if (toolLedger) {
+      const ledgerTotals = {
+        input_tokens: inputNonCached,
+        cached_input_tokens: cacheRead,
+        cache_creation_input_tokens: cacheCreate,
+        output_tokens: out.bucket_tokens.tool_calls || 0,
+        reasoning_output_tokens: 0,
+        total_tokens: inputNonCached + cacheRead + cacheCreate + (out.bucket_tokens.tool_calls || 0),
+      };
+      const toolTotalsByName = allocateTotalsAcrossRows(ledgerTotals, out.tool_calls.by_name);
+      for (const [name, row] of out.tool_calls.by_name.entries()) {
+        if (!toolLedger.tool_calls.by_name.has(name)) {
+          toolLedger.tool_calls.by_name.set(name, { name, calls: 0, totals: emptyTotals() });
+        }
+        const target = toolLedger.tool_calls.by_name.get(name);
+        target.calls += row.calls || 0;
+        addInto(target.totals, toolTotalsByName.get(name) || {});
+      }
+      toolLedger.tool_calls.total_calls += out.tool_calls.total_calls || 0;
+
+      const subagentTotals = {
+        input_tokens: inputNonCached,
+        cached_input_tokens: cacheRead,
+        cache_creation_input_tokens: cacheCreate,
+        output_tokens: out.bucket_tokens.subagents || 0,
+        reasoning_output_tokens: 0,
+        total_tokens: inputNonCached + cacheRead + cacheCreate + (out.bucket_tokens.subagents || 0),
+      };
+      const subagentTotalsByName = allocateTotalsAcrossRows(subagentTotals, out.subagents.by_name);
+      for (const [name, row] of out.subagents.by_name.entries()) {
+        if (!toolLedger.subagents.by_name.has(name)) {
+          toolLedger.subagents.by_name.set(name, { name, calls: 0, totals: emptyTotals() });
+        }
+        const target = toolLedger.subagents.by_name.get(name);
+        target.calls += row.calls || 0;
+        addInto(target.totals, subagentTotalsByName.get(name) || {});
+      }
+      toolLedger.subagents.total_calls += out.subagents.total_calls || 0;
+    }
   }
 }
 
 // Read one session jsonl streaming, in timestamp range, dedup by msgId+reqId.
-async function categorizeSessionFile(filePath, { fromIso, toIso, seenHashes }, breakdown) {
+async function categorizeSessionFile(filePath, { fromIso, toIso, seenHashes }, breakdown, toolLedger = null, skillLedger = null, execLedger = null) {
   let stream;
   try {
     stream = fssync.createReadStream(filePath, { encoding: "utf8" });
@@ -238,7 +486,7 @@ async function categorizeSessionFile(filePath, { fromIso, toIso, seenHashes }, b
       seenHashes.add(hash);
     }
 
-    classifyOneMessage(obj, sessionState, breakdown);
+    classifyOneMessage(obj, sessionState, breakdown, toolLedger, skillLedger, execLedger);
     counted += 1;
   }
   rl.close();
@@ -271,6 +519,7 @@ function dayKeyToIsoBounds(from, to) {
 // case the watcher misses something.
 const CACHE = new Map();
 const CACHE_TTL_MS = 60_000;
+const CACHE_SCHEMA_VERSION = "skills-exec-v2";
 
 function maxMtimeMs(files) {
   let max = 0;
@@ -303,7 +552,7 @@ async function computeClaudeCategoryBreakdown({ from = null, to = null, rootDir
     };
   }
 
-  const cacheKey = `${root}|${from || ""}|${to || ""}|${files.length}|${maxMtimeMs(files)}`;
+  const cacheKey = `${CACHE_SCHEMA_VERSION}|${root}|${from || ""}|${to || ""}|${files.length}|${maxMtimeMs(files)}`;
   const cached = CACHE.get(cacheKey);
   if (cached && Date.now() - cached.at < CACHE_TTL_MS) {
     return cached.value;
@@ -314,12 +563,27 @@ async function computeClaudeCategoryBreakdown({ from = null, to = null, rootDir
   const seenHashes = new Set();
   let messageCount = 0;
   let sessionCount = 0;
+  const toolLedger = {
+    tool_calls: { total_calls: 0, by_name: new Map() },
+    subagents: { total_calls: 0, by_name: new Map() },
+  };
+  const skillLedger = { total_calls: 0, by_name: new Map() };
+  const execLedger = {
+    total_calls: 0,
+    by_type: new Map(),
+    by_executable: new Map(),
+    by_command: new Map(),
+    by_exit: new Map(),
+  };
 
   for (const fp of files) {
     const counted = await categorizeSessionFile(
       fp,
       { fromIso, toIso, seenHashes },
       breakdown,
+      toolLedger,
+      skillLedger,
+      execLedger,
     );
     if (counted > 0) sessionCount += 1;
     messageCount += counted;
@@ -341,17 +605,210 @@ async function computeClaudeCategoryBreakdown({ from = null, to = null, rootDir
     }),
     session_count: sessionCount,
     message_count: messageCount,
+    message_breakdown: buildMessageBreakdown(breakdown),
+    tool_calls_breakdown: buildToolCallsBreakdown(toolLedger),
+    skills_breakdown: buildSkillsBreakdown(skillLedger),
+    exec_command_breakdown: buildExecCommandBreakdown(execLedger),
+    configured_resources: getConfiguredResources({ projectDir }),
   };
 
   CACHE.set(cacheKey, { at: Date.now(), value: result });
   // Bound cache size — categorizer is cheap to recompute, no point hoarding.
-  if (CACHE.size > 32) {
+  while (CACHE.size > 32) {
     const oldest = [...CACHE.entries()].sort((a, b) => a[1].at - b[1].at)[0];
     if (oldest) CACHE.delete(oldest[0]);
   }
   return result;
 }
 
+function buildToolCallsBreakdown(toolLedger) {
+  if (!toolLedger || !toolLedger.tool_calls || !toolLedger.subagents) {
+    return {
+      tool_calls: emptyToolBreakdown(),
+      subagents: emptyToolBreakdown(),
+    };
+  }
+
+  function mapToSortedRows(map) {
+    const rows = Array.from(map.values()).map((row) => ({
+      name: row.name,
+      calls: row.calls,
+      totals: row.totals || {
+        ...emptyTotals(),
+        output_tokens: row.output_tokens || 0,
+        total_tokens: row.total_tokens || row.output_tokens || 0,
+      },
+    }));
+    rows.sort((a, b) => (b.totals?.total_tokens || 0) - (a.totals?.total_tokens || 0));
+    return rows;
+  }
+
+  const toolCallsRows = mapToSortedRows(toolLedger.tool_calls.by_name || new Map());
+  const subagentRows = mapToSortedRows(toolLedger.subagents.by_name || new Map());
+
+  function groupIntoCategories(rows) {
+    const byCategory = new Map(); // name -> {name,calls,totals,tools:[]}
+    for (const row of rows) {
+      const toolName = String(row?.name || "");
+      if (!toolName) continue;
+      const cat = categorizeTool(toolName);
+      if (!byCategory.has(cat)) {
+        byCategory.set(cat, {
+          name: cat,
+          calls: 0,
+          totals: emptyTotals(),
+          tools: [],
+        });
+      }
+      const bucket = byCategory.get(cat);
+      bucket.calls += Number(row.calls || 0);
+      addInto(bucket.totals, row.totals || {});
+      bucket.tools.push({
+        name: toolName,
+        calls: Number(row.calls || 0),
+        totals: row.totals || emptyTotals(),
+      });
+    }
+    const categories = Array.from(byCategory.values())
+      .map((c) => ({
+        name: c.name,
+        calls: Math.round(c.calls || 0),
+        totals: {
+          input_tokens: Math.round(c.totals.input_tokens || 0),
+          cached_input_tokens: Math.round(c.totals.cached_input_tokens || 0),
+          cache_creation_input_tokens: Math.round(c.totals.cache_creation_input_tokens || 0),
+          output_tokens: Math.round(c.totals.output_tokens || 0),
+          reasoning_output_tokens: Math.round(c.totals.reasoning_output_tokens || 0),
+          total_tokens: Math.round(c.totals.total_tokens || 0),
+        },
+        tools: c.tools
+          .sort((a, b) => (b.totals?.total_tokens || 0) - (a.totals?.total_tokens || 0))
+          .map((t) => ({
+            name: t.name,
+            calls: Math.round(t.calls || 0),
+            totals: {
+              input_tokens: Math.round(t.totals.input_tokens || 0),
+              cached_input_tokens: Math.round(t.totals.cached_input_tokens || 0),
+              cache_creation_input_tokens: Math.round(t.totals.cache_creation_input_tokens || 0),
+              output_tokens: Math.round(t.totals.output_tokens || 0),
+              reasoning_output_tokens: Math.round(t.totals.reasoning_output_tokens || 0),
+              total_tokens: Math.round(t.totals.total_tokens || 0),
+            },
+          })),
+      }))
+      .sort((a, b) => (b.totals?.total_tokens || 0) - (a.totals?.total_tokens || 0));
+    return categories;
+  }
+
+  return {
+    tool_calls: {
+      total_calls: toolLedger.tool_calls.total_calls || 0,
+      tools: toolCallsRows,
+      categories: groupIntoCategories(toolCallsRows),
+    },
+    subagents: {
+      total_calls: toolLedger.subagents.total_calls || 0,
+      tools: subagentRows,
+      categories: groupIntoCategories(subagentRows),
+    },
+    privacy: {
+      includes_inputs: false,
+      note: "Aggregated tool names only; tool inputs are never recorded.",
+    },
+  };
+}
+
+function buildSkillsBreakdown(skillLedger) {
+  const rows = Array.from(skillLedger?.by_name?.values?.() || [])
+    .map((row) => ({
+      name: row.name,
+      calls: Math.round(row.calls || 0),
+      totals: roundTotals(row.totals || emptyTotals()),
+    }))
+    .sort((a, b) => (b.totals?.total_tokens || 0) - (a.totals?.total_tokens || 0));
+
+  return {
+    total_calls: Math.round(skillLedger?.total_calls || 0),
+    skills: rows,
+    privacy: {
+      includes_inputs: false,
+      note: "Aggregated skill names only; skill inputs are never returned.",
+    },
+  };
+}
+
+function serializeExecRows(map) {
+  return Array.from(map?.values?.() || [])
+    .map((row) => ({
+      name: row.name,
+      calls: Math.round(row.calls || 0),
+      failures: Math.round(row.failures || 0),
+      duration_ms: Math.round(row.duration_ms || 0),
+      max_duration_ms: Math.round(row.max_duration_ms || 0),
+      output_chars: Math.round(row.output_chars || 0),
+      output_lines: Math.round(row.output_lines || 0),
+      totals: roundTotals(row.totals || emptyTotals()),
+    }))
+    .sort((a, b) => (b.totals?.total_tokens || 0) - (a.totals?.total_tokens || 0));
+}
+
+function buildExecCommandBreakdown(execLedger) {
+  return {
+    total_calls: Math.round(execLedger?.total_calls || 0),
+    by_type: serializeExecRows(execLedger?.by_type),
+    by_executable: serializeExecRows(execLedger?.by_executable),
+    by_command: serializeExecRows(execLedger?.by_command),
+    by_duration: [],
+    by_output: [],
+    by_exit: serializeExecRows(execLedger?.by_exit),
+    privacy: {
+      includes_commands: false,
+      note: "Claude Bash commands are grouped into sanitized signatures; raw commands are not returned.",
+    },
+  };
+}
+
+function buildMessageBreakdown(breakdown) {
+  const rows = [
+    {
+      key: "user_input",
+      name: "User input",
+      totals: breakdown.user_input || emptyTotals(),
+    },
+    {
+      key: "conversation_history",
+      name: "Conversation history",
+      totals: breakdown.conversation_history || emptyTotals(),
+    },
+    {
+      key: "assistant_response",
+      name: "Assistant response",
+      totals: breakdown.assistant_response || emptyTotals(),
+    },
+  ];
+
+  return {
+    categories: rows
+      .map((row) => ({
+        key: row.key,
+        name: row.name,
+        totals: {
+          input_tokens: Math.round(row.totals.input_tokens || 0),
+          cached_input_tokens: Math.round(row.totals.cached_input_tokens || 0),
+          cache_creation_input_tokens: Math.round(row.totals.cache_creation_input_tokens || 0),
+          output_tokens: Math.round(row.totals.output_tokens || 0),
+          reasoning_output_tokens: Math.round(row.totals.reasoning_output_tokens || 0),
+          total_tokens: Math.round(row.totals.total_tokens || 0),
+        },
+      }))
+      .sort((a, b) => (b.totals?.total_tokens || 0) - (a.totals?.total_tokens || 0)),
+    privacy: {
+      includes_content: false,
+      note: "Aggregated message token categories only; prompt and assistant text are never returned.",
+    },
+  };
+}
+
 // Lightweight on-disk count of static resources Claude Code's /context UI
 // also surfaces (Skills, MCP servers, Memory files, Custom agents). These are
 // counts of what's *installed*, not historical token usage — the same way