@unpolarize/code-sessions 0.1.0

package/src/adapters/codex.ts

@@ -0,0 +1,228 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  SCHEMA_VERSIONS,
+  type ClaudeSessionMeta,
+  type ToolCall,
+  type Turn,
+} from '@unpolarize/code-sessions-schema';
+import { readEntries } from '../store/scan';
+import type { ImportedSession } from './import';
+
+/**
+ * Codex CLI adapter. Codex stores rollouts at
+ * ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl — a header/meta line
+ * plus event lines. The exact event schema has shifted across codex releases,
+ * so this parser is intentionally defensive: it extracts user/assistant
+ * messages + function (tool) calls from several known shapes and ignores the
+ * rest. Validated against fixtures; confirm against your real rollouts after
+ * `codex login`.
+ */
+
+const UUID_RE = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i;
+
+export function codexSessionsRoot(): string {
+  return join(homedir(), '.codex', 'sessions');
+}
+
+export interface CodexSessionInfo {
+  sessionId: string;
+  path: string;
+}
+
+export function discoverCodexSessions(root = codexSessionsRoot()): CodexSessionInfo[] {
+  if (!existsSync(root)) return [];
+  const out: CodexSessionInfo[] = [];
+  const walk = (dir: string, depth: number): void => {
+    if (depth > 6) return;
+    for (const e of readEntries(dir)) {
+      const name = String(e.name);
+      const full = join(dir, name);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (e.isFile() && name.endsWith('.jsonl')) {
+        const m = UUID_RE.exec(name);
+        out.push({ sessionId: m ? m[1]! : name.replace(/\.jsonl$/, ''), path: full });
+      }
+    }
+  };
+  walk(root, 0);
+  return out;
+}
+
+function textFromContent(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((b) => {
+        if (typeof b === 'string') return b;
+        if (b && typeof b === 'object') {
+          const o = b as any;
+          if (typeof o.text === 'string') return o.text;
+        }
+        return '';
+      })
+      .filter(Boolean)
+      .join('\n');
+  }
+  if (content && typeof content === 'object' && typeof (content as any).text === 'string') {
+    return (content as any).text;
+  }
+  return '';
+}
+
+interface NormalizedCodex {
+  role: Turn['role'];
+  text: string;
+  tool_calls: ToolCall[];
+}
+
+/**
+ * Normalize one codex event line. Codex (0.14x) emits the conversation as
+ * `event_msg/{user_message,agent_message}` (payload.message is a string) and
+ * tool calls as `response_item/function_call`. `response_item/message` carries
+ * developer/permission scaffolding + reasoning, which we skip to avoid noise.
+ */
+function normalizeCodexLine(ev: any): NormalizedCodex | null {
+  const p = ev?.payload && typeof ev.payload === 'object' ? ev.payload : ev;
+  const ptype = p?.type;
+
+  // primary conversation channel
+  if (ev?.type === 'event_msg') {
+    if (ptype === 'user_message' && typeof p.message === 'string') {
+      return { role: 'user', text: p.message, tool_calls: [] };
+    }
+    if (ptype === 'agent_message' && typeof p.message === 'string') {
+      return { role: 'assistant', text: p.message, tool_calls: [] };
+    }
+    return null; // task_started/complete/token_count/etc handled elsewhere
+  }
+
+  // tool calls live on response_item
+  if (ev?.type === 'response_item') {
+    if (ptype === 'function_call' || ptype === 'local_shell_call' || ptype === 'tool_call') {
+      const name = typeof p.name === 'string' ? p.name : ptype === 'local_shell_call' ? 'shell' : 'tool';
+      let input: unknown = p.arguments ?? p.input ?? p.action;
+      if (typeof input === 'string') {
+        try {
+          input = JSON.parse(input);
+        } catch {
+          /* keep string */
+        }
+      }
+      return { role: 'assistant', text: '', tool_calls: [{ name, input }] };
+    }
+    if (ptype === 'function_call_output' || ptype === 'tool_result') {
+      return { role: 'tool', text: textFromContent(p.output ?? p.content), tool_calls: [] };
+    }
+    // message / reasoning: scaffolding — skip
+    return null;
+  }
+  return null;
+}
+
+interface CodexUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+}
+
+function readTokenCount(ev: any): CodexUsage | null {
+  if (ev?.type !== 'event_msg' || ev?.payload?.type !== 'token_count') return null;
+  const u = ev.payload.info?.total_token_usage ?? ev.payload.info;
+  if (!u || typeof u !== 'object') return null;
+  return {
+    input_tokens: Number(u.input_tokens) || 0,
+    output_tokens: Number(u.output_tokens) || 0,
+    cache_read_tokens: Number(u.cached_input_tokens ?? u.cache_read_tokens) || 0,
+  };
+}
+
+function lineTs(ev: any, fallback: string): string {
+  const t = ev?.timestamp ?? ev?.ts;
+  if (typeof t === 'string' && !Number.isNaN(Date.parse(t))) return t;
+  return fallback;
+}
+
+export function parseCodexSession(info: CodexSessionInfo, host: string): ImportedSession | null {
+  const lines = readFileSync(info.path, 'utf8').split('\n').filter((l) => l.trim().length > 0);
+  if (lines.length === 0) return null;
+
+  let model: string | undefined;
+  let cwd: string | undefined;
+  let sessionId = info.sessionId;
+  let baseTs = '2020-01-01T00:00:00Z';
+  let latestUsage: CodexUsage | null = null;
+  let lastAssistantIdx = -1;
+
+  const turns: Turn[] = [];
+  let idx = 0;
+  for (const line of lines) {
+    let ev: any;
+    try {
+      ev = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    // session_meta: metadata lives under payload (id, cwd, model, timestamp)
+    if (ev?.type === 'session_meta') {
+      const src = ev.payload && typeof ev.payload === 'object' ? ev.payload : ev;
+      if (typeof src.model === 'string') model = src.model;
+      if (typeof src.cwd === 'string') cwd = src.cwd;
+      if (typeof src.id === 'string') sessionId = UUID_RE.exec(src.id)?.[1] ?? sessionId;
+      const t = src.timestamp ?? ev.timestamp;
+      if (typeof t === 'string' && !Number.isNaN(Date.parse(t))) baseTs = t;
+      continue;
+    }
+    if (ev?.type === 'turn_context' && typeof ev.payload?.cwd === 'string' && !cwd) {
+      cwd = ev.payload.cwd;
+    }
+
+    const usage = readTokenCount(ev);
+    if (usage) {
+      latestUsage = usage; // cumulative; latest wins
+      continue;
+    }
+
+    const norm = normalizeCodexLine(ev);
+    if (!norm) continue;
+    const ts = lineTs(ev, new Date(Date.parse(baseTs) + idx * 1000).toISOString());
+    if (norm.role === 'assistant') lastAssistantIdx = turns.length;
+    turns.push({
+      schema: SCHEMA_VERSIONS.turn,
+      session_id: sessionId,
+      host,
+      agent: 'codex',
+      turn_index: idx++,
+      ts,
+      role: norm.role,
+      text: norm.text,
+      tool_calls: norm.tool_calls,
+      usage: { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0 },
+      scrubbed: false,
+      raw_ref: null,
+    });
+  }
+
+  if (turns.length === 0) return null;
+
+  // Codex reports cumulative usage via token_count; attribute it to the final
+  // assistant turn so the session envelope totals are non-zero.
+  if (latestUsage && lastAssistantIdx >= 0) {
+    turns[lastAssistantIdx]!.usage = {
+      input_tokens: latestUsage.input_tokens,
+      output_tokens: latestUsage.output_tokens,
+      cache_read_tokens: latestUsage.cache_read_tokens,
+      cache_write_tokens: 0,
+    };
+  }
+  const meta: ClaudeSessionMeta = {
+    session_id: sessionId,
+    started_at: turns[0]!.ts,
+    ended_at: turns[turns.length - 1]!.ts,
+  };
+  if (model) meta.model = model;
+  if (cwd) meta.project_path = cwd;
+  return { host, sessionId, agent: 'codex', turns, meta };
+}

package/src/adapters/grok.ts

@@ -0,0 +1,179 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  SCHEMA_VERSIONS,
+  type ClaudeSessionMeta,
+  type ToolCall,
+  type Turn,
+} from '@unpolarize/code-sessions-schema';
+import type { ImportedSession } from './import';
+
+/**
+ * Grok Build CLI adapter. Grok stores each session as a directory under
+ * ~/.grok/sessions/<url-encoded-cwd>/<uuid>/ with chat_history.jsonl (event
+ * stream) + summary.json (metadata). Events carry no per-event timestamp, so
+ * we synthesize them from summary.created_at + line ordinal (ordering only).
+ */
+
+export function grokSessionsRoot(): string {
+  return join(homedir(), '.grok', 'sessions');
+}
+
+export interface GrokSessionInfo {
+  sessionId: string;
+  chatPath: string;
+  summaryPath: string;
+  cwd: string;
+}
+
+function safeDirs(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+export function discoverGrokSessions(root = grokSessionsRoot()): GrokSessionInfo[] {
+  if (!existsSync(root)) return [];
+  const out: GrokSessionInfo[] = [];
+  for (const enc of safeDirs(root)) {
+    let cwd = enc;
+    try {
+      cwd = decodeURIComponent(enc);
+    } catch {
+      /* keep raw */
+    }
+    for (const uuid of safeDirs(join(root, enc))) {
+      const dir = join(root, enc, uuid);
+      const chatPath = join(dir, 'chat_history.jsonl');
+      const summaryPath = join(dir, 'summary.json');
+      if (existsSync(chatPath)) out.push({ sessionId: uuid, chatPath, summaryPath, cwd });
+    }
+  }
+  return out;
+}
+
+function extractText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((b) => (typeof b === 'string' ? b : b && typeof b === 'object' && (b as any).type === 'text' ? String((b as any).text ?? '') : ''))
+      .filter(Boolean)
+      .join('\n\n');
+  }
+  return '';
+}
+
+function parseArgs(s: unknown): unknown {
+  if (typeof s !== 'string') return s;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+}
+
+interface GrokSummary {
+  created_at?: string;
+  updated_at?: string;
+  last_active_at?: string;
+  generated_title?: string;
+  session_summary?: string;
+  current_model_id?: string;
+  session_kind?: string;
+  info?: { cwd?: string };
+}
+
+/** Parse one grok session into a canonical ImportedSession (or null to skip). */
+export function parseGrokSession(info: GrokSessionInfo, host: string): ImportedSession | null {
+  let summary: GrokSummary = {};
+  if (existsSync(info.summaryPath)) {
+    try {
+      summary = JSON.parse(readFileSync(info.summaryPath, 'utf8')) as GrokSummary;
+    } catch {
+      /* defaults */
+    }
+  }
+  if (summary.session_kind === 'claude_import') return null; // claude indexer is authoritative
+
+  const baseMs = Date.parse(summary.created_at ?? '') || statMtime(info.chatPath);
+  const lines = readFileSync(info.chatPath, 'utf8').split('\n').filter((l) => l.trim().length > 0);
+
+  const turns: Turn[] = [];
+  let idx = 0;
+  let model = summary.current_model_id;
+  for (const line of lines) {
+    let ev: any;
+    try {
+      ev = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const ts = new Date(baseMs + idx * 1000).toISOString();
+    if (ev.type === 'user') {
+      turns.push(mkTurn(info.sessionId, host, idx++, ts, 'user', extractText(ev.content), []));
+    } else if (ev.type === 'assistant') {
+      if (typeof ev.model_id === 'string') model = ev.model_id;
+      const tools: ToolCall[] = Array.isArray(ev.tool_calls)
+        ? ev.tool_calls
+            .filter((t: any) => t && typeof t.name === 'string')
+            .map((t: any) => ({ name: t.name, input: parseArgs(t.arguments), ...(t.id ? { id: t.id } : {}) }))
+        : [];
+      turns.push(mkTurn(info.sessionId, host, idx++, ts, 'assistant', extractText(ev.content), tools));
+    } else if (ev.type === 'tool_result') {
+      turns.push(mkTurn(info.sessionId, host, idx++, ts, 'tool', extractText(ev.content), []));
+    }
+    // system / reasoning: skipped
+  }
+
+  if (turns.length === 0) return null;
+
+  const startedAt = new Date(baseMs).toISOString();
+  const endedAt = turns[turns.length - 1]!.ts;
+  const meta: ClaudeSessionMeta = {
+    session_id: info.sessionId,
+    project_path: summary.info?.cwd ?? info.cwd,
+    started_at: startedAt,
+    ended_at: endedAt,
+  };
+  if (model) meta.model = model;
+  const title = summary.generated_title?.trim() || summary.session_summary?.trim();
+  if (title) meta.title = title;
+
+  return { host, sessionId: info.sessionId, agent: 'grok', turns, meta };
+}
+
+function statMtime(p: string): number {
+  try {
+    return statSync(p).mtimeMs;
+  } catch {
+    return Date.parse('2020-01-01T00:00:00Z');
+  }
+}
+
+function mkTurn(
+  sessionId: string,
+  host: string,
+  index: number,
+  ts: string,
+  role: Turn['role'],
+  text: string,
+  tool_calls: ToolCall[],
+): Turn {
+  return {
+    schema: SCHEMA_VERSIONS.turn,
+    session_id: sessionId,
+    host,
+    agent: 'grok',
+    turn_index: index,
+    ts,
+    role,
+    text,
+    tool_calls,
+    usage: { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0 },
+    scrubbed: false,
+    raw_ref: null,
+  };
+}

package/src/adapters/import.ts

@@ -0,0 +1,79 @@
+import type {
+  AgentKind,
+  ClaudeSessionMeta,
+  SessionEnvelope,
+  Turn,
+} from '@unpolarize/code-sessions-schema';
+import type { CodeSessionsConfig } from '../config';
+import { applyHygiene } from '../hygiene';
+import { monthOf, sessionDir } from '../store/paths';
+import { computeEnvelope, writeBlobFile, writeTurnFile } from '../store/writer';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { envelopeFile } from '../store/paths';
+
+const NATIVE_FORMAT: Record<string, string> = {
+  'claude-code': 'claude-jsonl',
+  grok: 'grok-jsonl',
+  codex: 'codex-rollout',
+  unknown: 'unknown',
+};
+
+export interface ImportedSession {
+  host: string;
+  sessionId: string;
+  agent: AgentKind;
+  turns: Turn[];
+  meta: ClaudeSessionMeta;
+}
+
+export interface ImportResult {
+  sessionId: string;
+  sessionDir: string;
+  turns: number;
+  envelope: SessionEnvelope;
+}
+
+function writeJsonAtomic(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+/**
+ * Persist an imported (non-claude) session into the store: hygiene each turn,
+ * write immutable per-turn files, derive + write the envelope. Reuses the same
+ * writer the live claude capture path uses, so all agents land in one store.
+ */
+export function writeImportedSession(cfg: CodeSessionsConfig, s: ImportedSession): ImportResult {
+  const month = monthOf(s.meta.started_at ?? s.turns[0]?.ts);
+  const dir = sessionDir(cfg.storeDir, s.host, month, s.sessionId);
+
+  for (const turn of s.turns) {
+    const hy = applyHygiene(turn, cfg.hygiene);
+    if (hy.blob) writeBlobFile(dir, hy.blob.sha, hy.blob.content);
+    writeTurnFile(dir, hy.turn);
+  }
+
+  const env = computeEnvelope(s.turns, s.meta, {
+    session_id: s.sessionId,
+    host: s.host,
+    agent: s.agent,
+    native_uuid: s.sessionId,
+  });
+  env.native_ref.format = NATIVE_FORMAT[s.agent] ?? 'unknown';
+  // preserve labels if a prior envelope exists
+  const envPath = envelopeFile(dir);
+  if (existsSync(envPath)) {
+    try {
+      const prev = JSON.parse(readFileSync(envPath, 'utf8')) as SessionEnvelope;
+      if (prev.labels?.length) env.labels = prev.labels;
+    } catch {
+      /* ignore */
+    }
+  }
+  writeJsonAtomic(envPath, env);
+
+  return { sessionId: s.sessionId, sessionDir: dir, turns: s.turns.length, envelope: env };
+}

package/src/adapters/index.ts

@@ -0,0 +1,3 @@
+export * from './import';
+export * from './grok';
+export * from './codex';

package/src/analytics/analytics.test.ts

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import type { Turn } from '@unpolarize/code-sessions-schema';
+import { FakeProvider } from '../insights/provider';
+import { labelSession } from '../insights/labeler';
+import { sessionDir } from '../store/paths';
+import { rebuildEnvelope, writeTurnFile } from '../store/writer';
+import { makeConfig, withTempDirAsync } from '../test/tmp';
+import { cmdAnalytics } from './command';
+import { renderDigest } from './digest';
+import { computeReport } from './rollup';
+import { renderSite } from './site';
+
+function turn(i: number, over: Partial<Turn> = {}): Turn {
+  return {
+    schema: 'session-store/turn@1',
+    session_id: 's',
+    host: 'h',
+    agent: 'claude-code',
+    turn_index: i,
+    ts: `2026-06-20T08:0${i}:00Z`,
+    role: 'assistant',
+    text: '',
+    tool_calls: [],
+    usage: { input_tokens: 100, output_tokens: 10, cache_read_tokens: 0, cache_write_tokens: 0 },
+    scrubbed: false,
+    raw_ref: null,
+    ...over,
+  };
+}
+
+async function seed(store: string, sessionId: string): Promise<void> {
+  const dir = sessionDir(store, 'h', '2026-06', sessionId);
+  writeTurnFile(dir, turn(0, { role: 'user', text: 'Fix the bug in foo.ts' }));
+  writeTurnFile(dir, turn(1, { tool_calls: [{ name: 'Edit' }], telemetry: { cost_usd: 0.9 } }));
+  rebuildEnvelope(store, 'h', '2026-06', sessionId, { model: 'claude-opus-4-8' }, {
+    session_id: sessionId,
+    host: 'h',
+    agent: 'claude-code',
+    native_uuid: sessionId,
+  });
+  await labelSession(dir, { sessionId, host: 'h' }, new FakeProvider(), { now: '2026-06-20T09:00:00Z' });
+}
+
+describe('computeReport', () => {
+  it('aggregates totals, tags, signals, and similar sessions', async () => {
+    await withTempDirAsync(async (store) => {
+      await seed(store, 's1');
+      await seed(store, 's2');
+      const report = computeReport(store, '2026-06-20T10:00:00Z');
+      expect(report.sessions).toBe(2);
+      expect(report.hosts.h).toBe(2);
+      expect(report.totals.input_tokens).toBe(400);
+      expect(report.topTags.find((t) => t.tag === 'Edit')?.count).toBe(2);
+      expect(report.signalCounts['high-cost-turn']).toBe(2);
+      // both sessions share the 'Edit' tag -> similar
+      const sim = report.similar.find((s) => s.tag === 'Edit');
+      expect(sim?.sessions.sort()).toEqual(['s1', 's2']);
+      expect(report.byMonth['2026-06']?.sessions).toBe(2);
+    });
+  });
+});
+
+describe('renderDigest / renderSite', () => {
+  it('produces markdown + html from a report', async () => {
+    await withTempDirAsync(async (store) => {
+      await seed(store, 's1');
+      const report = computeReport(store, '2026-06-20T10:00:00Z');
+      const md = renderDigest(report);
+      expect(md).toContain('# Session digest');
+      expect(md).toContain('Estimated cost');
+      const html = renderSite(report);
+      expect(html).toContain('<!doctype html>');
+      expect(html).toContain('code-sessions');
+    });
+  });
+});
+
+describe('cmdAnalytics', () => {
+  it('writes report.json, digest.md, and index.html into the store', async () => {
+    await withTempDirAsync(async (store) => {
+      await seed(store, 's1');
+      const res = await cmdAnalytics(makeConfig(store), { now: '2026-06-20T10:00:00Z' });
+      expect(res.code).toBe(0);
+      const dir = join(store, 'analytics');
+      expect(existsSync(join(dir, 'report.json'))).toBe(true);
+      expect(existsSync(join(dir, 'digest.md'))).toBe(true);
+      expect(existsSync(join(dir, 'index.html'))).toBe(true);
+      const report = JSON.parse(readFileSync(join(dir, 'report.json'), 'utf8'));
+      expect(report.sessions).toBe(1);
+    });
+  });
+});

package/src/analytics/command.ts

@@ -0,0 +1,38 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { CodeSessionsConfig } from '../config';
+import type { CommandResult } from '../commands';
+import { GitStore } from '../store/git';
+import { renderDigest } from './digest';
+import { computeReport } from './rollup';
+import { renderSite } from './site';
+
+export interface AnalyticsOptions {
+  now?: string;
+}
+
+/** Compute MVP-2 rollups and write report.json + digest.md + index.html under analytics/. */
+export async function cmdAnalytics(
+  cfg: CodeSessionsConfig,
+  opts: AnalyticsOptions = {},
+): Promise<CommandResult> {
+  const now = opts.now ?? new Date().toISOString();
+  const report = computeReport(cfg.storeDir, now);
+
+  const dir = join(cfg.storeDir, 'analytics');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'report.json'), `${JSON.stringify(report, null, 2)}\n`);
+  writeFileSync(join(dir, 'digest.md'), renderDigest(report));
+  writeFileSync(join(dir, 'index.html'), renderSite(report));
+
+  const git = new GitStore(cfg.storeDir, {
+    ...(cfg.git.remote ? { remote: cfg.git.remote } : {}),
+    autoPush: cfg.git.autoPush,
+  });
+  if (git.isRepo()) git.sync(`analytics rollup (${report.sessions} sessions)`);
+
+  return {
+    code: 0,
+    output: `Analytics written for ${report.sessions} session(s) → ${dir}`,
+  };
+}

