agentquad 0.3.0

package/src/transcripts/indexer.js

@@ -0,0 +1,34 @@
+import { parseTranscriptFile } from './scanner.js'
+
+/**
+ * Parse + upsert a transcript file and its FTS rows.
+ * Returns the row (with id) or null on parse fail.
+ */
+export async function indexFile(db, { tool, jsonlPath, size, mtime }) {
+  let parsed
+  try { parsed = await parseTranscriptFile(tool, jsonlPath) }
+  catch (e) { return null }
+  const u = parsed.usage || {}
+  const row = db.upsertTranscriptFile({
+    tool,
+    nativeId: parsed.nativeId,
+    cwd: parsed.cwd,
+    jsonlPath,
+    size,
+    mtime,
+    startedAt: parsed.startedAt,
+    endedAt: parsed.endedAt,
+    firstUserPrompt: parsed.firstUserPrompt,
+    turnCount: parsed.turnCount,
+    inputTokens: u.inputTokens ?? null,
+    outputTokens: u.outputTokens ?? null,
+    cacheReadTokens: u.cacheReadTokens ?? null,
+    cacheCreationTokens: u.cacheCreationTokens ?? null,
+    primaryModel: u.primaryModel ?? null,
+    activeMs: u.activeMs ?? null,
+  })
+  if (row && parsed.turns?.length) {
+    db.writeFtsTurns(row.id, parsed.turns)
+  }
+  return row
+}

package/src/transcripts/matcher.js

@@ -0,0 +1,70 @@
+/**
+ * Three-gate auto-bind:
+ *  - same cwd
+ *  - startedAt within ±WINDOW_MS of an orphan AiSession.startedAt
+ *  - first_user_prompt[:100] == orphanSession.prompt[:100]
+ *
+ * Orphan = an AiSession on a todo that has no native_session_id and no completed_at.
+ * Greedy match by |Δt| ascending; ties → skip (avoid mis-bind).
+ */
+export const WINDOW_MS = 60_000
+const PROMPT_PREFIX_LEN = 100
+
+function norm(s) { return String(s || '').trim().slice(0, PROMPT_PREFIX_LEN) }
+
+export function collectOrphans(todos) {
+  const orphans = []
+  for (const todo of todos) {
+    const sessions = Array.isArray(todo.aiSessions) ? todo.aiSessions : (todo.aiSession ? [todo.aiSession] : [])
+    for (const s of sessions) {
+      if (!s) continue
+      if (s.nativeSessionId) continue
+      if (!s.startedAt) continue
+      orphans.push({
+        todoId: todo.id,
+        sessionId: s.sessionId,
+        tool: s.tool,
+        cwd: s.cwd ?? todo.workDir ?? null,
+        startedAt: s.startedAt,
+        prompt: norm(s.prompt),
+        claimed: false,
+      })
+    }
+  }
+  return orphans
+}
+
+export function autoMatch(unboundFiles, orphans) {
+  const pairs = []
+  const candidates = []
+  for (const f of unboundFiles) {
+    if (!f.cwd || !f.started_at || !f.first_user_prompt) continue
+    for (const o of orphans) {
+      if (o.tool !== f.tool) continue
+      if (o.cwd !== f.cwd) continue
+      if (norm(f.first_user_prompt) !== o.prompt) continue
+      const dt = Math.abs(f.started_at - o.startedAt)
+      if (dt > WINDOW_MS) continue
+      candidates.push({ file: f, orphan: o, dt })
+    }
+  }
+  candidates.sort((a, b) => a.dt - b.dt)
+  const usedFiles = new Set()
+  const usedOrphans = new Set()
+  const tieReject = new Set()
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i]
+    const nxt = candidates[i + 1]
+    if (nxt && nxt.file.id === c.file.id && nxt.dt === c.dt && nxt.orphan.sessionId !== c.orphan.sessionId) {
+      tieReject.add(c.file.id)
+      while (i + 1 < candidates.length && candidates[i + 1].file.id === c.file.id) i++
+      continue
+    }
+    if (usedFiles.has(c.file.id) || usedOrphans.has(c.orphan.sessionId)) continue
+    if (tieReject.has(c.file.id)) continue
+    usedFiles.add(c.file.id)
+    usedOrphans.add(c.orphan.sessionId)
+    pairs.push({ fileId: c.file.id, todoId: c.orphan.todoId, sessionId: c.orphan.sessionId, nativeId: c.file.native_id })
+  }
+  return pairs
+}

