toolroll 0.9.59 → 0.9.61

package/dist/live-input.js

@@ -0,0 +1,254 @@
+/**
+ * A Claude build's live input (live steering). The build runs with
+ * `--input-format stream-json` and its stdin left open, so Toolroll can talk
+ * to the session while it works instead of only through files it reads
+ * between steps (checked on Claude Code 2.1.290):
+ *
+ * - The brief is the FIRST stdin message, a user frame with its own uuid. A
+ *   `-p` prompt is silently dropped once stdin carries input, so the argv
+ *   never carries the brief.
+ * - A later user frame is taken up as soon as the current tool call ends,
+ *   inside the turn that is running: it adds no result of its own.
+ * - An interrupt control request stops the current turn within milliseconds
+ *   and keeps the process; the next user frame continues the same session
+ *   as a new turn. That is Pause; Resume is that next frame with only a
+ *   short "continue". Stop is still the process-tree kill it always was.
+ * - One process emits a result per turn, so the run ends when Toolroll
+ *   closes stdin, not at the first result: after a turn ends with the
+ *   handoff written or with nothing more owed, when the turn budget is
+ *   spent, or when a paused session reaches the idle limit. `--max-turns`
+ *   applies per user message, so the total is counted here. The idle
+ *   watchdog stays the transport's own; a paused session only asks it to
+ *   close stdin first (idleLimit), so the build settles from its handoff.
+ *   closeReason tells settlement which ending Toolroll chose.
+ *
+ * Sending is never reading: a note written here still counts as read only
+ * when the agent moves its file to handled/ (steer-mailbox.ts). Nothing here
+ * touches the store; the builder's dispatcher records what happened.
+ */
+import { randomUUID } from "node:crypto";
+/** What Resume sends a paused session: only a nudge to go on, never a note. */
+export const CONTINUE_TEXT = "continue";
+/** A stdin user frame, in the shape the harness reads. */
+export const userFrame = (text, uuid) => JSON.stringify({ type: "user", message: { role: "user", content: text }, uuid });
+/** A stdin interrupt: stop the current turn, keep the session. */
+export const interruptFrame = (requestId, cancelQueued = false) => JSON.stringify({ type: "control_request", request_id: requestId, request: { subtype: "interrupt", ...(cancelQueued ? { cancel_queued: true } : {}) } });
+/** The session's own words count; a subagent's (parent_tool_use_id set) or a background task's never do. */
+const topLevel = (event) => event["parent_tool_use_id"] === undefined || event["parent_tool_use_id"] === null;
+const primaryResult = (event) => {
+    const origin = event["origin"];
+    return origin === undefined || origin === null || (typeof origin === "object" && String(origin["kind"] ?? "") === "human");
+};
+export class LiveInput {
+    maxTurns;
+    #options;
+    #io = null;
+    #pending = [];
+    #begun = false;
+    #closed = false;
+    #turnActive = false;
+    /** A user frame was written while an interrupted turn had not yet ended: that frame's own turn is owed a result. */
+    #owed = false;
+    #paused = false;
+    #interrupts = new Set();
+    #turns = new Set();
+    #closeReason = null;
+    /** The brief's frame uuid, once begun. */
+    briefUuid = null;
+    constructor(options) {
+        this.#options = options;
+        this.maxTurns = Math.max(1, Math.floor(options.maxTurns));
+    }
+    /** Queue the brief as the first frame. Once, before the process is attached. */
+    begin(brief, uuid = randomUUID()) {
+        if (this.#begun)
+            throw new Error("a live session's brief is sent once");
+        this.#begun = true;
+        this.briefUuid = uuid;
+        this.#turnActive = true;
+        this.#write(userFrame(brief, uuid));
+    }
+    /** The transport spawned the child with stdin piped: write what is queued, brief first. */
+    attach(io) {
+        if (this.#io !== null || this.#closed)
+            return;
+        this.#io = io;
+        const pending = this.#pending;
+        this.#pending = [];
+        for (const line of pending)
+            if (!this.#raw(line))
+                return;
+        try {
+            this.#options.onOpen?.();
+        }
+        catch { /* display state never touches the session */ }
+    }
+    /** stdin is attached and still open: a note reaches the agent in seconds, and a Pause can stop its turn. */
+    get open() {
+        return this.#io !== null && !this.#closed;
+    }
+    get paused() {
+        return this.#paused;
+    }
+    /** Distinct assistant turns so far, across every message. */
+    get turns() {
+        return this.#turns.size;
+    }
+    /** Why stdin closed, once it has. */
+    get closeReason() {
+        return this.#closeReason;
+    }
+    /**
+     * Send a note (or anything the session should read next). A paused session continues. False once stdin is closed.
+     * Mid-turn, the harness folds it into the running turn; after an interrupt that turn is over, so the frame starts a
+     * turn of its own whose result is owed before stdin closes.
+     */
+    send(text, uuid) {
+        if (!this.open)
+            return false;
+        if (!this.#write(userFrame(text, uuid)))
+            return false;
+        if (this.#turnActive && this.#interrupts.size > 0)
+            this.#owed = true;
+        this.#paused = false;
+        this.#turnActive = true;
+        return true;
+    }
+    /** Resume a paused session with a short continue frame and no note. "not-paused" when nothing waits to go on. */
+    resume(uuid) {
+        if (!this.open)
+            return "closed";
+        if (!this.#paused)
+            return "not-paused";
+        return this.send(CONTINUE_TEXT, uuid) ? "sent" : "closed";
+    }
+    /**
+     * The transport's idle limit was reached. A paused session closes stdin instead of being killed — the harness exits
+     * and the build settles from whatever handoff it saved — and true asks the watchdog to wait once more for that exit.
+     * Anything else is an ordinary idle timeout.
+     */
+    idleLimit() {
+        if (!this.open || !this.#paused)
+            return false;
+        this.close("paused-idle");
+        return true;
+    }
+    /**
+     * Pause: stop the current turn, keep the session. "sent" when an interrupt was written; "idle" when no turn was
+     * running (the session is already waiting, so it is paused as it stands); "closed" when stdin is gone.
+     */
+    interrupt(requestId) {
+        if (!this.open)
+            return "closed";
+        this.#paused = true;
+        if (!this.#turnActive)
+            return "idle";
+        if (!this.#write(interruptFrame(requestId)))
+            return "closed";
+        this.#interrupts.add(requestId);
+        return "sent";
+    }
+    /** Every parsed stdout event, in order. */
+    observe(event) {
+        const type = String(event["type"] ?? "");
+        if (type === "assistant" && topLevel(event)) {
+            this.#turnActive = true;
+            const message = event["message"];
+            const id = typeof message?.["id"] === "string" ? message["id"] : `turn-${this.#turns.size + 1}`;
+            this.#turns.add(id);
+            if (this.#turns.size > this.maxTurns && this.open) {
+                // The total is spent once a turn past it starts: the last allowed turn ran in full, tools and all. Stop this
+                // one, then let the process finish on its own; settlement reads the handoff (closeReason).
+                // cancel_queued: a note already queued must not start a turn past the budget after stdin closes.
+                this.#write(interruptFrame(`budget-${randomUUID()}`, true));
+                this.close("turn-budget");
+            }
+        }
+        else if (type === "control_response") {
+            const response = event["response"];
+            const requestId = typeof response?.["request_id"] === "string" ? response["request_id"] : null;
+            if (requestId !== null && this.#interrupts.has(requestId) && response?.["subtype"] === "success" && this.#paused)
+                this.#notifyPaused();
+        }
+        else if (type === "result" && primaryResult(event)) {
+            this.#turnActive = false;
+            this.#interrupts.clear();
+            if (this.#paused) {
+                // A paused session waits for the next note; the idle watchdog still bounds the wait.
+                this.#notifyPaused();
+                return;
+            }
+            // A frame written after this turn was interrupted starts a turn of its own: wait for its result.
+            if (this.#owed) {
+                this.#owed = false;
+                return;
+            }
+            let finished = false;
+            try {
+                finished = this.#options.finished?.() === true;
+            }
+            catch {
+                finished = false;
+            }
+            this.close(finished ? "finished" : "settled");
+        }
+    }
+    /** Close stdin: the harness finishes what it has and exits. Further sends refuse. */
+    close(why) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#closeReason = why;
+        this.#paused = false;
+        if (this.#io !== null) {
+            try {
+                this.#io.end();
+            }
+            catch { /* already gone */ }
+        }
+        try {
+            this.#options.onClose?.(why);
+        }
+        catch { /* display state never touches the session */ }
+    }
+    /** The process ended (or its stdin failed): nothing more is written. */
+    detach(why = "ended") {
+        const closedAlready = this.#closed;
+        this.#closed = true;
+        if (!closedAlready)
+            this.#closeReason = why;
+        this.#paused = false;
+        this.#io = null;
+        if (!closedAlready) {
+            try {
+                this.#options.onClose?.(why);
+            }
+            catch { /* display state never touches the session */ }
+        }
+    }
+    #notifyPaused() {
+        try {
+            this.#options.onPaused?.();
+        }
+        catch { /* display state never touches the session */ }
+    }
+    #write(line) {
+        if (this.#closed)
+            return false;
+        if (this.#io === null) {
+            this.#pending.push(line);
+            return true;
+        }
+        return this.#raw(line);
+    }
+    #raw(line) {
+        try {
+            this.#io.write(`${line}\n`);
+            return true;
+        }
+        catch {
+            this.detach("input-failed");
+            return false;
+        }
+    }
+}

package/dist/live.d.ts

@@ -46,7 +46,7 @@ export declare function liveActivityKind(event: Record<string, unknown>): LiveAc
  * chatter — renders nothing in v1.
  */
 export declare function renderTranscriptLines(event: Record<string, unknown>): string[];
-/** Sanitize one display line: strip, redact whole on any secret hit, cap. */
+/** Sanitize one display line: strip controls and bidi overrides, redact whole on any secret hit, cap. */
 export declare function sanitizeTranscriptLine(line: string): string;
 export type LiveLog = {
     observe(event: Record<string, unknown>): void;

package/dist/live.js

@@ -190,9 +190,11 @@ export function renderTranscriptLines(event) {
     }
     return lines;
 }
-/** Sanitize one display line: strip, redact whole on any secret hit, cap. */
+/** Bidirectional overrides and isolates (U+202A–U+202E, U+2066–U+2069): they can make shown text read differently from what was written. */
+const BIDI_CONTROLS = /[\u202a-\u202e\u2066-\u2069]/g;
+/** Sanitize one display line: strip controls and bidi overrides, redact whole on any secret hit, cap. */
 export function sanitizeTranscriptLine(line) {
-    const stripped = stripControls(line);
+    const stripped = stripControls(line).replace(BIDI_CONTROLS, "");
     if (scanForSecrets(stripped).length > 0)
         return LIVE_REDACTED_LINE;
     return capBytes(stripped, LIVE_LINE_CAP);

package/dist/mailbox.js

@@ -15,8 +15,6 @@
  * answering machines. The card keeps the message's ID so a Send email step
  * replying to the sender stays in the same thread.
  */
-import { ImapFlow } from "imapflow";
-import { simpleParser } from "mailparser";
 import { googleAccessToken, googleConnected } from "./google-mail.js";
 import { readEmailSettings } from "./email-settings.js";
 const BODY_CHARS = 4000;
@@ -72,6 +70,8 @@ const header = (headers, name) => {
 };
 /** One raw message as plain words, and whether a machine sent it. */
 export async function readMail(uid, source) {
+    // The mail SDKs load when mail is read, not with every command that imports this module.
+    const { simpleParser } = await import("mailparser");
     const parsed = await simpleParser(source, { skipImageLinks: true, skipTextToHtml: true, skipTextLinks: true });
     const sender = parsed.from?.value[0];
     const from = (sender?.address ?? "").toLowerCase();
@@ -103,6 +103,7 @@ function problemOf(error) {
 }
 /** The production reader: one read-only IMAP visit. */
 export const readThroughImap = async (access, folder, after, limit) => {
+    const { ImapFlow } = await import("imapflow");
     const client = new ImapFlow({
         host: access.host, port: access.port, secure: access.secure, logger: false, disableAutoIdle: true,
         auth: access.accessToken !== undefined ? { user: access.user, accessToken: access.accessToken } : { user: access.user, pass: access.password ?? "" },

package/dist/maintenance.d.ts

@@ -5,6 +5,8 @@ export declare function startMaintenance(args: {
     run: () => Promise<void>;
     shouldStop: () => boolean;
     onError: (error: unknown) => void;
+    /** Synchronously cancel owned background work before waiting for the current pass. */
+    onStop?: () => void;
 }): {
     runNow: () => Promise<void>;
     stop: () => Promise<void>;

package/dist/maintenance.js

@@ -27,8 +27,11 @@ export function startMaintenance(args) {
     return {
         runNow,
         stop: async () => {
-            stopped = true;
-            clearInterval(timer);
+            if (!stopped) {
+                stopped = true;
+                clearInterval(timer);
+                args.onStop?.();
+            }
             await pending;
         },
     };

package/dist/mcp-core.js

@@ -56,7 +56,7 @@ const CONTRACT_GUIDE = [
     "recap, list_decisions, get_decision, and queue are the plane's own read queries (shared with the operator's mate). get_decision shows each option's consequence, never the builder's recommendation.",
     "propose_next, propose_reserve, propose_hold, propose_unhold, propose_scope, propose_cancel, and propose_answer write a PROPOSAL row and nothing else: an approver confirms it on the console or the CLI, and a stale one refuses there. Proposals share your hourly filing rate and hold at most 20 pending per credential; they expire after seven days.",
     "Approve, steer, answer, pick, mint, configure, merge: those verbs do not exist on this surface, by construction.",
-    "Claim one assignment, then follow list_assignment_updates with a saved cursor; inspect get_assignment when a current result or decision needs attention. claim_assignment records its lead; acknowledge_assignment records that lead's check of an exact ready receipt. Neither operation grants authority, accepts proof, answers decisions, approves work, publishes, or deploys.",
+    "Claim one assignment, then receive its changes with get_assignment_inbox and acknowledge each handled batch with acknowledge_assignment_delivery; inspect get_assignment when a current result or decision needs attention. list_assignment_updates is only the history of handoffs sent to people. claim_assignment records its lead; acknowledge_assignment records that lead's check of an exact ready receipt. Neither operation grants authority, accepts proof, answers decisions, approves work, publishes, or deploys.",
 ].join("\n");
 /** An assignment tool: the adapter reads its call with the same schema `toolroll assignment` does. */
 const assignmentHandler = (operation) => (ctx, args) => {

package/dist/operate-remote-arguments.js

@@ -29,7 +29,11 @@ export const REMOTE_ARGUMENTS = new Map([
     ['task block', args('id:task', 'key', { on: 'task' })],
     ['task unblock', args('id:task', 'key', { on: 'task' })],
     ['task next', args('id:task', 'key undo')],
-    ['task steer', args('id:task', 'note')],
+    // Live steering: --now pauses the running Claude build first; pause and continue name the exact attempt like stop and
+    // resume, and a repeated --request (or --key) id is the same request.
+    ['task steer', args('id:task', 'note now request key', { run: 'run' })],
+    ['task pause', args('id:task', 'request key', { run: 'run' })],
+    ['task continue', args('id:task', 'request key', { run: 'run' })],
     ['task assign', args('id:task', 'key runner anyone')],
     ['task scope', args('id:task', 'key goal not touches budget-usd risk acceptance candidate model provider repair-model')],
     ['task plan', args('id:task', 'key provider model')],

package/dist/operate-remote.js

@@ -37,7 +37,7 @@ const references = { kind: "references" }, listing = { kind: "listing" };
 export const REMOTE_SCOPES = new Map([
     ["status", listing], ["integrations", installation], ["ready", listing], ["grants", installation], ["sync", installation],
     ["gaps", repo], ["task add", repo],
-    ...["ask", "checks", "add-tests", "show", "wait", "complete", "revise", "state", "block", "unblock", "next", "steer", "assign", "scope", "plan", "hold",
+    ...["ask", "checks", "add-tests", "show", "wait", "complete", "revise", "state", "block", "unblock", "next", "steer", "pause", "continue", "assign", "scope", "plan", "hold",
         "unhold", "require", "requeue", "review", "repair", "route", "reopen", "stop", "resume"].map(action => [`task ${action}`, references]),
     ["check-progress", references],
     ["task list", listing],

package/dist/operate.d.ts

@@ -102,7 +102,7 @@ type Args = {
  * exports are behavior, not commentary — and the declared command guide
  * (surface.ts) is tested for exact equality against them.
  */
-export declare const TASK_ACTIONS: readonly ["add", "list", "show", "wait", "state", "block", "unblock", "next", "steer", "assign", "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan", "review", "accept", "repair", "route", "stop", "resume", "complete", "revise", "merge", "ask", "checks", "add-tests"];
+export declare const TASK_ACTIONS: readonly ["add", "list", "show", "wait", "state", "block", "unblock", "next", "steer", "pause", "continue", "assign", "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan", "review", "accept", "repair", "route", "stop", "resume", "complete", "revise", "merge", "ask", "checks", "add-tests"];
 export declare const PUBLISH_ACTIONS: readonly ["setup", "grant", "revoke", "status", "unblock", "rearm", "merge", "refire"];
 export declare const CONFIG_ACTIONS: readonly ["show", "set", "clear"];
 export declare const APPROVER_ACTIONS: readonly ["list", "add"];