@unpolarize/code-sessions 0.1.0

package/src/index_store/db.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import type { Insights, SessionEnvelope, Turn } from '@unpolarize/code-sessions-schema';
+import { SessionIndex } from './db';
+
+function env(id: string, agent: SessionEnvelope['agent'], over: Partial<SessionEnvelope> = {}): SessionEnvelope {
+  return {
+    schema: 'session-store/session@1',
+    session_id: id,
+    host: 'h',
+    agent,
+    project_path: '/p',
+    model: 'claude-opus-4-8',
+    started_at: '2026-06-20T08:00:00Z',
+    ended_at: '2026-06-20T08:05:00Z',
+    turn_count: 2,
+    tool_call_count: 1,
+    totals: { input_tokens: 100, output_tokens: 20, cost_usd: 0.5 },
+    title: `session ${id}`,
+    labels: ['debugging'],
+    native_ref: { format: 'claude-jsonl', uuid: id },
+    ...over,
+  };
+}
+
+function turn(sid: string, i: number, role: Turn['role'], text: string): Turn {
+  return {
+    schema: 'session-store/turn@1',
+    session_id: sid,
+    host: 'h',
+    agent: 'claude-code',
+    turn_index: i,
+    ts: `2026-06-20T08:0${i}:00Z`,
+    role,
+    text,
+    tool_calls: role === 'assistant' ? [{ name: 'Edit' }] : [],
+    usage: { input_tokens: 50, output_tokens: 10, cache_read_tokens: 0, cache_write_tokens: 0 },
+    scrubbed: false,
+    raw_ref: null,
+  };
+}
+
+const src = { source_path: '/s/x.json', mtime_ms: 1000, size_bytes: 200, indexed_at: 1 };
+
+describe('SessionIndex', () => {
+  it('upserts sessions/turns/insights and queries them', () => {
+    const idx = new SessionIndex(':memory:');
+    try {
+      idx.upsertSession(env('s1', 'claude-code'), { ...src, topic: 'fixing a bug' });
+      idx.replaceTurns('s1', [turn('s1', 0, 'user', 'fix the parser bug'), turn('s1', 1, 'assistant', 'done')]);
+      idx.upsertInsight({
+        schema: 'session-store/insights@1',
+        session_id: 's1',
+        host: 'h',
+        generated_at: 't',
+        provider: 'fake',
+        topic: 'fixing a bug',
+        tags: ['Edit'],
+        signals: [{ kind: 'high-cost-turn', severity: 'warn' }],
+      } as Insights);
+
+      const got = idx.getSession('s1')!;
+      expect(got.agent).toBe('claude-code');
+      expect(got.input_tokens).toBe(100);
+      expect(got.labels).toEqual(['debugging']);
+      expect(got.topic).toBe('fixing a bug');
+
+      expect(idx.listRecent(10)).toHaveLength(1);
+      expect(idx.searchTurns('parser')).toHaveLength(1);
+      expect(idx.searchTurns('nonexistent')).toHaveLength(0);
+
+      const s = idx.stats();
+      expect(s.sessions).toBe(1);
+      expect(s.turns).toBe(2);
+      expect(s.byAgent['claude-code']).toBe(1);
+    } finally {
+      idx.close();
+    }
+  });
+
+  it('is idempotent on re-upsert and supports incremental invalidation keys', () => {
+    const idx = new SessionIndex(':memory:');
+    try {
+      idx.upsertSession(env('s1', 'grok'), src);
+      idx.upsertSession(env('s1', 'grok', { title: 'updated' }), { ...src, mtime_ms: 2000 });
+      expect(idx.listRecent(10)).toHaveLength(1);
+      expect(idx.getSession('s1')!.title).toBe('updated');
+      const known = idx.knownSources();
+      expect(known.get('s1')!.mtime_ms).toBe(2000);
+    } finally {
+      idx.close();
+    }
+  });
+
+  it('filters by agent and deletes sessions (cascade turns)', () => {
+    const idx = new SessionIndex(':memory:');
+    try {
+      idx.upsertSession(env('c1', 'claude-code'), src);
+      idx.upsertSession(env('g1', 'grok'), { ...src, source_path: '/s/g.json' });
+      idx.replaceTurns('c1', [turn('c1', 0, 'user', 'hi')]);
+      expect(idx.listRecent(10, 'grok')).toHaveLength(1);
+      idx.deleteSessions(['c1']);
+      expect(idx.getSession('c1')).toBeUndefined();
+      expect(idx.stats().turns).toBe(0); // cascade removed c1's turn
+    } finally {
+      idx.close();
+    }
+  });
+});