package/src/transcripts/scanner.js

@@ -0,0 +1,259 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import readline from 'node:readline'
+import { extractUsage } from '../usage-parser.js'
+import { normalizeContent, blockToText } from './blocks.js'
+
+export const DEFAULT_CLAUDE_DIR = path.join(os.homedir(), '.claude', 'projects')
+export const DEFAULT_CODEX_DIR = path.join(os.homedir(), '.codex', 'sessions')
+export const DEFAULT_CURSOR_DIR = path.join(os.homedir(), '.cursor', 'projects')
+
+function walkJsonl(root) {
+  const out = []
+  function walk(dir) {
+    let entries
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const ent of entries) {
+      const p = path.join(dir, ent.name)
+      if (ent.isDirectory()) walk(p)
+      else if (ent.isFile() && ent.name.endsWith('.jsonl')) out.push(p)
+    }
+  }
+  walk(root)
+  return out
+}
+
+function safeStat(p) { try { return fs.statSync(p) } catch { return null } }
+
+function decodeClaudeCwdFromDir(dirName) {
+  // Claude 目录名用 '-' 替换路径分隔符：'-Users-liuzhenhua-Desktop-code' → '/Users/liuzhenhua/Desktop/code'
+  if (!dirName.startsWith('-')) return null
+  return dirName.replace(/-/g, '/')
+}
+
+function decodeCursorCwdFromDir(dirName) {
+  // cursor: 'Users-liuzhenhua-Desktop-foo' → '/Users/liuzhenhua/Desktop/foo'
+  // 'private-tmp-x' → '/private/tmp/x'
+  // 跳过特殊命名（'empty-window'、纯数字 workspaceId 等）
+  if (!dirName) return null
+  if (dirName === 'empty-window') return null
+  if (/^\d+$/.test(dirName)) return null
+  return '/' + dirName.replace(/-/g, '/')
+}
+
+async function parseClaudeFile(filePath, opts = {}) {
+  const preview = Boolean(opts.preview)
+  const rl = readline.createInterface({ input: fs.createReadStream(filePath, 'utf8'), crlfDelay: Infinity })
+  let nativeId = null
+  let cwd = null
+  let startedAt = null
+  let endedAt = null
+  let firstUserPrompt = null
+  let turnCount = 0
+  const turns = []
+  const rawLines = []
+  for await (const line of rl) {
+    if (!line.trim()) continue
+    rawLines.push(line)
+    let j
+    try { j = JSON.parse(line) } catch { continue }
+    if (!nativeId && j.sessionId) nativeId = j.sessionId
+    if (!cwd && j.cwd) cwd = j.cwd
+    const ts = j.timestamp ? Date.parse(j.timestamp) : null
+    if (ts) {
+      if (!startedAt || ts < startedAt) startedAt = ts
+      if (!endedAt || ts > endedAt) endedAt = ts
+    }
+    // preview 模式：剔除 isMeta（local-command-caveat 等噪音）与非 user/assistant 类型。
+    // 注意：不能过滤 isSidechain —— subagent transcript 文件全部是 sidechain，
+    // 过滤后会变成空预览（与索引时 turn_count 不一致）。
+    if (preview) {
+      if (j.isMeta) continue
+      if (j.type !== 'user' && j.type !== 'assistant') continue
+    }
+    const role = j.message?.role || j.type || j.role
+    const msg = j.message
+    let blocks
+    if (typeof msg === 'string') blocks = [{ type: 'text', text: msg }]
+    else blocks = normalizeContent(msg?.content)
+    const parts = []
+    for (const blk of blocks) {
+      const piece = blockToText(blk, { includeToolUse: preview, includeToolResult: preview, toolResultMaxChars: 300 })
+      if (piece) parts.push(piece)
+    }
+    const content = parts.join('\n').trim()
+    if (!content) continue
+    turnCount++
+    turns.push({ role: role || 'raw', content })
+    if (!firstUserPrompt && (role === 'user' || msg?.role === 'user')) {
+      firstUserPrompt = content.slice(0, 200)
+    }
+  }
+  if (!cwd) {
+    const parent = path.basename(path.dirname(filePath))
+    cwd = decodeClaudeCwdFromDir(parent)
+  }
+  const usage = extractUsage('claude', rawLines, {})
+  return { nativeId, cwd, startedAt, endedAt, firstUserPrompt, turnCount, turns, usage }
+}
+
+// eslint-disable-next-line no-unused-vars
+async function parseCursorFile(filePath, _opts = {}) {
+  // cursor jsonl 格式：每行 {"role":"user|assistant","message":{"content":[...]}}
+  // 没有顶层 timestamp / sessionId / cwd，需要从路径反推。
+  //   ~/.cursor/projects/<encoded-cwd>/agent-transcripts/<chatId>/<chatId>.jsonl
+  const rl = readline.createInterface({ input: fs.createReadStream(filePath, 'utf8'), crlfDelay: Infinity })
+  let firstUserPrompt = null
+  let turnCount = 0
+  const turns = []
+  const rawLines = []
+  for await (const line of rl) {
+    if (!line.trim()) continue
+    rawLines.push(line)
+    let j
+    try { j = JSON.parse(line) } catch { continue }
+    const role = j.role || j.message?.role
+    const content = j.message?.content
+    let text = ''
+    if (typeof content === 'string') text = content
+    else if (Array.isArray(content)) {
+      // 块格式同 claude：{type:'text',text}/{type:'tool_use',name,input}/{type:'tool_result',...}
+      const parts = []
+      for (const blk of content) {
+        if (!blk || typeof blk !== 'object') continue
+        if (blk.type === 'text' && blk.text) parts.push(String(blk.text))
+        else if (blk.type === 'tool_use') {
+          const name = blk.name || 'tool'
+          const input = blk.input || {}
+          const summary = input.command || input.file_path || input.path || input.url || input.pattern || input.query || input.description
+          parts.push(`🔧 ${name}${summary ? ': ' + String(summary).slice(0, 200) : ''}`)
+        }
+      }
+      text = parts.join('\n').trim()
+    }
+    if (!text) continue
+    turnCount++
+    turns.push({ role: role || 'raw', content: text })
+    if (!firstUserPrompt && role === 'user') firstUserPrompt = text.slice(0, 200)
+  }
+  // chatId = 文件名（去 .jsonl）；cwd 从父目录的父目录反编码
+  const chatId = path.basename(filePath, '.jsonl')
+  const grandparent = path.basename(path.dirname(path.dirname(path.dirname(filePath))))
+  const cwd = decodeCursorCwdFromDir(grandparent)
+  const st = safeStat(filePath)
+  const startedAt = st?.birthtimeMs ? Math.floor(st.birthtimeMs) : (st?.mtimeMs ? Math.floor(st.mtimeMs) : null)
+  const endedAt = st?.mtimeMs ? Math.floor(st.mtimeMs) : null
+  return { nativeId: chatId, cwd, startedAt, endedAt, firstUserPrompt, turnCount, turns, usage: null }
+}
+
+function safeParseJson(s) {
+  if (typeof s !== 'string') return s
+  try { return JSON.parse(s) } catch { return null }
+}
+
+async function parseCodexFile(filePath, opts = {}) {
+  const preview = Boolean(opts.preview)
+  const rl = readline.createInterface({ input: fs.createReadStream(filePath, 'utf8'), crlfDelay: Infinity })
+  let nativeId = null
+  let cwd = null
+  let startedAt = null
+  let endedAt = null
+  let firstUserPrompt = null
+  let turnCount = 0
+  const turns = []
+  const rawLines = []
+  for await (const line of rl) {
+    if (!line.trim()) continue
+    rawLines.push(line)
+    let j
+    try { j = JSON.parse(line) } catch { continue }
+    const ts = j.timestamp ? Date.parse(j.timestamp) : null
+    if (ts) {
+      if (!startedAt || ts < startedAt) startedAt = ts
+      if (!endedAt || ts > endedAt) endedAt = ts
+    }
+    if (j.type === 'session_meta' && j.payload) {
+      if (!nativeId && j.payload.id) nativeId = j.payload.id
+      if (!cwd && j.payload.cwd) cwd = j.payload.cwd
+      if (j.payload.timestamp) {
+        const t = Date.parse(j.payload.timestamp)
+        if (t && (!startedAt || t < startedAt)) startedAt = t
+      }
+      continue
+    }
+    if (preview && j.type === 'event_msg') continue   // task_started/task_complete/error 等噪音
+
+    const payload = j.payload || j
+    let role
+    let blocks = []
+
+    if (payload.type === 'reasoning') {
+      // 思考块默认隐藏，和 Claude thinking 行为一致
+      continue
+    } else if (preview && payload.type === 'function_call') {
+      role = 'tool_use'
+      blocks = [{ type: 'tool_use', name: payload.name, input: safeParseJson(payload.arguments) }]
+    } else if (preview && payload.type === 'function_call_output') {
+      role = 'tool_result'
+      const outRaw = payload.output ?? payload.content ?? ''
+      // codex 的 output 有时是字符串，有时是 {output: '...', metadata: {...}} 的 JSON 串
+      let outText = outRaw
+      if (typeof outRaw === 'string') {
+        const parsed = safeParseJson(outRaw)
+        if (parsed && typeof parsed === 'object') outText = parsed.output ?? parsed.content ?? outRaw
+      }
+      blocks = [{ type: 'tool_result', content: typeof outText === 'string' ? outText : JSON.stringify(outText) }]
+    } else if (payload.type === 'message') {
+      role = payload.role || 'raw'
+      blocks = normalizeContent(payload.content)
+    } else {
+      // 兜底：旧格式 / 测试 fixtures 的扁平 payload（{role, content}）
+      role = payload.role || j.type
+      if (typeof payload.content === 'string') blocks = [{ type: 'text', text: payload.content }]
+      else if (Array.isArray(payload.content)) blocks = normalizeContent(payload.content)
+      else if (typeof payload.text === 'string') blocks = [{ type: 'text', text: payload.text }]
+    }
+
+    const parts = []
+    for (const blk of blocks) {
+      const piece = blockToText(blk, { includeToolUse: preview, includeToolResult: preview, toolResultMaxChars: 300 })
+      if (piece) parts.push(piece)
+    }
+    const content = parts.join('\n').trim()
+    if (!content) continue
+    turnCount++
+    turns.push({ role: role || 'raw', content })
+    if (!firstUserPrompt && role === 'user') firstUserPrompt = content.slice(0, 200)
+  }
+  const usage = extractUsage('codex', rawLines, {})
+  return { nativeId, cwd, startedAt, endedAt, firstUserPrompt, turnCount, turns, usage }
+}
+
+export function listTranscriptFiles({ claudeDir = DEFAULT_CLAUDE_DIR, codexDir = DEFAULT_CODEX_DIR, cursorDir = null } = {}) {
+  const result = []
+  for (const p of walkJsonl(claudeDir)) {
+    const st = safeStat(p); if (!st) continue
+    result.push({ tool: 'claude', jsonlPath: p, size: st.size, mtime: Math.floor(st.mtimeMs) })
+  }
+  for (const p of walkJsonl(codexDir)) {
+    const st = safeStat(p); if (!st) continue
+    result.push({ tool: 'codex', jsonlPath: p, size: st.size, mtime: Math.floor(st.mtimeMs) })
+  }
+  // cursor: 只扫 agent-transcripts/<chatId>/<chatId>.jsonl，避免把 worker.log/repo.json 的同目录其他文件吃进来
+  if (cursorDir) {
+    for (const p of walkJsonl(cursorDir)) {
+      if (!p.includes(`${path.sep}agent-transcripts${path.sep}`)) continue
+      const st = safeStat(p); if (!st) continue
+      result.push({ tool: 'cursor', jsonlPath: p, size: st.size, mtime: Math.floor(st.mtimeMs) })
+    }
+  }
+  return result
+}
+
+export async function parseTranscriptFile(tool, filePath, opts = {}) {
+  if (tool === 'claude') return parseClaudeFile(filePath, opts)
+  if (tool === 'codex') return parseCodexFile(filePath, opts)
+  if (tool === 'cursor') return parseCursorFile(filePath, opts)
+  throw new Error(`unknown tool: ${tool}`)
+}

