toolroll 0.9.73 → 0.9.74

package/dist/live-open.js

@@ -0,0 +1,125 @@
+/**
+ * Opening and reading a live file for the Agents view (docs/plans/agents-view.md §3, N4, N5): one opener and one
+ * bounded line reader, shared by every reader and observer that slice adds.
+ *
+ * The opener. Node has no openat, so a file can't be opened relative to a held directory; instead the open is checked
+ * on both sides. Before: the live directory is a real directory (not a link), owned by this process's user, writable
+ * by no one else, and it resolves inside the data root. The file is opened O_NOFOLLOW | O_NONBLOCK (a link or a FIFO
+ * never blocks or redirects), and its descriptor must be a plain file with exactly one link, this user's, on the
+ * directory's device. After: the directory path still names the same directory, and the file path still names the
+ * very file opened. Anything else is "unavailable" — never a guess, never another file's contents or timing.
+ *
+ * The reader. One request reads at most READ_WINDOW bytes and looks at most SCAN_BUDGET past its start for a line's
+ * end: a longer line is skipped and said so, and the scan resumes past it on the next request rather than blocking
+ * this one. An unfinished last line stays pending.
+ */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync } from "node:fs";
+import { join, sep } from "node:path";
+import { liveDir } from "./live.js";
+export const READ_WINDOW = 64 * 1024;
+export const SCAN_BUDGET = 256 * 1024;
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const uid = () => (typeof process.getuid === "function" ? BigInt(process.getuid()) : null);
+/** Open `name` in the run's live directory under `root`, or say it is missing or unavailable. */
+export function openLiveTrusted(root, name, seams = {}) {
+    if (!/^\d{1,15}\.(?:jsonl|sub\.jsonl)$/.test(name))
+        return "unavailable";
+    const dir = liveDir(root);
+    /** The live directory as it must be: a real directory of this user's, writable by no one else, inside the root. */
+    const trustedDir = () => {
+        const stat = lstatSync(dir, { bigint: true });
+        const real = realpathSync(dir), base = realpathSync(root), me = uid();
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 18n) !== 0n || !real.startsWith(base + sep))
+            return null;
+        return me !== null && stat.uid !== me ? null : stat;
+    };
+    let before;
+    try {
+        const checked = trustedDir();
+        if (checked === null)
+            return "unavailable";
+        before = checked;
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? "missing" : "unavailable";
+    }
+    const path = join(dir, name);
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? "missing" : "unavailable";
+    }
+    try {
+        seams.afterOpen?.();
+        const me = uid();
+        const ours = (stat) => stat.isFile() && stat.nlink === 1n && stat.dev === before.dev && (me === null || stat.uid === me);
+        const file = fstatSync(fd, { bigint: true });
+        if (!ours(file))
+            throw new Error("not ours");
+        // After the open: the whole directory predicate again (not just its identity), the path still naming this file,
+        // and the descriptor still this user's single-link plain file, right before it is accepted.
+        const after = trustedDir();
+        if (after === null || !same(after, before) || !same(lstatSync(path, { bigint: true }), file))
+            throw new Error("moved");
+        const now = fstatSync(fd, { bigint: true });
+        if (!ours(now) || !same(now, file))
+            throw new Error("changed");
+        return { fd, gen: `${now.dev}:${now.ino}:${now.birthtimeNs}`, size: Number(now.size) };
+    }
+    catch {
+        try {
+            closeSync(fd);
+        }
+        catch { /* already */ }
+        return "unavailable";
+    }
+}
+/** Read complete lines from `from` (discarding first through the next newline when `skipping`), within the budgets. */
+export function readLiveLines(fd, size, from, skipping = false) {
+    const out = { lines: [], next: from, skipped: 0, skipping: false };
+    if (from >= size)
+        return { ...out, skipping };
+    const want = Math.min(size - from, READ_WINDOW);
+    const buffer = Buffer.alloc(want);
+    let got = 0;
+    while (got < want) {
+        const n = readSync(fd, buffer, got, want - got, from + got);
+        if (n <= 0)
+            break;
+        got += n;
+    }
+    let at = 0;
+    if (skipping) {
+        const lf = buffer.subarray(0, got).indexOf(0x0a);
+        if (lf === -1)
+            return { ...out, next: from + got, skipping: true };
+        at = lf + 1;
+    }
+    for (;;) {
+        const lf = buffer.subarray(at, got).indexOf(0x0a);
+        if (lf === -1)
+            break;
+        out.lines.push({ text: buffer.subarray(at, at + lf).toString("utf8"), end: from + at + lf + 1 });
+        at += lf + 1;
+    }
+    out.next = from + at;
+    // Nothing whole in a full window: one line longer than the window. Look on, within the budget, for its end.
+    if (out.lines.length === 0 && !skipping && got === READ_WINDOW) {
+        const scan = Buffer.alloc(16 * 1024);
+        for (let pos = from + got; pos < Math.min(size, from + SCAN_BUDGET);) {
+            const n = readSync(fd, scan, 0, Math.min(scan.length, from + SCAN_BUDGET - pos, size - pos), pos);
+            if (n <= 0)
+                break;
+            const lf = scan.subarray(0, n).indexOf(0x0a);
+            if (lf !== -1)
+                return { ...out, next: pos + lf + 1, skipped: 1 };
+            pos += n;
+        }
+        // Past the budget (or the end so far) still inside it: resume discarding there next time.
+        const stop = Math.min(size, from + SCAN_BUDGET);
+        return { ...out, next: stop, skipped: 1, skipping: true };
+    }
+    return out;
+}

