chainlesschain 0.162.48 → 0.162.60

package/src/repl/config-summary.js

@@ -0,0 +1,59 @@
+/**
+ * `/config` REPL command (Claude-Code parity) — show the effective
+ * configuration in a readable, SECRET-SAFE form: the LLM provider/model/baseURL
+ * actually in effect, whether an API key is set (never the key itself), the
+ * web-search backend, and the config-file path. Also surfaces the session's
+ * active provider/model, which can differ from the file (a --provider flag or
+ * .claude/settings.json overrides it).
+ *
+ * Pure: takes the loaded config + context, returns plain text. The REPL does
+ * the I/O. NEVER prints a secret — only "set (…1234)" / "not set".
+ */
+
+/** Mask a secret: presence + last 4 chars only, or "not set". */
+export function maskSecret(v) {
+  if (v == null || v === "") return "not set";
+  const s = String(v);
+  return s.length <= 4 ? "set (hidden)" : `set (…${s.slice(-4)})`;
+}
+
+/**
+ * @param {object|null} config  loaded config.json
+ * @param {object} [opts]  { path, activeProvider, activeModel }
+ * @returns {string}
+ */
+export function renderConfigSummary(config, opts = {}) {
+  const cfg = config || {};
+  const llm = cfg.llm || {};
+  const lines = ["Effective configuration:"];
+  if (opts.path) lines.push(`  config file: ${opts.path}`);
+
+  lines.push("  llm:");
+  lines.push(`    provider: ${llm.provider || "(unset → defaults to ollama)"}`);
+  lines.push(`    model:    ${llm.model || "(unset)"}`);
+  if (llm.visionModel) lines.push(`    vision:   ${llm.visionModel}`);
+  if (llm.baseUrl) lines.push(`    baseUrl:  ${llm.baseUrl}`);
+  lines.push(`    apiKey:   ${maskSecret(llm.apiKey)}`);
+
+  const ws = cfg.webSearch || {};
+  if (ws.provider || ws.apiKey) {
+    lines.push("  webSearch:");
+    lines.push(`    provider: ${ws.provider || "(unset → auto)"}`);
+    lines.push(`    apiKey:   ${maskSecret(ws.apiKey)}`);
+  }
+
+  if (opts.activeProvider || opts.activeModel) {
+    const ap = opts.activeProvider || "?";
+    const am = opts.activeModel || "?";
+    const differs = !!llm.provider && (ap !== llm.provider || am !== llm.model);
+    lines.push(
+      `  active this session: ${ap} · ${am}` +
+        (differs ? "  (overrides config)" : ""),
+    );
+  }
+
+  lines.push(
+    "  note: keys are hidden; env vars (e.g. *_API_KEY) can override config at runtime.",
+  );
+  return lines.join("\n");
+}

package/src/repl/conversation-export.js