package/src/usage-footer.js

@@ -0,0 +1,170 @@
+/**
+ * Telegram 推送 footer：把"本轮 token 用量 + session 累计费用"拼成两行信息，
+ * 让用户每次收到 AI 回复时都能立刻看到这一轮和这个 task 总共烧了多少钱。
+ *
+ * 数据流：
+ *   - turn usage: 由 openclaw-hook 从 readLatestAssistantTurn().raw.message 拿
+ *     （usage / model 直接是 Claude 写到 jsonl 里的字段）
+ *   - session usage: 扫整个 jsonl 文件，调 usage-parser.extractUsage('claude', lines)
+ *     拿到 session 内所有 assistant 消息的累加值
+ *
+ * 输出格式（紧凑两行，第三方 client 也好渲染）：
+ *
+ *   ———— 💸 ————
+ *   turn:    in 1.2k · out 350 · cache 1.0k → $0.012 (¥0.09)
+ *   session: $0.34 (¥2.46) · 12 turns
+ *
+ * 边界：
+ *   - 任何字段缺失 / 全 0 → 那一行直接省略
+ *   - turn 和 session 都没数据 → 返回空字符串（caller 直接不附 footer）
+ *   - showCny=false → 省略 ¥…
+ *   - cnyRate 缺省 → 用 DEFAULT_PRICING.cnyRate (7.2)
+ *
+ * 纯函数，无 IO；所有依赖（lines / pricing / cnyRate）都从入参传入，方便测试。
+ */
+
+import { extractUsage } from './usage-parser.js'
+import { estimateCost, DEFAULT_PRICING } from './pricing.js'
+
+const FOOTER_DIVIDER = '———— 💸 ————'
+
+/**
+ * 数字格式化：1234 → "1.2k", 999 → "999", 12345 → "12k", 1234567 → "1.2M"
+ * 主要给 token 数用，目的是节省 Telegram 显示空间。
+ */
+export function formatTokenCount(n) {
+  const v = Number(n) || 0
+  if (v < 0) return '0'
+  if (v < 1000) return String(v)
+  if (v < 10000) return (v / 1000).toFixed(1) + 'k'
+  if (v < 1_000_000) return Math.round(v / 1000) + 'k'
+  return (v / 1_000_000).toFixed(2) + 'M'
+}
+
+/**
+ * 钱数格式化：自适应位数。
+ *   < $0.001 → "<$0.001"     （太少不值显示具体）
+ *   < $0.01  → "$0.0042"     （4 位小数）
+ *   < $1     → "$0.123"      （3 位小数）
+ *   ≥ $1     → "$3.45"       （2 位小数）
+ *
+ * 同样规则套到 ¥ 上（CNY 数值通常是 USD * 7.2，量级类似）。
+ */
+function formatMoney(amount, symbol) {
+  const v = Math.abs(Number(amount) || 0)
+  if (v < 0.001) return `<${symbol}0.001`
+  let s
+  if (v < 0.01) s = v.toFixed(4)
+  else if (v < 1) s = v.toFixed(3)
+  else s = v.toFixed(2)
+  return `${symbol}${s}`
+}
+
+/**
+ * 拼"$0.012 (¥0.09)" 或单 USD/CNY，按 showCny 控制。
+ */
+export function formatCost({ usd, cny, showCny = true } = {}) {
+  const usdStr = formatMoney(usd, '$')
+  if (!showCny) return usdStr
+  const cnyStr = formatMoney(cny, '¥')
+  return `${usdStr} (${cnyStr})`
+}
+
+/**
+ * 从 readLatestAssistantTurn().raw 里抽出本轮 usage。
+ * 返回 { input, output, cacheRead, cacheCreation, model } —— 字段都是 number / string。
+ *
+ * 注意：单条 assistant message 的 usage 已经是 Claude 算好的"这次调用消耗"。
+ * 一个 turn 可能包含多条 assistant message（tool_use 跟 final response 分开），
+ * 但 readLatestAssistantTurn 取的是最后一条（final response），所以本轮 usage 就用这条。
+ *
+ * 如果 raw 没 usage（极端情况，例如 Claude Code 老版本），返回 null。
+ */
+export function extractTurnUsage(raw) {
+  const msg = raw?.message
+  if (!msg) return null
+  const u = msg.usage
+  if (!u) return null
+  return {
+    input: Number(u.input_tokens) || 0,
+    output: Number(u.output_tokens) || 0,
+    cacheRead: Number(u.cache_read_input_tokens) || 0,
+    cacheCreation: Number(u.cache_creation_input_tokens) || 0,
+    model: msg.model || null,
+  }
+}
+
+/**
+ * 从 jsonl lines 算 session 累计 usage。
+ *
+ * @param {string[]} lines  JSONL lines
+ * @param {'claude'|'codex'} tool  tool name; default 'claude' for back-compat
+ */
+export function extractSessionUsageFromLines(lines, tool = 'claude') {
+  const summary = extractUsage(tool, lines)
+  let turnCount = 0
+  for (const line of lines) {
+    if (!line || !line.trim()) continue
+    try {
+      const j = JSON.parse(line)
+      if (tool === 'claude' && j?.message?.role === 'assistant') turnCount++
+      else if (tool === 'codex' && j?.type === 'response_item' && j?.payload?.type === 'message' && j?.payload?.role === 'assistant') turnCount++
+    } catch {}
+  }
+  return {
+    input: summary.inputTokens,
+    output: summary.outputTokens,
+    cacheRead: summary.cacheReadTokens,
+    cacheCreation: summary.cacheCreationTokens,
+    primaryModel: summary.primaryModel,
+    turnCount,
+  }
+}
+
+/**
+ * 把 turn / session 拼成 Telegram footer 文本。
+ *
+ * 入参：
+ *   - turn:    { input, output, cacheRead, cacheCreation, model } 或 null
+ *   - session: { input, output, cacheRead, cacheCreation, primaryModel, turnCount } 或 null
+ *   - showCny: 是否显示人民币（默认 true）
+ *   - pricing: 同 estimateCost；默认 DEFAULT_PRICING
+ *
+ * 返回：footer 字符串，或 '' 表示不要附加。
+ *
+ * 单测覆盖各种 0 / null / 缺字段的退化路径。
+ */
+export function formatUsageFooter({ turn = null, session = null, showCny = true, pricing = DEFAULT_PRICING } = {}) {
+  const lines = []
+
+  // ── turn line ─────────────────────────────
+  if (turn && (turn.input || turn.output || turn.cacheRead || turn.cacheCreation)) {
+    const parts = []
+    if (turn.input)  parts.push(`in ${formatTokenCount(turn.input)}`)
+    if (turn.output) parts.push(`out ${formatTokenCount(turn.output)}`)
+    const cache = (turn.cacheRead || 0) + (turn.cacheCreation || 0)
+    if (cache > 0) parts.push(`cache ${formatTokenCount(cache)}`)
+    const cost = estimateCost(
+      { input: turn.input, output: turn.output, cacheRead: turn.cacheRead, cacheCreation: turn.cacheCreation },
+      turn.model,
+      pricing,
+    )
+    lines.push(`turn:    ${parts.join(' · ')} → ${formatCost({ usd: cost.usd, cny: cost.cny, showCny })}`)
+  }
+
+  // ── session line ──────────────────────────
+  if (session && (session.input || session.output || session.cacheRead || session.cacheCreation)) {
+    const cost = estimateCost(
+      { input: session.input, output: session.output, cacheRead: session.cacheRead, cacheCreation: session.cacheCreation },
+      session.primaryModel,
+      pricing,
+    )
+    const turnTag = session.turnCount ? ` · ${session.turnCount} turns` : ''
+    lines.push(`session: ${formatCost({ usd: cost.usd, cny: cost.cny, showCny })}${turnTag}`)
+  }
+
+  if (lines.length === 0) return ''
+  return `${FOOTER_DIVIDER}\n${lines.join('\n')}`
+}
+
+export const __test__ = { FOOTER_DIVIDER, formatMoney }

