ai-lens 0.8.74 → 0.8.80

package/.commithash

@@ -1 +1 @@
-87a4956
+a6ad00e

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 History of changes to the `ai-lens` CLI package on npm. New entries go on top. Format: `## X.Y.Z — YYYY-MM-DD`, followed by user-facing bullets.
 
+## 0.8.80 — 2026-06-04
+- fix: `ai-lens import claude-code` now caps long prompts (so a huge pasted prompt is no longer dropped by the server), captures prompts from messages that mix text with images/documents (shown as a safe `[N attachment(s)]` placeholder — never the image data), and avoids a stale session "end" time on transcripts that are still being written.
+
+## 0.8.79 — 2026-06-04
+- fix: `ai-lens import claude-code` now de-overlaps with live capture using the server instead of a local cache. On a machine already running AI Lens it imports only the part of each session that predates live capture — so it no longer over-skips your history (the old guard wrongly skipped almost everything) or double-counts what live already recorded. Requires the matching server update.
+
+## 0.8.78 — 2026-06-04
+- fix: large `ai-lens import claude-code` runs (e.g. `--days 0` or a busy 3–6 months) no longer silently drop events. The importer now ships in batches and only marks a session imported after its events have actually reached the server, so nothing is lost and an interrupted run safely resumes.
+
+## 0.8.77 — 2026-06-04
+- fix: `ai-lens import` no longer silently turns a preview into a real import when a value flag is missing (e.g. `--projects --dry-run`). A flag with a missing value now prints a clear error and stops, and `--dry-run` is always honored.
+
+## 0.8.76 — 2026-06-04
+- fix: `ai-lens import claude-code` no longer double-counts when AI Lens is already running live — imported token usage dedups against live-captured calls, and sessions already captured live are skipped. Also: clearer errors for bad `--days`/`--since`, exact `--projects` path matching, and a few mapping fixes (tool results without a matching call, subagent activity).
+
+## 0.8.75 — 2026-06-04
+- feat: `ai-lens import claude-code` imports your local Claude Code history (`~/.claude/projects`) so your dashboard shows months of real activity minutes after install — sessions, AI-hours, models, MCP/skills, plan-mode and subagent usage. Defaults to the last 30 days; use `--days N` (`--days 0` for everything), `--since YYYY-MM-DD`, `--projects`, or `--dry-run` to preview. Re-running is safe (idempotent).
+
 ## 0.8.74 — 2026-06-04
 - fix: committed Claude Code project hooks now resolve `capture.js` via `$CLAUDE_PROJECT_DIR`, so they fire from any working directory — no more `MODULE_NOT_FOUND` after the agent `cd`s into a subdirectory.
 - fix: `ai-lens status` and `ai-lens init --project-hooks` recognize the `$CLAUDE_PROJECT_DIR` hook form as current instead of flagging it outdated or overwriting it.

package/bin/ai-lens.js

@@ -18,6 +18,11 @@ switch (command) {
     await status({ report: process.argv.includes('--report') });
     break;
   }
