agentlytics 0.0.7 → 0.0.10

package/README.md

@@ -6,12 +6,12 @@
 
 <p align="center">
   <strong>Unified analytics for your AI coding agents</strong><br>
-  <sub>Cursor · Windsurf · Claude Code · VS Code Copilot · Zed · Antigravity · OpenCode · Gemini CLI · Copilot CLI · Cursor Agent</sub>
+  <sub>Cursor · Windsurf · Claude Code · VS Code Copilot · Zed · Antigravity · OpenCode · Codex · Gemini CLI · Copilot CLI · Cursor Agent · Command Code</sub>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/agentlytics"><img src="https://img.shields.io/npm/v/agentlytics?color=6366f1&label=npm" alt="npm"></a>
-  <a href="#supported-editors"><img src="https://img.shields.io/badge/editors-12-818cf8" alt="editors"></a>
+  <a href="#supported-editors"><img src="https://img.shields.io/badge/editors-14-818cf8" alt="editors"></a>
   <a href="#license"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen" alt="node"></a>
 </p>
@@ -32,6 +32,8 @@ npx agentlytics
 
 Opens at **http://localhost:4637**. Requires Node.js ≥ 18, macOS.
 
+For local development, run `npm run dev` from the repo root. That starts both the backend on `http://localhost:4637` and the Vite frontend on `http://localhost:5173`.
+
 ## Features
 
 - **Dashboard** — KPIs, activity heatmap, editor breakdown, coding streaks, token economy, peak hours, top models & tools
@@ -54,12 +56,16 @@ Opens at **http://localhost:4637**. Requires Node.js ≥ 18, macOS.
 | **VS Code Insiders** | `vscode-insiders` | ✅ | ✅ | ✅ | ✅ |
 | **Zed** | `zed` | ✅ | ✅ | ✅ | ❌ |
 | **OpenCode** | `opencode` | ✅ | ✅ | ✅ | ✅ |
+| **Codex** | `codex` | ✅ | ✅ | ✅ | ✅ |
 | **Gemini CLI** | `gemini-cli` | ✅ | ✅ | ✅ | ✅ |
 | **Copilot CLI** | `copilot-cli` | ✅ | ✅ | ✅ | ✅ |
 | **Cursor Agent** | `cursor-agent` | ✅ | ❌ | ❌ | ❌ |
+| **Command Code** | `commandcode` | ✅ | ✅ | ❌ | ❌ |
 
 > Windsurf, Windsurf Next, and Antigravity must be running during scan.
 