@@ -0,0 +1,133 @@
+/**
+ * `/export` REPL command — dump the LIVE in-memory conversation to a Markdown
+ * transcript (Claude-Code parity). Distinct from `cc export` (knowledge-base
+ * export) and from `cc session export` (which reads the persisted JSONL store):
+ * this renders the agent REPL's working `messages` array, so it captures
+ * exactly what's in context right now, persisted or not.
+ *
+ * Pure over the OpenAI-shaped message list the agent loop maintains:
+ *   {role:"user"|"assistant"|"system", content}              content: string | parts[]
+ *   {role:"assistant", content, tool_calls:[{function:{name,arguments}}]}
+ *   {role:"tool", content, tool_call_id}
+ * The REPL does the file I/O; this only produces text + a default filename.
+ */
+
+export const TOOL_BLOCK_CAP = 4000;
+
+/** Render message content (string, or OpenAI multimodal parts[]) as text. */
+function contentToText(content) {
+  if (content == null) return "";
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") return part;
+        if (!part || typeof part !== "object") return "";
+        if (part.type === "text" || typeof part.text === "string") {
+          return part.text || "";
+        }
+        if (part.type === "image_url" || part.image_url) return "[image]";
+        return "";
+      })
+      .filter(Boolean)
+      .join("\n");
+  }
+  try {
+    return JSON.stringify(content, null, 2);
+  } catch {
+    return String(content);
+  }
+}
+
+function fence(body, lang = "") {
+  const text =
+    typeof body === "string"
+      ? body
+      : (() => {
+          try {
+            return JSON.stringify(body, null, 2);
+          } catch {
+            return String(body);
+          }
+        })();
+  const capped =
+    text.length > TOOL_BLOCK_CAP
+      ? `${text.slice(0, TOOL_BLOCK_CAP)}\n… [truncated]`
+      : text;
+  const guard = capped.includes("```") ? "````" : "```";
+  return `${guard}${lang}\n${capped}\n${guard}`;
+}
+
+/** Pretty-print a tool_call's JSON-string arguments, falling back to raw. */
+function prettyArgs(argStr) {
+  if (typeof argStr !== "string") return fence(argStr, "json");
+  try {
+    return fence(JSON.parse(argStr), "json");
+  } catch {
+    return fence(argStr);
+  }
+}
+
+const two = (n) => String(n).padStart(2, "0");
+
+/**
+ * A timestamped default filename, e.g. chainlesschain-export-20260613-130600.md.
+ * Takes a Date so callers/tests stay deterministic.
+ */
+export function defaultExportFilename(date = new Date()) {
+  const d = date instanceof Date && !isNaN(date) ? date : new Date(0);
+  const stamp =
+    `${d.getFullYear()}${two(d.getMonth() + 1)}${two(d.getDate())}` +
+    `-${two(d.getHours())}${two(d.getMinutes())}${two(d.getSeconds())}`;
+  return `chainlesschain-export-${stamp}.md`;
+}
+
+/**
+ * Render the conversation as Markdown.
+ * @param {Array} messages  the REPL's working message list
+ * @param {object} [meta]   { provider, model, sessionId, exportedAt }
+ * @returns {string}
+ */
+export function renderConversationMarkdown(messages, meta = {}) {
+  const msgs = Array.isArray(messages) ? messages : [];
+  const L = ["# ChainlessChain Conversation Export", ""];
+  const bits = [];
+  if (meta.sessionId) bits.push(`session: ${meta.sessionId}`);
+  if (meta.provider) bits.push(`provider: ${meta.provider}`);
+  if (meta.model) bits.push(`model: ${meta.model}`);
+  if (meta.exportedAt) bits.push(`exported: ${meta.exportedAt}`);
+  if (bits.length) {
+    L.push(`> ${bits.join(" · ")}`, "");
+  }
+
+  let users = 0;
+  let assistants = 0;
+  for (const m of msgs) {
+    if (!m || typeof m !== "object") continue;
+    const role = m.role;
+    if (role === "user") {
+      users += 1;
+      L.push("## 👤 User", "", contentToText(m.content), "");
+    } else if (role === "assistant") {
+      const text = contentToText(m.content);
+      if (text) {
+        assistants += 1;
+        L.push("## 🤖 Assistant", "", text, "");
+      }
+      if (Array.isArray(m.tool_calls)) {
+        for (const tc of m.tool_calls) {
+          const name = tc?.function?.name || tc?.name || "?";
+          L.push(`**🔧 tool_call — \`${name}\`**`, "");
+          L.push(prettyArgs(tc?.function?.arguments ?? tc?.arguments), "");
+        }
+      }
+    } else if (role === "tool") {
+      L.push("**↩ tool_result**", "", fence(contentToText(m.content)), "");
+    } else if (role === "system") {
+      L.push("## ⚙ System", "", contentToText(m.content), "");
+    }
+  }
+
+  L.push("---", `_${users} user / ${assistants} assistant turns_`, "");
+  return L.join("\n");
+}

package/src/repl/doctor-status.js

