@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/dist/history/rows.js

@@ -0,0 +1,77 @@
+import { isRecord } from "../shared/unknown.js";
+import { HistoryIndexError } from "./types.js";
+export function indexRow(input) {
+    if (!isRecord(input)) {
+        throw new HistoryIndexError("CORRUPT", "Invalid index row.");
+    }
+    const row = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value !== null && typeof value !== "string" && typeof value !== "number") {
+            throw new HistoryIndexError("CORRUPT", `Unsupported index column ${key}.`);
+        }
+        row[key] = value;
+    }
+    return row;
+}
+export function text(row, key) {
+    const value = row[key];
+    if (typeof value !== "string") {
+        throw new HistoryIndexError("CORRUPT", `Invalid index text column ${key}.`);
+    }
+    return value;
+}
+export function number(row, key) {
+    const value = row[key];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new HistoryIndexError("CORRUPT", `Invalid index numeric column ${key}.`);
+    }
+    return value;
+}
+export function nullableText(row, key) {
+    return row[key] === null ? null : text(row, key);
+}
+export function nullableNumber(row, key) {
+    return row[key] === null ? null : number(row, key);
+}
+export function sourceRow(row) {
+    return {
+        id: text(row, "id"),
+        path: text(row, "path"),
+        generation: number(row, "generation"),
+        identity: nullableText(row, "identity"),
+        stamp: nullableText(row, "stamp"),
+        session_id: nullableText(row, "session_id"),
+        header_digest: nullableText(row, "header_digest"),
+        cursor: number(row, "cursor"),
+        prefix_digest: nullableText(row, "prefix_digest"),
+        state: text(row, "state"),
+        error: nullableText(row, "error"),
+        malformed: number(row, "malformed"),
+        complexity: number(row, "complexity"),
+        checked_at: nullableNumber(row, "checked_at"),
+        format_version: nullableNumber(row, "format_version"),
+    };
+}
+export function entryRow(row) {
+    return {
+        rowid: number(row, "rowid"),
+        source_id: text(row, "source_id"),
+        generation: number(row, "generation"),
+        id: text(row, "id"),
+        native_id: nullableText(row, "native_id"),
+        parent_id: nullableText(row, "parent_id"),
+        start: number(row, "start"),
+        end: number(row, "end"),
+        digest: text(row, "digest"),
+        timestamp: nullableNumber(row, "timestamp"),
+        type: text(row, "type"),
+        preview: text(row, "preview"),
+        published: number(row, "published"),
+        role: nullableText(row, "role"),
+        assistant_text: number(row, "assistant_text"),
+        visible_id: nullableText(row, "visible_id"),
+        human_id: nullableText(row, "human_id"),
+        configuration_model: nullableText(row, "configuration_model"),
+        configuration_thinking: nullableText(row, "configuration_thinking"),
+    };
+}

package/dist/history/run-projection.js

