toolroll 0.9.103 → 0.9.105

package/dist/live-detail.js

@@ -1,23 +1,9 @@
-/**
- * A project's "Show commands in the live view" (docs/plans/live-conversation.md):
- * whether a running agent's command text and command output are written to
- * its live conversation. Off unless an approver turned it on for the
- * project with their password; turning it off is one step. Every change is
- * an action-ledger line.
- *
- * Each run captures its answer once, before its live file opens
- * (run_live_detail, v136): what is off never reaches disk, a change applies
- * from the next run, and every reader withholds commands unless that run's
- * own captured answer is on (never the transcript's say, never the setting now).
- */
 import { createHash } from "node:crypto";
 import { captureRunLiveDetail } from "./store.js";
-/** The consent a "Show commands" form carries: a single-use nonce minted for this person and these exact terms. */
 export const LIVE_VIEW_CONSENT = "live-view";
 export function liveViewConsentDigest(repo) {
     return createHash("sha256").update(JSON.stringify(["live-view", repo, "commands-on"])).digest("hex");
 }
-/** Whether this project's live conversations show commands. Unknown or absent is off. */
 export function liveCommandsShown(store, repo) {
     if (repo === null)
         return false;
@@ -29,7 +15,6 @@ export function liveCommandsShown(store, repo) {
         return false;
     }
 }
