getprismo 0.1.22 → 0.1.24

package/lib/prismo-dev/usage-cost.js

@@ -0,0 +1,336 @@
+module.exports = function createUsageCost(deps) {
+  const {
+    CLAUDE_PRICING,
+    DEFAULT_CLAUDE_PRICING_KEY,
+    NPX_COMMAND,
+    formatMoney,
+    formatTokenCount,
+  } = deps;
+
+  function percentOf(part, total) {
+    if (!total) return 0;
+    return Math.round((Number(part || 0) / total) * 100);
+  }
+
+  function inferClaudePricingKey(model) {
+    const normalized = String(model || "").toLowerCase();
+    if (normalized.includes("opus") && normalized.includes("4-1")) return "opus-4.1";
+    if (normalized.includes("opus") && normalized.includes("4.1")) return "opus-4.1";
+    if (normalized.includes("opus") && normalized.includes("4")) return "opus-4";
+    if (normalized.includes("sonnet") && normalized.includes("4")) return "sonnet-4";
+    if (normalized.includes("sonnet") && (normalized.includes("3-7") || normalized.includes("3.7"))) return "sonnet-3.7";
+    if (normalized.includes("sonnet") && (normalized.includes("3-5") || normalized.includes("3.5"))) return "sonnet-3.5";
+    if (normalized.includes("haiku") && (normalized.includes("3-5") || normalized.includes("3.5"))) return "haiku-3.5";
+    if (normalized.includes("haiku") && normalized.includes("3")) return "haiku-3";
+    if (normalized.includes("opus") && normalized.includes("3")) return "opus-3";
+    return DEFAULT_CLAUDE_PRICING_KEY;
+  }
+
+  function calculateClaudeCost(tokens, model) {
+    const pricingKey = inferClaudePricingKey(model);
+    const pricing = CLAUDE_PRICING[pricingKey] || CLAUDE_PRICING[DEFAULT_CLAUDE_PRICING_KEY];
+    const inputTokens = Number(tokens.inputTokens || 0);
+    const outputTokens = Number(tokens.outputTokens || 0);
+    const cacheWriteTokens = Number(tokens.cacheCreationTokens || tokens.cacheWriteTokens || 0);
+    const cacheReadTokens = Number(tokens.cacheReadTokens || 0);
+    const input = (inputTokens / 1000000) * pricing.input;
+    const output = (outputTokens / 1000000) * pricing.output;
+    const cacheWrite = (cacheWriteTokens / 1000000) * pricing.cacheWrite;
+    const cacheRead = (cacheReadTokens / 1000000) * pricing.cacheRead;
+    const total = input + output + cacheWrite + cacheRead;
+    const noCache = ((inputTokens + cacheWriteTokens + cacheReadTokens) / 1000000) * pricing.input + output;
+    return {
+      model: pricing.name,
+      pricingKey,
+      pricing,
+      input,
+      output,
+      cacheWrite,
+      cacheRead,
+      total,
+      noCache,
+      cacheSavings: Math.max(noCache - total, 0),
+    };
+  }
+
+  function buildClaudeSessionDiagnosis(session) {
+    const totalCost = session.cost ? session.cost.total : 0;
+    const drivers = [];
+    if (session.cost) {
+      const costParts = [
+        ["output", session.cost.output, "Assistant output is the largest cost driver."],
+        ["cache-read", session.cost.cacheRead, "Repeated cached context reads are driving spend."],
+        ["cache-write", session.cost.cacheWrite, "Large context cache writes are adding upfront cost."],
+        ["input", session.cost.input, "Fresh input/context tokens are driving spend."],
+      ].sort((a, b) => b[1] - a[1]);
+      for (const [name, cost, message] of costParts) {
+        if (cost > 0) {
+          drivers.push({ type: name, cost, share: percentOf(cost, totalCost), message });
+        }
+      }
+    }
+    if (session.estimatedToolTokens >= 75000) {
+      drivers.push({
+        type: "tool-output",
+        tokens: session.estimatedToolTokens,
+        share: null,
+        message: "Tool output looks heavy; test logs, shell output, or file dumps may be inflating context.",
+      });
+    }
+    if (session.turns >= 30) {
+      drivers.push({
+        type: "long-session",
+        turns: session.turns,
+        share: null,
+        message: "Long session detected; unrelated follow-up work is likely riding old context.",
+      });
+    }
+    if (session.contextRisk === "High") {
+      drivers.push({
+        type: "context-risk",
+        tokens: session.displayTokens,
+        share: null,
+        message: "Session context is high enough that splitting work or using context packs should matter.",
+      });
+    }
+
+    const recommendations = [];
+    if (drivers.some((driver) => driver.type === "tool-output")) {
+      recommendations.push("Summarize long command output before pasting or re-reading it.");
+    }
+    if (drivers.some((driver) => driver.type === "cache-read" || driver.type === "cache-write" || driver.type === "context-risk")) {
+      recommendations.push(`Run ${NPX_COMMAND} optimize, then start from .prismo/architecture-summary.md.`);
+    }
+    if (drivers.some((driver) => driver.type === "long-session")) {
+      recommendations.push("Start a fresh Claude Code session for the next unrelated task.");
+    }
+    if (drivers.some((driver) => driver.type === "output")) {
+      recommendations.push("Ask for concise diffs, file paths, and verification results instead of full prose dumps.");
+    }
+    if (!recommendations.length) {
+      recommendations.push(`${NPX_COMMAND} scan --usage can tie this spend back to repo-level token waste.`);
+    }
+
+    const avoidableRate =
+      session.contextRisk === "High" ? 0.28 :
+        session.contextRisk === "Medium" ? 0.16 :
+          session.turns >= 20 || session.estimatedToolTokens >= 30000 ? 0.1 : 0.04;
+    return {
+      wasteScore: session.contextRisk === "High" ? 85 : session.contextRisk === "Medium" ? 55 : session.turns >= 20 ? 40 : 20,
+      estimatedAvoidableCost: totalCost * avoidableRate,
+      estimatedAvoidableRate: avoidableRate,
+      drivers: drivers.slice(0, 5),
+      recommendations: Array.from(new Set(recommendations)).slice(0, 4),
+    };
+  }
+
+  function buildSessionTimeline(session) {
+    const events = [];
+    const timeline = session.exactTokenTimeline || [];
+    for (let i = 1; i < timeline.length; i += 1) {
+      const previous = timeline[i - 1];
+      const current = timeline[i];
+      const delta = Math.max(0, (current.total || 0) - (previous.total || 0));
+      if (delta >= 60000) {
+        events.push({
+          timestamp: current.timestamp || session.updatedAt,
+          type: delta >= 250000 ? "context-spike" : "context-growth",
+          label: delta >= 250000 ? "Context spike likely" : "Context growth",
+          tokens: delta,
+          detail: `+${formatTokenCount(delta)} tokens`,
+        });
+      }
+    }
+    for (const item of (session.generatedArtifacts || []).slice(0, 5)) {
+      events.push({
+        timestamp: session.updatedAt,
+        type: "artifact-leak",
+        label: "Generated artifact likely entered context",
+        tokens: null,
+        detail: `${item.value} (${item.count}x)`,
+      });
+    }
+    for (const item of (session.repeatedCommands || []).slice(0, 5)) {
+      events.push({
+        timestamp: session.updatedAt,
+        type: "repeated-command",
+        label: session.loopSuspicion ? "Repeated command loop possible" : "Repeated command",
+        tokens: null,
+        detail: `${item.value} (${item.count}x)`,
+      });
+    }
+    for (const item of (session.repeatedPathMentions || []).slice(0, 3)) {
+      events.push({
+        timestamp: session.updatedAt,
+        type: "repeated-file",
+        label: "Repeated file/path context",
+        tokens: null,
+        detail: `${item.value} (${item.count}x)`,
+      });
+    }
+    if (session.estimatedToolTokens >= 75000) {
+      events.push({
+        timestamp: session.updatedAt,
+        type: "tool-output",
+        label: "Large tool output",
+        tokens: session.estimatedToolTokens,
+        detail: `${formatTokenCount(session.estimatedToolTokens)} estimated tool/output tokens`,
+      });
+    }
+    return events
+      .sort((a, b) => new Date(a.timestamp || 0) - new Date(b.timestamp || 0))
+      .slice(-20);
+  }
+
+  function buildClaudeCostInsights(sessions, totals) {
+    const highestCostSessions = sessions
+      .slice()
+      .sort((a, b) => (b.cost?.total || 0) - (a.cost?.total || 0))
+      .slice(0, 3)
+      .map((session) => ({
+        sessionId: session.sessionId,
+        updatedAt: session.updatedAt,
+        model: session.cost?.model || session.model,
+        cost: session.cost?.total || 0,
+        risk: session.contextRisk,
+        topDriver: session.prismo?.drivers?.[0] || null,
+      }));
+    const costDrivers = [
+      { type: "output", cost: totals.outputCost, share: percentOf(totals.outputCost, totals.totalCost) },
+      { type: "cache-read", cost: totals.cacheReadCost, share: percentOf(totals.cacheReadCost, totals.totalCost) },
+      { type: "cache-write", cost: totals.cacheWriteCost, share: percentOf(totals.cacheWriteCost, totals.totalCost) },
+      { type: "input", cost: totals.inputCost, share: percentOf(totals.inputCost, totals.totalCost) },
+    ].filter((driver) => driver.cost > 0).sort((a, b) => b.cost - a.cost);
+    const estimatedAvoidableCost = sessions.reduce((sum, session) => sum + (session.prismo?.estimatedAvoidableCost || 0), 0);
+    const recommendations = [];
+    if (costDrivers[0]?.type === "cache-read" || costDrivers[0]?.type === "cache-write") {
+      recommendations.push("Repeated context is the main spend driver; generate context packs and avoid broad repo reads.");
+    }
+    if (costDrivers[0]?.type === "output") {
+      recommendations.push("Output cost is leading; ask the agent for concise diffs and summaries by default.");
+    }
+    if (sessions.some((session) => session.estimatedToolTokens >= 75000)) {
+      recommendations.push("Tool output is bloating at least one session; keep shell output narrow and summarize logs.");
+    }
+    if (sessions.some((session) => session.turns >= 30)) {
+      recommendations.push("At least one session is long; split unrelated tasks into fresh sessions.");
+    }
+    recommendations.push(`${NPX_COMMAND} scan --usage`);
+    recommendations.push(`${NPX_COMMAND} optimize`);
+    return {
+      estimatedAvoidableCost,
+      estimatedAvoidableRate: totals.totalCost ? estimatedAvoidableCost / totals.totalCost : 0,
+      costDrivers,
+      highestCostSessions,
+      recommendations: Array.from(new Set(recommendations)).slice(0, 5),
+    };
+  }
+
+  function renderClaudeCostTerminal(summary) {
+    const lines = [];
+    const latest = summary.sessions[0] || null;
+    lines.push("");
+    lines.push("Prismo Claude Code Cost");
+    lines.push("");
+    if (!summary.sessions.length) {
+      lines.push(summary.scope === "all-claude-projects" ? "No Claude Code sessions found." : "No Claude Code sessions found for this repo.");
+      lines.push("");
+      lines.push("Tip: run Claude Code inside this project, then try `npx getprismo cc` again.");
+      return lines.join("\n");
+    }
+
+    if (summary.command === "list") {
+      lines.push(`Recent sessions: ${summary.sessions.length}`);
+      lines.push("");
+      summary.sessions.forEach((session, index) => {
+        lines.push(`${index + 1}. ${session.model || session.cost.model}  ${session.updatedAt || "unknown date"}`);
+        lines.push(`   ${formatTokenCount(session.exactTotalTokens || session.contextTokens)} tokens -> ${formatMoney(session.cost.total)}  (${session.sessionId})`);
+        if (session.prismo?.drivers?.[0]) lines.push(`   driver: ${session.prismo.drivers[0].message}`);
+      });
+      lines.push("");
+      lines.push(`Estimated avoidable spend: ${formatMoney(summary.insights.estimatedAvoidableCost)}`);
+      lines.push(`Next: ${summary.insights.recommendations.slice(0, 2).join(" -> ")}`);
+      return lines.join("\n");
+    }
+
+    if (summary.command === "all") {
+      lines.push(`Sessions: ${summary.totals.sessions}`);
+      lines.push("");
+      lines.push(`Input:        ${formatTokenCount(summary.totals.inputTokens).padStart(8)} tokens  ->  ${formatMoney(summary.totals.inputCost)}`);
+      lines.push(`Output:       ${formatTokenCount(summary.totals.outputTokens).padStart(8)} tokens  ->  ${formatMoney(summary.totals.outputCost)}`);
+      lines.push(`Cache write:  ${formatTokenCount(summary.totals.cacheCreationTokens).padStart(8)} tokens  ->  ${formatMoney(summary.totals.cacheWriteCost)}`);
+      lines.push(`Cache read:   ${formatTokenCount(summary.totals.cacheReadTokens).padStart(8)} tokens  ->  ${formatMoney(summary.totals.cacheReadCost)}`);
+      lines.push("--------------------------------------------------");
+      lines.push(`Total:        ${formatTokenCount(summary.totals.totalTokens).padStart(8)} tokens  ->  ${formatMoney(summary.totals.totalCost)}`);
+      if (summary.totals.cacheSavings > 0) lines.push("");
+      if (summary.totals.cacheSavings > 0) lines.push(`Cache saved you ${formatMoney(summary.totals.cacheSavings)} (vs no caching)`);
+      lines.push("");
+      lines.push("Prismo Diagnosis");
+      lines.push(`Estimated avoidable spend: ${formatMoney(summary.insights.estimatedAvoidableCost)} (${Math.round(summary.insights.estimatedAvoidableRate * 100)}%)`);
+      if (summary.insights.costDrivers.length) {
+        lines.push(`Main cost driver: ${summary.insights.costDrivers[0].type} (${summary.insights.costDrivers[0].share}%)`);
+      }
+      summary.insights.recommendations.slice(0, 3).forEach((recommendation) => lines.push(`- ${recommendation}`));
+      return lines.join("\n");
+    }
+
+    if (summary.command === "timeline") {
+      lines.push(`Session: ${latest.sessionId}`);
+      if (latest.model || latest.cost?.model) lines.push(`Model: ${latest.model || latest.cost.model}`);
+      lines.push(`Updated: ${latest.updatedAt || "unknown date"}`);
+      lines.push("");
+      lines.push("Timeline");
+      if (!latest.timeline || !latest.timeline.length) {
+        lines.push("- No major context spikes, repeated commands, or artifact leaks detected in this session.");
+      } else {
+        latest.timeline.forEach((event) => {
+          const when = event.timestamp ? new Date(event.timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }) : "unknown";
+          lines.push(`${when}  ${event.label}  ${event.detail}`);
+        });
+      }
+      lines.push("");
+      lines.push("Suggested Action");
+      lines.push(latest.prismo?.recommendations?.[0] || `${NPX_COMMAND} doctor`);
+      return lines.join("\n");
+    }
+
+    const sessions = summary.command === "last" ? summary.sessions : [latest];
+    sessions.forEach((session, index) => {
+      if (index > 0) lines.push("");
+      lines.push(`${session.cost.model}  ${session.updatedAt || "unknown date"}`);
+      if (session.sessionId) lines.push(`Session: ${session.sessionId}`);
+      if (session.exactAvailable) lines.push(`Confidence: ${session.confidence}`);
+      else lines.push("Confidence: estimated; exact token usage was not present in the local log.");
+      lines.push("");
+      lines.push(`Input:        ${formatTokenCount(session.exactInputTokens).padStart(8)} tokens  ->  ${formatMoney(session.cost.input)}`);
+      lines.push(`Output:       ${formatTokenCount(session.exactOutputTokens).padStart(8)} tokens  ->  ${formatMoney(session.cost.output)}`);
+      lines.push(`Cache write:  ${formatTokenCount(session.exactCacheCreationTokens).padStart(8)} tokens  ->  ${formatMoney(session.cost.cacheWrite)}`);
+      lines.push(`Cache read:   ${formatTokenCount(session.exactCacheReadTokens).padStart(8)} tokens  ->  ${formatMoney(session.cost.cacheRead)}`);
+      lines.push("--------------------------------------------------");
+      lines.push(`Total:        ${formatTokenCount(session.exactTotalTokens || session.contextTokens).padStart(8)} tokens  ->  ${formatMoney(session.cost.total)}`);
+      if (session.cost.cacheSavings > 0) lines.push("");
+      if (session.cost.cacheSavings > 0) lines.push(`Cache saved you ${formatMoney(session.cost.cacheSavings)} (vs no caching)`);
+      lines.push("");
+      lines.push("Prismo Diagnosis");
+      lines.push(`Waste score: ${session.prismo.wasteScore}/100`);
+      lines.push(`Estimated avoidable spend: ${formatMoney(session.prismo.estimatedAvoidableCost)} (${Math.round(session.prismo.estimatedAvoidableRate * 100)}%)`);
+      if (session.prismo.drivers.length) {
+        lines.push("Cost Drivers:");
+        session.prismo.drivers.slice(0, 3).forEach((driver) => lines.push(`- ${driver.message}`));
+      }
+      lines.push("Better Next Actions:");
+      session.prismo.recommendations.forEach((recommendation) => lines.push(`- ${recommendation}`));
+    });
+    lines.push("");
+    lines.push(`Next: ${NPX_COMMAND} scan --usage to connect spend back to repo token waste.`);
+    return lines.join("\n");
+  }
+
+  return {
+    buildClaudeCostInsights,
+    buildClaudeSessionDiagnosis,
+    buildSessionTimeline,
+    calculateClaudeCost,
+    renderClaudeCostTerminal,
+  };
+};

