freeharness 0.4.1

package/dist/cli/cost.js

@@ -0,0 +1,501 @@
+// `freeharness cost`: aggregates the usage log written by the cost-tracker hook
+// (canonical/hooks/freeharness-cost-tracker.mjs). Every log line is a cumulative
+// snapshot of one session, so aggregation keeps the LAST snapshot per session
+// (keyed by transcript path, falling back to session id) before summing per project
+// and per model. Pure functions over parsed lines; index.ts prints.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** Usage log path: FREEHARNESS_COST_LOG when set, else ~/.claude/freeharness/cost/usage.jsonl (may not exist yet). */
+export function costLogPath() {
+    return process.env.FREEHARNESS_COST_LOG || path.join(os.homedir(), ".claude", "freeharness", "cost", "usage.jsonl");
+}
+/** Installed price table path (user scope): ~/.claude/freeharness/hooks/cost-prices.json (may not exist yet). */
+export function costPricesPath() {
+    return process.env.FREEHARNESS_COST_PRICES || path.join(os.homedir(), ".claude", "freeharness", "hooks", "cost-prices.json");
+}
+/** Reads and parses usage.jsonl (malformed lines skipped); records in file order, empty when the file is absent. */
+export function readUsage(file) {
+    return readLog(file).usage;
+}
+/** Reads usage.jsonl into usage snapshots and pruner records (malformed lines skipped); file order, empty when the file is absent. */
+export function readLog(file) {
+    const usage = [];
+    const pruned = [];
+    if (!fs.existsSync(file))
+        return { usage, pruned };
+    for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const r = JSON.parse(line);
+            if (!r || typeof r !== "object")
+                continue;
+            if (r.kind === "pruned")
+                pruned.push(r);
+            else if (r.usage && typeof r.usage === "object")
+                usage.push(r);
+        }
+        catch {
+            // malformed line: skipped
+        }
+    }
+    return { usage, pruned };
+}
+function emptyRow(key) {
+    return { key, sessions: 0, turns: 0, input: 0, output: 0, cache_read: 0, cache_write: 0, est_usd: 0 };
+}
+function addBucket(row, b, usd) {
+    row.input += Number(b.input) || 0;
+    row.output += Number(b.output) || 0;
+    row.cache_read += Number(b.cache_read) || 0;
+    row.cache_write += Number(b.cache_write) || 0;
+    row.est_usd += usd;
+}
+function round(n) {
+    return Math.round(n * 1e6) / 1e6;
+}
+/**
+ * Keeps the last snapshot per session (transcript path, else session id, else the
+ * line itself) so cumulative lines are not summed twice; one record per session,
+ * in first-seen order.
+ */
+export function latestPerSession(records) {
+    const map = new Map();
+    let anon = 0;
+    for (const r of records) {
+        const key = r.transcript || r.session_id || `line-${anon++}`;
+        const prev = map.get(key);
+        if (!prev || (r.ts ?? "") >= (prev.ts ?? ""))
+            map.set(key, r);
+    }
+    return [...map.values()];
+}
+/** Aggregates usage lines into per-project and per-model rows plus a total; rows sorted by estimated USD descending. */
+export function aggregate(records, filter = {}, log = costLogPath()) {
+    const now = filter.now ?? new Date();
+    const since = filter.days !== undefined ? new Date(now.getTime() - filter.days * 86_400_000) : undefined;
+    let sessions = latestPerSession(records);
+    if (since)
+        sessions = sessions.filter((r) => Date.parse(r.ts) >= since.getTime());
+    if (filter.project)
+        sessions = sessions.filter((r) => r.project === filter.project);
+    const byProject = new Map();
+    const byModel = new Map();
+    const total = emptyRow("total");
+    let last;
+    for (const r of sessions) {
+        const usd = Number(r.est_usd) || 0;
+        const p = byProject.get(r.project) ?? emptyRow(r.project || "(unknown)");
+        p.sessions += 1;
+        p.turns += Number(r.turns) || 0;
+        addBucket(p, r.usage, usd);
+        byProject.set(p.key, p);
+        total.sessions += 1;
+        total.turns += Number(r.turns) || 0;
+        addBucket(total, r.usage, usd);
+        const models = r.by_model && Object.keys(r.by_model).length > 0 ? Object.entries(r.by_model) : [];
+        for (const [model, b] of models) {
+            const m = byModel.get(model) ?? emptyRow(model);
+            m.sessions += 1;
+            addBucket(m, b, Number(b.est_usd) || 0);
+            byModel.set(model, m);
+        }
+        if (!last || r.ts > last)
+            last = r.ts;
+    }
+    const finish = (rows) => [...rows].map((r) => ({ ...r, est_usd: round(r.est_usd) })).sort((a, b) => b.est_usd - a.est_usd || a.key.localeCompare(b.key));
+    return {
+        log,
+        since: since?.toISOString(),
+        project: filter.project,
+        lines: records.length,
+        sessions: sessions.length,
+        byProject: finish(byProject.values()),
+        byModel: finish(byModel.values()),
+        total: { ...total, est_usd: round(total.est_usd) },
+        last,
+    };
+}
+/** Formats a token count compactly (1.2k, 3.4M). */
+export function fmtTokens(n) {
+    if (n >= 1e6)
+        return `${(n / 1e6).toFixed(2)}M`;
+    if (n >= 1e3)
+        return `${(n / 1e3).toFixed(1)}k`;
+    return String(n);
+}
+/** Renders the report as aligned text tables. */
+export function formatReport(report) {
+    const lines = [];
+    const scope = [report.since ? `last ${Math.round((Date.now() - Date.parse(report.since)) / 86_400_000)} days` : "all time", report.project ? `project ${report.project}` : ""].filter(Boolean).join(", ");
+    lines.push(`cost report (${scope}): ${report.log}`);
+    lines.push(`lines ${report.lines}, sessions ${report.sessions}${report.last ? `, last entry ${report.last}` : ""}`);
+    if (report.sessions === 0) {
+        lines.push("no usage recorded yet (the hook writes on Stop / SessionEnd; run `freeharness init --only cost` if it is not installed)");
+        return lines;
+    }
+    const table = (title, rows, showTurns) => {
+        lines.push("");
+        lines.push(title);
+        const head = [`${"".padEnd(28)}`, "sessions".padStart(8), showTurns ? "turns".padStart(6) : "", "input".padStart(9), "output".padStart(9), "cache_rd".padStart(9), "cache_wr".padStart(9), "est USD".padStart(10)].filter((c) => c !== "");
+        lines.push(`  ${head.join(" ")}`);
+        for (const r of rows) {
+            const cells = [r.key.slice(0, 28).padEnd(28), String(r.sessions).padStart(8), showTurns ? String(r.turns).padStart(6) : "", fmtTokens(r.input).padStart(9), fmtTokens(r.output).padStart(9), fmtTokens(r.cache_read).padStart(9), fmtTokens(r.cache_write).padStart(9), r.est_usd.toFixed(4).padStart(10)].filter((c) => c !== "");
+            lines.push(`  ${cells.join(" ")}`);
+        }
+    };
+    table("Per project:", report.byProject, true);
+    table("Per model:", report.byModel, false);
+    table("Total:", [report.total], true);
+    lines.push("");
+    lines.push("Estimates use the editable price table (`freeharness cost prices`); edit it to your contract.");
+    return lines;
+}
+/**
+ * Renders the `cost prefix` session-start injection as one line, apart from the main-session
+ * total: Claude Code injects the routing table into the session-start turn only, so its cost
+ * never rides every request the way the counted items do.
+ * @param injection The estimate's `injection` item.
+ * @returns The formatted line.
+ */
+export function formatInjectionLine(injection) {
+    return `  ${String(injection.tokens).padStart(6)} session-start (main session only) — ${injection.source}`;
+}
+/** Doctor summary for the cost log: size, entries, last entry. */
+export function costLogLine(file) {
+    if (!fs.existsSync(file))
+        return `OK   cost-tracker installed; no usage recorded yet (${file} appears after the first Stop)`;
+    const records = readUsage(file);
+    const kb = (fs.statSync(file).size / 1024).toFixed(1);
+    const last = records[records.length - 1];
+    const sessions = latestPerSession(records).length;
+    return `OK   cost log: ${records.length} entries (${sessions} sessions), ${kb} KB${last ? `, last ${last.ts} ${last.project} $${(Number(last.est_usd) || 0).toFixed(4)}` : ""} — ${file}`;
+}
+/** Tokens estimated from characters (4 chars per token). */
+function charsToTokens(chars) {
+    return Math.round((Number(chars) || 0) / 4);
+}
+/**
+ * Ranks token sinks per project: sessions (or task classes) by total tokens with the
+ * tool-output share and the pruned bytes recovered, and tools by output. Sessions without a
+ * task class are `untagged` and counted.
+ */
+export function sinks(records, filter = {}, log = costLogPath()) {
+    const now = filter.now ?? new Date();
+    const since = filter.days !== undefined ? new Date(now.getTime() - filter.days * 86_400_000) : undefined;
+    let sessions = latestPerSession(records);
+    if (since)
+        sessions = sessions.filter((r) => Date.parse(r.ts) >= since.getTime());
+    if (filter.project)
+        sessions = sessions.filter((r) => r.project === filter.project);
+    const top = filter.top && filter.top > 0 ? filter.top : 10;
+    const byProject = new Map();
+    let untagged = 0;
+    let prunedTotal = 0;
+    for (const r of sessions) {
+        const project = r.project || "(unknown)";
+        const cls = r.task_class && r.task_class.trim() ? r.task_class.trim() : "untagged";
+        if (cls === "untagged")
+            untagged += 1;
+        const p = byProject.get(project) ?? { rows: new Map(), tools: new Map(), subagentsTotal: 0, subagentSessions: 0 };
+        const key = filter.byTaskClass ? cls : r.session_id || r.transcript || "(unknown)";
+        const row = p.rows.get(key) ?? { key, task_class: cls, sessions: 0, tokens: 0, output: 0, tool_output_tokens: 0, tool_output_share: 0, pruned_bytes: 0, est_usd: 0 };
+        const tokens = Number(r.usage.total) || (Number(r.usage.input) || 0) + (Number(r.usage.output) || 0) + (Number(r.usage.cache_read) || 0) + (Number(r.usage.cache_write) || 0);
+        row.sessions += 1;
+        row.tokens += tokens;
+        row.output += Number(r.usage.output) || 0;
+        row.tool_output_tokens += charsToTokens(r.tool_output_chars ?? 0);
+        row.pruned_bytes += Number(r.pruned_bytes) || 0;
+        row.est_usd += Number(r.est_usd) || 0;
+        prunedTotal += Number(r.pruned_bytes) || 0;
+        p.rows.set(key, row);
+        for (const [tool, t] of Object.entries(r.by_tool ?? {})) {
+            const tr = p.tools.get(tool) ?? { tool, calls: 0, output_tokens: 0 };
+            tr.calls += Number(t.calls) || 0;
+            tr.output_tokens += charsToTokens(t.output_chars);
+            p.tools.set(tool, tr);
+        }
+        // Subagent tokens, tracked apart from `usage`, are never folded into it; the project
+        // cwd is kept too (needed below to locate the project's own telemetry.jsonl for the
+        // observer row).
+        const subTotal = Number(r.subagents?.total) || 0;
+        if (subTotal > 0) {
+            p.subagentsTotal += subTotal;
+            p.subagentSessions += 1;
+        }
+        if (r.cwd && (!p.latestTs || (r.ts ?? "") >= p.latestTs)) {
+            p.latestTs = r.ts;
+            p.cwd = r.cwd;
+        }
+        byProject.set(project, p);
+    }
+    const out = [];
+    for (const [project, p] of byProject) {
+        const rows = [...p.rows.values()]
+            .map((r) => ({ ...r, tool_output_share: r.tokens > 0 ? Math.round((r.tool_output_tokens / r.tokens) * 1000) / 10 : 0, est_usd: round(r.est_usd) }))
+            .sort((a, b) => b.tokens - a.tokens || a.key.localeCompare(b.key))
+            .slice(0, top);
+        const tools = [...p.tools.values()].sort((a, b) => b.output_tokens - a.output_tokens || a.tool.localeCompare(b.tool)).slice(0, top);
+        const notes = [];
+        // `subagents` and `observer` are a fixed trailer appended after the ranked slice above:
+        // --top bounds only the per-session (or per-task-class) rows, never these two summary rows.
+        if (p.subagentsTotal > 0) {
+            rows.push({ key: "subagents", task_class: "sink", sessions: p.subagentSessions, tokens: p.subagentsTotal, output: 0, tool_output_tokens: 0, tool_output_share: 0, pruned_bytes: 0, est_usd: 0 });
+        }
+        let observerTokens = 0;
+        let observerSessions = 0;
+        let observerFound = false;
+        let localTokens = 0;
+        let localSessions = 0;
+        if (p.cwd) {
+            const telFile = path.join(p.cwd, ".freeharness", "telemetry.jsonl");
+            if (fs.existsSync(telFile)) {
+                observerFound = true;
+                for (const t of readTelemetry(telFile)) {
+                    if (t.sinks?.observer) {
+                        observerTokens += Number(t.sinks.observer.tokens) || 0;
+                        observerSessions += 1;
+                    }
+                    const local = Number(t.sinks?.observer_local?.tokens) || 0;
+                    if (local > 0) {
+                        localTokens += local;
+                        localSessions += 1;
+                    }
+                }
+            }
+        }
+        if (observerFound) {
+            rows.push({ key: "observer", task_class: "sink", sessions: observerSessions, tokens: observerTokens, output: 0, tool_output_tokens: 0, tool_output_share: 0, pruned_bytes: 0, est_usd: 0 });
+        }
+        else {
+            notes.push(`observer sink unavailable for ${project} (no project telemetry file)`);
+        }
+        // The local-provider trailer row follows `observer`, additive, and only when the project's
+        // telemetry actually carries local-model tokens (a session on the Claude provider only never
+        // grows a zero row).
+        if (localTokens > 0) {
+            rows.push({ key: "observer_local", task_class: "sink", sessions: localSessions, tokens: localTokens, output: 0, tool_output_tokens: 0, tool_output_share: 0, pruned_bytes: 0, est_usd: 0 });
+        }
+        out.push({ project, rows, tools, notes });
+    }
+    out.sort((a, b) => b.rows.reduce((n, r) => n + r.tokens, 0) - a.rows.reduce((n, r) => n + r.tokens, 0) || a.project.localeCompare(b.project));
+    return { log, since: since?.toISOString(), project: filter.project, by: filter.byTaskClass ? "task-class" : "session", sessions: sessions.length, untagged, pruned_bytes: prunedTotal, byProject: out };
+}
+/** Renders the sinks report. */
+export function formatSinks(report) {
+    const lines = [];
+    const scope = [report.since ? `last ${Math.round((Date.now() - Date.parse(report.since)) / 86_400_000)} days` : "all time", report.project ? `project ${report.project}` : ""].filter(Boolean).join(", ");
+    lines.push(`cost sinks by ${report.by} (${scope}): ${report.log}`);
+    lines.push(`sessions ${report.sessions}, untagged ${report.untagged} (no Class: header in the active brief), pruned bytes recovered ${report.pruned_bytes}`);
+    if (report.sessions === 0) {
+        lines.push("no usage recorded yet (the cost-tracker hook writes on Stop / SessionEnd)");
+        return lines;
+    }
+    for (const p of report.byProject) {
+        lines.push("");
+        lines.push(`Project ${p.project}:`);
+        lines.push(`  ${"".padEnd(30)} ${"class".padEnd(12)} ${"sessions".padStart(8)} ${"tokens".padStart(9)} ${"output".padStart(9)} ${"tool-out".padStart(9)} ${"share%".padStart(7)} ${"pruned".padStart(9)} ${"est USD".padStart(9)}`);
+        for (const r of p.rows) {
+            const label = r.key === "observer_local" ? "observer (local)" : r.key;
+            lines.push(`  ${label.slice(0, 30).padEnd(30)} ${r.task_class.slice(0, 12).padEnd(12)} ${String(r.sessions).padStart(8)} ${fmtTokens(r.tokens).padStart(9)} ${fmtTokens(r.output).padStart(9)} ${fmtTokens(r.tool_output_tokens).padStart(9)} ${r.tool_output_share.toFixed(1).padStart(7)} ${String(r.pruned_bytes).padStart(9)} ${r.est_usd.toFixed(4).padStart(9)}`);
+        }
+        if (p.tools.length > 0) {
+            lines.push("  tools by output:");
+            for (const t of p.tools)
+                lines.push(`    ${t.tool.slice(0, 28).padEnd(28)} ${String(t.calls).padStart(6)} calls ${fmtTokens(t.output_tokens).padStart(9)} tokens`);
+        }
+        for (const n of p.notes)
+            lines.push(`  note: ${n}`);
+    }
+    lines.push("");
+    lines.push("tool-out = tool_result characters / 4; share% = tool-out / tokens; pruned = bytes the output pruner kept out of the context.");
+    return lines;
+}
+/**
+ * Reads `.freeharness/telemetry.jsonl`: a line that is not valid JSON or lacks
+ * `session_id` is skipped and counted on the returned array's `skipped` property; the
+ * last record per `session_id` wins (ties broken by later `ts`), matching the
+ * `latestPerSession` rule for usage.jsonl. Deduplicated records in first-seen order;
+ * empty (with `skipped: 0`) when the file is absent.
+ */
+export function readTelemetry(file) {
+    const map = new Map();
+    let skipped = 0;
+    if (fs.existsSync(file)) {
+        for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+            if (!line.trim())
+                continue;
+            let rec;
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed && typeof parsed === "object" && typeof parsed.session_id === "string" && parsed.session_id)
+                    rec = parsed;
+            }
+            catch {
+                // skip: counted below
+            }
+            if (!rec) {
+                skipped += 1;
+                continue;
+            }
+            const prev = map.get(rec.session_id);
+            if (!prev || (rec.ts ?? "") >= (prev.ts ?? ""))
+                map.set(rec.session_id, rec);
+        }
+    }
+    const out = [...map.values()];
+    out.skipped = skipped;
+    return out;
+}
+/** Median (average of the two middle values when even), rounded to 6 decimals; 0 when empty. */
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? round((sorted[mid - 1] + sorted[mid]) / 2) : sorted[mid];
+}
+/**
+ * Groups telemetry records by their tagged `change` (records with no `change` fall
+ * into `untagged`): session count, median and total main/subagent tokens, summed
+ * observer tokens, summed est USD, and the tier mix (`standard 2, fast 1`, tiers with
+ * no session omitted). One row per change, ranked by total main tokens descending.
+ */
+export function changes(records) {
+    const groups = new Map();
+    for (const r of records) {
+        const key = r.change && r.change.trim() ? r.change.trim() : "untagged";
+        const arr = groups.get(key) ?? [];
+        arr.push(r);
+        groups.set(key, arr);
+    }
+    const rows = [];
+    for (const [change, recs] of groups) {
+        const mains = recs.map((r) => Number(r.sinks?.main?.total) || 0);
+        const subs = recs.map((r) => Number(r.sinks?.subagents?.total) || 0);
+        const totalObserver = recs.reduce((n, r) => n + (Number(r.sinks?.observer?.tokens) || 0), 0);
+        const est_usd = round(recs.reduce((n, r) => n + (Number(r.est_usd) || 0), 0));
+        const tierCounts = new Map();
+        for (const r of recs) {
+            if (!r.tier)
+                continue;
+            tierCounts.set(r.tier, (tierCounts.get(r.tier) ?? 0) + 1);
+        }
+        const tierMix = [...tierCounts.entries()]
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+            .map(([tier, n]) => `${tier} ${n}`)
+            .join(", ");
+        rows.push({
+            change,
+            sessions: recs.length,
+            medianMain: median(mains),
+            totalMain: mains.reduce((a, b) => a + b, 0),
+            medianSubagents: median(subs),
+            totalSubagents: subs.reduce((a, b) => a + b, 0),
+            totalObserver,
+            est_usd,
+            tierMix,
+        });
+    }
+    return rows.sort((a, b) => b.totalMain - a.totalMain || a.change.localeCompare(b.change));
+}
+/** Renders the `--changes` report; `skipped` counts lines `readTelemetry` dropped (malformed or without `session_id`). */
+export function formatChanges(rows, file, skipped) {
+    const lines = [];
+    lines.push(`cost report --changes: ${file}${skipped > 0 ? ` (${skipped} lines skipped)` : ""}`);
+    if (rows.length === 0) {
+        lines.push("no sessions recorded yet");
+        return lines;
+    }
+    lines.push(`  ${"change".padEnd(24)} ${"sessions".padStart(8)} ${"median main".padStart(12)} ${"total main".padStart(11)} ${"median sub".padStart(11)} ${"total sub".padStart(10)} ${"observer".padStart(9)} ${"est USD".padStart(9)}  tier mix`);
+    for (const r of rows) {
+        lines.push(`  ${r.change.slice(0, 24).padEnd(24)} ${String(r.sessions).padStart(8)} ${fmtTokens(r.medianMain).padStart(12)} ${fmtTokens(r.totalMain).padStart(11)} ${fmtTokens(r.medianSubagents).padStart(11)} ${fmtTokens(r.totalSubagents).padStart(10)} ${fmtTokens(r.totalObserver).padStart(9)} ${r.est_usd.toFixed(4).padStart(9)}  ${r.tierMix || "-"}`);
+    }
+    return lines;
+}
+/**
+ * Loads the price table for `agents()`'s USD estimate; a missing or malformed file
+ * yields an empty table so the estimate degrades to 0 instead of throwing.
+ * Mirrors `loadPrices` in canonical/hooks/freeharness-cost-tracker.mjs; kept as a
+ * separate copy since the hook is a standalone, dependency-free .mjs the CLI does not
+ * import from. Returns model name -> price row (per MTok).
+ */
+export function loadPriceTable(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed.prices === "object" && parsed.prices ? parsed.prices : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The price row for a model: exact key, then the longest key the model name starts
+ * with, then `default`. Mirrors `priceFor` in canonical/hooks/freeharness-cost-tracker.mjs
+ * (same separate-copy rationale as `loadPriceTable`). Undefined when no row matches.
+ */
+function priceRowFor(prices, model) {
+    if (prices[model])
+        return prices[model];
+    let best;
+    for (const key of Object.keys(prices)) {
+        if (key !== "default" && model.startsWith(key) && (!best || key.length > best.length))
+            best = key;
+    }
+    return best ? prices[best] : prices.default;
+}
+/**
+ * Ranks subagent dispatches by total tokens from each session's last `by_agent`
+ * snapshot: per agent name, the model with the most tokens (ties broken by name,
+ * mirroring the hook's `mergeAgentUsage`), `dispatches` and `messages` each summed
+ * across sessions from their own fields (an entry from before per-transcript merging
+ * carries no `dispatches` and counts as 1), tokens per bucket summed across sessions,
+ * and an est USD from the price table. Rows ranked by total tokens descending.
+ */
+export function agents(records, prices = loadPriceTable(costPricesPath())) {
+    const sessions = latestPerSession(records);
+    const byName = new Map();
+    for (const r of sessions) {
+        for (const [name, a] of Object.entries(r.by_agent ?? {})) {
+            const row = byName.get(name) ?? { model: a.model, bestTotal: -1, dispatches: 0, messages: 0, input: 0, output: 0, cache_read: 0, cache_write: 0 };
+            row.dispatches += Number(a.dispatches) || 1;
+            row.messages += Number(a.messages) || 0;
+            row.input += Number(a.usage.input) || 0;
+            row.output += Number(a.usage.output) || 0;
+            row.cache_read += Number(a.usage.cache_read) || 0;
+            row.cache_write += Number(a.usage.cache_write) || 0;
+            const total = Number(a.usage.total) || 0;
+            if (total > row.bestTotal || (total === row.bestTotal && a.model.localeCompare(row.model) < 0)) {
+                row.bestTotal = total;
+                row.model = a.model;
+            }
+            byName.set(name, row);
+        }
+    }
+    const rows = [];
+    for (const [name, r] of byName) {
+        const tokens = r.input + r.output + r.cache_read + r.cache_write;
+        const price = priceRowFor(prices, r.model);
+        const per = (n, p) => (n * (Number(p) || 0)) / 1e6;
+        const est_usd = price ? per(r.input, price.input) + per(r.output, price.output) + per(r.cache_read, price.cache_read) + per(r.cache_write, price.cache_write) : 0;
+        rows.push({ name, model: r.model, dispatches: r.dispatches, messages: r.messages, input: r.input, output: r.output, cache_read: r.cache_read, cache_write: r.cache_write, tokens, est_usd: round(est_usd) });
+    }
+    return rows.sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name));
+}
+/** Renders the `--agents` report; `priceTable.loaded: false` prints a notice, `true` (or omitted) prints none. */
+export function formatAgents(rows, priceTable = { file: costPricesPath(), loaded: true }) {
+    const lines = [];
+    lines.push("cost report --agents (ranked by total tokens):");
+    if (!priceTable.loaded)
+        lines.push(`price table not loaded (${priceTable.file}): est USD shown as 0.00`);
+    lines.push(`  ${"agent".padEnd(30)} ${"model".padEnd(24)} ${"dispatch".padStart(8)} ${"messages".padStart(8)} ${"tokens".padStart(9)} ${"est USD".padStart(9)}`);
+    for (const r of rows) {
+        lines.push(`  ${r.name.slice(0, 30).padEnd(30)} ${r.model.slice(0, 24).padEnd(24)} ${String(r.dispatches).padStart(8)} ${String(r.messages).padStart(8)} ${fmtTokens(r.tokens).padStart(9)} ${r.est_usd.toFixed(4).padStart(9)}`);
+    }
+    return lines;
+}
+/** Per-project telemetry file path: `<dir>/.freeharness/telemetry.jsonl` (may not exist yet); `dir` defaults to the current working directory. */
+export function telemetryPath(dir = process.cwd()) {
+    return path.join(path.resolve(dir), ".freeharness", "telemetry.jsonl");
+}