-/** Save the setting and its ledger line in one transaction. The caller has proved who is asking (and, to turn it on, their password). */
 export function setLiveCommands(store, change, now) {
     store.transact(() => {
         store.handle
@@ -41,8 +26,6 @@ export function setLiveCommands(store, change, now) {
     });
     return { said: change.commands ? "Commands now show in the live view for this project, from the next run." : "Commands are hidden in the live view for this project, from the next run." };
 }
-/** A run's trusted context for its live file: its own checkout, and its project's setting, captured for the run now —
- * before the file opens. The writer uses the captured answer: a capture that fails writes no commands. */
 export function liveLogContext(store, runId, taskRef, worktree, now) {
     let repo = null;
     try {

package/dist/live-input.js

@@ -1,38 +1,7 @@
-/**
- * A Claude build's live input (live steering). The build runs with
- * `--input-format stream-json` and its stdin left open, so Toolroll can talk
- * to the session while it works instead of only through files it reads
- * between steps (checked on Claude Code 2.1.290):
- *
- * - The brief is the FIRST stdin message, a user frame with its own uuid. A
- *   `-p` prompt is silently dropped once stdin carries input, so the argv
- *   never carries the brief.
- * - A later user frame is taken up as soon as the current tool call ends,
- *   inside the turn that is running: it adds no result of its own.
- * - An interrupt control request stops the current turn within milliseconds
- *   and keeps the process; the next user frame continues the same session
- *   as a new turn. That is Pause; Resume is that next frame with only a
- *   short "continue". Stop is still the process-tree kill it always was.
- * - One process emits a result per turn, so the run ends when Toolroll
- *   closes stdin, not at the first result: after a turn ends with the
- *   handoff written or with nothing more owed, when the turn budget is
- *   spent, or when a paused session reaches the idle limit. `--max-turns`
- *   applies per user message, so the total is counted here. The idle
- *   watchdog stays the transport's own; a paused session only asks it to
- *   close stdin first (idleLimit), so the build settles from its handoff.
- *   closeReason tells settlement which ending Toolroll chose.
- *
- * Sending is never reading: a note written here still counts as read only
- * when the agent moves its file to handled/ (steer-mailbox.ts). Nothing here
- * touches the store; the builder's dispatcher records what happened.
- */
 import { randomUUID } from "node:crypto";
 import { primaryResultEvent, topLevelEvent } from "./stream-scope.js";
-/** What Resume sends a paused session: only a nudge to go on, never a note. */
 export const CONTINUE_TEXT = "continue";
-/** A stdin user frame, in the shape the harness reads. */
 export const userFrame = (text, uuid) => JSON.stringify({ type: "user", message: { role: "user", content: text }, uuid });
-/** A stdin interrupt: stop the current turn, keep the session. */
 export const interruptFrame = (requestId, cancelQueued = false) => JSON.stringify({ type: "control_request", request_id: requestId, request: { subtype: "interrupt", ...(cancelQueued ? { cancel_queued: true } : {}) } });
 export class LiveInput {
     maxTurns;
@@ -42,19 +11,16 @@ export class LiveInput {
     #begun = false;
     #closed = false;
     #turnActive = false;
-    /** A user frame was written while an interrupted turn had not yet ended: that frame's own turn is owed a result. */
     #owed = false;
     #paused = false;
     #interrupts = new Set();
     #turns = new Set();
     #closeReason = null;
-    /** The brief's frame uuid, once begun. */
     briefUuid = null;
     constructor(options) {
         this.#options = options;
         this.maxTurns = Math.max(1, Math.floor(options.maxTurns));
     }
-    /** Queue the brief as the first frame. Once, before the process is attached. */
     begin(brief, uuid = randomUUID()) {
         if (this.#begun)
             throw new Error("a live session's brief is sent once");
@@ -63,7 +29,6 @@ export class LiveInput {
         this.#turnActive = true;
         this.#write(userFrame(brief, uuid));
     }
-    /** The transport spawned the child with stdin piped: write what is queued, brief first. */
     attach(io) {
         if (this.#io !== null || this.#closed)
             return;
@@ -76,28 +41,20 @@ export class LiveInput {
         try {
             this.#options.onOpen?.();
         }
-        catch { /* display state never touches the session */ }
+        catch { }
     }
-    /** stdin is attached and still open: a note reaches the agent in seconds, and a Pause can stop its turn. */
     get open() {
         return this.#io !== null && !this.#closed;
     }
     get paused() {
         return this.#paused;
     }
-    /** Distinct assistant turns so far, across every message. */
     get turns() {
         return this.#turns.size;
     }
-    /** Why stdin closed, once it has. */
     get closeReason() {
         return this.#closeReason;
     }
-    /**
-     * Send a note (or anything the session should read next). A paused session continues. False once stdin is closed.
-     * Mid-turn, the harness folds it into the running turn; after an interrupt that turn is over, so the frame starts a
-     * turn of its own whose result is owed before stdin closes.
-     */
     send(text, uuid) {
         if (!this.open)
             return false;
@@ -109,7 +66,6 @@ export class LiveInput {
         this.#turnActive = true;
         return true;
     }
-    /** Resume a paused session with a short continue frame and no note. "not-paused" when nothing waits to go on. */
     resume(uuid) {
         if (!this.open)
             return "closed";
@@ -117,21 +73,12 @@ export class LiveInput {
             return "not-paused";
         return this.send(CONTINUE_TEXT, uuid) ? "sent" : "closed";
     }
-    /**
-     * The transport's idle limit was reached. A paused session closes stdin instead of being killed — the harness exits
-     * and the build settles from whatever handoff it saved — and true asks the watchdog to wait once more for that exit.
-     * Anything else is an ordinary idle timeout.
-     */
     idleLimit() {
         if (!this.open || !this.#paused)
             return false;
         this.close("paused-idle");
         return true;
     }
-    /**
-     * Pause: stop the current turn, keep the session. "sent" when an interrupt was written; "idle" when no turn was
-     * running (the session is already waiting, so it is paused as it stands); "closed" when stdin is gone.
-     */
     interrupt(requestId) {
         if (!this.open)
             return "closed";
@@ -143,10 +90,7 @@ export class LiveInput {
         this.#interrupts.add(requestId);
         return "sent";
     }
-    /** Every parsed stdout event, in order. */
     observe(event) {
-        // A subagent's events (parent_tool_use_id set) are never the session's: not its words, its control answers or its
-        // result (stream-scope.ts).
         if (!topLevelEvent(event))
             return;
         const type = String(event["type"] ?? "");
@@ -156,9 +100,6 @@ export class LiveInput {
             const id = typeof message?.["id"] === "string" ? message["id"] : `turn-${this.#turns.size + 1}`;
             this.#turns.add(id);
             if (this.#turns.size > this.maxTurns && this.open) {
-                // The total is spent once a turn past it starts: the last allowed turn ran in full, tools and all. Stop this
-                // one, then let the process finish on its own; settlement reads the handoff (closeReason).
-                // cancel_queued: a note already queued must not start a turn past the budget after stdin closes.
                 this.#write(interruptFrame(`budget-${randomUUID()}`, true));
                 this.close("turn-budget");
             }
@@ -173,11 +114,9 @@ export class LiveInput {
             this.#turnActive = false;
             this.#interrupts.clear();
             if (this.#paused) {
-                // A paused session waits for the next note; the idle watchdog still bounds the wait.
                 this.#notifyPaused();
                 return;
             }
-            // A frame written after this turn was interrupted starts a turn of its own: wait for its result.
             if (this.#owed) {
                 this.#owed = false;
                 return;
@@ -192,7 +131,6 @@ export class LiveInput {
             this.close(finished ? "finished" : "settled");
         }
     }
-    /** Close stdin: the harness finishes what it has and exits. Further sends refuse. */
     close(why) {
         if (this.#closed)
             return;
@@ -203,14 +141,13 @@ export class LiveInput {
             try {
                 this.#io.end();
             }
-            catch { /* already gone */ }
+            catch { }
         }
         try {
             this.#options.onClose?.(why);
         }
-        catch { /* display state never touches the session */ }
+        catch { }
     }
-    /** The process ended (or its stdin failed): nothing more is written. */
     detach(why = "ended") {
         const closedAlready = this.#closed;
         this.#closed = true;
@@ -222,14 +159,14 @@ export class LiveInput {
             try {
                 this.#options.onClose?.(why);
             }
-            catch { /* display state never touches the session */ }
+            catch { }
         }
     }
     #notifyPaused() {
         try {
             this.#options.onPaused?.();
         }
-        catch { /* display state never touches the session */ }
+        catch { }
     }
     #write(line) {
         if (this.#closed)

package/dist/live-main-read.js

@@ -1,11 +1,3 @@
-/**
- * Reading a run's own live file for the Agents view's tiles (docs/plans/agents-view.md §2.3, N1): through the checked
- * opener, one bounded window per request, from a sealed cursor — or, with none, from the start of a small file or
- * the last 256 KiB of a large one. The run's own file has no checkpoints (its format is unchanged), so a read that
- * starts mid-file can't know whether it starts inside a key block: it reads as if inside one until an END marker or
- * 64 KiB of text pass, and a line that can't be read puts it back in that state. Every record is re-checked and
- * re-redacted (live-records.ts parseLiveRecord) and read under the run's own captured "Show commands" answer.
- */
 import { closeSync } from "node:fs";
 import { withholdCommands } from "./live.js";
 import { CURSOR_CAP, openCursor, sealCursor, UNKNOWN_KEY_BYTES } from "./live-children-read.js";
@@ -24,7 +16,6 @@ function unseal(cursor, key, run, gen) {
         return null;
     return { run, gen, off: off, skipping, inKey, tail, unknown: unknown };
 }
-/** The bytes of text a record line carries (its words or output, as written): what uncertainty runs down by. */
 function rawText(line) {
     try {
         const record = JSON.parse(line);
@@ -35,7 +26,6 @@ function rawText(line) {
         return 0;
     }
 }
-/** One window of a run's own live file. `commands` is the run's own captured answer (store.ts runLiveCommands). */
 export function readMainWindow(root, runId, cursor, options) {
     const opened = openLiveTrusted(root, `${Math.trunc(runId)}.jsonl`);
     if (opened === "missing" || opened === "unavailable")
@@ -45,7 +35,6 @@ export function readMainWindow(root, runId, cursor, options) {
         const restarted = cursor !== null && (state === null || state.off > opened.size);
         let earlier = false;
         if (state === null || state.off > opened.size) {
-            // A small file from its start (its state is known there); a large one from its last 256 KiB, key state unknown.
             earlier = opened.size > SCAN_BUDGET;
             state = earlier
                 ? { run: runId, gen: opened.gen, off: opened.size - SCAN_BUDGET, skipping: true, inKey: false, tail: "", unknown: UNKNOWN_KEY_BYTES }
@@ -66,15 +55,13 @@ export function readMainWindow(root, runId, cursor, options) {
                 unknowable();
                 continue;
             }
-            // `inKey` is a block actually seen open (only a valid END ends it); `unknown` is uncertainty, which also runs
-            // down by the text the record actually carried.
             const observed = { inKey: state.inKey, tail: state.tail };
             parseLiveRecord(line.text, observed);
             state.inKey = keys.inKey ? observed.inKey : false;
             state.unknown = keys.inKey ? Math.max(0, state.unknown - rawText(line.text)) : 0;
             state.tail = keys.tail ?? "";
             if (parsed.k === "say" && parsed.t.length === 0)
-                continue; // all inside a key block
+                continue;
             records.push(...withholdCommands([parsed], options.commands));
         }
         state.off = read.next;

package/dist/live-notes.js

@@ -1,26 +1,14 @@
-/**
- * The steering notes that belong in one run's live conversation
- * (docs/plans/live-conversation.md §5): every note this run reached —
- * attached to its brief, mailed into its folder, or read by it, as kept in
- * steer_note_run when it happened — and, only while this run is the task's
- * live build, notes still waiting for it. A note never shows on a run it did
- * not reach, and is credited as read only to the run that read it.
- */
 import { steerStandingParts } from "./steer-status.js";
 export const RUN_NOTES_SHOWN = 20;
-/** Where a note stands as seen from this run. */
 function standingFor(note, run, live) {
     if (note.authorshipState === "verified" && note.supersededAt === null && note.deliveredAt === null && !live) {
-        // This run ended (or is not the one reading notes) without reading it: it waits for the next attempt.
         return { standing: "Not read in this attempt — the next one gets it", readAt: null };
     }
-    // Once read, a note's attached run is the run that read it (ackSteerNote, settleSteerDelivered).
     if (note.deliveredAt !== null && note.attachedRun !== run)
         return { standing: "Read in another attempt", readAt: null };
     const { words, readAt } = steerStandingParts(note, live);
     return { standing: words, readAt };
 }
-/** This run's notes, oldest first: the newest RUN_NOTES_SHOWN, and how many older ones the task page keeps. */
 export function runNotes(store, run, viewer, now) {
     const live = store.steeringLiveBuild(run.taskRef, now) === run.id;
     const reached = new Map(store.steerNotesReaching(run.id).filter(note => note.taskRef === run.taskRef).map(note => [note.id, note]));

package/dist/live-open.js

@@ -1,18 +1,3 @@
-/**
- * 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";
@@ -20,12 +5,10 @@ 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();
@@ -58,8 +41,6 @@ export function openLiveTrusted(root, name, seams = {}) {
         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");
@@ -72,11 +53,10 @@ export function openLiveTrusted(root, name, seams = {}) {
         try {
             closeSync(fd);
         }
-        catch { /* already */ }
+        catch { }
         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)
@@ -105,7 +85,6 @@ export function readLiveLines(fd, size, from, skipping = false) {
         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);) {
@@ -117,7 +96,6 @@ export function readLiveLines(fd, size, from, skipping = false) {
                 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 };
     }