@@ -0,0 +1,137 @@
+import { ownedRunView } from "../runs/shared/run-records.js";
+import { acceptanceHumanAction } from "../runs/shared/acceptance-evaluation.js";
+import { getRunMetadataDir, listRunQuestions, summarizeSupervisorQuestion, } from "../runs/shared/supervisor-questions.js";
+import { safeText } from "./text.js";
+function compactResult(result) {
+    if (!result) {
+        return;
+    }
+    return {
+        agent: result.agent,
+        task: safeText(result.task),
+        exitCode: result.exitCode,
+        usage: {
+            input: result.usage.input,
+            output: result.usage.output,
+            cacheRead: result.usage.cacheRead,
+            cacheWrite: result.usage.cacheWrite,
+            cost: result.usage.cost,
+            turns: result.usage.turns,
+        },
+        finalOutput: safeText(result.finalOutput, 1024),
+        error: result.error === undefined ? undefined : safeText(result.error),
+        sessionFile: result.sessionFile,
+        terminalEntryId: result.terminalEntryId,
+        terminalLeafId: result.terminalLeafId,
+        detached: result.detached,
+        interrupted: result.interrupted,
+        timedOut: result.timedOut,
+        nativeSessionId: result.nativeSessionId,
+        accounting: result.accounting,
+        agentProcessExit: result.agentProcessExit,
+        model: result.model,
+        fullOutputPath: result.fullOutputPath,
+    };
+}
+function compactActivity(activity) {
+    if (!activity) {
+        return;
+    }
+    return {
+        status: activity.status,
+        currentTool: activity.currentTool,
+        currentToolArgs: activity.currentToolArgs === undefined ? undefined : safeText(activity.currentToolArgs, 256),
+        currentPath: activity.currentPath,
+        streamingText: activity.streamingText === undefined
+            ? undefined
+            : safeText(activity.streamingText.slice(-2048), 2048),
+        lastActivityAt: activity.lastActivityAt,
+        recentOutput: activity.recentOutput?.slice(-4).map((line) => safeText(line, 256)),
+    };
+}
+function compactChild(child) {
+    return {
+        agent: child.agent,
+        index: child.index,
+        workflowNodeId: child.workflowNodeId,
+        sessionFile: child.sessionFile,
+        task: child.task === undefined ? undefined : safeText(child.task),
+        label: child.label === undefined ? undefined : safeText(child.label, 256),
+        state: child.state,
+        configuration: child.configuration,
+        missingSession: child.missingSession,
+        identityUnavailable: child.identityUnavailable,
+        modelSelection: child.modelSelection,
+        savedConfiguration: child.launch && {
+            model: child.launch.model,
+            thinking: child.launch.thinking,
+            modelRecordedAt: child.launch.modelRecordedAt,
+        },
+        humanAction: child.result?.acceptance && safeText(acceptanceHumanAction(child.result.acceptance), 2048),
+        acceptanceStatus: child.result?.acceptance?.status,
+        activity: compactActivity(child.activity),
+        result: compactResult(child.result),
+    };
+}
+function compactQuestion(question) {
+    const summary = summarizeSupervisorQuestion(question);
+    return {
+        ...summary,
+        message: safeText(question.message, 2048),
+        answer: summary.answer && {
+            ...summary.answer,
+            message: safeText(question.answer?.message, 2048),
+        },
+    };
+}
+export function unknownRun(run, diagnosis = "Run summary is awaiting background canonical projection.") {
+    return {
+        ...run,
+        state: "unknown",
+        updatedAt: run.startedAt,
+        attention: ["unknown"],
+        canInterrupt: false,
+        continuations: [],
+        children: run.children.map((child) => ({
+            ...child,
+            state: "unknown",
+            configuration: "legacy-partial",
+        })),
+        diagnosis,
+    };
+}
+export function compactView(view) {
+    return {
+        ...view,
+        task: safeText(view.task, 2048),
+        error: view.error === undefined ? undefined : safeText(view.error),
+        diagnosis: view.diagnosis === undefined ? undefined : safeText(view.diagnosis),
+        recoveryError: view.recoveryError === undefined ? undefined : safeText(view.recoveryError),
+        review: view.review && {
+            ...view.review,
+            message: view.review.message === undefined ? undefined : safeText(view.review.message),
+        },
+        continuations: [],
+        questions: view.questions?.map(compactQuestion),
+        children: view.children.map(compactChild),
+        summary: safeText(view.children
+            .map((child) => child.result?.finalOutput ?? child.result?.error ?? "")
+            .filter((text) => text.length > 0)
+            .join(" | "), 1024),
+    };
+}
+/** Canonical owner/filesystem projection. Native transcript presence never establishes completion. */
+export function projectRun(run, ownerSessionId, runs, foreground) {
+    const state = { ownedRuns: runs, foregroundRuns: foreground };
+    const questions = listRunQuestions(getRunMetadataDir(run.runId)).filter((question) => question.ownerSessionId === ownerSessionId &&
+        ["awaiting_input", "answer_pending"].includes(question.state));
+    return {
+        ...ownedRunView(run, state, {
+            pendingInput: questions.length > 0,
+            includeContinuations: false,
+            readConfiguration: false,
+            reconcile: false,
+        }),
+        questions,
+    };
+}

package/dist/history/run-queries.js

