@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/dist/history/queries.js

@@ -0,0 +1,350 @@
+import * as fs from "node:fs";
+import { createHash } from "node:crypto";
+import { JsonProjection } from "../shared/journal-reader.js";
+import { compactEntry, identity, previewLimits, previewProjection } from "./ingest.js";
+import { HistoryIndexError } from "./types.js";
+import { hash, HistoryStore, integer, pageLimit } from "./store.js";
+export class HistoryQueries {
+    store;
+    info;
+    constructor(store, info) { this.store = store; this.info = info; }
+    cursor(query, keys, offset) {
+        return Buffer.from(JSON.stringify({ generation: this.store.generation, owner: this.store.owner, version: this.info().version, query, keys, offset })).toString("base64url");
+    }
+    parseCursor(value, query) {
+        if (value === undefined)
+            return;
+        let cursor;
+        try {
+            if (value.length > 4096)
+                throw new Error();
+            cursor = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+            if (!Array.isArray(cursor.keys) || cursor.keys.length > 8 || cursor.keys.some((key) => typeof key !== "number" && typeof key !== "string") || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0)
+                throw new Error();
+        }
+        catch {
+            throw new HistoryIndexError("INVALID_CURSOR", "Invalid history cursor.");
+        }
+        if (cursor.generation !== this.store.generation || cursor.owner !== this.store.owner || cursor.query !== query || cursor.version !== this.info().version)
+            throw new HistoryIndexError("STALE_CURSOR", "History changed or this cursor belongs to a different query/source; restart paging.");
+        return cursor;
+    }
+    child(runId, index) {
+        integer(index, 0);
+        const child = this.store.get("SELECT * FROM children WHERE run_id=? AND child_index=?", runId, index);
+        if (!child)
+            throw new HistoryIndexError("OWNERSHIP", "Run/child is not in the current owner's admitted handles.");
+        return { source: child.source_id ? this.store.source(child.source_id) : undefined, agent: child.agent };
+    }
+    listRuns(options) {
+        const limit = pageLimit(options.limit, 20), offset = integer(options.offset, 0), sort = options.sort ?? "attention";
+        if (!["attention", "newest", "oldest"].includes(sort))
+            throw new HistoryIndexError("INVALID", "Unsupported run sort.");
+        if (options.state && !["live", "completed", "paused", "blocked", "failed", "unknown"].includes(options.state))
+            throw new HistoryIndexError("INVALID", "Unsupported run state.");
+        if ((options.text?.length ?? 0) > 256 || (options.agent?.length ?? 0) > 256 || options.latestTasksOnly !== undefined && typeof options.latestTasksOnly !== "boolean")
+            throw new HistoryIndexError("INVALID", "Invalid run filter.");
+        const query = hash(JSON.stringify(["runs", sort, options.agent ?? null, options.state ?? null, options.text?.toLowerCase() ?? null, options.latestTasksOnly ?? false]));
+        const cursor = this.parseCursor(options.cursor, query);
+        if (cursor && options.offset !== undefined)
+            throw new HistoryIndexError("INVALID", "Use cursor or offset, not both.");
+        const clauses = [], params = [], childClauses = [], childParams = [];
+        if (options.agent) {
+            childClauses.push("c.agent=?");
+            childParams.push(options.agent);
+        }
+        if (options.text) {
+            childClauses.push("instr(c.filter_text,?)>0");
+            childParams.push(options.text.toLowerCase());
+        }
+        if (options.latestTasksOnly)
+            childClauses.push("NOT EXISTS(SELECT 1 FROM runs successor WHERE successor.predecessor_id=c.run_id AND successor.predecessor_index=c.child_index)");
+        const childWhere = childClauses.length ? ` AND ${childClauses.join(" AND ")}` : "";
+        if (childWhere) {
+            clauses.push(`EXISTS(SELECT 1 FROM children c WHERE c.run_id=r.id${childWhere})`);
+            params.push(...childParams);
+        }
+        if (options.state) {
+            clauses.push("r.state=?");
+            params.push(options.state);
+        }
+        const total = Number(this.store.get(`SELECT COUNT(*) AS total FROM runs r ${clauses.length ? `WHERE ${clauses.join(" AND ")}` : ""}`, ...params).total);
+        const columns = sort === "attention" ? ["attention", "negative_updated", "id"] : [sort === "newest" ? "negative_updated" : "updated", "id"];
+        if (cursor) {
+            if (cursor.keys.length !== columns.length)
+                throw new HistoryIndexError("INVALID_CURSOR", "Invalid run seek tuple.");
+            clauses.push(`(${columns.map((column) => `r.${column}`).join(",")}) > (${columns.map(() => "?").join(",")})`);
+            params.push(...cursor.keys);
+        }
+        const rows = this.store.all(`SELECT * FROM runs r ${clauses.length ? `WHERE ${clauses.join(" AND ")}` : ""} ORDER BY ${columns.map((column) => `r.${column}`).join(",")} LIMIT ? OFFSET ?`, ...params, limit + 1, cursor ? 0 : offset);
+        const more = rows.length > limit, page = rows.slice(0, limit), position = cursor?.offset ?? offset;
+        const views = page.map((row) => {
+            const view = JSON.parse(row.view);
+            if (childWhere)
+                view.matchedChildIndexes = this.store.all(`SELECT child_index FROM children c WHERE c.run_id=?${childWhere} ORDER BY child_index`, view.runId, ...childParams).map((child) => child.child_index);
+            for (const child of view.children) {
+                const { source } = this.child(view.runId, child.index);
+                if (source)
+                    child.nativeConfiguration = this.configuration(source, child.state === "live" ? {} : { terminalEntryId: child.result?.terminalEntryId, endedAt: child.result?.terminalEntryId ? undefined : view.updatedAt, leaf: child.result?.terminalLeafId }, false);
+            }
+            return view;
+        });
+        return { rows: views, total, offset: position, ...this.info(), ...(more ? { nextOffset: position + page.length, nextCursor: this.cursor(query, columns.map((column) => page.at(-1)[column]), position + page.length) } : {}) };
+    }
+    boundary(source, input, alias = "") {
+        const column = alias ? `${alias}.` : "", clauses = [`${column}source_id=?`, `${column}generation=?`, `${column}published=1`], params = [source.id, source.generation];
+        let terminalSequence;
+        if (input.terminalEntryId) {
+            const terminal = this.store.get("SELECT start FROM entries WHERE source_id=? AND generation=? AND id=? AND published=1", source.id, source.generation, input.terminalEntryId);
+            if (!terminal)
+                throw new HistoryIndexError("BOUNDARY_UNAVAILABLE", "Saved terminal entry is not available in the current indexed generation.");
+            terminalSequence = terminal.start;
+            clauses.push(`${column}start<=?`);
+            params.push(terminal.start);
+        }
+        else if (input.endedAt !== undefined) {
+            clauses.push(`${column}timestamp<=?`);
+            params.push(integer(input.endedAt, 0));
+        }
+        return { clauses, params, terminalSequence };
+    }
+    configuration(source, input, strict = true) {
+        if (input.leaf === null)
+            return {};
+        let boundary;
+        try {
+            boundary = this.boundary(source, input);
+        }
+        catch (error) {
+            if (!strict && error instanceof HistoryIndexError && error.code === "BOUNDARY_UNAVAILABLE")
+                return {};
+            throw error;
+        }
+        const leaf = input.leaf ?? this.store.get(`SELECT id FROM entries WHERE ${boundary.clauses.join(" AND ")} ORDER BY start DESC LIMIT 1`, ...boundary.params)?.id;
+        if (!leaf)
+            return {};
+        // Fix recursive loop order: look up each child's parent by ID instead of
+        // rescanning the eligible transcript at every ancestry step.
+        const ancestry = `WITH RECURSIVE eligible AS (SELECT rowid,id,parent_id,start,timestamp,configuration_model,configuration_thinking FROM entries WHERE ${boundary.clauses.join(" AND ")}), branch AS (SELECT * FROM eligible WHERE id=? UNION SELECT parent.* FROM branch child CROSS JOIN eligible parent WHERE parent.id=child.parent_id)`;
+        const facts = this.store.get(`${ancestry} SELECT
+			(SELECT COUNT(*) FROM branch) AS count,
+			EXISTS(SELECT 1 FROM branch child WHERE parent_id IS NULL OR NOT EXISTS(SELECT 1 FROM eligible parent WHERE parent.id=child.parent_id)) AS rooted,
+			(SELECT configuration_model FROM branch WHERE configuration_model IS NOT NULL ORDER BY start DESC LIMIT 1) AS model,
+			(SELECT timestamp FROM branch WHERE configuration_model IS NOT NULL ORDER BY start DESC LIMIT 1) AS recorded_at,
+			(SELECT configuration_thinking FROM branch WHERE configuration_thinking IS NOT NULL ORDER BY start DESC LIMIT 1) AS thinking`, ...boundary.params, leaf);
+        if (!facts.count && input.leaf && strict)
+            throw new HistoryIndexError("BOUNDARY_UNAVAILABLE", "Selected configuration leaf is not available in the indexed generation.");
+        if (facts.count && !facts.rooted) {
+            if (!strict)
+                return {};
+            throw new HistoryIndexError("MALFORMED_ANCESTRY", "Selected native configuration has cyclic ancestry.");
+        }
+        return { ...(facts.model ? { model: facts.model, modelRecordedAt: facts.recorded_at ?? undefined } : {}), ...(facts.thinking ? { thinking: facts.thinking } : {}) };
+    }
+    historyPage(input) {
+        const { source } = this.child(input.runId, input.index);
+        const info = this.info(), limit = pageLimit(input.limit);
+        if (input.before !== undefined && input.after !== undefined)
+            throw new HistoryIndexError("INVALID", "Use before or after, not both.");
+        if (input.messageIds && (!Array.isArray(input.messageIds) || input.messageIds.length > 1000 || input.messageIds.some((id) => typeof id !== "string" || id.length > 512)) || input.readThrough !== undefined && input.readThrough !== null && (typeof input.readThrough !== "string" || input.readThrough.length > 1024))
+            throw new HistoryIndexError("INVALID", "Invalid scoped message/read metadata request.");
+        const empty = { ...info, entries: [], count: 0, hasMore: false, sourceId: source?.id ?? null, generation: source?.generation ?? null, sessionId: source?.session_id ?? null, sourceState: source?.state ?? "unlinked", configuration: {}, deliveredMessages: [], latestEntryId: null };
+        if (!source)
+            return { ...empty, unavailable: "This legacy or unstarted child has no linked native conversation." };
+        const query = hash(JSON.stringify(["history", input.runId, input.index, source.id, source.generation, input.terminalEntryId ?? null, input.endedAt ?? null, input.leaf ?? null]));
+        const cursor = this.parseCursor(input.cursor, query);
+        if (cursor && (input.before !== undefined || input.after !== undefined))
+            throw new HistoryIndexError("INVALID", "Use cursor or sequence, not both.");
+        const { clauses, params, terminalSequence } = this.boundary(source, input);
+        const metadataWhere = clauses.join(" AND "), metadataParams = params.slice();
+        const latest = this.store.get(`SELECT start,visible_id FROM entries WHERE ${metadataWhere} AND visible_id IS NOT NULL ORDER BY start DESC LIMIT 1`, ...metadataParams);
+        const marker = typeof input.readThrough === "string" ? this.store.get(`SELECT start,visible_id FROM entries WHERE ${metadataWhere} AND id=?`, ...metadataParams, input.readThrough.replace(/:(?:\d+|error)$/, "")) : undefined;
+        const deliveredMessages = [];
+        for (const id of new Set(input.messageIds ?? [])) {
+            const human = this.store.get(`SELECT start FROM entries WHERE ${metadataWhere} AND human_id=? ORDER BY start DESC LIMIT 1`, ...metadataParams, id);
+            if (human)
+                deliveredMessages.push([id, Boolean(this.store.get(`SELECT rowid FROM entries WHERE ${metadataWhere} AND start>? AND assistant_text=1 LIMIT 1`, ...metadataParams, human.start))]);
+        }
+        const outputDigest = this.store.get("SELECT output_digest FROM children WHERE run_id=? AND child_index=?", input.runId, input.index)?.output_digest;
+        const configuration = this.configuration(source, input);
+        const count = Number(this.store.get(`SELECT COUNT(*) AS count FROM entries WHERE ${metadataWhere}`, ...metadataParams).count);
+        const before = cursor ? integer(cursor.keys[0], 0) : input.before;
+        if (before !== undefined) {
+            clauses.push("start<?");
+            params.push(integer(before, 0));
+        }
+        if (input.after !== undefined) {
+            clauses.push("start>?");
+            params.push(integer(input.after, 0));
+        }
+        const forward = input.after !== undefined;
+        const fetched = this.store.all(`SELECT * FROM entries WHERE ${clauses.join(" AND ")} ORDER BY start ${forward ? "ASC" : "DESC"} LIMIT ?`, ...params, limit + 1);
+        const more = fetched.length > limit, rows = fetched.slice(0, limit);
+        if (!forward)
+            rows.reverse();
+        const first = rows[0], last = rows.at(-1);
+        const finalResultId = outputDigest ? this.finalResultId(input, outputDigest, first && last ? [first.start, last.start] : undefined) : undefined;
+        const previous = first && this.store.get(`SELECT start FROM entries WHERE ${metadataWhere} AND start<? LIMIT 1`, ...metadataParams, first.start);
+        return { ...empty, configuration, deliveredMessages, latestEntryId: latest?.visible_id ?? null, terminalSequence,
+            ...(input.readThrough !== undefined ? { unreadAfter: Boolean(latest && (!marker || latest.start > marker.start || latest.start === marker.start && latest.visible_id !== input.readThrough)) } : {}),
+            ...(finalResultId ? { finalResultId } : {}), entries: rows.map((row) => this.store.entry(row)), count, hasMore: forward ? more : Boolean(previous),
+            ...(previous && first ? { previousBefore: first.start, previousCursor: this.cursor(query, [first.start], 0) } : {}),
+            ...(last ? { nextAfter: last.start } : {}), ...(source.error ? { unavailable: source.error } : source.state === "missing" ? { unavailable: "Linked conversation is missing." } : {}) };
+    }
+    search(input) {
+        const expression = searchGrammar(input.query), limit = pageLimit(input.limit, 20), sort = input.sort ?? "relevance";
+        if (!["relevance", "newest"].includes(sort))
+            throw new HistoryIndexError("INVALID", "Unsupported search sort.");
+        if (input.index !== undefined && !input.runId)
+            throw new HistoryIndexError("INVALID", "A child search requires runId.");
+        if (input.runId && !this.store.get("SELECT id FROM runs WHERE id=?", input.runId))
+            throw new HistoryIndexError("OWNERSHIP", "Run is not admitted by the current owner.");
+        if (input.index !== undefined)
+            this.child(input.runId, input.index);
+        if (input.runId)
+            for (const child of this.store.all(`SELECT source_id,terminal_entry_id,ended_at FROM children WHERE run_id=?${input.index !== undefined ? " AND child_index=?" : ""}`, input.runId, ...(input.index !== undefined ? [input.index] : []))) {
+                const source = child.source_id && this.store.source(child.source_id);
+                if (source)
+                    this.boundary(source, { terminalEntryId: child.terminal_entry_id ?? undefined, endedAt: child.ended_at ?? undefined });
+            }
+        const query = hash(JSON.stringify(["search", expression, sort, input.runId ?? null, input.index ?? null, input.agent ?? null]));
+        const cursor = this.parseCursor(input.cursor, query);
+        const clauses = ["e.published=1", "e.generation=s.generation", "(c.terminal_entry_id IS NULL OR e.start<=terminal.start)", "(c.ended_at IS NULL OR e.timestamp<=c.ended_at)"], params = [...expression];
+        if (input.runId) {
+            clauses.push("c.run_id=?");
+            params.push(input.runId);
+        }
+        if (input.index !== undefined) {
+            clauses.push("c.child_index=?");
+            params.push(input.index);
+        }
+        if (input.agent) {
+            if (input.agent.length > 256)
+                throw new HistoryIndexError("INVALID", "Agent filter is too long.");
+            clauses.push("c.agent=?");
+            params.push(input.agent);
+        }
+        // Ordering/filters apply globally before limit. Common terms may still require an FTS
+        // scan/sort; the parent enforces a hard deadline by killing this separate process.
+        const score = sort === "relevance" ? "matched.score" : "-COALESCE(e.timestamp,0)";
+        if (cursor) {
+            if (cursor.keys.length !== 4)
+                throw new HistoryIndexError("INVALID_CURSOR", "Invalid search seek tuple.");
+            clauses.push(`(${score},d.id,c.run_id,c.child_index)>(?,?,?,?)`);
+            params.push(...cursor.keys);
+        }
+        // Match words across all visible fields/windows of one native record. A quoted
+        // phrase remains a single FTS expression, so it cannot span unrelated fields.
+        const rows = this.store.all(`WITH hits AS MATERIALIZED (
+			${expression.map((_term, index) => `SELECT d.id,d.entry_rowid,bm25(corpus) AS score,${index} AS term FROM corpus JOIN documents d ON d.id=corpus.rowid WHERE corpus MATCH ?`).join(" UNION ALL ")}
+		), terms AS (
+			SELECT entry_rowid,term,MIN(score) AS score FROM hits GROUP BY entry_rowid,term
+		), matched AS (
+			SELECT entry_rowid,SUM(score) AS score FROM terms GROUP BY entry_rowid HAVING COUNT(*)=${expression.length}
+		), excerpts AS (
+			SELECT id,entry_rowid,ROW_NUMBER() OVER (PARTITION BY entry_rowid ORDER BY score,id) AS choice FROM hits
+		)
+		SELECT d.*,${score} AS score,e.*,d.id AS document_id,s.path,s.session_id,c.run_id,c.child_index,c.agent,d.preview AS document_preview FROM matched JOIN excerpts ON excerpts.entry_rowid=matched.entry_rowid AND excerpts.choice=1 JOIN documents d ON d.id=excerpts.id JOIN entries e ON e.rowid=matched.entry_rowid JOIN sources s ON s.id=e.source_id JOIN children c ON c.source_id=s.id LEFT JOIN entries terminal ON terminal.source_id=s.id AND terminal.generation=s.generation AND terminal.id=c.terminal_entry_id AND terminal.published=1 WHERE ${clauses.join(" AND ")} ORDER BY score,d.id,c.run_id,c.child_index LIMIT ?`, ...params, limit + 1);
+        const more = rows.length > limit, page = rows.slice(0, limit);
+        return { ...this.info(), matches: page.map((row) => ({ id: row.document_id, runId: row.run_id, index: row.child_index, agent: row.agent, entryId: row.id, nativeId: row.native_id, sessionId: row.session_id, sessionFile: row.path, timestamp: row.timestamp,
+                ref: { sourceId: row.source_id, generation: row.generation, start: row.start, end: row.end, digest: row.digest }, preview: row.document_preview, field: row.field, textStart: row.text_start, textEnd: row.text_end, score: row.score })),
+            ...(more ? { nextCursor: this.cursor(query, [page.at(-1).score, page.at(-1).document_id, page.at(-1).run_id, page.at(-1).child_index], (cursor?.offset ?? 0) + page.length) } : {}) };
+    }
+    finalResultId(input, digest, preferredRange) {
+        const { source } = this.child(input.runId, input.index);
+        if (!source)
+            return;
+        const boundary = this.boundary(source, input, "e");
+        return this.store.get(`SELECT a.item_id FROM answers a JOIN entries e ON e.rowid=a.entry_rowid WHERE a.digest=? AND ${boundary.clauses.join(" AND ")} ORDER BY ${preferredRange ? "(e.start BETWEEN ? AND ?) DESC," : ""}e.start DESC LIMIT 1`, digest, ...boundary.params, ...(preferredRange ?? []))?.item_id;
+    }
+    selected(input, full) {
+        const { source } = this.child(input.runId, input.index);
+        if (!source)
+            return null;
+        const boundary = this.boundary(source, input), where = boundary.clauses.join(" AND ");
+        let row;
+        if (input.ref) {
+            if (input.ref.sourceId !== source.id || input.ref.generation !== source.generation)
+                throw new HistoryIndexError("SOURCE_CHANGED", "Selected source generation changed; refresh history.");
+            row = this.store.get(`SELECT * FROM entries WHERE ${where} AND start=? AND end=? AND digest=?`, ...boundary.params, input.ref.start, input.ref.end, input.ref.digest);
+            if (!row)
+                throw new HistoryIndexError("SOURCE_CHANGED", "Selected byte reference is no longer indexed.");
+        }
+        else if (input.entryId)
+            row = this.store.get(`SELECT * FROM entries WHERE ${where} AND id=?`, ...boundary.params, input.entryId);
+        else if (input.toolCallId && ["call", "result"].includes(input.kind ?? "call"))
+            row = this.store.get(`SELECT e.* FROM tools t JOIN entries e ON e.rowid=t.entry_rowid WHERE ${this.boundary(source, input, "e").clauses.join(" AND ")} AND t.call_id=? AND t.kind=? ORDER BY e.start DESC LIMIT 1`, ...boundary.params, input.toolCallId, input.kind ?? "call");
+        else
+            throw new HistoryIndexError("INVALID", "Select an entry ID, byte reference, or tool call/result ID.");
+        if (!row)
+            return null;
+        const body = validateRecord(source, row, full);
+        return full ? body : { ...this.store.entry(row), entry: { ...compactEntry(body), id: row.id } };
+    }
+}
+function searchGrammar(query) {
+    if (typeof query !== "string" || !query.trim() || query.length > 1024)
+        throw new HistoryIndexError("INVALID_QUERY", "Search requires 1–12 tokens or one quoted phrase.");
+    const text = query.trim(), phrase = text.startsWith('"') && text.endsWith('"');
+    const words = (phrase ? text.slice(1, -1) : text).trim().split(/\s+/u);
+    if (!words.length || words.length > 12 || words.some((word) => !/^[\p{L}\p{N}\p{M}]{1,64}$/u.test(word) || !phrase && ["AND", "OR", "NOT", "NEAR"].includes(word)))
+        throw new HistoryIndexError("INVALID_QUERY", "Only lexical tokens or one quoted phrase are supported; operators, punctuation, and prefixes are not allowed.");
+    return phrase ? [`"${words.join(" ")}"`] : [...new Set(words.map((word) => `"${word}"`))];
+}
+function validateRecord(source, row, full) {
+    let fd;
+    try {
+        fd = fs.openSync(source.path, "r");
+        const stat = fs.fstatSync(fd, { bigint: true });
+        if (identity(stat) !== source.identity || Number(stat.size) < row.end)
+            throw new HistoryIndexError("SOURCE_CHANGED", "Selected conversation was replaced or truncated.");
+        const headerHash = createHash("sha256"), headerBytes = Buffer.allocUnsafe(64 * 1024);
+        let headerPosition = 0, headerComplete = false;
+        while (!headerComplete && headerPosition < 1024 * 1024) {
+            const count = fs.readSync(fd, headerBytes, 0, headerBytes.length, headerPosition);
+            if (!count)
+                break;
+            const newline = headerBytes.subarray(0, count).indexOf(10);
+            const length = newline < 0 ? count : newline + 1;
+            headerHash.update(headerBytes.subarray(0, length));
+            headerPosition += length;
+            headerComplete = newline >= 0;
+        }
+        if (!headerComplete || headerHash.digest("hex") !== source.header_digest)
+            throw new HistoryIndexError("SOURCE_CHANGED", "Selected native header changed or exceeds its validation budget.");
+        if (full && row.end - row.start > 16 * 1024 * 1024)
+            throw new HistoryIndexError("RECORD_TOO_LARGE", "Selected full record exceeds the 16 MiB detail budget; use its validated preview.");
+        const digest = createHash("sha256"), parser = new JsonProjection(previewProjection, undefined, undefined, previewLimits), bytes = Buffer.allocUnsafe(64 * 1024), body = [];
+        const decoder = new TextDecoder("utf8", { fatal: true });
+        for (let position = row.start; position < row.end;) {
+            const count = fs.readSync(fd, bytes, 0, Math.min(bytes.length, row.end - position), position);
+            if (!count)
+                throw new HistoryIndexError("SOURCE_CHANGED", "Selected record was truncated during validation.");
+            const chunk = bytes.subarray(0, count);
+            digest.update(chunk);
+            if (full)
+                body.push(Buffer.from(chunk));
+            else
+                parser.write(decoder.decode(chunk, { stream: true }));
+            position += count;
+        }
+        const current = fs.statSync(source.path, { bigint: true }), after = fs.fstatSync(fd, { bigint: true });
+        if (identity(current) !== identity(stat) || current.size < BigInt(row.end) || after.ctimeNs !== stat.ctimeNs && after.size <= stat.size || digest.digest("hex") !== row.digest)
+            throw new HistoryIndexError("SOURCE_CHANGED", "Selected record changed; refresh history before reading details.");
+        if (full)
+            return JSON.parse(new TextDecoder("utf8", { fatal: true }).decode(Buffer.concat(body)));
+        parser.write(decoder.decode());
+        return parser.finish();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new HistoryIndexError("SOURCE_CHANGED", "Selected conversation is missing.");
+        if (error instanceof RangeError)
+            throw new HistoryIndexError("RECORD_COMPLEXITY", "Selected preview exceeds bounded history structure budgets.");
+        throw error;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}

package/dist/history/store.js

@@ -0,0 +1,216 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { historyDirectory, historyTransaction, openHistoryDatabase } from "./database.js";
+import { stripTerminalSequences } from "../shared/native-tui.js";
+import { HistoryIndexError } from "./types.js";
+import { readSavedOutput } from "./canonical-result.js";
+export const hash = (text) => createHash("sha256").update(text).digest("hex");
+export const exactTextDigest = (text) => hash(stripTerminalSequences(text).trim());
+export const safeText = (value, limit = 1024) => typeof value === "string" ? value.replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)|\x1b\[[0-?]*[ -/]*[@-~]|[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "").slice(0, limit) : "";
+export function integer(value, fallback, maximum = Number.MAX_SAFE_INTEGER) {
+    const result = value === undefined ? fallback : value;
+    if (!Number.isSafeInteger(result) || Number(result) < 0 || Number(result) > maximum)
+        throw new HistoryIndexError("INVALID", "Expected a bounded non-negative integer.");
+    return Number(result);
+}
+export function pageLimit(value, fallback = 100) {
+    const limit = integer(value, fallback, 100);
+    if (!limit)
+        throw new HistoryIndexError("INVALID", "Page limit must be from 1 to 100.");
+    return limit;
+}
+export class HistoryStore {
+    db;
+    generation;
+    file;
+    owner;
+    operations = { sourceChecks: 0, sourceOpens: 0, sourceBytesRead: 0, runProjections: 0, queries: 0 };
+    ingestLock;
+    outputDigests = new Map();
+    constructor(agentDir, owner) {
+        this.owner = owner;
+        const directory = historyDirectory(agentDir);
+        const manifest = path.join(directory, `${hash(owner)}.json`);
+        let name;
+        try {
+            const saved = JSON.parse(fs.readFileSync(manifest, "utf8"));
+            if (typeof saved.file === "string" && /^[a-f0-9-]+\.sqlite$/.test(saved.file))
+                name = saved.file;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
+                throw error;
+        }
+        let db;
+        if (name) {
+            try {
+                const file = path.join(directory, name);
+                if (!fs.existsSync(file) || fs.lstatSync(file).isSymbolicLink())
+                    throw new HistoryIndexError("CORRUPT", "Invalid index generation.");
+                db = openHistoryDatabase(file);
+                if (db.prepare("PRAGMA user_version").get()?.user_version !== 5)
+                    throw new HistoryIndexError("CORRUPT", "Invalid index schema.");
+                db.prepare("SELECT value FROM meta WHERE key='generation'").get();
+            }
+            catch (error) {
+                db?.close();
+                db = undefined;
+                if (!isCorruption(error))
+                    throw error;
+                name = undefined;
+            }
+        }
+        if (!name) {
+            name = `${randomUUID()}.sqlite`;
+            db = openHistoryDatabase(path.join(directory, name));
+            this.schema(db);
+            const temporary = `${manifest}.${process.pid}.${randomUUID()}`;
+            fs.writeFileSync(temporary, JSON.stringify({ file: name }), { mode: 0o600 });
+            fs.renameSync(temporary, manifest);
+            // Never rename/unlink an open SQLite generation or separate its WAL. Old corrupt
+            // generations remain private for diagnosis; the manifest selects the new projection.
+        }
+        this.db = db;
+        this.file = path.join(directory, name);
+        fs.chmodSync(this.file, 0o600);
+        for (const suffix of ["-wal", "-shm"])
+            if (fs.existsSync(this.file + suffix))
+                fs.chmodSync(this.file + suffix, 0o600);
+        this.generation = String(this.get("SELECT value FROM meta WHERE key='generation'").value);
+        this.db.exec("CREATE TEMP TABLE pending_text(field TEXT, position INTEGER, end_position INTEGER, text TEXT)");
+    }
+    schema(db) {
+        db.exec(`
+			CREATE TABLE meta(key TEXT PRIMARY KEY,value TEXT NOT NULL);
+			INSERT INTO meta VALUES ('generation','${randomUUID()}'),('version','0'),('indexedAt','0');
+			CREATE TABLE runs(id TEXT PRIMARY KEY,attention INTEGER NOT NULL,updated INTEGER NOT NULL,negative_updated INTEGER NOT NULL,state TEXT NOT NULL,filter_text TEXT NOT NULL,view TEXT NOT NULL,predecessor_id TEXT,predecessor_index INTEGER);
+			CREATE INDEX runs_predecessor ON runs(predecessor_id,predecessor_index);
+			CREATE INDEX runs_attention ON runs(attention,negative_updated,id);
+			CREATE INDEX runs_newest ON runs(negative_updated,id);
+			CREATE INDEX runs_oldest ON runs(updated,id);
+			CREATE INDEX runs_state ON runs(state,attention,negative_updated,id);
+			CREATE TABLE sources(id TEXT PRIMARY KEY,path TEXT NOT NULL UNIQUE,generation INTEGER NOT NULL DEFAULT 1,identity TEXT,stamp TEXT,session_id TEXT,header_digest TEXT,cursor INTEGER NOT NULL DEFAULT 0,prefix_digest TEXT,state TEXT NOT NULL DEFAULT 'pending',error TEXT,malformed INTEGER NOT NULL DEFAULT 0,complexity INTEGER NOT NULL DEFAULT 0,checked_at INTEGER,format_version INTEGER);
+			CREATE TABLE children(run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,child_index INTEGER NOT NULL,agent TEXT NOT NULL,source_id TEXT REFERENCES sources(id),filter_text TEXT NOT NULL,output_digest TEXT,terminal_entry_id TEXT,ended_at INTEGER,PRIMARY KEY(run_id,child_index));
+			CREATE INDEX children_source ON children(source_id);
+			CREATE INDEX children_agent ON children(agent,run_id);
+			CREATE TABLE entries(rowid INTEGER PRIMARY KEY,source_id TEXT NOT NULL REFERENCES sources(id),generation INTEGER NOT NULL,id TEXT NOT NULL,native_id TEXT,parent_id TEXT,start INTEGER NOT NULL,end INTEGER NOT NULL,digest TEXT NOT NULL,timestamp INTEGER,type TEXT NOT NULL,preview TEXT NOT NULL,published INTEGER NOT NULL DEFAULT 0,role TEXT,assistant_text INTEGER NOT NULL DEFAULT 0,visible_id TEXT,human_id TEXT,configuration_model TEXT,configuration_thinking TEXT,UNIQUE(source_id,generation,id),UNIQUE(source_id,generation,start));
+			CREATE INDEX entries_page ON entries(source_id,generation,published,start);
+			CREATE INDEX entries_time ON entries(source_id,generation,published,timestamp,start);
+			CREATE INDEX entries_human ON entries(source_id,generation,human_id,start);
+			CREATE TABLE answers(entry_rowid INTEGER NOT NULL REFERENCES entries(rowid) ON DELETE CASCADE,digest TEXT NOT NULL,item_id TEXT NOT NULL,PRIMARY KEY(entry_rowid,digest));
+			CREATE INDEX answers_digest ON answers(digest,entry_rowid);
+			CREATE TABLE tools(entry_rowid INTEGER NOT NULL REFERENCES entries(rowid) ON DELETE CASCADE,source_id TEXT NOT NULL,generation INTEGER NOT NULL,call_id TEXT NOT NULL,kind TEXT NOT NULL);
+			CREATE INDEX tools_lookup ON tools(source_id,generation,call_id,kind);
+			CREATE TABLE documents(id INTEGER PRIMARY KEY,entry_rowid INTEGER NOT NULL REFERENCES entries(rowid) ON DELETE CASCADE,field TEXT NOT NULL,text_start INTEGER NOT NULL,text_end INTEGER NOT NULL,preview TEXT NOT NULL);
+			CREATE INDEX documents_entry ON documents(entry_rowid);
+			CREATE VIRTUAL TABLE corpus USING fts5(text,content='',contentless_delete=1,tokenize='unicode61');
+			PRAGMA user_version=5;
+		`);
+    }
+    get(sql, ...params) { return this.db.prepare(sql).get(...params); }
+    all(sql, ...params) { return this.db.prepare(sql).all(...params); }
+    run(sql, ...params) { return this.db.prepare(sql).run(...params); }
+    deleteDocuments(sourceId, unpublishedOnly = false) {
+        const where = `entry_rowid IN (SELECT rowid FROM entries WHERE source_id=?${unpublishedOnly ? " AND published=0" : ""})`;
+        this.run(`DELETE FROM corpus WHERE rowid IN (SELECT id FROM documents WHERE ${where})`, sourceId);
+        this.run(`DELETE FROM documents WHERE ${where}`, sourceId);
+    }
+    transaction(work) { return historyTransaction(this.db, work); }
+    bump() { this.run("UPDATE meta SET value=CAST(value AS INTEGER)+1 WHERE key='version'"); this.run("UPDATE meta SET value=? WHERE key='indexedAt'", String(Date.now())); }
+    source(id) { return this.get("SELECT * FROM sources WHERE id=?", id); }
+    resetSource(id, state = "pending", error = null) {
+        this.transaction(() => {
+            this.deleteDocuments(id);
+            this.run("DELETE FROM entries WHERE source_id=?", id);
+            this.run("UPDATE sources SET generation=generation+1,identity=NULL,stamp=NULL,session_id=NULL,header_digest=NULL,format_version=NULL,cursor=0,prefix_digest=NULL,state=?,error=?,malformed=0,complexity=0,checked_at=? WHERE id=?", state, error, Date.now(), id);
+            this.bump();
+        });
+    }
+    clearUnpublished(id) {
+        this.transaction(() => {
+            this.deleteDocuments(id, true);
+            this.run("DELETE FROM entries WHERE source_id=? AND published=0", id);
+        });
+    }
+    outputDigest(result) {
+        if (!result)
+            return null;
+        if (!result.fullOutputPath)
+            return typeof result.finalOutput === "string" && result.finalOutput.length !== 8192 && !result.truncation?.truncated ? exactTextDigest(result.finalOutput) : null;
+        try {
+            const stat = fs.statSync(result.fullOutputPath, { bigint: true });
+            if (!stat.isFile() || stat.size > 16n * 1024n * 1024n)
+                return null;
+            const stamp = `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+            const cached = this.outputDigests.get(result.fullOutputPath);
+            if (cached?.stamp === stamp)
+                return cached.digest;
+            const text = readSavedOutput(result.fullOutputPath);
+            const digest = exactTextDigest(text);
+            this.outputDigests.set(result.fullOutputPath, { stamp, digest });
+            return digest;
+        }
+        catch {
+            return null;
+        }
+    }
+    putView(view, full = view) {
+        const attention = view.attention.includes("awaiting_input") ? 0 : view.attention.some((reason) => reason !== "unreviewed") ? 1 : view.state === "live" ? 2 : view.attention.length ? 3 : 4;
+        const json = JSON.stringify(view), filters = new Map(full.children.map((child) => [child.index, safeText(`${child.agent} ${child.label ?? ""} ${child.task ?? full.task}`, Infinity).toLowerCase()]));
+        const filterText = safeText(`${full.task} ${[...filters.values()].join(" ")}`, Infinity).toLowerCase();
+        const digests = new Map(full.children.map((child) => [child.index, this.outputDigest(child.result)]));
+        const saved = this.get("SELECT view,filter_text FROM runs WHERE id=?", view.runId);
+        if (saved?.view === json && saved.filter_text === filterText && this.all("SELECT child_index,output_digest FROM children WHERE run_id=?", view.runId).every((child) => child.output_digest === digests.get(child.child_index)))
+            return;
+        this.transaction(() => {
+            this.run("INSERT INTO runs VALUES (?,?,?,?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET attention=excluded.attention,updated=excluded.updated,negative_updated=excluded.negative_updated,state=excluded.state,filter_text=excluded.filter_text,view=excluded.view,predecessor_id=excluded.predecessor_id,predecessor_index=excluded.predecessor_index", view.runId, attention, view.updatedAt, -view.updatedAt, view.state, filterText, json, view.predecessorRunId ?? null, view.predecessorIndex ?? 0);
+            this.run("DELETE FROM children WHERE run_id=?", view.runId);
+            for (const child of view.children) {
+                let source = null;
+                if (child.sessionFile) {
+                    const file = path.resolve(child.sessionFile);
+                    source = hash(file);
+                    this.run("INSERT INTO sources(id,path) VALUES (?,?) ON CONFLICT(id) DO NOTHING", source, file);
+                }
+                const terminal = child.state !== "live" && child.state !== "unknown";
+                this.run("INSERT INTO children VALUES (?,?,?,?,?,?,?,?)", view.runId, child.index, child.agent, source, filters.get(child.index) ?? "", digests.get(child.index) ?? null, terminal ? child.result?.terminalEntryId ?? null : null, terminal && !child.result?.terminalEntryId ? view.updatedAt : null);
+            }
+            this.bump();
+        });
+    }
+    info(pending) {
+        const sources = this.get("SELECT COUNT(*) AS total,SUM(state IN ('pending','indexing')) AS pending,SUM(state IN ('degraded','missing','error')) AS errors FROM sources WHERE id IN (SELECT source_id FROM children)");
+        const indexedAt = Number(this.get("SELECT value FROM meta WHERE key='indexedAt'").value) || null;
+        const errors = Number(sources.errors ?? 0);
+        const remaining = pending + Number(sources.pending ?? 0);
+        const freshness = { authoritative: false, state: remaining ? "catching-up" : errors ? "degraded" : "current", pending: remaining, errors, indexedAt };
+        return { version: Number(this.get("SELECT value FROM meta WHERE key='version'").value), indexedAt, freshness };
+    }
+    entry(row) {
+        return { id: row.id, nativeId: row.native_id, parentId: row.parent_id, sequence: row.start, timestamp: row.timestamp, type: row.type,
+            ref: { sourceId: row.source_id, generation: row.generation, start: row.start, end: row.end, digest: row.digest }, entry: JSON.parse(row.preview) };
+    }
+    /** A separate SQLite transaction serializes incremental staging without blocking browse queries.
+     * SQLite releases it on process death; no PID lease, expiry, or stale-file deletion is needed. */
+    beginIngest() {
+        if (!this.ingestLock) {
+            this.ingestLock = openHistoryDatabase(`${this.file}.ingest.sqlite`);
+            this.ingestLock.exec("PRAGMA busy_timeout=0");
+        }
+        try {
+            this.ingestLock.exec("BEGIN IMMEDIATE");
+        }
+        catch (error) {
+            if (/locked|busy/i.test(String(error.message)))
+                throw new HistoryIndexError("INDEX_BUSY", "Another worker is indexing this generation.");
+            throw error;
+        }
+    }
+    endIngest() { if (this.ingestLock?.isTransaction)
+        this.ingestLock.exec("ROLLBACK"); }
+    close() { this.ingestLock?.close(); this.db.close(); }
+}
+function isCorruption(error) {
+    return error instanceof HistoryIndexError && error.code === "CORRUPT" || /malformed|not a database|no such table|corrupt/i.test(String(error.message));
+}

package/dist/history/types.js

@@ -0,0 +1,4 @@
+export class HistoryIndexError extends Error {
+    code;
+    constructor(code, message) { super(message); this.name = "HistoryIndexError"; this.code = code; }
+}