@@ -0,0 +1,114 @@
+/**
+ * `/doctor` REPL command (Claude-Code parity) — a consolidated session-health
+ * readout. Where /config, /ide, /mcp, /permissions each show one subsystem,
+ * /doctor rolls them into a single pass/warn view and flags the common reasons
+ * a chat silently fails (no provider, provider set but no key, …).
+ *
+ * Pure and dependency-free: `buildDoctorChecks` turns already-resolved session
+ * state into a check list, `renderDoctor` formats it. The REPL gathers inputs.
+ */
+
+/** Providers whose models run locally and need no API key. */
+const FREE_PROVIDERS = ["ollama", "local", "llamacpp", "mediapipe"];
+
+/**
+ * @param {object} input
+ *   { config, ideTools?: string[], mcpServers?: Array, permissionRules?, settingsHooks? }
+ * @returns {Array<{level:'ok'|'warn'|'info'|'err', name:string, detail:string}>}
+ */
+export function buildDoctorChecks(input = {}) {
+  const { config, ideTools, mcpServers, permissionRules, settingsHooks } =
+    input;
+  const llm = (config && config.llm) || {};
+  const checks = [];
+
+  // LLM provider / model
+  if (!llm.provider) {
+    checks.push({
+      level: "warn",
+      name: "LLM provider",
+      detail:
+        "unset → defaults to ollama (local); set llm.provider or --provider",
+    });
+  } else {
+    checks.push({
+      level: "ok",
+      name: "LLM provider",
+      detail: `${llm.provider}${llm.model ? " · " + llm.model : " (no model set)"}`,
+    });
+  }
+
+  // API key for non-local providers
+  if (
+    llm.provider &&
+    !FREE_PROVIDERS.includes(String(llm.provider).toLowerCase()) &&
+    !llm.apiKey
+  ) {
+    checks.push({
+      level: "warn",
+      name: "API key",
+      detail: `${llm.provider} has no apiKey set (config llm.apiKey or a *_API_KEY env var)`,
+    });
+  }
+
+  // IDE bridge
+  const ideCount = Array.isArray(ideTools) ? ideTools.length : 0;
+  checks.push(
+    ideCount > 0
+      ? {
+          level: "ok",
+          name: "IDE bridge",
+          detail: `${ideCount} tools connected`,
+        }
+      : { level: "info", name: "IDE bridge", detail: "not connected" },
+  );
+
+  // MCP servers
+  const mcpCount = Array.isArray(mcpServers) ? mcpServers.length : 0;
+  checks.push(
+    mcpCount > 0
+      ? { level: "ok", name: "MCP servers", detail: `${mcpCount} connected` }
+      : { level: "info", name: "MCP servers", detail: "none" },
+  );
+
+  // Permission rules
+  const ruleCount = permissionRules
+    ? (permissionRules.allow?.length || 0) +
+      (permissionRules.ask?.length || 0) +
+      (permissionRules.deny?.length || 0)
+    : 0;
+  checks.push({
+    level: "info",
+    name: "Permission rules",
+    detail: ruleCount > 0 ? `${ruleCount} rule(s)` : "none (default gate)",
+  });
+
+  // settings.json hooks
+  checks.push({
+    level: "info",
+    name: "settings.json hooks",
+    detail: settingsHooks ? "loaded" : "none",
+  });
+
+  return checks;
+}
+
+const ICON = { ok: "✓", warn: "⚠", err: "✗", info: "·" };
+
+/** Render the check list as a readable health block. */
+export function renderDoctor(checks) {
+  const list = Array.isArray(checks) ? checks : [];
+  const lines = ["Session health (/doctor):"];
+  for (const c of list) {
+    lines.push(`  ${ICON[c.level] || "·"} ${c.name}: ${c.detail}`);
+  }
+  const problems = list.filter(
+    (c) => c.level === "warn" || c.level === "err",
+  ).length;
+  lines.push(
+    problems === 0
+      ? "  no problems detected"
+      : `  ${problems} item(s) need attention`,
+  );
+  return lines.join("\n");
+}

package/src/repl/memory-status.js

@@ -0,0 +1,45 @@
+/**
+ * `/memory` REPL command (Claude-Code parity) — show the project-memory files
+ * the agent auto-loads into its system prompt (the cc.md > CLAUDE.md > AGENTS.md
+ * hierarchy + @imports + path-scoped rules), so "why does it know/behave like
+ * this?" is answerable in-session. Distinct from `#` (append a note to cc.md)
+ * and `cc memory recall` (the scoped MemoryStore).
+ *
+ * Pure: renders a loadProjectInstructions() result. The REPL does the I/O.
+ */
+
+/**
+ * @param {{files?:Array<{path:string,scope:string,bytes?:number,truncated?:boolean}>,warnings?:string[]}} loaded
+ * @param {{enabled?:boolean}} [opts]  enabled=false when CC_PROJECT_MEMORY=0
+ * @returns {string}
+ */
+export function renderMemoryFiles(loaded, { enabled = true } = {}) {
+  const files = Array.isArray(loaded?.files) ? loaded.files : [];
+  const warnings = Array.isArray(loaded?.warnings) ? loaded.warnings : [];
+  const lines = ["Project memory (auto-loaded into the system prompt):"];
+
+  if (!enabled) {
+    lines.push(
+      "  ⚠ disabled via CC_PROJECT_MEMORY=0 — the files below are NOT loaded this session",
+    );
+  }
+
+  if (files.length === 0) {
+    lines.push("  (none found — run `cc init` to generate a cc.md)");
+    return lines.join("\n");
+  }
+
+  let total = 0;
+  for (const f of files) {
+    const bytes = Number(f.bytes) || 0;
+    total += bytes;
+    lines.push(
+      `  [${String(f.scope || "?").padEnd(7)}] ${f.path}  ${bytes}B${f.truncated ? " (truncated)" : ""}`,
+    );
+  }
+  lines.push(
+    `  ${files.length} file(s), ${total}B total · precedence cc.md > CLAUDE.md > AGENTS.md`,
+  );
+  for (const w of warnings) lines.push(`  ⚠ ${w}`);
+  return lines.join("\n");
+}

