toolroll 0.9.59 → 0.9.61

package/dist/exec.js

@@ -420,7 +420,10 @@ export const DEFAULT_MAX_BUFFER = 8 * 1024 * 1024;
  * watchdog with no wall-clock deadline. Both roads share the same kill and
  * settlement semantics.
  */
-function streamWatchdog(options, onTimeout) {
+function streamWatchdog(options, onTimeout, 
+/** The idle limit was reached: true when the caller ended the wait its own way (a paused live session closes
+ * stdin), so the same limit runs again for the process to exit before it is killed. */
+onIdle) {
     const hardMs = options.timeoutMs ?? (options.idleTimeoutMs === undefined ? DEFAULT_TIMEOUT_MS : undefined);
     const idleMs = options.idleTimeoutMs;
     let fired = false;
@@ -432,12 +435,25 @@ function streamWatchdog(options, onTimeout) {
         fired = true;
         onTimeout();
     };
+    const idle = () => {
+        let handled = false;
+        try {
+            handled = onIdle?.() === true;
+        }
+        catch {
+            handled = false;
+        }
+        if (handled)
+            armIdle();
+        else
+            fire();
+    };
     const armIdle = () => {
         if (idleMs === undefined)
             return;
         if (idleTimer !== undefined)
             clearTimeout(idleTimer);
-        idleTimer = setTimeout(fire, idleMs);
+        idleTimer = setTimeout(idle, idleMs);
         idleTimer.unref?.();
     };
     if (hardMs !== undefined) {
@@ -725,14 +741,36 @@ const JSONL_OVERFLOW_PREFIX_CAP = 4 * 1024;
  * storage can be reused for the next record. Counting the original bytes
  * (rather than JavaScript characters) makes the overflow receipt exact.
  */
-function boundedJsonlFramer(cap, onLine, inspectDiscriminants = false) {
+function boundedJsonlFramer(cap, onLine, inspectDiscriminants = false, tailCap = 0) {
     const retained = Buffer.allocUnsafe(cap);
     let retainedBytes = 0;
     let originalBytes = 0;
     let nonWhitespace = false;
     let discriminants = inspectDiscriminants ? jsonlDiscriminants() : null;
+    // An oversized line's last tailCap bytes, kept only once the line passes the cap (Claude's result carries its cost
+    // after the words that made it too large). Seeded from the retained prefix's end, so it is always the line's true end.
+    const tailSize = Math.max(0, Math.min(tailCap, cap));
+    const tail = tailSize === 0 ? null : Buffer.allocUnsafe(tailSize);
+    let tailBytes = 0;
+    let tailSeeded = false;
+    const keepTail = (part) => {
+        if (tail === null)
+            return;
+        if (!tailSeeded) {
+            tailSeeded = true;
+            tailBytes = retained.copy(tail, 0, retainedBytes - tailSize, retainedBytes);
+        }
+        if (part.length >= tailSize) {
+            tailBytes = part.copy(tail, 0, part.length - tailSize);
+            return;
+        }
+        const keepOld = Math.min(tailBytes, tailSize - part.length);
+        tail.copyWithin(0, tailBytes - keepOld, tailBytes);
+        tailBytes = keepOld + part.copy(tail, keepOld);
+    };
     const append = (part) => {
         discriminants?.push(part);
+        const before = originalBytes;
         originalBytes += part.length;
         if (!nonWhitespace) {
             for (const byte of part) {
@@ -745,6 +783,9 @@ function boundedJsonlFramer(cap, onLine, inspectDiscriminants = false) {
         if (retainedBytes < cap) {
             retainedBytes += part.copy(retained, retainedBytes, 0, cap - retainedBytes);
         }
+        // The bytes up to the cap are in the prefix; only what runs past it moves the tail.
+        if (tail !== null && originalBytes > cap)
+            keepTail(before >= cap ? part : part.subarray(cap - before));
     };
     const emit = () => {
         onLine({
@@ -752,7 +793,10 @@ function boundedJsonlFramer(cap, onLine, inspectDiscriminants = false) {
             bytesOriginal: originalBytes,
             overflowed: originalBytes > cap,
             ...(discriminants === null ? {} : { discriminants: discriminants.finish() }),
+            ...(tail !== null && originalBytes > cap ? { tail: tail.subarray(0, tailBytes) } : {}),
         });
+        tailBytes = 0;
+        tailSeeded = false;
         retainedBytes = 0;
         originalBytes = 0;
         nonWhitespace = false;
@@ -866,6 +910,85 @@ function leadingClaudeSystemSubtype(prefix) {
     const match = /^\s*\{\s*"type"\s*:\s*"system"\s*,\s*"subtype"\s*:\s*"([A-Za-z0-9._-]+)"/.exec(prefix.toString("utf8", 0, Math.min(prefix.length, 512)));
     return match?.[1] ?? null;
 }
+/** How much of an oversized Claude result's end is kept to read its cost and usage (they follow the words). */
+const CLAUDE_RESULT_TAIL_CAP = 64 * 1024;
+/**
+ * Where a key's value starts in a fragment of JSON text, once and only once. `"key":` never occurs inside a JSON
+ * string (every quote there is escaped, so `y":` cannot appear), so each match is a real key, though possibly of a
+ * nested object. A key seen more than once is ambiguous and reads as absent.
+ */
+function soleKeyValueAt(texts, key) {
+    const pattern = new RegExp(`"${key}"\\s*:\\s*`, "g");
+    let found = null;
+    for (const text of texts) {
+        for (const match of text.matchAll(pattern)) {
+            if (found !== null)
+                return null;
+            found = { text, at: match.index + match[0].length };
+        }
+    }
+    return found;
+}
+/** The JSON object starting at `at`, read to its matching brace (strings and escapes respected), or null. */
+function jsonObjectAt(text, at) {
+    if (text[at] !== "{")
+        return null;
+    let depth = 0, inString = false;
+    for (let i = at; i < text.length && i - at < CLAUDE_RESULT_TAIL_CAP; i += 1) {
+        const c = text[i];
+        if (inString) {
+            if (c === "\\")
+                i += 1;
+            else if (c === '"')
+                inString = false;
+        }
+        else if (c === '"')
+            inString = true;
+        else if (c === "{")
+            depth += 1;
+        else if (c === "}" && --depth === 0) {
+            try {
+                const value = JSON.parse(text.slice(at, i + 1));
+                return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * The accounting an oversized Claude result still carries, read by a bounded scan of its kept prefix and tail: the
+ * session's running `total_cost_usd`, its `usage` and `num_turns`, and whether it is a main result at all (an
+ * `origin` naming anything but a person makes it a background task's). Anything unreadable or seen twice is absent.
+ */
+export function scanOversizedClaudeResult(prefix, tail) {
+    const texts = [prefix.toString("utf8"), ...(tail === undefined ? [] : [tail.toString("utf8")])];
+    const origin = soleKeyValueAt(texts, "origin");
+    const originObject = origin === null ? null : jsonObjectAt(origin.text, origin.at);
+    const primary = originObject === null || String(originObject["kind"] ?? "") === "human";
+    const account = {};
+    const number = (key) => {
+        const at = soleKeyValueAt(texts, key);
+        const match = at === null ? null : /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(at.text.slice(at.at, at.at + 64));
+        const value = match === null ? NaN : Number(match[0]);
+        return Number.isFinite(value) && value >= 0 ? value : null;
+    };
+    const cost = number("total_cost_usd");
+    if (cost !== null)
+        account["total_cost_usd"] = cost;
+    const turns = number("num_turns");
+    if (turns !== null)
+        account["num_turns"] = turns;
+    const usageAt = soleKeyValueAt(texts, "usage");
+    const usage = usageAt === null ? null : jsonObjectAt(usageAt.text, usageAt.at);
+    if (usage !== null)
+        account["usage"] = usage;
+    return { primary, account };
+}
+/** Marks a Claude result whose session cost could not be read: the gateway charges the run's dollar cap instead. */
+export const CLAUDE_COST_UNKNOWN = "standing_orders_cost_unknown";
 function malformedCodexEventIsLoadBearing(prefix) {
     const type = leadingJsonObjectType(prefix);
     if (type === "thread.started" || type === "turn.completed" || type === "turn.failed")
@@ -1331,15 +1454,45 @@ function primaryResultOrigin(event) {
         return true;
     return false; // task-notification, channel, peer, coordinator, unknown: never the envelope
 }
+/** The usage fields Claude reports per message (not per session): a live session's account adds them up. */
+const LIVE_SUMMED_USAGE = ["input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens"];
+/**
+ * A live session's account so far (one main result per turn, checked on Claude Code 2.1.290): the latest result's
+ * session, ending, words and cost — `total_cost_usd` is already the session's running total — with the usage token
+ * fields and `num_turns`, which count only their own message, added up across every main result. A field that is not
+ * a non-negative number adds nothing.
+ */
+export function cumulativeLiveResult(previous, latest) {
+    const count = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+    const usageOf = (event) => event["usage"] !== null && typeof event["usage"] === "object" && !Array.isArray(event["usage"]) ? event["usage"] : null;
+    const before = usageOf(previous), now = usageOf(latest);
+    const usage = { ...(now ?? {}) };
+    for (const key of LIVE_SUMMED_USAGE) {
+        const a = before === null ? null : count(before[key]), b = now === null ? null : count(now[key]);
+        if (a !== null || b !== null)
+            usage[key] = (a ?? 0) + (b ?? 0);
+    }
+    const turnsBefore = count(previous["num_turns"]), turnsNow = count(latest["num_turns"]);
+    return {
+        ...latest,
+        ...(before === null && now === null ? {} : { usage }),
+        ...(turnsBefore === null && turnsNow === null ? {} : { num_turns: (turnsBefore ?? 0) + (turnsNow ?? 0) }),
+    };
+}
+/** This transport can keep stdin open for a live session (RunOptions.liveInput). */
+export const STREAM_INPUT = Symbol.for("toolroll.streamInput");
+/** Whether a runner declares it keeps stdin open for a live session; an injected runner opts in by carrying the mark. */
+export const streamsInput = (runner) => typeof runner === "function" && runner[STREAM_INPUT] === true;
 export function runClaudeStreamJsonl(file, args, options = {}) {
     const { cwd } = options;
     const childEnv = resolveChildEnv(options);
+    const live = options.liveInput ?? null;
     return new Promise(resolve => {
         let child;
         let container = null;
         let attachFailure = null;
         try {
-            const spawned = spawnStream(file, args, options, ["ignore", "pipe", "pipe"], childEnv);
+            const spawned = spawnStream(file, args, options, [live === null ? "ignore" : "pipe", "pipe", "pipe"], childEnv);
             child = spawned.child;
             container = spawned.container;
             void spawned.attached.then(outcome => { if (!outcome.ok)
@@ -1359,6 +1512,12 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
         let conflictingInitLine = null;
         let initSessionId = null;
         let resultLine = null;
+        let resultOverflowed = false;
+        // The run's account: the first main result, or for a live session every main result added up (each oversized
+        // one's scanned cost and usage too). Its cost is the highest running total seen; costUnknown when the latest main
+        // result's cost could not be read (an oversized one), which only a later readable result can clear.
+        let account = null;
+        let costUnknown = false;
         let overflowLine = null;
         let receiptFired = false;
         let stderr = "";
@@ -1380,6 +1539,26 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
                 // note stays honestly unreceipted and re-attaches later.
             }
         };
+        const tally = (event, line) => {
+            const before = account;
+            account = account === null || live === null ? event : { ...(line === null ? account : {}), ...cumulativeLiveResult(account, event) };
+            const cost = event["total_cost_usd"];
+            const readable = typeof cost === "number" && Number.isFinite(cost) && cost >= 0;
+            // The running total only grows: an earlier, higher total stands (a session's cost is never given back).
+            const prior = before?.["total_cost_usd"];
+            if (readable && typeof prior === "number" && prior > cost)
+                account = { ...account, total_cost_usd: prior };
+            if (line === null)
+                costUnknown = !readable;
+            else if (readable)
+                costUnknown = false;
+            if (resultOverflowed)
+                return;
+            if (line !== null && account === event)
+                resultLine = line;
+            else if (line !== null || resultLine !== null)
+                resultLine = JSON.stringify(account);
+        };
         const keep = (framed) => {
             if (framed.overflowed) {
                 // An oversized result is the first primary candidate and therefore
@@ -1404,10 +1583,22 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
                         overflowLine = claudeOverflowLine(framed);
                     return;
                 }
-                if (resultLine === null)
+                // Nothing inside an oversized result is trusted: the agent shapes its bytes (tool inputs in permission_denials
+                // are real JSON objects), so a planted total_cost_usd or origin could read as genuine. It counts as the main
+                // result with an unknown cost, charged at the run's cap, and a live session's input closes.
+                const scanned = { primary: true, account: {} };
+                if (live !== null || resultLine === null)
+                    tally(scanned.account, null);
+                if (resultLine === null) {
                     resultLine = claudeOverflowLine(framed);
+                    resultOverflowed = true;
+                }
                 else if (overflowLine === null)
                     overflowLine = claudeOverflowLine(framed);
+                // A live session whose main result was too large to read cannot be steered safely: close its input, so the
+                // process ends instead of running further turns nobody can account for.
+                if (live !== null && scanned.primary)
+                    live.close("settled");
                 return;
             }
             const line = framed.prefix.toString("utf8");
@@ -1458,8 +1649,11 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
                 // v105: the plan's usage windows, as Claude says them each turn (the Tasks page's limits).
                 noteLimits(claudeLimitsOf(event));
             }
-            else if (type === "result" && resultLine === null && primaryResultOrigin(event)) {
-                resultLine = line;
+            else if (type === "result" && (resultLine === null || live !== null) && primaryResultOrigin(event)) {
+                // A live session ends a turn with a result each time: the run's account is the last one, with every main
+                // result's usage and turns added up (account). After an oversized main result the retained result stays the
+                // fail-closed overflow, but later results still count toward its cost.
+                tally(event, line);
                 // Fallback receipt (finding 11): a SUCCESSFUL main-query completion
                 // entails the prompt ran even if the stream elided assistant
                 // events. Error results never fire — startup death is not delivery.
@@ -1474,15 +1668,32 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
                     // Observational only: a broken listener never touches the run.
                 }
             }
+            // After the run's own bookkeeping: the session may close stdin on this event.
+            if (live !== null)
+                live.observe(event);
         };
-        const framing = boundedJsonlFramer(JSONL_EVENT_HARD_CAP, keep);
+        // The retained main result as the run's account: an oversized one stays the fail-closed overflow but carries the
+        // cost and usage read from it and from later results; a cost that could not be read says so (CLAUDE_COST_UNKNOWN).
+        const accountedResultLine = () => {
+            if (resultLine === null || (!resultOverflowed && !costUnknown))
+                return resultLine;
+            const kept = JSON.parse(resultLine);
+            const counted = {};
+            if (resultOverflowed && account !== null) {
+                for (const key of ["total_cost_usd", "usage", "num_turns"])
+                    if (account[key] !== undefined)
+                        counted[key] = account[key];
+            }
+            return JSON.stringify({ ...kept, ...counted, ...(costUnknown ? { [CLAUDE_COST_UNKNOWN]: true } : {}) });
+        };
+        const framing = boundedJsonlFramer(JSONL_EVENT_HARD_CAP, keep, false, CLAUDE_RESULT_TAIL_CAP);
         const watchdog = streamWatchdog(options, () => {
             timedOut = true;
             if (options.processGroup === true)
                 killGroup(child);
             else
                 child.kill("SIGKILL");
-        });
+        }, live === null ? undefined : () => live.idleLimit());
         child.stdout?.on("data", (chunk) => {
             watchdog.touch();
             framing.push(chunk);
@@ -1501,7 +1712,8 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
             watchdog.stop();
             liveProviders.delete(child);
             framing.finish();
-            const lines = [initLine, initIdentityLine, conflictingInitLine, resultLine, overflowLine]
+            live?.detach();
+            const lines = [initLine, initIdentityLine, conflictingInitLine, accountedResultLine(), overflowLine]
                 .filter((one) => one !== null)
                 .filter((line, index, all) => all.indexOf(line) === index);
             const settlement = container === null ? Promise.resolve(null) : settleContainer(container, options);
@@ -1521,5 +1733,12 @@ export function runClaudeStreamJsonl(file, args, options = {}) {
             finish(null);
         });
         child.on("close", code => finish(code));
+        if (live !== null && child.stdin !== null) {
+            const input = child.stdin;
+            // A pipe the child closed (it exited) ends live input; the run settles on the process, as always.
+            input.on("error", () => live.detach("input-failed"));
+            live.attach({ write: line => { input.write(line, "utf8"); }, end: () => { input.end(); } });
+        }
     });
 }
+runClaudeStreamJsonl[STREAM_INPUT] = true;

package/dist/flow-actions.js

@@ -21,7 +21,6 @@
 import { createHash } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import nodemailer from "nodemailer";
 import { redactSecretAssignments } from "./builder.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { fillFlowText } from "./flows.js";
@@ -132,6 +131,8 @@ export async function sendingAccount(dir, fetcher) {
 }
 /** The production sender: the operator's mail server through nodemailer. */
 export const sendThroughServer = async (settings, mail) => {
+    // nodemailer loads when mail is sent, not with every command that imports this module.
+    const { default: nodemailer } = await import("nodemailer");
     const transport = nodemailer.createTransport({
         // A password never travels unencrypted: with a sign-in, the connection must be (or become) TLS.
         host: settings.host, port: settings.port, secure: settings.secure, requireTLS: !settings.secure && settings.user !== "",

package/dist/guides.js

@@ -208,22 +208,25 @@ runner never pushes, merges, or opens pull requests itself.
 const steering = {
     name: "steering",
     title: "Steering a task",
-    oneLiner: "an operator ceremony: credentialed notes read before the next attempt — agents cannot file one",
+    oneLiner: "an operator ceremony: credentialed notes a running build reads when it next checks for notes, or the next attempt — agents cannot file one",
     content: `# Steering a task
 
 ${AUTHORITY_LINE}
 
 Steering is an OPERATOR ceremony. \`task steer <id> --note "..." --as
-<you> --token <t>\` files one note (≤4000 characters) for the
-task's NEXT attempt, and the credential is the point: the note appears
-in the agent's brief under an OPERATOR STEERING heading, so only a
-verified person may put words there. Anonymous or agent-authored notes
-are refused outright.
-
-- Delivery is recorded: the task page shows whether a note is waiting,
-  attached to an attempt, or was read. A running agent is never
-  interrupted — notes wait for the next natural boundary (a repair, a
-  resume after a parked decision, a fresh attempt, a revision).
+<you> --token <t>\` files one note (≤4000 characters) for the task's
+agent, and the credential is the point: the note reaches the agent as
+operator guidance, so only a verified person may put words there.
+Anonymous or agent-authored notes are refused outright.
+
+- While a build's agent is running, the note is put in its steering
+  folder; the agent reads it when it next checks for notes and moves it
+  to handled/, which is the only thing that marks it read. Otherwise —
+  or if the agent finishes before reading it — the next attempt's brief
+  quotes it under an OPERATOR STEERING heading.
+- Each note says where it stands, the same on the task page, in
+  \`task show\` and to the lead: waiting for the agent to read it, read
+  by the agent at a time, or will reach the next attempt.
 - A note is guidance INSIDE the approved scope. It cannot widen scope,
   approve anything, or replace the ceremony a change of scope needs.
 - Refusals: missing credential is usage; a wrong credential is