taskflow-core 0.1.3 → 0.1.4

package/dist/runtime.js

@@ -12,6 +12,7 @@
 import * as path from "node:path";
 import * as fs from "node:fs";
 import { coerceArray, evaluateCondition, interpolate, safeParse, tryEvaluateCondition } from "./interpolate.js";
+import { contractViolations } from "./contract.js";
 import { isFailed, isTransientError, mapWithConcurrencyLimit } from "./runner-core.js";
 /** Default runner used when no host injected one: fail loudly rather than
  *  silently spawn anything (core is host-neutral and cannot spawn pi/codex). */
@@ -100,6 +101,7 @@ function resultToPhaseState(id, r, inputHash, parseJson) {
         usage: r.usage,
         model: r.model,
         attempts: attempts > 1 ? attempts : undefined,
+        timedOut: r.phaseTimeout || undefined,
         error: failed ? r.errorMessage || r.stderr || r.output : undefined,
         inputHash,
         endedAt: Date.now(),
@@ -314,6 +316,7 @@ function mergePhaseState(id, results, inputHash, parseJson) {
         usage,
         model,
         attempts: attempts > results.length ? attempts : undefined,
+        timedOut: ran.some((r) => r.phaseTimeout) || undefined,
         budgetTruncated: budgetSkips.length > 0 || undefined,
         subProgress: { done: ran.length, total: results.length, running: 0, failed: failedCount },
         error: errors.length ? errors.join("; ") : undefined,
@@ -648,7 +651,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     // each run (schema already rejects explicit cross-run, but the default-scope
     // path must also be blocked). If flowDefHash failed, cross-run is unsafe
     // because the key degrades to flowName-only and reopens cross-flow collisions.
-    const CROSS_RUN_BLOCKED_TYPES = new Set(["gate", "approval", "loop", "tournament"]);
+    const CROSS_RUN_BLOCKED_TYPES = new Set(["gate", "approval", "loop", "tournament", "script"]);
     if (cacheScope === "cross-run" && CROSS_RUN_BLOCKED_TYPES.has(type)) {
         cacheScope = "run-only";
     }
@@ -671,12 +674,12 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         tools: phase.tools,
         preRead,
     };
-    const baseRun = (agentName, task, onLive, ctxNodeId) => run(effCwd, deps.agents, agentName, task, {
+    const baseRun = (agentName, task, onLive, ctxNodeId, signal) => run(effCwd, deps.agents, agentName, task, {
         model: phase.model,
         thinking: phase.thinking,
         tools: phase.tools,
         cwd: effCwd,
-        signal: deps.signal,
+        signal: signal ?? deps.signal,
         onLive,
         ctxDir: ctxDir,
         nodeId: ctxDir ? ctxNodeId : undefined,
@@ -693,7 +696,12 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     const DEFAULT_TRANSIENT_RETRIES = 3;
     const DEFAULT_TRANSIENT_BACKOFF_MS = 2000;
     const DEFAULT_TRANSIENT_FACTOR = 2;
-    const runOne = async (agentName, task, onLive, ctxNodeId) => {
+    // Per-phase timeout: caps EACH subagent call of an agent-running phase.
+    // (script phases enforce their own child-process timeout — see the script branch.)
+    const phaseTimeoutMs = type !== "script" && typeof phase.timeout === "number" && Number.isFinite(phase.timeout) && phase.timeout >= 1000
+        ? phase.timeout
+        : undefined;
+    const runOne = async (agentName, task, onLive, ctxNodeId, check) => {
         const explicitMax = Math.max(1, 1 + Math.max(0, Math.floor(retry?.max ?? 0)));
         // Allow enough attempts to cover whichever policy applies on a given attempt.
         const maxAttempts = Math.max(explicitMax, 1 + DEFAULT_TRANSIENT_RETRIES);
@@ -702,8 +710,65 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
             if (deps.signal?.aborted)
                 break;
-            last = await baseRun(agentName, task, onLive, ctxNodeId);
+            // Phase timeout — an AbortController chained to the run's signal that also
+            // fires after `phase.timeout` ms. Deterministic: a timed-out call is never
+            // retried (retrying a call that just burned its full cap would double-spend).
+            let timedOut = false;
+            let timer;
+            let onParentAbort;
+            let callSignal;
+            if (phaseTimeoutMs) {
+                const ac = new AbortController();
+                callSignal = ac.signal;
+                if (deps.signal?.aborted)
+                    ac.abort();
+                else if (deps.signal) {
+                    onParentAbort = () => ac.abort();
+                    deps.signal.addEventListener("abort", onParentAbort, { once: true });
+                }
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    ac.abort();
+                }, phaseTimeoutMs);
+            }
+            try {
+                last = await baseRun(agentName, task, onLive, ctxNodeId, callSignal);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                if (onParentAbort)
+                    deps.signal?.removeEventListener("abort", onParentAbort);
+            }
+            if (timedOut) {
+                // Reclassify the abort as a phase timeout: a distinct, deterministic
+                // failure (stopReason "error" keeps it in the failed bucket; the
+                // phaseTimeout marker excludes it from transient retry).
+                last = {
+                    ...last,
+                    exitCode: last.exitCode === 0 ? 1 : last.exitCode,
+                    stopReason: "error",
+                    errorMessage: `Phase timed out after ${phaseTimeoutMs}ms (subagent aborted)`,
+                    phaseTimeout: true,
+                };
+                usages.push(last.usage);
+                break;
+            }
             usages.push(last.usage);
+            // Output contract (`expect`): a successful attempt whose JSON output
+            // violates the declared contract is a failure — eligible for the phase's
+            // explicit retry policy (never the transient fallback).
+            if (check && !isFailed(last)) {
+                const violations = check(last);
+                if (violations.length > 0) {
+                    last = {
+                        ...last,
+                        exitCode: last.exitCode === 0 ? 1 : last.exitCode,
+                        stopReason: "error",
+                        errorMessage: `Output contract violated:\n- ${violations.join("\n- ")}`,
+                    };
+                }
+            }
             // B6: aggregate and surface cumulative usage before the retry decision,
             // so the TUI / budget guard see the in-flight spend on every attempt.
             const liveRetry = state.phases[phase.id];
@@ -759,6 +824,17 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         return last;
     };
     const parseJson = phase.output === "json";
+    // Output contract (`expect`): validates the parsed JSON output of a finished
+    // subagent call. Wired into `runOne` so a violation counts as a failed attempt
+    // (retryable under the phase's explicit `retry` policy).
+    const contractCheck = phase.expect !== undefined && parseJson
+        ? (r) => {
+            const parsed = safeParse(r.output);
+            if (parsed === undefined)
+                return ["$: output is not valid JSON (contract could not be checked)"];
+            return contractViolations(parsed, phase.expect);
+        }
+        : undefined;
     // Runs a list of sub-tasks with live fan-out progress + aggregate live usage/activity.
     // `perItem` (map only) enables per-item cross-run caching: each item is looked
     // up in the cache before spawning a subagent, and a successful fresh item is
@@ -959,7 +1035,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         const cached = cachedPhase(cc, ck);
         if (cached)
             return cached;
-        const r = await runOne(agentName, fullTask, liveSink(state, phase.id, emitProgress), nodeIdFor());
+        const r = await runOne(agentName, fullTask, liveSink(state, phase.id, emitProgress), nodeIdFor(), contractCheck);
         const ps = resultToPhaseState(phase.id, r, inputHash, parseJson);
         if (readRefs.length)
             ps.reads = readRefsToReads(readRefs, state);
@@ -1021,7 +1097,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 const retryText = interpolate(phase.task ?? "", retryCtx).text;
                 const retryTask = preRead + retryText;
                 const retryIH = cacheKeys(cc, [phase.id, agentName, phase.model ?? "", retryTask]).key;
-                const retryR = await runOne(agentName, retryTask, liveSink(state, phase.id, emitProgress));
+                const retryR = await runOne(agentName, retryTask, liveSink(state, phase.id, emitProgress), undefined, contractCheck);
                 gatePs = resultToPhaseState(phase.id, retryR, retryIH, parseJson);
                 if (gatePs.status === "done")
                     gatePs.gate = parseGateVerdict(retryR.output);
@@ -1035,6 +1111,157 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         recordCache(cc, ps);
         return ps;
     }
+    // script — zero-token shell command. Spawns a child process, pipes
+    // interpolated `input` to stdin, captures stdout as the phase output.
+    if (type === "script") {
+        const cmd = phase.run;
+        if (!cmd) {
+            return {
+                id: phase.id,
+                status: "failed",
+                error: "script phase requires 'run'",
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            };
+        }
+        // Interpolate the command.
+        // Array form: interpolate each element (safe — schema rejects placeholders in string form).
+        // String form: skip interpolation — schema already guarantees no {placeholders}.
+        const interpRun = Array.isArray(cmd)
+            ? cmd.map((s) => interpolate(s, ctx))
+            : [{ text: cmd, missing: [] }];
+        // Warn unresolved references.
+        for (const r of interpRun) {
+            if (r.missing.length)
+                warnUnresolvedRefs(phase.id, r.missing);
+        }
+        const interpRunText = interpRun.map((r) => r.text);
+        // Interpolate stdin input if provided.
+        const stdinInterp = phase.input !== undefined ? interpolate(phase.input, ctx) : undefined;
+        if (stdinInterp?.missing.length)
+            warnUnresolvedRefs(phase.id, stdinInterp.missing);
+        const stdinInput = stdinInterp?.text;
+        const ck = cacheKeys(cc, [phase.id, JSON.stringify(interpRunText), stdinInput ?? ""]);
+        const inputHash = ck.key;
+        const cached = cachedPhase(cc, ck);
+        if (cached)
+            return cached;
+        const MAX_STDOUT = 1_048_576; // 1 MB cap
+        const SCRIPT_TIMEOUT_MS = (phase.timeout ?? 60_000); // default 60 s, configurable via phase.timeout
+        const SIGKILL_GRACE_MS = 5_000; // grace period after SIGTERM before SIGKILL
+        try {
+            const { spawn } = await import("node:child_process");
+            const result = await new Promise((resolve, reject) => {
+                // Array command → direct spawn (safe); string → shell (rejected at validation if it has placeholders).
+                const child = Array.isArray(cmd)
+                    ? spawn(interpRunText[0], interpRunText.slice(1), {
+                        cwd: effCwd,
+                        env: process.env,
+                        shell: false,
+                        signal: deps.signal,
+                    })
+                    : spawn(interpRunText[0], [], {
+                        cwd: effCwd,
+                        env: process.env,
+                        shell: true,
+                        signal: deps.signal,
+                    });
+                let stdout = "";
+                let stderr = "";
+                let stdoutOversize = false;
+                let timedOut = false;
+                child.stdout?.on("data", (d) => {
+                    if (stdout.length < MAX_STDOUT) {
+                        const need = MAX_STDOUT - stdout.length;
+                        stdout += d.toString().slice(0, need);
+                        if (stdout.length >= MAX_STDOUT)
+                            stdoutOversize = true;
+                    }
+                });
+                child.stderr?.on("data", (d) => {
+                    if (stderr.length < 500) {
+                        stderr += d.toString().slice(0, 500 - stderr.length);
+                    }
+                });
+                // Timeout guard: SIGTERM first, then SIGKILL after grace period.
+                let sigkillTimer;
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    child.kill("SIGTERM");
+                    // SIGKILL fallback if process ignores SIGTERM.
+                    sigkillTimer = setTimeout(() => {
+                        try {
+                            child.kill("SIGKILL");
+                        }
+                        catch { /* already dead */ }
+                    }, SIGKILL_GRACE_MS);
+                }, SCRIPT_TIMEOUT_MS);
+                child.on("error", (err) => {
+                    clearTimeout(timer);
+                    clearTimeout(sigkillTimer);
+                    reject(err);
+                });
+                child.on("close", (code) => {
+                    clearTimeout(timer);
+                    clearTimeout(sigkillTimer);
+                    resolve({ stdout, stderr, code, stdoutOversize, timedOut });
+                });
+                if (stdinInput !== undefined) {
+                    child.stdin?.on("error", () => { }); // swallow EPIPE when child closes stdin early
+                    child.stdin?.write(stdinInput);
+                    child.stdin?.end();
+                }
+            });
+            if (result.code !== 0 || result.timedOut) {
+                const ps = {
+                    id: phase.id,
+                    status: "failed",
+                    output: result.stdout,
+                    error: result.timedOut
+                        ? `Script timed out after ${SCRIPT_TIMEOUT_MS}ms`
+                        : `Script exited with code ${result.code}${result.stderr ? ": " + result.stderr.slice(0, 500) : ""}${result.stdoutOversize ? " [stdout truncated at 1 MB]" : ""}`,
+                    timedOut: result.timedOut || undefined,
+                    usage: emptyUsage(),
+                    inputHash,
+                    endedAt: Date.now(),
+                };
+                if (readRefs.length)
+                    ps.reads = readRefsToReads(readRefs, state);
+                // Non-zero exit: cache (deterministic failure). Timeout: don't cache (transient, like spawn errors).
+                if (!result.timedOut)
+                    recordCache(cc, ps);
+                return ps;
+            }
+            const ps = {
+                id: phase.id,
+                status: "done",
+                output: result.stdout.trimEnd() + (result.stdoutOversize ? "\n[stdout truncated at 1 MB]" : ""),
+                usage: emptyUsage(),
+                inputHash,
+                endedAt: Date.now(),
+            };
+            if (readRefs.length)
+                ps.reads = readRefsToReads(readRefs, state);
+            recordCache(cc, ps);
+            return ps;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // Note: intentionally NOT cached — spawn errors (ENOENT, permission denied, etc.)
+            // are treated as transient. The phase will re-execute on resume/retry.
+            const ps = {
+                id: phase.id,
+                status: "failed",
+                error: `Script error: ${msg}`,
+                usage: emptyUsage(),
+                inputHash,
+                endedAt: Date.now(),
+            };
+            if (readRefs.length)
+                ps.reads = readRefsToReads(readRefs, state);
+            return ps;
+        }
+    }
     if (type === "parallel") {
         const branches = (phase.branches ?? []).map((b) => {
             const r = interpolate(b.task, ctx);
@@ -1416,7 +1643,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 loop: { iteration: i, lastOutput, maxIterations: maxIters },
             }, (ref) => readRefs.push(ref));
             const body = preRead + interpolate(phase.task ?? "", bodyCtx).text;
-            const r = await runOne(agentName, body, liveSink(state, phase.id, emitProgress));
+            const r = await runOne(agentName, body, liveSink(state, phase.id, emitProgress), undefined, contractCheck);
             usages.push(r.usage);
             if (isFailed(r)) {
                 failedResult = r;
@@ -1457,6 +1684,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 status: "failed",
                 output: lastOutput || undefined,
                 usage: aggUsage,
+                timedOut: failedResult?.phaseTimeout || undefined,
                 error: failedResult?.errorMessage || failedResult?.stderr || (stop === "aborted" ? "Aborted" : `loop '${phase.id}' iteration ${iterations} failed`),
                 loop: { iterations, stop },
                 warnings: loopWarnings.length ? loopWarnings : undefined,
@@ -1518,6 +1746,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 status: "failed",
                 usage: variantUsage,
                 error: `tournament '${phase.id}': all ${competitors.length} variants failed`,
+                timedOut: ran.some((r) => r.phaseTimeout) || undefined,
                 budgetTruncated: budgetSkipCount > 0 || undefined,
                 tournament: { variants: competitors.length, winner: 0, mode },
                 inputHash,