package/src/repl/permissions-status.js

@@ -0,0 +1,51 @@
+/**
+ * `/permissions` REPL command (Claude-Code parity) — show the allow / ask /
+ * deny rules in effect for THIS session (loaded from .claude/settings.json by
+ * settings-loader, applied by permission-rules in agent-core's executeTool).
+ * These rules are otherwise invisible mid-session; surfacing them tells the
+ * user exactly what the agent can do unprompted, what it asks about, and what
+ * is blocked.
+ *
+ * Pure: takes the effective rules ({allow,ask,deny}) + the contributing source
+ * files, returns plain text. The REPL does the I/O.
+ */
+
+function pushGroup(lines, label, marker, rules) {
+  const list = Array.isArray(rules) ? rules : [];
+  if (list.length === 0) return;
+  lines.push(`  ${label}:`);
+  for (const r of list) lines.push(`    ${marker} ${r}`);
+}
+
+/**
+ * @param {{allow?:string[],ask?:string[],deny?:string[]}|null} rules
+ * @param {{files?:string[]}} [opts]
+ * @returns {string}
+ */
+export function renderPermissions(rules, { files = [] } = {}) {
+  const r = rules || { allow: [], ask: [], deny: [] };
+  const count =
+    (r.allow?.length || 0) + (r.ask?.length || 0) + (r.deny?.length || 0);
+
+  if (count === 0) {
+    return [
+      "Permission rules: none configured.",
+      "  Tools run under the default gate — dangerous shell commands still",
+      "  always require approval. Add rules in .claude/settings.json or via",
+      "  `cc permissions add`.",
+    ].join("\n");
+  }
+
+  const lines = ["Permission rules (effective this session):"];
+  // Render most-restrictive first to mirror the deny > ask > allow precedence.
+  pushGroup(lines, "deny  (blocked)", "✗", r.deny);
+  pushGroup(lines, "ask   (prompt first)", "?", r.ask);
+  pushGroup(lines, "allow (auto-approved)", "✓", r.allow);
+  if (Array.isArray(files) && files.length) {
+    lines.push(`  sources: ${files.join(", ")}`);
+  }
+  lines.push(
+    "  precedence: deny > ask > allow · dangerous shell commands are always denied",
+  );
+  return lines.join("\n");
+}

package/src/repl/recent-sessions.js

@@ -0,0 +1,46 @@
+/**
+ * `/sessions` REPL command — list recent RESUMABLE conversations (Claude-Code
+ * `/resume` parity, read-only half + mirrors the VS Code panel's /sessions).
+ * Where `/session` shows the CURRENT session, this lists past ones (across the
+ * DB + JSONL stores, via lib/recent-session.js listRecentSessions) with the
+ * ids you can pass to `cc agent --resume <id>`.
+ *
+ * Pure: renders the listRecentSessions row shape
+ *   { id, title?, message_count?, updated_at?, _store? }
+ * The REPL gathers the rows + supplies the current id.
+ */
+
+/**
+ * @param {Array} sessions  listRecentSessions() rows
+ * @param {{currentId?:string, limit?:number}} [opts]
+ * @returns {string}
+ */
+export function renderRecentSessions(sessions, opts = {}) {
+  const limit = opts.limit || 15;
+  const list = Array.isArray(sessions) ? sessions : [];
+  if (list.length === 0) {
+    return "No recent sessions found. Start chatting, or resume one later with `cc agent --resume <id>`.";
+  }
+
+  const lines = ["Recent sessions (resume with `cc agent --resume <id>`):"];
+  for (const s of list.slice(0, limit)) {
+    const id = String(s?.id || "");
+    if (!id) continue;
+    const current =
+      opts.currentId && id === opts.currentId ? "  ← current" : "";
+    const store = s._store ? `[${s._store}]` : "";
+    const msgs = Number.isFinite(s.message_count)
+      ? `${s.message_count} msgs`
+      : "";
+    const when = s.updated_at
+      ? String(s.updated_at).slice(0, 19).replace("T", " ")
+      : "";
+    const title = s.title && s.title !== "Untitled" ? ` — ${s.title}` : "";
+    const meta = [store, msgs, when].filter(Boolean).join(" · ");
+    lines.push(`  ${id.slice(0, 12)}${current}  ${meta}${title}`);
+  }
+  if (list.length > limit) {
+    lines.push(`  … +${list.length - limit} more`);
+  }
+  return lines.join("\n");
+}

