toolroll 0.5.0

package/dist/peek-cli.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `toolroll peek` — the terminal multiplexer over live agents.
+ *
+ * One pane per open run: its task, worker, role, stage word, elapsed
+ * clock, and the tail of its live transcript (the same per-run file the
+ * console's run page follows: text the agent said and the kind of tool it
+ * reached for — never file contents, never a command line, credential
+ * shapes redacted at write). Digits focus one pane, `a` shows all, `q`
+ * leaves. No dependency: the screen is the alternate buffer and a
+ * handful of escape sequences. `--tmux` opens a real tmux session with one
+ * window per run for people who live there. Outside a TTY (or with
+ * `--json`) it prints one snapshot and exits — the same data, an envelope.
+ *
+ * Read-only by construction: nothing here writes to the store or the
+ * files; a peek is a look.
+ */
+import type { Store } from "./store.js";
+export declare const PEEK_TAIL_LINES = 400;
+export type PeekPane = {
+    runId: number;
+    taskId: string;
+    title: string;
+    repo: string | null;
+    runner: string;
+    role: string;
+    provider: string;
+    model: string | null;
+    phase: string;
+    startedAt: string;
+    /** Tail of the live transcript, newest last. */
+    lines: string[];
+    /** Why the transcript is absent, when it is. */
+    transcript: "live" | "not-yet" | "replaced" | "unreadable";
+};
+type Tail = {
+    offset: number;
+    lines: string[];
+    state: PeekPane["transcript"];
+};
+/** Advance one run's tail from its offset; `replaced` resets visibly. */
+export declare function advanceTail(root: string, runId: number, tail: Tail): Tail;
+/** The stage word for a pane: the machine's own phase, or what precedes it. */
+export declare function stageWord(run: {
+    phase: string | null;
+    model: string | null;
+    providerStartedAt: string | null;
+}): string;
+export declare function elapsedWords(startedAt: string, now: Date): string;
+/** One snapshot of every live run — the envelope's body, and the TUI's first frame. */
+export declare function snapshotLiveRuns(store: Store, root: string, now: Date, tails?: Map<number, Tail>): PeekPane[];
+/**
+ * Compose one frame: panes stacked, each with a header and as many tail
+ * lines as its share of the rows allows; the focused pane takes the whole
+ * screen. Pure — the loop paints what this returns.
+ */
+export declare function composeFrame(panes: PeekPane[], size: {
+    columns: number;
+    rows: number;
+}, focus: number | null, now: Date): string;
+export type PeekIo = {
+    stdout: NodeJS.WriteStream & {
+        columns?: number;
+        rows?: number;
+    };
+    stdin: NodeJS.ReadStream & {
+        setRawMode?: (raw: boolean) => void;
+        isRaw?: boolean;
+    };
+};
+/**
+ * Follow live runs until `q` (or, watching one run, until it finishes).
+ * Resolves with the exit code.
+ */
+export declare function runPeek(store: Store, root: string, options: {
+    runId?: number;
+    io: PeekIo;
+    clock?: () => Date;
+    intervalMs?: number;
+}): Promise<number>;
+/**
+ * A real tmux session, one window per live run, each running `peek <run>`
+ * — for people who already live in tmux. The plane never becomes tmux's
+ * dependant: liveness stays in the store's leases, and this is a view.
+ */
+export declare function openInTmux(panes: readonly PeekPane[], command: readonly string[], run: (file: string, args: readonly string[]) => Promise<{
+    code: number;
+    stderr: string;
+}>, session?: string): Promise<{
+    ok: true;
+    windows: number;
+} | {
+    ok: false;
+    message: string;
+}>;
+/** Hand the terminal to tmux and wait for it to come back. */
+export declare function attachTmux(session?: string): Promise<number>;
+export {};

package/dist/peek-cli.js

