toolroll 0.9.60 → 0.9.61

package/dist/agent-pulse.js

@@ -0,0 +1,214 @@
+/**
+ * The Agents board on the build's existing minute pulse (agent-board.ts):
+ * the agent's status file, the live transcript's size, the changed-file
+ * count and the four-minute Stuck mark. No model and no tokens: files the
+ * plane already owns, read with the same discipline as every protocol file.
+ *
+ * The status file is the agent's: one JSON object per line, appended.
+ *   {"status":"working","note":"…"}
+ *   {"status":"needs-decision","key":"short-key","question":"…"}
+ *   {"status":"blocked","note":"…"}
+ *   {"status":"done","note":"…"}
+ * It is read forward from a saved offset, only through complete lines, never
+ * past its caps, opened O_NOFOLLOW as a regular file; a line that is not one
+ * of these shapes is skipped, and every word goes through the live view's
+ * sanitizer (a credential-shaped line is replaced whole).
+ */
+import { closeSync, constants, fstatSync, openSync, readSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ingestStatus, markStuck, noteDiff, noteTranscript, NOTE_MAX, pageQuestions, QUESTION_KEY, QUESTION_MAX, QUESTIONS_OPEN_MAX, QUESTIONS_PER_ATTEMPT } from "./agent-board.js";
+import { readVerifiedArtifact } from "./evidence.js";
+import { liveLogPath, sanitizeTranscriptLine } from "./live.js";
+import { observeWorktree, parseBaseTreeSnapshot, PEEK_LIMITS } from "./peek.js";
+/** The whole file may grow this far; past it, nothing more is read. */
+export const STATUS_FILE_CAP = 256 * 1024;
+/** At most this much is read per beat. */
+const STATUS_WINDOW = 64 * 1024;
+/** A line longer than this is skipped, never cut. */
+const STATUS_LINE_CAP = 4 * 1024;
+const clean = (value, cap) => {
+    if (typeof value !== "string")
+        return null;
+    const one = sanitizeTranscriptLine(value.replace(/\s+/g, " ").trim());
+    if (one === "")
+        return null;
+    return one.length > cap ? `${one.slice(0, cap - 1).trimEnd()}…` : one;
+};
+/** One status line, strictly: a known status and its fields, or null. */
+export function parseStatusLine(line) {
+    if (line.trim() === "" || Buffer.byteLength(line, "utf8") > STATUS_LINE_CAP)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    const status = record["status"];
+    if (status === "needs-decision") {
+        const key = typeof record["key"] === "string" ? record["key"].trim().toLowerCase() : "";
+        const question = clean(record["question"], QUESTION_MAX);
+        return QUESTION_KEY.test(key) && question !== null ? { status, key, question } : null;
+    }
+    if (status === "working" || status === "blocked" || status === "done")
+        return { status, note: clean(record["note"], NOTE_MAX) };
+    return null;
+}
+/** The complete lines after `from`, and where the next read starts. */
+export function readStatusFile(path, from) {
+    if (!Number.isSafeInteger(from) || from < 0)
+        return { ok: false, reason: "unreadable" };
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        return { ok: false, reason: error.code === "ENOENT" ? "missing" : "unreadable" };
+    }
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            return { ok: false, reason: "unreadable" };
+        const size = Math.min(Number(stat.size), STATUS_FILE_CAP);
+        if (Number(stat.size) < from)
+            return { ok: false, reason: "replaced" };
+        if (from >= STATUS_FILE_CAP)
+            return { ok: false, reason: "full" };
+        const want = Math.min(size - from, STATUS_WINDOW);
+        if (want <= 0)
+            return { ok: true, read: { lines: [], nextOffset: from } };
+        const buffer = Buffer.alloc(want);
+        let got = 0;
+        while (got < want) {
+            const read = readSync(fd, buffer, got, want - got, from + got);
+            if (read <= 0)
+                break;
+            got += read;
+        }
+        const chunk = buffer.subarray(0, got);
+        const lastLf = chunk.lastIndexOf(0x0a);
+        if (lastLf === -1) {
+            // One line longer than the whole window is never going to parse: step past it.
+            return { ok: true, read: { lines: [], nextOffset: got >= STATUS_WINDOW ? from + got : from } };
+        }
+        const lines = chunk.subarray(0, lastLf).toString("utf8").split("\n").map(parseStatusLine).filter((one) => one !== null);
+        return { ok: true, read: { lines, nextOffset: from + lastLf + 1 } };
+    }
+    catch {
+        return { ok: false, reason: "unreadable" };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Create the attempt's empty status file (created here, never adopted); null when it cannot be. */
+export function openStatusFile(worktree, name) {
+    const path = join(worktree, name);
+    try {
+        writeFileSync(path, "", { flag: "wx", mode: 0o600 });
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+export function removeStatusFile(path) {
+    if (path === null)
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch { /* already gone */ }
+}
+/** The brief's few lines: where to write, what each status means, and how a reply arrives. */
+export function statusBrief(name, steerFolder) {
+    return [
+        "",
+        "Status for the person watching (the Agents board):",
+        `- Append one JSON object per line to ${name} in the worktree root. Never rewrite or delete it; it is never committed.`,
+        '  {"status":"working","note":"<what you are doing, one short line>"}',
+        '  {"status":"needs-decision","key":"<short-key>","question":"<one question a person must answer>"}',
+        '  {"status":"blocked","note":"<what stops you>"}',
+        '  {"status":"done","note":"<one-line outcome>"}',
+        "- Use needs-decision only for a real judgement call inside the agreed scope; a key is lowercase letters, digits and",
+        "  hyphens, at most 40 characters, and is asked once. Keep working on anything that does not depend on the answer.",
+        `- At most ${QUESTIONS_OPEN_MAX} questions can be open at once, and ${QUESTIONS_PER_ATTEMPT} in all; any more reach no one.`,
+        steerFolder === null
+            ? "- A reply cannot reach this attempt while it runs; if the answer is required to finish, park instead."
+            : `- A reply arrives as a note in ${steerFolder}/ that begins 'Reply to your question "<short-key>"'.`,
+        "",
+    ].join("\n");
+}
+/** The run's verified base snapshot, as the live peek reads it; null when it was not captured cleanly. */
+export function baseEntriesOf(store, root, run) {
+    const artifact = store.artifactsFor(run).find(one => one.kind === "base-tree");
+    if (artifact === undefined || artifact.captureStatus !== "ok" || artifact.truncated)
+        return null;
+    const read = readVerifiedArtifact(root, artifact);
+    if (!read.ok)
+        return null;
+    const snapshot = parseBaseTreeSnapshot(read.content.toString("utf8"));
+    return snapshot === null || snapshot.run !== run ? null : snapshot.entries;
+}
+/** What a look at the checkout found: changed, deleted and new files together; null when it could not look. */
+export async function changedFileCount(worktree, base) {
+    const seen = await observeWorktree(worktree, base, { ...PEEK_LIMITS, deadlineMs: 1_500 });
+    if (!seen.ok)
+        return null;
+    return seen.rows.filter(one => one.kind === "changed" || one.kind === "deleted").length + seen.newPaths.length;
+}
+/**
+ * One beat for the board. Each part is its own fail-soft step: a status file
+ * that cannot be read, or a checkout that cannot be looked at, costs only
+ * its own line on the board, never the build.
+ */
+export function pulseAgentBoard(store, state, now) {
+    try {
+        const bytes = statSync(liveLogPath(state.root, state.run)).size;
+        noteTranscript(store, state.run, state.attemptKey, bytes, now);
+    }
+    catch { /* no live log: the activity row still counts */ }
+    if (state.status !== null) {
+        try {
+            const from = store.handle.prepare("SELECT status_offset FROM agent_now WHERE run = ? AND attempt_key = ?").get(state.run, state.attemptKey);
+            if (from !== undefined) {
+                const read = readStatusFile(state.status, Number(from["status_offset"] ?? 0));
+                if (read.ok)
+                    ingestStatus(store, state.run, state.attemptKey, read.read, now);
+            }
+        }
+        catch { /* the next beat reads from the same offset */ }
+        // Questions asked inside the page window go out once it ends, with or without a new line.
+        try {
+            pageQuestions(store, state.run, state.attemptKey, now);
+        }
+        catch { /* the next beat */ }
+    }
+    try {
+        markStuck(store, state.run, state.attemptKey, now);
+    }
+    catch { /* the next beat */ }
+    if (state.looking)
+        return;
+    if (state.base === undefined) {
+        try {
+            state.base = baseEntriesOf(store, state.root, state.run);
+        }
+        catch {
+            state.base = null;
+        }
+    }
+    const base = state.base;
+    if (base === null)
+        return;
+    state.looking = true;
+    void changedFileCount(state.worktree, base)
+        .then(count => { if (count !== null)
+        noteDiff(store, state.run, state.attemptKey, count, now); })
+        .catch(() => { })
+        .finally(() => { state.looking = false; });
+}

package/dist/agent-turns.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Live turn states from the agent's own output stream (Agents board): no
+ * hooks, no model. The builder already parses Claude stream-json and Codex
+ * --json events for the live log; this reads the same events for three facts:
+ *
+ * - busy: a session, turn or tool call started (or the agent is mid-turn);
+ * - idle: the turn's result arrived (success or not, it is a result);
+ * - crashed: the process ended while a turn was still open — no result.
+ *
+ * Each change is recorded once, under the run's attempt key
+ * (agent-board.ts decides whether it may move the current snapshot).
+ * The same events say which tool calls are open — a Claude tool_use until its
+ * tool_result, a Codex command or tool item until it completes — so a long,
+ * silent command is not mistaken for a stuck agent. Only those known shapes
+ * count, at most OPEN_TOOLS_CAP at once, and a turn result or the process
+ * ending closes them all.
+ * Fail-soft: a recording that throws never touches the build.
+ */
+import type { AgentTurn, ToolKind } from "./agent-board.js";
+type Observer = {
+    observe(event: Record<string, unknown>): void;
+    close(): void;
+};
+/** What one stream event says about the turn; null when it says nothing. */
+export declare function turnSignalOf(event: Record<string, unknown>): Exclude<AgentTurn, "crashed"> | null;
+/** At most this many open calls are tracked; past it, a new one is not (the oldest still holds the long threshold). */
+export declare const OPEN_TOOLS_CAP = 64;
+/** The tool calls one stream event opens and closes, by id: only Claude's and Codex's known shapes. */
+export declare function toolCallsOf(event: Record<string, unknown>): {
+    opened: {
+        id: string;
+        kind: ToolKind;
+    }[];
+    closed: string[];
+};
+export type OpenTool = {
+    kind: ToolKind;
+    at: Date;
+} | null;
+export type TurnRecorder = Observer & {
+    /** The agent process is gone: a turn still open ended without its result. */
+    ended(): void;
+    /** The last state recorded (null: nothing yet). */
+    readonly state: AgentTurn | null;
+};
+/**
+ * Watch a run's stream for turn changes, beside its live log (which may be
+ * null), and for the oldest tool call still open (recordTool hears it move;
+ * a turn that leaves busy closes them all, and its own record clears them).
+ */
+export declare function withAgentTurns(inner: Observer | null, record: (state: AgentTurn, at: Date) => void, clock: () => Date, recordTool?: (open: OpenTool, at: Date) => void): TurnRecorder;
+export {};

package/dist/agent-turns.js

@@ -0,0 +1,137 @@
+/** What one stream event says about the turn; null when it says nothing. */
+export function turnSignalOf(event) {
+    const type = typeof event["type"] === "string" ? event["type"] : "";
+    switch (type) {
+        // Claude stream-json: the session starts, the assistant speaks or calls a tool, a tool answers; then one result.
+        case "system": return event["subtype"] === "init" ? "busy" : null;
+        case "assistant":
+        case "user": return "busy";
+        case "result": return "idle";
+        // Codex --json: a thread and its turns start, items run; a turn completes or fails.
+        case "thread.started":
+        case "turn.started":
+        case "item.started":
+        case "item.updated":
+        case "item.completed": return "busy";
+        case "turn.completed":
+        case "turn.failed": return "idle";
+        // Gemini stream-json, which the same live log reads.
+        case "init":
+        case "tool_use":
+        case "tool_call":
+        case "message": return "busy";
+        default: return null;
+    }
+}
+/** At most this many open calls are tracked; past it, a new one is not (the oldest still holds the long threshold). */
+export const OPEN_TOOLS_CAP = 64;
+const CODEX_TOOL_ITEMS = new Map([["command_execution", "command"], ["mcp_tool_call", "tool"], ["web_search", "tool"], ["file_change", "tool"]]);
+const COMMAND_TOOLS = new Set(["Bash", "BashOutput"]);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+const callId = (value) => typeof value === "string" && value !== "" && value.length <= 200 ? value : null;
+/** The tool calls one stream event opens and closes, by id: only Claude's and Codex's known shapes. */
+export function toolCallsOf(event) {
+    const opened = [], closed = [];
+    const type = event["type"];
+    if (type === "assistant" || type === "user") {
+        const content = object(event["message"])?.["content"];
+        for (const part of Array.isArray(content) ? content : []) {
+            const block = object(part);
+            if (block === null)
+                continue;
+            if (type === "assistant" && block["type"] === "tool_use") {
+                const id = callId(block["id"]);
+                if (id !== null)
+                    opened.push({ id, kind: COMMAND_TOOLS.has(String(block["name"])) ? "command" : "tool" });
+            }
+            else if (type === "user" && block["type"] === "tool_result") {
+                const id = callId(block["tool_use_id"]);
+                if (id !== null)
+                    closed.push(id);
+            }
+        }
+    }
+    else if (type === "item.started" || type === "item.completed") {
+        const item = object(event["item"]);
+        const id = callId(item?.["id"]), kind = CODEX_TOOL_ITEMS.get(item?.["type"]);
+        if (id !== null && kind !== undefined)
+            (type === "item.started" ? opened.push({ id, kind }) : closed.push(id));
+    }
+    return { opened, closed };
+}
+/**
+ * Watch a run's stream for turn changes, beside its live log (which may be
+ * null), and for the oldest tool call still open (recordTool hears it move;
+ * a turn that leaves busy closes them all, and its own record clears them).
+ */
+export function withAgentTurns(inner, record, clock, recordTool = () => { }) {
+    let state = null;
+    let spoke = false;
+    const open = new Map();
+    let oldest = null;
+    const move = (next) => {
+        if (next === state)
+            return;
+        state = next;
+        if (next !== "busy") {
+            open.clear();
+            oldest = null;
+        }
+        try {
+            record(next, clock());
+        }
+        catch { /* display state: the next change tries again */ }
+    };
+    const tools = (event) => {
+        const calls = toolCallsOf(event);
+        if (calls.opened.length === 0 && calls.closed.length === 0)
+            return;
+        const at = clock();
+        for (const id of calls.closed)
+            open.delete(id);
+        for (const one of calls.opened)
+            if (!open.has(one.id) && open.size < OPEN_TOOLS_CAP)
+                open.set(one.id, { kind: one.kind, at });
+        const first = open.values().next().value ?? null;
+        if (first === oldest)
+            return;
+        oldest = first;
+        try {
+            recordTool(first, at);
+        }
+        catch { /* display state: the next change tries again */ }
+    };
+    return {
+        observe(event) {
+            inner?.observe(event);
+            if (state === "crashed")
+                return;
+            let signal = null;
+            try {
+                signal = turnSignalOf(event);
+            }
+            catch {
+                signal = null;
+            }
+            if (signal === null)
+                return;
+            spoke = true;
+            move(signal);
+            if (signal === "busy") {
+                try {
+                    tools(event);
+                }
+                catch { /* an unreadable call: the turn's result closes it */ }
+            }
+        },
+        close() { inner?.close(); },
+        ended() {
+            if (state === "crashed")
+                return;
+            // A process that never spoke, or whose last turn never reported its result, ended without one.
+            if (!spoke || state !== "idle")
+                move("crashed");
+        },
+        get state() { return state; },
+    };
+}

package/dist/agents-board.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The Agents board's projection (one place to check on running agents): each
+ * task's newest build attempt from the last day, in the viewer's admitted
+ * projects, grouped Needs you, Working, Stuck, Done (not viewed yet), Idle.
+ * A protocol repair never takes the row: while one runs, its parent's row says
+ * "Fixing the handoff" and keeps the parent's transcript, changes and link.
+ * Saved facts only (agent-board.ts, the run, its activity and its sealed diff
+ * stats); nothing here verifies evidence or grants an action.
+ */
+import { type AgentTurn, type ToolKind } from "./agent-board.js";
+import type { AgentGroupKey, BrowserAgentRow } from "./browser-workspace.js";
+import type { Store } from "./store.js";
+export declare const AGENT_GROUPS: readonly {
+    key: AgentGroupKey;
+    label: string;
+}[];
+export type AgentFacts = {
+    runId: number;
+    taskRef: number;
+    taskId: string;
+    title: string;
+    repo: string | null;
+    provider: string;
+    runner: string;
+    outcome: string | null;
+    reason: string | null;
+    startedAt: string;
+    finishedAt: string | null;
+    legacy: boolean;
+    taskState: string;
+    turn: AgentTurn | null;
+    stateAt: string | null;
+    transcriptAt: string | null;
+    stuckAt: string | null;
+    said: string | null;
+    saidNote: string | null;
+    saidAt: string | null;
+    diffFiles: number | null;
+    toolKind: ToolKind | null;
+    toolAt: string | null;
+    phase: string | null;
+    /** The note the board shows once the agent asked past the questions cap. */
+    questionNote: string | null;
+    /** A protocol repair of this attempt is running now. */
+    repairing: boolean;
+    question: {
+        id: number;
+        key: string;
+        text: string;
+    } | null;
+    seen: boolean;
+};
+/**
+ * The board's candidate builds, through the partial indexes (agent_board_open, agent_board_recent): open ones and
+ * those finished since $kept, one per task (its newest), never a scan of every run. A candidate a newer build of the
+ * same task has replaced is dropped by an indexed probe, so the row is still the task's newest build.
+ */
+export declare const BOARD_CANDIDATES = "WITH candidate AS (\n    SELECT task_ref, id FROM run WHERE role = 'builder' AND outcome IS NULL\n    UNION ALL\n    SELECT task_ref, id FROM run WHERE role = 'builder' AND outcome IS NOT NULL AND finished_at >= $kept\n  ), newest AS (SELECT task_ref, MAX(id) AS id FROM candidate GROUP BY task_ref)";
+/** The board's candidate attempts: each task's newest build, open or recently finished, in the admitted projects. */
+export declare function agentFacts(store: Store, now: Date, access: {
+    repos: readonly string[] | null;
+}, account: string): AgentFacts[];
+/** The board's query, exported for its query-plan test. */
+export declare function agentFactsSql(): string;
+/** One exact build attempt, whatever its age (the opened row), in the admitted projects: a repair opens as its parent. */
+export declare function agentFactsFor(store: Store, run: number, access: {
+    repos: readonly string[] | null;
+}, account: string): AgentFacts | null;
+/** Where an attempt sits on the board, and its one state word. Stuck is worked out from the facts now, so fresh
+ * transcript or activity clears it at once (the pulse's saved mark only tells open boards it crossed). */
+export declare function agentGroupOf(facts: AgentFacts, activityAt: string | null, now: Date): {
+    group: AgentGroupKey;
+    label: string;
+};
+type DiffSummary = {
+    fileCount: number;
+    additions: number;
+    deletions: number;
+    files: {
+        path: string;
+        additions: number | null;
+        deletions: number | null;
+    }[];
+};
+/** A finished attempt's sealed diff stats (cached by artifact: sealed bytes never change). */
+export declare function sealedDiffOf(store: Store, root: string | undefined, run: number): DiffSummary | null;
+/** A row's diff size: the sealed stats once finished, the pulse's count while it runs. */
+export declare function diffWords(facts: AgentFacts, diff: DiffSummary | null): string | null;
+/** One board row. */
+export declare function agentRowOf(store: Store, facts: AgentFacts, now: Date, root?: string): BrowserAgentRow;
+/** The whole board: groups in order, rows newest first within each; empty groups dropped. */
+export declare function agentsBoardOf(store: Store, now: Date, access: {
+    repos: readonly string[] | null;
+}, account: string, root?: string): {
+    key: AgentGroupKey;
+    label: string;
+    rows: BrowserAgentRow[];
+}[];
+/** A board fingerprint for one exact build: what its open view shows moved, its repairs included. */
+export declare function agentRunFingerprint(store: Store, run: number): string | null;
+export {};