@foldrun/core 0.3.0 → 0.4.0

package/dist/src/step-exec.js

@@ -12,6 +12,13 @@ import path from "node:path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { spawn } from "node:child_process";
 import { checkPaths, checkBash, isFilesystemTool } from "./confine.js";
+import { hostSafeEnv } from "./host-env.js";
+import { validateSchema, describeSchemaErrors, looksLikeSchema } from "./json-schema.js";
+/** How often the stop flag is read while a step runs. */
+export const STOP_POLL_MS = 2000;
+/** After an interrupt is asked for, how long the model loop gets to wind
+ *  down on its own before the query is aborted outright. */
+export const INTERRUPT_GRACE_MS = 10_000;
 /** Conservative per-token rates for a model nothing else can price — an
  *  unknown id on a gateway with no catalogue. Opus-class, so a ceiling
  *  still means something. Only ever reached when `knownPrice` below does
@@ -72,7 +79,28 @@ export function stepCeiling(budgetUsd, spentUsd, launching) {
         return null;
     return Math.max(0, budgetUsd - spentUsd) / Math.max(1, launching);
 }
-export async function executeStep(opts) {
+/**
+ * The ceiling a step actually runs under, and which line set it.
+ *
+ * Two caps can apply to one step: the flow's `budget:` gives it an equal
+ * share of what the run has left; the agent's own `budget:` is the most that
+ * agent may spend in one run, less what its earlier steps in this run cost.
+ * The tighter one wins, and the note says which, because "over budget" with
+ * no line to go and raise is a message that sends someone to the wrong file.
+ */
+export function stepCeilingFor(flowShareUsd, agentBudgetUsd, agentSpentUsd, agent) {
+    const flow = { ceilingUsd: flowShareUsd, note: "budget: in the flow file" };
+    if (!agentBudgetUsd || agentBudgetUsd <= 0)
+        return flow;
+    const left = Math.max(0, agentBudgetUsd - agentSpentUsd);
+    if (flowShareUsd !== null && flowShareUsd <= left)
+        return flow;
+    return { ceilingUsd: left, note: `budget: on the ${agent} agent` };
+}
+export async function executeStep(opts, 
+/** The model loop. Injected so the clock and the stop can be tested
+ *  without a model; production passes nothing and gets the SDK. */
+runQuery = query) {
     const { agentDir, workspaceRoot, libraryRoot, emit } = opts;
     let status = "running";
     let costUsd = null;
@@ -80,16 +108,22 @@ export async function executeStep(opts) {
     const texts = [];
     fs.mkdirSync(path.join(agentDir, "outputs"), { recursive: true });
     fs.mkdirSync(path.join(agentDir, "memory"), { recursive: true });
-    const q = query({
+    // The one handle that can end the loop from outside: the timeout and a
+    // stop both ask the query to interrupt, and abort it outright if it has
+    // not wound down within the grace period.
+    const abort = new AbortController();
+    const q = runQuery({
         prompt: opts.prompt,
         options: {
             cwd: agentDir,
+            abortController: abort,
             model: opts.model,
             // Omitted, not passed as undefined-with-a-default: an unset effort
             // should mean "whatever this model does normally", which is not a
             // level we can name — it moves as models ship.
             ...(opts.effort ? { effort: opts.effort } : {}),
             systemPrompt: opts.systemPrompt,
+            ...(opts.maxTurns ? { maxTurns: opts.maxTurns } : {}),
             // Restrict the toolset itself, not just approval: an agent that
             // declares no tools gets none, instead of seeing the full Claude
             // Code toolset and burning turns on denied calls.
@@ -141,7 +175,37 @@ export async function executeStep(opts) {
             },
         },
     });
-    const deadline = opts.timeoutSec ? Date.now() + opts.timeoutSec * 1000 : null;
+    // Why the loop was ended from outside, if it was. The deadline used to be
+    // checked only when a message arrived, so a step waiting on one long tool
+    // call — a crawl, a build — sailed past its timeout: with no message there
+    // was nothing to check it against. The backstop timer fires regardless,
+    // and a stop is read on a clock rather than between groups.
+    let ended = null;
+    const timers = [];
+    const endWith = (why) => {
+        if (ended)
+            return;
+        ended = why;
+        void q.interrupt().catch(() => { });
+        timers.push(setTimeout(() => abort.abort(), INTERRUPT_GRACE_MS));
+    };
+    if (opts.timeoutSec)
+        timers.push(setTimeout(() => endWith("timeout"), opts.timeoutSec * 1000));
+    if (opts.stopRequested) {
+        timers.push(setInterval(() => {
+            try {
+                if (opts.stopRequested())
+                    endWith("stopped");
+            }
+            catch {
+                // an unreadable record is not a stop
+            }
+        }, STOP_POLL_MS));
+    }
+    // The clocks stay referenced on purpose: a step hanging in a tool call may
+    // be the only thing keeping the loop alive, and an unreferenced timer
+    // would let the process exit around it instead of ending it. They are all
+    // cleared when the step ends, so nothing outlives the step.
     // The hard cap. Spend is counted as each assistant turn arrives — its
     // usage is in the message — so the step can stop at the ceiling rather
     // than learn afterwards that it crossed it. Cache traffic is counted as
@@ -152,70 +216,89 @@ export async function executeStep(opts) {
     // Open tool calls, by the provider's id, so the result can be paired with
     // its call and the trace can say how long each tool ran.
     const openCalls = new Map();
-    for await (const message of q) {
-        if (deadline && Date.now() > deadline) {
-            emit("error", `step exceeded its ${opts.timeoutSec}s timeout`);
-            status = "failed";
-            break;
-        }
-        if (message.type === "assistant") {
-            const u = message.message.usage;
-            if (ceiling && u) {
-                spentUsd += priceTurn(u, opts.price ?? null);
-                if (spentUsd >= ceiling) {
-                    emit("error", `over budget — this step reached $${spentUsd.toFixed(4)} of its $${ceiling.toFixed(4)} ceiling mid-turn and was stopped (budget: in the flow file)`);
-                    status = "failed";
-                    break;
-                }
-            }
-            for (const block of message.message.content) {
-                if (block.type === "text" && block.text.trim()) {
-                    texts.push(block.text);
-                    emit("text", block.text);
+    try {
+        for await (const message of q) {
+            if (ended)
+                break;
+            if (message.type === "assistant") {
+                const u = message.message.usage;
+                if (ceiling && u) {
+                    spentUsd += priceTurn(u, opts.price ?? null);
+                    if (spentUsd >= ceiling) {
+                        emit("error", `over budget — this step reached $${spentUsd.toFixed(4)} of its $${ceiling.toFixed(4)} ceiling mid-turn and was stopped (${opts.budgetNote ?? "budget: in the flow file"})`);
+                        status = "failed";
+                        break;
+                    }
                 }
-                else if (block.type === "tool_use") {
-                    openCalls.set(block.id, { name: block.name, at: Date.now() });
-                    emit("tool", block.name, { call: block.id });
+                for (const block of message.message.content) {
+                    if (block.type === "text" && block.text.trim()) {
+                        texts.push(block.text);
+                        emit("text", block.text);
+                    }
+                    else if (block.type === "tool_use") {
+                        openCalls.set(block.id, { name: block.name, at: Date.now() });
+                        emit("tool", block.name, { call: block.id });
+                    }
                 }
             }
-        }
-        else if (message.type === "user") {
-            // Tool results ride back as user turns. The completion event closes
-            // the span the call opened; the runner's journal keeps both.
-            const content = message.message.content;
-            if (Array.isArray(content)) {
-                for (const block of content) {
-                    if (block.type !== "tool_result")
-                        continue;
-                    const open = openCalls.get(block.tool_use_id);
-                    if (!open)
-                        continue;
-                    openCalls.delete(block.tool_use_id);
-                    emit("tool", open.name, {
-                        call: block.tool_use_id,
-                        ms: Date.now() - open.at,
-                        ...(block.is_error ? { err: true } : {}),
-                    });
+            else if (message.type === "user") {
+                // Tool results ride back as user turns. The completion event closes
+                // the span the call opened; the runner's journal keeps both.
+                const content = message.message.content;
+                if (Array.isArray(content)) {
+                    for (const block of content) {
+                        if (block.type !== "tool_result")
+                            continue;
+                        const open = openCalls.get(block.tool_use_id);
+                        if (!open)
+                            continue;
+                        openCalls.delete(block.tool_use_id);
+                        emit("tool", open.name, {
+                            call: block.tool_use_id,
+                            ms: Date.now() - open.at,
+                            ...(block.is_error ? { err: true } : {}),
+                        });
+                    }
                 }
             }
-        }
-        else if (message.type === "result") {
-            status = message.subtype === "success" ? "completed" : "failed";
-            costUsd = "total_cost_usd" in message ? (message.total_cost_usd ?? null) : null;
-            if ("usage" in message && message.usage) {
-                const u = message.usage;
-                usage = {
-                    // Cache traffic is input the provider still bills (at its own
-                    // rates); folding it into the input count over-approximates for
-                    // gateways with cheaper cache reads, which errs on the honest side.
-                    inputTokens: (u.input_tokens ?? 0) +
-                        (u.cache_creation_input_tokens ?? 0) +
-                        (u.cache_read_input_tokens ?? 0),
-                    outputTokens: u.output_tokens ?? 0,
-                };
+            else if (message.type === "result") {
+                status = message.subtype === "success" ? "completed" : "failed";
+                if (message.subtype === "error_max_turns") {
+                    emit("error", `stopped after ${opts.maxTurns ?? "its"} turns (max_turns: in the flow file) — the step did not finish`);
+                }
+                costUsd = "total_cost_usd" in message ? (message.total_cost_usd ?? null) : null;
+                if ("usage" in message && message.usage) {
+                    const u = message.usage;
+                    usage = {
+                        // Cache traffic is input the provider still bills (at its own
+                        // rates); folding it into the input count over-approximates for
+                        // gateways with cheaper cache reads, which errs on the honest side.
+                        inputTokens: (u.input_tokens ?? 0) +
+                            (u.cache_creation_input_tokens ?? 0) +
+                            (u.cache_read_input_tokens ?? 0),
+                        outputTokens: u.output_tokens ?? 0,
+                    };
+                }
             }
         }
     }
+    catch (err) {
+        // An abort we asked for is not an error of the step's; anything else is.
+        if (!ended)
+            throw err;
+    }
+    finally {
+        for (const t of timers)
+            clearTimeout(t);
+    }
+    if (ended === "timeout") {
+        emit("error", `timed out after ${opts.timeoutSec}s (timeout: in the flow file) — the step was stopped with the files it wrote so far kept`);
+        status = "failed";
+    }
+    else if (ended === "stopped") {
+        emit("error", "stopped by a person mid-step");
+        status = "failed";
+    }
     // The SDK ends a healthy run with a `result` message. A stream that just
     // stops — subprocess OOM-killed, crashed, or torn down — used to fall
     // through as "completed", which reported a run that produced nothing as a
@@ -240,6 +323,14 @@ export async function executeStep(opts) {
         if (extracted.ok) {
             data = extracted.value;
             emit("info", `output: json — ${describeJson(data)}`);
+            // The declared shape, checked here beside the extraction: a value
+            // that parses but is not what the next step was promised is the same
+            // failure as no value, and the message names the field.
+            const errors = opts.schema !== undefined && looksLikeSchema(opts.schema) ? validateSchema(data, opts.schema) : [];
+            if (errors.length) {
+                emit("error", `schema: the value does not fit — ${describeSchemaErrors(errors)}`);
+                status = "failed";
+            }
         }
         else {
             emit("error", `output: json — ${extracted.reason}`);
@@ -401,9 +492,13 @@ function runVerify(agentDir, command, env, data) {
     return new Promise((resolve) => {
         // No clock of the platform's: a verify like `npm run build` takes what
         // it takes, and the step's own `timeout:` is the bound if the flow set one.
+        // The allowlisted host base plus what the caller passed: the step's
+        // secrets and identifiers on the in-process path (runner.ts), the
+        // container's own environment on the isolated one (run-container.ts).
+        // Never process.env whole — see host-env.ts.
         const child = spawn("bash", ["-lc", command], {
             cwd: agentDir,
-            env: { ...process.env, ...env },
+            env: { ...hostSafeEnv(), ...env },
             stdio: ["pipe", "pipe", "pipe"],
         });
         // An `output: json` step's data arrives on stdin, so a check can be