ccsniff 1.0.32 → 1.1.1

package/README.md

@@ -33,6 +33,20 @@ CommonJS:
 const { watch, JsonlWatcher } = require('ccsniff');
 ```
 
+## Mountable Express router (`/v1/history/*`)
+
+ccsniff ships a mountable router that hosts all the read-only history endpoints used by AgentGUI's live client (`/v1/history/snapshot`, `/sessions`, `/sessions/:sid/events`, `/search`, `/stream` SSE, and `POST /reindex`). It reads `~/.claude/projects` by default; override with the `CLAUDE_PROJECTS_DIR` env var. `express` is an optional peer dependency — install it in the host app.
+
+```js
+import express from 'express';
+import { createHistoryRouter } from 'ccsniff';
+
+const app = express();
+app.use(await createHistoryRouter({ projectsDir: process.env.CLAUDE_PROJECTS_DIR }));
+app.listen(3000);
+```
+
+
 ## CLI
 
 ```bash

package/gui/app.js

@@ -1,6 +1,6 @@
 import { mount, components as C, h } from 'anentrypoint-design';
 
-const TABS = ['overview', 'sessions', 'projects', 'tools', 'timeline', 'errors', 'subagents', 'live', 'search'];
+const TABS = ['overview', 'sessions', 'projects', 'tools', 'timeline', 'errors', 'subagents', 'events', 'live', 'search'];
 const state = {
   tab: 'overview',
   data: { snapshot: null, sessions: [], projects: [], tools: [], timeline: [], stats: null, errors: [], subagents: [] },
@@ -8,6 +8,9 @@ const state = {
   searchResults: [],
   searching: false,
   liveLog: [],
+  defaults: { active: 'recent', presets: [] },
+  activePreset: 'recent',
+  events: { total: 0, rows: [], loading: false },
 };
 
 const api = (p) => fetch(p).then(r => r.json());
@@ -144,16 +147,81 @@ function SubagentsView() {
   ) });
 }
 
-function LiveView() {
-  return C.Panel({ head: `live · ${state.liveLog.length} events (last 200)`, children: h('div', { class: 'live' },
-    ...state.liveLog.slice().reverse().map((e, i) => h('div', { key: i, class: 'e' },
-      h('span', { class: 'ts' }, ts(e.ts || Date.now()).slice(11)),
-      h('span', { class: 'k' }, e._kind || 'event'),
-      h('span', {}, fmtLive(e)),
+function PresetChips() {
+  const presets = state.defaults.presets || [];
+  return h('div', { style: 'display:flex;flex-wrap:wrap;gap:6px;padding:8px 12px' },
+    ...presets.map(p => h('span', {
+      class: 'pill' + (p.id === state.activePreset ? ' accent' : ''),
+      style: 'cursor:pointer;user-select:none;' + (p.id === state.activePreset ? 'outline:1px solid currentColor' : ''),
+      onclick: () => { state.activePreset = p.id; loadEvents(); },
+    }, p.label)),
+  );
+}
+
+function currentPresetQuery() {
+  const p = (state.defaults.presets || []).find(x => x.id === state.activePreset);
+  return p?.query || {};
+}
+
+async function loadEvents() {
+  state.events.loading = true; render();
+  const q = currentPresetQuery();
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(q)) if (v !== undefined && v !== null && v !== '') params.set(k, String(v));
+  params.set('limit', '200');
+  const r = await api('/api/events?' + params.toString());
+  state.events = { total: r.total || 0, rows: r.rows || [], loading: false, error: r.error || null };
+  render();
+}
+
+function EventsView() {
+  const rows = state.events.rows;
+  return C.Panel({ head: `events · ${state.events.total} match · showing ${rows.length}`, children: h('div', {},
+    PresetChips(),
+    state.events.error ? h('div', { class: 'err', style: 'padding:8px 12px' }, state.events.error) : null,
+    h('div', { class: 'row-grid', style: 'grid-template-columns:140px 80px 110px 100px 1fr;opacity:.55' },
+      h('span', {}, 'when'), h('span', {}, 'role'), h('span', {}, 'type'), h('span', {}, 'tool'), h('span', {}, 'text')),
+    ...rows.map(e => h('div', { class: 'row-grid', style: 'grid-template-columns:140px 80px 110px 100px 1fr' },
+      h('span', {}, ts(e.ts).slice(5)),
+      h('span', {}, e.role || '—'),
+      h('span', {}, e.type || '—'),
+      h('span', { class: 'accent' }, e.tool || '—'),
+      h('span', { class: 'truncate' + (e.isError ? ' err' : '') },
+        h('span', { class: 'pill' }, e.project || '—'),
+        ' ',
+        (e.text || '').slice(0, 400)),
     )),
   ) });
 }
 
+function liveMatches(e) {
+  const q = currentPresetQuery();
+  if (q.role && e.role !== q.role) return false;
+  if (q.type && e.type !== q.type) return false;
+  if (q.tool && e.tool !== q.tool) return false;
+  if (q.project && e.project !== q.project) return false;
+  if (q.isMeta === true && !e.isMeta) return false;
+  if (q.isMeta === false && e.isMeta) return false;
+  if (q.isSubagent === true && !e.isSubagent) return false;
+  if (q.isSubagent === false && e.isSubagent) return false;
+  if (q.isError === true && !e.isError) return false;
+  return true;
+}
+
+function LiveView() {
+  const filtered = state.liveLog.filter(e => e._kind !== 'event' || liveMatches(e));
+  return C.Panel({ head: `live · ${filtered.length}/${state.liveLog.length} events (preset: ${state.activePreset})`, children: h('div', {},
+    PresetChips(),
+    h('div', { class: 'live' },
+      ...filtered.slice().reverse().map((e, i) => h('div', { key: i, class: 'e' },
+        h('span', { class: 'ts' }, ts(e.ts || Date.now()).slice(11)),
+        h('span', { class: 'k' }, e._kind || 'event'),
+        h('span', {}, fmtLive(e)),
+      )),
+    ),
+  ) });
+}
+
 function fmtLive(e) {
   if (e._kind === 'conversation') return 'new ' + (e.conv?.title || e.conv?.id?.slice(0, 8));
   if (e._kind === 'start' || e._kind === 'complete') return (e.sid || '').slice(0, 8);
@@ -192,7 +260,7 @@ async function doSearch() {
   state.searching = false; render();
 }
 
-const VIEWS = { overview: Overview, sessions: SessionsView, projects: ProjectsView, tools: ToolsView, timeline: TimelineView, errors: ErrorsView, subagents: SubagentsView, live: LiveView, search: SearchView };
+const VIEWS = { overview: Overview, sessions: SessionsView, projects: ProjectsView, tools: ToolsView, timeline: TimelineView, errors: ErrorsView, subagents: SubagentsView, events: EventsView, live: LiveView, search: SearchView };
 
 function App() {
   const s = state.data.snapshot || {};
@@ -201,7 +269,7 @@ function App() {
       brand: '247420', leaf: 'ccsniff',
       items: TABS.map(t => [t, '#/' + t]),
       active: state.tab,
-      onNav: (t) => { state.tab = t; location.hash = '#/' + t; render(); },
+      onNav: (t) => { state.tab = t; location.hash = '#/' + t; render(); if (t === 'events') loadEvents(); },
     }),
     main: h('div', { style: 'padding:16px;display:flex;flex-direction:column;gap:16px' },
       C.Crumb({ trail: ['247420', 'ccsniff'], leaf: state.tab, right: h('span', { class: 'pill' }, n(s.events) + ' events') }),
@@ -224,7 +292,13 @@ render();
 })();
 
 (async function init() {
+  try {
+    const d = await api('/api/defaults');
+    state.defaults = d || state.defaults;
+    state.activePreset = d?.active || state.activePreset;
+  } catch {}
   await loadAll();
+  if (state.tab === 'events') loadEvents();
   setInterval(loadAll, 15_000);
   const sse = new EventSource('/api/stream');
   const push = (kind, data) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccsniff",
-  "version": "1.0.32",
+  "version": "1.1.1",
   "description": "Watch Claude Code JSONL output files and emit structured events as a Node.js EventEmitter",
   "type": "module",
   "main": "./src/index.js",
@@ -39,5 +39,13 @@
   "homepage": "https://anentrypoint.github.io/ccsniff",
   "engines": {
     "node": ">=18"
+  },
+  "peerDependencies": {
+    "express": "^4 || ^5"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
   }
 }

package/src/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { JsonlReplayer, rollup, vault } from './index.js';
 import { toUnslothMessages, toShareGPT } from './unsloth.js';
+import { parseTime, compileRegexes, buildFilter } from './filters.js';
 import fs from 'fs';
 import path from 'path';
 
@@ -69,7 +70,7 @@ TIME (any ISO date, epoch ms, or relative Ns/Nm/Nh/Nd/Nw)
 
 FILTERS (repeatable flags combine as OR within a flag, AND across flags)
   --grep <re>            text regex (case-insensitive); repeat = AND
-  --igrep <re>           inverted text regex; repeat = AND (none must match)
+  --igrep <re>           exclude if regex matches text; repeat = exclude if ANY matches
   --invert               invert the entire filter result
   --cwd <re>             working-dir regex
   --project <name>       basename(cwd) exact match; repeat = OR
@@ -114,21 +115,6 @@ EXAMPLES
 `);
 }
 
-function parseTime(s) {
-  if (!s) return 0;
-  if (/^\d{10,}$/.test(s)) return parseInt(s, 10);
-  const m = /^(\d+)([smhdw])$/.exec(s);
-  if (m) {
-    const n = parseInt(m[1], 10);
-    const mult = { s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 }[m[2]];
-    return Date.now() - n * mult;
-  }
-  const t = Date.parse(s);
-  return Number.isFinite(t) ? t : 0;
-}
-
-function compileRegexes(arr) { return arr.map(s => new RegExp(s, 'i')); }
-
 function blockText(b) {
   if (!b) return '';
   if (typeof b.text === 'string') return b.text;
@@ -138,46 +124,6 @@ function blockText(b) {
   return '';
 }
 
-function buildFilter(opts) {
-  const since = parseTime(opts.since || opts.after);
-  const until = parseTime(opts.until || opts.before);
-  const greps = compileRegexes(opts._multi.grep);
-  const igreps = compileRegexes(opts._multi.igrep);
-  const cwdRes = compileRegexes(opts._multi.cwd);
-  const projects = new Set(opts._multi.project);
-  const roles = new Set(opts._multi.role);
-  const types = new Set(opts._multi.type);
-  const tools = new Set(opts._multi.tool);
-  const sids = opts._multi.session.concat(opts._multi.sid || []);
-  const parent = opts.parent || null;
-
-  return ev => {
-    const conv = ev.conversation || {};
-    const block = ev.block || {};
-    const ts = ev.timestamp || 0;
-    let pass = true;
-    if (since && ts < since) pass = false;
-    else if (until && ts > until) pass = false;
-    else if (cwdRes.length && !cwdRes.every(r => r.test(conv.cwd || ''))) pass = false;
-    else if (projects.size && !projects.has(path.basename(conv.cwd || ''))) pass = false;
-    else if (roles.size && !roles.has(ev.role)) pass = false;
-    else if (types.size && !types.has(block.type)) pass = false;
-    else if (tools.size && !tools.has(block.name)) pass = false;
-    else if (sids.length && !sids.some(s => conv.id?.startsWith(s))) pass = false;
-    else if (parent && conv.parentSid !== parent) pass = false;
-    else if (opts['no-subagents'] && conv.isSubagent) pass = false;
-    else if (opts['only-subagents'] && !conv.isSubagent) pass = false;
-    else if (opts['no-meta'] && block.isMeta) pass = false;
-    else if (opts['only-meta'] && !block.isMeta) pass = false;
-    else {
-      const text = blockText(block);
-      if (greps.length && !greps.every(r => r.test(text))) pass = false;
-      else if (igreps.length && igreps.some(r => r.test(text))) pass = false;
-    }
-    return opts.invert ? !pass : pass;
-  };
-}
-
 function formatRow(ev, opts) {
   const conv = ev.conversation || {};
   const block = ev.block || {};
@@ -242,8 +188,14 @@ if (opts.help || process.argv.length <= 2) { printHelp(); process.exit(0); }
 
 { const r = vault(); if (r.copied > 0) process.stderr.write(`# vault: ${r.copied} copied → ~/.claude/history-backup\n`); }
 
-const since = parseTime(opts.since || opts.after);
-const filter = buildFilter(opts);
+let since, filter;
+try {
+  since = parseTime(opts.since || opts.after);
+  filter = buildFilter(opts);
+} catch (e) {
+  process.stderr.write(`ccsniff: ${e.message}\n`);
+  process.exit(2);
+}
 
 // ---------- rollup (filtered)
 if (opts.rollup) {

package/src/filters.js

@@ -0,0 +1,89 @@
+// Filter primitives shared by cli.js, gui-server.js, and tests.
+import path from 'path';
+
+export function parseTime(s) {
+  if (s === undefined || s === null || s === '') return 0;
+  if (typeof s === 'number') return Number.isFinite(s) ? s : 0;
+  s = String(s).trim();
+  if (!s) return 0;
+  if (/^\d{10,}$/.test(s)) return parseInt(s, 10);
+  const m = /^(\d+)\s*([smhdw])$/i.exec(s);
+  if (m) {
+    const n = parseInt(m[1], 10);
+    const mult = { s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 }[m[2].toLowerCase()];
+    return Date.now() - n * mult;
+  }
+  const t = Date.parse(s);
+  if (Number.isFinite(t)) return t;
+  throw new Error(`invalid time: ${s} (use ISO date, epoch ms, or Ns/Nm/Nh/Nd/Nw)`);
+}
+
+export function compileRegexes(arr) {
+  return (arr || []).map(s => {
+    try { return new RegExp(s, 'i'); }
+    catch (e) { throw new Error(`invalid regex /${s}/: ${e.message}`); }
+  });
+}
+
+function blockText(b) {
+  if (!b) return '';
+  if (typeof b.text === 'string') return b.text;
+  if (typeof b.content === 'string') return b.content;
+  if (Array.isArray(b.content)) return b.content.map(c => c?.text || '').join('');
+  if (b.input) { try { return JSON.stringify(b.input); } catch { return ''; } }
+  return '';
+}
+
+export function buildFilter(opts) {
+  const m = opts._multi || {};
+  const since = parseTime(opts.since || opts.after);
+  const until = parseTime(opts.until || opts.before);
+  const greps = compileRegexes(m.grep);
+  const igreps = compileRegexes(m.igrep);
+  const cwdRes = compileRegexes(m.cwd);
+  const projects = new Set(m.project || []);
+  const roles = new Set(m.role || []);
+  const types = new Set(m.type || []);
+  const tools = new Set(m.tool || []);
+  const sids = (m.session || []).concat(m.sid || []);
+  const parent = opts.parent || null;
+
+  return ev => {
+    const conv = ev.conversation || {};
+    const block = ev.block || {};
+    const ts = ev.timestamp || 0;
+    let pass = true;
+    if (since && ts < since) pass = false;
+    else if (until && ts > until) pass = false;
+    else if (cwdRes.length && !cwdRes.every(r => r.test(conv.cwd || ''))) pass = false;
+    else if (projects.size && !projects.has(path.basename(conv.cwd || ''))) pass = false;
+    else if (roles.size && !roles.has(ev.role)) pass = false;
+    else if (types.size && !types.has(block.type)) pass = false;
+    else if (tools.size && !tools.has(block.name)) pass = false;
+    else if (sids.length && !sids.some(s => conv.id?.startsWith(s))) pass = false;
+    else if (parent && conv.parentSid !== parent) pass = false;
+    else if (opts['no-subagents'] && conv.isSubagent) pass = false;
+    else if (opts['only-subagents'] && !conv.isSubagent) pass = false;
+    else if (opts['no-meta'] && block.isMeta) pass = false;
+    else if (opts['only-meta'] && !block.isMeta) pass = false;
+    else {
+      const text = blockText(block);
+      if (greps.length && !greps.every(r => r.test(text))) pass = false;
+      else if (igreps.length && igreps.some(r => r.test(text))) pass = false;
+    }
+    return opts.invert ? !pass : pass;
+  };
+}
+
+export const DEFAULT_PRESETS = [
+  { id: 'recent',     label: 'Last 24h',       query: { since: '24h', isMeta: false } },
+  { id: 'week',       label: 'Last 7d',        query: { since: '7d',  isMeta: false } },
+  { id: 'errors',     label: 'Errors',         query: { since: '7d',  isError: true } },
+  { id: 'tools',      label: 'Tool calls',     query: { since: '24h', type: 'tool_use' } },
+  { id: 'user-turns', label: 'User turns',     query: { since: '7d',  role: 'user', type: 'text', isMeta: false } },
+  { id: 'assistant',  label: 'Assistant text', query: { since: '24h', role: 'assistant', type: 'text' } },
+  { id: 'subagents',  label: 'Subagents',      query: { since: '7d',  isSubagent: true } },
+  { id: 'all',        label: 'All time',       query: {} },
+];
+
+export const DEFAULT_ACTIVE = 'recent';

package/src/gui-server.js

@@ -4,9 +4,12 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { JsonlReplayer, JsonlWatcher } from './index.js';
 import { buildIndex, search, snippet, tokenize } from './bm25.js';
+import { DEFAULT_PRESETS, DEFAULT_ACTIVE } from './filters.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const GUI_DIR = path.join(__dirname, '..', 'gui');
+
+export const DEFAULT_FILTERS = { active: DEFAULT_ACTIVE, presets: DEFAULT_PRESETS };
 const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml' };
 
 function blockText(b) {
@@ -34,6 +37,7 @@ function flattenEvent(ev, idx) {
     tool: b.name || null,
     text: blockText(b),
     isError: !!b.is_error || ev.role === 'streaming_error',
+    isMeta: !!b.isMeta,
     cost: b.total_cost_usd || null,
     duration: b.duration_ms || null,
     subtype: b.subtype || null,
@@ -223,20 +227,42 @@ class Store {
     return out;
   }
 
-  events_filtered({ role, type, project, sid, tool, since, until, limit = 200, offset = 0, q } = {}) {
+  events_filtered({ role, type, project, sid, tool, since, until, limit = 200, offset = 0, q, grep, igrep, isMeta, isSubagent, isError, parent } = {}) {
     let arr = this.events;
+    let greRe = null, igreRe = null;
+    try {
+      if (grep) greRe = new RegExp(grep, 'i');
+      if (igrep) igreRe = new RegExp(igrep, 'i');
+    } catch (e) {
+      return { total: 0, rows: [], error: `invalid regex: ${e.message}` };
+    }
     if (q) {
-      const tokens = new Set(tokenize(q));
-      arr = arr.filter(e => { const t = tokenize(e.text); return [...tokens].every(x => t.includes(x)); });
+      const tokens = [...new Set(tokenize(q))];
+      if (tokens.length) {
+        arr = arr.filter(e => { const t = tokenize(e.text); return tokens.every(x => t.includes(x)); });
+      } else {
+        // q tokenized to nothing (too short / stopwords) → substring fallback
+        const needle = String(q).toLowerCase();
+        arr = arr.filter(e => (e.text || '').toLowerCase().includes(needle));
+      }
     }
     arr = arr.filter(e => {
       if (role && e.role !== role) return false;
       if (type && e.type !== type) return false;
       if (project && e.project !== project) return false;
       if (sid && !e.sid.startsWith(sid)) return false;
+      if (parent && e.parent !== parent) return false;
       if (tool && e.tool !== tool) return false;
       if (since && e.ts < since) return false;
       if (until && e.ts > until) return false;
+      if (isMeta === true && !e.isMeta) return false;
+      if (isMeta === false && e.isMeta) return false;
+      if (isSubagent === true && !e.isSubagent) return false;
+      if (isSubagent === false && e.isSubagent) return false;
+      if (isError === true && !e.isError) return false;
+      if (isError === false && e.isError) return false;
+      if (greRe && !greRe.test(e.text || '')) return false;
+      if (igreRe && igreRe.test(e.text || '')) return false;
       return true;
     });
     return { total: arr.length, rows: arr.slice(offset, offset + limit) };
@@ -260,14 +286,36 @@ function serveStatic(req, res) {
   });
 }
 
+function parseRelTime(s) {
+  if (s === null || s === undefined || s === '') return 0;
+  const str = String(s).trim();
+  if (/^\d{10,}$/.test(str)) return parseInt(str, 10);
+  const m = /^(\d+)\s*([smhdw])$/i.exec(str);
+  if (m) {
+    const n = parseInt(m[1], 10);
+    const mult = { s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 }[m[2].toLowerCase()];
+    return Date.now() - n * mult;
+  }
+  const t = Date.parse(str);
+  return Number.isFinite(t) ? t : 0;
+}
+function parseBool(v) {
+  if (v === undefined) return undefined;
+  if (v === 'true' || v === '1') return true;
+  if (v === 'false' || v === '0') return false;
+  return undefined;
+}
 function parseQuery(u) {
   const q = {};
   for (const [k, v] of u.searchParams) q[k] = v;
-  if (q.limit) q.limit = parseInt(q.limit, 10);
-  if (q.offset) q.offset = parseInt(q.offset, 10);
-  if (q.since) q.since = parseInt(q.since, 10);
-  if (q.until) q.until = parseInt(q.until, 10);
-  if (q.bucket) q.bucket = parseInt(q.bucket, 10);
+  if (q.limit !== undefined) q.limit = parseInt(q.limit, 10) || 200;
+  if (q.offset !== undefined) q.offset = parseInt(q.offset, 10) || 0;
+  if (q.since !== undefined) q.since = parseRelTime(q.since);
+  if (q.until !== undefined) q.until = parseRelTime(q.until);
+  if (q.bucket !== undefined) q.bucket = parseInt(q.bucket, 10) || 0;
+  for (const k of ['isMeta', 'isSubagent', 'isError']) {
+    if (q[k] !== undefined) q[k] = parseBool(q[k]);
+  }
   return q;
 }
 
@@ -291,6 +339,7 @@ export function createServer({ projectsDir, port = 0, host = '127.0.0.1' } = {})
       if (path === '/api/errors') return send(res, 200, store.errorsList());
       if (path === '/api/subagents') return send(res, 200, store.subagents());
       if (path === '/api/events') return send(res, 200, store.events_filtered(q));
+      if (path === '/api/defaults') return send(res, 200, DEFAULT_FILTERS);
       if (path === '/api/search') return send(res, 200, { query: q.q || '', results: q.q ? store.search(q.q, q) : [] });
       if (path === '/api/reindex') { store.rebuildIndex(); return send(res, 200, { ok: true, at: store.lastBuilt }); }
       if (path === '/api/stream') {

package/src/index.js

@@ -3,7 +3,8 @@ import path from 'path';
 import os from 'os';
 import { EventEmitter } from 'events';
 
-const DEFAULT_DIR = path.join(os.homedir(), '.claude', 'projects');
+const DEFAULT_DIR = process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects');
+export { DEFAULT_DIR };
 const DEBOUNCE_MS = 16;
 
 export class JsonlWatcher extends EventEmitter {
@@ -265,6 +266,9 @@ export function vault({ projectsDir = DEFAULT_DIR, destDir = path.join(os.homedi
   return { copied, skipped };
 }
 
+export { Store, getStore, flattenEvent, blockText, DEFAULT_PROJECTS_DIR } from './store.js';
+export { createHistoryRouter } from './router.js';
+
 export async function rollup({ projectsDir, since = 0, out, format = 'ndjson' } = {}) {
   if (!out) throw new Error('rollup: out path required');
   const r = new JsonlReplayer(projectsDir);

package/src/router.js

@@ -0,0 +1,86 @@
+// Mountable Express router exposing /v1/history/* — mount at app.use('/', createHistoryRouter()).
+// Express is a peer dependency. Caller must `npm i express`.
+import { Store, getStore, DEFAULT_PROJECTS_DIR } from './store.js';
+
+function loadExpress() {
+  // Lazy import so ccsniff doesn't hard-require express for its other exports.
+  // Caller (e.g. agentgui) already has express in its deps.
+  // eslint-disable-next-line no-undef
+  return import('express').then(m => m.default || m);
+}
+
+export async function createHistoryRouter({ projectsDir, store: providedStore } = {}) {
+  const express = await loadExpress();
+  const router = express.Router();
+  const store = providedStore || getStore(projectsDir || DEFAULT_PROJECTS_DIR);
+
+  const corsHeaders = (res) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Cache-Control', 'no-cache');
+  };
+
+  router.use((req, res, next) => { corsHeaders(res); next(); });
+
+  router.get('/v1/history/snapshot', (req, res) => {
+    try { res.json(store.snapshot()); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  router.get('/v1/history/sessions', (req, res) => {
+    try { res.json({ sessions: store.sessions() }); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  router.get('/v1/history/sessions/:sid/events', (req, res) => {
+    try { res.json({ sid: req.params.sid, events: store.sessionEvents(req.params.sid) }); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  router.get('/v1/history/search', (req, res) => {
+    try {
+      const q = req.query.q || '';
+      const limit = parseInt(req.query.limit, 10) || 50;
+      const opts = { limit };
+      for (const k of ['role', 'type', 'project', 'sid']) {
+        if (req.query[k]) opts[k] = req.query[k];
+      }
+      const results = q ? store.search(q, opts) : [];
+      const hits = results.map(r => ({ sid: r.sid, snippet: r.snippet, score: r.score, ts: r.ts, role: r.role, type: r.type, project: r.project, text: r.text }));
+      res.json({ query: q, hits, results });
+    } catch (e) {
+      res.status(500).json({ error: { message: e.message } });
+    }
+  });
+
+  router.post('/v1/history/reindex', (req, res) => {
+    try { store.rebuildIndex(); res.json({ ok: true, at: store.lastBuilt }); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  router.get('/v1/history/stream', (req, res) => {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+    res.write('event: hello\ndata: {}\n\n');
+    store.sseClients.add(res);
+    req.on('close', () => store.sseClients.delete(res));
+  });
+
+  // Compatibility GET reindex (some clients may call GET).
+  router.get('/v1/history/reindex', (req, res) => {
+    try { store.rebuildIndex(); res.json({ ok: true, at: store.lastBuilt }); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  router.get('/v1/history', (req, res) => {
+    try { res.json(store.snapshot()); }
+    catch (e) { res.status(500).json({ error: { message: e.message } }); }
+  });
+
+  return router;
+}
+
+export { Store, getStore, DEFAULT_PROJECTS_DIR };

package/src/store.js

@@ -0,0 +1,294 @@
+// Shared store for both legacy /api/* (gui-server.js) and new /v1/history/* (router.js).
+import path from 'path';
+import os from 'os';
+import { JsonlReplayer, JsonlWatcher } from './index.js';
+import { buildIndex, search, snippet, tokenize } from './bm25.js';
+
+export const DEFAULT_PROJECTS_DIR =
+  process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects');
+
+export function blockText(b) {
+  if (!b) return '';
+  if (typeof b.text === 'string') return b.text;
+  if (typeof b.content === 'string') return b.content;
+  if (Array.isArray(b.content)) return b.content.map(c => c?.text || '').join('');
+  if (b.input) { try { return JSON.stringify(b.input); } catch { return ''; } }
+  return '';
+}
+
+export function flattenEvent(ev, idx) {
+  const c = ev.conversation || {};
+  const b = ev.block || {};
+  return {
+    i: idx,
+    ts: ev.timestamp || 0,
+    sid: c.id || '',
+    parent: c.parentSid || null,
+    cwd: c.cwd || '',
+    project: path.basename(c.cwd || ''),
+    isSubagent: !!c.isSubagent,
+    role: ev.role,
+    type: b.type || null,
+    tool: b.name || null,
+    text: blockText(b),
+    isError: !!b.is_error || ev.role === 'streaming_error',
+    isMeta: !!b.isMeta,
+    cost: b.total_cost_usd || null,
+    duration: b.duration_ms || null,
+    subtype: b.subtype || null,
+    model: b.model || null,
+  };
+}
+
+export class Store {
+  constructor(projectsDir) {
+    this.projectsDir = projectsDir || DEFAULT_PROJECTS_DIR;
+    this.events = [];
+    this.errors = [];
+    this.fileBytes = 0;
+    this.fileCount = 0;
+    this.index = null;
+    this.lastBuilt = 0;
+    this.watcher = null;
+    this.sseClients = new Set();
+    this.convs = new Map();
+  }
+
+  loadOnce() {
+    const r = new JsonlReplayer(this.projectsDir);
+    let i = 0;
+    r.on('conversation_created', ev => this.convs.set(ev.conversation.id, ev.conversation));
+    r.on('streaming_progress', ev => { this.events.push(flattenEvent(ev, i++)); });
+    r.on('streaming_error', ev => { this.errors.push({ ts: ev.timestamp, sid: ev.conversationId, error: ev.error, recoverable: ev.recoverable }); });
+    const stats = r.replay({});
+    this.fileCount = stats.files;
+    this.rebuildIndex();
+    return stats;
+  }
+
+  rebuildIndex() {
+    this.index = buildIndex(this.events, e => e.text);
+    this.lastBuilt = Date.now();
+  }
+
+  startLive() {
+    if (this.watcher) return;
+    this.watcher = new JsonlWatcher(this.projectsDir);
+    this.watcher.on('conversation_created', ev => {
+      this.convs.set(ev.conversation.id, ev.conversation);
+      this.broadcast('conversation', { conv: ev.conversation, ts: ev.timestamp });
+    });
+    this.watcher.on('streaming_progress', ev => {
+      const fl = flattenEvent(ev, this.events.length);
+      this.events.push(fl);
+      this.broadcast('event', { sid: fl.sid, payload: fl });
+    });
+    this.watcher.on('streaming_error', ev => {
+      const e = { ts: ev.timestamp, sid: ev.conversationId, error: ev.error, recoverable: ev.recoverable };
+      this.errors.push(e);
+      this.broadcast('error', e);
+    });
+    this.watcher.on('streaming_start', ev => this.broadcast('start', { sid: ev.conversationId, ts: ev.timestamp }));
+    this.watcher.on('streaming_complete', ev => this.broadcast('complete', { sid: ev.conversationId, ts: ev.timestamp }));
+    this.watcher.start();
+  }
+
+  stop() {
+    if (this.watcher) this.watcher.stop();
+    for (const r of this.sseClients) try { r.end(); } catch {}
+    this.sseClients.clear();
+  }
+
+  broadcast(kind, data) {
+    const payload = `event: ${kind}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const res of this.sseClients) { try { res.write(payload); } catch {} }
+  }
+
+  snapshot() {
+    const sids = new Set(), projects = new Set(), tools = new Map();
+    let earliest = Infinity, latest = 0, bytes = 0;
+    for (const e of this.events) {
+      sids.add(e.sid); if (e.project) projects.add(e.project);
+      if (e.tool) tools.set(e.tool, (tools.get(e.tool) || 0) + 1);
+      if (e.ts < earliest) earliest = e.ts;
+      if (e.ts > latest) latest = e.ts;
+      bytes += (e.text || '').length;
+    }
+    return {
+      events: this.events.length,
+      sessions: sids.size,
+      projects: projects.size,
+      tools: tools.size,
+      errors: this.errors.length,
+      files: this.fileCount,
+      bytes,
+      earliest: earliest === Infinity ? 0 : earliest,
+      latest,
+      dateRange: { earliest: earliest === Infinity ? 0 : earliest, latest },
+      indexedAt: this.lastBuilt,
+    };
+  }
+
+  sessions() {
+    const map = new Map();
+    for (const e of this.events) {
+      let s = map.get(e.sid);
+      if (!s) {
+        const conv = this.convs.get(e.sid) || {};
+        s = { sid: e.sid, title: conv.title || '', project: e.project, cwd: e.cwd, parent: e.parent, isSubagent: e.isSubagent, first: e.ts, last: e.ts, events: 0, tools: 0, userTurns: 0, cost: 0, errors: 0 };
+        map.set(e.sid, s);
+      }
+      s.events++;
+      if (e.ts < s.first) s.first = e.ts;
+      if (e.ts > s.last) s.last = e.ts;
+      if (e.type === 'tool_use') s.tools++;
+      if (e.role === 'user' && e.type === 'text') s.userTurns++;
+      if (e.cost) s.cost += e.cost;
+      if (e.isError) s.errors++;
+    }
+    return [...map.values()].sort((a, b) => b.last - a.last);
+  }
+
+  sessionEvents(sid) {
+    return this.events.filter(e => e.sid === sid);
+  }
+
+  projects() {
+    const map = new Map();
+    for (const e of this.events) {
+      if (!e.project) continue;
+      let p = map.get(e.project);
+      if (!p) { p = { project: e.project, sessions: new Set(), events: 0, tools: 0, last: 0, errors: 0, cost: 0 }; map.set(e.project, p); }
+      p.events++;
+      p.sessions.add(e.sid);
+      if (e.type === 'tool_use') p.tools++;
+      if (e.ts > p.last) p.last = e.ts;
+      if (e.cost) p.cost += e.cost;
+      if (e.isError) p.errors++;
+    }
+    return [...map.values()].map(p => ({ ...p, sessions: p.sessions.size })).sort((a, b) => b.last - a.last);
+  }
+
+  tools() {
+    const map = new Map();
+    for (const e of this.events) {
+      if (!e.tool) continue;
+      let t = map.get(e.tool);
+      if (!t) { t = { tool: e.tool, count: 0, sessions: new Set(), errors: 0, last: 0 }; map.set(e.tool, t); }
+      t.count++;
+      t.sessions.add(e.sid);
+      if (e.isError) t.errors++;
+      if (e.ts > t.last) t.last = e.ts;
+    }
+    return [...map.values()].map(t => ({ ...t, sessions: t.sessions.size })).sort((a, b) => b.count - a.count);
+  }
+
+  timeline(bucketMs = 3600_000) {
+    const buckets = new Map();
+    for (const e of this.events) {
+      const k = Math.floor(e.ts / bucketMs) * bucketMs;
+      let b = buckets.get(k);
+      if (!b) { b = { t: k, events: 0, tools: 0, errors: 0, sessions: new Set() }; buckets.set(k, b); }
+      b.events++;
+      if (e.type === 'tool_use') b.tools++;
+      if (e.isError) b.errors++;
+      b.sessions.add(e.sid);
+    }
+    return [...buckets.values()].map(b => ({ ...b, sessions: b.sessions.size })).sort((a, b) => a.t - b.t);
+  }
+
+  stats() {
+    const role = {}, type = {}, model = {};
+    let cost = 0, dur = 0, results = 0;
+    for (const e of this.events) {
+      role[e.role || '?'] = (role[e.role || '?'] || 0) + 1;
+      type[e.type || '?'] = (type[e.type || '?'] || 0) + 1;
+      if (e.model) model[e.model] = (model[e.model] || 0) + 1;
+      if (e.cost) { cost += e.cost; results++; }
+      if (e.duration) dur += e.duration;
+    }
+    return { role, type, model, totalCostUsd: cost, totalDurationMs: dur, results };
+  }
+
+  errorsList() { return this.errors.slice(-200).reverse(); }
+
+  subagents() {
+    const tree = new Map();
+    for (const e of this.events) {
+      if (!e.isSubagent) continue;
+      const parent = e.parent || 'orphan';
+      let p = tree.get(parent);
+      if (!p) { p = { parent, children: new Map() }; tree.set(parent, p); }
+      let c = p.children.get(e.sid);
+      if (!c) { c = { sid: e.sid, project: e.project, events: 0, last: 0 }; p.children.set(e.sid, c); }
+      c.events++;
+      if (e.ts > c.last) c.last = e.ts;
+    }
+    return [...tree.values()].map(p => ({ parent: p.parent, children: [...p.children.values()] }));
+  }
+
+  search(q, { limit = 50, role, type, project, sid } = {}) {
+    if (!this.index) this.rebuildIndex();
+    const hits = search(this.index, q, { limit: limit * 4 });
+    const out = [];
+    for (const h of hits) {
+      const e = this.events[h.i];
+      if (role && e.role !== role) continue;
+      if (type && e.type !== type) continue;
+      if (project && e.project !== project) continue;
+      if (sid && !e.sid.startsWith(sid)) continue;
+      out.push({ ...e, score: h.score, terms: h.terms, snippet: snippet(e.text, h.terms) });
+      if (out.length >= limit) break;
+    }
+    return out;
+  }
+
+  events_filtered({ role, type, project, sid, tool, since, until, limit = 200, offset = 0, q, grep, igrep, isMeta, isSubagent, isError, parent } = {}) {
+    let arr = this.events;
+    let greRe = null, igreRe = null;
+    try {
+      if (grep) greRe = new RegExp(grep, 'i');
+      if (igrep) igreRe = new RegExp(igrep, 'i');
+    } catch (e) {
+      return { total: 0, rows: [], error: `invalid regex: ${e.message}` };
+    }
+    if (q) {
+      const tokens = [...new Set(tokenize(q))];
+      if (tokens.length) {
+        arr = arr.filter(e => { const t = tokenize(e.text); return tokens.every(x => t.includes(x)); });
+      } else {
+        const needle = String(q).toLowerCase();
+        arr = arr.filter(e => (e.text || '').toLowerCase().includes(needle));
+      }
+    }
+    arr = arr.filter(e => {
+      if (role && e.role !== role) return false;
+      if (type && e.type !== type) return false;
+      if (project && e.project !== project) return false;
+      if (sid && !e.sid.startsWith(sid)) return false;
+      if (parent && e.parent !== parent) return false;
+      if (tool && e.tool !== tool) return false;
+      if (since && e.ts < since) return false;
+      if (until && e.ts > until) return false;
+      if (isMeta === true && !e.isMeta) return false;
+      if (isMeta === false && e.isMeta) return false;
+      if (isSubagent === true && !e.isSubagent) return false;
+      if (isSubagent === false && e.isSubagent) return false;
+      if (isError === true && !e.isError) return false;
+      if (isError === false && e.isError) return false;
+      if (greRe && !greRe.test(e.text || '')) return false;
+      if (igreRe && igreRe.test(e.text || '')) return false;
+      return true;
+    });
+    return { total: arr.length, rows: arr.slice(offset, offset + limit) };
+  }
+}
+
+let _shared = null;
+export function getStore(projectsDir) {
+  if (_shared) return _shared;
+  _shared = new Store(projectsDir);
+  _shared.loadOnce();
+  _shared.startLive();
+  return _shared;
+}