+Codex sessions are read from `${CODEX_HOME:-~/.codex}/sessions/**/*.jsonl`. Reasoning summaries may appear in transcripts when Codex records them in clear text, but encrypted reasoning content is not readable. Codex Desktop and CLI sessions are aggregated into one `codex` editor in analytics.
+
 ## How It Works
 
 ```

package/cache.js

@@ -106,6 +106,9 @@ const insertMsg = () => db.prepare(`
   INSERT INTO messages (chat_id, seq, role, content, model, input_tokens, output_tokens)
   VALUES (?, ?, ?, ?, ?, ?, ?)
 `);
+const updateChatBubbleCount = () => db.prepare(`
+  UPDATE chats SET bubble_count = ? WHERE id = ?
+`);
 
 function analyzeAndStore(chat) {
   if (chat.encrypted) return;
@@ -127,6 +130,7 @@ function analyzeAndStore(chat) {
   delTc.run(chat.composerId);
 
   const ins = insertMsg();
+  const updBubbleCount = updateChatBubbleCount();
   const insTc = db.prepare('INSERT INTO tool_calls (chat_id, tool_name, args_json, source, folder, timestamp) VALUES (?, ?, ?, ?, ?, ?)');
   const chatTs = chat.lastUpdatedAt || chat.createdAt || null;
 
@@ -174,6 +178,8 @@ function analyzeAndStore(chat) {
     ins.run(chat.composerId, seq++, msg.role, storedContent, msg._model || null, msg._inputTokens || null, msg._outputTokens || null);
   }
 
+  updBubbleCount.run(messages.length, chat.composerId);
+
   const insStat = insertStat();
   insStat.run(
     chat.composerId, stats.total, stats.user, stats.assistant, stats.tool, stats.system,
@@ -205,7 +211,7 @@ function scanAll(onProgress) {
         chat.composerId, chat.source, chat.name || null, chat.mode || null,
         chat.folder || null, chat.createdAt || null, chat.lastUpdatedAt || null,
         chat.encrypted ? 1 : 0, chat.bubbleCount || 0,
-        JSON.stringify({ _type: chat._type, _dbPath: chat._dbPath, _filePath: chat._filePath, _port: chat._port, _csrf: chat._csrf, _https: chat._https, _rootBlobId: chat._rootBlobId, _dataType: chat._dataType })
+        JSON.stringify({ _type: chat._type, _dbPath: chat._dbPath, _filePath: chat._filePath, _port: chat._port, _csrf: chat._csrf, _https: chat._https, _rootBlobId: chat._rootBlobId, _dataType: chat._dataType, _rawSource: chat._rawSource, _originator: chat._originator, _cliVersion: chat._cliVersion, _modelProvider: chat._modelProvider })
       );
     }
   });
@@ -256,15 +262,30 @@ function scanAll(onProgress) {
 // ============================================================
 
 function getCachedChats(opts = {}) {
-  let sql = 'SELECT * FROM chats WHERE 1=1';
+  let sql = 'SELECT c.*, cs.models AS _models FROM chats c LEFT JOIN chat_stats cs ON cs.chat_id = c.id WHERE 1=1';
   const params = [];
-  if (opts.editor) { sql += ' AND source LIKE ?'; params.push(`%${opts.editor}%`); }
-  if (opts.folder) { sql += ' AND folder LIKE ?'; params.push(`%${opts.folder}%`); }
-  if (opts.named !== false) { sql += ' AND (name IS NOT NULL OR bubble_count > 0)'; }
-  sql += ' ORDER BY last_updated_at DESC';
+  if (opts.editor) { sql += ' AND c.source LIKE ?'; params.push(`%${opts.editor}%`); }
+  if (opts.folder) { sql += ' AND c.folder LIKE ?'; params.push(`%${opts.folder}%`); }
+  if (opts.named !== false) { sql += ' AND (c.name IS NOT NULL OR c.bubble_count > 0)'; }
+  if (opts.dateFrom) { sql += ' AND COALESCE(c.last_updated_at, c.created_at) >= ?'; params.push(opts.dateFrom); }
+  if (opts.dateTo) { sql += ' AND COALESCE(c.last_updated_at, c.created_at) <= ?'; params.push(opts.dateTo); }
+  sql += ' ORDER BY c.last_updated_at DESC';
   if (opts.limit) { sql += ' LIMIT ?'; params.push(opts.limit); }
   if (opts.offset) { sql += ' OFFSET ?'; params.push(opts.offset); }
-  return db.prepare(sql).all(params);
+  const rows = db.prepare(sql).all(params);
+  for (const r of rows) {
+    r.top_model = null;
+    try {
+      const models = JSON.parse(r._models || '[]');
+      if (models.length > 0) {
+        const freq = {};
+        for (const m of models) freq[m] = (freq[m] || 0) + 1;
+        r.top_model = Object.entries(freq).sort((a, b) => b[1] - a[1])[0][0];
+      }
+    } catch {}
+    delete r._models;
+  }
+  return rows;
 }
 
 function countCachedChats(opts = {}) {
@@ -273,14 +294,20 @@ function countCachedChats(opts = {}) {
   if (opts.editor) { sql += ' AND source LIKE ?'; params.push(`%${opts.editor}%`); }
   if (opts.folder) { sql += ' AND folder LIKE ?'; params.push(`%${opts.folder}%`); }
   if (opts.named !== false) { sql += ' AND (name IS NOT NULL OR bubble_count > 0)'; }
+  if (opts.dateFrom) { sql += ' AND COALESCE(last_updated_at, created_at) >= ?'; params.push(opts.dateFrom); }
+  if (opts.dateTo) { sql += ' AND COALESCE(last_updated_at, created_at) <= ?'; params.push(opts.dateTo); }
   return db.prepare(sql).get(params).cnt;
 }
 
 function getCachedOverview(opts = {}) {
-  const editorFilter = opts.editor || null;
-  const where = editorFilter ? ' WHERE source = ?' : '';
-  const whereAnd = editorFilter ? ' AND source = ?' : '';
-  const params = editorFilter ? [editorFilter] : [];
+  // Build conditions dynamically to support editor + date range filters
+  const conditions = [];
+  const params = [];
+  if (opts.editor) { conditions.push('source = ?'); params.push(opts.editor); }
+  if (opts.dateFrom) { conditions.push('COALESCE(last_updated_at, created_at) >= ?'); params.push(opts.dateFrom); }
+  if (opts.dateTo) { conditions.push('COALESCE(last_updated_at, created_at) <= ?'); params.push(opts.dateTo); }
+  const where = conditions.length > 0 ? ' WHERE ' + conditions.join(' AND ') : '';
+  const whereAnd = conditions.length > 0 ? ' AND ' + conditions.join(' AND ') : '';
 
   const totalChats = db.prepare(`SELECT COUNT(*) as cnt FROM chats${where}`).get(...params).cnt;
   // Editors list is always unfiltered so the breakdown remains visible
@@ -338,9 +365,12 @@ function getCachedOverview(opts = {}) {
 }
 
 function getCachedDailyActivity(opts = {}) {
-  const editorFilter = opts.editor || null;
-  const whereAnd = editorFilter ? ' AND source = ?' : '';
-  const params = editorFilter ? [editorFilter] : [];
+  const conditions = [];
+  const params = [];
+  if (opts.editor) { conditions.push('source = ?'); params.push(opts.editor); }
+  if (opts.dateFrom) { conditions.push('COALESCE(last_updated_at, created_at) >= ?'); params.push(opts.dateFrom); }
+  if (opts.dateTo) { conditions.push('COALESCE(last_updated_at, created_at) <= ?'); params.push(opts.dateTo); }
+  const whereAnd = conditions.length > 0 ? ' AND ' + conditions.join(' AND ') : '';
   const rows = db.prepare(`
     SELECT
       date(COALESCE(last_updated_at, created_at)/1000, 'unixepoch', 'localtime') as day,