package/src/repl/session-cost.js

@@ -0,0 +1,216 @@
+/**
+ * `/cost` REPL command — running token spend + estimated $ for the LIVE agent
+ * session (Claude-Code parity). Where `cc cost` reads persisted JSONL usage,
+ * this accumulates each turn's usage events IN MEMORY, so it reflects exactly
+ * this conversation and works even for anonymous (non-persisted) sessions.
+ *
+ * Pure and dependency-light (only the shared pricing lib); the REPL feeds it
+ * usage events and prints the rendered string.
+ */
+import { priceRollup, mergePricing } from "../lib/llm-pricing.js";
+
+function num(n) {
+  const v = Number(n);
+  return Number.isFinite(v) ? v : 0;
+}
+
+function fmtUsd(n) {
+  const v = Number(n) || 0;
+  if (v === 0) return "$0.00";
+  if (v < 0.01) return `$${v.toFixed(6)}`;
+  return `$${v.toFixed(4)}`;
+}
+
+/** A fresh accumulator: running totals + per provider/model rows. */
+export function newCostStore() {
+  return {
+    total: { inputTokens: 0, outputTokens: 0, totalTokens: 0, calls: 0 },
+    byKey: new Map(),
+  };
+}
+
+/**
+ * Fold the REPL's per-turn usage events ([{ provider, model, usage }]) into the
+ * store. Each `usage` is the raw LLM usage object (input_tokens/output_tokens/…
+ * with provider-variant aliases). Zero-token events are ignored. Mutates and
+ * returns the store.
+ */
+export function addUsage(store, events) {
+  const s = store || newCostStore();
+  for (const ev of Array.isArray(events) ? events : []) {
+    const u = ev && ev.usage ? ev.usage : null;
+    if (!u) continue;
+    const inT = num(u.input_tokens ?? u.prompt_tokens ?? u.inputTokens);
+    const outT = num(u.output_tokens ?? u.completion_tokens ?? u.outputTokens);
+    const totT = num(u.total_tokens ?? u.totalTokens ?? inT + outT);
+    if (inT === 0 && outT === 0 && totT === 0) continue;
+    s.total.inputTokens += inT;
+    s.total.outputTokens += outT;
+    s.total.totalTokens += totT;
+    s.total.calls += 1;
+    const key = `${ev.provider || "?"}/${ev.model || "?"}`;
+    let row = s.byKey.get(key);
+    if (!row) {
+      row = {
+        provider: ev.provider || null,
+        model: ev.model || null,
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        calls: 0,
+      };
+      s.byKey.set(key, row);
+    }
+    row.inputTokens += inT;
+    row.outputTokens += outT;
+    row.totalTokens += totT;
+    row.calls += 1;
+  }
+  return s;
+}
+
+/**
+ * Classify a priced model row into a cost CATEGORY by its role in the session
+ * (Claude-Code `/cost` breakdown parity). Roles are derived from config + the
+ * live session: the active model is "main", the configured vision model is
+ * "vision", any model in the fallback chain is "fallback", anything else (e.g.
+ * a model switched to mid-session) is "other".
+ *
+ * The active model wins over vision/fallback when names collide, so a session
+ * that never used vision shows everything as "main".
+ *
+ * @param {string} provider
+ * @param {string} model
+ * @param {{mainProvider?:string, mainModel?:string, visionModel?:string, fallbackModels?:string[]}} roles
+ * @returns {"main"|"vision"|"fallback"|"other"}
+ */
+export function classifyModelRole(provider, model, roles = {}) {
+  const lc = (x) => String(x || "").toLowerCase();
+  const p = lc(provider);
+  const m = lc(model);
+  if (
+    roles.mainModel &&
+    m === lc(roles.mainModel) &&
+    (!roles.mainProvider || p === lc(roles.mainProvider))
+  ) {
+    return "main";
+  }
+  if (roles.visionModel && m === lc(roles.visionModel)) return "vision";
+  if (
+    Array.isArray(roles.fallbackModels) &&
+    roles.fallbackModels.some((fm) => lc(fm) === m)
+  ) {
+    return "fallback";
+  }
+  return "other";
+}
+
+/**
+ * Group a priced rollup's per-model rows into categories. Operates on the output
+ * of priceRollup (rows carry cost/matched/free), so dollar sums are accurate and
+ * unpriced models are flagged rather than silently counted as $0.
+ *
+ * @returns {Array<{category,inputTokens,outputTokens,totalTokens,calls,cost,models,anyUnpriced}>}
+ *          sorted by cost (then tokens) descending.
+ */
+export function categorizeByRole(pricedResult, roles = {}) {
+  const cats = new Map();
+  for (const row of pricedResult?.byModel || []) {
+    const category = classifyModelRole(row.provider, row.model, roles);
+    let c = cats.get(category);
+    if (!c) {
+      c = {
+        category,
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        calls: 0,
+        cost: 0,
+        models: [],
+        anyUnpriced: false,
+      };
+      cats.set(category, c);
+    }
+    c.inputTokens += num(row.inputTokens);
+    c.outputTokens += num(row.outputTokens);
+    c.totalTokens += num(row.totalTokens);
+    c.calls += num(row.calls);
+    if (row.matched && !row.free) c.cost += num(row.cost);
+    if (!row.matched && !row.free) c.anyUnpriced = true;
+    if (row.model && !c.models.includes(row.model)) c.models.push(row.model);
+  }
+  return Array.from(cats.values()).sort(
+    (a, b) => b.cost - a.cost || b.totalTokens - a.totalTokens,
+  );
+}
+
+/** Snapshot the store as the `{ total, byModel[] }` aggregate priceRollup wants. */
+export function costAggregate(store) {
+  const s = store || newCostStore();
+  return {
+    total: { ...s.total },
+    byModel: Array.from(s.byKey.values()).sort(
+      (a, b) => b.totalTokens - a.totalTokens,
+    ),
+  };
+}
+
+/**
+ * Render the live session cost. `pricingOverrides` is typically
+ * `config.llm.pricing`. Returns plain text (the REPL does the I/O).
+ */
+export function renderSessionCost(store, { pricingOverrides, roles } = {}) {
+  const agg = costAggregate(store);
+  if (agg.total.calls === 0) {
+    return "Session cost: no LLM calls yet this session.";
+  }
+  const table = mergePricing(pricingOverrides);
+  const result = priceRollup(agg, { table });
+  const lines = [];
+  lines.push("Session cost (estimated):");
+  lines.push(
+    `  total: ${fmtUsd(result.cost.totalCost)} USD  ` +
+      `(${result.total.totalTokens.toLocaleString()} tokens, ${result.total.calls} calls)`,
+  );
+  for (const row of result.byModel) {
+    const provider = (row.provider || "?").padEnd(10);
+    const model = (row.model || "?").padEnd(24);
+    const tokens = `in=${row.inputTokens} out=${row.outputTokens}`;
+    const price = row.free
+      ? "free (local)"
+      : row.matched
+        ? fmtUsd(row.cost)
+        : "unpriced";
+    lines.push(`  ${provider} ${model} ${price}  ${tokens}`);
+  }
+
+  // Category breakdown (main / vision / fallback / other) — only worth showing
+  // when more than one category was actually used; a single-model session is
+  // already fully described by the per-model rows above.
+  if (roles) {
+    const cats = categorizeByRole(result, roles);
+    if (cats.length >= 2) {
+      const totalCost = num(result.cost.totalCost);
+      lines.push("  by category:");
+      for (const c of cats) {
+        const label = c.category.padEnd(9);
+        const price =
+          c.anyUnpriced && c.cost === 0 ? "unpriced" : fmtUsd(c.cost);
+        const pct =
+          totalCost > 0 ? ` (${Math.round((c.cost / totalCost) * 100)}%)` : "";
+        lines.push(
+          `    ${label} ${price}${pct}  in=${c.inputTokens} out=${c.outputTokens} ${c.calls} calls`,
+        );
+      }
+    }
+  }
+
+  if (result.unpriced.length > 0) {
+    lines.push(
+      `  note: ${result.unpriced.length} model(s) have no rate — ` +
+        "tokens excluded from total. Add rates via config: llm.pricing.",
+    );
+  }
+  lines.push("  prices are estimates of public list rates (USD/1M tokens).");
+  return lines.join("\n");
+}