@geraldmaron/construct 1.0.0

package/lib/comment-lint.mjs

@@ -0,0 +1,191 @@
+/**
+ * lib/comment-lint.mjs — enforce the Construct comment policy from rules/common/comments.md.
+ *
+ * lintFile(path) checks a single file. lintRepo({ rootDir, fix }) checks all
+ * scoped paths and optionally inserts stub headers for files missing one.
+ * Used by `construct lint:comments`, the comment-lint PostToolUse hook, and CI.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// --- scoped paths that require a file header ---
+
+const JS_HEADER_GLOBS = [
+  /^bin\//,
+  /^lib\/(?!server\/)([\w-]+\.mjs)$/,
+  /^lib\/hooks\//,
+  /^lib\/server\//,
+  /^lib\/mcp\//,
+  /^lib\/metrics\//,
+  /^sync-agents\.mjs$/,
+  /^tests\//,
+];
+
+const MD_HEADER_GLOBS = [
+  /^personas\//,
+  /^skills\//,
+  /^rules\//,
+  /^commands\//,
+];
+
+function relPath(rootDir, absPath) {
+  return path.relative(rootDir, absPath).replace(/\\/g, '/');
+}
+
+function requiresHeader(rel) {
+  const ext = path.extname(rel);
+  const jsMatch = JS_HEADER_GLOBS.some(r => r.test(rel));
+  const mdMatch = MD_HEADER_GLOBS.some(r => r.test(rel));
+  const type = (jsMatch && ext !== '.html') ? 'js' : (jsMatch || mdMatch) ? 'md' : null;
+  return { required: jsMatch || mdMatch, type };
+}
+
+// --- header detection ---
+
+const JS_HEADER_RE = /^(?:#![^\n]*\n)?(?:\/\/[^\n]*\n)*\/\*\*[\s\S]*?\*\//;
+const MD_HEADER_RE = /^<!--[\s\S]*?-->/;
+const SH_HEADER_RE = /^#!.*\n(?:#[^\n]*\n)*/;
+
+function hasHeader(content, type) {
+  if (type === 'js') return JS_HEADER_RE.test(content.trimStart());
+  if (type === 'md') return MD_HEADER_RE.test(content.trimStart());
+  return SH_HEADER_RE.test(content.trimStart());
+}
+
+// --- banned comment patterns ---
+
+const BANNED = [
+  { pattern: /\/\/.*\b(?:added for|added recently|recently added|just added|new:)\b/i, label: 'point-in-time: "added for / recently / just / new:"' },
+  { pattern: /\/\/.*\b(?:used by|called from|only consumer)\b/i, label: 'caller reference: "used by / called from"' },
+  { pattern: /\/\/.*\bpreviously\b.*\bwe used to\b/i, label: 'point-in-time: "previously / we used to"' },
+  { pattern: /\/\/.*(?:#\d{3,}|GH-\d+|JIRA-\d+|closes #|fixes #|ticket )/i, label: 'issue/PR reference in source comment (put in commit message instead)' },
+  { pattern: /<!--.*\b(?:added for|added recently|just added|new:)\b.*-->/i, label: 'point-in-time in markdown comment' },
+  { pattern: /<!--.*\b(?:used by|called from|only consumer)\b.*-->/i, label: 'caller reference in markdown comment' },
+  { pattern: /\/\/\s*TODO(?:\((\w+)\))?:?(?!\s*\(\w+\):)/i, label: 'TODO without owner — use: TODO(owner): what and why' },
+];
+
+function checkBanned(content, filePath) {
+  if (filePath && (filePath.endsWith('comment-lint.mjs') || filePath.endsWith('comments.md'))) return [];
+  const warnings = [];
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    for (const { pattern, label } of BANNED) {
+      if (pattern.test(lines[i])) {
+        warnings.push({ line: i + 1, label });
+      }
+    }
+  }
+  return warnings;
+}
+
+// --- stub header generation ---
+
+function stubJsHeader(rel) {
+  return `/**\n * ${rel} — <one-line purpose>\n *\n * <2–6 line summary: what it does, who calls it, key side effects.>\n */\n`;
+}
+
+function stubMdHeader(rel) {
+  return `<!--\n${rel} — <one-line purpose>\n\n<2–6 line summary.>\n-->\n`;
+}
+
+function extractShebang(content) {
+  if (content.startsWith('#!')) {
+    const nl = content.indexOf('\n');
+    if (nl !== -1) return { shebang: content.slice(0, nl + 1), rest: content.slice(nl + 1) };
+  }
+  return { shebang: '', rest: content };
+}
+
+// --- single file lint ---
+
+/**
+ * Check one file against the comment policy.
+ * Returns { path, errors, warnings }.
+ */
+export function lintFile(filePath, { rootDir = process.cwd(), fix = false } = {}) {
+  const rel = relPath(rootDir, filePath);
+  const { required, type } = requiresHeader(rel);
+
+  let content;
+  try { content = fs.readFileSync(filePath, 'utf8'); } catch { return { path: rel, errors: [], warnings: [] }; }
+
+  const errors = [];
+  const warnings = [];
+
+  if (required && !hasHeader(content, type)) {
+    errors.push({ line: 1, label: `missing file header block (see rules/common/comments.md §1)` });
+    if (fix) {
+      const stub = type === 'md' ? stubMdHeader(rel) : stubJsHeader(rel);
+      const { shebang, rest } = extractShebang(content);
+      fs.writeFileSync(filePath, shebang + stub + rest);
+    }
+  }
+
+  const banned = checkBanned(content, filePath);
+  for (const w of banned) warnings.push(w);
+
+  return { path: rel, errors, warnings };
+}
+
+// --- repo-wide lint ---
+
+function walkDir(dir, results = []) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return results; }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (['.git', 'node_modules', 'site', '.cx', '.construct', '.claude'].includes(entry.name)) continue;
+      walkDir(full, results);
+    } else if (entry.isFile()) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Lint all scoped files in the repo. Returns an array of lint results.
+ * With fix:true, inserts stub headers for missing-header errors.
+ */
+export function lintRepo({ rootDir = process.cwd(), fix = false } = {}) {
+  const files = walkDir(rootDir);
+  const results = [];
+  for (const f of files) {
+    const rel = relPath(rootDir, f);
+    const { required } = requiresHeader(rel);
+    const ext = path.extname(f);
+    if (!required && !['.mjs', '.md', '.sh'].includes(ext)) continue;
+    const result = lintFile(f, { rootDir, fix });
+    if (result.errors.length || result.warnings.length) results.push(result);
+  }
+  return results;
+}
+
+/**
+ * Format lint results for terminal output. Returns { output, exitCode }.
+ */
+export function formatResults(results) {
+  if (!results.length) return { output: '  ✓  No comment policy violations found.\n', exitCode: 0 };
+
+  const lines = [];
+  let errorCount = 0;
+  let warnCount = 0;
+
+  for (const { path: p, errors, warnings } of results) {
+    for (const { line, label } of errors) {
+      lines.push(`  error  ${p}:${line}  ${label}`);
+      errorCount++;
+    }
+    for (const { line, label } of warnings) {
+      lines.push(`  warn   ${p}:${line}  ${label}`);
+      warnCount++;
+    }
+  }
+
+  const summary = `\n  ${errorCount} error(s), ${warnCount} warning(s)`;
+  lines.push(summary);
+
+  return { output: lines.join('\n') + '\n', exitCode: errorCount > 0 ? 1 : 0 };
+}