+  case 'import': {
+    const { default: importCmd } = await import('../cli/import.js');
+    await importCmd();
+    break;
+  }
   case 'version':
   case '--version':
   case '-v': {
@@ -46,6 +51,11 @@ switch (command) {
     console.log('    --use-repo-path Run capture.js from this package; skip copy to ~/.ai-lens/client/');
     console.log('  remove          Remove AI Lens hooks and client files');
     console.log('  status          Run diagnostics and generate a status report');
+    console.log('  import <source>  Import local history (source: claude-code)');
+    console.log('    --days N         Window in days (default 30; 0 = all history)');
+    console.log('    --since DATE     Import from YYYY-MM-DD instead of --days');
+    console.log('    --dry-run        Scan + count, write nothing');
+    console.log('    --projects LIST  Only these project paths (comma-separated)');
     console.log('  version         Show package version and commit hash');
     process.exit(command ? 1 : 0);
 }

package/cli/import/claude-code.js

@@ -0,0 +1,363 @@
+/**
+ * `ai-lens import claude-code` engine.
+ *
+ * Reads ~/.claude/projects/**\/*.jsonl, maps each transcript to unified events
+ * (cli/import/transcript-map.js), enriches with developer + git identity,
+ * redacts + spools via the live client pipeline (writeToSpool), and lets the
+ * existing sender ship them to POST /api/events. Historical timestamps are kept
+ * verbatim; re-import is idempotent via the server content-hash dedup.
+ */
+import { createReadStream, existsSync, readdirSync, statSync, readFileSync, writeFileSync, mkdirSync, renameSync, realpathSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline';
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { writeToSpool, canonicalizeProjectPath, deterministicEventId } from '../../client/capture.js';
+import { PENDING_DIR, SENDING_DIR, DATA_DIR, ensureDataDir, getGitIdentity, getGitMetadata, getServerUrl, getAuthToken } from '../../client/config.js';
+import { mapTranscript } from './transcript-map.js';
+import { info, success, warn, error, heading, detail, blank } from '../logger.js';
+
+const PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+const LEDGER_PATH = join(DATA_DIR, 'import-state', 'claude-code.json');
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+// TokenUsage gets a LIVE-compatible event_id (sha of the assistant line uuid,
+// exactly as client/capture.js:1363) so an imported call dedups against the same
+// call captured live. Everything else uses an import-scoped deterministic id.
+export function computeEventId(ev) {
+  if (ev.type === 'TokenUsage' && ev.raw && ev.raw.source_uuid) {
+    return deterministicEventId(`claude_code:tokenusage:${ev.raw.source_uuid}`);
+  }
+  return deterministicEventId(`claude_code:import:v1:${ev._seed}`);
+}
+
+const DAY_MS = 86400_000;
+// Drain the spool to the server every DRAIN_BATCH spooled events. MUST stay well
+// under sender.js MAX_QUEUE_SIZE (10_000) — once pending exceeds that, the sender
+// DROPS the oldest overflow files (data loss). Draining in batches also lets us
+// commit the ledger only AFTER a batch's events have actually shipped, so a failed
+// send never leaves files marked covered. (sender.js can't be imported for the
+// constant — it self-invokes main() on import.)
+const DRAIN_BATCH = 4000;
+// A transcript untouched for ≥ this long is treated as a finished session, so its
+// terminal Stop/SubagentStop marker is safe to emit (matches the 5h chain-gap).
+const TERMINAL_DORMANT_MS = 5 * 60 * 60 * 1000;
+
+/** Validate flags. Returns an error string, or null when ok. */
+export function validateFlags({ days, since }) {
+  if (since != null) {
+    if (typeof since !== 'string' || Number.isNaN(Date.parse(since))) {
+      return `Invalid --since "${since}". Use YYYY-MM-DD.`;
+    }
+  } else if (!Number.isInteger(days) || days < 0) {
+    return `Invalid --days "${days}". Use a non-negative integer (0 = all history).`;
+  }
+  return null;
+}
+
+/** Resolve the cutoff ISO string from flags. `--days 0` / no window ⇒ epoch (all). */
+export function resolveCutoff({ days, since }, now = new Date()) {
+  if (since) return new Date(Date.parse(since)).toISOString();
+  if (days === 0) return new Date(0).toISOString();
+  const d = Number.isInteger(days) && days >= 0 ? days : 30;
+  return new Date(now.getTime() - d * DAY_MS).toISOString();
+}
+
+/** Expand a leading ~ and resolve to a canonical project (git) root. */
+function normalizeProjectArg(p) {
+  let s = (p || '').trim();
+  if (!s) return null;
+  if (s === '~' || s.startsWith('~/')) s = join(homedir(), s.slice(1));
+  let real = s;
+  try { real = realpathSync(s); } catch { /* path may not exist on disk — keep as given */ }
+  return canonicalizeProjectPath(real) || real;
+}
+
+/** Path-boundary match (so /repo does NOT match /repo2). */
+export function projectMatches(projectPath, filters) {
+  if (!filters) return true;
+  if (!projectPath) return false;
+  return filters.some((pf) => projectPath === pf || projectPath.startsWith(pf + '/'));
+}
+
+/**
+ * Ask the server, for these session_ids, the earliest LIVE (non-import) event
+ * timestamp it already has → { sessionId: minIso }. Best-effort: on any failure
+ * (old server without the route, network) returns {} so we import everything
+ * (TokenUsage still dedups on its live-compatible id; nothing is lost).
+ */
+export async function fetchCoverage(sessionIds, { fetchImpl = globalThis.fetch } = {}) {
+  const out = {};
+  if (!sessionIds.length || !fetchImpl) return out;
+  const base = getServerUrl();
+  const token = getAuthToken();
+  const CHUNK = 400;
+  for (let i = 0; i < sessionIds.length; i += CHUNK) {
+    const batch = sessionIds.slice(i, i + CHUNK);
+    try {
+      const res = await fetchImpl(new URL('/api/events/coverage', base), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...(token ? { 'X-Auth-Token': token } : {}) },
+        body: JSON.stringify({ session_ids: batch }),
+      });
+      if (res.ok) Object.assign(out, await res.json());
+    } catch { /* best-effort */ }
+  }
+  return out;
+}
+
+/**
+ * Drop events at/after the live-coverage boundary for their session, so import
+ * only adds the pre-live backlog. No boundary ⇒ keep all. (Pure, for tests.)
+ */
+export function sliceEvents(events, coverage) {
+  return events.filter((ev) => {
+    const boundary = coverage[ev.session_id];
+    if (!boundary) return true;
+    // Compare instants, not strings — server timestamps may lack the ms ('…00Z'
+    // vs '…00.000Z'), which would mis-sort a boundary-equal event lexically.
+    return Date.parse(ev.timestamp) < Date.parse(boundary);
+  });
+}
+
+function walkJsonl(dir) {
+  const out = [];
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...walkJsonl(p));
+    else if (e.isFile() && e.name.endsWith('.jsonl')) out.push(p);
+  }
+  return out;
+}
+
+function loadLedger() {
+  try { return JSON.parse(readFileSync(LEDGER_PATH, 'utf-8')); } catch { return {}; }
+}
+function saveLedger(ledger) {
+  mkdirSync(join(DATA_DIR, 'import-state'), { recursive: true });
+  const tmp = LEDGER_PATH + '.tmp';
+  writeFileSync(tmp, JSON.stringify(ledger));
+  renameSync(tmp, LEDGER_PATH);
+}
+
+/** A file is already covered if a prior run imported a wider-or-equal window AND the file is unchanged. */
+export function ledgerCovers(entry, cutoff, fp) {
+  if (!entry || !entry.fingerprint) return false;
+  if (entry.fingerprint.mtimeMs !== fp.mtimeMs || entry.fingerprint.size !== fp.size) return false;
+  return entry.complete_all || (entry.covered_cutoff && entry.covered_cutoff <= cutoff);
+}
+
+/** Read one transcript file fully (line-by-line, never JSON.parse(whole_file)). */
+async function readTranscript(filePath) {
+  const lines = [];
+  let lastTs = null;
+  const rl = createInterface({ input: createReadStream(filePath, { encoding: 'utf-8' }), crlfDelay: Infinity });
+  for await (const raw of rl) {
+    if (!raw) continue;
+    let obj;
+    try { obj = JSON.parse(raw); } catch { continue; } // tolerant: skip bad line
+    lines.push(obj);
+    if ((obj.type === 'user' || obj.type === 'assistant') && typeof obj.timestamp === 'string' && obj.timestamp > (lastTs || '')) {
+      lastTs = obj.timestamp;
+    }
+  }
+  return { lines, lastTs };
+}
+
+function firstCwd(lines) {
+  for (const l of lines) {
+    if ((l.type === 'user' || l.type === 'assistant') && l.cwd) return l.cwd;
+  }
+  return null;
+}
+function firstSessionId(lines, fallback) {
+  for (const l of lines) if (l.sessionId) return l.sessionId;
+  return fallback;
+}
+
+async function drainSpool({ timeoutMs = 120_000 } = {}) {
+  const senderPath = join(__dirname, '..', '..', 'client', 'sender.js');
+  const pendingCount = () => { try { return readdirSync(PENDING_DIR).filter((f) => f.endsWith('.json')).length; } catch { return 0; } };
+  const sendingCount = () => { try { return readdirSync(SENDING_DIR).filter((f) => f.endsWith('.json')).length; } catch { return 0; } };
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (pendingCount() === 0 && sendingCount() === 0) return true;
+    await new Promise((resolve) => {
+      const child = spawn(process.execPath, [senderPath], { stdio: 'ignore' });
+      child.on('exit', resolve);
+      child.on('error', resolve);
+    });
+    await new Promise((r) => setTimeout(r, 400));
+  }
+  return pendingCount() === 0 && sendingCount() === 0;
+}
+
+export default async function importClaudeCode(flags) {
+  const {
+    days = 30, since = null, dryRun = false, projects = null,
+    noRedact = false, analysisMaxAgeDays: amAgeFlag = 30,
+  } = flags;
+  const analysisMaxAgeDays = Number.isInteger(amAgeFlag) && amAgeFlag >= 0 ? amAgeFlag : 30;
+
+  heading('Import — Claude Code history');
+  if (!existsSync(PROJECTS_DIR)) {
+    warn(`No Claude Code history found at ${PROJECTS_DIR}`);
+    return;
+  }
+  if (!dryRun && !getAuthToken()) {
+    error('No auth token. Run `npx ai-lens init` first (or set AI_LENS_AUTH_TOKEN).');
+    return;
+  }
+  if (noRedact) warn('⚠ --no-redact: secrets in raw transcripts are NOT redacted client-side and persist locally in the spool if a send fails. Use only for debugging.');
+
+  const flagErr = validateFlags({ days, since });
+  if (flagErr) { error(flagErr); process.exitCode = 1; return; }
+
+  const cutoff = resolveCutoff({ days, since });
+  const projectFilter = projects
+    ? projects.split(',').map(normalizeProjectArg).filter(Boolean)
+    : null;
+  ensureDataDir();
+  const ledger = loadLedger();
+  if (!dryRun) info(`Server: ${getServerUrl()}`);
+  info(dryRun ? `Scanning (dry-run, window: ${since || (days === 0 ? 'all' : days + 'd')})…`
+              : `Importing window: ${since || (days === 0 ? 'all' : days + 'd')} (cutoff ${cutoff.slice(0, 10)})`);
+
+  const allFiles = [...new Set(walkJsonl(PROJECTS_DIR))];
+  let filesIncluded = 0, filesSkipped = 0, eventCount = 0, sessionCount = 0, liveSkipped = 0;
+  let withinWindow = 0, older = 0;
+  let lastDate = null;
+  const nowMs = Date.now();
+
+  // Batched shipping: spool events, and every DRAIN_BATCH events drain the spool
+  // to the server, committing the ledger only for files whose events have shipped.
+  let inFlight = 0;            // events spooled since the last successful drain
+  const pendingCommit = [];   // {filePath, entry} for fully-written, not-yet-committed files
+  let drainFailed = false;
+  const flush = async () => {
+    if (dryRun) { inFlight = 0; return true; }
+    const ok = await drainSpool();
+    if (!ok) { drainFailed = true; return false; }
+    inFlight = 0;
+    for (const c of pendingCommit) ledger[c.filePath] = c.entry;
+    if (pendingCommit.length) saveLedger(ledger);
+    pendingCommit.length = 0;
+    return true;
+  };
+
+  // Pass 1 — cheap shortlist (mtime + ledger), no file reads. A transcript's
+  // filename basename IS the session UUID, so we can gather session ids for the
+  // coverage query without reading anything.
+  const candidates = [];
+  for (const filePath of allFiles) {
+    let st;
+    try { st = statSync(filePath); } catch { continue; }
+    const fp = { mtimeMs: Math.trunc(st.mtimeMs), size: st.size };
+    if (st.mtime.toISOString() < cutoff) { filesSkipped++; continue; } // last write before window
+    if (ledgerCovers(ledger[filePath], cutoff, fp)) { filesSkipped++; continue; }
+    candidates.push({ filePath, fp });
+  }
+
+  // Ask the server which of these sessions it already has LIVE (non-import) events
+  // for, so we import only the pre-live backlog — replacing the old, unsafe
+  // session-paths "delivery" guess (a local cache written before delivery).
+  const coverage = await fetchCoverage([...new Set(
+    candidates.filter((c) => !/\/subagents\/agent-/.test(c.filePath)).map((c) => basename(c.filePath, '.jsonl')),
+  )]);
+
+  // Pass 2 — read, map, de-overlap, ship.
+  for (const { filePath, fp } of candidates) {
+    if (drainFailed) break;
+    const { lines, lastTs } = await readTranscript(filePath);
+    if (!lastTs || lastTs < cutoff) { filesSkipped++; continue; }
+
+    const cwd = firstCwd(lines);
+    const projectPath = canonicalizeProjectPath(cwd) || cwd || null;
+    if (!projectMatches(projectPath, projectFilter)) { filesSkipped++; continue; }
+
+    const sessionId = firstSessionId(lines, basename(filePath, '.jsonl'));
+    const fileId = createHash('sha1').update(filePath).digest('hex').slice(0, 12);
+    const isSubagentFile = /\/subagents\/agent-/.test(filePath);
+    const agentId = isSubagentFile ? basename(filePath, '.jsonl') : null;
+
+    // Only emit terminal markers (Stop/SubagentStop) for dormant files — an
+    // actively-appended transcript would otherwise get a stale, file-stable Stop
+    // event_id that the server can't update on re-import (see transcript-map).
+    const emitTerminal = (nowMs - fp.mtimeMs) >= TERMINAL_DORMANT_MS;
+    const mapped = mapTranscript(lines, { sessionId, projectPath, fileId, isSubagentFile, agentId, agentSlug: null, emitTerminal });
+    if (mapped.length === 0) { filesSkipped++; continue; }
+    const events = sliceEvents(mapped, coverage); // import only pre-live events
+    if (events.length === 0) {
+      // Whole session is at/after the live boundary — live already owns it.
+      liveSkipped++;
+      if (!dryRun) pendingCommit.push({ filePath, entry: { covered_cutoff: cutoff, complete_all: days === 0, fingerprint: fp } });
+      continue;
+    }
+
+    const ident = getGitIdentity(cwd);
+    const gitMeta = getGitMetadata(projectPath);
+
+    for (const ev of events) {
+      const unified = {
+        event_id: computeEventId(ev),
+        source: 'claude_code',
+        session_id: ev.session_id,
+        type: ev.type,
+        project_path: ev.project_path,
+        timestamp: ev.timestamp,
+        data: { ...ev.data, _import: true }, // marks import rows so /coverage ignores them
+        raw: ev.raw,
+        developer_email: ident.email || null,
+        developer_name: ident.name || null,
+        git_remote: gitMeta.git_remote || null,
+        git_branch: gitMeta.git_branch || null,
+        git_commit: gitMeta.git_commit || null,
+      };
+      if (!dryRun) {
+        if (noRedact) writeRaw(unified); else writeToSpool(unified);
+        inFlight++;
+        // Drain BEFORE pending can approach the sender's overflow cap. Checked per
+        // event so a single huge transcript can't blow past it mid-file.
+        if (inFlight >= DRAIN_BATCH) { if (!(await flush())) break; }
+      }
+      eventCount++;
+    }
+    if (drainFailed) break;
+
+    filesIncluded++;
+    sessionCount++;
+    if (!isSubagentFile) (lastTs >= new Date(nowMs - analysisMaxAgeDays * 86400_000).toISOString() ? withinWindow++ : older++);
+    if (!lastDate || lastTs > lastDate) lastDate = lastTs;
+    // Defer the ledger commit until this file's events have actually shipped (flush()).
+    if (!dryRun) pendingCommit.push({ filePath, entry: { covered_cutoff: cutoff, complete_all: days === 0, fingerprint: fp } });
+    if (filesIncluded % 25 === 0) info(`  …${filesIncluded} files, ${eventCount} events — last ${(lastDate || '').slice(0, 10)}`);
+  }
+
+  blank();
+  if (liveSkipped > 0) info(`Skipped ${liveSkipped} session(s) already captured live (no duplication).`);
+  if (dryRun) {
+    success(`Dry-run: ${filesIncluded} session file(s), ${eventCount} event(s) would import (${filesSkipped} skipped). Nothing written.`);
+    return;
+  }
+
+  info(`Spooled ${eventCount} event(s) from ${filesIncluded} session(s). Shipping…`);
+  const drained = await flush(); // ship the final partial batch + commit remaining ledger
+  if (drained) success(`Imported ${sessionCount} session(s), ${eventCount} event(s).`);
+  else warn(`Some events couldn't be shipped — their sessions were NOT marked imported and will retry on the next run. Check \`ai-lens status\`.`);
+
+  detail(`Within ${analysisMaxAgeDays}d: ${withinWindow} session(s) eligible for auto-analysis. Older: ${older} (skipped by max-age ${analysisMaxAgeDays}, available on-demand).`);
+  detail('Open /me to see your imported history.');
+}
+
+/** --no-redact path: write the event to pending/ WITHOUT client redaction. */
+function writeRaw(unified) {
+  const filename = `${unified.event_id}.json`;
+  const tmp = join(PENDING_DIR, filename + '.tmp.' + process.pid);
+  writeFileSync(tmp, JSON.stringify(unified));
+  renameSync(tmp, join(PENDING_DIR, filename));
+}

