toolroll 0.9.104 → 0.9.105

package/dist/live-records.js

@@ -1,24 +1,8 @@
-/**
- * The live conversation's records (docs/plans/live-conversation.md): what a
- * running agent said and did, one JSON object per line of `live/<run>.jsonl`.
- *
- * The recorder turns provider stream events into records. It names a step's
- * target only from a closed list of argument fields, keeps a command's text
- * and output only when the project turned "Show commands in the live view"
- * on (the `commands` tier), and never writes a tool's own name — only our
- * fixed kind. Every string is redacted, then cleaned of controls, then cut.
- * The redaction is best effort; the opt-in is the real control.
- *
- * Readers trust nothing they read back: `parseLiveRecord` re-checks shape,
- * caps and redaction, since the machine running the agent could alter the
- * file. Display state, never evidence.
- */
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { scanForSecrets } from "./evidence.js";
 import { topLevelEvent } from "./stream-scope.js";
 import { cleanTerminalLine } from "./terminal-text.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;
 const LINE_CAP = 2 * 1024;
 const COMMAND_CAP = 300;
@@ -26,7 +10,6 @@ const SHORT_CAP = 120;
 const OUT_LINES = 20;
 const OUT_BYTES = 4 * 1024;
 const OPEN_STEPS_CAP = 64;
-/** A `say` record is split before it grows past this many bytes or lines (the reader's own limits). */
 const SAY_CHUNK = 6 * 1024;
 const SAY_LINES = 400;
 export const HIDDEN_TARGET = "[hidden]";
@@ -34,12 +17,6 @@ export const HIDDEN_LINE = "[a line was hidden]";
 export const HIDDEN_KEY_BLOCK = "[a key block was hidden]";
 export const OUTSIDE_PROJECT = "a file outside the project";
 export const SOME_FILE = "a file";