@@ -0,0 +1,153 @@
+import { HistoryIndexError, } from "./types.js";
+import { integer, pageLimit, hasText } from "./text.js";
+import { number, text } from "./rows.js";
+import { parseRunRow } from "./wire-models.js";
+function validate(options) {
+    if (options.state !== undefined &&
+        !["live", "completed", "paused", "blocked", "failed", "unknown"].includes(options.state)) {
+        throw new HistoryIndexError("INVALID", "Unsupported run state.");
+    }
+    validateFilters(options);
+}
+function validateFilters(options) {
+    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.");
+    }
+}
+function queryKey(scope, options, sort) {
+    return scope.key([
+        "runs",
+        sort,
+        options.agent ?? null,
+        options.state ?? null,
+        options.text?.toLowerCase() ?? null,
+        options.latestTasksOnly ?? false,
+    ]);
+}
+function filters(options) {
+    const clauses = [];
+    const params = [];
+    const childClauses = [];
+    const childParams = [];
+    if (hasText(options.agent)) {
+        childClauses.push("c.agent=?");
+        childParams.push(options.agent);
+    }
+    if (hasText(options.text)) {
+        childClauses.push("instr(c.filter_text,?)>0");
+        childParams.push(options.text.toLowerCase());
+    }
+    if (options.latestTasksOnly === true) {
+        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 > 0 ? ` AND ${childClauses.join(" AND ")}` : "";
+    if (childWhere.length > 0) {
+        clauses.push(`EXISTS(SELECT 1 FROM children c WHERE c.run_id=r.id${childWhere})`);
+        params.push(...childParams);
+    }
+    if (hasText(options.state)) {
+        clauses.push("r.state=?");
+        params.push(options.state);
+    }
+    return { clauses, params, childWhere, childParams };
+}
+function columns(sort) {
+    if (sort === "attention") {
+        return ["attention", "negative_updated", "id"];
+    }
+    return [sort === "newest" ? "negative_updated" : "updated", "id"];
+}
+function runSort(value) {
+    const sort = value ?? "attention";
+    if (!["attention", "newest", "oldest"].includes(sort)) {
+        throw new HistoryIndexError("INVALID", "Unsupported run sort.");
+    }
+    return sort;
+}
+function seek(filter, cursor, order) {
+    if (!cursor) {
+        return filter;
+    }
+    if (cursor.keys.length !== order.length) {
+        throw new HistoryIndexError("INVALID_CURSOR", "Invalid run seek tuple.");
+    }
+    return {
+        ...filter,
+        clauses: [
+            ...filter.clauses,
+            `(${order.map((column) => `r.${column}`).join(",")}) > (${order.map(() => "?").join(",")})`,
+        ],
+        params: [...filter.params, ...cursor.keys],
+    };
+}
+export class RunQueries {
+    scope;
+    constructor(scope) {
+        this.scope = scope;
+    }
+    view(row, filter) {
+        const value = JSON.parse(text(row, "view"));
+        const view = parseRunRow(value);
+        const matchedChildIndexes = filter.childWhere.length > 0
+            ? this.scope.store
+                .all(`SELECT child_index FROM children c WHERE c.run_id=?${filter.childWhere} ORDER BY child_index`, view.runId, ...filter.childParams)
+                .map((child) => number(child, "child_index"))
+            : view.matchedChildIndexes;
+        return {
+            ...view,
+            ...(matchedChildIndexes === undefined ? {} : { matchedChildIndexes }),
+            children: view.children.map((child) => {
+                const { source } = this.scope.child(view.runId, child.index);
+                if (!source) {
+                    return child;
+                }
+                const boundary = child.state === "live"
+                    ? {}
+                    : {
+                        terminalEntryId: child.result?.terminalEntryId,
+                        endedAt: (child.result?.terminalEntryId?.length ?? 0) > 0 ? undefined : view.updatedAt,
+                        leaf: child.result?.terminalLeafId,
+                    };
+                return Object.assign({}, child, {
+                    nativeConfiguration: this.scope.configuration(source, boundary, false),
+                });
+            }),
+        };
+    }
+    nextPage(query, order, page, position) {
+        const last = page.at(-1);
+        return last
+            ? {
+                nextOffset: position + page.length,
+                nextCursor: this.scope.cursor(query, order.map((column) => (column === "id" ? text(last, column) : number(last, column))), position + page.length),
+            }
+            : {};
+    }
+    list(options) {
+        validate(options);
+        const limit = pageLimit(options.limit, 20);
+        const offset = integer(options.offset, 0);
+        const sort = runSort(options.sort);
+        const query = queryKey(this.scope, options, sort);
+        const cursor = this.scope.parseCursor(options.cursor, query);
+        if (cursor && options.offset !== undefined) {
+            throw new HistoryIndexError("INVALID", "Use cursor or offset, not both.");
+        }
+        const filter = filters(options);
+        const total = number(this.scope.store.require(`SELECT COUNT(*) AS total FROM runs r ${filter.clauses.length > 0 ? `WHERE ${filter.clauses.join(" AND ")}` : ""}`, ...filter.params), "total");
+        const order = columns(sort);
+        const selected = seek(filter, cursor, order);
+        const rows = this.scope.store.all(`SELECT * FROM runs r ${selected.clauses.length > 0 ? `WHERE ${selected.clauses.join(" AND ")}` : ""} ORDER BY ${order.map((column) => `r.${column}`).join(",")} LIMIT ? OFFSET ?`, ...selected.params, limit + 1, cursor ? 0 : offset);
+        const page = rows.slice(0, limit);
+        const position = cursor?.offset ?? offset;
+        return {
+            rows: page.map((row) => this.view(row, filter)),
+            total,
+            offset: position,
+            ...this.scope.info(),
+            ...this.nextPage(query, order, rows.length > limit ? page : [], position),
+        };
+    }
+}

package/dist/history/schema.js

@@ -0,0 +1,31 @@
+import { randomUUID } from "node:crypto";
+export const HISTORY_SCHEMA_VERSION = 5;
+/** One schema version owns the row, FTS and cursor publication contracts together. */
+export function createHistorySchema(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=${HISTORY_SCHEMA_VERSION};
+  `);
+}

package/dist/history/search-queries.js

@@ -0,0 +1,163 @@
+import { HistoryIndexError, } from "./types.js";
+import { integer, pageLimit, hasText } from "./text.js";
+import { number, nullableNumber, nullableText, text } from "./rows.js";
+function searchGrammar(query) {
+    if (typeof query !== "string" || query.trim().length === 0 || query.length > 1024) {
+        throw new HistoryIndexError("INVALID_QUERY", "Search requires 1–12 tokens or one quoted phrase.");
+    }
+    const value = query.trim();
+    const phrase = value.startsWith('"') && value.endsWith('"');
+    const words = (phrase ? value.slice(1, -1) : value).trim().split(/\s+/u);
+    if (words.length === 0 ||
+        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 match(row) {
+    return {
+        id: number(row, "document_id"),
+        runId: text(row, "run_id"),
+        index: number(row, "child_index"),
+        agent: text(row, "agent"),
+        entryId: text(row, "id"),
+        nativeId: nullableText(row, "native_id"),
+        sessionId: nullableText(row, "session_id"),
+        sessionFile: text(row, "path"),
+        timestamp: nullableNumber(row, "timestamp"),
+        ref: {
+            sourceId: text(row, "source_id"),
+            generation: number(row, "generation"),
+            start: number(row, "start"),
+            end: number(row, "end"),
+            digest: text(row, "digest"),
+        },
+        preview: text(row, "document_preview"),
+        field: text(row, "field"),
+        textStart: number(row, "text_start"),
+        textEnd: number(row, "text_end"),
+        score: number(row, "score"),
+    };
+}
+function plan(input, expression, cursor, score) {
+    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)",
+    ];
+    const params = [...expression];
+    if (hasText(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 (hasText(input.agent)) {
+        if (input.agent.length > 256) {
+            throw new HistoryIndexError("INVALID", "Agent filter is too long.");
+        }
+        clauses.push("c.agent=?");
+        params.push(input.agent);
+    }
+    // Scope physical records once before aggregation; bm25 still uses the whole corpus.
+    const eligible = hasText(input.runId) || hasText(input.agent)
+        ? `eligible AS MATERIALIZED (SELECT e.rowid FROM entries e JOIN sources s ON s.id=e.source_id WHERE e.published=1 AND e.generation=s.generation AND e.source_id IN (SELECT c.source_id FROM children c WHERE ${clauses.slice(4).join(" AND ")})),`
+        : "";
+    const eligibleParams = eligible.length > 0 ? params.slice(expression.length) : [];
+    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);
+    }
+    return { clauses, params, eligible, eligibleParams };
+}
+function queryKey(scope, input, expression, sort) {
+    return scope.key([
+        "search",
+        expression,
+        sort,
+        input.runId ?? null,
+        input.index ?? null,
+        input.agent ?? null,
+    ]);
+}
+export class SearchQueries {
+    scope;
+    constructor(scope) {
+        this.scope = scope;
+    }
+    validateScope(input) {
+        if (input.index !== undefined && !hasText(input.runId)) {
+            throw new HistoryIndexError("INVALID", "A child search requires runId.");
+        }
+        if (!hasText(input.runId)) {
+            return;
+        }
+        if (!this.scope.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.scope.child(input.runId, integer(input.index, 0));
+        }
+        this.checkAttemptBoundaries(input);
+    }
+    checkAttemptBoundaries(input) {
+        for (const child of this.scope.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 sourceId = nullableText(child, "source_id");
+            const source = sourceId === null ? undefined : this.scope.store.source(sourceId);
+            if (source) {
+                this.scope.boundary(source, {
+                    terminalEntryId: nullableText(child, "terminal_entry_id") ?? undefined,
+                    endedAt: nullableNumber(child, "ended_at") ?? undefined,
+                });
+            }
+        }
+    }
+    rows(expression, filter, score, limit) {
+        // Match every token across a record's visible windows; a quoted phrase cannot span fields.
+        // Ranking/filters precede LIMIT. The parent owns the hard deadline for a costly FTS scan.
+        return this.scope.store.all(`WITH ${filter.eligible} 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 ?${filter.eligible.length > 0 ? " AND d.entry_rowid IN (SELECT rowid FROM eligible)" : ""}`).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 ${filter.clauses.join(" AND ")} ORDER BY score,d.id,c.run_id,c.child_index LIMIT ?`, ...filter.eligibleParams, ...filter.params, limit + 1);
+    }
+    search(input) {
+        const expression = searchGrammar(input.query);
+        const limit = pageLimit(input.limit, 20);
+        const sort = input.sort ?? "relevance";
+        if (!["relevance", "newest"].includes(sort)) {
+            throw new HistoryIndexError("INVALID", "Unsupported search sort.");
+        }
+        this.validateScope(input);
+        const query = queryKey(this.scope, input, expression, sort);
+        const cursor = this.scope.parseCursor(input.cursor, query);
+        const score = sort === "relevance" ? "matched.score" : "-COALESCE(e.timestamp,0)";
+        const filter = plan(input, expression, cursor, score);
+        const rows = this.rows(expression, filter, score, limit);
+        const page = rows.slice(0, limit);
+        const last = page.at(-1);
+        return {
+            ...this.scope.info(),
+            matches: page.map(match),
+            ...(rows.length > limit && last
+                ? {
+                    nextCursor: this.scope.cursor(query, [
+                        number(last, "score"),
+                        number(last, "document_id"),
+                        text(last, "run_id"),
+                        number(last, "child_index"),
+                    ], (cursor?.offset ?? 0) + page.length),
+                }
+                : {}),
+        };
+    }
+}

