taskflow-core 0.1.6 → 0.1.8

package/dist/runtime.js

@@ -29,7 +29,12 @@ const noRunnerInjected = async (_cwd, _agents, agentName, task) => ({
 import { aggregateUsage, emptyUsage } from "./usage.js";
 import { dependenciesOf, finalPhase, LOOP_DEFAULT_MAX_ITERATIONS, LOOP_HARD_MAX_ITERATIONS, MAX_DYNAMIC_MAP_ITEMS, MAX_DYNAMIC_NESTING, parseTtlMs, resolveArgs, topoLayers, TOURNAMENT_DEFAULT_VARIANTS, TOURNAMENT_HARD_MAX_VARIANTS, validateTaskflow } from "./schema.js";
 import { verifyTaskflow } from "./verify.js";
-import { combineScores, combineWithJudge, evaluatePureScorer, formatScorerReport, parseJudgeOutput, SCORE_DEFAULT_THRESHOLD, scoreResultJSON, scorerShapeErrors } from "./scorers.js";
+import { combineScores, combineWithJudge, evaluatePureScorer, formatScorerReport, parseJudgeOutput, SCORE_DEFAULT_THRESHOLD, scoreResultJSON, scorerShapeErrors, WINNER_TOKEN_RE } from "./scorers.js";
+import { parseGateVerdict, overBudget as overBudgetCheck } from "./deterministic.js";
+import {} from "./trace.js";
+// Re-export so existing `import { parseGateVerdict } from "./runtime.ts"` callers
+// (and tests) keep working; the implementation now lives in deterministic.ts.
+export { parseGateVerdict };
 import { runCodeCompilesScorer } from "./scorer-runtime.js";
 import { buildReflexionSummary, isContractViolation, REFLEXION_SENTINEL } from "./reflexion.js";
 import { hashInput, newRunId, runsDir } from "./store.js";
@@ -268,14 +273,12 @@ function overBudget(state) {
     const budget = state.def.budget;
     if (!budget)
         return { over: false, reason: "" };
-    const u = aggregateUsage(Object.values(state.phases).map((p) => p.usage ?? emptyUsage()));
-    if (budget.maxUSD !== undefined && u.cost > budget.maxUSD) {
-        return { over: true, reason: `cost $${u.cost.toFixed(3)} exceeded cap $${budget.maxUSD}` };
-    }
-    if (budget.maxTokens !== undefined && u.input + u.output > budget.maxTokens) {
-        return { over: true, reason: `tokens ${u.input + u.output} exceeded cap ${budget.maxTokens}` };
-    }
-    return { over: false, reason: "" };
+    const input = {
+        maxUSD: budget.maxUSD,
+        maxTokens: budget.maxTokens,
+        usages: Object.values(state.phases).map((p) => p.usage ?? emptyUsage()),
+    };
+    return overBudgetCheck(input);
 }
 /** Merge several sub-results into a single PhaseState (for map/parallel). */
 function mergePhaseState(id, results, inputHash, parseJson) {
@@ -331,6 +334,55 @@ function mergePhaseState(id, results, inputHash, parseJson) {
  * A live-update sink that mirrors a subagent's streaming progress into a single
  * phase's state row, then notifies the TUI. Shared by all single-agent phases.
  */
+/** Fail-open trace emit: a throwing/missing sink must NEVER crash a run.
+ *  Mirrors the `safeEmit` discipline used for `persist`/`onProgress`. */
+function traceEmit(deps, event) {
+    try {
+        deps.trace?.emit(event);
+    }
+    catch {
+        /* trace is best-effort; never run-breaking */
+    }
+}
+/** Fail-open trace flush at phase-end. */
+function traceFlush(deps, phaseId) {
+    try {
+        deps.trace?.flush(phaseId);
+    }
+    catch {
+        /* trace is best-effort; never run-breaking */
+    }
+}
+/** Emit a `decision: unreplayable` marker for a phase whose inputs the trace
+ *  cannot fully capture (Shared Context Tree, inner sub-flows, context files,
+ *  unobservable interpolation deps). A future replay marks such phases
+ *  `needs-live-rerun` instead of silently reusing a recorded output.
+ *  Single-phase analog of `hasUnobservedDependencies`. Fail-open. */
+function emitUnreplayableMarker(deps, state, phase) {
+    const reason = unreplayableReason(state, phase);
+    if (!reason)
+        return;
+    traceEmit(deps, {
+        ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "decision",
+        decision: { type: "unreplayable", reason },
+    });
+}
+/** Why (if at all) a single phase cannot be deterministically replayed. */
+function unreplayableReason(state, phase) {
+    if (phase.shareContext === true || state.def.contextSharing === true)
+        return "context-sharing";
+    if (phase.type === "flow")
+        return "inner-flow";
+    if (phase.context && phase.context.length > 0)
+        return "context-files";
+    // Interpolation refs that don't resolve through steps.*/args.*/item.* are
+    // unobservable to the trace (previous.output is observable via dependsOn).
+    const scan = (text) => !!text && /\{(previous\.output|item\b|item\.)/.test(text);
+    if (scan(phase.task) || scan(phase.when) || scan(phase.until) || (Array.isArray(phase.eval) && phase.eval.some(scan))) {
+        return "unobservable-deps";
+    }
+    return undefined;
+}
 function liveSink(state, phaseId, emitProgress) {
     return (l) => {
         const live = state.phases[phaseId];
@@ -556,6 +608,38 @@ async function runSpawnedChildren(assignments, ctxDir, parentNodeId, phase, deps
     return { reports: `\n\n<!-- ctx_spawn: ${lines.length} child report(s) -->\n${lines.join("\n\n")}`, usage };
 }
 async function executePhase(phase, state, deps, prior, emitProgress, _retryDepth = 0, opts) {
+    // Trace: phase-start (fail-open). Record whether this phase is replayable
+    // up front so a future replay can short-circuit it without walking events.
+    traceEmit(deps, { ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "phase-start" });
+    if (deps.trace)
+        emitUnreplayableMarker(deps, state, phase);
+    let result;
+    let threw = false;
+    try {
+        result = await executePhaseImpl(phase, state, deps, prior, emitProgress, _retryDepth, opts);
+    }
+    catch (e) {
+        threw = true;
+        // Trace: phase-end on failure (fail-open) before re-throwing.
+        traceEmit(deps, {
+            ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "phase-end",
+            status: "failed", error: e instanceof Error ? e.message : String(e),
+        });
+        traceFlush(deps, phase.id);
+        throw e;
+    }
+    if (threw)
+        return result; // unreachable; satisfies TS
+    // Trace: phase-end with the real status, then flush buffered events.
+    traceEmit(deps, {
+        ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "phase-end",
+        status: result.status, error: result.error,
+    });
+    traceFlush(deps, phase.id);
+    return result;
+}
+/** The pre-trace body of executePhase (workspace lifecycle + stamping). */
+async function executePhaseImpl(phase, state, deps, prior, emitProgress, _retryDepth = 0, opts) {
     // Side-effect classification: stamp the marker at the single exit point so
     // every type branch inside executePhaseInner is covered. A skipped phase ran
     // nothing — no side effect to record.
@@ -855,6 +939,29 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         if (usages.length > 1)
             last.usage = aggregateUsage(usages);
         last.attempts = usages.length;
+        // Trace: record this subagent call (the load-bearing record a future
+        // replay consumes). Fail-open. nodePath carries the item/variant
+        // discriminator (e.g. "review", "review-item-3", "gate-judge").
+        traceEmit(deps, {
+            ts: Date.now(),
+            runId: state.runId,
+            phaseId: phase.id,
+            kind: "subagent-call",
+            input: {
+                agent: agentName,
+                model: phase.model,
+                task,
+                preRead,
+                nodePath: ctxNodeId ?? phase.id,
+                attempt: usages.length > 0 ? usages.length - 1 : undefined,
+            },
+            output: {
+                text: last.output,
+                model: last.model,
+                usage: last.usage,
+                stopReason: last.stopReason,
+            },
+        });
         return last;
     };
     const parseJson = phase.output === "json";
@@ -1162,7 +1269,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                     if (phase.task) {
                         const agentName = resolveAgent(phase.agent, deps, state);
                         const text = interpolate(phase.task, freshCtx).text;
-                        const fullTask = `${preRead}${text}\n\n---\n\n${report}`;
+                        const fullTask = appendGateFormatSuffix(`${preRead}${text}\n\n---\n\n${report}`, phase);
                         const ckT = cacheKeys(cc, [phase.id, agentName, phase.model ?? "", fullTask, scoreId]);
                         const inputHash = ckT.key;
                         const cachedT = cachedPhase(cc, ckT);
@@ -1253,7 +1360,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             const interpM = interpolate(phase.task ?? "", ctx);
             const textM = interpM.text;
             const refWarningM = warnUnresolvedRefs(phase.id, interpM.missing);
-            const fullTaskM = preRead + textM;
+            const fullTaskM = appendGateFormatSuffix(preRead + textM, phase);
             const agentNameM = resolveAgent(phase.agent, deps, state);
             const ckM = cacheKeys(cc, [phase.id, agentNameM, phase.model ?? "", fullTaskM]);
             const cachedM = cachedPhase(cc, ckM);
@@ -1272,7 +1379,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         const interp = interpolate(phase.task ?? "", ctx);
         const text = interp.text;
         const refWarning = warnUnresolvedRefs(phase.id, interp.missing);
-        const fullTask = preRead + text;
+        const fullTask = appendGateFormatSuffix(preRead + text, phase);
         const agentName = resolveAgent(phase.agent, deps, state);
         const ck = cacheKeys(cc, [phase.id, agentName, phase.model ?? "", fullTask]);
         const inputHash = ck.key;
@@ -1285,8 +1392,16 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             ps.reads = readRefsToReads(readRefs, state);
         if (refWarning)
             ps.warnings = [...(ps.warnings ?? []), refWarning];
-        if (type === "gate" && ps.status === "done")
+        if (type === "gate" && ps.status === "done") {
             ps.gate = parseGateVerdict(r.output);
+            // Trace: record the gate verdict decision (fail-open). A future replay
+            // re-adjudicates this against a changed threshold.
+            if (ps.gate)
+                traceEmit(deps, {
+                    ts: Date.now(), runId: state.runId, phaseId: phase.id, kind: "decision",
+                    decision: { type: "gate-verdict", value: ps.gate.verdict, reason: ps.gate.reason },
+                });
+        }
         // Shared Context Tree: register this node, mark its terminal status, and
         // pick up any ctx_spawn intents the subagent queued. The spawned child
         // tasks run here (supervision loop) and their reports are folded into this
@@ -1339,7 +1454,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 }
                 const retryCtx = buildInterpolationContext(state, lastCompletedOutput(state, phase));
                 const retryText = interpolate(phase.task ?? "", retryCtx).text;
-                const retryTask = preRead + retryText;
+                const retryTask = appendGateFormatSuffix(preRead + retryText, phase);
                 const retryIH = cacheKeys(cc, [phase.id, agentName, phase.model ?? "", retryTask]).key;
                 const retryR = await runOne(agentName, retryTask, liveSink(state, phase.id, emitProgress), undefined, contractCheck);
                 gatePs = resultToPhaseState(phase.id, retryR, retryIH, parseJson);
@@ -2354,38 +2469,50 @@ function defaultAgent(deps) {
     return deps.agents[0]?.name ?? "default";
 }
 /**
- * Parse a gate phase's output into a verdict. Blocks the flow only on an
- * explicit negative signal; ambiguous output passes (fail-open).
- * Accepts JSON ({continue|pass: bool} or {verdict: "..."}) or a text marker
- * `VERDICT: PASS|BLOCK|FAIL|STOP|OK|REJECT|HALT` (last occurrence wins).
+ * Parse a gate phase's output into a verdict. Blocks the flow on an explicit
+ * negative signal OR on ambiguous, unparseable model output. Accepts JSON
+ * ({continue|pass: bool} or {verdict: "..."}) or a text marker
+ * `VERDICT: PASS|BLOCK|FAIL|STOP|OK|REJECT|HALT` (last occurrence wins). The text
+ * matcher tolerates common Markdown emphasis around the verdict word
+ * (`VERDICT: **BLOCK**`, `### VERDICT: __BLOCK__`, `VERDICT: `BLOCK``) so a
+ * genuine BLOCK is never silently downgraded to PASS (issue #54).
+ *
+ * **Fail-closed:** if the model produced output but no verdict could be parsed,
+ * the gate BLOCKS. A gate that cannot reach a verdict cannot be trusted to pass;
+ * halting is recoverable (prior phases persist, the run is resumable) whereas a
+ * rubber-stamped PASS is silent and potentially ships broken work. Note that a
+ * JSON verdict object whose value is non-blocking (e.g. `{"verdict":"No issues
+ * found"}`) is an *explicit* pass, not ambiguity, and still resolves to pass.
  */
-export function parseGateVerdict(output) {
-    const json = safeParse(output);
-    if (json && typeof json === "object") {
-        const o = json;
-        if (typeof o.continue === "boolean")
-            return { verdict: o.continue ? "pass" : "block", reason: asReason(o.reason) };
-        if (typeof o.pass === "boolean")
-            return { verdict: o.pass ? "pass" : "block", reason: asReason(o.reason) };
-        if (typeof o.verdict === "string") {
-            // Note: do NOT include standalone "no" — natural-language verdicts like
-            // "No issues found" / "no errors" would otherwise be false-positive BLOCK.
-            // Fail-open covers any ambiguous text.
-            const block = /block|fail|stop|reject|halt/i.test(o.verdict);
-            return { verdict: block ? "block" : "pass", reason: asReason(o.reason) };
-        }
-    }
-    const matches = [...output.matchAll(/VERDICT\s*[:=]\s*(PASS|BLOCK|FAIL|STOP|OK|REJECT|HALT)/gi)];
-    if (matches.length) {
-        const v = matches[matches.length - 1][1].toUpperCase();
-        const pass = v === "PASS" || v === "OK";
-        return { verdict: pass ? "pass" : "block" };
-    }
-    return { verdict: "pass" };
-}
+// `parseGateVerdict` is implemented in `deterministic.ts` (a pure seam a
+// future replay can import without dragging in the process-spawning runner).
+// It is imported at the top of this file and re-exported from the barrel.
 function asReason(v) {
     return typeof v === "string" && v.trim() ? v.trim() : undefined;
 }
+/**
+ * If a gate phase relies on free-text verdict parsing (no `output:"json"` +
+ * `expect` contract) and its task does not already demand a `VERDICT:` marker,
+ * append a hard output-format suffix. This pushes the model toward the exact
+ * machine-readable terminator the parser expects, so a genuine verdict is not
+ * lost to an authoring slip or a model that "forgets" to emit one (issue #54).
+ * When the phase already enforces a JSON contract, no suffix is needed — the
+ * `expect` schema validates the output deterministically.
+ */
+function appendGateFormatSuffix(task, phase) {
+    // Only free-text GATE phases need the verdict terminator. Agent/map/reduce/loop
+    // phases pass through untouched — they have no verdict to parse.
+    if (phase.type !== "gate")
+        return task;
+    if (phase.output === "json" && phase.expect)
+        return task;
+    // Already asks for a verdict marker (any case) — don't duplicate.
+    if (/VERDICT\s*[:=]/i.test(task))
+        return task;
+    return (`${task}\n\n--- Required output format ---\n` +
+        `End your response with exactly one line in this exact form (no Markdown, no bold, no extra words):\n` +
+        `VERDICT: PASS\nor\nVERDICT: BLOCK`);
+}
 /**
  * Parse a judge's pick of the winning variant. Accepts JSON ({"winner":n} or
  * {"best":n}) or a `WINNER: n` line (last match wins). Clamps to [1, count].
@@ -2402,7 +2529,7 @@ export function parseTournamentWinner(output, count) {
         if (Number.isFinite(n))
             return { winner: clamp(n), reason: asReason(o.reason) };
     }
-    const matches = [...output.matchAll(/WINNER\s{0,20}[:=]\s{0,20}#?\s{0,20}(\d+)/gi)];
+    const matches = [...output.matchAll(WINNER_TOKEN_RE)];
     if (matches.length) {
         const n = Number(matches[matches.length - 1][1]);
         if (Number.isFinite(n))