@@ -0,0 +1,215 @@
+/**
+ * `toolroll peek` — the terminal multiplexer over live agents.
+ *
+ * One pane per open run: its task, worker, role, stage word, elapsed
+ * clock, and the tail of its live transcript (the same per-run file the
+ * console's run page follows: text the agent said and the kind of tool it
+ * reached for — never file contents, never a command line, credential
+ * shapes redacted at write). Digits focus one pane, `a` shows all, `q`
+ * leaves. No dependency: the screen is the alternate buffer and a
+ * handful of escape sequences. `--tmux` opens a real tmux session with one
+ * window per run for people who live there. Outside a TTY (or with
+ * `--json`) it prints one snapshot and exits — the same data, an envelope.
+ *
+ * Read-only by construction: nothing here writes to the store or the
+ * files; a peek is a look.
+ */
+import { spawn } from "node:child_process";
+import { readLiveWindow } from "./live.js";
+export const PEEK_TAIL_LINES = 400;
+const ESC = "\u001b";
+/** Advance one run's tail from its offset; `replaced` resets visibly. */
+export function advanceTail(root, runId, tail) {
+    const read = readLiveWindow(root, runId, tail.offset);
+    if (!read.ok) {
+        if (read.reason === "replaced")
+            return { offset: 0, lines: ["[the live view was replaced — starting over]"], state: "replaced" };
+        return { ...tail, state: read.reason === "missing" ? (tail.lines.length === 0 ? "not-yet" : tail.state) : "unreadable" };
+    }
+    if (read.text === "")
+        return { ...tail, state: tail.lines.length === 0 ? "not-yet" : "live" };
+    const fresh = read.text.split("\n").filter(one => one !== "");
+    const lines = [...tail.lines, ...fresh].slice(-PEEK_TAIL_LINES);
+    return { offset: read.nextOffset, lines, state: "live" };
+}
+/** The stage word for a pane: the machine's own phase, or what precedes it. */
+export function stageWord(run) {
+    if (run.phase !== null)
+        return run.phase.replace(/-/g, " ");
+    return run.providerStartedAt === null ? "preparing workspace" : "the agent is working";
+}
+export function elapsedWords(startedAt, now) {
+    const ms = Math.max(0, now.getTime() - new Date(startedAt).getTime());
+    const minutes = Math.floor(ms / 60_000);
+    const seconds = Math.floor((ms % 60_000) / 1000);
+    return minutes >= 60 ? `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m` : `${minutes}m${String(seconds).padStart(2, "0")}s`;
+}
+/** One snapshot of every live run — the envelope's body, and the TUI's first frame. */
+export function snapshotLiveRuns(store, root, now, tails = new Map()) {
+    const panes = [];
+    for (const run of store.liveRuns(now)) {
+        const previous = tails.get(run.id) ?? { offset: 0, lines: [], state: "not-yet" };
+        const tail = advanceTail(root, run.id, previous);
+        tails.set(run.id, tail);
+        panes.push({
+            runId: run.id,
+            taskId: run.taskId,
+            title: run.title,
+            repo: run.repo,
+            runner: run.runner,
+            role: run.role,
+            provider: run.provider,
+            model: run.model,
+            phase: stageWord(run),
+            startedAt: run.startedAt,
+            lines: tail.lines,
+            transcript: tail.state,
+        });
+    }
+    for (const id of [...tails.keys()]) {
+        if (!panes.some(one => one.runId === id))
+            tails.delete(id);
+    }
+    return panes;
+}
+// ---- the frame --------------------------------------------------------------
+function fit(text, width) {
+    const chars = [...text];
+    if (chars.length <= width)
+        return text + " ".repeat(width - chars.length);
+    return chars.slice(0, Math.max(0, width - 1)).join("") + "…";
+}
+function header(pane, index, now, width, focused) {
+    const left = `${index + 1} · #${pane.runId} ${pane.title}`;
+    const right = `${pane.runner} · ${pane.role} · ${pane.phase} · ${elapsedWords(pane.startedAt, now)}`;
+    const room = Math.max(0, width - [...right].length - 1);
+    const line = `${fit(left, room)} ${right}`;
+    return `${ESC}[7m${focused ? `${ESC}[1m` : ""}${fit(line, width)}${ESC}[0m`;
+}
+/**
+ * Compose one frame: panes stacked, each with a header and as many tail
+ * lines as its share of the rows allows; the focused pane takes the whole
+ * screen. Pure — the loop paints what this returns.
+ */
+export function composeFrame(panes, size, focus, now) {
+    const columns = Math.max(20, size.columns);
+    const rows = Math.max(4, size.rows);
+    const footer = `${ESC}[2m${fit(panes.length === 0 ? "no agent is working right now — q leaves" : `${panes.length} live · 1-${Math.min(9, panes.length)} focus · a all · q leaves`, columns)}${ESC}[0m`;
+    const shown = focus !== null && panes[focus] !== undefined ? [panes[focus]] : panes;
+    const out = [];
+    if (shown.length === 0) {
+        out.push(fit("", columns));
+        out.push(fit("  nothing to peek at: no run is open.", columns));
+        for (let i = out.length; i < rows - 1; i += 1)
+            out.push(fit("", columns));
+        out.push(footer);
+        return out.join("\n");
+    }
+    const body = rows - 1;
+    const share = Math.max(2, Math.floor(body / shown.length));
+    for (const [i, pane] of shown.entries()) {
+        const index = focus !== null && panes[focus] !== undefined ? focus : i;
+        const height = i === shown.length - 1 ? body - share * (shown.length - 1) : share;
+        out.push(header(pane, index, now, columns, focus !== null));
+        const lines = pane.lines.length === 0
+            ? [pane.transcript === "not-yet" ? "  (no transcript yet — the agent has not spoken)" : pane.transcript === "unreadable" ? "  (the live file could not be read)" : "  …"]
+            : pane.lines.slice(-(height - 1)).map(one => `  ${one}`);
+        for (let r = 0; r < height - 1; r += 1)
+            out.push(fit(lines[r] ?? "", columns));
+    }
+    while (out.length < rows - 1)
+        out.push(fit("", columns));
+    out.push(footer);
+    return out.slice(0, rows).join("\n");
+}
+/**
+ * Follow live runs until `q` (or, watching one run, until it finishes).
+ * Resolves with the exit code.
+ */
+export async function runPeek(store, root, options) {
+    const { io } = options;
+    const clock = options.clock ?? (() => new Date());
+    const tails = new Map();
+    let focus = null;
+    let stop = false;
+    let finishedWord = null;
+    const paint = () => {
+        const now = clock();
+        let panes = snapshotLiveRuns(store, root, now, tails);
+        if (options.runId !== undefined) {
+            panes = panes.filter(one => one.runId === options.runId);
+            if (panes.length === 0 && finishedWord === null) {
+                const run = store.getRun(options.runId);
+                finishedWord = run === null ? "no such run" : `run #${options.runId} finished: ${run.outcome ?? "?"}${run.reason === null ? "" : ` (${run.reason})`}`;
+                stop = true;
+            }
+        }
+        const size = { columns: io.stdout.columns ?? 100, rows: io.stdout.rows ?? 30 };
+        io.stdout.write(`${ESC}[H${composeFrame(panes, size, options.runId !== undefined ? null : focus, now)}`);
+    };
+    const wasRaw = io.stdin.isRaw === true;
+    io.stdout.write(`${ESC}[?1049h${ESC}[?25l${ESC}[2J`);
+    io.stdin.setRawMode?.(true);
+    io.stdin.resume();
+    const onKey = (chunk) => {
+        for (const ch of chunk.toString("utf8")) {
+            if (ch === "q" || ch === "\u0003")
+                stop = true;
+            else if (ch === "a")
+                focus = null;
+            else if (ch >= "1" && ch <= "9")
+                focus = Number(ch) - 1;
+        }
+    };
+    io.stdin.on("data", onKey);
+    const onResize = () => paint();
+    io.stdout.on("resize", onResize);
+    try {
+        paint();
+        while (!stop) {
+            await new Promise(resolve => setTimeout(resolve, options.intervalMs ?? 500));
+            paint();
+        }
+    }
+    finally {
+        io.stdin.removeListener("data", onKey);
+        io.stdout.removeListener("resize", onResize);
+        io.stdin.setRawMode?.(wasRaw);
+        io.stdin.pause();
+        io.stdout.write(`${ESC}[?25h${ESC}[?1049l`);
+        if (finishedWord !== null)
+            io.stdout.write(`${finishedWord}\n`);
+    }
+    return 0;
+}
+// ---- tmux -------------------------------------------------------------------
+/**
+ * A real tmux session, one window per live run, each running `peek <run>`
+ * — for people who already live in tmux. The plane never becomes tmux's
+ * dependant: liveness stays in the store's leases, and this is a view.
+ */
+export async function openInTmux(panes, command, run, session = "toolroll") {
+    if (panes.length === 0)
+        return { ok: false, message: "no run is open — nothing to open a window for" };
+    const probe = await run("tmux", ["-V"]);
+    if (probe.code !== 0)
+        return { ok: false, message: "tmux is not installed (or not on PATH) — `toolroll peek` without --tmux needs nothing" };
+    const shellWord = (part) => `'${part.replace(/'/g, "'\\''")}'`;
+    const commandFor = (runId) => [...command, "peek", String(runId)].map(shellWord).join(" ");
+    const [first, ...rest] = panes;
+    const made = await run("tmux", ["new-session", "-d", "-s", session, "-n", first.taskId, commandFor(first.runId)]);
+    if (made.code !== 0)
+        return { ok: false, message: `tmux new-session: ${made.stderr.trim() || "refused"} — a session named ${session} may already exist (\`tmux attach -t ${session}\`)` };
+    for (const pane of rest) {
+        await run("tmux", ["new-window", "-t", session, "-n", pane.taskId, commandFor(pane.runId)]);
+    }
+    return { ok: true, windows: panes.length };
+}
+/** Hand the terminal to tmux and wait for it to come back. */
+export function attachTmux(session = "toolroll") {
+    return new Promise(resolve => {
+        const child = spawn("tmux", ["attach", "-t", session], { stdio: "inherit" });
+        child.on("exit", code => resolve(code ?? 0));
+        child.on("error", () => resolve(1));
+    });
+}

package/dist/peek.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The live peek's NATIVE reader (attended finding 7, CRITICAL): the whole
+ * point of this module is what it does not do. No git invocation ever has
+ * the agent's worktree as its working tree; nothing here consults
+ * gitattributes, hooks, clean/process filters, or external diff drivers —
+ * the mechanisms finding 7 proved can execute repository-configured
+ * commands. Change detection is a git-blob sha1 computed IN PROCESS against
+ * the frozen base tree; the diff is a line-based Myers implemented here.
+ *
+ * Two layers, deliberately separated: the PURE core (sha1, diff, parsers,
+ * aggregation — bytes in, structures out) and ONE I/O function,
+ * observeWorktree — descriptor-DISCIPLINED, not descriptor-confined: Node
+ * has no openat, so traversal is by pathname and a same-UID attacker
+ * renaming ancestors mid-walk can misdirect it (round-3 finding 44 owns
+ * the honest disclosure). What IS held: files open O_NOFOLLOW|O_NONBLOCK
+ * and must fstat as regular files on the root's device before a byte is
+ * read; reads go through that descriptor, bounded to the accepted size,
+ * with growth re-checked after; directories must prove the root's device
+ * before descent; symlinks are never followed; `.git` is never entered;
+ * every cap is explicit; unreadable corners make the look PARTIAL rather
+ * than silently narrower. Guarding, caching, and serving stay with their
+ * owners (serve.ts).
+ */
+/** git's own blob identity: sha1 over "blob <len>\0" + bytes. Computing it
+ * here is what lets change detection never ask git about a working tree. */
+export declare function gitBlobSha1(bytes: Buffer): string;
+/** git's heuristic, near enough: a NUL in the first 8 KiB means binary —
+ * named on the page, never diffed. */
+export declare function looksBinary(bytes: Buffer): boolean;
+export type Hunk = {
+    aStart: number;
+    aLines: number;
+    bStart: number;
+    bLines: number;
+    /** Prefixed lines: " ctx", "-old", "+new" — exactly unified-diff shape. */
+    lines: string[];
+};
+/**
+ * Line-based Myers (the O(ND) greedy walk), bounded by the caller's caps —
+ * inputs beyond the byte caps never reach here. Returns unified hunks with
+ * three lines of context, or null when the edit distance exceeds `maxD`
+ * (a rewrite is not usefully rendered as a diff — the caller says so).
+ */
+export declare function diffLines(aText: string, bText: string, maxD?: number): Hunk[] | null;
+/** Render hunks as a unified patch body for one file, capped in bytes.
+ * The cap drops the incomplete final line (finding 9), and says so. */
+export declare function renderUnified(path: string, hunks: Hunk[], capBytes: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * New-file readability WITHOUT suppression (round-1 finding 19: ignore
+ * parsing is gone — a pattern match can HIDE a name, and patterns are
+ * agent-influencable). Aggregation only: a first path segment holding more
+ * than `groupAt` new files collapses to one row stating its exact count;
+ * everything else lists; the row cap saturates with exact totals. No name
+ * is ever dropped silently — the numbers always add up.
+ */
+export type NewFileRow = {
+    label: string;
+    count: number;
+    collapsed: boolean;
+};
+export declare function aggregateNewNames(paths: readonly string[], groupAt?: number, rowCap?: number): {
+    rows: NewFileRow[];
+    total: number;
+    renderedFiles: number;
+};
+/**
+ * The base-tree snapshot parser (round-1 finding 15's demands, applied to
+ * OUR OWN format anyway): every entry is proved shaped before use —
+ * relative path with no dot-dot/backslash/control bytes, a known mode,
+ * a 40-hex sha, a bounded non-negative size. Anything else refuses the
+ * whole snapshot; a partial base is not a base.
+ */
+export type BaseTreeEntry = {
+    path: string;
+    mode: string;
+    sha: string;
+    size: number;
+};
+/**
+ * The enveloped snapshot document (round-2 finding 26): entries alone are
+ * not a snapshot — the envelope binds schema version, repository, run, and
+ * the exact base OID, and the CONSUMER (not readVerifiedArtifact) proves
+ * those against the run row plus capture_status/truncated before any walk.
+ */
+export type BaseTreeSnapshot = {
+    repo: string;
+    run: number;
+    base: string;
+    entries: BaseTreeEntry[];
+};
+export declare function encodeBaseTreeSnapshot(snapshot: BaseTreeSnapshot): string;
+export declare function parseBaseTreeSnapshot(json: string, entryCap?: number): BaseTreeSnapshot | null;
+export declare function parseBaseTree(json: string, entryCap?: number): BaseTreeEntry[] | null;
+export type PeekLimits = {
+    /** Walk abandons past this many entries — a typed refusal, not a guess. */
+    maxEntries: number;
+    /** Combined cap across changed+deleted+unchecked rows (finding 38). */
+    maxRows: number;
+    /** Files larger than this are compared by size only, and say so. */
+    maxFileBytes: number;
+    /** Total bytes hashed per observation; past it, remaining files go unverified. */
+    maxHashedBytes: number;
+    /** Wall budget, checked between files — over it, a partial look, never a hang. */
+    deadlineMs: number;
+};
+export declare const PEEK_LIMITS: PeekLimits;
+export type PeekRow = {
+    kind: "changed" | "deleted" | "unchecked";
+    path: string;
+    detail: string;
+};
+export type Observation = {
+    ok: true;
+    rows: PeekRow[];
+    newPaths: string[];
+    /** Non-null when the look is partial, saying why in plain words. */
+    partial: string | null;
+    scanned: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * One best-effort observation of a working tree against its frozen base
+ * (v2 brief §2). Descriptor-confined throughout: directories via opendir
+ * handles, files via O_NOFOLLOW descriptors, sizes from fstat on the OPEN
+ * descriptor (never a path-racy stat), bytes hashed through the same
+ * descriptor. Symlinks are typed by lstat-equivalent dirent info and never
+ * opened. Nothing here writes, spawns, or evaluates anything.
+ */
+export declare function observeWorktree(root: string, base: readonly BaseTreeEntry[], limits?: PeekLimits): Promise<Observation>;