package/lib/completions.mjs

@@ -0,0 +1,170 @@
+/**
+ * completions.mjs — generates bash and zsh completion scripts for construct.
+ *
+ * Called by sync-agents.mjs after each sync.
+ * Outputs to a platform-appropriate per-user completions directory.
+ */
+
+import { CLI_COMMANDS } from './cli-commands.mjs';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const COMPLETIONS_DIR = process.platform === 'win32'
+  ? join(process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'construct', 'completions')
+  : join(homedir(), '.local', 'share', 'construct', 'completions');
+
+function buildBash() {
+  const names = CLI_COMMANDS.map(c => c.name).join(' ');
+
+  const subcommandCases = CLI_COMMANDS
+    .filter(c => c.subcommands?.length)
+    .map(c => {
+      const subs = c.subcommands.map(s => s.name).join(' ');
+      return `        ${c.name}) COMPREPLY=($(compgen -W "${subs}" -- "$cur")) ;;`;
+    })
+    .join('\n');
+
+  const dirCommands = CLI_COMMANDS
+    .filter(c => c.usage?.includes('<dir>'))
+    .map(c => c.name)
+    .join('|');
+
+  const optionCases = CLI_COMMANDS
+    .filter(c => c.options?.length)
+    .map(c => {
+      const flags = c.options.map(o => o.flag.split('=')[0]).join(' ');
+      return `        ${c.name}) COMPREPLY=($(compgen -W "${flags}" -- "$cur")) ;;`;
+    })
+    .join('\n');
+
+  return `# bash completion for construct
+# Source this file in ~/.bashrc:
+#   source ~/.local/share/construct/completions/construct.bash
+
+_construct_completions() {
+  local cur prev words cword
+  _init_completion 2>/dev/null || {
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    words=("\${COMP_WORDS[@]}")
+    cword=$COMP_CWORD
+  }
+
+  local commands="${names}"
+
+  # First argument: complete command names
+  if [[ $cword -eq 1 ]]; then
+    COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+    return 0
+  fi
+
+  local cmd="\${words[1]}"
+
+  # Subcommands
+  if [[ $cword -eq 2 ]]; then
+    case "$cmd" in
+${subcommandCases}
+      ${dirCommands ? `${dirCommands}) _filedir -d ;;` : ''}
+    esac
+    return 0
+  fi
+
+  # Options (flags starting with -)
+  if [[ "$cur" == -* ]]; then
+    case "$cmd" in
+${optionCases}
+    esac
+    return 0
+  fi
+}
+
+complete -F _construct_completions construct
+`;
+}
+
+function buildZsh() {
+  const commandDescriptions = CLI_COMMANDS
+    .map(c => `    '${c.name}:${c.emoji} ${c.description.replace(/'/g, "\\'")}' \\`)
+    .join('\n');
+
+  const subcommandFunctions = CLI_COMMANDS
+    .filter(c => c.subcommands?.length)
+    .map(c => {
+      const subs = c.subcommands
+        .map(s => `      '${s.name}:${s.desc.replace(/'/g, "\\'")}'`)
+        .join('\n');
+      return `_construct_${c.name.replace(/-/g, '_')}() {
+  local subcmds
+  subcmds=(
+${subs}
+  )
+  _describe -t subcommands '${c.name} subcommand' subcmds
+}`;
+    })
+    .join('\n\n');
+
+  const subcommandDispatch = CLI_COMMANDS
+    .filter(c => c.subcommands?.length)
+    .map(c => `      ${c.name}) _construct_${c.name.replace(/-/g, '_')} ;;`)
+    .join('\n');
+
+  const dirCommands = CLI_COMMANDS
+    .filter(c => c.usage?.includes('<dir>'))
+    .map(c => c.name)
+    .join('|');
+
+  return `#compdef construct
+# zsh completion for construct
+# Add to fpath: fpath=(~/.local/share/construct/completions $fpath)
+# Then: autoload -Uz compinit && compinit
+
+${subcommandFunctions}
+
+_construct_commands() {
+  local commands
+  commands=(
+${commandDescriptions}
+  )
+  _describe -t commands 'construct command' commands
+}
+
+_construct() {
+  local context state state_descr line
+  typeset -A opt_args
+
+  _arguments -C \\
+    '1: :_construct_commands' \\
+    '*:: :->args'
+
+  case $state in
+    args)
+      case $words[1] in
+${subcommandDispatch}
+        ${dirCommands ? `${dirCommands}) _files -/ ;;` : ''}
+        *) ;;
+      esac
+      ;;
+  esac
+}
+
+_construct
+`;
+}
+
+export function generateCompletions() {
+  try {
+    mkdirSync(COMPLETIONS_DIR, { recursive: true });
+
+    writeFileSync(join(COMPLETIONS_DIR, 'construct.bash'), buildBash());
+    writeFileSync(join(COMPLETIONS_DIR, '_construct'), buildZsh());
+
+    return COMPLETIONS_DIR;
+  } catch (err) {
+    process.stderr.write(`[completions] failed to write: ${err.message}\n`);
+    return null;
+  }
+}
+
+export { COMPLETIONS_DIR };