package/cli/import/transcript-map.js

@@ -0,0 +1,215 @@
+/**
+ * Pure, stateful mapper: Claude Code transcript lines (one parsed JSONL record
+ * each, in file order) → unified events matching the LIVE capture.js taxonomy
+ * for source='claude_code'. No I/O — fully unit-testable.
+ *
+ * Emits the SAME event types the hook pipeline produces, so imported history is
+ * indistinguishable to the dashboard/analyzer: SessionStart, UserPromptSubmit,
+ * PostToolUse/PostToolUseFailure, PlanModeStart/PlanModeEnd, TokenUsage, Stop,
+ * and SubagentStart/SubagentStop for sidechain (subagent) activity.
+ *
+ * Each returned event carries a stable `_seed` (NOT a final event_id); the
+ * engine prefixes `claude_code:import:v1:` and hashes it. Synthetic markers
+ * (SessionStart/Stop/Subagent*) seed off the stable FILE identity so their id
+ * doesn't shift when the import window widens.
+ */
+import { truncateToolInput, truncateToolResult, truncate, TRUNCATION_LIMITS } from '../../client/capture.js';
+import { buildTokenUsageRaw } from '../../client/token-usage.js';
+
+const PLAN_MODE_TOOLS = { EnterPlanMode: 'PlanModeStart', ExitPlanMode: 'PlanModeEnd' };
+
+/**
+ * Build a prompt string from a user message's content (string, or an array of
+ * text/image/document blocks). Text is concatenated and capped to the live
+ * prompt limit; attachments become a safe count placeholder — never base64.
+ */
+function promptFromUserContent(content) {
+  if (typeof content === 'string') return truncate(content, TRUNCATION_LIMITS.userPrompt);
+  const texts = [];
+  let attachments = 0;
+  for (const b of asArray(content)) {
+    if (b?.type === 'text' && typeof b.text === 'string') texts.push(b.text);
+    else if (b?.type === 'image' || b?.type === 'document') attachments++;
+  }
+  let prompt = texts.join('\n');
+  if (attachments > 0) prompt += `${prompt ? '\n' : ''}[${attachments} attachment(s)]`;
+  return prompt ? truncate(prompt, TRUNCATION_LIMITS.userPrompt) : '';
+}
+
+/** A transcript line is "content" only if it's a user/assistant turn with a timestamp. */
+function isContent(line) {
+  return !!line && (line.type === 'user' || line.type === 'assistant') && typeof line.timestamp === 'string';
+}
+
+function asArray(content) {
+  return Array.isArray(content) ? content : [];
+}
+
+function mcpServerOf(toolName) {
+  return typeof toolName === 'string' && toolName.startsWith('mcp__') ? (toolName.split('__')[1] || null) : null;
+}
+
+/**
+ * @param {object[]} lines  Parsed JSONL records, in file order.
+ * @param {object} ctx  { sessionId, projectPath, fileId, isSubagentFile?, agentId?, agentSlug? }
+ * @returns {object[]} events: { session_id, type, project_path, timestamp, data, raw, _seed }
+ */
+export function mapTranscript(lines, ctx) {
+  const { sessionId, projectPath, fileId, isSubagentFile = false, agentId = null, agentSlug = null, emitTerminal = true } = ctx;
+  const events = [];
+  const content = (lines || []).filter(isContent);
+  if (content.length === 0) return events;
+
+  const first = content[0];
+  const last = content[content.length - 1];
+  const mk = (line, type, data, raw, seed) => ({
+    session_id: sessionId,
+    type,
+    project_path: projectPath,
+    timestamp: line.timestamp,
+    data: data || {},
+    raw: raw || {},
+    _seed: seed,
+  });
+  const tokenEvent = (line, seed) => {
+    const u = line.message?.usage;
+    const model = line.message?.model || null;
+    if (!u && !model) return null;
+    // source_uuid (the assistant line uuid) mirrors live capture.js exactly, so the
+    // engine derives a live-compatible event_id and the server dedups an imported
+    // TokenUsage against the same call captured live (no token/usage double-count).
+    const raw = buildTokenUsageRaw({ source_uuid: line.uuid || null }, u || null, model);
+    const data = {
+      ...(model ? { model } : {}),
+      ...(typeof u?.input_tokens === 'number' ? { input_tokens: u.input_tokens } : {}),
+      ...(typeof u?.output_tokens === 'number' ? { output_tokens: u.output_tokens } : {}),
+    };
+    return mk(line, 'TokenUsage', data, raw, seed);
+  };
+
+  // ── Subagent transcript file: SubagentStart → TokenUsage* → SubagentStop, all
+  // under the PARENT session_id (line.sessionId). No SessionStart / prompts / tools
+  // (live attributes only token usage of a subagent to the parent). ──────────────
+  if (isSubagentFile) {
+    const subData = { agent_id: agentId, agent_type: agentSlug, subagent_type: agentSlug };
+    events.push(mk(first, 'SubagentStart', subData, {}, `${sessionId}:substart:${fileId}`));
+    content.forEach((line, i) => {
+      if (line.type === 'assistant') {
+        const ev = tokenEvent(line, `${sessionId}:${line.uuid || fileId + ':' + i}:TokenUsage`);
+        if (ev) events.push(ev);
+      }
+    });
+    if (emitTerminal) events.push(mk(last, 'SubagentStop', { agent_id: agentId, agent_type: agentSlug }, {}, `${sessionId}:substop:${fileId}`));
+    return events;
+  }
+
+  // ── Main transcript ────────────────────────────────────────────────────────
+  events.push(mk(first, 'SessionStart', { cwd: first.cwd || null }, {}, `${sessionId}:sessionstart:${fileId}`));
+
+  const toolBuf = new Map(); // tool_use_id -> { tool, input }
+  let inSidechain = false;
+  let subSeq = 0;
+
+  for (let i = 0; i < content.length; i++) {
+    const line = content[i];
+    const sidechain = !!line.isSidechain;
+    const lineKey = line.uuid || `${fileId}:${i}`;
+
+    // Sidechain transitions → SubagentStart/Stop in the parent session.
+    if (sidechain && !inSidechain) {
+      inSidechain = true;
+      subSeq++;
+      const slug = line.agentSlug || line.slug || null;
+      events.push(mk(line, 'SubagentStart',
+        { agent_id: line.agentId || `sub-${subSeq}`, agent_type: slug, subagent_type: slug },
+        {}, `${sessionId}:substart:${fileId}:${subSeq}`));
+    } else if (!sidechain && inSidechain) {
+      inSidechain = false;
+      const prev = content[i - 1];
+      events.push(mk(prev, 'SubagentStop',
+        { agent_id: prev.agentId || `sub-${subSeq}`, agent_type: prev.agentSlug || prev.slug || null },
+        {}, `${sessionId}:substop:${fileId}:${subSeq}`));
+    }
+
+    // Inside a sidechain run, live only surfaces the subagent's TOKEN usage in
+    // the parent — skip its prompts/tools (avoids inflating parent prompt/tool counts).
+    if (inSidechain) {
+      if (line.type === 'assistant') {
+        const ev = tokenEvent(line, `${sessionId}:${lineKey}:TokenUsage`);
+        if (ev) events.push(ev);
+      }
+      continue;
+    }
+
+    if (line.type === 'user') {
+      const c = line.message?.content;
+      // A user turn is a real prompt (string, OR an array with text/image/document
+      // blocks) and/or tool_result continuations. Emit the prompt (capped to the
+      // live limit, attachments as a placeholder — never base64) AND pair any
+      // tool_results.
+      const prompt = promptFromUserContent(c);
+      if (prompt) {
+        events.push(mk(line, 'UserPromptSubmit', { prompt }, {}, `${sessionId}:${lineKey}:UserPromptSubmit`));
+      }
+      if (typeof c !== 'string') {
+        asArray(c).forEach((block, bi) => {
+          if (block?.type !== 'tool_result') return;
+          const buf = toolBuf.get(block.tool_use_id);
+          // No matching tool_use buffered (e.g. it belonged to a skipped sidechain
+          // turn) — drop it rather than emit a phantom unknown/null PostToolUse.
+          if (!buf) return;
+          toolBuf.delete(block.tool_use_id);
+          const tool = buf.tool;
+          const isErr = block.is_error === true;
+          const data = { tool, input: truncateToolInput(buf.input, tool) };
+          const mcp = mcpServerOf(tool);
+          if (mcp) data.mcp_server = mcp;
+          if (tool === 'Skill' && buf?.input?.skill) data.skill_name = buf.input.skill;
+          const resultText = truncateToolResult(block.content, tool);
+          if (isErr) data.error = resultText; else data.result = resultText;
+          events.push(mk(line, isErr ? 'PostToolUseFailure' : 'PostToolUse', data, {},
+            `${sessionId}:${lineKey}:tr:${block.tool_use_id || bi}`));
+        });
+      }
+    } else if (line.type === 'assistant') {
+      asArray(line.message?.content).forEach((block, bi) => {
+        if (block?.type !== 'tool_use') return;
+        const name = block.name || 'unknown';
+        // Plan-mode tools are promoted immediately — never buffered.
+        if (PLAN_MODE_TOOLS[name]) {
+          events.push(mk(line, PLAN_MODE_TOOLS[name],
+            { tool: name, input: truncateToolInput(block.input, name) }, {},
+            `${sessionId}:${lineKey}:${name}:${bi}`));
+          return;
+        }
+        toolBuf.set(block.id, { tool: name, input: block.input });
+      });
+      const ev = tokenEvent(line, `${sessionId}:${lineKey}:TokenUsage`);
+      if (ev) events.push(ev);
+    }
+  }
+
+  // Unpaired tool_use (no tool_result seen) → best-effort PostToolUse, no result.
+  for (const [id, buf] of toolBuf) {
+    const data = { tool: buf.tool, input: truncateToolInput(buf.input, buf.tool) };
+    const mcp = mcpServerOf(buf.tool);
+    if (mcp) data.mcp_server = mcp;
+    if (buf.tool === 'Skill' && buf.input?.skill) data.skill_name = buf.input.skill;
+    events.push(mk(last, 'PostToolUse', data, {}, `${sessionId}:unpaired:${fileId}:${id}`));
+  }
+
+  // Terminal markers (Stop / final SubagentStop) describe the LAST line, which is
+  // mutable: an appended transcript shifts the true end, but their event_id is
+  // file-stable so the server's insertIgnore would keep the stale one. Stop and
+  // SubagentStop are NOT excluded from gap/AI-hours metrics, so a stale end would
+  // skew duration. Only emit them once the file is dormant (engine sets
+  // emitTerminal=false while a file is still active); SessionStart is the first
+  // (immutable) line and is always safe.
+  if (emitTerminal && inSidechain) {
+    events.push(mk(last, 'SubagentStop',
+      { agent_id: last.agentId || `sub-${subSeq}`, agent_type: last.agentSlug || last.slug || null },
+      {}, `${sessionId}:substop:${fileId}:${subSeq}`));
+  }
+  if (emitTerminal) events.push(mk(last, 'Stop', {}, {}, `${sessionId}:stop:${fileId}`));
+  return events;
+}