@@ -369,6 +399,8 @@ function getCachedDeepAnalytics(opts = {}) {
   const params = [];
   if (opts.editor) { sql += ' AND c.source LIKE ?'; params.push(`%${opts.editor}%`); }
   if (opts.folder) { sql += ' AND c.folder = ?'; params.push(opts.folder); }
+  if (opts.dateFrom) { sql += ' AND COALESCE(c.last_updated_at, c.created_at) >= ?'; params.push(opts.dateFrom); }
+  if (opts.dateTo) { sql += ' AND COALESCE(c.last_updated_at, c.created_at) <= ?'; params.push(opts.dateTo); }
   sql += ' ORDER BY cs.analyzed_at DESC';
   if (opts.limit) { sql += ' LIMIT ?'; params.push(opts.limit); }
 
@@ -454,16 +486,22 @@ function getCachedChat(id) {
   };
 }
 
-function getCachedProjects() {
+function getCachedProjects(opts = {}) {
+  // Build date filter
+  let dateFilter = '';
+  const dateParams = [];
+  if (opts.dateFrom) { dateFilter += ' AND COALESCE(last_updated_at, created_at) >= ?'; dateParams.push(opts.dateFrom); }
+  if (opts.dateTo) { dateFilter += ' AND COALESCE(last_updated_at, created_at) <= ?'; dateParams.push(opts.dateTo); }
+
   // All unique projects with their stats
   const projects = db.prepare(`
     SELECT folder, source, COUNT(*) as count,
       MIN(COALESCE(last_updated_at, created_at)) as first_seen,
       MAX(COALESCE(last_updated_at, created_at)) as last_seen
-    FROM chats WHERE folder IS NOT NULL
+    FROM chats WHERE folder IS NOT NULL${dateFilter}
     GROUP BY folder, source
     ORDER BY folder, count DESC
-  `).all();
+  `).all(...dateParams);
 
   // Group by folder
   const map = {};
@@ -478,12 +516,13 @@ function getCachedProjects() {
   // For each project, get models and tools from chat_stats
   const result = [];
   for (const [folder, proj] of Object.entries(map)) {
+    const statsDateFilter = dateFilter.replace(/COALESCE\(last_updated_at/g, 'COALESCE(c.last_updated_at').replace(/created_at\)/g, 'c.created_at)');
     const stats = db.prepare(`
       SELECT cs.models, cs.tool_calls, cs.total_messages, cs.total_input_tokens, cs.total_output_tokens,
              cs.total_user_chars, cs.total_assistant_chars, cs.total_cache_read, cs.total_cache_write
       FROM chat_stats cs JOIN chats c ON cs.chat_id = c.id
-      WHERE c.folder = ?
-    `).all(folder);
+      WHERE c.folder = ?${statsDateFilter}
+    `).all(folder, ...dateParams);
 
     const modelFreq = {};
     const toolFreq = {};
@@ -585,7 +624,7 @@ async function scanAllAsync(onProgress) {
         chat.composerId, chat.source, chat.name || null, chat.mode || null,
         chat.folder || null, chat.createdAt || null, chat.lastUpdatedAt || null,
         chat.encrypted ? 1 : 0, chat.bubbleCount || 0,
-        JSON.stringify({ _type: chat._type, _dbPath: chat._dbPath, _filePath: chat._filePath, _port: chat._port, _csrf: chat._csrf, _https: chat._https, _rootBlobId: chat._rootBlobId, _dataType: chat._dataType })
+        JSON.stringify({ _type: chat._type, _dbPath: chat._dbPath, _filePath: chat._filePath, _port: chat._port, _csrf: chat._csrf, _https: chat._https, _rootBlobId: chat._rootBlobId, _dataType: chat._dataType, _rawSource: chat._rawSource, _originator: chat._originator, _cliVersion: chat._cliVersion, _modelProvider: chat._modelProvider })
       );
     }
   });