package/lib/context-state.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * lib/context-state.mjs — compact project/session context persistence.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function contextJsonPath(rootDir) {
+  return join(rootDir, '.cx', 'context.json');
+}
+
+export function contextMarkdownPath(rootDir) {
+  return join(rootDir, '.cx', 'context.md');
+}
+
+export function readContextState(rootDir) {
+  const inspection = inspectContextState(rootDir);
+  return inspection.state;
+}
+
+export function inspectContextState(rootDir) {
+  const jsonPath = contextJsonPath(rootDir);
+  const mdPath = contextMarkdownPath(rootDir);
+  const hasJsonFile = existsSync(jsonPath);
+  const hasMarkdownFile = existsSync(mdPath);
+  const hasFile = hasJsonFile || hasMarkdownFile;
+
+  let state = null;
+  let source = 'missing';
+
+  if (hasJsonFile) {
+    try {
+      state = JSON.parse(readFileSync(jsonPath, 'utf8'));
+      source = 'json';
+    } catch {
+      source = hasMarkdownFile ? 'markdown' : 'invalid';
+    }
+  }
+
+  if (!state && hasMarkdownFile) {
+    try {
+      state = {
+        format: 'markdown',
+        markdown: readFileSync(mdPath, 'utf8'),
+      };
+      if (source !== 'json') source = 'markdown';
+    } catch {
+      if (!hasJsonFile) source = 'invalid';
+    }
+  }
+
+  return {
+    hasFile,
+    source,
+    savedAt: state?.savedAt || null,
+    summary: state?.contextSummary || contextSummaryLine(state) || null,
+    state,
+  };
+}
+
+export function writeContextState(rootDir, state, { markdown = null } = {}) {
+  const cxDir = join(rootDir, '.cx');
+  mkdirSync(cxDir, { recursive: true });
+
+  const payload = {
+    format: 'json',
+    savedAt: new Date().toISOString(),
+    ...state,
+  };
+  writeFileSync(contextJsonPath(rootDir), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+
+  if (markdown !== null) {
+    writeFileSync(contextMarkdownPath(rootDir), markdown.endsWith('\n') ? markdown : `${markdown}\n`, 'utf8');
+  }
+
+  return payload;
+}
+
+export function contextSummaryLine(state) {
+  if (!state || typeof state !== 'object') return '';
+  if (state.compact) return String(state.compact);
+  if (state.recoveryContext) return String(state.recoveryContext).slice(0, 240);
+  if (state.markdown) return String(state.markdown).slice(0, 240);
+  return '';
+}
+
+export function buildContextDigest(state, { maxItems = 3 } = {}) {
+  if (!state || typeof state !== 'object') return null;
+
+  return {
+    summary: state.contextSummary || contextSummaryLine(state) || null,
+    activeWork: Array.isArray(state.activeWork) ? state.activeWork.slice(0, maxItems) : [],
+    recentDecisions: Array.isArray(state.recentDecisions) ? state.recentDecisions.slice(0, maxItems) : [],
+    architectureNotes: Array.isArray(state.architectureNotes) ? state.architectureNotes.slice(0, maxItems) : [],
+    openQuestions: Array.isArray(state.openQuestions) ? state.openQuestions.slice(0, maxItems) : [],
+    source: state.source || null,
+    savedAt: state.savedAt || null,
+  };
+}

package/lib/cost.mjs

@@ -0,0 +1,213 @@
+/**
+ * lib/cost.mjs — <one-line purpose>
+ *
+ * <2–6 line summary: what it does, who calls it, key side effects.>
+ */
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function numberFrom(...values) {
+  for (const value of values) {
+    const n = Number(value);
+    if (Number.isFinite(n) && n !== 0) return n;
+  }
+  return 0;
+}
+
+export function normalizeCostEntry(entry = {}) {
+  const cacheCreation5mInputTokens = numberFrom(
+    entry.cache_creation_5m_input_tokens,
+    entry.cacheCreation5mInputTokens,
+    entry.cache_creation?.ephemeral_5m_input_tokens,
+  );
+  const cacheCreation1hInputTokens = numberFrom(
+    entry.cache_creation_1h_input_tokens,
+    entry.cacheCreation1hInputTokens,
+    entry.cache_creation?.ephemeral_1h_input_tokens,
+  );
+  const explicitCacheCreation = numberFrom(
+    entry.cache_creation_input_tokens,
+    entry.cacheCreationInputTokens,
+  );
+  const cacheCreationInputTokens = explicitCacheCreation || cacheCreation5mInputTokens + cacheCreation1hInputTokens;
+  const cacheReadInputTokens = numberFrom(
+    entry.cache_read_input_tokens,
+    entry.cacheReadInputTokens,
+    entry.prompt_tokens_details?.cached_tokens,
+  );
+  const inputTokens = numberFrom(
+    entry.input_tokens,
+    entry.inputTokens,
+    entry.prompt_tokens,
+    entry.promptTokens,
+  );
+  const outputTokens = numberFrom(
+    entry.output_tokens,
+    entry.outputTokens,
+    entry.completion_tokens,
+    entry.completionTokens,
+  );
+
+  return {
+    ...entry,
+    inputTokens,
+    outputTokens,
+    cacheReadInputTokens,
+    cacheCreationInputTokens,
+    cacheCreation5mInputTokens,
+    cacheCreation1hInputTokens,
+    processedInputTokens: inputTokens + cacheReadInputTokens + cacheCreationInputTokens,
+    totalTokens: inputTokens + outputTokens,
+    costUsd: Number(entry.cost_usd ?? entry.costUsd ?? 0),
+  };
+}
+
+export function readCostLog(homeDir) {
+  const logPath = join(homeDir, '.cx', 'session-cost.jsonl');
+  if (!existsSync(logPath)) return [];
+  try {
+    return readFileSync(logPath, 'utf8')
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function clearCostLog(homeDir) {
+  const logPath = join(homeDir, '.cx', 'session-cost.jsonl');
+  if (existsSync(logPath)) writeFileSync(logPath, '');
+}
+
+export function aggregateCostByAgent(entries) {
+  const agentMap = new Map();
+  for (const rawEntry of entries) {
+    const entry = normalizeCostEntry(rawEntry);
+    const agent = entry.agent || 'orchestrator';
+    const acc = agentMap.get(agent) ?? {
+      agent,
+      interactions: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadInputTokens: 0,
+      cacheCreationInputTokens: 0,
+      processedInputTokens: 0,
+      costUsd: 0,
+    };
+    acc.interactions += 1;
+    acc.inputTokens += entry.inputTokens;
+    acc.outputTokens += entry.outputTokens;
+    acc.cacheReadInputTokens += entry.cacheReadInputTokens;
+    acc.cacheCreationInputTokens += entry.cacheCreationInputTokens;
+    acc.processedInputTokens += entry.processedInputTokens;
+    acc.costUsd += entry.costUsd;
+    acc.cacheReadRate = acc.processedInputTokens > 0
+      ? Number((acc.cacheReadInputTokens / acc.processedInputTokens).toFixed(3))
+      : 0;
+    agentMap.set(agent, acc);
+  }
+  return [...agentMap.values()].sort((a, b) => b.costUsd - a.costUsd);
+}
+
+export function computeCacheStats(entries) {
+  const normalized = entries.map((entry) => normalizeCostEntry(entry));
+  const totalInput = normalized.reduce((sum, e) => sum + e.inputTokens, 0);
+  const totalCacheReadInputTokens = normalized.reduce((sum, e) => sum + e.cacheReadInputTokens, 0);
+  const totalCacheCreationInputTokens = normalized.reduce((sum, e) => sum + e.cacheCreationInputTokens, 0);
+  const totalCacheCreation5mInputTokens = normalized.reduce((sum, e) => sum + e.cacheCreation5mInputTokens, 0);
+  const totalCacheCreation1hInputTokens = normalized.reduce((sum, e) => sum + e.cacheCreation1hInputTokens, 0);
+  const totalProcessedInputTokens = totalInput + totalCacheReadInputTokens + totalCacheCreationInputTokens;
+  return {
+    totalInput,
+    totalCacheReadInputTokens,
+    totalCacheCreationInputTokens,
+    totalCacheCreation5mInputTokens,
+    totalCacheCreation1hInputTokens,
+    totalProcessedInputTokens,
+    totalCached: totalCacheReadInputTokens + totalCacheCreationInputTokens,
+    cacheReadRate: totalProcessedInputTokens > 0 ? Number((totalCacheReadInputTokens / totalProcessedInputTokens).toFixed(3)) : 0,
+  };
+}
+
+export function summarizeCostData(entries, { days, agent } = {}) {
+  const cutoff = days ? new Date(Date.now() - days * 86_400_000).toISOString() : null;
+  let filtered = cutoff ? entries.filter((e) => e.ts && e.ts >= cutoff) : entries;
+  if (agent) filtered = filtered.filter((e) => (e.agent || 'orchestrator') === agent);
+
+  const normalized = filtered.map((entry) => normalizeCostEntry(entry));
+  const totalInputTokens = normalized.reduce((s, e) => s + e.inputTokens, 0);
+  const totalOutputTokens = normalized.reduce((s, e) => s + e.outputTokens, 0);
+  const totalTokens = totalInputTokens + totalOutputTokens;
+  const totalCostUsd = normalized.reduce((s, e) => s + e.costUsd, 0);
+  const cacheStats = computeCacheStats(normalized);
+
+  return {
+    interactions: normalized.length,
+    totalInputTokens,
+    totalOutputTokens,
+    totalTokens,
+    totalCostUsd: Number(totalCostUsd.toFixed(4)),
+    processedInputTokens: cacheStats.totalProcessedInputTokens,
+    cacheReadInputTokens: cacheStats.totalCacheReadInputTokens,
+    cacheCreationInputTokens: cacheStats.totalCacheCreationInputTokens,
+    cacheCreation5mInputTokens: cacheStats.totalCacheCreation5mInputTokens,
+    cacheCreation1hInputTokens: cacheStats.totalCacheCreation1hInputTokens,
+    cachedTokens: cacheStats.totalCached,
+    cacheReadRate: cacheStats.cacheReadRate,
+    cacheHitRate: cacheStats.cacheReadRate,
+    byAgent: aggregateCostByAgent(normalized),
+    days: days ?? null,
+    agentFilter: agent ?? null,
+  };
+}
+
+export function formatCostReport(data, colors = {}) {
+  const C = { bold: '', dim: '', reset: '', green: '', yellow: '', cyan: '', red: '', ...colors };
+  const lines = [];
+  lines.push(`${C.bold}Construct Cost Report${C.reset}`);
+  lines.push('═════════════════════');
+  lines.push('');
+
+  if (data.days) lines.push(`${C.dim}Window: last ${data.days} day${data.days === 1 ? '' : 's'}${C.reset}`);
+  if (data.agentFilter) lines.push(`${C.dim}Agent filter: ${data.agentFilter}${C.reset}`);
+
+  lines.push(`Interactions:    ${data.interactions}`);
+  lines.push(`Total tokens:    ${data.totalTokens.toLocaleString()} (${data.totalInputTokens.toLocaleString()} uncached in / ${data.totalOutputTokens.toLocaleString()} out)`);
+  lines.push(`Processed input: ${Number(data.processedInputTokens || data.totalInputTokens || 0).toLocaleString()}`);
+
+  const readPct = ((data.cacheReadRate ?? data.cacheHitRate ?? 0) * 100).toFixed(1);
+  const cacheColor = (data.cacheReadRate ?? data.cacheHitRate ?? 0) >= 0.5 ? C.green : (data.cacheReadRate ?? data.cacheHitRate ?? 0) >= 0.2 ? C.yellow : C.red;
+  lines.push(`Cache reads:     ${Number(data.cacheReadInputTokens || 0).toLocaleString()} (${cacheColor}${readPct}% read rate${C.reset})`);
+  lines.push(`Cache writes:    ${Number(data.cacheCreationInputTokens || 0).toLocaleString()} (${Number(data.cacheCreation5mInputTokens || 0).toLocaleString()} 5m / ${Number(data.cacheCreation1hInputTokens || 0).toLocaleString()} 1h)`);
+  lines.push(`Estimated cost:  $${data.totalCostUsd.toFixed(4)}`);
+
+  if (data.byAgent.length > 0) {
+    lines.push('');
+    lines.push('By Agent:');
+    lines.push(`  ${'Agent'.padEnd(28)} ${'Turns'.padStart(5)}  ${'Input tok'.padStart(10)}  ${'Cost'.padStart(8)}  ${'Share'.padStart(5)}  Cache`);
+    lines.push(`  ${'-'.repeat(28)} ${'-'.repeat(5)}  ${'-'.repeat(10)}  ${'-'.repeat(8)}  ${'-'.repeat(5)}  -----`);
+    for (const a of data.byAgent) {
+      const sharePct = data.totalCostUsd > 0 ? Math.round((a.costUsd / data.totalCostUsd) * 100) : 0;
+      const hitRate = Math.round((a.cacheReadRate || 0) * 100);
+      const shareColor = sharePct >= 50 ? C.red : sharePct >= 25 ? C.yellow : '';
+      lines.push(
+        `  ${a.agent.padEnd(28)} ${String(a.interactions).padStart(5)}` +
+        `  ${a.inputTokens.toLocaleString().padStart(10)}` +
+        `  ${'$' + a.costUsd.toFixed(4).padStart(7)}` +
+        `  ${shareColor}${String(sharePct + '%').padStart(5)}${C.reset}` +
+        `  ${hitRate}%`,
+      );
+    }
+  }
+
+  if (data.interactions === 0) {
+    lines.push('');
+    lines.push(`${C.dim}No cost data recorded yet. Token usage is logged at session end.${C.reset}`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}