package/lib/prismo-dev/usage-log-utils.js

@@ -0,0 +1,251 @@
+module.exports = function createUsageLogUtils(deps) {
+  const {
+    fs,
+    path,
+    GENERATED_ARTIFACT_PATTERNS,
+    readIfText,
+  } = deps;
+
+  function listFilesRecursive(root, predicate = () => true, limit = 300) {
+    const files = [];
+    if (!fs.existsSync(root)) return files;
+    const stack = [root];
+    while (stack.length && files.length < limit) {
+      const current = stack.pop();
+      let entries;
+      try {
+        entries = fs.readdirSync(current, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        const fullPath = path.join(current, entry.name);
+        if (entry.isDirectory()) {
+          stack.push(fullPath);
+        } else if (entry.isFile() && predicate(fullPath)) {
+          files.push(fullPath);
+        }
+      }
+    }
+    return files.sort((a, b) => {
+      try {
+        return fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs;
+      } catch {
+        return 0;
+      }
+    });
+  }
+
+  function parseJsonl(filePath, maxLines = 20000) {
+    const text = readIfText(filePath, 30 * 1024 * 1024);
+    if (!text) return [];
+    const rows = [];
+    const lines = text.split(/\r?\n/).filter(Boolean);
+    for (const line of lines.slice(Math.max(0, lines.length - maxLines))) {
+      try {
+        rows.push(JSON.parse(line));
+      } catch {
+        // Local tool logs can contain partial writes while a session is active.
+      }
+    }
+    return rows;
+  }
+
+  function collectText(value, options = {}, depth = 0) {
+    if (value == null || depth > 8) return "";
+    if (typeof value === "string") return value;
+    if (typeof value === "number" || typeof value === "boolean") return String(value);
+    if (Array.isArray(value)) return value.map((item) => collectText(item, options, depth + 1)).join("\n");
+    if (typeof value !== "object") return "";
+
+    const skipKeys = new Set(["signature", "encrypted_content", "image_url", "data", "auth", "api_key", "token"]);
+    const parts = [];
+    for (const [key, child] of Object.entries(value)) {
+      if (skipKeys.has(key)) continue;
+      parts.push(collectText(child, options, depth + 1));
+    }
+    return parts.filter(Boolean).join("\n");
+  }
+
+  function addUsage(target, usage) {
+    if (!usage || typeof usage !== "object") return;
+    target.inputTokens += Number(usage.input_tokens || usage.prompt_tokens || 0);
+    target.outputTokens += Number(usage.output_tokens || usage.completion_tokens || 0);
+    target.cacheReadTokens += Number(usage.cache_read_input_tokens || 0);
+    target.cacheCreationTokens += Number(usage.cache_creation_input_tokens || 0);
+  }
+
+  function totalUsageTokens(usage) {
+    if (!usage) return 0;
+    return (
+      Number(usage.input_tokens || usage.prompt_tokens || 0) +
+      Number(usage.output_tokens || usage.completion_tokens || 0) +
+      Number(usage.cache_read_input_tokens || 0) +
+      Number(usage.cache_creation_input_tokens || 0)
+    );
+  }
+
+  function incrementMap(map, key, amount = 1) {
+    if (!key) return;
+    map[key] = (map[key] || 0) + amount;
+  }
+
+  function normalizeMentionedPath(value, cwd = "") {
+    let normalized = String(value || "")
+      .replace(/\\/g, "/")
+      .replace(/^[`'"]+|[`'",:;)\]}]+$/g, "")
+      .trim();
+    normalized = normalized.replace(/^[ MADRCU?!]{1,4}\s+(?=\/|Users\/|home\/)/, "");
+    const normalizedCwd = String(cwd || "").replace(/\\/g, "/");
+    const wasAbsolute = normalized.startsWith("/");
+    if (wasAbsolute && normalizedCwd && !normalized.startsWith(`${normalizedCwd}/`) && normalized !== normalizedCwd) {
+      return "";
+    }
+    if (normalizedCwd && normalized.startsWith(normalizedCwd)) {
+      normalized = normalized.slice(normalizedCwd.length);
+    }
+    normalized = normalized.replace(/^\.?\//, "");
+    if (normalizedCwd) {
+      const repoName = path.basename(normalizedCwd);
+      const repoIndex = normalized.indexOf(`${repoName}/`);
+      if (repoIndex >= 0) normalized = normalized.slice(repoIndex + repoName.length + 1);
+    }
+    return normalized;
+  }
+
+  function isGeneratedArtifactPath(relPath) {
+    const normalized = normalizeMentionedPath(relPath);
+    return GENERATED_ARTIFACT_PATTERNS.some((pattern) => pattern.test(normalized));
+  }
+
+  function looksLikeUsefulPath(relPath) {
+    const normalized = normalizeMentionedPath(relPath);
+    if (!normalized || normalized.startsWith("http") || normalized.includes("://")) return false;
+    if (normalized.length < 3 || normalized.split("/").some((part) => !part || part.length > 120)) return false;
+    if (/^(Users|home|var|tmp|private|Volumes)\//i.test(normalized)) return false;
+    if (/^(Users|home|var|tmp|Downloads|Code|Projects)$/i.test(normalized)) return false;
+    if (isGeneratedArtifactPath(normalized)) return true;
+    if (/\.[A-Za-z0-9]{1,12}$/.test(normalized)) return true;
+    return /(^|\/)(src|app|lib|backend|frontend|tests|docs|scripts|components|pages|routes|api)\//.test(normalized);
+  }
+
+  function extractMentionedPaths(text, cwd = "") {
+    const found = new Set();
+    const source = String(text || "");
+    const pathPattern = /(?:^|[\s"'`])((?:\.{0,2}\/)?(?:[\w.@-]+\/)+[\w.@+-]+\.[A-Za-z0-9]{1,12})/g;
+    const filePattern = /(?:^|[\s"'`])((?:package-lock\.json|pnpm-lock\.yaml|yarn\.lock|coverage-final\.json|tsconfig\.json|pyproject\.toml|requirements\.txt|README\.md|CLAUDE\.md|AGENTS\.md))/g;
+    for (const pattern of [pathPattern, filePattern]) {
+      let match;
+      while ((match = pattern.exec(source))) {
+        const rel = normalizeMentionedPath(match[1], cwd);
+        if (!looksLikeUsefulPath(rel)) continue;
+        if (cwd && !isGeneratedArtifactPath(rel) && !fs.existsSync(path.join(cwd, rel))) continue;
+        found.add(rel);
+      }
+    }
+    return Array.from(found);
+  }
+
+  function normalizeCommand(value) {
+    return String(value || "")
+      .replace(/\s+/g, " ")
+      .replace(/[;|&]+$/g, "")
+      .trim()
+      .slice(0, 160);
+  }
+
+  function isShellCommand(value) {
+    return /^(npm|pnpm|yarn|bun|pytest|python3?|node|npx|uv|ruff|cargo|go|make|git|cd|rm|cp|mv|sed|rg|grep|find|cat)\b/.test(String(value || "").trim());
+  }
+
+  function extractCommandCandidates(row, text) {
+    const commands = [];
+    const directInputs = [
+      row.payload?.input,
+      row.payload?.arguments,
+      row.message?.input,
+      row.message?.arguments,
+    ];
+    for (const input of directInputs) {
+      if (typeof input === "string") commands.push(input);
+      else if (input && typeof input === "object") {
+        for (const value of Object.values(input)) {
+          if (typeof value === "string") commands.push(value);
+        }
+      }
+    }
+    const toolItems = Array.isArray(row.message?.content) ? row.message.content : [];
+    for (const item of toolItems) {
+      if (!item || typeof item !== "object") continue;
+      if (typeof item.input === "string") commands.push(item.input);
+      if (item.input && typeof item.input === "object") {
+        for (const value of Object.values(item.input)) {
+          if (typeof value === "string") commands.push(value);
+        }
+      }
+    }
+    if (/tool_use|function_call/i.test(row.type || row.payload?.type || "")) {
+      const commandPattern = /\b(?:npm|pnpm|yarn|bun|pytest|python3?|node|npx|uv|ruff|cargo|go test|make|git)\b[^\n\r"`']{0,140}/g;
+      for (const match of String(text || "").matchAll(commandPattern)) {
+        commands.push(match[0]);
+      }
+    }
+    return Array.from(new Set(commands.map(normalizeCommand).filter((cmd) => cmd.length >= 3 && /\s/.test(cmd) && isShellCommand(cmd))));
+  }
+
+  function topCountEntries(map, limit = 5, minCount = 2) {
+    return Object.entries(map || {})
+      .filter(([, count]) => count >= minCount)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, limit)
+      .map(([value, count]) => ({ value, count }));
+  }
+
+  function isExpectedRepeatedPath(value) {
+    const normalized = normalizeMentionedPath(value).toLowerCase();
+    return ["claude.md", "agents.md", "readme.md"].includes(normalized) || normalized.endsWith("/readme.md");
+  }
+
+  function getActionableRepeatedPaths(session, limit = 3) {
+    return (session.repeatedPathMentions || [])
+      .filter((item) => !isExpectedRepeatedPath(item.value))
+      .filter((item) => !isGeneratedArtifactPath(item.value))
+      .slice(0, limit);
+  }
+
+  function summarizeGeneratedArtifacts(items = [], limit = 4) {
+    const groups = new Map();
+    for (const item of items) {
+      const value = normalizeMentionedPath(item.value);
+      let key = "generated files";
+      if (value.includes("__pycache__/") || value.endsWith(".pyc")) key = "__pycache__";
+      else if (value.includes("node_modules/")) key = "node_modules";
+      else if (/package-lock\.json|pnpm-lock\.yaml|yarn\.lock$/i.test(value)) key = "lockfiles";
+      else if (value.includes("/dist/") || value.startsWith("dist/")) key = "dist";
+      else if (value.includes("/build/") || value.startsWith("build/")) key = "build";
+      else if (value.includes("/coverage/") || value.startsWith("coverage/")) key = "coverage";
+      else if (/(^|\/)assets\/[^/]+-[A-Za-z0-9_-]{6,}\.(js|css|map)$/i.test(value)) key = "hashed assets";
+      const current = groups.get(key) || { type: key, count: 0, examples: [] };
+      current.count += Number(item.count || 1);
+      if (current.examples.length < 2) current.examples.push(value);
+      groups.set(key, current);
+    }
+    return Array.from(groups.values()).sort((a, b) => b.count - a.count).slice(0, limit);
+  }
+
+  return {
+    addUsage,
+    collectText,
+    extractCommandCandidates,
+    extractMentionedPaths,
+    getActionableRepeatedPaths,
+    incrementMap,
+    isGeneratedArtifactPath,
+    listFilesRecursive,
+    normalizeMentionedPath,
+    parseJsonl,
+    summarizeGeneratedArtifacts,
+    topCountEntries,
+    totalUsageTokens,
+  };
+};