-/* ---------- redaction and cleaning ---------- */
-/**
- * The live view's own shapes, beside the evidence scanner's high-confidence
- * ones: generic `key = value` credentials, auth headers, and URLs carrying
- * credentials. Over-hiding is the accepted cost here — this is a display.
- */
 const LIVE_SECRET_SHAPES = [
     /(?:^|[^A-Za-z0-9])[A-Za-z0-9_.-]*?(?:pass(?:word|wd)?|secret|token|api[_-]?key|authorization|auth|bearer|credentials?|private[_-]?key|session(?:[_-]?(?:id|key|token))?|cookie)["']?\s*[:=]\s*\S/i,
     /\bauthorization\s*:/i,
@@ -47,25 +24,20 @@ const LIVE_SECRET_SHAPES = [
     /\b[a-z][a-z0-9+.-]*:\/\/[^\s/@]+@/i,
     /[?&](?:access_token|token|key|api_key|apikey|secret|sig|signature|password|pwd|auth|code)=[^&\s]+/i,
 ];
-/** A line that is only a long run of mixed-case base64 — a key body whose BEGIN line was elsewhere (a hash is not). */
 function keyBodyShaped(line) {
     const bare = line.trim();
     return bare.length >= 24 && /^[A-Za-z0-9+/]+={0,2}$/.test(bare) && /[A-Z]/.test(bare) && /[a-z]/.test(bare) && /[0-9]/.test(bare);
 }
-/** Whether a line looks like it carries a credential (best effort). */
 export function liveSecretHit(line) {
     if (scanForSecrets(line).length > 0)
         return true;
     return keyBodyShaped(line) || LIVE_SECRET_SHAPES.some(shape => shape.test(line));
 }
-/** Controls, ANSI escapes and bidi overrides out; tabs to spaces (terminal-text.ts, the one sanitizer). */
 export function cleanLiveText(text) {
     return cleanTerminalLine(text);
 }
-/** Letters, digits and dashes only, after folding look-alike letters and dashes. */
 const reduceForm = (text) => text.normalize("NFKC").replace(/[\u2010-\u2015\u2212\u2E3A\u2E3B\uFE58\uFE63\uFF0D]/g, "-").toUpperCase().replace(/[^A-Z0-9-]/g, "");
 const CSI_ANY = /(?:\x1b\[|\u009b)[0-?]*[ -/]*[@-~]/g;
-/** The part of a line that only finishes the escape the previous line began: never shown, never text. */
 function finishEscape(line, carry) {
     if (carry === "C") {
         const done = /^[0-?]*[ -/]*[@-~]/.exec(line);
@@ -79,7 +51,6 @@ function finishEscape(line, carry) {
         return { rest: line.slice(1), carry: "" };
     return { rest: line, carry: "" };
 }
-/** Whether a line ends inside an escape the next line must finish. */
 function escapeLeftOpen(line) {
     if (/(?:\x1b\[|\u009b)[0-?]*[ -/]*$/.test(line))
         return "C";
@@ -87,11 +58,6 @@ function escapeLeftOpen(line) {
         return "O";
     return /\x1b$/.test(line) ? "E" : "";
 }
-/**
- * Where, in `text`, the escape `carry` left open at the end of what came before is over — read exactly as
- * cleanLiveText reads escapes — or null while it is still open. Words written after it are words; words written
- * inside it are cleaned away with it.
- */
 function escapeEnd(text, carry) {
     if (carry === "C") {
         const done = /^[0-?]*[ -/]*[@-~]/.exec(text);
@@ -110,7 +76,6 @@ function escapeEnd(text, carry) {
         return text[stop + 1] === "\\" ? stop + 2 : stop;
     }
     if (carry === "I") {
-        // ESC and intermediate bytes so far: the rest is more of them, then one final byte.
         const done = /^[ -/]*[0-~]/.exec(text);
         if (done !== null)
             return done[0].length;
@@ -130,23 +95,12 @@ function escapeEnd(text, carry) {
     }
     return 0;
 }
-/** The escape `text` ends inside, read as cleanLiveText reads escapes: escapeLeftOpen's, or ESC with intermediate
- * bytes ("I") that a final byte still has to finish. */
 function heldEscape(text) {
     const open = escapeLeftOpen(text);
     if (open !== "")
         return open;
     return /\x1b[ -/]+$/.test(text) ? "I" : "";
 }
-/**
- * The ways one line can be read when judging where a key block begins or
- * ends: exactly as it will be shown (cleaned, with the escape the previous
- * line left open finished first), with only colour sequences removed, and
- * raw with every escape's payload kept. A block opens if ANY reading shows a
- * BEGIN, and closes only if EVERY reading agrees it has ended — so a marker
- * hidden in, split by, or faked inside an escape never lets a key body
- * through. Over-hiding is the accepted cost.
- */
 const boundaryForms = (line, carry) => {
     const finished = finishEscape(line, carry).rest;
     return [
@@ -155,12 +109,7 @@ const boundaryForms = (line, carry) => {
         reduceForm(line),
     ];
 };
-/**
- * Every BEGIN and END marker in a line, in order. BEGIN counts with any label (or none); END only as a whole END line
- * — its label and closing dashes — so a header's own trailing dashes never read as one.
- */
 const KEY_MARKERS = /-{5}(BEGIN|END[A-Z0-9-]*?-{5})/g;
-/** Cut to at most `cap` UTF-8 bytes on a character boundary, "…" when cut. */
 export function capLive(text, cap) {
     if (Buffer.byteLength(text, "utf8") <= cap)
         return text;
@@ -175,14 +124,12 @@ export function capLive(text, cap) {
     }
     return `${out}…`;
 }
-/** One line for the view: redacted whole when it hits, then cleaned and cut. */
 export function liveLine(raw, cap = LINE_CAP) {
     const clean = cleanLiveText(raw);
     if (liveSecretHit(raw) || liveSecretHit(clean))
         return HIDDEN_LINE;
     return capLive(clean, cap);
 }
-/** A target: `[hidden]` when it hits, else cleaned and cut. Empty → null. */
 function liveTarget(raw, cap) {
     const clean = cleanLiveText(raw).trim();
     if (clean === "")
@@ -192,7 +139,6 @@ function liveTarget(raw, cap) {
     return capLive(clean, cap);
 }
 const BEGIN_WORD = "-----BEGIN";
-/** The longest end of `text` that starts "-----BEGIN" without completing it — all a split opener needs carried. */
 function beginPrefix(text) {
     for (let size = Math.min(text.length, BEGIN_WORD.length - 1); size > 0; size -= 1) {
         const end = text.slice(-size);
@@ -201,7 +147,6 @@ function beginPrefix(text) {
     }
     return "";
 }
-/** Whether a carried tail is one this code could have produced: three BEGIN prefixes and an escape flag, or nothing. */
 export function validKeyTail(tail) {
     if (tail === "")
         return true;
@@ -213,9 +158,6 @@ export function validKeyTail(tail) {
 export function redactLiveLines(lines, state = { inKey: false }) {
     const out = [];
     for (const line of lines) {
-        // Each reading is one stream across line breaks (and reads): markers are found in order wherever they are split,
-        // an END then a BEGIN on one line opens a block again, a block opens if ANY reading opens it and closes only if
-        // EVERY reading closes it.
         const startedInKey = state.inKey;
         const carried = validKeyTail(state.tail ?? "") && (state.tail ?? "") !== "" ? state.tail.split("|") : ["", "", "", ""];
         const escape = carried[3];
@@ -229,7 +171,6 @@ export function redactLiveLines(lines, state = { inKey: false }) {
                 const end = marker.index + marker[0].length;
                 if (end <= prefix.length)
                     continue;
-                // A BEGIN may be split across lines; an END counts only within this line.
                 if (marker[1] === "BEGIN") {
                     inKey = true;
                     opened = true;
@@ -245,7 +186,7 @@ export function redactLiveLines(lines, state = { inKey: false }) {
         state.tail = nextTails.join("|");
         state.inKey = stillIn;
         if (startedInKey)
-            continue; // a line inside a block is never shown, whatever it holds
+            continue;
         if (line === HIDDEN_KEY_BLOCK || line === HIDDEN_LINE) {
             out.push(line);
             continue;
@@ -258,11 +199,6 @@ export function redactLiveLines(lines, state = { inKey: false }) {
     }
     return out;
 }
-/**
- * Output for a command step: every line redacted first (a key block hidden
- * from its BEGIN line to its END, or to the end), then the last 20 lines
- * within 4 KiB — truncation never comes before redaction.
- */
 export function liveOutput(raw, keys = { inKey: false }) {
     const redacted = redactLiveLines(raw.split(/\r?\n/), keys);
     while (redacted.length > 0 && redacted[redacted.length - 1].trim() === "")
@@ -279,11 +215,6 @@ export function liveOutput(raw, keys = { inKey: false }) {
     }
     return kept;
 }
-/**
- * A target under the key-block rule: hidden while a block is open. A target is one argument (a search pattern, a
- * path), never part of the conversation's text, so it neither opens nor closes a block — searching for "-----BEGIN"
- * is a search, not a key — and a target that itself looks like a marker or a secret is hidden.
- */
 function keyedTarget(target, keys) {
     if (target === null || target === HIDDEN_TARGET)
         return target;
@@ -292,11 +223,6 @@ function keyedTarget(target, keys) {
     const [shown] = redactLiveLines([target], { ...keys });
     return shown === HIDDEN_KEY_BLOCK || shown === HIDDEN_LINE ? HIDDEN_TARGET : target;
 }
-/* ---------- targets ---------- */
-/**
- * A path as the view shows it: relative to the run's own checkout when it
- * lies inside it, judged lexically — nothing is opened or resolved on disk.
- */
 export function livePath(base, given) {
     if (typeof given !== "string" || given.trim() === "")
         return null;
@@ -308,12 +234,10 @@ export function livePath(base, given) {
         return OUTSIDE_PROJECT;
     return liveTarget(shown.split(sep).join("/"), LINE_CAP);
 }
-/** `bash -lc '…'` and friends, unwrapped for display only. */
 function unwrapShell(command) {
     const wrapped = /^(?:\/(?:usr\/)?bin\/)?(?:ba|z)?sh\s+-l?c\s+(['"])([\s\S]*)\1\s*$/.exec(command.trim());
     return wrapped === null ? command : wrapped[2];
 }
-/** A command's first line, "…" when more followed or it was cut. */
 export function liveCommand(given) {
     const text = Array.isArray(given) ? given.filter(one => typeof one === "string").join(" ") : given;
     if (typeof text !== "string")
@@ -328,7 +252,6 @@ export function liveCommand(given) {
         return first;
     return lines.length > 1 && !first.endsWith("…") ? `${first} …` : first;
 }
-/** A URL's host only: no scheme, userinfo, port, path or query. */
 function liveHost(given) {
     if (typeof given !== "string")
         return null;
@@ -341,9 +264,7 @@ 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"],
     ["Bash", "command"], ["Read", "read"], ["LS", "read"], ["Glob", "search"], ["Grep", "search"],
@@ -375,7 +296,6 @@ function claudeTarget(name, input, base, commands) {
 }
 const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 const providerId = (value) => (typeof value === "string" && value !== "" && value.length <= 200 ? value : null);
-/** A Claude tool_result's text, whatever its shape. */
 function resultText(content) {
     if (typeof content === "string")
         return content;
@@ -388,14 +308,11 @@ function resultText(content) {
         .join("\n");
 }
 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 = given.keyState ?? { inKey: false };
-    /** Provider call id → our step, while it is open. */
     const open = new Map();
     const stamp = () => clock().toISOString();
     const closeAll = (at) => {
@@ -405,16 +322,15 @@ export function createLiveRecorder(given) {
     };
     const openStep = (at, call, kind, target) => {
         if (call !== null && open.has(call))
-            return []; // a duplicate open is ignored
+            return [];
         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 */ }
+        catch { }
         if (call === null)
             return [{ ...step, once: true }];
         if (open.size >= OPEN_STEPS_CAP)
@@ -442,7 +358,6 @@ export function createLiveRecorder(given) {
     };
     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.
         if (!topLevelEvent(event))
             return [];
         if (type === "system")
@@ -469,7 +384,7 @@ export function createLiveRecorder(given) {
                 const call = providerId(block["tool_use_id"]);
                 const step = call === null ? undefined : open.get(call);
                 if (step === undefined)
-                    continue; // a close for an unknown id is dropped
+                    continue;
                 open.delete(call);
                 const out = options.commands && step.kind === "command" ? liveOutput(resultText(block["content"]), keyState) : [];
                 records.push({ k: "done", at, id: step.id, ok: block["is_error"] !== true, ...(out.length > 0 ? { out } : {}) });
@@ -524,7 +439,6 @@ export function createLiveRecorder(given) {
             return [];
         const records = [];
         let step = call === null ? undefined : open.get(call);
-        // An item that completes without having started (a file change) opens and closes at once.
         if (step === undefined) {
             if (call === null || open.size >= OPEN_STEPS_CAP)
                 return openStep(at, null, kind, codexTarget(item));
@@ -538,7 +452,6 @@ export function createLiveRecorder(given) {
         records.push({ k: "done", at, id: step.id, ok: codexOk(item), ...(out.length > 0 ? { out } : {}) });
         return records;
     };
-    /** Gemini: whole messages and tool headlines, no targets, nothing to pair. */
     const gemini = (event, at) => {
         const type = event["type"];
         if (type === "init")
@@ -552,39 +465,18 @@ export function createLiveRecorder(given) {
         }
         return null;
     };
-    /**
-     * ACP (acp-client.ts; the runner hands each session update over as `{acp: update}`). The record format is the one
-     * every dialect writes: a tool call is held — bounded — until it has a target, starts running or ends, and is then
-     * shown once (OpenCode names its command only in a later update); the words of a message, which arrive in chunks,
-     * are shown when the message ends (a tool call, or the end of the run).
-     */
     const ACP_KINDS = { read: "read", edit: "edit", delete: "edit", move: "edit", search: "search", execute: "command", fetch: "lookup", think: "plan" };
     const ACP_HELD_CAP = 64;
-    /** A message's words are shown in one piece when it ends — or, past this many characters, in pieces as they come:
-     * every word passes the shared redaction in the order the agent wrote it, none is dropped unseen. */
     const ACP_WORDS_CAP = 16 * 1024;
-    /** A line with no end in sight is flushed whole past this (it is cut to a line's length on the way out anyway). */
     const ACP_LINE_HARD_CAP = 256 * 1024;
     const held = new Map();
-    /** The latest output an open command showed, already redacted when it arrived (a later update may carry none). */
     const outputs = new Map();
     let acpWords = "";
-    /** A step came between the held unfinished line and the words after it: they are joined with one space, so a token
-     * keeps the word boundary a scanner needs ("credentials ghp_…") and `key= value` still reads as one. */
     let acpSeparated = false;
-    /** The message the held words belong to, when the agent names it: a new id is a new message, and a word break. */
     let acpMessageId = null;
-    /** A new message began (its id changed) and its break isn't written yet: owed until it is, whatever chunks come. */
     let acpNewMessage = false;
-    /** Past the hard cap, the rest of that one line is not shown; each piece is still read for the key-block state, in
-     * order — the state itself carries a split BEGIN across pieces, and an END split across two simply keeps the block
-     * hidden (never the other way). Nothing is read twice. */
     let acpSkipping = false;
     const skipRead = (text) => { redactLiveLines([text], keyState); };
-    /** Before anything else is written, the message's complete lines are; a partial last line waits for its own end (a
-     * `key=` and its value are never split by an update arriving between them), or for the end of the run. */
-    /** A message's complete lines, said in order; its unfinished last line waits for its own end (or the run's): a line
-     * is only ever judged — for secrets, for key blocks — whole, as the agent wrote it. */
     const flushLines = (at) => {
         const cut = acpWords.lastIndexOf("\n");
         if (cut < 0)
@@ -593,19 +485,14 @@ export function createLiveRecorder(given) {
         acpWords = acpWords.slice(cut + 1);
         return whole.trim() === "" ? [] : say(at, whole);
     };
-    /** Everything left, at the end of the run. */
     const flushWords = (at) => {
         const words = acpWords;
         acpWords = "";
         return words.trim() === "" ? [] : say(at, words);
     };
-    /** Whether the message's unfinished line opens a key block it hasn't finished saying: until that line is judged,
-     * what comes between (a step's target) is hidden — never shown on the strength of a state not yet read. */
     const heldKeyOpen = () => {
         if (/BEGIN/i.test(cleanLiveText(acpWords).replace(/[^A-Za-z]/g, "")))
             return true;
-        // Read as redaction will read it — every reading, from the state carried so far — on a copy of that state: a block
-        // it would open, or an opener it has begun and not finished, hides the target.
         const probe = { inKey: keyState.inKey, ...(keyState.tail === undefined ? {} : { tail: keyState.tail }) };
         redactLiveLines(acpWords === "" ? [] : acpWords.split(/\r?\n/), probe);
         return probe.inKey || (probe.tail ?? "").split("|").slice(0, 3).some(prefix => prefix !== "");
@@ -618,15 +505,12 @@ export function createLiveRecorder(given) {
         const first = Array.isArray(update["locations"]) ? object(update["locations"][0]) : null;
         return first !== null && typeof first["path"] === "string" ? livePath(options.base, first["path"]) : before;
     };
-    /** An update's command output, redacted now — in stream order, through the shared key state — or null when it has none. */
     const acpOutput = (update) => {
         if (!options.commands || !Array.isArray(update["content"]))
             return null;
         const text = update["content"].map(object).filter(one => one !== null && one["type"] === "content")
             .map(one => object(one["content"])).filter(block => block !== null && block["type"] === "text" && typeof block["text"] === "string")
             .map(block => block["text"]).join("\n");
-        // ACP sends a call's whole output again with each update — a snapshot, not a stream: each is judged on its own,
-        // from a fresh key state, and never moves the message's (key bodies are hidden by their shape either way).
         return text === "" ? null : liveOutput(text, { inKey: false });
     };
     const acp = (update, at) => {
@@ -637,7 +521,6 @@ export function createLiveRecorder(given) {
                 return [];
             let text = content["text"];
             if (acpSkipping) {
-                // The rest of a line too long to show: read for the key state, never written, until it ends.
                 const end = text.indexOf("\n");
                 skipRead(end < 0 ? text : text.slice(0, end));
                 if (end < 0)
@@ -645,12 +528,7 @@ export function createLiveRecorder(given) {
                 acpSkipping = false;
                 text = text.slice(end + 1);
             }
-            // A step between two messages is a word break, always written: whatever the next chunk starts with (a CR, a BOM,
-            // an escape) may be cleaned away, and the break with it.
             const messageId = typeof update["messageId"] === "string" ? update["messageId"] : null;
-            // The agent's own word on what is one message wins: a new id is a break, owed until written; the same id
-            // cancels only the break a step implied (a tool's update arriving mid-sentence doesn't split `api_` from `key=`).
-            // With no id, a step is a break.
             if (messageId !== null && acpMessageId !== null) {
                 if (messageId !== acpMessageId)
                     acpNewMessage = true;
@@ -663,8 +541,6 @@ export function createLiveRecorder(given) {
                 if (acpWords === "" || acpWords.endsWith("\n"))
                     acpSeparated = acpNewMessage = false;
                 else {
-                    // The break goes where cleaning can't take it: after any escape the held words left open, once it is over
-                    // (written inside it, it would be cleaned away with it). Still open, the break waits for the next chunk.
                     const at = escapeEnd(text, heldEscape(acpWords));
                     if (at !== null) {
                         text = `${text.slice(0, at)} ${text.slice(at)}`;
@@ -675,8 +551,6 @@ export function createLiveRecorder(given) {
             acpWords += text;
             if (acpWords.length <= ACP_WORDS_CAP)
                 return [];
-            // Flushed only at a line's end, so nothing the redaction reads (a key block's BEGIN, a `key=` and its value) is
-            // ever split across two pieces; the partial last line waits for the rest of itself.
             const cut = acpWords.lastIndexOf("\n");
             if (cut >= 0) {
                 const whole = acpWords.slice(0, cut + 1);
@@ -685,21 +559,15 @@ export function createLiveRecorder(given) {
             }
             if (acpWords.length <= ACP_LINE_HARD_CAP)
                 return [];
-            // One line with no end in sight: it is not shown — said once — and its rest is only read.
             acpSkipping = true;
             skipRead(acpWords);
             acpWords = "";
             return [{ k: "cut", at }];
         }
-        // A tool call or a permission answer is where the agent's message ends: its words go first, whole. Any other
-        // update (usage, a plan, a mode) is not: only the message's complete lines go before it, so a line in progress —
-        // a `key=` and the value still to come — is never split by one.
-        // Anything else comes after the message's complete lines; an unfinished line waits for its end, whatever arrives.
         const records = flushLines(at);
         if (kind === "tool_call" || kind === "tool_call_update" || kind === "permission")
             acpSeparated = true;
         if (kind === "permission") {
-            // A request's title is free text (a command, a path anywhere): only the answer is shown.
             return [...records, ...openStep(at, null, "tool", update["granted"] === true ? "allowed once" : "refused")];
         }
         if (kind !== "tool_call" && kind !== "tool_call_update")
@@ -712,8 +580,6 @@ export function createLiveRecorder(given) {
         const shown = open.get(call);
         const before = held.get(call);
         const stepKind = typeof update["kind"] === "string" ? ACP_KINDS[update["kind"]] ?? "tool" : shown?.kind ?? before?.kind ?? "tool";
-        // Output is read (and so redacted, in order) whatever the call, but kept only for a call shown or held — bounded
-        // by them — so an untracked or overflowing call leaves nothing behind.
         const output = stepKind === "command" ? acpOutput(update) : null;
         if (output !== null && (shown !== undefined || before !== undefined || kind === "tool_call"))
             outputs.set(call, output);
@@ -745,12 +611,10 @@ export function createLiveRecorder(given) {
         }
         held.delete(call);
         const opened = openStep(at, call, stepKind, target);
-        // A step shown "once" (past the open-step cap) is never closed by id: nothing of it is kept.
         if (!open.has(call))
             outputs.delete(call);
         if (!ended)
             return [...records, ...opened];
-        // Shown and ended at once: a step and its result.
         const step = open.get(call);
         if (step === undefined) {
             outputs.delete(call);
@@ -797,20 +661,13 @@ export function createLiveRecorder(given) {
         },
     };
 }
-/** One record as its file line; an oversized one becomes `cut`. */
 export function serializeLiveRecord(record) {
     const line = JSON.stringify(record);
     return Buffer.byteLength(line, "utf8") <= LIVE_RECORD_CAP ? line : JSON.stringify({ k: "cut", at: record.at });
 }
-/* ---------- reading back ---------- */
 const KINDS = new Set(LIVE_ACTIVITY_KINDS);
 const STEP_ID = /^s[1-9][0-9]{0,8}$/;
 const strings = (value, max) => Array.isArray(value) && value.length <= max && value.every(one => typeof one === "string") ? value : null;
-/**
- * One file line back into a record, strictly: a known shape within its caps,
- * every string redacted and cleaned again. Anything else is null — skipped,
- * never shown raw.
- */
 export function parseLiveRecord(line, keys = { inKey: false }) {
     if (line === "" || Buffer.byteLength(line, "utf8") > LIVE_RECORD_CAP)
         return null;
@@ -863,7 +720,6 @@ export function parseLiveRecord(line, keys = { inKey: false }) {
             return null;
     }
 }
-/** Complete file lines (a window's text) into records; bad lines are skipped. */
 export function parseLiveRecords(text, keys = { inKey: false }) {
     const records = [];
     for (const line of text.split("\n")) {
@@ -873,7 +729,6 @@ export function parseLiveRecords(text, keys = { inKey: false }) {
     }
     return records;
 }
-/* ---------- the text projection ---------- */
 export const LIVE_CAP_WORDS = "[the live view stopped at its size cap — the run record continues]";
 export const LIVE_CUT_WORDS = "[a line was too long to show]";
 const TARGET_WORDS = {
@@ -900,13 +755,11 @@ export const LIVE_KIND_HEADLINES = {
     delegate: "→ delegating to a helper",
     tool: "→ using a tool",
 };
-/** A step's one line of words, with its target when it has one. */
 export function stepWords(step) {
     if (step.target === undefined || step.kind === "plan" || step.kind === "tool")
         return LIVE_KIND_HEADLINES[step.kind];
     return `${TARGET_WORDS[step.kind]} ${step.kind === "delegate" ? step.target : `\`${step.target}\``}`;
 }
-/** Records as the plain lines the run page and `toolroll peek` show. */
 export function projectLiveText(records) {
     const lines = [];
     for (const record of records) {

package/dist/live-reply.js

@@ -1,33 +1,13 @@
-/**
- * The shared live-reply core (docs/plans/responsive-chat.md §2): one lead turn's `LeadProgress` turned into text-only
- * views that every surface renders. Surfaces never read `LeadProgress` themselves.
- *
- *   queued → working (one status line) → writing (status + display-safe partial text) → closed (answered | failed | blocked)
- *
- * Nothing here is durable or authoritative: the saved thread message and its cards remain the record, and no view ever
- * carries a card, a button, an ask or an approval. A partial is the reply as written so far, cut back to what is
- * settled (never an unfinished word, code span, link or bold run), withheld while its tail could be the start of a
- * password or key, and shaped with the final reply's own presentation policy (presentation, not redaction).
- *
- * `createLiveSender` is the one sender per live surface message (§2.4): at most one request in flight, one pending
- * slot holding only the newest view, a generation that only grows, and `close()` — after which nothing more is sent,
- * and which resolves only once the request in flight has settled, so durable delivery can start strictly after it.
- */
 import { scanForSecrets } from "./evidence.js";
 import { shapeReply, shapeReplyPrefix } from "./reply-shape.js";
-/** The status line's fixed words (§2.3). A running tool reads as its own label plus "…". */
 export const LIVE_STATUS = {
     queued: "Waiting for your earlier messages…",
     thinking: "Thinking…",
     writing: "Writing…",
     repair: "Fixing the reply…",
     shorten: "Shortening the reply…",
-    /** A preview closed because text looked like a password or key; the turn itself may still answer. */
     held: "Working on it…",
 };
-/** One token that could still grow into a match of a secret family: a non-empty prefix of one of its openings, or the
- * whole opening followed by its body characters. Preceded by a non-word character or the start, as the detectors'
- * own word boundaries are. */
 function opening(leads, body) {
     const escape = (text) => text.replace(/[.*+?^${}()|[\]\\/-]/g, "\\$&");
     const alternatives = new Set();
@@ -38,17 +18,9 @@ function opening(leads, body) {
     }
     return `(?:${[...alternatives].join("|")})`;
 }
-/**
- * The start of every `SECRET_PATTERNS` family (evidence.ts), checked against the end of the text written so far:
- * while any matches, the partial is withheld. Single-token families look at the unfinished last token; the families
- * whose match spans spaces (a private-key header, an npm `_authToken = value`) look at the whole last line.
- */
 const SECRET_STARTS = [
-    // private-key: "-----BEGIN RSA PRIVATE KEY-----", partway. No start boundary: the complete detector has none either.
     /-{1,5}(?:B(?:E(?:G(?:I(?:N(?:[ \t][A-Z \t]*-{0,5})?)?)?)?)?)?$/,
-    // npm-auth-token: "_authToken = value", partway.
     new RegExp(String.raw `(?:^|[^A-Za-z0-9])${opening(["_authToken"], String.raw `[\s=]`)}\S*$`),
-    // aws-access-key, github-token, slack-token, openai-key, stripe-key, google-api-key, gitlab-token.
     new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["AKIA", "ASIA"], "[0-9A-Z]")}$`),
     new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["ghp_", "gho_", "ghu_", "ghs_", "ghr_", "github_pat_"], "[A-Za-z0-9_]")}$`),
     new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["xoxb-", "xoxa-", "xoxp-", "xoxr-", "xoxs-"], "[A-Za-z0-9-]")}$`),
@@ -56,23 +28,14 @@ const SECRET_STARTS = [
     new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["sk_live_", "sk_test_", "rk_live_", "rk_test_", "whsec_"], "[A-Za-z0-9]")}$`),
     new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["AIza"], "[0-9A-Za-z_-]")}$`),
     new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["glpat-"], "[A-Za-z0-9_-]")}$`),
-    // telegram-bot-token: "123456789:AA…".
     /(?:^|[^A-Za-z0-9_])\d+(?::(?:A(?:A[A-Za-z0-9_-]*)?)?)?$/,
-    // discord-bot-token: "M…24.…6.…27".
     /(?:^|[^A-Za-z0-9_])[MN][A-Za-z\d]*(?:\.[\w-]*(?:\.[\w-]*)?)?$/,
-    // password-in-url: "scheme://user:password@host", partway (a scheme and its colon are enough to wait).
     /(?:^|[^A-Za-z0-9+.-])[a-z][a-z0-9+.-]*:\S*$/i,
 ];
-/** Could the end of this text be the start of a password or key? Then nothing of it shows yet. */
 export function secretMayStart(text) {
     const lastLine = text.replace(/\r\n?/g, "\n").split("\n").at(-1) ?? "";
     return SECRET_STARTS.some(pattern => pattern.test(lastLine));
 }
-/**
- * What of a reply still being written is settled: everything before its last whitespace (the unfinished last word
- * stays out), then cut back before any code fence, code span, bold run or link that hasn't closed yet. Trailing
- * whitespace is trimmed.
- */
 export function settledText(raw) {
     const text = raw.replace(/\r\n?/g, "\n");
     let end = text.length;
@@ -132,23 +95,16 @@ export function settledText(raw) {
     const cut = Math.min(...[fence, code, bold, link].filter(at => at !== -1), shown.length);
     return shown.slice(0, cut).trimEnd();
 }
-/**
- * A partial as it may be shown: `blocked` when it holds a password or key (the preview closes), `withheld` while its
- * tail could still become one (show nothing new), else the settled text shaped for display. A step's finished text
- * (`final`, secret-checked whole by the engine) shows whole.
- */
 export function partialDisplay(raw, final, shape = {}) {
     if (scanForSecrets(raw).length > 0)
         return { kind: "blocked" };
     if (!final && secretMayStart(raw))
         return { kind: "withheld" };
     const text = final ? shapeReply(raw, shape) : shapeReplyPrefix(settledText(raw), shape);
-    // Shaping only relabels and removes; a secret in what it returns would mean it came from somewhere else. Never shown.
     if (scanForSecrets(text).length > 0)
         return { kind: "blocked" };
     return { kind: "shown", text };
 }
-/** One turn's live reply. `shape`: the owner's message (`asked`) and this app's origins, as the final reply is shaped. */
 export function createLiveReply(shape = {}, options = {}) {
     const steps = [];
     let queued = options.queued === true;
@@ -242,12 +198,6 @@ export function createLiveReply(shape = {}, options = {}) {
         tools: () => steps.map(step => step.calls.map(call => ({ ...call }))),
     };
 }
-/**
- * The serialized sender for one live surface message (§2.4). `standing` re-proves the viewer's right to see this turn
- * before every send (it may await; the close is re-checked after it). `spacingMs` is the least time between two sends,
- * read before each one (a surface widens it after the platform asks for a pause). A failed send drops that view:
- * previews are best effort.
- */
 export function createLiveSender(options) {
     const spacing = () => typeof options.spacingMs === "function" ? options.spacingMs() : options.spacingMs ?? 0;
     const now = options.now ?? Date.now;
@@ -277,7 +227,7 @@ export function createLiveSender(options) {
                 lastSent = now();
                 await options.send(next.view, next.generation);
             }
-            catch { /* best effort: this view is dropped */ }
+            catch { }
         })().finally(() => { inflight = null; pump(); });
     };
     return {