toolroll 0.9.104 → 0.9.105

package/dist/flow-steps.js

@@ -1,27 +1,3 @@
-/**
- * Steps that run outside a model (v84), in the worker's pass:
- *
- * - check  — runs one of the project's scripts (flow-scripts.ts) in a fresh
- *            copy of the card's latest result (or the base branch), after the
- *            project's approved setup, with the same bare environment setup
- *            and checks get, plus FLOW_* variables naming the card. Exit 0
- *            passes; anything else takes the failure path. The end of its
- *            output (64 KB, whole lines, keys blanked) is kept as the log.
- * - update — comments on the GitHub or Linear issue the card came from, and
- *            can close it (Linear: moves it to the team's done state), with
- *            the person's own `gh` login and Linear key.
- * - draft  — (v86) Claude writes from the card (flow-draft.ts); the draft
- *            is kept on the card for a person and later steps.
- * - sort   — (v85) asks Jev through OpenRouter which of the zone's answers
- *            fits the card (flow-sort.ts), and sends it where that answer
- *            leads, or down the not-sure path.
- * - pull-request — opens a pull request for the card's result and follows
- *            its CI (flow-pull-request.ts).
- *
- * One run per visit to the zone (flow_step_run): two workers never run it
- * twice. Trouble reaching a service is retried three times, 5 then 15
- * minutes apart; a check that fails is an answer, not trouble.
- */
 import { mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { approvedCommandShell, redactSecretAssignments, SETUP_ENV_ALLOWLIST, SETUP_ENV_DENYLIST } from "./builder.js";
@@ -47,18 +23,13 @@ import { toolRefusal } from "./policy.js";
 import { pullRequestStep } from "./flow-pull-request.js";
 import { withStageHandoff } from "./contracts/stage-output.js";
 const RETRY_MS = [5 * 60_000, 15 * 60_000];
-/** A subagent's turn tries again sooner: a card waiting on a person's colleague shouldn't wait long for a hiccup. */
 const SUBAGENT_RETRY_MS = [60_000, 5 * 60_000];
 const OUTPUT_CHARS = 3000;
-/** How much of a step's output its run keeps as the log. */
 const LOG_CHARS = 64_000;
-/** Run every due check and update in one project, then move each card on. */
 export async function runFlowSteps(store, repo, now, io) {
-    // v105: one budget gate a pass, built only if a Sort card is waiting.
     let gate = null;
     const budgetGate = work => (gate ??= store.budgetGate(now))(work);
     const pass = { ran: 0, problems: [] };
-    // A step left running long past any time limit had its worker stop: it may try again.
     for (const stale of store.staleFlowSteps(new Date(now.getTime() - 75 * 60_000)))
         store.finishFlowStep(stale.card, stale.entry, { state: "waiting", result: "Interrupted; trying again.", nextAt: now.toISOString() }, now);
     const flows = new Map();
@@ -72,15 +43,12 @@ export async function runFlowSteps(store, repo, now, io) {
         const stage = known.definition?.stages.find(one => one.id === card.stage);
         if (stage === undefined)
             continue;
-        // A card whose task is put away (v145) runs nothing — no step, subagent turn or pull request — until it's restored.
         if (cardTaskArchived(store, card.id))
             continue;
-        // v92: a subagent's turn — a zone it handles, or a decision it staffs (a person decides when it's paused or gone).
         if (stage.kind === "subagent" || (stage.kind === "approval" && stage.subagent !== undefined)) {
             await subagentStep(store, known.flow, known.definition, stage, card, now, io, pass);
             continue;
         }
-        // A pull request: opened for the card's result, then CI decides where it goes (flow-pull-request.ts).
         if (stage.kind === "pull-request") {
             try {
                 if (await pullRequestStep(store, known.flow, known.definition, stage, card, now, { gh: io.gh, ...(io.evidenceRoot === undefined ? {} : { evidenceRoot: io.evidenceRoot }) }))
@@ -93,7 +61,6 @@ export async function runFlowSteps(store, repo, now, io) {
         }
         if (!["check", "update", "sort", "draft", "request", "email", "tool"].includes(stage.kind))
             continue;
-        // Email and tools wait, saying why, until what they need is set up.
         const setup = stage.kind === "email" && !sendingReady(io.dir) ? "Email isn't set up yet. Add your mail server or a Google account in Settings → Email."
             : stage.kind === "tool" ? toolWaiting(store, stage, repo) : null;
         if (setup !== null) {
@@ -108,8 +75,6 @@ export async function runFlowSteps(store, repo, now, io) {
                 store.updateFlowCard(card.id, { waiting }, now);
             continue;
         }
-        // v105: sorting spends the key's credit, and a draft whatever this computer's Claude bills: a budget for this project
-        // (or everything) that holds key work holds them.
         const agents = stage.kind === "sort" ? [{ provider: "openrouter", billing: "api-key" }]
             : stage.kind === "draft" ? [{ provider: "claude", billing: claudeMachineBilling(store.handle) }] : null;
         const held = agents === null ? null : budgetGate({ project: repo, person: null, subagent: null, agents });
@@ -119,7 +84,6 @@ export async function runFlowSteps(store, repo, now, io) {
                 store.updateFlowCard(card.id, { waiting }, now);
             continue;
         }
-        // Sprint 8: a sort, a draft or a tool call the organisation policy doesn't allow waits, saying which rule.
         const disallowed = stage.kind === "sort" ? store.agentPolicyRefusal("openrouter", JEV_MODEL)
             : stage.kind === "draft" ? store.agentPolicyRefusal("claude", draftModel(store))
                 : stage.kind === "tool" && stage.tool !== undefined && stage.tool !== null ? toolRefusal(store.orgPolicy(), stage.tool.server) : null;
@@ -135,14 +99,12 @@ export async function runFlowSteps(store, repo, now, io) {
                 store.updateFlowCard(card.id, { waiting }, now);
             continue;
         }
-        // A script an imported flow brought waits until a person approves it, like any change to what runs here.
         if (script !== null && script.held !== null) {
             const waiting = `The ${script.name} script came with an imported flow. Approve it on the Scripts panel to run it.`;
             if (card.waiting !== waiting)
                 store.updateFlowCard(card.id, { waiting }, now);
             continue;
         }
-        // A script waits for the secrets it names (v90), and runs on its own once they're saved.
         const missing = stage.kind === "check" ? (stage.secrets ?? []).filter(name => readFlowSecrets(io.dir, repo)[name] === undefined) : [];
         if (missing.length > 0) {
             const waiting = `${stage.script} needs the secret${missing.length === 1 ? "" : "s"} ${missing.join(", ")}. Save ${missing.length === 1 ? "it" : "them"} on the zone.`;
@@ -150,8 +112,6 @@ export async function runFlowSteps(store, repo, now, io) {
                 store.updateFlowCard(card.id, { waiting }, now);
             continue;
         }
-        // A script that starts a browser waits, saying so, until a person approves browser use for the flow (flow-browser.ts),
-        // rather than run and crash inside the sandbox; it runs on its own once approved.
         const browser = stage.kind === "check" && stage.browser === true ? (script === null || known.definition === null ? { allowed: false, said: "This zone's script can't be read." } : browserStanding(store, known.flow.id, stage.id, { definition: known.definition, script })) : null;
         if (browser !== null && !browser.allowed) {
             if (card.waiting !== browser.said)
@@ -176,7 +136,6 @@ export async function runFlowSteps(store, repo, now, io) {
         catch (error) {
             outcome = { state: "retry", said: error instanceof Error ? error.message : "It couldn't run." };
         }
-        // What went out is kept before the card moves on, so a reply that comes back at once still finds it.
         if (outcome.state === "passed" && outcome.mail !== undefined)
             recordSent(store, card, outcome.mail, now);
         settle(store, known.definition, stage, store.getFlowCard(card.id), outcome, now, Date.now() - started);
@@ -185,34 +144,27 @@ export async function runFlowSteps(store, repo, now, io) {
     }
     return pass;
 }
-/** Claim this card's visit to its step zone, only while the card is still there on that visit: a pass that read the card
- * before another pass (or a person) moved it never runs the step for a visit that's over. */
 export function claimStep(store, card, step, now) {
     return store.transact(() => {
         const fresh = store.getFlowCard(card.id);
         if (fresh === null || fresh.state !== "active" || fresh.entry !== card.entry || fresh.stage !== step.stage)
             return false;
-        // A card whose task is put away (v145) runs no step until the task is restored (both of its tasks, re-read here).
         if (cardTaskArchived(store, card.id))
             return false;
         if (!store.claimFlowStep({ card: card.id, entry: card.entry, ...step }, now))
             return false;
-        // The tasks this step was admitted for stay held while it runs, wherever the card moves meanwhile.
         for (const task of [fresh.task, fresh.primaryTask])
             if (task !== null)
                 store.handle.prepare("INSERT OR IGNORE INTO flow_step_task (card, entry, task_id) VALUES (?, ?, ?)").run(card.id, card.entry, task);
         return true;
     });
 }
-/** One subagent turn, when one is due for this card: claimed like any step, retried on failure, and waiting while its question is open. */
 async function subagentStep(store, flow, definition, stage, card, now, io, pass) {
-    // v102: on a protected project a subagent never decides an approval; the engine asks the person.
     if (stage.kind === "approval" && store.approvalRules(flow.repo).protectProject)
         return true;
     const mate = stage.subagent === undefined ? null : store.subagentByHandle(flow.repo, stage.subagent);
     const ready = subagentReady(store, mate, now);
     if (!ready.ok) {
-        // A decision goes to its person (the engine asks them). A zone only it handles waits, saying why.
         if (stage.kind === "approval")
             return true;
         const waiting = ready.why === "gone" ? `There's no subagent called ${stage.subagent ?? "(none)"} in this project.` : `${mate.handle} is ${ready.why === "paused" ? "paused" : `waiting: ${ready.why}`}.`;
@@ -220,7 +172,6 @@ async function subagentStep(store, flow, definition, stage, card, now, io, pass)
             store.updateFlowCard(card.id, { waiting }, now);
         return true;
     }
-    // Waiting on a person: its own question, or (v94) a tool call they approve first.
     if (store.openSubagentQuestionOn(card.id, card.entry) !== null)
         return true;
     if (!claimStep(store, card, { stage: stage.id, kind: "subagent", script: null, scriptVersion: null }, now))
@@ -255,7 +206,6 @@ async function subagentStep(store, flow, definition, stage, card, now, io, pass)
         : { state: outcome.state === "passed" ? "passed" : "failed", result: outcome.said, ...kept }, now);
     return true;
 }
-/** Record what a step did and move the card: on for a pass, down its failure path for a fail, or wait to try again. */
 function settle(store, definition, stage, card, outcome, now, durationMs) {
     const run = store.flowStepRun(card.id, card.entry);
     const kept = { log: outcome.log === undefined ? null : keptLog(outcome.log), exitCode: outcome.exitCode ?? null, durationMs, ...(outcome.decisionJson === undefined ? {} : { decisionJson: outcome.decisionJson }) };
@@ -269,8 +219,6 @@ function settle(store, definition, stage, card, outcome, now, durationMs) {
         outcome = { state: "failed", said: `${outcome.said} It didn't work after three tries.` };
     }
     store.finishFlowStep(card.id, card.entry, { state: outcome.state === "passed" ? "passed" : "failed", result: outcome.said, ...kept }, now);
-    // What the steps after it read: whole up to TEXT_LIMITS.stageOutput; longer is attached whole to the card's discussion,
-    // and they read a link to it, while a task filed after it is given it whole (the card keeps it attached). Never cut.
     const whole = outcome.output ?? outcome.said;
     const passed = passOn(whole, TEXT_LIMITS.stageOutput, { label: "the card's discussion", href: flowCardHref(card.flow, card.id) });
     if (passed.kept)
@@ -278,7 +226,6 @@ function settle(store, definition, stage, card, outcome, now, durationMs) {
     store.updateFlowCard(card.id, { outputs: withStageHandoff(card.outputs, stage.id, { text: passed.text }), ...(passed.kept ? { attached: { [stage.id]: whole } } : {}), waiting: null }, now);
     const titleOf = (id) => definition.stages.find(one => one.id === id)?.title ?? "another zone";
     if (outcome.state === "passed") {
-        // A sort names where the card goes; one it isn't sure about is a person's to place.
         const to = outcome.to !== undefined ? outcome.to : stage.next;
         if (outcome.unsure === true) {
             const people = card.owner === null ? cardFollowers(store, card) : [card.owner];
@@ -300,31 +247,24 @@ function settle(store, definition, stage, card, outcome, now, durationMs) {
     const people = card.owner === null ? cardFollowers(store, card) : [card.owner];
     notifyPeople(store, card, people, null, { key: `step-failed:${card.entry}`, subject: `${stage.title} didn't pass for “${card.title}”`, body: `${outcome.said}${stage.onFail === null ? "" : `\n\nIt's back in ${titleOf(stage.onFail)}.`}`, attention: true }, now);
 }
-/** A run's log: the end of its output in whole lines, where failures show, with key-shaped lines replaced and credential-looking values blanked. */
 function keptLog(text) {
     const end = text.length <= LOG_CHARS ? text : text.slice(-LOG_CHARS).replace(/^[^\n]*\n/, "");
     return redactSecretAssignments(redactSecretLines(end, scanForSecrets(end)));
 }
-/** The end of a command's output, without anything that looks like a key. */
 function tail(text) {
     const end = text.trim().slice(-OUTPUT_CHARS);
     return scanForSecrets(end).length > 0 ? "(Its output held something that looked like a key, so it isn't shown.)" : end;
 }
-/** The Claude model a draft runs on: the lead chat's Claude model, or Claude's default. */
 function draftModel(store) {
     const config = store.getChatConfig();
     return config?.provider === "claude-subscription" ? config.model : "default";
 }
-/** A draft: Claude writes what the zone asks, from the card, with the lead chat's Claude model; the text stays on the card. */
 async function draftCard(store, definition, stage, card, io, repo, now) {
     const model = draftModel(store);
     const runner = io.draft ?? claudeDraftRunner();
-    // Claude is told the limit before it writes; a draft over it is asked once to shorten, and one still over is kept whole
-    // in the step's log and attached to the card's discussion, linked from what the next steps read (settle): never cut.
     let first = null;
     const written = await writeWithin(async (shorten) => {
         const answer = await runner({ model, prompt: draftPrompt(stage, card, definition, shorten === null || first === null ? null : { draft: first, ask: shorten }), timeoutMs: DRAFT_TIMEOUT });
-        // v105: what it cost, billed as this computer's Claude does (a plan's is $0).
         if (answer.ok) {
             store.recordDraftSpend({ repo, model: model === "default" ? null : model, costUsd: answer.costUsd ?? null }, now);
             first ??= wholeDraft(answer.text);
@@ -339,13 +279,11 @@ async function draftCard(store, definition, stage, card, io, repo, now) {
         return written.repaired && first !== null ? draftOutcome(first, model, answer.ms, true) : { state: "retry", said: "Claude's draft came back empty." };
     return draftOutcome(text, model, answer.ms, written.repaired);
 }
-/** A draft step's result: the draft whole, on the card and in its log. */
 function draftOutcome(text, model, ms, shortened) {
     const words = text.split(/\s+/).filter(Boolean).length;
     const over = text.length > DRAFT_CHARS ? ` It is still over the ${DRAFT_CHARS.toLocaleString("en-US")}-character limit after one ask to shorten, so it is kept whole.` : shortened ? " Shortened once to fit." : "";
     return { state: "passed", said: `Drafted ${words} word${words === 1 ? "" : "s"}.${over}`, output: text, log: `Claude (${model})${ms === null ? "" : ` · ${(ms / 1000).toFixed(1)} s`}\n\n${text}` };
 }
-/** A sort: Jev picks one of the zone's answers for the card; the answer (or the not-sure path) says where it goes. */
 async function sortCard(definition, stage, card, key, io) {
     const index = definition.stages.findIndex(one => one.id === stage.id);
     const earlier = definition.stages.filter((one, at) => at !== index && card.outputs[one.id] !== undefined).map(one => ({ id: one.id, title: one.title }));
@@ -357,19 +295,12 @@ async function sortCard(definition, stage, card, key, io) {
         return { state: "retry", said: decision.problem };
     return { state: "passed", said: sortWords(decision), log: sortLog(stage, decision), to: decision.to, decisionJson: JSON.stringify(decision), unsure: !decision.confident };
 }
-/** A script step: a fresh detached copy at the card's latest result (or the base branch), the approved setup, then the script. */
-/**
- * A script zone (v90: code steps): the script runs with the card as its input, in a clean folder or in
- * a copy of the card's work (after the project's setup), inside the agents' fence. What it prints is
- * the step's result; a last "goto:" line picks one of the zone's answers.
- */
 async function runCheck(store, flow, stage, script, card, now, io) {
     const task = card.primaryTask ?? card.task;
     const copy = (stage.runIn ?? "copy") === "copy";
     const receipt = !copy || task === null ? null : assignmentOf(store, task, now, { principal: "operator", repos: [flow.repo] }, io.evidenceRoot)?.receipt ?? null;
     const commit = receipt?.head ?? null;
     const where = !copy ? "" : commit === null ? ` on ${io.base}` : ` on commit ${commit.slice(0, 7)}`;
-    // The secrets it names, from the flow's saved ones: a missing one is said, never run without.
     const saved = readFlowSecrets(io.dir, flow.repo);
     const missing = (stage.secrets ?? []).filter(name => saved[name] === undefined);
     if (missing.length > 0)
@@ -383,10 +314,7 @@ async function runCheck(store, flow, stage, script, card, now, io) {
         if (added.code !== 0)
             return { state: "retry", said: `Couldn't make a copy of${where}: ${added.stderr.trim().split("\n")[0]?.slice(0, 160) ?? "git refused"}.` };
     }
-    // Browser use, proved at the moment of launch: a zone that says it starts a browser runs only with a person's standing
-    // approval (flow-browser.ts); then its script, and only its script, gets Chromium's one service.
     const wantsBrowser = stage.browser === true;
-    // Read once: the drawing and the script this launch runs are the very objects the browser decision is about.
     const running = flowDefinitionOf(flow);
     const standing = !wantsBrowser ? null : running === null || running.stages.find(one => one.id === stage.id) === undefined || JSON.stringify(running.stages.find(one => one.id === stage.id)) !== JSON.stringify(stage)
         ? { allowed: false, said: "This zone changed while it was starting, so it didn't run." } : browserStanding(store, flow.id, stage.id, { definition: running, script });
@@ -400,7 +328,6 @@ async function runCheck(store, flow, stage, script, card, now, io) {
     try {
         if (launch !== null && "problem" in launch)
             return { state: "failed", said: launch.problem };
-        // The project's setup never gets the browser rule: only the zone's script asked for it.
         const setupFence = launch?.fence === undefined ? undefined : { ...launch.fence, fenceGrants: withoutBrowser(launch.fence.fenceGrants) };
         let log = "";
         const setup = copy ? store.liveWorktreeSetup(flow.repo) : null;
@@ -414,7 +341,6 @@ async function runCheck(store, flow, stage, script, card, now, io) {
         }
         const definition = flowDefinitionOf(flow);
         const titleOf = (id) => definition?.stages.find(one => one.id === id.split(".")[0])?.title ?? id;
-        // The card as data: never part of a command.
         const input = {
             card: { id: card.id, title: card.title, description: card.description, email: cardEmailOf(card) || null, note: card.note, owner: card.owner, source: card.source === null ? null : { kind: card.source.kind, label: card.source.label, url: card.source.url } },
             outputs: Object.fromEntries(Object.entries(card.outputs).map(([id, text]) => [id, { zone: titleOf(id), text }])),
@@ -422,18 +348,15 @@ async function runCheck(store, flow, stage, script, card, now, io) {
             answers: (stage.routes ?? []).map(one => one.answer),
         };
         const env = { FLOW_NAME: flow.name, FLOW_CARD_ID: String(card.id), FLOW_CARD_TITLE: card.title, FLOW_COMMIT: commit ?? "", FLOW_SCRIPT: script.name, FLOW_PROJECT: flow.repo };
-        // Checked again right before the script: the flow or its script may have changed while the setup ran.
         if (wantsBrowser) {
             const still = running === null ? { allowed: false, said: "This flow's drawing can't be read." } : browserStanding(store, flow.id, stage.id, { definition: running, script });
             if (!still.allowed)
                 return { state: "failed", said: still.said, log };
         }
-        // And at every spawn attempt (a retry after a failed spawn too): revoked or changed meanwhile, nothing starts.
         const stillApproved = !wantsBrowser || running === null ? undefined : () => browserStanding(store, flow.id, stage.id, { definition: running, script }).allowed;
         const ran = await runCode({ script, cwd: path, root: copy ? path : flow.repo, input, env, secrets, scratch: io.scratch, shell: io.shell, launch, ...(stillApproved === undefined ? {} : { beforeSpawn: stillApproved }) });
         log += ran.log;
         const output = ran.output === "" ? undefined : ran.output;
-        // Where it ran goes at the end of the first line: "run-tests failed (exit 1) on main."
         const placed = (said) => { const [first = "", ...rest] = said.split("\n"); return [first.replace(/\.$/, `${where}.`), ...rest].join("\n"); };
         if (ran.state === "failed")
             return { state: "failed", said: placed(ran.said), log, exitCode: ran.exitCode, ...(output === undefined ? {} : { output }) };
@@ -452,18 +375,15 @@ async function runCheck(store, flow, stage, script, card, now, io) {
         rmSync(path, { recursive: true, force: true });
     }
 }
-/** A fence's grants without Chromium's service (a flow's setup, beside a script zone that has it). */
 function withoutBrowser(grants) {
     const { browser: _scriptOnly, ...rest } = grants;
     return rest;
 }
-/** An update: a comment on the issue the card came from, and closing it if the zone says so. */
 async function updateSource(store, stage, card, io, now) {
     const source = card.source;
     const text = fillFlowText(stage.message ?? "Done: {{card.title}}", { title: card.title, description: card.description, note: card.note, outputs: card.outputs });
     if (scanForSecrets(text).length > 0)
         return { state: "failed", said: "The comment looked like it held a key or password, so nothing was posted." };
-    // A card from a chat channel (v89): the answer goes in the thread it came from.
     if (source?.chat !== undefined) {
         const replied = replyInChannel(store, source.chat, { card: card.id, entry: card.entry }, text, now);
         return replied.ok ? { state: "passed", said: `Answered in the ${source.label.replace(/ message$/, "")} thread.` } : { state: "failed", said: replied.said };