toolroll 0.9.62 → 0.9.65

package/dist/live-bus.d.ts

@@ -85,6 +85,7 @@ export declare class LiveConnection {
     private readonly proofs;
     private readonly timer;
     private closed;
+    private refusing;
     constructor(response: ServerResponse, options?: {
         limitBytes?: number;
         keepAliveMs?: number;
@@ -95,6 +96,10 @@ export declare class LiveConnection {
     get open(): boolean;
     /** An event for one room: its data says which. */
     send(room: string, event: string, data?: Record<string, unknown>): void;
+    /** A room leaves because its proof failed (a sign-out, a revoked or narrowed account): if that departure ends the
+     * connection, the page is told the stream `ended` and stops, rather than reconnecting at once into a request that
+     * can't sign in. Any other close — the page going, a later shutdown, an overflow — says nothing of it. */
+    refuse(leave: () => void): void;
     /** Run when the connection ends; returns the undo for a room that leaves first. */
     onClose(leave: () => void): () => void;
     close(): void;
@@ -120,6 +125,9 @@ export type LiveRoomOptions = {
     bus?: LiveBus | null;
     safetyNetMs?: number;
     minIntervalMs?: number;
+    /** A room whose read is costly reads at most once per this window after a signal; every viewer is still re-proved
+     * the moment a signal arrives (and again at the read). */
+    readSettleMs?: number;
 };
 /**
  * Rooms of open pages that hear the bus. `presence` says who else is here, as

package/dist/live-bus.js

@@ -201,6 +201,7 @@ export class LiveConnection {
     proofs = new Set();
     timer;
     closed = false;
+    refusing = false;
     constructor(response, options = {}) {
         this.response = response;
         this.stream = new LiveStream(response, options.limitBytes, () => this.close());
@@ -222,6 +223,19 @@ export class LiveConnection {
     get open() { return !this.closed && this.stream.open; }
     /** An event for one room: its data says which. */
     send(room, event, data = {}) { this.stream.send(event, { room, ...data }); }
+    /** A room leaves because its proof failed (a sign-out, a revoked or narrowed account): if that departure ends the
+     * connection, the page is told the stream `ended` and stops, rather than reconnecting at once into a request that
+     * can't sign in. Any other close — the page going, a later shutdown, an overflow — says nothing of it. */
+    refuse(leave) {
+        const outer = this.refusing;
+        this.refusing = true;
+        try {
+            leave();
+        }
+        finally {
+            this.refusing = outer;
+        }
+    }
     /** Run when the connection ends; returns the undo for a room that leaves first. */
     onClose(leave) { this.leaves.add(leave); return () => { this.leaves.delete(leave); }; }
     close() {
@@ -233,6 +247,10 @@ export class LiveConnection {
             leave();
         this.leaves.clear();
         this.proofs.clear();
+        if (this.refusing && this.stream.open) {
+            this.response.end("event: ended\ndata: {}\n\n");
+            return;
+        }
         if (!this.response.writableEnded)
             this.response.end();
     }
@@ -251,6 +269,7 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
     const bus = options.bus ?? null;
     const safetyNetMs = options.safetyNetMs ?? SAFETY_NET_MS;
     const minIntervalMs = options.minIntervalMs ?? 0;
+    const readSettleMs = options.readSettleMs ?? 0;
     const rooms = new Map();
     let unsubscribe = null;
     const announce = (key, room) => {
@@ -287,6 +306,8 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
             clearTimeout(room.retry);
         if (room.holding !== null)
             clearTimeout(room.holding);
+        if (room.reading !== null)
+            clearTimeout(room.reading);
         rooms.delete(key);
         if (rooms.size === 0 && unsubscribe !== null) {
             unsubscribe();
@@ -312,7 +333,10 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
                 viewer.connection.send(viewer.room, "gone");
             }
             finally {
-                leave(key, viewer);
+                if (valid)
+                    leave(key, viewer);
+                else
+                    viewer.connection.refuse(() => leave(key, viewer));
             }
             return false;
         }
@@ -366,8 +390,20 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
             deliver(key, room, viewer, "change", { at: room.last, revision: room.revision });
     };
     const heard = (change) => {
-        for (const [key, room] of [...rooms])
-            refresh(key, room, change.revision);
+        for (const [key, room] of [...rooms]) {
+            if (readSettleMs <= 0) {
+                refresh(key, room, change.revision);
+                continue;
+            }
+            // Re-prove now; read once the burst settles.
+            for (const viewer of [...room.viewers.keys()])
+                deliver(key, room, viewer);
+            if (rooms.get(key) !== room || room.reading !== null)
+                continue;
+            room.reading = setTimeout(() => { room.reading = null; if (rooms.get(key) === room)
+                refresh(key, room, null); }, readSettleMs);
+            room.reading.unref();
+        }
     };
     return {
         join(key, viewer) {
@@ -378,7 +414,7 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
                     last = fingerprint(key);
                 }
                 catch { /* the next signal or the safety net reads it */ }
-                const created = { viewers: new Map(), last, timer: setInterval(() => refresh(key, created, null), safetyNetMs), settling: null, retry: null, saidAt: 0, holding: null, revision: null };
+                const created = { viewers: new Map(), last, timer: setInterval(() => refresh(key, created, null), safetyNetMs), settling: null, retry: null, saidAt: 0, holding: null, revision: null, reading: null };
                 created.timer.unref();
                 room = created;
                 rooms.set(key, room);

package/dist/live-detail.d.ts

@@ -0,0 +1,27 @@
+import type { Store } from "./store.js";
+/** The consent a "Show commands" form carries: a single-use nonce minted for this person and these exact terms. */
+export declare const LIVE_VIEW_CONSENT = "live-view";
+export declare function liveViewConsentDigest(repo: string): string;
+export type LiveDetailSetting = {
+    repo: string;
+    commands: boolean;
+    updatedBy: string;
+    updatedAt: string;
+};
+/** Whether this project's live conversations show commands. Unknown or absent is off. */
+export declare function liveCommandsShown(store: Store, repo: string | null): boolean;
+export declare function liveDetailSetting(store: Store, repo: string): LiveDetailSetting | null;
+/** Save the setting and its ledger line in one transaction. The caller has proved who is asking (and, to turn it on, their password). */
+export declare function setLiveCommands(store: Store, change: {
+    repo: string;
+    commands: boolean;
+    by: string;
+    via: string;
+}, now: Date): {
+    said: string;
+};
+/** A run's trusted context for its live file: its own checkout, and its project's setting, read now. */
+export declare function liveLogContext(store: Store, taskRef: number, worktree: string | null): {
+    base: string | null;
+    commands: boolean;
+};

package/dist/live-detail.js

@@ -0,0 +1,57 @@
+/**
+ * A project's "Show commands in the live view" (docs/plans/live-conversation.md):
+ * whether a running agent's command text and command output are written to
+ * its live conversation. Off unless an approver turned it on for the
+ * project with their password; turning it off is one step. Every change is
+ * an action-ledger line.
+ *
+ * The writer reads it once, when it opens a run's live file: what is off
+ * never reaches disk, and a change applies from the next run.
+ */
+import { createHash } from "node:crypto";
+/** The consent a "Show commands" form carries: a single-use nonce minted for this person and these exact terms. */
+export const LIVE_VIEW_CONSENT = "live-view";
+export function liveViewConsentDigest(repo) {
+    return createHash("sha256").update(JSON.stringify(["live-view", repo, "commands-on"])).digest("hex");
+}
+/** Whether this project's live conversations show commands. Unknown or absent is off. */
+export function liveCommandsShown(store, repo) {
+    if (repo === null)
+        return false;
+    try {
+        const row = store.handle.prepare("SELECT commands FROM live_detail_setting WHERE repo = ?").get(repo);
+        return row !== undefined && Number(row["commands"]) === 1;
+    }
+    catch {
+        return false;
+    }
+}
+export function liveDetailSetting(store, repo) {
+    const row = store.handle.prepare("SELECT repo, commands, updated_by, updated_at FROM live_detail_setting WHERE repo = ?").get(repo);
+    if (row === undefined)
+        return null;
+    return { repo: String(row["repo"]), commands: Number(row["commands"]) === 1, updatedBy: String(row["updated_by"]), updatedAt: String(row["updated_at"]) };
+}
+/** Save the setting and its ledger line in one transaction. The caller has proved who is asking (and, to turn it on, their password). */
+export function setLiveCommands(store, change, now) {
+    store.transact(() => {
+        store.handle
+            .prepare(`INSERT INTO live_detail_setting (repo, commands, updated_by, updated_at) VALUES (?,?,?,?)
+        ON CONFLICT (repo) DO UPDATE SET commands = excluded.commands, updated_by = excluded.updated_by, updated_at = excluded.updated_at`)
+            .run(change.repo, change.commands ? 1 : 0, change.by, now.toISOString());
+        store.recordAction({ at: now.toISOString(), actor: change.by, repo: change.repo, taskId: null, runId: null,
+            action: "live view commands", outcome: change.commands ? "on" : "off", source: "request", detail: `via ${change.via}` });
+    });
+    return { said: change.commands ? "Commands now show in the live view for this project, from the next run." : "Commands are hidden in the live view for this project, from the next run." };
+}
+/** A run's trusted context for its live file: its own checkout, and its project's setting, read now. */
+export function liveLogContext(store, taskRef, worktree) {
+    let repo = null;
+    try {
+        repo = store.refForId(taskRef)?.repo ?? null;
+    }
+    catch {
+        repo = null;
+    }
+    return { base: worktree, commands: liveCommandsShown(store, repo) };
+}

package/dist/live-notes.d.ts

@@ -0,0 +1,20 @@
+import type { Store } from "./store.js";
+export declare const RUN_NOTES_SHOWN = 20;
+export type RunNote = {
+    id: number;
+    author: string;
+    /** Whether the person looking wrote it: only then does the view say "You". */
+    mine: boolean;
+    at: string;
+    text: string;
+    standing: string;
+    readAt: string | null;
+};
+/** This run's notes, oldest first: the newest RUN_NOTES_SHOWN, and how many older ones the task page keeps. */
+export declare function runNotes(store: Store, run: {
+    id: number;
+    taskRef: number;
+}, viewer: string, now: Date): {
+    notes: RunNote[];
+    older: number;
+};

package/dist/live-notes.js

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

package/dist/live-records.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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.
+ */
+/**
+ * The fixed tool vocabulary: known harness tools map to OUR kinds; anything
+ * unrecognized is "tool". The tool's own name never reaches the file.
+ */
+export type LiveActivityKind = "session" | "message" | "edit" | "command" | "read" | "search" | "lookup" | "plan" | "delegate" | "tool";
+export declare const LIVE_ACTIVITY_KINDS: readonly LiveActivityKind[];
+/** What a run's live file may hold: the base tier, or commands too (the project setting, read at open). */
+export type LiveDetail = "base" | "commands";
+/** One record. `at` is when the recorder saw it (ISO). */
+export type LiveRecord = 
+/** The file's first record: what this run's project allowed when it started, kept with the run. */
+{
+    k: "open";
+    at: string;
+    detail: LiveDetail;
+} | {
+    k: "start";
+    at: string;
+} | {
+    k: "say";
+    at: string;
+    t: string[];
+} | {
+    k: "step";
+    at: string;
+    id: string;
+    kind: LiveActivityKind;
+    target?: string;
+    once?: true;
+} | {
+    k: "done";
+    at: string;
+    id: string;
+    ok: boolean | null;
+    out?: string[];
+} | {
+    k: "cut";
+    at: string;
+} | {
+    k: "cap";
+    at: string;
+};
+/** A record's serialized size limit: a longer one is replaced by `cut`. */
+export declare const LIVE_RECORD_CAP: number;
+export declare const HIDDEN_TARGET = "[hidden]";
+export declare const HIDDEN_LINE = "[a line was hidden]";
+export declare const HIDDEN_KEY_BLOCK = "[a key block was hidden]";
+export declare const OUTSIDE_PROJECT = "a file outside the project";
+export declare const SOME_FILE = "a file";
+/** Whether a line looks like it carries a credential (best effort). */
+export declare function liveSecretHit(line: string): boolean;
+/** Controls, ANSI escapes and bidi overrides out; tabs to spaces. */
+export declare function cleanLiveText(text: string): string;
+/** An escape a line ended in the middle of, which the next line finishes: CSI, OSC, or a bare ESC. */
+export type EscapeCarry = "" | "C" | "O" | "E";
+/** Cut to at most `cap` UTF-8 bytes on a character boundary, "…" when cut. */
+export declare function capLive(text: string, cap: number): string;
+/** One line for the view: redacted whole when it hits, then cleaned and cut. */
+export declare function liveLine(raw: string, cap?: number): string;
+/**
+ * Lines redacted as a whole: each line on its own, and a key block hidden
+ * from its BEGIN line to its END (or to the end) as one line. Used for the
+ * agent's words, command output, and everything read back.
+ */
+/**
+ * Whether reading is inside a key block: carried from line to line, record to
+ * record and — through the reader's cursor — from one read to the next, so a
+ * block split anywhere stays hidden.
+ */
+export type KeyState = {
+    inKey: boolean;
+    /** Per reading, how much of "-----BEGIN" the stream has ended on so far, then the escape the last line left open:
+     * marker characters and one flag only, never content, so it may ride the cursor. Joined with "|" when carried. */
+    tail?: string;
+};
+/** Whether a carried tail is one this code could have produced: three BEGIN prefixes and an escape flag, or nothing. */
+export declare function validKeyTail(tail: string): boolean;
+export declare function redactLiveLines(lines: readonly string[], state?: KeyState): string[];
+/**
+ * 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 declare function liveOutput(raw: string, keys?: KeyState): string[];
+/**
+ * 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 declare function livePath(base: string | null, given: unknown): string | null;
+/** A command's first line, "…" when more followed or it was cut. */
+export declare function liveCommand(given: unknown): string | null;
+export type LiveRecorderOptions = {
+    /** The run's own checkout; null when it has none (every path is "a file"). */
+    base: string | null;
+    /** The project's "Show commands in the live view" setting, read at open. */
+    commands: boolean;
+    clock?: () => Date;
+};
+export type LiveRecorder = {
+    /** The records one stream event adds. Never throws. */
+    observe(event: Record<string, unknown>): LiveRecord[];
+    /** The process ended: every step still open closes unknown. */
+    end(): LiveRecord[];
+};
+export declare function createLiveRecorder(options: LiveRecorderOptions): LiveRecorder;
+/** One record as its file line; an oversized one becomes `cut`. */
+export declare function serializeLiveRecord(record: LiveRecord): string;
+/**
+ * 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 declare function parseLiveRecord(line: string, keys?: KeyState): LiveRecord | null;
+/** Complete file lines (a window's text) into records; bad lines are skipped. */
+export declare function parseLiveRecords(text: string, keys?: KeyState): LiveRecord[];
+export declare const LIVE_CAP_WORDS = "[the live view stopped at its size cap \u2014 the run record continues]";
+export declare const LIVE_CUT_WORDS = "[a line was too long to show]";
+export declare const LIVE_KIND_HEADLINES: Readonly<Record<LiveActivityKind, string>>;
+/** A step's one line of words, with its target when it has one. */
+export declare function stepWords(step: {
+    kind: LiveActivityKind;
+    target?: string;
+}): string;
+/** Records as the plain lines the run page and `toolroll peek` show. */
+export declare function projectLiveText(records: readonly LiveRecord[]): string[];