@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/dist/history/index.js

@@ -1,10 +1,12 @@
 import { fork } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
-import { HistoryIndexError } from "./types.js";
+import { HistoryIndexError, } from "./types.js";
 import { requirePiPackageRoot } from "../runs/shared/pi-spawn.js";
+import { isRecord } from "../shared/unknown.js";
+import { parseRunPage, parsePage, parseSearchPage, parseStatus, parseEntry, parseResult, parseNothing, parseBoolean, parseResponse, } from "./wire-models.js";
 export * from "./types.js";
-/** A disposable browse index. Authoritative owner/control/receipt checks remain outside this engine. */
+/** Disposable browse process. Authoritative ownership/control/receipt checks stay outside this engine. */
 export class SubagentHistoryIndex {
     process;
     children = new Map();
@@ -17,55 +19,91 @@ export class SubagentHistoryIndex {
     pending = new Map();
     listeners = new Set();
     agentDir;
-    constructor(agentDir) { this.agentDir = path.resolve(agentDir); }
-    get failure() { return this.unavailable; }
-    spawn() {
-        const child = fork(fileURLToPath(new URL(`worker${import.meta.url.endsWith(".ts") ? ".ts" : ".js"}`, import.meta.url)), [this.agentDir], {
-            execArgv: [], stdio: ["ignore", "ignore", "ignore", "ipc"], serialization: "advanced",
-            env: { ...process.env, PI_PACKAGE_DIR: requirePiPackageRoot(), PI_CODING_AGENT_DIR: this.agentDir },
-        });
-        this.unavailable = undefined;
-        this.process = child;
-        this.children.set(child, new Promise((resolve) => {
+    constructor(agentDir) {
+        this.agentDir = path.resolve(agentDir);
+    }
+    get failure() {
+        return this.unavailable;
+    }
+    track(child) {
+        const completed = new Promise((resolve) => {
             const exited = () => {
                 child.removeListener("exit", exited);
                 child.removeListener("close", exited);
                 this.children.delete(child);
                 resolve();
             };
-            // Disconnected IPC children can exit without Node emitting close. Exit already
-            // releases their database and watch handles; failed spawns report close instead.
+            // Disconnected IPC can exit without close; failed spawn instead reports close.
             child.once("exit", exited);
             child.once("close", exited);
-        }));
-        child.on("message", (message) => {
-            if (child !== this.process)
-                return;
-            if ("changed" in message) {
-                for (const listener of this.listeners) {
-                    try {
-                        listener();
-                    }
-                    catch { /* Consumer failures must not strand IPC requests. */ }
-                }
+        });
+        this.children.set(child, completed);
+    }
+    message(child, value) {
+        if (child !== this.process) {
+            return;
+        }
+        try {
+            const response = parseResponse(value);
+            if ("changed" in response) {
+                this.notify();
                 return;
             }
-            const pending = this.pending.get(message.id);
-            if (!pending)
+            const pending = this.pending.get(response.id);
+            if (!pending) {
                 return;
-            this.pending.delete(message.id);
+            }
+            this.pending.delete(response.id);
             pending.cleanup();
-            if (message.error)
-                pending.reject(new HistoryIndexError(message.error.code, message.error.message));
-            else
-                pending.resolve(message.value);
+            if (response.error) {
+                pending.reject(new HistoryIndexError(response.error.code, response.error.message));
+            }
+            else {
+                pending.resolve(response.value);
+            }
+        }
+        catch {
+            this.stop(new HistoryIndexError("INVALID", "Invalid history IPC response."), child);
+        }
+    }
+    notify() {
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch {
+                // Consumer failure cannot strand IPC requests.
+            }
+        }
+    }
+    spawn() {
+        const child = fork(fileURLToPath(new URL(`worker${import.meta.url.endsWith(".ts") ? ".ts" : ".js"}`, import.meta.url)), [this.agentDir], {
+            execArgv: [],
+            stdio: ["ignore", "ignore", "ignore", "ipc"],
+            serialization: "advanced",
+            env: {
+                ...process.env,
+                PI_PACKAGE_DIR: requirePiPackageRoot(),
+                PI_CODING_AGENT_DIR: this.agentDir,
+            },
+        });
+        this.unavailable = undefined;
+        this.process = child;
+        this.track(child);
+        child.on("message", (message) => {
+            this.message(child, message);
+        });
+        child.on("error", () => {
+            this.stop(new HistoryIndexError("UNAVAILABLE", "History process could not start."), child);
+        });
+        child.on("exit", () => {
+            this.stop(new HistoryIndexError("UNAVAILABLE", "History process exited; retry to reopen the disposable index."), child);
         });
-        child.on("error", () => this.stop(new HistoryIndexError("UNAVAILABLE", "History process could not start."), child));
-        child.on("exit", () => this.stop(new HistoryIndexError("UNAVAILABLE", "History process exited; retry to reopen the disposable index."), child));
     }
     stop(error, child = this.process, kill = true) {
-        if (!child || child !== this.process)
+        if (!child || child !== this.process) {
             return;
+        }
         this.unavailable = error;
         this.process = undefined;
         this.ready = undefined;
@@ -74,125 +112,232 @@ export class SubagentHistoryIndex {
             pending.reject(error);
         }
         this.pending.clear();
-        if (kill && child.exitCode === null && child.signalCode === null)
+        if (kill && child.exitCode === null && child.signalCode === null) {
             child.kill("SIGKILL");
+        }
     }
-    send(method, input, signal, timeout = 3000) {
-        if (this.closed)
+    send(method, input, decode, options = {}) {
+        if (this.closed) {
             return Promise.reject(new HistoryIndexError("CLOSED", "History index is closed."));
-        if (signal?.aborted)
+        }
+        if (options.signal?.aborted === true) {
             return Promise.reject(new HistoryIndexError("CANCELLED", "History request cancelled."));
+        }
         const child = this.process;
-        if (!child?.connected)
+        if (!child || !child.connected) {
             return Promise.reject(new HistoryIndexError("UNAVAILABLE", "History process is unavailable."));
+        }
         return new Promise((resolve, reject) => {
             const id = ++this.sequence;
-            const cancel = () => this.stop(new HistoryIndexError("CANCELLED", "History request cancelled; the process was stopped and can be reopened."), child);
-            const timer = setTimeout(() => this.stop(new HistoryIndexError("DEADLINE", "History request exceeded its process deadline; retry or narrow the query."), child), timeout);
+            const cancel = () => {
+                this.stop(new HistoryIndexError("CANCELLED", "History request cancelled; the process was stopped and can be reopened."), child);
+            };
+            const timer = setTimeout(() => {
+                this.stop(new HistoryIndexError("DEADLINE", "History request exceeded its process deadline; retry or narrow the query."), child);
+            }, options.timeout ?? 3000);
             timer.unref();
-            this.pending.set(id, { resolve, reject, cleanup: () => { clearTimeout(timer); signal?.removeEventListener("abort", cancel); } });
-            signal?.addEventListener("abort", cancel, { once: true });
-            child.send({ id, method, input }, (error) => { if (error)
-                this.stop(new HistoryIndexError("UNAVAILABLE", "History IPC failed."), child); });
+            this.pending.set(id, {
+                resolve: (value) => {
+                    try {
+                        resolve(decode(value));
+                    }
+                    catch (error) {
+                        reject(error instanceof Error
+                            ? error
+                            : new HistoryIndexError("INVALID", "History IPC decoding failed."));
+                    }
+                },
+                reject,
+                cleanup: () => {
+                    clearTimeout(timer);
+                    options.signal?.removeEventListener("abort", cancel);
+                },
+            });
+            options.signal?.addEventListener("abort", cancel, { once: true });
+            child.send({ id, method, input }, (error) => {
+                if (error) {
+                    this.stop(new HistoryIndexError("UNAVAILABLE", "History IPC failed."), child);
+                }
+            });
         });
     }
     async ensure() {
-        if (this.closed)
+        if (this.closed) {
             throw new HistoryIndexError("CLOSED", "History index is closed.");
-        if (this.unavailable)
+        }
+        if (this.unavailable) {
             throw this.unavailable;
-        if (!this.owner)
+        }
+        if (!this.owner) {
             throw new HistoryIndexError("NO_OWNER", "Set genuine restored ownership before querying history.");
+        }
         if (!this.process) {
             await Promise.all(this.children.values());
-            if (this.closed)
+            // close() and setOwner() can change lifecycle state while old children exit.
+            // oxlint-disable-next-line typescript/no-unnecessary-condition
+            if (this.closed) {
                 throw new HistoryIndexError("CLOSED", "History index is closed.");
-            if (!this.process) {
+            }
+            // setOwner() may install a replacement while this ensure() waits for child exit.
+            // oxlint-disable-next-line typescript/no-unnecessary-condition
+            if (this.process === undefined) {
                 this.spawn();
-                this.ready = this.send("setOwner", this.owner, undefined, 15_000);
+                this.ready = this.send("setOwner", this.owner, parseNothing, { timeout: 15_000 });
             }
         }
         await this.ready;
     }
     /** Arms an ordinary deadline only in the continuation that saw the current admission and worker settle, never behind a replacement admission. */
-    async admitted(method, input, signal, timeout) {
+    async admitted(method, input, decode, options = {}) {
         await this.ensure();
-        const ready = this.ready, child = this.process;
+        const ready = this.ready;
+        const child = this.process;
         await ready;
         // setOwner() or a restart may have replaced readiness during either await; wait for the replacement.
-        if (!child || ready !== this.ready || child !== this.process)
-            return this.admitted(method, input, signal, timeout);
-        return this.send(method, input, signal, timeout);
+        if (!child || ready !== this.ready || child !== this.process) {
+            return this.admitted(method, input, decode, options);
+        }
+        return this.send(method, input, decode, options);
     }
     async setOwner(input) {
-        if (this.closed)
+        if (this.closed) {
             throw new HistoryIndexError("CLOSED", "History index is closed.");
-        if (!this.process)
+        }
+        if (!this.process) {
             await Promise.all(this.children.values());
-        if (this.closed)
+        }
+        // close() may run while the previous child is exiting.
+        // oxlint-disable-next-line typescript/no-unnecessary-condition
+        if (this.closed) {
             throw new HistoryIndexError("CLOSED", "History index is closed.");
-        // Snapshot inputs so later caller mutation cannot silently change admission or replay.
+        }
         const snapshot = structuredClone(input);
-        if (!snapshot.ownerSessionId || snapshot.runs.some((run) => run.ownerSessionId !== snapshot.ownerSessionId))
+        if (snapshot.ownerSessionId.length === 0 ||
+            snapshot.runs.some((run) => run.ownerSessionId !== snapshot.ownerSessionId)) {
             throw new HistoryIndexError("OWNERSHIP", "Every run must belong to the current owner session.");
-        if (new Set(snapshot.runs.map((run) => run.runId)).size !== snapshot.runs.length)
+        }
+        if (new Set(snapshot.runs.map((run) => run.runId)).size !== snapshot.runs.length) {
             throw new HistoryIndexError("INVALID", "Duplicate owned run IDs.");
+        }
         this.owner = snapshot;
-        if (!this.process)
+        if (!this.process) {
             this.spawn();
-        this.ready = this.send("setOwner", snapshot, undefined, 15_000);
+        }
+        this.ready = this.send("setOwner", snapshot, parseNothing, { timeout: 15_000 });
         await this.ready;
     }
     async updateRun(run, foreground) {
         await this.ensure();
-        if (run.ownerSessionId !== this.owner.ownerSessionId || foreground && foreground.runId !== run.runId)
+        const owner = this.owner;
+        if (!owner ||
+            run.ownerSessionId !== owner.ownerSessionId ||
+            (foreground && foreground.runId !== run.runId)) {
             throw new HistoryIndexError("OWNERSHIP", "Run does not belong to the current owner.");
-        const copy = structuredClone(run), fg = foreground && structuredClone(foreground);
-        await this.admitted("updateRun", { run: copy, foreground: fg });
-        this.owner.runs = [...this.owner.runs.filter((entry) => entry.runId !== run.runId), copy];
-        if (fg)
-            this.owner.foregroundRuns = [...(this.owner.foregroundRuns ?? []).filter((entry) => entry.runId !== run.runId), fg];
+        }
+        const copy = structuredClone(run);
+        const fg = foreground === undefined ? undefined : structuredClone(foreground);
+        await this.admitted("updateRun", { run: copy, foreground: fg }, parseNothing);
+        const current = this.owner;
+        if (!current || current.ownerSessionId !== owner.ownerSessionId) {
+            throw new HistoryIndexError("OWNER_CHANGED", "History owner changed during run update.");
+        }
+        this.owner = {
+            ...current,
+            runs: [...current.runs.filter((entry) => entry.runId !== run.runId), copy],
+            ...(fg
+                ? {
+                    foregroundRuns: [
+                        ...(current.foregroundRuns ?? []).filter((entry) => entry.runId !== run.runId),
+                        fg,
+                    ],
+                }
+                : {}),
+        };
     }
-    async query(method, input) {
+    async query(method, input, decode) {
         const { signal, ...wire } = input;
-        return this.admitted(method, wire, signal);
-    }
-    /** Tool discovery waits for run metadata only, not transcript backfill. */
-    needsControls() { return this.admitted("needsControls", undefined, undefined, 15_000); }
-    listRuns(options = {}) { return this.query("listRuns", options); }
-    historyPage(input) { return this.query("historyPage", input); }
-    search(input) { return this.query("search", input); }
-    status() { return this.query("status", {}); }
-    /** Validated bounded preview, including paired tools outside the current page. */
-    entry(input) { return this.query("entry", input); }
-    /** Explicit selected detail only; records over 16 MiB fail with RECORD_TOO_LARGE. */
-    record(input) { return this.query("record", input); }
-    /** Selected canonical output, never a transcript scan or a truncated-preview match. */
-    result(input) { return this.query("result", input); }
+        return this.admitted(method, wire, decode, { signal });
+    }
+    async needsControls() {
+        return this.admitted("needsControls", undefined, parseBoolean, { timeout: 15_000 });
+    }
+    listRuns(options = {}) {
+        return this.query("listRuns", options, parseRunPage);
+    }
+    historyPage(input) {
+        return this.query("historyPage", input, parsePage);
+    }
+    search(input) {
+        return this.query("search", input, parseSearchPage);
+    }
+    status() {
+        return this.query("status", {}, parseStatus);
+    }
+    entry(input) {
+        return this.query("entry", input, parseEntry);
+    }
+    record(input) {
+        return this.query("record", input, (value) => {
+            if (value === null) {
+                return null;
+            }
+            if (!isRecord(value)) {
+                throw new HistoryIndexError("INVALID", "Invalid history detail response.");
+            }
+            return value;
+        });
+    }
+    result(input) {
+        return this.query("result", input, parseResult);
+    }
     async refresh(runId, options = {}) {
-        if (!this.closed)
+        if (!this.closed) {
             this.unavailable = undefined;
-        return this.admitted("refresh", { runId }, options.signal, 120_000);
+        }
+        return this.admitted("refresh", { runId }, parseNothing, {
+            signal: options.signal,
+            timeout: 120_000,
+        });
+    }
+    onChanged(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    cancel() {
+        this.stop(new HistoryIndexError("CANCELLED", "History process cancelled; explicitly refresh or retry to reopen it."));
+    }
+    async waitForChildren(timers) {
+        await Promise.all(this.children.values());
+        for (const timer of timers) {
+            clearTimeout(timer);
+        }
     }
-    onChanged(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
-    /** Hard cancellation affects this instance's outstanding work, not native sessions or other indexers. */
-    cancel() { this.stop(new HistoryIndexError("CANCELLED", "History process cancelled; explicitly refresh or retry to reopen it.")); }
     close() {
-        if (this.closing)
+        if (this.closing) {
             return this.closing;
+        }
         const child = this.process;
         this.closed = true;
         this.listeners.clear();
         this.unavailable ??= new HistoryIndexError("CLOSED", "History index closed.");
-        const timers = [...this.children.keys()].map((owned) => { const timer = setTimeout(() => owned.kill("SIGKILL"), 1000); timer.unref(); return timer; });
-        this.closing = Promise.all(this.children.values()).then(() => { for (const timer of timers)
-            clearTimeout(timer); });
+        const timers = [...this.children.keys()].map((owned) => {
+            const timer = setTimeout(() => {
+                owned.kill("SIGKILL");
+            }, 1000);
+            timer.unref();
+            return timer;
+        });
+        this.closing = this.waitForChildren(timers);
         if (child) {
             this.stop(new HistoryIndexError("CLOSED", "History index closed."), child, false);
-            if (child.connected)
+            if (child.connected) {
                 child.disconnect();
-            else
+            }
+            else {
                 child.kill("SIGKILL");
+            }
         }
         return this.closing;
     }