/** * @fileoverview Per-session edit history: the parsed edits and Bash images of one claude * session, plus where in each transcript file reading stopped. * * Sources are the main transcript (`main`) and each subagent transcript * (`subagents/agent-.jsonl`). Each has a cursor: * - `offset` — the next byte to read forward; always a line boundary. * - `floor` — the lowest byte already parsed; > 0 while older lines are unread * ("ältere laden" reads `[floor − budget, floor)`). * The store decides WHICH byte range to read (`nextRange`/`olderRange`); the caller reads * it — locally or over ssh — and hands the bytes to `apply`. Cuts happen only at `\n`, * which never occurs inside a UTF-8 sequence, so multibyte characters split by a chunk * boundary are never decoded half. * * A first read of a file starts `budget` bytes before its end (transcripts reach 100 MB+), * drops the cut first line and leaves `floor` there. A line longer than the budget is * skipped instead of blocking the cursor, reading forward (`midLine`) and backward * (`floorMidLine`). * * A new conversation (`/clear`, resume) arrives as a new `transcriptId`: cursors and * pending Bash calls start over, entries stay. Entries are capped at {@link MAX_ENTRIES} * and {@link MAX_STORE_BYTES} of diff text; the oldest by time are dropped. Besides them * the file holds the cursors, at most {@link MAX_PENDING_BASH} unanswered Bash calls and at * most {@link MAX_AGENTS} subagent labels. * * ⚠️ The file holds secrets: a diff carries whatever the agent wrote, keys and `.env` * contents included. So, like `intents.json`, it is written 0600 via tmp+rename, bounded, * deleted with the session (`remove()`), never fed to `/api/search`, and blocked from the * file routes by `isSensitivePath` (`web/sensitive-path.ts`). * * Persisted as JSON under `dataPath('edit-history', '.json')`, written debounced. * * Tests: `test/edit-history-store.test.ts`. * * @module edit-history-store */ import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'; import { join } from 'node:path'; import { dataPath } from './config/instance.js'; import { MAX_HUNK_BYTES, MAX_PENDING_BASH, MAX_PENDING_COMMAND_CHARS, parseClaudeEditLines, type EditRecord, type EditTool, type ImageCandidate, type PendingBash, } from './edit-history-parse.js'; export const MAX_ENTRIES = 500; /** Diff text (and paths) kept per session; see {@link entryBytes}. */ export const MAX_STORE_BYTES = 4 * 1024 * 1024; /** Longest string kept from a subagent's `meta.json` field. */ export const MAX_AGENT_META_CHARS = 1024; /** * Subagent labels kept; past it the oldest one no entry uses is dropped. One more than * {@link MAX_ENTRIES}, so besides the newest label there always is one. */ export const MAX_AGENTS = MAX_ENTRIES + 1; /** Bytes read per file and pass (first read, forward step, "older" step). */ export const READ_BUDGET_BYTES = 8 * 1024 * 1024; export const MAIN_SOURCE = 'main'; const SAVE_DEBOUNCE_MS = 1000; const FILE_VERSION = 1; const NL = 0x0a; /** `bash`: an image a Bash call wrote; `sent`: an image claude delivered to the user. */ export type EditHistoryTool = EditTool | 'bash' | 'sent'; export interface EditHistoryEntry extends Omit { tool: EditHistoryTool; } export interface SourceCursor { offset: number; floor: number; /** The next forward read starts inside a line longer than the budget; skip to its end. */ midLine?: boolean; /** `floor` lies inside a line longer than the budget; the next older read drops its tail. */ floorMidLine?: boolean; } export interface AgentMeta { description: string; agentType: string; worktreePath?: string; worktreeBranch?: string; } export interface ByteRange { offset: number; len: number; } export interface ApplyInput { transcriptId: string; /** `main` or `subagents/agent-.jsonl`. */ source: string; startOffset: number; chunk: Buffer; /** Size of the file when the chunk was read. */ size: number; } export interface ApplyResult { added: number; candidates: ImageCandidate[]; } export interface ConfirmedImage { toolUseId: string; path: string; ts: number; agentId?: string; tool?: 'bash' | 'sent'; } export interface EditHistoryStoreOptions { /** Directory holding `.json`; default `dataPath('edit-history')`. */ dir?: string; debounceMs?: number; } interface StoreFile { version: number; sessionId: string; transcriptId: string | null; cursors: Record; pendingBash: PendingBash[]; agents: Record; entries: EditHistoryEntry[]; } function isObj(v: unknown): v is Record { return typeof v === 'object' && v !== null && !Array.isArray(v); } /** What an entry costs against {@link MAX_STORE_BYTES}: its path and diff lines, plus a fixed overhead. */ export function entryBytes(e: EditHistoryEntry): number { let n = 128 + Buffer.byteLength(e.path); for (const h of e.hunks) if (Array.isArray(h?.lines)) for (const l of h.lines) n += Buffer.byteLength(String(l)) + 3; return n; } function metaString(v: unknown): string | undefined { return typeof v === 'string' && v ? v.slice(0, MAX_AGENT_META_CHARS) : undefined; } /** Parse an `agent-.meta.json` text; null when it is not an object. */ export function parseAgentMeta(text: string): AgentMeta | null { try { return agentMetaFrom(JSON.parse(text)); } catch { return null; } } function isOffset(v: unknown): v is number { return Number.isSafeInteger(v) && (v as number) >= 0; } // The loaders below take the persisted file as untrusted: a hand-edited or damaged store // loses the broken parts instead of failing every request or stalling a cursor. function agentMetaFrom(raw: unknown): AgentMeta | null { if (!isObj(raw)) return null; const meta: AgentMeta = { description: metaString(raw.description) ?? '', agentType: metaString(raw.agentType) ?? '', }; const worktreePath = metaString(raw.worktreePath); const worktreeBranch = metaString(raw.worktreeBranch); if (worktreePath) meta.worktreePath = worktreePath; if (worktreeBranch) meta.worktreeBranch = worktreeBranch; return meta; } function cursorFrom(raw: unknown): SourceCursor | null { if (!isObj(raw) || !isOffset(raw.offset) || !isOffset(raw.floor) || raw.floor > raw.offset) return null; const cursor: SourceCursor = { offset: raw.offset, floor: raw.floor }; if (raw.midLine === true) cursor.midLine = true; if (raw.floorMidLine === true) cursor.floorMidLine = true; return cursor; } function pendingBashFrom(raw: unknown): PendingBash | null { if (!isObj(raw)) return null; const { id, ts, command, cwd, agentId } = raw; if (typeof id !== 'string' || typeof ts !== 'number' || typeof command !== 'string' || typeof cwd !== 'string') { return null; } const pending: PendingBash = { id, ts, command: command.slice(0, MAX_PENDING_COMMAND_CHARS), cwd }; if (typeof agentId === 'string') pending.agentId = agentId; return pending; } function isEntry(raw: unknown): raw is EditHistoryEntry { return ( isObj(raw) && typeof raw.id === 'string' && typeof raw.path === 'string' && typeof raw.ts === 'number' && Array.isArray(raw.hunks) && raw.hunks.every((h) => isObj(h) && Array.isArray(h.lines)) ); } export class EditHistoryStore { readonly sessionId: string; private readonly file: string; private readonly debounceMs: number; private transcriptId: string | null = null; private cursors = new Map(); private pendingBash: PendingBash[] = []; private agents = new Map(); private entries = new Map(); /** Sum of {@link entryBytes} over `entries`. */ private bytes = 0; private saveTimer: NodeJS.Timeout | null = null; /** The last queued write; `remove()` waits for it. */ private writing: Promise | null = null; private removed = false; constructor(sessionId: string, opts: EditHistoryStoreOptions = {}) { this.sessionId = sessionId; this.file = join(opts.dir ?? dataPath('edit-history'), `${sessionId}.json`); this.debounceMs = opts.debounceMs ?? SAVE_DEBOUNCE_MS; } /** A store with the persisted state of `sessionId`; empty when the file is missing or unreadable. */ static async load(sessionId: string, opts: EditHistoryStoreOptions = {}): Promise { const store = new EditHistoryStore(sessionId, opts); let data: unknown; try { data = JSON.parse(await readFile(store.file, 'utf-8')); } catch { return store; } if (!isObj(data)) return store; if (data.version !== FILE_VERSION) return store; const f = data as unknown as StoreFile; store.transcriptId = typeof f.transcriptId === 'string' ? f.transcriptId : null; for (const [k, raw] of Object.entries(isObj(f.cursors) ? f.cursors : {})) { const cursor = cursorFrom(raw); if (cursor) store.cursors.set(k, cursor); } if (Array.isArray(f.pendingBash)) { store.pendingBash = f.pendingBash .map(pendingBashFrom) .filter((p): p is PendingBash => p !== null) .slice(-MAX_PENDING_BASH); } if (Array.isArray(f.entries)) store.addRecords(f.entries.filter(isEntry)); for (const [k, raw] of Object.entries(isObj(f.agents) ? f.agents : {})) { const meta = agentMetaFrom(raw); if (meta) store.putAgent(k, meta); } return store; } getTranscriptId(): string | null { return this.transcriptId; } getCursor(source: string): SourceCursor | undefined { const c = this.cursors.get(source); return c ? { ...c } : undefined; } /** * True while any source has unread older lines that could still be shown. At a cap (no * room left for another entry) an older edit would be dropped the moment it is read, so * there is nothing more to load. */ get backfillTruncated(): boolean { if (this.entries.size >= MAX_ENTRIES || this.bytes > MAX_STORE_BYTES - MAX_HUNK_BYTES) return false; for (const c of this.cursors.values()) if (c.floor > 0) return true; return false; } /** Entries newest first. */ list(): EditHistoryEntry[] { return [...this.entries.values()].sort((a, b) => b.ts - a.ts); } get(id: string): EditHistoryEntry | undefined { return this.entries.get(id); } getAgents(): Record { return Object.fromEntries(this.agents); } hasAgentMeta(agentId: string): boolean { return this.agents.has(agentId); } /** Record a subagent's `meta.json`; ignored when it does not parse. */ setAgentMeta(agentId: string, metaText: string): void { const meta = this.removed ? null : parseAgentMeta(metaText); if (!meta) return; this.putAgent(agentId, meta); this.scheduleSave(); } /** * The next forward range to read from `source`, or null when nothing is new. * A conversation other than the stored one starts from scratch (see `apply`). */ nextRange(source: string, size: number, transcriptId: string, budget = READ_BUDGET_BYTES): ByteRange | null { const cursor = transcriptId === this.transcriptId ? this.cursors.get(source) : undefined; if (cursor && size >= cursor.offset) { if (size === cursor.offset) return null; return { offset: cursor.offset, len: Math.min(budget, size - cursor.offset) }; } // Unknown file, new conversation, or a file that shrank (replaced): read its end. const offset = Math.max(0, size - budget); return size > offset ? { offset, len: size - offset } : null; } /** The next older range of `source` ("ältere laden"), or null when it is read to its start. */ olderRange(source: string, budget = READ_BUDGET_BYTES): ByteRange | null { const cursor = this.cursors.get(source); if (!cursor || cursor.floor <= 0) return null; const offset = Math.max(0, cursor.floor - budget); return { offset, len: cursor.floor - offset }; } /** Every source with a cursor in the current conversation. */ knownSources(): string[] { return [...this.cursors.keys()]; } /** Sources with older lines left. */ sourcesWithOlder(): string[] { return [...this.cursors.entries()].filter(([, c]) => c.floor > 0).map(([s]) => s); } /** Apply a forward chunk read at `nextRange`. Returns new entries and Bash image candidates. */ apply(input: ApplyInput): ApplyResult { if (this.removed) return { added: 0, candidates: [] }; const { transcriptId, source, startOffset, chunk, size } = input; if (transcriptId !== this.transcriptId) { this.transcriptId = transcriptId; this.cursors.clear(); this.pendingBash = []; } let cursor = this.cursors.get(source); if (cursor && size < cursor.offset) { this.cursors.delete(source); cursor = undefined; } if (cursor && startOffset !== cursor.offset) return { added: 0, candidates: [] }; const atEof = startOffset + chunk.length >= size; // Bytes before `from` belong to a line that started before this chunk. let from = 0; if (cursor ? cursor.midLine : startOffset > 0) { const nl = chunk.indexOf(NL); if (nl === -1) { // Still inside that line: move past it unless it is the line being written. A first // read began inside it, so the floor does too. if (!atEof) this.setCursor(source, cursor, startOffset + chunk.length, startOffset, true, true); return { added: 0, candidates: [] }; } from = nl + 1; } const lastNl = chunk.lastIndexOf(NL); if (lastNl < from) { if (!atEof && chunk.length > 0) { // One line longer than the budget: skip it instead of re-reading it forever. this.setCursor(source, cursor, startOffset + chunk.length, startOffset + from, true); } else if (!cursor) { this.setCursor(source, undefined, startOffset + from, startOffset + from, false); } return { added: 0, candidates: [] }; } const end = lastNl + 1; this.setCursor(source, cursor, startOffset + end, startOffset + from, false); const parsed = parseClaudeEditLines(chunk.subarray(from, end).toString('utf8'), this.pendingBash); this.pendingBash = parsed.pending; const added = this.addRecords(parsed.records); this.scheduleSave(); return { added, candidates: parsed.candidates }; } /** * Apply a chunk read at `olderRange`: it ends at the floor, which is a line start, or with * `floorMidLine` lies inside a line longer than the budget (its part in this chunk is dropped). */ applyOlder(input: ApplyInput): ApplyResult { const { transcriptId, source, startOffset, chunk } = input; const cursor = this.removed ? undefined : this.cursors.get(source); if (transcriptId !== this.transcriptId || !cursor || startOffset + chunk.length !== cursor.floor) { return { added: 0, candidates: [] }; } const end = cursor.floorMidLine ? chunk.lastIndexOf(NL) + 1 : chunk.length; let from = 0; let insideLine = false; if (startOffset > 0) { // The newline at `end - 1` closes a line that may have started before this chunk. const nl = chunk.subarray(0, end).indexOf(NL); insideLine = nl === -1 || nl === end - 1; from = insideLine ? end : nl + 1; } if (insideLine) { // No line starts in this chunk: it lies inside one line longer than the budget. Skip it. cursor.floor = startOffset; cursor.floorMidLine = true; } else { cursor.floor = startOffset + from; delete cursor.floorMidLine; } // Calls whose results lie in already-read newer lines cannot be paired here. const parsed = parseClaudeEditLines(chunk.subarray(from, end).toString('utf8')); const added = this.addRecords(parsed.records); this.scheduleSave(); return { added, candidates: parsed.candidates }; } /** Add Bash images whose mtime was confirmed inside their call's window. */ addImageEntries(images: readonly ConfirmedImage[]): number { if (this.removed) return 0; const records: EditHistoryEntry[] = images.map((img) => { const entry: EditHistoryEntry = { id: `${img.toolUseId}:${img.path}`, ts: img.ts, path: img.path, kind: 'image', tool: img.tool ?? 'bash', created: false, added: 0, removed: 0, hunks: [], truncated: false, }; if (img.agentId) entry.agentId = img.agentId; return entry; }); const added = this.addRecords(records); if (added) this.scheduleSave(); return added; } /** Write now (cancels a pending debounced write). Writes run one after another. */ async flush(): Promise { if (this.saveTimer) { clearTimeout(this.saveTimer); this.saveTimer = null; } const run = (this.writing ?? Promise.resolve()).then(() => this.write()); this.writing = run.catch(() => undefined); await run; } /** * Delete the persisted file (session deleted) and forget the content. The store takes no * changes afterwards, so a read still in flight neither writes nor refills it. */ async remove(): Promise { this.removed = true; if (this.saveTimer) { clearTimeout(this.saveTimer); this.saveTimer = null; } this.entries.clear(); this.bytes = 0; this.cursors.clear(); this.pendingBash = []; this.agents.clear(); // A write already under way ends first (or sees `removed`), so it cannot rename its // tmp file over the deleted store afterwards. await this.writing; await unlink(this.file).catch(() => undefined); } private async write(): Promise { if (this.removed) return; const data: StoreFile = { version: FILE_VERSION, sessionId: this.sessionId, transcriptId: this.transcriptId, cursors: Object.fromEntries(this.cursors), pendingBash: this.pendingBash, agents: Object.fromEntries(this.agents), entries: this.list(), }; const dir = join(this.file, '..'); await mkdir(dir, { recursive: true, mode: 0o700 }); // `mode` applies only to a file being created: the fresh tmp file is 0600, and the rename // makes it the store, so an existing store never keeps wider bits. const tmp = `${this.file}.${process.pid}.tmp`; await writeFile(tmp, JSON.stringify(data), { mode: 0o600 }); if (this.removed) { await unlink(tmp).catch(() => undefined); return; } await rename(tmp, this.file); } private putAgent(agentId: string, meta: AgentMeta): void { this.agents.delete(agentId); this.agents.set(agentId, meta); if (this.agents.size <= MAX_AGENTS) return; const used = new Set(); for (const e of this.entries.values()) if (e.agentId) used.add(e.agentId); for (const id of this.agents.keys()) { if (this.agents.size <= MAX_AGENTS) break; // The newest label has no entries yet: they come with its transcript. if (id !== agentId && !used.has(id)) this.agents.delete(id); } } private setCursor( source: string, cursor: SourceCursor | undefined, offset: number, firstFloor: number, midLine: boolean, firstFloorMidLine = false ): void { const next: SourceCursor = { offset, floor: cursor ? cursor.floor : firstFloor }; if (midLine) next.midLine = true; if (cursor ? cursor.floorMidLine : firstFloorMidLine) next.floorMidLine = true; this.cursors.set(source, next); } private addRecords(records: readonly EditHistoryEntry[]): number { const fresh: string[] = []; for (const r of records) { if (this.entries.has(r.id)) continue; this.entries.set(r.id, r); this.bytes += entryBytes(r); fresh.push(r.id); } if (this.entries.size > MAX_ENTRIES || this.bytes > MAX_STORE_BYTES) { for (const e of [...this.entries.values()].sort((a, b) => a.ts - b.ts)) { if (this.entries.size <= MAX_ENTRIES && this.bytes <= MAX_STORE_BYTES) break; this.entries.delete(e.id); this.bytes -= entryBytes(e); } } // Only what is still there counts: an "older" block past the cap adds nothing. return fresh.filter((id) => this.entries.has(id)).length; } private scheduleSave(): void { if (this.removed || this.saveTimer) return; this.saveTimer = setTimeout(() => { this.saveTimer = null; void this.flush().catch((err) => { console.warn(`[EditHistory] Save failed for session ${this.sessionId}:`, err); }); }, this.debounceMs); this.saveTimer.unref?.(); } }