package/src/index_store/db.ts

@@ -0,0 +1,289 @@
+import { mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import type { DatabaseSync as DatabaseSyncT } from 'node:sqlite';
+import type { Insights, SessionEnvelope, Turn } from '@unpolarize/code-sessions-schema';
+
+// Load node:sqlite at runtime via createRequire so the bundler never rewrites
+// the `node:` specifier (esbuild doesn't yet know `node:sqlite` is a builtin and
+// would strip the prefix to a bare `sqlite` package). Types come from the
+// type-only import above.
+const nodeRequire = createRequire(import.meta.url);
+const { DatabaseSync } = nodeRequire('node:sqlite') as {
+  DatabaseSync: new (path: string) => DatabaseSyncT;
+};
+
+/**
+ * Internal SQLite index for the CS library — a queryable projection of the git
+ * `sessions` store. Built on node:sqlite (Node's built-in, zero native deps).
+ * This is a CACHE, rebuildable from the store at any time; the git files remain
+ * the source of truth. Mirrors the shape CS-vscode's cache uses so a consumer
+ * can share the model.
+ */
+
+const SCHEMA_VERSION = 1;
+
+export interface SessionIndexRow {
+  session_id: string;
+  host: string;
+  agent: string;
+  project_path: string;
+  model: string | null;
+  started_at: number | null;
+  ended_at: number | null;
+  turn_count: number;
+  tool_call_count: number;
+  input_tokens: number;
+  output_tokens: number;
+  cost_usd: number;
+  title: string | null;
+  labels: string[];
+  topic: string | null;
+  source_path: string;
+}
+
+function toMs(iso: string | undefined): number | null {
+  if (!iso) return null;
+  const v = Date.parse(iso);
+  return Number.isNaN(v) ? null : v;
+}
+
+export class SessionIndex {
+  readonly db: DatabaseSyncT;
+
+  constructor(path: string) {
+    if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
+    this.db = new DatabaseSync(path);
+    this.db.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;');
+    this.migrate();
+  }
+
+  private migrate(): void {
+    const row = this.db.prepare('PRAGMA user_version').get() as { user_version: number };
+    if ((row?.user_version ?? 0) < 1) {
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS session (
+          session_id TEXT PRIMARY KEY,
+          host TEXT NOT NULL,
+          agent TEXT NOT NULL,
+          project_path TEXT NOT NULL DEFAULT '',
+          model TEXT,
+          started_at INTEGER,
+          ended_at INTEGER,
+          turn_count INTEGER NOT NULL DEFAULT 0,
+          tool_call_count INTEGER NOT NULL DEFAULT 0,
+          input_tokens INTEGER NOT NULL DEFAULT 0,
+          output_tokens INTEGER NOT NULL DEFAULT 0,
+          cost_usd REAL NOT NULL DEFAULT 0,
+          title TEXT,
+          labels_json TEXT NOT NULL DEFAULT '[]',
+          topic TEXT,
+          source_path TEXT NOT NULL,
+          mtime_ms INTEGER NOT NULL DEFAULT 0,
+          size_bytes INTEGER NOT NULL DEFAULT 0,
+          indexed_at INTEGER NOT NULL DEFAULT 0
+        );
+        CREATE INDEX IF NOT EXISTS idx_session_started ON session(started_at DESC);
+        CREATE INDEX IF NOT EXISTS idx_session_agent ON session(agent);
+        CREATE TABLE IF NOT EXISTS turn (
+          turn_uuid TEXT PRIMARY KEY,
+          session_id TEXT NOT NULL REFERENCES session(session_id) ON DELETE CASCADE,
+          turn_index INTEGER NOT NULL,
+          ts INTEGER,
+          role TEXT NOT NULL,
+          text TEXT NOT NULL DEFAULT '',
+          tool_names_csv TEXT NOT NULL DEFAULT '',
+          input_tokens INTEGER NOT NULL DEFAULT 0,
+          output_tokens INTEGER NOT NULL DEFAULT 0,
+          cost_usd REAL NOT NULL DEFAULT 0
+        );
+        CREATE INDEX IF NOT EXISTS idx_turn_session ON turn(session_id, turn_index);
+        CREATE TABLE IF NOT EXISTS insight (
+          session_id TEXT PRIMARY KEY REFERENCES session(session_id) ON DELETE CASCADE,
+          topic TEXT,
+          tags_json TEXT NOT NULL DEFAULT '[]',
+          signals_json TEXT NOT NULL DEFAULT '[]',
+          provider TEXT,
+          generated_at TEXT
+        );
+      `);
+      this.db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+    }
+  }
+
+  /** session_id -> {mtime_ms, size_bytes} for incremental sync invalidation. */
+  knownSources(): Map<string, { mtime_ms: number; size_bytes: number }> {
+    const rows = this.db.prepare('SELECT session_id, mtime_ms, size_bytes FROM session').all() as Array<{
+      session_id: string;
+      mtime_ms: number;
+      size_bytes: number;
+    }>;
+    const m = new Map<string, { mtime_ms: number; size_bytes: number }>();
+    for (const r of rows) m.set(r.session_id, { mtime_ms: r.mtime_ms, size_bytes: r.size_bytes });
+    return m;
+  }
+
+  upsertSession(
+    env: SessionEnvelope,
+    src: { source_path: string; mtime_ms: number; size_bytes: number; indexed_at: number; topic?: string },
+  ): void {
+    this.db
+      .prepare(
+        `INSERT INTO session (session_id, host, agent, project_path, model, started_at, ended_at,
+           turn_count, tool_call_count, input_tokens, output_tokens, cost_usd, title, labels_json,
+           topic, source_path, mtime_ms, size_bytes, indexed_at)
+         VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+         ON CONFLICT(session_id) DO UPDATE SET
+           host=excluded.host, agent=excluded.agent, project_path=excluded.project_path,
+           model=excluded.model, started_at=excluded.started_at, ended_at=excluded.ended_at,
+           turn_count=excluded.turn_count, tool_call_count=excluded.tool_call_count,
+           input_tokens=excluded.input_tokens, output_tokens=excluded.output_tokens,
+           cost_usd=excluded.cost_usd, title=excluded.title, labels_json=excluded.labels_json,
+           topic=excluded.topic, source_path=excluded.source_path, mtime_ms=excluded.mtime_ms,
+           size_bytes=excluded.size_bytes, indexed_at=excluded.indexed_at`,
+      )
+      .run(
+        env.session_id,
+        env.host,
+        env.agent,
+        env.project_path,
+        env.model ?? null,
+        toMs(env.started_at),
+        toMs(env.ended_at),
+        env.turn_count,
+        env.tool_call_count,
+        env.totals.input_tokens,
+        env.totals.output_tokens,
+        env.totals.cost_usd,
+        env.title ?? null,
+        JSON.stringify(env.labels ?? []),
+        src.topic ?? null,
+        src.source_path,
+        src.mtime_ms,
+        src.size_bytes,
+        src.indexed_at,
+      );
+  }
+
+  replaceTurns(sessionId: string, turns: Turn[]): void {
+    this.db.prepare('DELETE FROM turn WHERE session_id = ?').run(sessionId);
+    const stmt = this.db.prepare(
+      `INSERT OR REPLACE INTO turn (turn_uuid, session_id, turn_index, ts, role, text,
+         tool_names_csv, input_tokens, output_tokens, cost_usd) VALUES (?,?,?,?,?,?,?,?,?,?)`,
+    );
+    for (const t of turns) {
+      stmt.run(
+        `${sessionId}#${t.turn_index}`,
+        sessionId,
+        t.turn_index,
+        toMs(t.ts),
+        t.role,
+        t.text.slice(0, 8192),
+        t.tool_calls.map((c) => c.name).join(','),
+        t.usage.input_tokens,
+        t.usage.output_tokens,
+        t.telemetry?.cost_usd ?? 0,
+      );
+    }
+  }
+
+  upsertInsight(ins: Insights): void {
+    this.db
+      .prepare(
+        `INSERT OR REPLACE INTO insight (session_id, topic, tags_json, signals_json, provider, generated_at)
+         VALUES (?,?,?,?,?,?)`,
+      )
+      .run(
+        ins.session_id,
+        ins.topic ?? null,
+        JSON.stringify(ins.tags ?? []),
+        JSON.stringify(ins.signals ?? []),
+        ins.provider,
+        ins.generated_at,
+      );
+  }
+
+  deleteSessions(ids: string[]): void {
+    if (ids.length === 0) return;
+    const stmt = this.db.prepare('DELETE FROM session WHERE session_id = ?');
+    for (const id of ids) stmt.run(id);
+  }
+
+  private rowToIndex(r: any): SessionIndexRow {
+    return {
+      session_id: r.session_id,
+      host: r.host,
+      agent: r.agent,
+      project_path: r.project_path,
+      model: r.model ?? null,
+      started_at: r.started_at ?? null,
+      ended_at: r.ended_at ?? null,
+      turn_count: r.turn_count,
+      tool_call_count: r.tool_call_count,
+      input_tokens: r.input_tokens,
+      output_tokens: r.output_tokens,
+      cost_usd: r.cost_usd,
+      title: r.title ?? null,
+      labels: safeJson(r.labels_json),
+      topic: r.topic ?? null,
+      source_path: r.source_path,
+    };
+  }
+
+  listRecent(limit = 50, agent?: string): SessionIndexRow[] {
+    const rows = agent
+      ? this.db
+          .prepare('SELECT * FROM session WHERE agent = ? ORDER BY started_at DESC LIMIT ?')
+          .all(agent, limit)
+      : this.db.prepare('SELECT * FROM session ORDER BY started_at DESC LIMIT ?').all(limit);
+    return (rows as any[]).map((r) => this.rowToIndex(r));
+  }
+
+  getSession(id: string): SessionIndexRow | undefined {
+    const r = this.db.prepare('SELECT * FROM session WHERE session_id = ?').get(id);
+    return r ? this.rowToIndex(r) : undefined;
+  }
+
+  /** Full-text-ish search over turn text + session titles. */
+  searchTurns(query: string, limit = 50): SessionIndexRow[] {
+    const like = `%${query}%`;
+    const rows = this.db
+      .prepare(
+        `SELECT DISTINCT s.* FROM session s
+         LEFT JOIN turn t ON t.session_id = s.session_id
+         WHERE t.text LIKE ? OR s.title LIKE ?
+         ORDER BY s.started_at DESC LIMIT ?`,
+      )
+      .all(like, like, limit);
+    return (rows as any[]).map((r) => this.rowToIndex(r));
+  }
+
+  stats(): { sessions: number; turns: number; cost_usd: number; byAgent: Record<string, number> } {
+    const s = this.db.prepare('SELECT COUNT(*) c, COALESCE(SUM(cost_usd),0) cost FROM session').get() as {
+      c: number;
+      cost: number;
+    };
+    const t = this.db.prepare('SELECT COUNT(*) c FROM turn').get() as { c: number };
+    const agents = this.db.prepare('SELECT agent, COUNT(*) c FROM session GROUP BY agent').all() as Array<{
+      agent: string;
+      c: number;
+    }>;
+    const byAgent: Record<string, number> = {};
+    for (const a of agents) byAgent[a.agent] = a.c;
+    return { sessions: s.c, turns: t.c, cost_usd: Math.round(s.cost * 1e6) / 1e6, byAgent };
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}
+
+function safeJson(s: unknown): string[] {
+  if (typeof s !== 'string') return [];
+  try {
+    const v = JSON.parse(s);
+    return Array.isArray(v) ? v : [];
+  } catch {
+    return [];
+  }
+}

package/src/index_store/index.ts

@@ -0,0 +1,2 @@
+export * from './db';
+export * from './sync';

package/src/index_store/sync.test.ts

@@ -0,0 +1,88 @@
+import { rmSync } from 'node:fs';
+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 { SessionIndex } from './db';
+import { syncIndex } from './sync';
+
+function turn(i: number, over: Partial<Turn> = {}): Turn {
+  return {
+    schema: 'session-store/turn@1',
+    session_id: 's1',
+    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, id: string): Promise<string> {
+  const dir = sessionDir(store, 'h', '2026-06', id);
+  writeTurnFile(dir, turn(0, { session_id: id, role: 'user', text: 'fix the parser bug' }));
+  writeTurnFile(dir, turn(1, { session_id: id, tool_calls: [{ name: 'Edit' }] }));
+  rebuildEnvelope(store, 'h', '2026-06', id, { model: 'claude-opus-4-8' }, {
+    session_id: id,
+    host: 'h',
+    agent: 'claude-code',
+    native_uuid: id,
+  });
+  await labelSession(dir, { sessionId: id, host: 'h' }, new FakeProvider(), { now: '2026-06-20T09:00:00Z' });
+  return dir;
+}
+
+describe('syncIndex', () => {
+  it('projects the git store into the SQLite index', async () => {
+    await withTempDirAsync(async (store) => {
+      await seed(store, 's1');
+      await seed(store, 's2');
+      const cfg = makeConfig(store);
+
+      const stats = syncIndex(cfg);
+      expect(stats.total).toBe(2);
+      expect(stats.indexed).toBe(2);
+
+      const idx = new SessionIndex(cfg.indexPath);
+      try {
+        expect(idx.stats().sessions).toBe(2);
+        expect(idx.searchTurns('parser').length).toBeGreaterThan(0);
+        expect(idx.listRecent(10)[0]!.topic).toContain('fix the parser bug');
+      } finally {
+        idx.close();
+      }
+    });
+  });
+
+  it('is incremental (unchanged on re-sync) and removes deleted sessions', async () => {
+    await withTempDirAsync(async (store) => {
+      const dir = await seed(store, 's1');
+      await seed(store, 's2');
+      const cfg = makeConfig(store);
+      syncIndex(cfg);
+
+      const again = syncIndex(cfg);
+      expect(again.indexed).toBe(0);
+      expect(again.unchanged).toBe(2);
+
+      rmSync(dir, { recursive: true, force: true });
+      const after = syncIndex(cfg);
+      expect(after.removed).toBe(1);
+      const idx = new SessionIndex(cfg.indexPath);
+      try {
+        expect(idx.stats().sessions).toBe(1);
+      } finally {
+        idx.close();
+      }
+    });
+  });
+});

package/src/index_store/sync.ts

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { safeParseInsights, safeParseSession } from '@unpolarize/code-sessions-schema';
+import type { CodeSessionsConfig } from '../config';
+import { envelopeFile, insightsFile } from '../store/paths';
+import { listSessionDirs } from '../store/scan';
+import { readTurns } from '../store/writer';
+import { SessionIndex } from './db';
+
+export interface IndexSyncStats {
+  total: number;
+  indexed: number;
+  unchanged: number;
+  removed: number;
+}
+
+/**
+ * Project the git store into the SQLite index, incrementally (mtime/size
+ * invalidation per session.json). Rebuildable any time; the git files stay
+ * authoritative.
+ */
+export function syncIndex(
+  cfg: CodeSessionsConfig,
+  opts: { index?: SessionIndex; now?: number } = {},
+): IndexSyncStats {
+  const index = opts.index ?? new SessionIndex(cfg.indexPath);
+  const ownsIndex = !opts.index;
+  const now = opts.now ?? Date.now();
+  try {
+    const refs = listSessionDirs(cfg.storeDir);
+    const known = index.knownSources();
+    const seen = new Set<string>();
+    let indexed = 0;
+    let unchanged = 0;
+
+    for (const ref of refs) {
+      const envPath = envelopeFile(ref.dir);
+      if (!existsSync(envPath)) continue;
+      const st = statSync(envPath);
+      const mtime_ms = Math.floor(st.mtimeMs);
+      const size_bytes = st.size;
+      seen.add(ref.sessionId);
+
+      const cached = known.get(ref.sessionId);
+      if (cached && cached.mtime_ms === mtime_ms && cached.size_bytes === size_bytes) {
+        unchanged++;
+        continue;
+      }
+
+      const parsed = safeParseSession(JSON.parse(readFileSync(envPath, 'utf8')));
+      if (!parsed.success) continue;
+      const env = parsed.data;
+
+      let topic: string | undefined;
+      const insPath = insightsFile(ref.dir);
+      let insights = undefined;
+      if (existsSync(insPath)) {
+        const pi = safeParseInsights(JSON.parse(readFileSync(insPath, 'utf8')));
+        if (pi.success) {
+          insights = pi.data;
+          topic = pi.data.topic;
+        }
+      }
+
+      index.upsertSession(env, {
+        source_path: envPath,
+        mtime_ms,
+        size_bytes,
+        indexed_at: now,
+        ...(topic ? { topic } : {}),
+      });
+      index.replaceTurns(env.session_id, readTurns(ref.dir));
+      if (insights) index.upsertInsight(insights);
+      indexed++;
+    }
+
+    const removed = [...known.keys()].filter((id) => !seen.has(id));
+    index.deleteSessions(removed);
+
+    return { total: refs.length, indexed, unchanged, removed: removed.length };
+  } finally {
+    if (ownsIndex) index.close();
+  }
+}

package/src/insights/heuristics.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import type { Turn } from '@unpolarize/code-sessions-schema';
+import { deriveSignals, deriveTags, guessTopic } from './heuristics';
+
+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: 't',
+    role: 'assistant',
+    text: '',
+    tool_calls: [],
+    usage: { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0 },
+    scrubbed: false,
+    raw_ref: null,
+    ...over,
+  };
+}
+
+describe('deriveSignals', () => {
+  it('flags a stuck loop on repeated identical actions', () => {
+    const turns = [
+      turn(0, { tool_calls: [{ name: 'Bash', input: { command: 'ls' } }] }),
+      turn(1, { tool_calls: [{ name: 'Bash', input: { command: 'ls' } }] }),
+      turn(2, { tool_calls: [{ name: 'Bash', input: { command: 'ls' } }] }),
+    ];
+    const s = deriveSignals(turns);
+    expect(s.some((x) => x.kind === 'stuck-loop' && x.severity === 'warn')).toBe(true);
+  });
+
+  it('flags error-recovery when a turn mentions an error', () => {
+    const turns = [turn(0, { role: 'tool', text: 'TypeError: cannot read foo' })];
+    expect(deriveSignals(turns).some((x) => x.kind === 'error-recovery')).toBe(true);
+  });
+
+  it('flags high-cost turns', () => {
+    const turns = [turn(0, { telemetry: { cost_usd: 0.9 } })];
+    expect(deriveSignals(turns).some((x) => x.kind === 'high-cost-turn')).toBe(true);
+  });
+
+  it('flags tool-heavy sessions', () => {
+    const turns = [
+      turn(0, { tool_calls: [{ name: 'Read' }, { name: 'Edit' }] }),
+      turn(1, { tool_calls: [{ name: 'Bash' }] }),
+    ];
+    expect(deriveSignals(turns).some((x) => x.kind === 'tool-heavy')).toBe(true);
+  });
+
+  it('produces nothing notable for a calm short session', () => {
+    const turns = [turn(0, { role: 'user', text: 'hi' }), turn(1, { text: 'hello' })];
+    expect(deriveSignals(turns)).toEqual([]);
+  });
+});
+
+describe('guessTopic / deriveTags', () => {
+  it('guesses a topic from the first user turn', () => {
+    const topic = guessTopic([turn(0, { role: 'user', text: 'Fix the bug in foo.ts please now' })]);
+    expect(topic).toContain('Fix the bug');
+  });
+
+  it('collects distinct tool names as tags', () => {
+    const tags = deriveTags([
+      turn(0, { tool_calls: [{ name: 'Read' }, { name: 'Edit' }] }),
+      turn(1, { tool_calls: [{ name: 'Read' }] }),
+    ]);
+    expect(tags.sort()).toEqual(['Edit', 'Read']);
+  });
+});