package/dist/history/selected-record.js

@@ -0,0 +1,108 @@
+import * as fs from "node:fs";
+import { createHash } from "node:crypto";
+import { JsonProjection } from "../shared/journal-reader.js";
+import { HistoryIndexError } from "./types.js";
+import { identity } from "./source-file.js";
+import { previewLimits, previewProjection } from "./preview.js";
+import { parseObject } from "./values.js";
+import { isRecord, hasErrorCode } from "../shared/unknown.js";
+function validateHeader(fd, source) {
+    const hash = createHash("sha256");
+    const bytes = Buffer.allocUnsafe(64 * 1024);
+    let position = 0;
+    let complete = false;
+    while (!complete && position < 1024 * 1024) {
+        const count = fs.readSync(fd, bytes, 0, bytes.length, position);
+        if (count === 0) {
+            break;
+        }
+        const newline = bytes.subarray(0, count).indexOf(10);
+        const length = newline < 0 ? count : newline + 1;
+        hash.update(bytes.subarray(0, length));
+        position += length;
+        complete = newline >= 0;
+    }
+    if (!complete || hash.digest("hex") !== source.header_digest) {
+        throw new HistoryIndexError("SOURCE_CHANGED", "Selected native header changed or exceeds its validation budget.");
+    }
+}
+function readBody(fd, row, full) {
+    const digest = createHash("sha256");
+    const parser = new JsonProjection(previewProjection, undefined, undefined, previewLimits);
+    const bytes = Buffer.allocUnsafe(64 * 1024);
+    const 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 === 0) {
+            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;
+    }
+    return {
+        digest: digest.digest("hex"),
+        finish: () => {
+            if (full) {
+                return parseObject(new TextDecoder("utf8", { fatal: true }).decode(Buffer.concat(body)));
+            }
+            parser.write(decoder.decode());
+            const projected = parser.finish();
+            if (!isRecord(projected)) {
+                throw new HistoryIndexError("SOURCE_CHANGED", "Selected record is not an object.");
+            }
+            return projected;
+        },
+    };
+}
+function validateSnapshot(fd, source, row, snapshot) {
+    const { before, digest } = snapshot;
+    const current = fs.statSync(source.path, { bigint: true });
+    const after = fs.fstatSync(fd, { bigint: true });
+    if (identity(current) !== identity(before) ||
+        current.size < BigInt(row.end) ||
+        (after.ctimeNs !== before.ctimeNs && after.size <= before.size) ||
+        digest !== row.digest) {
+        throw new HistoryIndexError("SOURCE_CHANGED", "Selected record changed; refresh history before reading details.");
+    }
+}
+/** Revalidate physical identity, native header and exact selected bytes before exposing detail. */
+export 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.");
+        }
+        validateHeader(fd, source);
+        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 body = readBody(fd, row, full);
+        validateSnapshot(fd, source, row, { before: stat, digest: body.digest });
+        // Physical validation wins over full JSON/UTF-8 decode errors if the file changed during reading.
+        return body.finish();
+    }
+    catch (error) {
+        if (hasErrorCode(error, "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);
+        }
+    }
+}