package/dist/live-records.d.ts

@@ -104,12 +104,20 @@ export declare function liveOutput(raw: string, keys?: KeyState): string[];
 export declare function livePath(base: string | null, given: unknown): string | null;
 /** A command's first line, "…" when more followed or it was cut. */
 export declare function liveCommand(given: unknown): string | null;
+declare const short: (given: unknown) => string | null;
+/** A short display form of one field: its first line, cleaned, redacted and cut (a delegated task's description). */
+export declare const liveShort: typeof short;
 export type LiveRecorderOptions = {
     /** The run's own checkout; null when it has none (every path is "a file"). */
     base: string | null;
     /** The project's "Show commands in the live view" setting, read at open. */
     commands: boolean;
     clock?: () => Date;
+    /** The key-block state to carry (the caller's, so it can write it down in a checkpoint); a fresh one by default. */
+    keyState?: KeyState;
+    /** Told of each step as it is recorded: the provider's call id (null when it has none), our id, and the target as
+     * written (redacted, under the key state). Observation only: it changes nothing recorded. */
+    onStep?: (call: string | null, id: string, target: string | null) => void;
 };
 export type LiveRecorder = {
     /** The records one stream event adds. Never throws. */
@@ -117,7 +125,7 @@ export type LiveRecorder = {
     /** The process ended: every step still open closes unknown. */
     end(): LiveRecord[];
 };
-export declare function createLiveRecorder(options: LiveRecorderOptions): LiveRecorder;
+export declare function createLiveRecorder(given: LiveRecorderOptions): LiveRecorder;
 /** One record as its file line; an oversized one becomes `cut`. */
 export declare function serializeLiveRecord(record: LiveRecord): string;
 /**
@@ -138,3 +146,4 @@ export declare function stepWords(step: {
 }): string;
 /** Records as the plain lines the run page and `toolroll peek` show. */
 export declare function projectLiveText(records: readonly LiveRecord[]): string[];
+export {};

package/dist/live-records.js

@@ -15,6 +15,7 @@
  */
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { scanForSecrets } from "./evidence.js";
+import { topLevelEvent } from "./stream-scope.js";
 export const LIVE_ACTIVITY_KINDS = ["session", "message", "edit", "command", "read", "search", "lookup", "plan", "delegate", "tool"];
 /** A record's serialized size limit: a longer one is replaced by `cut`. */
 export const LIVE_RECORD_CAP = 8 * 1024;
@@ -349,6 +350,8 @@ function liveHost(given) {
     }
 }
 const short = (given) => (typeof given === "string" ? liveTarget(given.split(/\r?\n/)[0] ?? "", SHORT_CAP) : null);
