nomoremeatproxy 0.0.0-stage → 0.1.0

package/src/history/claude.mjs

@@ -0,0 +1,263 @@
+// Claude history: list and read Claude Code sessions from their local session files. The
+// file format is not a documented interface, so every field is read defensively.
+// Sections: records (pure) / files / find and read / compact conversation / message search.
+import { createReadStream, existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { sameFolder } from './folder.mjs';
+import { matchedOn, matchItem, textWords } from './match.mjs';
+import { clipItems, firstLine, lastTurns } from './render.mjs';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// A search inside messages reads at most this many of the most recent session files. On the
+// development machine, reading all 46 files there (420 MB) took about 2 seconds.
+export const TEXT_SCAN = 200;
+
+// --- records ---
+
+// The text the user typed, or null for tool results, injected records and side conversations.
+function promptText(record) {
+  if (record.type !== 'user' || record.isMeta || record.isSidechain) return null;
+  const content = record.message?.content;
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content) || content.some((block) => block.type === 'tool_result')) return null;
+  return content.filter((block) => block.type === 'text').map((block) => block.text).join('\n') || null;
+}
+
+// Returns null for blocks that are not surfaced, such as the model's private reasoning.
+export function describeClaudeBlock(block) {
+  if (block.type === 'text') return { kind: 'assistant', text: block.text ?? '' };
+  if (block.type !== 'tool_use') return null;
+  const detail = block.input?.command ?? block.input?.file_path ?? block.input?.description ?? '';
+  return { kind: 'tool', text: detail ? `${block.name}: ${detail}` : String(block.name) };
+}
+
+// Adds one record to the session and returns the items it added.
+function foldClaudeRecord(session, record) {
+  if (record.timestamp && record.timestamp > (session.updatedAt ?? '')) session.updatedAt = record.timestamp;
+  if (record.cwd) session.cwd = record.cwd;
+  if (record.type === 'custom-title' && record.customTitle) session.title = record.customTitle;
+  const prompt = promptText(record);
+  if (prompt !== null) {
+    const item = { kind: 'user', text: prompt };
+    session.turns.push({ startedAt: record.timestamp ?? null, items: [item] });
+    return [item];
+  }
+  if (record.type !== 'assistant' || record.isSidechain || session.turns.length === 0) return [];
+  const blocks = Array.isArray(record.message?.content) ? record.message.content : [];
+  const items = blocks.map(describeClaudeBlock).filter(Boolean);
+  session.turns.at(-1).items.push(...items);
+  return items;
+}
+
+const newSession = () => ({ title: '', cwd: null, updatedAt: null, turns: [] });
+
+function finishSession(session) {
+  if (!session.title) session.title = firstLine(session.turns[0]?.items[0]?.text);
+  return session;
+}
+
+export function foldClaudeRecords(records) {
+  const session = newSession();
+  for (const record of records) foldClaudeRecord(session, record);
+  return finishSession(session);
+}
+
+// A record, or null for a line that is torn, damaged or not a record at all.
+function parseRecord(line) {
+  try {
+    const record = JSON.parse(line);
+    return record && typeof record === 'object' && !Array.isArray(record) ? record : null;
+  } catch {
+    return null;
+  }
+}
+
+// --- files ---
+
+export function claudeProjectsDir(env = process.env) {
+  return path.join(env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), '.claude'), 'projects');
+}
+
+function sessionFiles(projectsDir) {
+  if (!existsSync(projectsDir)) return [];
+  return readdirSync(projectsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .flatMap((project) =>
+      readdirSync(path.join(projectsDir, project.name))
+        .filter((name) => UUID.test(name.replace(/\.jsonl$/, '')) && name.endsWith('.jsonl'))
+        .map((name) => ({ threadId: name.replace(/\.jsonl$/, ''), file: path.join(projectsDir, project.name, name) })),
+    );
+}
+
+function loadSession(file) {
+  // A session being written can end in a torn line.
+  return foldClaudeRecords(sessionRecords(file));
+}
+
+const sessionRecords = (file) => readFileSync(file, 'utf8').split('\n').map(parseRecord).filter(Boolean);
+
+// --- find and read ---
+
+export function findClaudeSessions({ search, limit, project, projectsDir = claudeProjectsDir() }) {
+  const files = sessionFiles(projectsDir);
+  const needle = String(search ?? '').toLowerCase();
+  const matches = files
+    .map(({ threadId, file }) => ({ threadId, ...loadSession(file) }))
+    .filter((session) => session.title.toLowerCase().includes(needle) && (!project || sameFolder(session.cwd, project)))
+    .sort((a, b) => String(b.updatedAt ?? '').localeCompare(String(a.updatedAt ?? '')));
+  return {
+    side: 'claude',
+    matchedOn: project ? 'title, within the project folder' : 'title',
+    scope: `${files.length} Claude Code session files on this machine`,
+    more: matches.length > limit,
+    threads: matches.slice(0, limit).map(({ threadId, title, updatedAt, cwd }) => ({ threadId, title, updatedAt, cwd })),
+  };
+}
+
+function sessionEntry(threadId, projectsDir) {
+  // The Claude desktop app shows the same id with a `local_` prefix.
+  const id = String(threadId ?? '').replace(/^local_/, '');
+  if (!UUID.test(id)) throw new Error(`invalid Claude session id: ${JSON.stringify(threadId)}`);
+  const entry = sessionFiles(projectsDir).find((candidate) => candidate.threadId === id);
+  if (!entry) throw new Error(`no Claude session ${id} on this machine`);
+  return { id, file: entry.file };
+}
+
+export function readClaudeSession({ threadId, turns, maxChars, projectsDir = claudeProjectsDir() }) {
+  const { id, file } = sessionEntry(threadId, projectsDir);
+  const session = loadSession(file);
+  return {
+    side: 'claude',
+    threadId: id,
+    title: session.title,
+    updatedAt: session.updatedAt,
+    cwd: session.cwd,
+    turnsTotal: session.turns.length,
+    turns: lastTurns(session.turns, turns).map((turn) => ({ startedAt: turn.startedAt, items: clipItems(turn.items, maxChars) })),
+  };
+}
+
+// --- compact conversation ---
+
+export function claudeConversation(records) {
+  const turns = [];
+  for (const record of records) {
+    if (record.type !== 'user' && record.type !== 'assistant') continue;
+    const content = record.message?.content;
+    const blocks = typeof content === 'string' ? [{ type: 'text', text: content }] : Array.isArray(content) ? content : [];
+    const text = blocks.filter(block => block?.type === 'text').map(block => block.text ?? '').join('\n');
+    // Structured provenance wins. Old local command records lack it: recognize only complete
+    // machine envelopes, not mentions of /compact or task notifications in ordinary prose.
+    const context = record.isCompactSummary === true;
+    const synthetic = record.isMeta || record.isSidechain || ['task-notification', 'peer'].includes(record.origin?.kind) ||
+      record.turnOrigin === 'task_notification' ||
+      /^<command-name>\/compact<\/command-name>(?:\s*<command-message>[\s\S]*<\/command-message>)?(?:\s*<command-args>[\s\S]*<\/command-args>)?\s*$/.test(text) ||
+      /^<local-command-stdout>Compacted [\s\S]*<\/local-command-stdout>\s*$/.test(text);
+    const omission = context ? 'context' : synthetic ? 'synthetic' : null;
+    const items = blocks.flatMap(block => {
+      if (!block || typeof block !== 'object') return [{ kind: 'unsupported', text: '', omission: 'privateOrUnsupported' }];
+      if (block.type === 'text') return [{ kind: record.type === 'user' ? 'user' : 'assistant', text: String(block.text ?? ''), ...(omission ? { omission } : {}) }];
+      const described = describeClaudeBlock(block);
+      if (described) return [{ ...described, ...(omission ? { omission } : {}) }];
+      if (block.type === 'tool_result') return [{ kind: 'tool-result', text: typeof block.content === 'string' ? block.content : JSON.stringify(block.content ?? ''), ...(omission ? { omission } : {}) }];
+      // Never surface private reasoning, even with --tools; count its exclusion without text.
+      return [{ kind: 'private', text: '', omission: 'privateOrUnsupported' }];
+    });
+    const startsTurn = record.type === 'user' && !blocks.some(block => block?.type === 'tool_result');
+    if (startsTurn || turns.length === 0) turns.push({ startedAt: record.timestamp ?? null, items: [] });
+    turns.at(-1).items.push(...items);
+  }
+  return turns;
+}
+
+export function readClaudeConversation({ threadId, projectsDir = claudeProjectsDir() }) {
+  const { id, file } = sessionEntry(threadId, projectsDir);
+  return { side: 'claude', threadId: id, turns: claudeConversation(sessionRecords(file)) };
+}
+
+// --- search inside messages ---
+
+// Reads a session file line by line up to its first matching message, or to the end when the
+// final title is needed. Limit: a title set after the match is not seen when reading stops.
+// One assistant message is written as several records that share its message id, so their
+// text is gathered before matching; tool calls and tool output are left out.
+async function firstMatch(file, words, readToEnd) {
+  const session = newSession();
+  let match = null;
+  let open = null; // the message being gathered: { key, kind, text, at }
+  const close = () => {
+    const found = !match && open && matchItem(open, words);
+    if (found) match = { ...found, at: open.at };
+    open = null;
+  };
+  const input = createReadStream(file, 'utf8');
+  try {
+    for await (const line of readline.createInterface({ input, crlfDelay: Infinity })) {
+      const record = parseRecord(line);
+      if (!record) continue;
+      let said;
+      try {
+        said = foldClaudeRecord(session, record).filter((item) => item.kind === 'user' || item.kind === 'assistant');
+      } catch {
+        continue; // A record with damaged contents is skipped like a damaged line.
+      }
+      if (said.length === 0) continue;
+      const key = record.message?.id ?? Symbol('one record');
+      if (open?.key !== key) close();
+      if (match && !readToEnd) break;
+      const text = said.map((item) => item.text).join('\n');
+      if (open) open.text += `\n${text}`;
+      else open = { key, kind: said[0].kind, text, at: record.timestamp ?? null };
+    }
+    close();
+  } finally {
+    input.destroy();
+  }
+  return { session: finishSession(session), match };
+}
+
+export async function searchClaudeSessions({ search, text, limit, project, projectsDir = claudeProjectsDir(), bound = TEXT_SCAN }) {
+  // A file that cannot be read, or is gone since the listing, is skipped and counted.
+  let unreadable = 0;
+  const files = sessionFiles(projectsDir)
+    .flatMap((entry) => {
+      try {
+        return [{ ...entry, modified: statSync(entry.file).mtime }];
+      } catch {
+        unreadable += 1;
+        return [];
+      }
+    })
+    .sort((a, b) => b.modified - a.modified);
+  const words = textWords(text);
+  const needle = String(search ?? '').toLowerCase();
+  const threads = [];
+  let looked = 0;
+  for (const { threadId, file, modified } of files.slice(0, bound)) {
+    if (threads.length > limit) break;
+    looked += 1;
+    let session;
+    let match;
+    try {
+      ({ session, match } = await firstMatch(file, words, Boolean(needle)));
+    } catch {
+      unreadable += 1;
+      continue;
+    }
+    if (!match || !session.title.toLowerCase().includes(needle) || (project && !sameFolder(session.cwd, project))) continue;
+    // The file's last change stands for when the chat was updated, since reading may stop early.
+    threads.push({ threadId, title: session.title, updatedAt: modified.toISOString(), cwd: session.cwd, match });
+  }
+  const cut = looked === bound && files.length > bound ? `; the search stops at ${bound}, so ${files.length - bound} older ones were not searched` : '';
+  return {
+    side: 'claude',
+    matchedOn: matchedOn({ search, text, project }),
+    scope:
+      `the ${looked} most recent of ${files.length} Claude Code session files on this machine` +
+      `${unreadable ? `; ${unreadable} could not be read` : ''}${cut}`,
+    more: threads.length > limit,
+    threads: threads.slice(0, limit),
+  };
+}

package/src/history/codex.mjs

@@ -0,0 +1,164 @@
+// Codex history: list and read the threads the Codex desktop app shows, through app-server.
+// Sections: descriptions / legacy list/read / compact conversation / message search.
+import { withCodexServer } from '../adapters/codex-transport.mjs';
+import { sameFolder } from './folder.mjs';
+import { matchedOn, matchItem, textWords } from './match.mjs';
+import { clipItems, firstLine, lastTurns } from './render.mjs';
+
+const toIso = (seconds) => (typeof seconds === 'number' ? new Date(seconds * 1000).toISOString() : null);
+
+// Returns null for items that are not surfaced, such as the model's private reasoning.
+export function describeCodexItem(item) {
+  switch (item.type) {
+    case 'userMessage':
+      return { kind: 'user', text: (item.content ?? []).filter((part) => part.type === 'text').map((part) => part.text).join('\n') };
+    case 'agentMessage':
+      return { kind: 'assistant', text: item.text ?? '' };
+    case 'plan':
+      return { kind: 'plan', text: item.text ?? '' };
+    case 'commandExecution':
+      return { kind: 'command', text: typeof item.exitCode === 'number' ? `${item.command} (exit ${item.exitCode})` : String(item.command) };
+    case 'fileChange':
+      return { kind: 'file-change', text: (item.changes ?? []).map((change) => change.path).join('\n') };
+    case 'mcpToolCall':
+      return { kind: 'tool', text: [item.server, item.tool].filter(Boolean).join('.') };
+    case 'dynamicToolCall':
+      return { kind: 'tool', text: [item.namespace, item.tool].filter(Boolean).join('.') };
+    case 'webSearch':
+      return { kind: 'web-search', text: item.query ?? '' };
+    case 'reasoning':
+      return null;
+    default:
+      return { kind: item.type, text: '' };
+  }
+}
+
+export function summarizeCodexThread(thread) {
+  return {
+    threadId: thread.id,
+    title: thread.name || firstLine(thread.preview),
+    updatedAt: toIso(thread.updatedAt),
+    cwd: thread.cwd ?? null,
+  };
+}
+
+// Read from outside, a turn another process is still running reports `interrupted` (see
+// findRequestTurn). A newer turn means an older one ended, so only the newest is in doubt.
+export const shownStatus = (status, newest) => (newest && status === 'interrupted' ? 'interrupted, or still running' : status ?? null);
+
+export function renderCodexThread(thread, { turns, maxChars }) {
+  const all = thread.turns ?? [];
+  return {
+    side: 'codex',
+    ...summarizeCodexThread(thread),
+    turnsTotal: all.length,
+    turns: lastTurns(all, turns).map((turn) => ({
+      startedAt: toIso(turn.startedAt),
+      status: shownStatus(turn.status, turn === all.at(-1)),
+      items: clipItems((turn.items ?? []).map(describeCodexItem).filter(Boolean), maxChars),
+    })),
+  };
+}
+
+// Codex compares a thread's folder in its own way, so the folder is matched here instead, over
+// the newest threads only. The result says how far back that reached. thread/list returns at
+// most 100 threads in one request, whatever larger limit is asked for.
+const LIST_MAX = 100;
+
+export function threadsInFolder(threads, project) {
+  return project ? threads.filter((thread) => sameFolder(thread.cwd, project)) : threads;
+}
+
+export async function findCodexThreads({ search, limit, project }) {
+  const result = await withCodexServer((client) =>
+    client.request('thread/list', { searchTerm: search || null, limit: project ? LIST_MAX : limit, sortKey: 'updated_at' }),
+  );
+  const listed = 'threads the Codex app lists (interactive sources, not archived)';
+  const matches = threadsInFolder(result.data.map(summarizeCodexThread), project);
+  return {
+    side: 'codex',
+    matchedOn: project ? 'title, within the project folder' : 'title',
+    scope: project ? `the newest ${result.data.length} ${listed}` : listed,
+    more: matches.length > limit || Boolean(result.nextCursor),
+    threads: matches.slice(0, limit),
+  };
+}
+
+export async function readCodexThread({ threadId, turns, maxChars }) {
+  const result = await withCodexServer((client) => client.request('thread/read', { threadId, includeTurns: true }));
+  return renderCodexThread(result.thread, { turns, maxChars });
+}
+
+// Separate CLI view: do not change the legacy renderer or the recovery/check consumers.
+export function codexConversation(thread) {
+  return {
+    side: 'codex', threadId: thread.id,
+    turns: (thread.turns ?? []).map(turn => ({ startedAt: toIso(turn.startedAt), status: turn.status ?? null, items: (turn.items ?? []).map(item => {
+      const described = describeCodexItem(item);
+      if (!described) return { kind: 'private', text: '', omission: 'privateOrUnsupported' };
+      return { ...described, ...(item.type === 'contextCompaction' ? { omission: 'context' } : {}) };
+    }) })),
+  };
+}
+
+export async function readCodexConversation({ threadId }) {
+  const result = await withCodexServer(client => client.request('thread/read', { threadId, includeTurns: true }));
+  return codexConversation(result.thread);
+}
+
+// --- search inside messages ---
+
+// How many threads a search inside messages reads, one after another on one server. Without a
+// project it lists only that many; with one it lists up to LIST_MAX and reads the project's.
+// Listing is most of the cost: on the development machine listing 20 threads took about 4
+// seconds and 100 about 7, while each read took under 0.1 seconds.
+export const TEXT_SCAN = 20;
+
+export function firstCodexMatch(thread, words) {
+  for (const turn of thread.turns ?? []) {
+    for (const item of turn.items ?? []) {
+      const described = describeCodexItem(item);
+      const match = described && matchItem(described, words);
+      if (match) return { ...match, at: toIso(turn.startedAt) };
+    }
+  }
+  return null;
+}
+
+export async function searchCodexThreads({ search, text, limit, project, bound = TEXT_SCAN, server = withCodexServer }) {
+  const words = textWords(text);
+  return server(async (client) => {
+    const listed = await client.request('thread/list', { searchTerm: search || null, limit: project ? LIST_MAX : bound, sortKey: 'updated_at' });
+    const inFolder = threadsInFolder(listed.data, project);
+    const threads = [];
+    let looked = 0;
+    let unreadable = 0;
+    for (const thread of inFolder.slice(0, bound)) {
+      if (threads.length > limit) break;
+      looked += 1;
+      let full;
+      try {
+        ({ thread: full } = await client.request('thread/read', { threadId: thread.id, includeTurns: true }));
+      } catch {
+        unreadable += 1;
+        continue;
+      }
+      const match = firstCodexMatch(full, words);
+      if (match) threads.push({ ...summarizeCodexThread(full), match });
+    }
+    const lists = 'the Codex app lists (interactive sources, not archived)';
+    const searched = project
+      ? `the ${looked} threads in the project folder among the ${listed.data.length} most recent threads ${lists}`
+      : `the ${looked} most recent threads ${lists}`;
+    let cut = '';
+    if (threads.length <= limit && inFolder.length > bound) cut = `; the search reads at most ${bound} threads, so older ones in the project folder were not searched`;
+    else if (threads.length <= limit && listed.nextCursor) cut = `; threads older than the ${listed.data.length} listed were not searched`;
+    return {
+      side: 'codex',
+      matchedOn: matchedOn({ search, text, project }),
+      scope: `${searched}${unreadable ? `; ${unreadable} of them could not be read` : ''}${cut}`,
+      more: threads.length > limit,
+      threads: threads.slice(0, limit),
+    };
+  });
+}

package/src/history/compact.mjs

@@ -0,0 +1,149 @@
+// Compact conversation pages. Sections: validation/cursors / selection / byte-budgeted pages.
+// The legacy renderers remain unchanged; only the CLI opts into this view.
+import { createHash } from 'node:crypto';
+import { shownStatus } from './codex.mjs';
+
+const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const size = (value) => Buffer.byteLength(JSON.stringify(value)) + 1; // includes CLI newline
+const stats = (items) => ({ items: items.length, textUnits: items.reduce((sum, item) => sum + item.text.length, 0) });
+const integer = (n) => Number.isSafeInteger(n) && n >= 0;
+const splitsScalar = (value, at) => at > 0 && at < value.length &&
+  value.charCodeAt(at - 1) >= 0xd800 && value.charCodeAt(at - 1) <= 0xdbff &&
+  value.charCodeAt(at) >= 0xdc00 && value.charCodeAt(at) <= 0xdfff;
+
+export function validateCompactOptions({ turns = 2, maxChars = 4000, budget = 16000, cursor } = {}) {
+  for (const [name, value] of Object.entries({ turns, 'max-chars': maxChars, budget })) {
+    if (!Number.isSafeInteger(value) || value < 1) throw new Error(`--${name} must be a positive safe integer`);
+  }
+  if (budget < 2048) throw new Error('--budget must be at least 2048 UTF-8 bytes');
+  if (cursor !== undefined && (typeof cursor !== 'string' || !/^[A-Za-z0-9_-]{1,2048}$/.test(cursor))) throw new Error('invalid read cursor');
+  if (cursor !== undefined) decodeCursor(cursor);
+}
+
+function decodeCursor(cursor) {
+  try {
+    const page = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    if (!page || Object.keys(page).sort().join(',') !== 'end,hash,index,offset,scope,snapshotEnd,start,tools,v' ||
+        page.v !== 2 || typeof page.tools !== 'boolean' || !/^[a-f0-9]{64}$/.test(page.scope) ||
+        !/^[a-f0-9]{64}$/.test(page.hash) || ![page.start, page.end, page.snapshotEnd, page.index, page.offset].every(integer)) throw new Error();
+    return page;
+  } catch {
+    throw new Error('invalid read cursor');
+  }
+}
+
+function reason(item, tools) {
+  if (item.omission) return item.omission;
+  if (item.kind === 'user' || item.kind === 'assistant') return null;
+  return tools ? null : 'tools';
+}
+
+export function renderConversation(source, { turns = 2, maxChars = 4000, budget = 16000, tools = false, cursor } = {}) {
+  validateCompactOptions({ turns, maxChars, budget, cursor });
+  const scope = hash([source.side, source.threadId]);
+  const all = source.turns ?? [];
+  let page = cursor ? decodeCursor(cursor) : null;
+  if (page && (page.scope !== scope || page.tools !== tools)) throw new Error('read cursor belongs to another thread, side or --tools view');
+  const end = page?.end ?? all.length;
+  const snapshotEnd = page?.snapshotEnd ?? all.length;
+  if (end > snapshotEnd) throw new Error('invalid read cursor snapshot');
+  if (snapshotEnd > all.length) throw new Error('history changed; restart read without --cursor');
+  // Hidden-only turns do not consume --turns, so notifications cannot crowd out discussion.
+  const visible = all.slice(0, end).flatMap((turn, index) => turn.items.some(item => !reason(item, tools)) ? [index] : []);
+  const start = page?.start ?? visible[Math.max(0, visible.length - turns)] ?? 0;
+  if (start > end) throw new Error('invalid read cursor window');
+  const window = all.slice(start, end);
+  const digest = hash(window);
+  if (page && page.hash !== digest) throw new Error('history changed; restart read without --cursor');
+  const entries = [];
+  const filtered = {};
+  window.forEach((turn, turnIndex) => turn.items.forEach((item, itemIndex) => {
+    const omitted = reason(item, tools);
+    if (omitted) {
+      const count = filtered[omitted] ??= { items: 0, textUnits: 0 };
+      count.items += 1;
+      count.textUnits += item.text.length;
+    } else entries.push({ turn: start + turnIndex, item: itemIndex, startedAt: turn.startedAt ?? null,
+      // Raw statuses stay in the digest; presentation uses the saved whole-thread newest
+      // turn, not this window's end or a newer append, so cursors remain stable.
+      status: source.side === 'codex' ? shownStatus(turn.status, start + turnIndex === snapshotEnd - 1) : turn.status ?? null,
+      kind: item.kind, text: item.text });
+  }));
+  const index = page?.index ?? 0;
+  const offset = page?.offset ?? 0;
+  if (index > entries.length || (index === entries.length ? offset !== 0 : offset > entries[index].text.length)) throw new Error('invalid read cursor position');
+  if (index < entries.length && splitsScalar(entries[index].text, offset)) throw new Error('invalid read cursor scalar boundary');
+  const outside = [...all.slice(0, start), ...all.slice(end)].flatMap(turn => turn.items);
+  const before = stats(entries.slice(0, index));
+  before.textUnits += offset;
+  if (offset > 0) before.items += 1;
+  const olderVisible = visible.filter(i => i < start);
+  const count = visible.filter(i => i >= start).length;
+  const olderStart = olderVisible[Math.max(0, olderVisible.length - count)] ?? 0;
+  const olderCursor = olderVisible.length === 0 ? null : Buffer.from(JSON.stringify({
+    v: 2, scope, hash: hash(all.slice(olderStart, start)), tools, snapshotEnd,
+    start: olderStart, end: start, index: 0, offset: 0,
+  })).toString('base64url');
+  const messages = [];
+  const resultAt = (nextIndex, nextOffset) => {
+    const remaining = stats(entries.slice(nextIndex));
+    remaining.textUnits -= nextOffset;
+    const more = nextIndex < entries.length;
+    return {
+      side: source.side, threadId: source.threadId, view: tools ? 'conversation+tools' : 'conversation',
+      window: { startTurn: start, endTurn: end, conversationTurns: visible.filter(i => i >= start).length },
+      budget: { bytes: budget, unit: 'UTF-8 serialized JSON including newline' },
+      messages,
+      omitted: {
+        outsideWindow: { ...stats(outside), olderTurns: start, newerTurns: all.length - end },
+        filtered, beforePage: before, afterPage: remaining,
+        splitItems: messages.filter(item => item.offset > 0 || item.text.length < item.totalTextUnits).length,
+      },
+      nextCursor: more ? Buffer.from(JSON.stringify({ v: 2, scope, hash: digest, tools, snapshotEnd, start, end, index: nextIndex, offset: nextOffset })).toString('base64url') : null,
+      olderCursor: more ? null : olderCursor,
+    };
+  };
+  let nextIndex = index;
+  let nextOffset = offset;
+  const result = resultAt(nextIndex, nextOffset);
+  if (size(result) > budget) throw new Error(`--budget too small for page metadata; need at least ${size(result)} UTF-8 bytes`);
+  while (nextIndex < entries.length) {
+    const entry = entries[nextIndex];
+    let available = Math.min(maxChars, entry.text.length - nextOffset);
+    if (splitsScalar(entry.text, nextOffset + available)) available -= 1;
+    // Limit: --max-chars=1 needs two UTF-16 units for one supplementary Unicode scalar.
+    if (available === 0 && nextOffset < entry.text.length) available = 2;
+    const boundaries = [0];
+    for (let i = 0; i < available;) {
+      i += entry.text.codePointAt(nextOffset + i) > 0xffff ? 2 : 1;
+      boundaries.push(i);
+    }
+    const fragment = { ...entry, text: '', offset: nextOffset, totalTextUnits: entry.text.length };
+    messages.push(fragment);
+    const candidateAt = (length) => {
+      fragment.text = entry.text.slice(nextOffset, nextOffset + length);
+      const complete = nextOffset + length === entry.text.length;
+      return resultAt(complete ? nextIndex + 1 : nextIndex, complete ? 0 : nextOffset + length);
+    };
+    let low = size(candidateAt(available)) <= budget ? boundaries.length - 1 : 0;
+    let high = low === boundaries.length - 1 ? low : Math.max(0, boundaries.length - 2);
+    // Measure the serialized envelope, not just text: escaping and metadata count too.
+    while (low < high) {
+      const mid = Math.ceil((low + high) / 2);
+      if (size(candidateAt(boundaries[mid])) <= budget) low = mid;
+      else high = mid - 1;
+    }
+    const length = boundaries[low];
+    const candidate = candidateAt(length);
+    if (size(candidate) > budget || (length === 0 && available > 0)) {
+      const minimum = size(candidateAt(boundaries[1] ?? 0));
+      messages.pop();
+      if (messages.length === 0) throw new Error(`--budget too small for the next fragment; need at least ${minimum} UTF-8 bytes`);
+      break;
+    }
+    nextOffset += length;
+    if (nextOffset === entry.text.length) { nextIndex += 1; nextOffset = 0; }
+    if (nextOffset > 0) break;
+  }
+  return resultAt(nextIndex, nextOffset);
+}

package/src/history/folder.mjs

@@ -0,0 +1,10 @@
+// Whether two folder paths name the same folder, however each tool wrote them: a trailing
+// slash anywhere, and on Windows either kind of slash and any letter case. Elsewhere a
+// backslash is an ordinary character of a name.
+export function folderKey(folder, platform = process.platform) {
+  const text = String(folder ?? '');
+  const plain = platform === 'win32' ? text.replaceAll('\\', '/').toLowerCase() : text;
+  return plain.replace(/\/+$/, '');
+}
+
+export const sameFolder = (a, b, platform = process.platform) => Boolean(a) && Boolean(b) && folderKey(a, platform) === folderKey(b, platform);

package/src/history/index.mjs

@@ -0,0 +1,35 @@
+// Find and read threads on either side by one interface.
+import { findClaudeSessions, readClaudeConversation, readClaudeSession, searchClaudeSessions } from './claude.mjs';
+import { findCodexThreads, readCodexConversation, readCodexThread, searchCodexThreads } from './codex.mjs';
+import { renderConversation, validateCompactOptions } from './compact.mjs';
+
+const SIDES = Object.freeze({
+  codex: Object.freeze({ find: findCodexThreads, searchText: searchCodexThreads, read: readCodexThread, conversation: readCodexConversation }),
+  claude: Object.freeze({ find: findClaudeSessions, searchText: searchClaudeSessions, read: readClaudeSession, conversation: readClaudeConversation }),
+});
+
+function sideNamed(name) {
+  const key = String(name ?? '').toLowerCase();
+  if (!Object.hasOwn(SIDES, key)) throw new Error(`--side must be one of: ${Object.keys(SIDES).join(', ')}`);
+  return SIDES[key];
+}
+
+// `project`, when given, keeps only threads whose folder is that project folder. `text`, when
+// given, searches inside messages as well.
+export async function findThreads({ side, search = '', text, limit = 10, project }) {
+  const chosen = sideNamed(side);
+  if (text === undefined) return chosen.find({ search, limit, project });
+  if (!String(text).trim()) throw new Error('--text is empty');
+  return chosen.searchText({ search, text, limit, project });
+}
+
+export async function readThread({ side, threadId, turns = 2, maxChars = 4000 }) {
+  if (!threadId) throw new Error('--thread is required');
+  return sideNamed(side).read({ threadId, turns, maxChars });
+}
+
+export async function readConversation({ side, threadId, ...options }) {
+  if (!threadId) throw new Error('--thread is required');
+  validateCompactOptions(options);
+  return renderConversation(await sideNamed(side).conversation({ threadId }), options);
+}

package/src/history/match.mjs

@@ -0,0 +1,20 @@
+// Searching inside messages, the same on either side: a message matches when it holds every
+// word, in any order and any case. Only what the person and the assistant wrote is searched.
+import { excerpt } from './render.mjs';
+
+export const textWords = (text) => String(text ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+
+// Where an item matched, or null. `item` is a described item ({ kind, text }) of either side.
+export function matchItem(item, words) {
+  if (item.kind !== 'user' && item.kind !== 'assistant') return null;
+  const flat = String(item.text ?? '').replace(/\s+/g, ' ').trim();
+  const lower = flat.toLowerCase();
+  if (!words.every((word) => lower.includes(word))) return null;
+  // Lowercasing can change the length of a few characters, which shifts the excerpt slightly.
+  return { by: item.kind, excerpt: excerpt(flat, Math.min(...words.map((word) => lower.indexOf(word)))) };
+}
+
+export function matchedOn({ search, text, project }) {
+  const what = [search && 'title', text && 'text'].filter(Boolean).join(' and ') || 'title';
+  return project ? `${what}, within the project folder` : what;
+}

package/src/history/render.mjs

@@ -0,0 +1,23 @@
+// Shared shaping for thread history, whichever side it came from.
+
+export function clip(text, maxChars) {
+  const value = String(text ?? '');
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, maxChars)}\n[cut: ${value.length - maxChars} more characters; raise --max-chars to read them]`;
+}
+
+export function firstLine(text) {
+  const line = String(text ?? '').split('\n').find((candidate) => candidate.trim());
+  return line ? line.trim() : '';
+}
+
+export const lastTurns = (turns, count) => turns.slice(Math.max(0, turns.length - count));
+
+export const clipItems = (items, maxChars) => items.map((item) => ({ ...item, text: clip(item.text, maxChars) }));
+
+// One line of about `size` characters around position `at`, with ... where it was cut.
+export function excerpt(text, at, size = 160) {
+  const flat = String(text ?? '').replace(/\s+/g, ' ').trim();
+  const start = Math.max(0, Math.min(at - Math.floor(size / 4), flat.length - size));
+  return `${start > 0 ? '...' : ''}${flat.slice(start, start + size)}${start + size < flat.length ? '...' : ''}`;
+}