@@ -637,10 +676,14 @@ async function resetAndRescanAsync(onProgress) {
 }
 
 function getCachedDashboardStats(opts = {}) {
-  const editorFilter = opts.editor || null;
-  const where = editorFilter ? ' WHERE source = ?' : '';
-  const whereAnd = editorFilter ? ' AND source = ?' : '';
-  const params = editorFilter ? [editorFilter] : [];
+  // Build conditions dynamically to support editor + date range filters
+  const conditions = [];
+  const params = [];
+  if (opts.editor) { conditions.push('source = ?'); params.push(opts.editor); }
+  if (opts.dateFrom) { conditions.push('COALESCE(last_updated_at, created_at) >= ?'); params.push(opts.dateFrom); }
+  if (opts.dateTo) { conditions.push('COALESCE(last_updated_at, created_at) <= ?'); params.push(opts.dateTo); }
+  const where = conditions.length > 0 ? ' WHERE ' + conditions.join(' AND ') : '';
+  const whereAnd = conditions.length > 0 ? ' AND ' + conditions.join(' AND ') : '';
 
   // ── Hourly distribution (aggregate across all days) ──
   const hourlyRows = db.prepare(`

package/editors/codex.js

@@ -0,0 +1,453 @@
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const name = 'codex';
+const DEFAULT_CODEX_HOME = path.join(os.homedir(), '.codex');
+const SESSION_SUBDIR = 'sessions';
+const MAX_TOOL_RESULT_PREVIEW = 500;
+
+function getChats() {
+  const sessionsDir = getSessionsDir();
+  if (!fs.existsSync(sessionsDir)) return [];
+
+  const chats = [];
+  for (const filePath of walkJsonlFiles(sessionsDir)) {
+    const chat = readChatMetadata(filePath);
+    if (chat) chats.push(chat);
+  }
+  return chats;
+}
+
+function getMessages(chat) {
+  const filePath = chat && chat._filePath;
+  if (!filePath || !fs.existsSync(filePath)) return [];
+  return parseSessionMessages(filePath);
+}
+
+function getSessionsDir() {
+  const codexHome = process.env.CODEX_HOME && process.env.CODEX_HOME.trim()
+    ? path.resolve(process.env.CODEX_HOME.trim())
+    : DEFAULT_CODEX_HOME;
+  return path.join(codexHome, SESSION_SUBDIR);
+}
+
+function walkJsonlFiles(dir) {
+  const results = [];
+  const stack = [dir];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  return results.sort();
+}
+
+function readChatMetadata(filePath) {
+  const lines = readLines(filePath);
+  if (lines.length === 0) return null;
+
+  const first = safeParseJson(lines[0]);
+  if (!first || first.type !== 'session_meta' || !first.payload) return null;
+
+  let title = null;
+  for (let i = 1; i < lines.length; i++) {
+    const entry = safeParseJson(lines[i]);
+    if (!entry || entry.type !== 'response_item' || !entry.payload) continue;
+    const payload = entry.payload;
+    if (payload.type !== 'message' || payload.role !== 'user') continue;
+    const text = extractUserText(payload.content);
+    if (!text || isBootstrapMessage(text)) continue;
+    title = cleanPrompt(text);
+    break;
+  }
+
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    stat = null;
+  }
+
+  const payload = first.payload;
+  return {
+    source: 'codex',
+    composerId: payload.id || path.basename(filePath, '.jsonl'),
+    name: title,
+    createdAt: toTimestamp(payload.timestamp) || (stat ? stat.birthtimeMs : null),
+    lastUpdatedAt: stat ? stat.mtimeMs : null,
+    mode: 'codex',
+    folder: payload.cwd || null,
+    encrypted: false,
+    bubbleCount: 0,
+    _filePath: filePath,
+    _rawSource: payload.source || null,
+    _originator: payload.originator || null,
+    _cliVersion: payload.cli_version || null,
+    _modelProvider: payload.model_provider || null,
+  };
+}
+
+function parseSessionMessages(filePath) {
+  const lines = readLines(filePath);
+  const messages = [];
+
+  let currentModel = null;
+  let previousTotals = null;
+  let currentTurn = createTurnState();
+  let turnHasStarted = false;
+  const toolNamesByCallId = new Map();
+
+  function flushTurn() {
+    const hasAssistantContent = currentTurn.parts.length > 0;
+    const hasTokens = currentTurn.inputTokens > 0 || currentTurn.outputTokens > 0 || currentTurn.cacheRead > 0;
+    const hasTools = currentTurn.toolCalls.length > 0;
+    if (!hasAssistantContent && !hasTokens && !hasTools) {
+      currentTurn = createTurnState();
+      toolNamesByCallId.clear();
+      return;
+    }
+
+    messages.push(composeAssistantMessage(currentTurn));
+    currentTurn = createTurnState();
+    toolNamesByCallId.clear();
+  }
+
+  for (const line of lines) {
+    const entry = safeParseJson(line);
+    if (!entry) continue;
+
+    if (entry.type === 'turn_context') {
+      if (turnHasStarted) flushTurn();
+      turnHasStarted = true;
+      const model = extractModel(entry.payload);
+      if (model) {
+        currentModel = model;
+        currentTurn.model = model;
+      }
+      continue;
+    }
+
+    if (entry.type === 'response_item' && entry.payload) {
+      const payload = entry.payload;
+
+      if (payload.type === 'message') {
+        if (payload.role === 'user') {
+          const text = extractUserText(payload.content);
+          if (!text || isBootstrapMessage(text)) continue;
+          if (turnHasStarted) flushTurn();
+          messages.push({ role: 'user', content: text });
+        } else if (payload.role === 'assistant') {
+          const text = extractAssistantText(payload.content);
+          if (text) currentTurn.parts.push(text);
+          if (!currentTurn.model && currentModel) currentTurn.model = currentModel;
+        } else if (payload.role === 'system') {
+          const text = extractAssistantText(payload.content);
+          if (text) messages.push({ role: 'system', content: text });
+        }
+        continue;
+      }
+
+      if (payload.type === 'reasoning') {
+        const summary = extractReasoningSummary(payload);
+        if (summary) currentTurn.parts.push(summary);
+        continue;
+      }
+
+      if (isToolCallPayload(payload.type)) {
+        const toolCall = normalizeToolCall(payload);
+        currentTurn.parts.push(toolCall.line);
+        currentTurn.toolCalls.push({ name: toolCall.name, args: toolCall.args });
+        if (payload.call_id) toolNamesByCallId.set(payload.call_id, toolCall.name);
+        continue;
+      }
+
+      if (isToolOutputPayload(payload.type)) {
+        const lineText = normalizeToolResult(payload, toolNamesByCallId.get(payload.call_id));
+        if (lineText) currentTurn.parts.push(lineText);
+        continue;
+      }
+
+      continue;
+    }
+
+    if (entry.type === 'event_msg' && entry.payload && entry.payload.type === 'token_count') {
+      const tokenInfo = entry.payload.info || {};
+      const lastUsage = normalizeRawUsage(tokenInfo.last_token_usage);
+      const totalUsage = normalizeRawUsage(tokenInfo.total_token_usage);
+
+      let rawUsage = lastUsage;
+      if (!rawUsage && totalUsage) rawUsage = subtractRawUsage(totalUsage, previousTotals);
+      if (totalUsage) previousTotals = totalUsage;
+      if (!rawUsage) continue;
+
+      const delta = convertToDelta(rawUsage);
+      if (delta.inputTokens === 0 && delta.outputTokens === 0 && delta.cacheRead === 0) continue;
+
+      currentTurn.inputTokens += delta.inputTokens;
+      currentTurn.outputTokens += delta.outputTokens;
+      currentTurn.cacheRead += delta.cacheRead;
+
+      const model = extractModel(tokenInfo) || extractModel(entry.payload);
+      if (model) {
+        currentModel = model;
+        currentTurn.model = model;
+      } else if (!currentTurn.model && currentModel) {
+        currentTurn.model = currentModel;
+      }
+    }
+  }
+
+  if (turnHasStarted) flushTurn();
+
+  return messages;
+}
+
+function createTurnState() {
+  return {
+    parts: [],
+    toolCalls: [],
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheRead: 0,
+    model: null,
+  };
+}
+
+function composeAssistantMessage(turn) {
+  const content = turn.parts.join('\n') || '[assistant activity]';
+  return {
+    role: 'assistant',
+    content,
+    _model: turn.model || undefined,
+    _inputTokens: turn.inputTokens || undefined,
+    _outputTokens: turn.outputTokens || undefined,
+    _cacheRead: turn.cacheRead || undefined,
+    _toolCalls: turn.toolCalls.length > 0 ? turn.toolCalls : undefined,
+  };
+}
+
+function extractUserText(content) {
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((item) => item && item.type === 'input_text' && typeof item.text === 'string')
+    .map((item) => item.text.trim())
+    .filter(Boolean)
+    .join('\n')
+    .trim();
+}
+
+function extractAssistantText(content) {
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((item) => item && item.type === 'output_text' && typeof item.text === 'string')
+    .map((item) => item.text.trim())
+    .filter(Boolean)
+    .join('\n')
+    .trim();
+}
+
+function extractReasoningSummary(payload) {
+  if (!Array.isArray(payload.summary)) return '';
+  return payload.summary
+    .filter((item) => item && typeof item.text === 'string' && item.text.trim())
+    .map((item) => `[thinking] ${item.text.trim()}`)
+    .join('\n')
+    .trim();
+}
+
+function isBootstrapMessage(text) {
+  const trimmed = text.trim();
+  return trimmed.startsWith('<user_instructions>') || trimmed.startsWith('<environment_context>');
+}
+
+function cleanPrompt(text) {
+  return text.replace(/\s+/g, ' ').trim().substring(0, 120) || null;
+}
+
+function isToolCallPayload(type) {
+  return type === 'function_call' || type === 'custom_tool_call' || type === 'web_search_call';
+}
+
+function isToolOutputPayload(type) {
+  return type === 'function_call_output' || type === 'custom_tool_call_output';
+}
+
+function normalizeToolCall(payload) {
+  const name = payload.name || (payload.type === 'web_search_call' ? 'web_search' : 'tool');
+  const args = parseToolArgs(payload);
+  const argKeys = Object.keys(args).join(', ');
+  return {
+    name,
+    args,
+    line: `[tool-call: ${name}(${argKeys})]`,
+  };
+}
+
+function normalizeToolResult(payload, fallbackName) {
+  const name = payload.name || fallbackName || 'tool';
+  const preview = previewToolOutput(payload.output);
+  return preview ? `[tool-result: ${name}] ${preview}` : `[tool-result: ${name}]`;
+}
+
+function parseToolArgs(payload) {
+  if (payload.type === 'function_call') {
+    return parseJsonRecord(payload.arguments);
+  }
+  if (payload.type === 'custom_tool_call') {
+    return { input: truncateSingleLine(String(payload.input || ''), 300) };
+  }
+  if (payload.type === 'web_search_call') {
+    return parseJsonRecord(payload.arguments || payload.input || payload.query);
+  }
+  return {};
+}
+
+function previewToolOutput(output) {
+  if (output == null) return '';
+  let value = output;
+  if (typeof value === 'string') {
+    const parsed = safeParseJson(value);
+    if (parsed && typeof parsed === 'object' && typeof parsed.output === 'string') {
+      value = parsed.output;
+    } else {
+      value = value;
+    }
+  } else if (typeof value === 'object') {
+    value = JSON.stringify(value);
+  } else {
+    value = String(value);
+  }
+
+  const trimmed = String(value).trim();
+  if (!trimmed) return '';
+  return truncateSingleLine(trimmed, MAX_TOOL_RESULT_PREVIEW);
+}
+
+function truncateSingleLine(text, maxLen) {
+  const oneLine = String(text).replace(/\s+/g, ' ').trim();
+  return oneLine.length > maxLen ? oneLine.substring(0, maxLen) + '…' : oneLine;
+}
+
+function parseJsonRecord(value) {
+  if (value == null) return {};
+  if (typeof value === 'object' && !Array.isArray(value)) return value;
+  if (typeof value !== 'string') return {};
+  const parsed = safeParseJson(value);
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+}
+
+function normalizeRawUsage(value) {
+  if (!value || typeof value !== 'object') return null;
+  const input = ensureNumber(value.input_tokens);
+  const cached = ensureNumber(value.cached_input_tokens != null ? value.cached_input_tokens : value.cache_read_input_tokens);
+  const output = ensureNumber(value.output_tokens);
+  const total = ensureNumber(value.total_tokens);
+  return {
+    input_tokens: input,
+    cached_input_tokens: cached,
+    output_tokens: output,
+    total_tokens: total > 0 ? total : input + output,
+  };
+}
+
+function subtractRawUsage(current, previous) {
+  return {
+    input_tokens: Math.max(current.input_tokens - (previous ? previous.input_tokens : 0), 0),
+    cached_input_tokens: Math.max(current.cached_input_tokens - (previous ? previous.cached_input_tokens : 0), 0),
+    output_tokens: Math.max(current.output_tokens - (previous ? previous.output_tokens : 0), 0),
+    total_tokens: Math.max(current.total_tokens - (previous ? previous.total_tokens : 0), 0),
+  };
+}
+
+function convertToDelta(raw) {
+  return {
+    inputTokens: raw.input_tokens,
+    cacheRead: Math.min(raw.cached_input_tokens, raw.input_tokens),
+    outputTokens: raw.output_tokens,
+    totalTokens: raw.total_tokens > 0 ? raw.total_tokens : raw.input_tokens + raw.output_tokens,
+  };
+}
+
+function extractModel(value) {
+  if (!value || typeof value !== 'object') return null;
+
+  const direct = asNonEmptyString(value.model)
+    || asNonEmptyString(value.model_name);
+  if (direct) return direct;
+
+  if (value.info && typeof value.info === 'object') {
+    const infoModel = extractModel(value.info);
+    if (infoModel) return infoModel;
+  }
+
+  if (value.metadata && typeof value.metadata === 'object') {
+    const metadataModel = extractModel(value.metadata);
+    if (metadataModel) return metadataModel;
+  }
+
+  return null;
+}
+
+function asNonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function ensureNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function toTimestamp(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function readLines(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8').split(/\r?\n/).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function safeParseJson(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  name,
+  getChats,
+  getMessages,
+  _test: {
+    getSessionsDir,
+    readChatMetadata,
+    parseSessionMessages,
+    normalizeRawUsage,
+    subtractRawUsage,
+    convertToDelta,
+    extractModel,
+    isBootstrapMessage,
+    previewToolOutput,
+  },
+};