package/src/analytics/digest.ts

@@ -0,0 +1,48 @@
+import type { AnalyticsReport } from './rollup';
+
+/** Render a human-readable Markdown digest from an analytics report. */
+export function renderDigest(report: AnalyticsReport): string {
+  const lines: string[] = [];
+  lines.push('# Session digest');
+  lines.push('');
+  lines.push(`_Generated ${report.generated_at}_`);
+  lines.push('');
+  lines.push(`- **Sessions:** ${report.sessions}`);
+  lines.push(
+    `- **Tokens:** ${report.totals.input_tokens.toLocaleString()} in / ${report.totals.output_tokens.toLocaleString()} out`,
+  );
+  lines.push(`- **Estimated cost:** $${report.totals.cost_usd.toFixed(2)}`);
+  lines.push(`- **Hosts:** ${Object.entries(report.hosts).map(([h, n]) => `${h} (${n})`).join(', ') || '—'}`);
+  lines.push('');
+
+  if (report.topTopics.length) {
+    lines.push('## Top topics');
+    for (const t of report.topTopics) lines.push(`- ${t.topic} — ${t.count}`);
+    lines.push('');
+  }
+  if (report.topTags.length) {
+    lines.push('## Top tags');
+    lines.push(report.topTags.map((t) => `\`${t.tag}\` (${t.count})`).join(' · '));
+    lines.push('');
+  }
+  if (Object.keys(report.signalCounts).length) {
+    lines.push('## Signals');
+    for (const [kind, count] of Object.entries(report.signalCounts).sort((a, b) => b[1] - a[1])) {
+      lines.push(`- ${kind}: ${count}`);
+    }
+    lines.push('');
+  }
+  if (report.similar.length) {
+    lines.push('## Related sessions (shared tags)');
+    for (const s of report.similar) lines.push(`- \`${s.tag}\`: ${s.sessions.length} sessions`);
+    lines.push('');
+  }
+  if (Object.keys(report.byMonth).length) {
+    lines.push('## By month');
+    for (const [month, m] of Object.entries(report.byMonth).sort()) {
+      lines.push(`- ${month}: ${m.sessions} sessions, $${m.cost_usd.toFixed(2)}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}