package/cli/import.js

@@ -0,0 +1,66 @@
+/**
+ * `ai-lens import <source>` — import local AI-tool history into AI Lens.
+ * Currently supports `claude-code`; Cursor/Codex/Gemini are separate follow-ups.
+ */
+import { initLogger, error, info } from './logger.js';
+import { getVersionInfo } from './hooks.js';
+
+const BOOL_FLAGS = { '--dry-run': 'dryRun', '--no-redact': 'noRedact' };
+const VALUE_FLAGS = { '--days': 'days', '--since': 'since', '--projects': 'projects', '--analysis-max-age-days': 'analysisMaxAgeDays' };
+const INT_KEYS = new Set(['days', 'analysisMaxAgeDays']);
+
+/**
+ * Parse import flags. Returns { flags, errors }. CRITICAL: a value flag whose
+ * next token is missing or is itself another flag does NOT consume that token —
+ * it records a missing-value error and lets the loop process the following flag.
+ * (Otherwise `--projects --dry-run` would swallow `--dry-run` and silently run a
+ * REAL import instead of a preview.)
+ */
+export function parseFlags(argv) {
+  const flags = { days: 30, since: null, dryRun: false, projects: null, noRedact: false, analysisMaxAgeDays: 30 };
+  const errors = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (BOOL_FLAGS[arg]) { flags[BOOL_FLAGS[arg]] = true; continue; }
+    if (VALUE_FLAGS[arg]) {
+      const next = argv[i + 1];
+      if (next == null || next.startsWith('--')) { errors.push(`Missing value for ${arg}.`); continue; }
+      i++; // consume the value only now that we know it isn't another flag
+      const key = VALUE_FLAGS[arg];
+      flags[key] = INT_KEYS.has(key) ? parseInt(next, 10) : next;
+      continue;
+    }
+    errors.push(`Unknown flag "${arg}".`);
+  }
+  return { flags, errors };
+}
+
+export default async function importCmd() {
+  const source = process.argv[3];
+  const { flags, errors } = parseFlags(process.argv.slice(4));
+
+  const { version, commit } = getVersionInfo();
+  initLogger(`v${version} (${commit})`);
+
+  if (errors.length) {
+    errors.forEach((e) => error(e));
+    info('Usage: ai-lens import claude-code [--days N | --since YYYY-MM-DD] [--projects A,B] [--dry-run] [--no-redact]');
+    process.exitCode = 1;
+    return;
+  }
+
+  switch (source) {
+    case 'claude-code': {
+      const { default: importClaudeCode } = await import('./import/claude-code.js');
+      await importClaudeCode(flags);
+      break;
+    }
+    case undefined:
+      error('Usage: ai-lens import <source>   (sources: claude-code)');
+      break;
+    default:
+      error(`Unknown import source "${source}". Supported: claude-code.`);
+      info('Cursor / Codex / Gemini imports are coming separately.');
+      process.exitCode = 1;
+  }
+}

