@foldrun/core 0.2.0 → 0.4.0

package/src/step-exec.ts

@@ -11,10 +11,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
-import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import type { McpServerConfig, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { Effort } from "./store.ts";
+import type { TestEffect } from "./test-mode.ts";
 import { spawn } from "node:child_process";
 import { checkPaths, checkBash, isFilesystemTool } from "./confine.ts";
+import { hostSafeEnv } from "./host-env.ts";
+import { validateSchema, describeSchemaErrors, looksLikeSchema } from "./json-schema.ts";
 
 export interface ExecOutcome {
   status: "completed" | "failed";
@@ -57,6 +60,9 @@ export interface ExecOptions {
    *  The runner derives it from the flow's `budget:` and what the run has
    *  already spent; absent means no ceiling on this step. */
   budgetUsd?: number | null;
+  /** Which line set the ceiling, for the error that names it — "budget: in
+   *  the flow file" or "budget: on the <agent> agent". */
+  budgetNote?: string;
   /** Price per token for the model, when the catalogue knows it, so spend
    *  can be counted turn by turn instead of learned at the end. Without it
    *  the step prices its turns from the SDK's own running total. */
@@ -69,30 +75,93 @@ export interface ExecOptions {
   /** `output: json` — the reply must carry one JSON value; extracting it is
    *  part of finishing the step, and failing to is failing the step. */
   output?: "json";
+  /** `schema:` — what that value must look like; a value that does not fit
+   *  fails the step naming the field. See json-schema.ts. */
+  schema?: Record<string, unknown> | boolean;
+  /** `max_turns:` — the most model turns before the step is stopped. The
+   *  SDK enforces it; the step reads the result's reason and says so. */
+  maxTurns?: number;
   /** false when the caller is already an isolation boundary (a run
    *  container): the SDK's bash sandbox is then redundant and would block
    *  declared network use. Default (undefined/true) keeps it on. */
   sandboxBash?: boolean;
+  /** Has a person asked for the run to stop? Polled every couple of
+   *  seconds while the model loop runs; true interrupts it. The in-process
+   *  runner answers from the run record (stopRun writes there from another
+   *  process); a container has a sandbox that is destroyed instead. */
+  stopRequested?: () => boolean;
   emit: (type: "text" | "tool" | "info" | "error", text: string, extra?: EventExtra) => void;
 }
 
+/** 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;
+
+/** The model loop, as executeStep needs it — the SDK's `query`, or a test's
+ *  stand-in. Only the shape the loop reads. */
+export type QueryLike = AsyncIterable<unknown> & { interrupt(): Promise<unknown> };
+export type QueryFn = (args: { prompt: string; options: Record<string, unknown> }) => QueryLike;
+
 /** The pairing fields on a tool event — see RunEvent in store.ts. */
-export type EventExtra = { call?: string; ms?: number; err?: boolean };
+export type EventExtra = { call?: string; ms?: number; err?: boolean; effect?: TestEffect };
 
-/** Conservative per-token rates for a model the catalogue cannot price —
- *  Opus-class — so a ceiling still means something on an unknown gateway. */
+
+/** 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
+ *  not recognise the model either. */
 export const FALLBACK_PRICE = { input: 15e-6, output: 75e-6 };
 
+/** The rates we know without asking anyone: the tiers this runtime resolves
+ *  (`fast`/`default`/`max` → haiku/sonnet/opus) and the model ids that carry
+ *  those words. A gateway with a catalogue still wins — that is the
+ *  authority — but the platform's own Anthropic key has no catalogue, and
+ *  pricing its steps at Opus rates made every mid-turn ceiling read up to
+ *  fifteen times high: an indexing run was stopped at "$1.17" having
+ *  actually spent $0.15 (2026-09-08). Per token, input/output. */
+const KNOWN_PRICES: [RegExp, { input: number; output: number }][] = [
+  [/haiku/i, { input: 1e-6, output: 5e-6 }],
+  [/sonnet/i, { input: 2e-6, output: 10e-6 }],
+  [/\bopus\b/i, { input: 5e-6, output: 25e-6 }],
+];
+
+/** What a token costs on this model, when we can say without a catalogue. */
+export function knownPrice(model: string | undefined): { input: number; output: number } | null {
+  if (!model) return null;
+  return KNOWN_PRICES.find(([re]) => re.test(model))?.[1] ?? null;
+}
+
+/** Anthropic's cache multipliers, and the shape every gateway that bills
+ *  for caching at all has copied: a write costs a quarter more than fresh
+ *  input, a read a tenth of it. Counting both at the full input rate — as
+ *  this did — makes a long cached prompt read about ten times its price,
+ *  which on a ceiling is not "the honest direction to be wrong in", it is
+ *  a step killed for spending money it never spent. */
+const CACHE_WRITE_MULTIPLIER = 1.25;
+const CACHE_READ_MULTIPLIER = 0.1;
+
 /**
- * What one assistant turn cost. Cache traffic is counted as input at the
- * input rate, which over-approximates on gateways with cheaper cache reads
- * — on the money side, the honest direction to be wrong in. Pure.
+ * What one assistant turn cost, from the usage the SDK reports. Pure.
+ *
+ * A gateway whose cache is priced differently is over- or under-counted
+ * here by that difference alone; the run record's own cost is repriced
+ * from the catalogue afterwards and stays the authority on the bill. This
+ * number exists to stop a runaway step mid-turn, and wants to be close.
  */
 export function priceTurn(u: Record<string, number | undefined>, price: { input: number; output: number } | null): number {
-  const inTok = (u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0);
-  const outTok = u.output_tokens ?? 0;
   const p = price ?? FALLBACK_PRICE;
-  return inTok * p.input + outTok * p.output;
+  const fresh = u.input_tokens ?? 0;
+  const written = u.cache_creation_input_tokens ?? 0;
+  const read = u.cache_read_input_tokens ?? 0;
+  const outTok = u.output_tokens ?? 0;
+  return (
+    fresh * p.input +
+    written * p.input * CACHE_WRITE_MULTIPLIER +
+    read * p.input * CACHE_READ_MULTIPLIER +
+    outTok * p.output
+  );
 }
 
 /**
@@ -105,7 +174,34 @@ export function stepCeiling(budgetUsd: number | null | undefined, spentUsd: numb
   return Math.max(0, budgetUsd - spentUsd) / Math.max(1, launching);
 }
 
-export async function executeStep(opts: ExecOptions): Promise<ExecOutcome> {
+/**
+ * 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: number | null,
+  agentBudgetUsd: number | null | undefined,
+  agentSpentUsd: number,
+  agent: string,
+): { ceilingUsd: number | null; note: string } {
+  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: ExecOptions,
+  /** The model loop. Injected so the clock and the stop can be tested
+   *  without a model; production passes nothing and gets the SDK. */
+  runQuery: QueryFn = query as unknown as QueryFn,
+): Promise<ExecOutcome> {
   const { agentDir, workspaceRoot, libraryRoot, emit } = opts;
   let status: "running" | "completed" | "failed" = "running";
   let costUsd: number | null = null;
@@ -115,16 +211,23 @@ export async function executeStep(opts: ExecOptions): Promise<ExecOutcome> {
   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.
@@ -178,7 +281,34 @@ export async function executeStep(opts: ExecOptions): Promise<ExecOutcome> {
     },
   });
 
-  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: "timeout" | "stopped" | null = null;
+  const timers: NodeJS.Timeout[] = [];
+  const endWith = (why: "timeout" | "stopped") => {
+    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
@@ -191,18 +321,15 @@ export async function executeStep(opts: ExecOptions): Promise<ExecOutcome> {
   // its call and the trace can say how long each tool ran.
   const openCalls = new Map<string, { name: string; at: number }>();
 
-  for await (const message of q) {
-    if (deadline && Date.now() > deadline) {
-      emit("error", `step exceeded its ${opts.timeoutSec}s timeout`);
-      status = "failed";
-      break;
-    }
+  try {
+  for await (const message of q as AsyncIterable<SDKMessage>) {
+    if (ended) break;
     if (message.type === "assistant") {
       const u = (message.message as unknown as { usage?: Record<string, number | undefined> }).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)`);
+          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;
         }
@@ -235,6 +362,9 @@ export async function executeStep(opts: ExecOptions): Promise<ExecOutcome> {
       }
     } 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 as unknown as Record<string, number | undefined>;
@@ -251,6 +381,19 @@ export async function executeStep(opts: ExecOptions): Promise<ExecOutcome> {
       }
     }
   }
+  } 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
@@ -279,6 +422,14 @@ export async function executeStep(opts: ExecOptions): Promise<ExecOutcome> {
     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}`);
       status = "failed";
@@ -475,9 +626,13 @@ function runVerify(
   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

package/src/storage.ts

@@ -302,8 +302,14 @@ export function s3Config(): S3Config | null {
   };
 }
 
-const sha256 = (b: crypto.BinaryLike) => crypto.createHash("sha256").update(b).digest("hex");
-const hmac = (key: crypto.BinaryLike, data: string) =>
+// Narrower than crypto.BinaryLike on purpose. BinaryLike also covers views
+// over a SharedArrayBuffer, which .update() has never accepted and which
+// @types/node 26 finally says so about — the old typings let this compile by
+// being vaguer than the runtime. Every caller here passes a string or a
+// Buffer, so this is the honest signature, not a workaround.
+type Hashable = string | Uint8Array;
+const sha256 = (b: Hashable) => crypto.createHash("sha256").update(b).digest("hex");
+const hmac = (key: Hashable, data: string) =>
   crypto.createHmac("sha256", key).update(data, "utf8").digest();
 
 /** RFC 3986. encodeURIComponent leaves !'()* alone and SigV4 does not. */