package/src/usage-parser.js

@@ -0,0 +1,132 @@
+// Pure helpers: given already-read JSONL lines + tool, return usage summary.
+// No I/O. No throw on bad lines; returns parseErrorCount instead.
+
+const MODEL_DATE_SUFFIX = /-\d{8}$/ // e.g. "-20260101"
+
+function normalizeModel(name) {
+  if (!name) return null
+  return String(name).replace(MODEL_DATE_SUFFIX, '')
+}
+
+function pickMode(counter) {
+  let best = null, bestN = -1
+  for (const [k, n] of counter) if (n > bestN) { best = k; bestN = n }
+  return best
+}
+
+// Shared accumulation: takes normalized records { usage, model, ts } and returns summary.
+function accumulateRecords(records, idleThresholdMs) {
+  let input = 0, output = 0, cacheR = 0, cacheC = 0
+  const modelCounter = new Map()
+  const assistantTs = []
+  for (const { usage: u = {}, model, ts } of records) {
+    input  += Number(u.input_tokens)  || 0
+    output += Number(u.output_tokens) || 0
+    cacheR += Number(u.cache_read_input_tokens)     || 0
+    cacheC += Number(u.cache_creation_input_tokens) || 0
+    if (model) modelCounter.set(model, (modelCounter.get(model) || 0) + 1)
+    if (!Number.isNaN(ts)) assistantTs.push(ts)
+  }
+  let activeMs = 0
+  assistantTs.sort((a, b) => a - b)
+  for (let i = 1; i < assistantTs.length; i++) {
+    const dt = assistantTs[i] - assistantTs[i - 1]
+    if (dt > 0 && dt <= idleThresholdMs) activeMs += dt
+  }
+  return {
+    inputTokens: input, outputTokens: output,
+    cacheReadTokens: cacheR, cacheCreationTokens: cacheC,
+    primaryModel: pickMode(modelCounter),
+    activeMs,
+  }
+}
+
+function extractClaude(lines, { idleThresholdMs }) {
+  const records = []
+  let errors = 0
+  for (const line of lines) {
+    if (!line || !line.trim()) continue
+    let j
+    try { j = JSON.parse(line) } catch { errors++; continue }
+    const msg = j.message
+    if (msg?.role !== 'assistant') continue
+    records.push({
+      usage: msg.usage || {},
+      model: normalizeModel(msg.model),
+      ts: j.timestamp ? Date.parse(j.timestamp) : NaN,
+    })
+  }
+  return { ...accumulateRecords(records, idleThresholdMs), parseErrorCount: errors }
+}
+
+function extractCodex(lines, { idleThresholdMs }) {
+  let lastTokenCountInfo = null
+  const responseItemRecords = []
+  const modelCounter = new Map()
+  const assistantTs = []
+  let errors = 0
+
+  for (const line of lines) {
+    if (!line || !line.trim()) continue
+    let j
+    try { j = JSON.parse(line) } catch { errors++; continue }
+
+    if (j.type === 'event_msg' && j.payload?.type === 'token_count') {
+      const info = j.payload?.info
+      if (info?.total_token_usage) lastTokenCountInfo = info
+    } else if (j.type === 'response_item' && j.payload?.type === 'message' && j.payload?.role === 'assistant') {
+      const model = normalizeModel(j.payload.model)
+      if (model) modelCounter.set(model, (modelCounter.get(model) || 0) + 1)
+      const ts = j.timestamp ? Date.parse(j.timestamp) : NaN
+      if (!Number.isNaN(ts)) assistantTs.push(ts)
+      const u = j.payload.token_usage || j.payload.usage
+      if (u) responseItemRecords.push({ usage: u, model, ts })
+    } else if (j.type === 'session_meta') {
+      const model = normalizeModel(j.payload?.model || j.payload?.model_provider?.model)
+      if (model) modelCounter.set(model, (modelCounter.get(model) || 0) + 1)
+    } else if (j.type === 'turn_context') {
+      const model = normalizeModel(j.payload?.model || j.payload?.collaboration_mode?.settings?.model)
+      if (model) modelCounter.set(model, (modelCounter.get(model) || 0) + 1)
+    }
+  }
+
+  let input = 0, output = 0, cacheR = 0, cacheC = 0
+  if (lastTokenCountInfo?.total_token_usage) {
+    const t = lastTokenCountInfo.total_token_usage
+    input  = Number(t.input_tokens)  || 0
+    output = Number(t.output_tokens) || 0
+    cacheR = Number(t.cached_input_tokens || t.cache_read_input_tokens) || 0
+    cacheC = Number(t.cache_creation_input_tokens) || 0
+  } else {
+    for (const r of responseItemRecords) {
+      input  += Number(r.usage.input_tokens)  || 0
+      output += Number(r.usage.output_tokens) || 0
+      cacheR += Number(r.usage.cached_input_tokens || r.usage.cache_read_input_tokens) || 0
+      cacheC += Number(r.usage.cache_creation_input_tokens) || 0
+    }
+  }
+
+  let activeMs = 0
+  assistantTs.sort((a, b) => a - b)
+  for (let i = 1; i < assistantTs.length; i++) {
+    const dt = assistantTs[i] - assistantTs[i - 1]
+    if (dt > 0 && dt <= idleThresholdMs) activeMs += dt
+  }
+
+  return {
+    inputTokens: input, outputTokens: output,
+    cacheReadTokens: cacheR, cacheCreationTokens: cacheC,
+    primaryModel: pickMode(modelCounter),
+    activeMs,
+    parseErrorCount: errors,
+  }
+}
+
+export function extractUsage(tool, lines, opts = {}) {
+  const o = { idleThresholdMs: 120_000, ...opts }
+  if (tool === 'claude') return extractClaude(lines, o)
+  if (tool === 'codex')  return extractCodex(lines, o)
+  // cursor-agent jsonl 目前不带 token usage 字段（v0.x），返回空 usage 让上游不抛错
+  if (tool === 'cursor') return { records: [], totals: {}, parseErrorCount: 0 }
+  throw new Error(`unknown tool: ${tool}`)
+}