package/client/capture.js

@@ -93,7 +93,7 @@ export function resolveIdentity(gitIdentity, event, hasAuthToken) {
 // Truncation (reused from ai-session-lens prompts.js approach)
 // =============================================================================
 
-const TRUNCATION_LIMITS = {
+export const TRUNCATION_LIMITS = {
   toolInput: { command: 500, old_string: 200, new_string: 200, default: 200 },
   toolResult: { Read: 200, Bash: 300, Grep: 200, Edit: 100, Write: 100, Glob: 100, default: 200 },
   userPrompt: 1000,
@@ -101,7 +101,7 @@ const TRUNCATION_LIMITS = {
   agentThought: 500,
 };
 
-function truncate(text, maxLen) {
+export function truncate(text, maxLen) {
   if (typeof text !== 'string' || text.length <= maxLen) return text;
   if (maxLen <= 0) return `[...truncated, ${text.length} chars total]`;
   // Avoid splitting UTF-16 surrogate pairs at the boundary.
@@ -114,7 +114,7 @@ function truncate(text, maxLen) {
   return text.slice(0, end) + ` [...truncated, ${text.length} chars total]`;
 }
 
-function truncateToolInput(input, toolName, depth = 0) {
+export function truncateToolInput(input, toolName, depth = 0) {
   if (!input || typeof input !== 'object') return input;
   // Depth limit prevents stack overflow on pathological input while still
   // truncating strings at any realistic nesting depth. A low limit (e.g. 5)
@@ -140,7 +140,7 @@ function truncateToolInput(input, toolName, depth = 0) {
   return result;
 }
 
-function truncateToolResult(result, toolName) {
+export function truncateToolResult(result, toolName) {
   if (typeof result === 'string') {
     const limit = TRUNCATION_LIMITS.toolResult[toolName] || TRUNCATION_LIMITS.toolResult.default;
     return truncate(result, limit);
@@ -599,7 +599,7 @@ function findGitRoot(filePath) {
  *
  * Returns `dir` unchanged when no `.git` is found anywhere up the tree.
  */
-function canonicalizeProjectPath(dir) {
+export function canonicalizeProjectPath(dir) {
   if (!dir || typeof dir !== 'string') return dir;
   return findGitRootFromDir(dir) || dir;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lens",
-  "version": "0.8.74",
+  "version": "0.8.80",
   "type": "module",
   "description": "Centralized session analytics for AI coding tools",
   "bin": {