toolroll 0.5.0

package/dist/live.js

@@ -0,0 +1,366 @@
+/**
+ * The live window (arc 1): what the running agent is saying, on disk, for
+ * the run page to poll — and NOTHING else.
+ *
+ * This file is display state, not evidence. No artifact row points at it,
+ * no digest binds it, and the page that renders it says so: the machine
+ * running the agent could alter it. It exists so a person can watch work
+ * happen without a terminal, and every byte in it went through the same
+ * sanitize discipline as the peek: controls stripped, credential-shaped
+ * lines replaced whole, tool activity described in OUR fixed vocabulary —
+ * event metadata is never echoed.
+ *
+ * Fail-soft everywhere: a live view that cannot be written must never
+ * break, slow, or reclassify a build.
+ */
+import { closeSync, constants, fstatSync, mkdirSync, openSync, readSync, readdirSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { scanForSecrets } from "./evidence.js";
+export const LIVE_LINE_CAP = 2 * 1024;
+export const LIVE_FILE_CAP = 2 * 1024 * 1024;
+export const LIVE_CAP_MARKER = "[the live view stopped at its size cap — the run record continues]";
+export const LIVE_REDACTED_LINE = "[a credential-shaped line was redacted]";
+/** Finalized runs keep their live file this long for the final drain. */
+export const LIVE_RETAIN_MS = 24 * 60 * 60 * 1000;
+/** The bounded sweep: at most this many FINALIZED files survive a pass. */
+export const LIVE_FILE_BOUND = 500;
+export function liveDir(root) {
+    return join(root, "live");
+}
+/** The exact filename, from the numeric id and nothing else — no user
+ * input is ever parsed into this path. */
+export function liveLogPath(root, runId) {
+    return join(liveDir(root), `${Math.trunc(runId)}.log`);
+}
+/**
+ * The fixed tool-headline vocabulary. Known harness tools map to OUR
+ * phrases; anything unrecognized gets the generic line. The tool's own
+ * name, arguments, and metadata never reach the file: a tool named after
+ * a secret stays unspoken.
+ */
+const TOOL_HEADLINES = new Map([
+    ["Edit", "→ editing files"],
+    ["Write", "→ editing files"],
+    ["MultiEdit", "→ editing files"],
+    ["NotebookEdit", "→ editing files"],
+    ["Bash", "→ running a command"],
+    ["Read", "→ reading the code"],
+    ["Glob", "→ searching the code"],
+    ["Grep", "→ searching the code"],
+    ["LS", "→ reading the code"],
+    ["WebFetch", "→ looking something up"],
+    ["WebSearch", "→ looking something up"],
+    ["TodoWrite", "→ organizing its plan"],
+    ["Task", "→ delegating to a helper"],
+]);
+const TOOL_HEADLINE_GENERIC = "→ using a tool";
+/** Strip ANSI escapes and every control character; tabs become spaces. */
+function stripControls(text) {
+    return text
+        .replace(/\x1b\[[0-9;?]*[ -\/]*[@-~]/g, "")
+        .replace(/\t/g, " ")
+        .replace(/[\x00-\x1f\x7f-\x9f]/g, "");
+}
+/** Cut a string to at most `cap` UTF-8 bytes without splitting a character. */
+function capBytes(text, cap) {
+    if (Buffer.byteLength(text, "utf8") <= cap)
+        return text;
+    const bytes = Buffer.from(text, "utf8").subarray(0, cap);
+    const decoded = bytes.toString("utf8");
+    // A cut mid-character decodes with a trailing replacement char — drop it.
+    return decoded.endsWith("�") ? decoded.slice(0, -1) : decoded;
+}
+/**
+ * One stream event → zero or more display lines, in the fixed vocabulary.
+ * Assistant TEXT is the agent's own words (sanitized below); tool use is a
+ * headline; everything else — tool results, deltas, results, subagent
+ * chatter — renders nothing in v1.
+ */
+export function renderTranscriptLines(event) {
+    const type = String(event["type"] ?? "");
+    if (type === "system" && String(event["subtype"] ?? "") === "init") {
+        return ["the agent session started"];
+    }
+    // Codex-shaped streams (peek): a thread starts, items complete.
+    if (type === "thread.started")
+        return ["the agent session started"];
+    if (type === "item.completed") {
+        const item = event["item"];
+        const kind = item === undefined ? "" : String(item["type"] ?? "");
+        if (kind === "agent_message") {
+            const text = item?.["text"];
+            return typeof text === "string" ? text.split("\n").filter(one => one.trim() !== "") : [];
+        }
+        if (kind === "command_execution")
+            return ["→ running a command"];
+        if (kind === "file_change")
+            return ["→ editing files"];
+        if (kind === "web_search")
+            return ["→ looking something up"];
+        return [];
+    }
+    // Gemini-shaped streams (peek): whole assistant messages, never deltas.
+    if (type === "init")
+        return ["the agent session started"];
+    if (type === "message" && String(event["role"] ?? "") === "assistant" && event["delta"] !== true) {
+        const content = event["content"];
+        return typeof content === "string" ? content.split("\n").filter(one => one.trim() !== "") : [];
+    }
+    if (type === "tool_call" || type === "tool_use") {
+        const name = event["name"] ?? event["tool"]?.["name"];
+        return [TOOL_HEADLINES.get(typeof name === "string" ? name : "") ?? TOOL_HEADLINE_GENERIC];
+    }
+    if (type !== "assistant")
+        return [];
+    // Top-level only: a subagent's words are not this run's transcript.
+    const parent = event["parent_tool_use_id"];
+    if (parent !== undefined && parent !== null)
+        return [];
+    const message = event["message"];
+    const content = message?.["content"];
+    if (!Array.isArray(content))
+        return [];
+    const lines = [];
+    for (const block of content) {
+        if (block === null || typeof block !== "object")
+            continue;
+        const kind = String(block["type"] ?? "");
+        if (kind === "text") {
+            const text = block["text"];
+            if (typeof text === "string" && text.trim() !== "") {
+                for (const one of text.split("\n")) {
+                    if (one.trim() !== "")
+                        lines.push(one);
+                }
+            }
+        }
+        else if (kind === "tool_use") {
+            const name = block["name"];
+            lines.push(TOOL_HEADLINES.get(typeof name === "string" ? name : "") ?? TOOL_HEADLINE_GENERIC);
+        }
+    }
+    return lines;
+}
+/** Sanitize one display line: strip, redact whole on any secret hit, cap. */
+export function sanitizeTranscriptLine(line) {
+    const stripped = stripControls(line);
+    if (scanForSecrets(stripped).length > 0)
+        return LIVE_REDACTED_LINE;
+    return capBytes(stripped, LIVE_LINE_CAP);
+}
+/**
+ * Open the run's live file for appending. The directory is 0700, the file
+ * 0600 and CREATED HERE (O_EXCL: a name that already exists — whatever put
+ * it there — is refused, not appended to), opened O_NOFOLLOW with the
+ * descriptor retained for the run's whole duration. Returns null on any
+ * failure: no live view is ever worth a build.
+ */
+export function openLiveLog(root, runId) {
+    let fd;
+    try {
+        mkdirSync(liveDir(root), { recursive: true, mode: 0o700 });
+        fd = openSync(liveLogPath(root, runId), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_APPEND | constants.O_NOFOLLOW, 0o600);
+    }
+    catch {
+        return null;
+    }
+    let written = 0;
+    let capped = false;
+    let closed = false;
+    const append = (line) => {
+        if (closed || capped)
+            return;
+        const payload = Buffer.from(`${line}\n`, "utf8");
+        // The marker is RESERVED inside the cap: whatever remains must still fit it.
+        const markerBytes = Buffer.byteLength(`${LIVE_CAP_MARKER}\n`, "utf8");
+        if (written + payload.length + markerBytes > LIVE_FILE_CAP) {
+            capped = true;
+            try {
+                writeSync(fd, `${LIVE_CAP_MARKER}\n`);
+            }
+            catch {
+                // Nothing to do: the file simply ends early.
+            }
+            return;
+        }
+        try {
+            writeSync(fd, payload);
+            written += payload.length;
+        }
+        catch {
+            closed = true; // a broken descriptor never breaks the run
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // already gone
+            }
+        }
+    };
+    return {
+        observe(event) {
+            try {
+                for (const line of renderTranscriptLines(event)) {
+                    append(sanitizeTranscriptLine(line));
+                }
+            }
+            catch {
+                // Rendering is observational; a malformed event renders nothing.
+            }
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // already gone
+            }
+        },
+    };
+}
+const READ_WINDOW = 64 * 1024;
+const READ_LOOKAHEAD = 2 * 1024;
+/**
+ * Read the live file from a byte offset, returning only COMPLETE lines
+ * (through the last LF in the window). The descriptor is the authority:
+ * opened O_NOFOLLOW, proved a regular file, measured and read through
+ * itself. A file smaller than the offset was replaced — the caller resets,
+ * visibly, never silently duplicating (arc 1 §4). `allowTail` (the final
+ * drain) returns the unterminated tail after finalization.
+ */
+export function readLiveWindow(root, runId, from, allowTail = false) {
+    if (!Number.isSafeInteger(from) || from < 0)
+        return { ok: false, reason: "unreadable" };
+    let fd;
+    try {
+        fd = openSync(liveLogPath(root, runId), constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    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 = Number(stat.size);
+        if (size < from)
+            return { ok: false, reason: "replaced" };
+        const want = Math.min(size - from, READ_WINDOW + READ_LOOKAHEAD);
+        const buffer = Buffer.alloc(want);
+        let offset = 0;
+        while (offset < want) {
+            const read = readSync(fd, buffer, offset, want - offset, from + offset);
+            if (read <= 0)
+                break;
+            offset += read;
+        }
+        const chunk = buffer.subarray(0, offset);
+        const lastLf = chunk.lastIndexOf(0x0a);
+        const eofReached = from + offset >= size;
+        if (lastLf === -1) {
+            if (allowTail && eofReached && offset > 0) {
+                return { ok: true, text: chunk.toString("utf8"), nextOffset: from + offset, eof: true };
+            }
+            return { ok: true, text: "", nextOffset: from, eof: eofReached && offset === 0 };
+        }
+        if (allowTail && eofReached && lastLf + 1 < offset) {
+            return { ok: true, text: chunk.toString("utf8"), nextOffset: from + offset, eof: true };
+        }
+        const complete = chunk.subarray(0, lastLf + 1);
+        return { ok: true, text: complete.toString("utf8"), nextOffset: from + lastLf + 1, eof: from + lastLf + 1 >= size };
+    }
+    catch {
+        return { ok: false, reason: "unreadable" };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * 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).
+ */
+export function listLiveFiles(root) {
+    let names;
+    try {
+        names = readdirSync(liveDir(root));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        let mtimeMs = 0;
+        try {
+            mtimeMs = statSync(join(liveDir(root), name)).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        const match = /^(\d{1,15})\.log$/.exec(name);
+        out.push({ runId: match === null ? null : Number(match[1]), fileName: name, mtimeMs });
+    }
+    return out;
+}
+/** Remove one live file, silently: a sweep never throws over display state. */
+export function removeLiveFile(root, fileName) {
+    // The name comes from listLiveFiles' own readdir, never from user input.
+    if (fileName.includes("/") || fileName.includes("\\") || fileName.includes(".."))
+        return;
+    try {
+        unlinkSync(join(liveDir(root), fileName));
+    }
+    catch {
+        // already gone
+    }
+}
+/**
+ * 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.
+ */
+export function sweepLiveLogs(store, root, now) {
+    const removed = [];
+    const removable = [];
+    for (const entry of listLiveFiles(root)) {
+        if (entry.runId !== null) {
+            const run = store.getRun(entry.runId);
+            if (run !== null && run.outcome === null)
+                continue; // live: untouchable
+            const finished = run?.finishedAt === null || run?.finishedAt === undefined ? null : Date.parse(run.finishedAt);
+            removable.push({
+                fileName: entry.fileName,
+                ageAnchorMs: finished === null || Number.isNaN(finished) ? entry.mtimeMs : finished,
+            });
+        }
+        else {
+            removable.push({ fileName: entry.fileName, ageAnchorMs: entry.mtimeMs });
+        }
+    }
+    removable.sort((a, b) => a.ageAnchorMs - b.ageAnchorMs);
+    const cutoff = now.getTime() - LIVE_RETAIN_MS;
+    const survivors = [];
+    for (const one of removable) {
+        if (one.ageAnchorMs <= cutoff) {
+            removeLiveFile(root, one.fileName);
+            removed.push(one.fileName);
+        }
+        else {
+            survivors.push(one);
+        }
+    }
+    // Oldest-first beyond the bound — still never touching an active run.
+    for (let index = 0; index < survivors.length - LIVE_FILE_BOUND; index += 1) {
+        const one = survivors[index];
+        removeLiveFile(root, one.fileName);
+        removed.push(one.fileName);
+    }
+    return { removed };
+}

package/dist/liveness.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Attended-liveness semantics (Parity II Phase 1, S3) — the ONE definition
+ * every attended feature consumes. A browser proves presence only by
+ * RENEWING a heartbeat; absence is inferred only from renewal ceasing,
+ * never from observing a tab close (which is not reliably observable).
+ * Renewal can extend nothing past an absolute expiry and can never mint
+ * or broaden authority — it only keeps an already-signed authorization
+ * usable (strategy rulings 1c/12).
+ *
+ * The state contract, exact (spec finding 11/18):
+ * - "expired" iff now >= absoluteExpiryAt — checked FIRST; renewal is
+ *   irrelevant past the absolute wall.
+ * - a null beat (never renewed) is "lapsed".
+ * - a FUTURE beat is "lapsed": strict means strict — a clock that claims
+ *   tomorrow proves nothing about presence now.
+ * - "live"  iff now - lastBeatAt <= 20s (one 15s beat + 5s jitter).
+ * - "grace" iff now - lastBeatAt <= 45s (one missed beat, forgiven —
+ *   background-tab throttling survives grace, not live).
+ * - otherwise "lapsed".
+ *
+ * Session COOKIE lifetimes (12h idle / 7d absolute in serve.ts) are a
+ * different thing and are untouched by all of this.
+ */
+export declare const BEAT_MS = 15000;
+/** live = one beat plus jitter. */
+export declare const LIVE_MS = 20000;
+/** grace = one whole missed beat beyond live, forgiven. */
+export declare const GRACE_MS = 45000;
+export type AttendedLiveness = "live" | "grace" | "lapsed" | "expired";
+export declare function attendedLivenessState(lastBeatAt: number | null, now: number, absoluteExpiryAt: number): AttendedLiveness;

package/dist/liveness.js

@@ -0,0 +1,42 @@
+/**
+ * Attended-liveness semantics (Parity II Phase 1, S3) — the ONE definition
+ * every attended feature consumes. A browser proves presence only by
+ * RENEWING a heartbeat; absence is inferred only from renewal ceasing,
+ * never from observing a tab close (which is not reliably observable).
+ * Renewal can extend nothing past an absolute expiry and can never mint
+ * or broaden authority — it only keeps an already-signed authorization
+ * usable (strategy rulings 1c/12).
+ *
+ * The state contract, exact (spec finding 11/18):
+ * - "expired" iff now >= absoluteExpiryAt — checked FIRST; renewal is
+ *   irrelevant past the absolute wall.
+ * - a null beat (never renewed) is "lapsed".
+ * - a FUTURE beat is "lapsed": strict means strict — a clock that claims
+ *   tomorrow proves nothing about presence now.
+ * - "live"  iff now - lastBeatAt <= 20s (one 15s beat + 5s jitter).
+ * - "grace" iff now - lastBeatAt <= 45s (one missed beat, forgiven —
+ *   background-tab throttling survives grace, not live).
+ * - otherwise "lapsed".
+ *
+ * Session COOKIE lifetimes (12h idle / 7d absolute in serve.ts) are a
+ * different thing and are untouched by all of this.
+ */
+export const BEAT_MS = 15_000;
+/** live = one beat plus jitter. */
+export const LIVE_MS = 20_000;
+/** grace = one whole missed beat beyond live, forgiven. */
+export const GRACE_MS = 45_000;
+export function attendedLivenessState(lastBeatAt, now, absoluteExpiryAt) {
+    if (now >= absoluteExpiryAt)
+        return "expired";
+    if (lastBeatAt === null)
+        return "lapsed";
+    if (lastBeatAt > now)
+        return "lapsed";
+    const age = now - lastBeatAt;
+    if (age <= LIVE_MS)
+        return "live";
+    if (age <= GRACE_MS)
+        return "grace";
+    return "lapsed";
+}

package/dist/log.d.ts

@@ -0,0 +1,7 @@
+export type LogLevel = "info" | "warn" | "error";
+export type LogFields = Record<string, string | number | boolean | null | undefined>;
+export declare function formatLogLine(level: LogLevel, event: string, fields: LogFields, now: Date, json: boolean): string;
+export declare function logEvent(level: LogLevel, event: string, fields?: LogFields, options?: {
+    now?: Date;
+    write?: (line: string) => void;
+}): void;

package/dist/log.js

@@ -0,0 +1,25 @@
+/**
+ * One line per event on stderr (v99), where the service manager keeps the
+ * log. Plain by default ("2026-09-27T17:00:00.000Z error serve.error path=/x
+ * error=…"); with TOOLROLL_LOG_FORMAT=json, one JSON object per line
+ * for a log shipper. Fields are facts about the event, never a request body,
+ * a password or a token; values are cut to 500 characters and key-shaped text
+ * is blanked.
+ */
+import { scanForSecrets } from "./evidence.js";
+import { envValue } from "./names.js";
+const clean = (value) => {
+    const cut = value.replace(/[\u0000-\u001f\u007f]+/g, " ").slice(0, 500);
+    return scanForSecrets(cut).length > 0 ? "[redacted: key-shaped text]" : cut;
+};
+export function formatLogLine(level, event, fields, now, json) {
+    const facts = Object.entries(fields).filter((entry) => entry[1] !== undefined)
+        .map(([key, value]) => [key, typeof value === "string" ? clean(value) : value]);
+    if (json)
+        return JSON.stringify({ at: now.toISOString(), level, event, ...Object.fromEntries(facts) });
+    return [now.toISOString(), level, event, ...facts.map(([key, value]) => `${key}=${typeof value === "string" && /\s/.test(value) ? JSON.stringify(value) : String(value)}`)].join(" ");
+}
+export function logEvent(level, event, fields = {}, options = {}) {
+    const line = formatLogLine(level, event, fields, options.now ?? new Date(), envValue(process.env, "LOG_FORMAT") === "json");
+    (options.write ?? (text => process.stderr.write(text)))(`${line}\n`);
+}

package/dist/mailbox.d.ts

@@ -0,0 +1,57 @@
+export type MailboxAccess = {
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    password?: string;
+    accessToken?: string;
+};
+export type InboundMail = {
+    uid: number;
+    messageId: string | null;
+    inReplyTo: string | null;
+    references: string[];
+    from: string;
+    fromName: string | null;
+    subject: string;
+    text: string;
+    automatic: boolean;
+};
+/** Where a folder stands: its UIDVALIDITY and the last UID seen. */
+export type MailCursor = {
+    validity: string;
+    uid: number;
+};
+/** `at` is where the next read starts; `more` says mail is still waiting past it. */
+export type MailRead = {
+    ok: true;
+    at: MailCursor;
+    mails: InboundMail[];
+    renumbered: boolean;
+    more: boolean;
+} | {
+    ok: false;
+    said: string;
+    permanent: boolean;
+};
+export type MailReader = (access: MailboxAccess, folder: string, after: MailCursor | null, limit: number) => Promise<MailRead>;
+export declare function mailCursorOf(text: string | null): MailCursor | null;
+export declare const mailCursorText: (at: MailCursor) => string;
+/** Whether Inbox triggers can read mail: a connected Google account, or a mail server with its IMAP address. */
+export declare function mailboxReady(dir: string | null): boolean;
+/** The mailbox to read, signed in: Google when connected, else the mail server's IMAP. */
+export declare function mailboxAccess(dir: string | null, fetcher: typeof fetch): Promise<{
+    ok: true;
+    access: MailboxAccess;
+    address: string;
+} | {
+    ok: false;
+    said: string;
+    permanent: boolean;
+}>;
+/** The new part of a message: no quoted earlier messages, no signature, tidy lines. */
+export declare function freshText(text: string): string;
+/** One raw message as plain words, and whether a machine sent it. */
+export declare function readMail(uid: number, source: Buffer | string): Promise<InboundMail>;
+/** The production reader: one read-only IMAP visit. */
+export declare const readThroughImap: MailReader;