+/** A short display form of one field: its first line, cleaned, redacted and cut (a delegated task's description). */
+export const liveShort = short;
 /** Claude tools: our kind, and whether it is a command. */
 const CLAUDE_KINDS = new Map([
     ["Edit", "edit"], ["Write", "edit"], ["MultiEdit", "edit"], ["NotebookEdit", "edit"],
@@ -393,11 +396,14 @@ function resultText(content) {
         .map(part => String(part["text"]))
         .join("\n");
 }
-export function createLiveRecorder(options) {
-    const clock = options.clock ?? (() => new Date());
+export function createLiveRecorder(given) {
+    // The settings are read once, here: nothing the caller (or a callback) changes later reaches the recording.
+    const options = Object.freeze({ base: given.base, commands: given.commands === true });
+    const notifyStep = given.onStep;
+    const clock = given.clock ?? (() => new Date());
     let sequence = 0;
     /** A key block the agent began in one message stays hidden through the next, until it ends or a new session starts. */
-    const keyState = { inKey: false };
+    const keyState = given.keyState ?? { inKey: false };
     /** Provider call id → our step, while it is open. */
     const open = new Map();
     const stamp = () => clock().toISOString();
@@ -412,6 +418,12 @@ export function createLiveRecorder(options) {
         const id = `s${++sequence}`;
         const keyed = keyedTarget(target, keyState);
         const step = { k: "step", at, id, kind, ...(keyed === null ? {} : { target: keyed }) };
+        // Detached: called with no receiver, so it never sees (or changes) the settings above.
+        try {
+            if (notifyStep !== undefined)
+                notifyStep(call, id, keyed);
+        }
+        catch { /* observation only */ }
         if (call === null)
             return [{ ...step, once: true }];
         if (open.size >= OPEN_STEPS_CAP)
@@ -440,8 +452,7 @@ export function createLiveRecorder(options) {
     const claude = (event, at) => {
         const type = event["type"];
         // A subagent's words, tools, turns and sessions are not this run's conversation — and never close its steps.
-        const parent = event["parent_tool_use_id"];
-        if (parent !== undefined && parent !== null)
+        if (!topLevelEvent(event))
             return [];
         if (type === "system")
             return event["subtype"] === "init" ? (keyState.inKey = false, [...closeAll(at), { k: "start", at }]) : [];

package/dist/live.d.ts

@@ -19,13 +19,20 @@ export declare const LIVE_FILE_CAP: number;
 export declare const LIVE_REDACTED_LINE = "[a credential-shaped line was redacted]";
 /** Finalized runs keep their live file this long for the final drain. */
 export declare const LIVE_RETAIN_MS: number;
-/** The bounded sweep: at most this many FINALIZED files survive a pass. */
+/** The bounded sweep: at most this many FINALIZED runs' files survive a pass (a run's records and its subagents' file
+ * count as one). */
 export declare const LIVE_FILE_BOUND = 500;
+/** A run's subagent file (docs/plans/agents-view.md §2.3) is never larger than this; its writer stops there. */
+export declare const LIVE_SUB_FILE_CAP: number;
+/** All finished and orphan live files together stay under this; the oldest runs go first past it. */
+export declare const LIVE_TOTAL_BYTES: number;
 export declare function liveDir(root: string): string;
 /** The exact filename, from the numeric id and nothing else — no user
  * input is ever parsed into this path. Records (`.jsonl`) are what every
  * run writes now; the name is the format. */
 export declare function liveLogPath(root: string, runId: number): string;
+/** A run's subagents' records (docs/plans/agents-view.md §2.3): the run's file, swept with it. */
+export declare function liveSubLogPath(root: string, runId: number): string;
 /** The plain-text file runs wrote before the live conversation; read until it ages out. */
 export declare function legacyLiveLogPath(root: string, runId: number): string;
 export { LIVE_ACTIVITY_KINDS, type LiveActivityKind } from "./live-records.js";
@@ -78,43 +85,68 @@ export type LiveWindowRead = {
  * finalization. Legacy text is cleaned again on the way out.
  */
 export declare function readLiveWindow(root: string, runId: number, from: number, allowTail?: boolean): LiveWindowRead;
-/** A window's complete lines as the plain words the run page and `toolroll peek` show, whatever its format. */
+/** A window's complete lines as the plain words the run page and `toolroll peek` show, whatever its format. `commands` is
+ * the run's own captured answer (store.ts runLiveCommands), never the file's say. */
 export declare function liveWindowLines(read: {
     text: string;
     format: LiveFormat;
-}, keys?: KeyState): string[];
-/** A window as records, whatever its format: an older plain file's lines become the agent's words. */
+}, commands: boolean, keys?: KeyState): string[];
+/** A window as records, whatever its format: an older plain file's lines become the agent's words. Command text and
+ * output show only when the run's own captured answer (`commands`) is on. */
 export declare function liveWindowRecords(read: {
     text: string;
     format: LiveFormat;
-}, keys?: KeyState): LiveRecord[];
+}, commands: boolean, keys?: KeyState): LiveRecord[];
+/**
+ * Enforce a run's captured "Show commands" answer on read: the file is build-writable, so an `open` record, a command
+ * step's text or a step's output may say anything. With the answer off, every `open` reads the base tier, command steps
+ * lose their text and steps lose their output. (The older plain-text format predates command detail and is unchanged.)
+ */
+export declare function withholdCommands(records: LiveRecord[], commands: boolean): LiveRecord[];
 export type LiveSweepVerdict = {
     /** run id, or null when the name is not a run's file. */
     runId: number | null;
     fileName: string;
-    mtimeMs: number;
+    /** The most a file of this name is ever written to (records, subagents, older text); null for a name we never write. */
+    cap: number | null;
 };
 /**
- * Enumerate the live directory for the reconcile sweep. Pure listing — the
- * CALLER decides which runs are finalized and when; this module only
- * refuses to guess. Non-run names are reported with runId null (orphans
- * from nothing this plane wrote; aged on mtime like everything else).
+ * Enumerate the live directory for the reconcile sweep: names only. Pure listing — the CALLER settles which runs are
+ * finalized before it measures anything; this module only refuses to guess. Non-run names are reported with runId
+ * null (orphans from nothing this plane wrote; aged on mtime like everything else).
  */
 export declare function listLiveFiles(root: string): LiveSweepVerdict[];
-/** Remove one live file, silently: a sweep never throws over display state. */
-export declare function removeLiveFile(root: string, fileName: string): void;
+/** Remove one live file, silently: a sweep never throws over display state. True when it is gone now. */
+export declare function removeLiveFile(root: string, fileName: string, unlink?: (path: string) => void): boolean;
+type SweepRun = {
+    outcome: string | null;
+    finishedAt: string | null;
+};
+/** What the sweep reads of the store: a run's state, and (production) the write lock run admission also takes. */
+export type LiveSweepStore = {
+    getRun(id: number): SweepRun | null;
+    transact?<T>(body: () => T): T;
+};
 /**
  * The reconcile sweep (arc 1 §2): ACTIVE runs are exempt ABSOLUTELY — the
- * transport's no-truncation assumption depends on it. Finalized runs age
- * from finished_at; orphans (no run row, or a name this plane never
- * writes) age from mtime; and the 500-file bound applies only WITHIN the
- * finalized-or-orphan set, oldest first.
+ * transport's no-truncation assumption depends on it — and a run's files
+ * (its records, its subagents' file, an older text file) go together, as one.
+ * A run is settled finished (or absent) BEFORE its files are measured.
+ * Finalized runs age from finished_at; orphans (no run row, or a name this
+ * plane never writes) age from mtime. Among the finalized-or-orphan: a file
+ * far past its own cap goes at once, then the day's retention, then the
+ * 500-run bound, then the total byte limit, oldest first, until each limit is
+ * really met or nothing eligible is left. Each removal re-proves, under the
+ * store's write lock (the one run admission takes), that the run is still
+ * not active and the file is the very one measured; otherwise it is kept. A
+ * file that can't be removed stays counted and never stops the rest.
  */
-export declare function sweepLiveLogs(store: {
-    getRun(id: number): {
-        outcome: string | null;
-        finishedAt: string | null;
-    } | null;
-}, root: string, now: Date): {
+export declare function sweepLiveLogs(store: LiveSweepStore, root: string, now: Date, io?: {
+    unlink?: (path: string) => void;
+    lstat?: (path: string) => import("node:fs").Stats;
+    /** Test seams: before a removal starts, and right after its run-state check (before the claim). */
+    beforeRemove?: (fileName: string) => void;
+    afterCheck?: (fileName: string) => void;
+}): {
     removed: string[];
 };