clinkx 0.2.0 → 0.2.2

package/clinkx-workflows/dist/engine.js

@@ -0,0 +1,1044 @@
+/**
+ * Workflow execution engine for ordered linear stages.
+ *
+ * ## Timeout Ownership Model (3-8)
+ *
+ * Timeouts in clinkx-workflows operate at three distinct layers, each with
+ * clear ownership boundaries:
+ *
+ * ### Layer 1: Workflow-level deadline (engine-owned)
+ *
+ * The engine creates an AbortController with a deadline derived from
+ * `settings.timeout_seconds` (default: CLINKX_WORKFLOWS_TIMEOUT_SECONDS,
+ * 1800s). This is a hard wall clock ceiling for the entire workflow run.
+ * When exceeded, remaining stages are aborted and the run fails with
+ * a clear timeout error.
+ *
+ * Owner: WorkflowEngine.createDeadlineController()
+ * Config: CLINKX_WORKFLOWS_TIMEOUT_SECONDS (default: 1800)
+ * Scope: Entire workflow run
+ *
+ * ### Layer 2: Per-call parent-side timeout (engine-owned)
+ *
+ * Each tools/call RPC to the child has a parent-side timeout computed as:
+ *   max(call.timeout_seconds * 1000 + CALL_TIMEOUT_BUFFER_MS, DEFAULT_PARENT_CALL_TIMEOUT_MS)
+ *
+ * This prevents individual calls from blocking indefinitely. The buffer
+ * (CALL_TIMEOUT_BUFFER_MS = 5s) accounts for child-side teardown latency.
+ * DEFAULT_PARENT_CALL_TIMEOUT_MS (600s = 10min) is the floor — even calls
+ * without explicit timeout_seconds get a parent-side deadline.
+ *
+ * Owner: WorkflowEngine.invokeCall()
+ * Config: Per-call timeout_seconds in workflow definition
+ * Scope: Single tools/call RPC round-trip
+ *
+ * ### Layer 3: Child-side timeout (adapter-owned, NOT engine-controlled)
+ *
+ * The ClinkX child's own timeout behavior is controlled by adapter JSON
+ * config (codex.json:9, claude.json:8 — both set timeout_seconds: 3600).
+ * The env vars CLINKX_TIMEOUT_SECONDS, CLINKX_IDLE_TIMEOUT_SECONDS, and
+ * CLINKX_IDLE_TIMEOUT_STARTUP_SECONDS are DEAD KNOBS with current shipped
+ * adapters — adapter JSON config wins (runner.ts:156-171).
+ *
+ * The workflow engine does NOT attempt to control child-side timeouts via
+ * env vars. Instead:
+ * - Per-call `timeout_seconds` in the workflow definition is passed as a
+ *   hidden field in the ClinkInput payload, which the child uses for
+ *   UPWARD EXTENSION ONLY (extends beyond adapter floor, never shortens).
+ * - If different child timeout/idle floors are needed, point the child at
+ *   a workflow-specific adapter bundle via CLINKX_WORKFLOWS_CHILD_CONFIG_PATH.
+ *
+ * Owner: Adapter JSON config in the child's config path
+ * Config: CLINKX_WORKFLOWS_CHILD_CONFIG_PATH for custom adapter bundles
+ * Scope: Single subprocess spawn within the child
+ *
+ * ### Interaction between layers
+ *
+ * The workflow deadline (L1) takes precedence: if it fires, all in-flight
+ * calls are cancelled regardless of their per-call timeouts (L2). The
+ * per-call timeout (L2) prevents any single call from consuming the entire
+ * workflow budget. The child-side timeout (L3) is independently enforced
+ * by the child and may fire before L2 — in that case the child returns
+ * isError: true with termination_reason: "wall" or "idle", which the
+ * workflow engine treats as a transient failure eligible for retry.
+ */
+import { stat as fsStat } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { callClink } from "./clink-client.js";
+import { getArtifactsDir, getChildMaxConcurrent, getMaxParallel, getMaxPromptBytes, getStateDir, resolveWorkspaceRoot, } from "./config.js";
+import { CallExecutionError, InvalidCallError, WorkflowCancellationError, WorkflowError, } from "./errors.js";
+import { analyzeOutputFidelity, enforceOutputFidelity } from "./fidelity.js";
+import { validateDynamicPaths } from "./path-validation.js";
+import { estimatePromptBudget, enforcePromptBudget, createPathContributor } from "./prompt-budget.js";
+import { DispatchQueue } from "./queue.js";
+import { renderCallPrompt } from "./template.js";
+import { ArtifactStore } from "./artifacts.js";
+import { getReducer } from "./reducers/index.js";
+import { logger } from "./logger.js";
+/** Default parent-side timeout for a single tools/call RPC (10 minutes). */
+const DEFAULT_PARENT_CALL_TIMEOUT_MS = 600_000;
+/** Buffer added to per-call timeout to account for child-side teardown latency. */
+const CALL_TIMEOUT_BUFFER_MS = 5_000;
+export class WorkflowEngine {
+    definition;
+    session;
+    variables;
+    validatorRegistry;
+    runId;
+    runDir;
+    signal;
+    queueDepth;
+    maxPromptBytes;
+    promptReserveBytes;
+    allowedRoots;
+    hooks;
+    resumeCompletedCalls;
+    resumePreparedInputs;
+    resumeFailedCalls;
+    contextProducingCalls = new Set();
+    artifactStore;
+    constructor(options) {
+        this.definition = options.definition;
+        this.session = options.session;
+        this.variables = options.variables;
+        this.validatorRegistry = options.validatorRegistry;
+        this.runId = options.runId;
+        this.runDir = options.runDir;
+        this.signal = options.signal;
+        this.queueDepth = Math.min(options.maxParallel ?? getMaxParallel(), options.childMaxConcurrent ?? getChildMaxConcurrent());
+        this.maxPromptBytes = options.maxPromptBytes ?? getMaxPromptBytes();
+        this.promptReserveBytes = options.promptReserveBytes;
+        this.allowedRoots = options.allowedRoots ?? this.defaultAllowedRoots();
+        this.hooks = options.hooks ?? {};
+        this.resumeCompletedCalls = options.resume?.completedCalls ?? new Map();
+        this.resumePreparedInputs = options.resume?.preparedInputs ?? new Map();
+        this.resumeFailedCalls = options.resume?.failedCalls ?? new Map();
+        this.artifactStore = new ArtifactStore(options.runDir, options.validatorRegistry);
+        this.validateFinalStage();
+        this.validateAdvertisedCliNames();
+        this.contextProducingCalls = collectContextProducingCalls(this.definition);
+        this.seedResumedArtifacts();
+    }
+    async execute() {
+        const deadlineController = this.createDeadlineController();
+        const stages = [];
+        const startedAt = new Date().toISOString();
+        try {
+            await this.emitRunStateChange({
+                runId: this.runId,
+                workflowName: this.definition.name,
+                state: "running",
+                startedAt,
+            });
+            await this.emitProgress({
+                runId: this.runId,
+                workflowName: this.definition.name,
+                scope: "run",
+                state: "running",
+                message: `Workflow ${this.definition.name} is running`,
+            });
+            await this.validateInputPathsExist();
+            for (let stageIndex = 0; stageIndex < this.definition.stages.length; stageIndex += 1) {
+                this.throwIfAborted(deadlineController.signal);
+                const stage = this.definition.stages[stageIndex];
+                logger.info({ run_id: this.runId, stage_id: stage.id }, "executing workflow stage");
+                await this.emitProgress({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    scope: "stage",
+                    stageId: stage.id,
+                    stageDescription: stage.description,
+                    state: "running",
+                    message: `Stage ${stage.id} is running`,
+                });
+                const executedStage = stage.parallel
+                    ? await this.executeParallelStage(stage, stageIndex, deadlineController.signal)
+                    : await this.executeSequentialStage(stage, stageIndex, deadlineController.signal);
+                const aggregateArtifactPath = this.artifactStore.writeStageAggregate(stage, stageIndex);
+                stages.push({
+                    ...executedStage,
+                    ...(aggregateArtifactPath != null ? { aggregateArtifactPath } : {}),
+                });
+                await this.emitProgress({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    scope: "stage",
+                    stageId: stage.id,
+                    stageDescription: stage.description,
+                    state: executedStage.ok ? "succeeded" : "failed",
+                    message: `Stage ${stage.id} ${executedStage.ok ? "succeeded" : "failed"}`,
+                });
+                if (!executedStage.ok && stage.on_failure === "abort") {
+                    throw new WorkflowError(`Stage ${stage.id} failed and on_failure=abort`);
+                }
+            }
+            const finalStage = stages[stages.length - 1];
+            const finalCall = finalStage?.calls[0];
+            if (finalCall == null || !finalCall.ok || finalCall.outputText == null) {
+                throw new WorkflowError("Final stage did not produce a successful terminal call result");
+            }
+            const completedAt = new Date().toISOString();
+            await this.emitRunStateChange({
+                runId: this.runId,
+                workflowName: this.definition.name,
+                state: "succeeded",
+                startedAt,
+                completedAt,
+            });
+            await this.emitProgress({
+                runId: this.runId,
+                workflowName: this.definition.name,
+                scope: "run",
+                state: "succeeded",
+                message: `Workflow ${this.definition.name} succeeded`,
+            });
+            return {
+                outputText: finalCall.outputText,
+                stages,
+                artifactsDir: this.artifactStore.artifactsDir,
+            };
+        }
+        catch (error) {
+            const completedAt = new Date().toISOString();
+            const message = error instanceof Error ? error.message : String(error);
+            if (error instanceof WorkflowCancellationError) {
+                await this.emitRunStateChange({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    state: "cancelled",
+                    startedAt,
+                    completedAt,
+                    error: message,
+                });
+                await this.emitProgress({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    scope: "run",
+                    state: "cancelled",
+                    message: `Workflow ${this.definition.name} cancelled`,
+                });
+            }
+            else {
+                await this.emitRunStateChange({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    state: "failed",
+                    startedAt,
+                    completedAt,
+                    error: message,
+                    failureClass: classifyFailureClass(error),
+                });
+                await this.emitProgress({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    scope: "run",
+                    state: "failed",
+                    message: `Workflow ${this.definition.name} failed: ${message}`,
+                });
+            }
+            throw error;
+        }
+        finally {
+            deadlineController.dispose();
+        }
+    }
+    async executeParallelStage(stage, stageIndex, signal) {
+        const queue = new DispatchQueue(this.queueDepth);
+        const settled = await Promise.allSettled(stage.calls.map((call, callIndex) => queue.run(async () => this.executeSingleCall(stage, call, stageIndex, callIndex, signal))));
+        const calls = new Array(stage.calls.length);
+        for (let callIndex = 0; callIndex < settled.length; callIndex += 1) {
+            const result = settled[callIndex];
+            if (result.status === "fulfilled") {
+                calls[callIndex] = result.value;
+                continue;
+            }
+            calls[callIndex] = await this.materializeUnexpectedFailure(stage, stage.calls[callIndex], result.reason);
+        }
+        const ok = calls.every((call) => call?.ok === true);
+        return { stageId: stage.id, ok, calls };
+    }
+    async executeSequentialStage(stage, stageIndex, signal) {
+        const calls = [];
+        for (let callIndex = 0; callIndex < stage.calls.length; callIndex += 1) {
+            this.throwIfAborted(signal);
+            const executedCall = await this.executeSingleCall(stage, stage.calls[callIndex], stageIndex, callIndex, signal);
+            calls.push(executedCall);
+            if (!executedCall.ok && stage.on_failure === "abort") {
+                return { stageId: stage.id, ok: false, calls };
+            }
+        }
+        return {
+            stageId: stage.id,
+            ok: calls.every((call) => call.ok),
+            calls,
+        };
+    }
+    async executeSingleCall(stage, call, stageIndex, callIndex, signal) {
+        const startedAt = new Date().toISOString();
+        const startedAtMs = Date.now();
+        const contextProducing = this.contextProducingCalls.has(`${stage.id}.${call.id}`);
+        const callKey = `${stage.id}.${call.id}`;
+        const resumedCall = this.resumeCompletedCalls.get(callKey);
+        if (resumedCall != null) {
+            return resumedCall;
+        }
+        // Handle built-in reducers — no LLM call, no retry loop
+        if (call.reducer != null) {
+            const reducer = getReducer(call.reducer);
+            if (reducer == null) {
+                const message = `Unknown reducer: "${call.reducer}"`;
+                this.artifactStore.noteFailedCall(stage.id, call.id, message);
+                await this.emitCallStateChange({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    stageId: stage.id,
+                    callId: call.id,
+                    state: "failed",
+                    attempt: 1,
+                    retryCount: 0,
+                    startedAt,
+                    completedAt: new Date().toISOString(),
+                    durationMs: Date.now() - startedAtMs,
+                    error: message,
+                    failureClass: "permanent",
+                });
+                return { stageId: stage.id, callId: call.id, ok: false, error: message };
+            }
+            try {
+                const contextArtifacts = this.artifactStore.buildContext(this.definition, call.context_from);
+                const outputText = reducer(contextArtifacts.artifacts);
+                const artifact = this.maybeWriteArtifact(stage, call, stageIndex, callIndex, outputText);
+                const completedAt = new Date().toISOString();
+                const durationMs = Date.now() - startedAtMs;
+                await this.emitCallStateChange({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    stageId: stage.id,
+                    callId: call.id,
+                    state: "succeeded",
+                    attempt: 1,
+                    retryCount: 0,
+                    startedAt,
+                    completedAt,
+                    durationMs,
+                    outputText,
+                    artifact,
+                });
+                await this.emitProgress({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    scope: "call",
+                    stageId: stage.id,
+                    stageDescription: stage.description,
+                    callId: call.id,
+                    state: "succeeded",
+                    attempt: 1,
+                    retryCount: 0,
+                    message: `Call ${callKey} succeeded (reducer: ${call.reducer})`,
+                });
+                return { stageId: stage.id, callId: call.id, ok: true, outputText, artifact };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.artifactStore.noteFailedCall(stage.id, call.id, message);
+                await this.emitCallStateChange({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    stageId: stage.id,
+                    callId: call.id,
+                    state: "failed",
+                    attempt: 1,
+                    retryCount: 0,
+                    startedAt,
+                    completedAt: new Date().toISOString(),
+                    durationMs: Date.now() - startedAtMs,
+                    error: message,
+                    failureClass: "permanent",
+                });
+                return { stageId: stage.id, callId: call.id, ok: false, error: message };
+            }
+        }
+        // Build input ONCE before retry loop — materialized inputs are stable
+        let input;
+        try {
+            input = this.buildCallInput(stage, call, callKey, callIndex);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.artifactStore.noteFailedCall(stage.id, call.id, message);
+            logger.warn({ run_id: this.runId, stage_id: stage.id, call_id: call.id, err: message }, "workflow call input build failed");
+            const completedAt = new Date().toISOString();
+            const durationMs = Date.now() - startedAtMs;
+            await this.emitCallStateChange({
+                runId: this.runId,
+                workflowName: this.definition.name,
+                stageId: stage.id,
+                callId: call.id,
+                state: "failed",
+                attempt: 1,
+                retryCount: 0,
+                startedAt,
+                completedAt,
+                durationMs,
+                error: message,
+                failureClass: "permanent",
+            });
+            await this.emitProgress({
+                runId: this.runId,
+                workflowName: this.definition.name,
+                scope: "call",
+                stageId: stage.id,
+                stageDescription: stage.description,
+                callId: call.id,
+                state: "failed",
+                attempt: 1,
+                retryCount: 0,
+                message: `Call ${callKey} failed: ${message}`,
+            });
+            return {
+                stageId: stage.id,
+                callId: call.id,
+                ok: false,
+                error: message,
+            };
+        }
+        // Read retry config from stage
+        const maxRetries = stage.retry.max_retries;
+        const retryMode = stage.retry.mode;
+        const backoffSeconds = stage.retry.backoff_seconds;
+        const maxBackoffSeconds = stage.retry.max_backoff_seconds;
+        // Emit call prepared ONCE (input is stable across retries)
+        await this.emitCallPrepared({
+            runId: this.runId,
+            workflowName: this.definition.name,
+            stageId: stage.id,
+            callId: call.id,
+            attempt: 1,
+            retryCount: 0,
+            contextProducing,
+            input: structuredClone(input),
+        });
+        let lastError = undefined;
+        let lastFailureClass = "permanent";
+        let lastRetryCount = 0;
+        for (let retryCount = 0; retryCount <= maxRetries; retryCount += 1) {
+            const attempt = retryCount + 1;
+            lastRetryCount = retryCount;
+            this.throwIfAborted(signal);
+            await this.emitCallStateChange({
+                runId: this.runId,
+                workflowName: this.definition.name,
+                stageId: stage.id,
+                callId: call.id,
+                state: "running",
+                attempt,
+                retryCount,
+                startedAt,
+            });
+            await this.emitProgress({
+                runId: this.runId,
+                workflowName: this.definition.name,
+                scope: "call",
+                stageId: stage.id,
+                stageDescription: stage.description,
+                callId: call.id,
+                state: "running",
+                attempt,
+                retryCount,
+                message: retryCount === 0
+                    ? `Call ${callKey} is running`
+                    : `Call ${callKey} is retrying (attempt ${String(attempt)})`,
+            });
+            try {
+                const result = await this.invokeCall(stage, call, input, signal);
+                const fidelity = analyzeOutputFidelity(result.outputText, result.debugMetadata);
+                enforceOutputFidelity(fidelity, {
+                    stageId: stage.id,
+                    callId: call.id,
+                    contextProducing,
+                });
+                const artifact = this.maybeWriteArtifact(stage, call, stageIndex, callIndex, result.outputText);
+                const completedAt = new Date().toISOString();
+                const durationMs = Date.now() - startedAtMs;
+                await this.emitCallStateChange({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    stageId: stage.id,
+                    callId: call.id,
+                    state: "succeeded",
+                    attempt,
+                    retryCount,
+                    startedAt,
+                    completedAt,
+                    durationMs,
+                    outputText: result.outputText,
+                    fidelity,
+                    artifact,
+                });
+                await this.emitProgress({
+                    runId: this.runId,
+                    workflowName: this.definition.name,
+                    scope: "call",
+                    stageId: stage.id,
+                    stageDescription: stage.description,
+                    callId: call.id,
+                    state: "succeeded",
+                    attempt,
+                    retryCount,
+                    message: `Call ${callKey} succeeded`,
+                });
+                return {
+                    stageId: stage.id,
+                    callId: call.id,
+                    ok: true,
+                    outputText: result.outputText,
+                    artifact,
+                    fidelity,
+                };
+            }
+            catch (error) {
+                // Cancellation is never retryable
+                if (error instanceof WorkflowCancellationError) {
+                    const completedAt = new Date().toISOString();
+                    const durationMs = Date.now() - startedAtMs;
+                    await this.emitCallStateChange({
+                        runId: this.runId,
+                        workflowName: this.definition.name,
+                        stageId: stage.id,
+                        callId: call.id,
+                        state: "cancelled",
+                        attempt,
+                        retryCount,
+                        startedAt,
+                        completedAt,
+                        durationMs,
+                        error: error.message,
+                    });
+                    await this.emitProgress({
+                        runId: this.runId,
+                        workflowName: this.definition.name,
+                        scope: "call",
+                        stageId: stage.id,
+                        stageDescription: stage.description,
+                        callId: call.id,
+                        state: "cancelled",
+                        attempt,
+                        retryCount,
+                        message: `Call ${callKey} cancelled`,
+                    });
+                    throw error;
+                }
+                const failureClass = classifyFailureClass(error);
+                lastError = error;
+                lastFailureClass = failureClass;
+                // Determine if this error is retryable
+                const canRetry = retryCount < maxRetries && isRetryable(error, failureClass, retryMode);
+                if (canRetry) {
+                    // Compute backoff with jitter
+                    const delayMs = computeRetryDelay(retryCount, backoffSeconds, maxBackoffSeconds);
+                    const message = error instanceof Error ? error.message : String(error);
+                    logger.info({
+                        run_id: this.runId,
+                        stage_id: stage.id,
+                        call_id: call.id,
+                        attempt,
+                        retry_count: retryCount,
+                        delay_ms: delayMs,
+                        failure_class: failureClass,
+                    }, "scheduling retry");
+                    await this.emitRetryScheduled({
+                        runId: this.runId,
+                        workflowName: this.definition.name,
+                        stageId: stage.id,
+                        callId: call.id,
+                        attempt,
+                        retryCount,
+                        nextRetryCount: retryCount + 1,
+                        delayMs,
+                        error: message,
+                        failureClass,
+                    });
+                    // Wait for backoff delay (abort-aware)
+                    await abortableDelay(delayMs, signal);
+                    continue;
+                }
+                // Not retryable or retries exhausted — fail the call
+                break;
+            }
+        }
+        // All retries exhausted or non-retryable error
+        const message = lastError instanceof Error ? lastError.message : String(lastError);
+        const finalRetryCount = lastRetryCount;
+        const lastChildDebug = lastError instanceof CallExecutionError ? lastError.childDebugMetadata : undefined;
+        this.artifactStore.noteFailedCall(stage.id, call.id, message);
+        logger.warn({ run_id: this.runId, stage_id: stage.id, call_id: call.id, err: message, retries: finalRetryCount }, "workflow call failed");
+        const completedAt = new Date().toISOString();
+        const durationMs = Date.now() - startedAtMs;
+        await this.emitCallStateChange({
+            runId: this.runId,
+            workflowName: this.definition.name,
+            stageId: stage.id,
+            callId: call.id,
+            state: "failed",
+            attempt: finalRetryCount + 1,
+            retryCount: finalRetryCount,
+            startedAt,
+            completedAt,
+            durationMs,
+            error: message,
+            failureClass: lastFailureClass,
+            childDebugMetadata: lastChildDebug,
+        });
+        await this.emitProgress({
+            runId: this.runId,
+            workflowName: this.definition.name,
+            scope: "call",
+            stageId: stage.id,
+            stageDescription: stage.description,
+            callId: call.id,
+            state: "failed",
+            attempt: finalRetryCount + 1,
+            retryCount: finalRetryCount,
+            message: `Call ${callKey} failed: ${message}`,
+        });
+        return {
+            stageId: stage.id,
+            callId: call.id,
+            ok: false,
+            error: message,
+        };
+    }
+    async invokeCall(stage, call, input, signal) {
+        const timeoutMs = call.timeout_seconds != null
+            ? Math.max((call.timeout_seconds * 1000) + CALL_TIMEOUT_BUFFER_MS, DEFAULT_PARENT_CALL_TIMEOUT_MS)
+            : undefined;
+        return await callClink(this.session, input, signal, { stageId: stage.id, callId: call.id }, timeoutMs);
+    }
+    maybeWriteArtifact(stage, call, stageIndex, callIndex, outputText) {
+        const requiresValidation = call.validator_schema_id != null;
+        if (!requiresValidation) {
+            return undefined;
+        }
+        const validatorSchemaId = call.validator_schema_id;
+        if (validatorSchemaId == null) {
+            throw new WorkflowError(`Validated call ${stage.id}.${call.id} must declare validator_schema_id`);
+        }
+        const validated = this.artifactStore.validateJsonOutput(stage.id, call.id, validatorSchemaId, outputText);
+        return this.artifactStore.writeCallArtifact({
+            stage,
+            call,
+            stageIndex,
+            callIndex,
+            validated,
+        });
+    }
+    resolveDynamicPaths(variableName, context) {
+        if (variableName == null) {
+            return [];
+        }
+        const rawValue = this.variables[variableName];
+        if (!Array.isArray(rawValue)) {
+            throw new WorkflowError(`Variable "${variableName}" for ${context} must be a string[]`);
+        }
+        const workspaceRoot = resolveWorkspaceRoot();
+        const values = rawValue.map((value) => {
+            if (typeof value !== "string") {
+                throw new WorkflowError(`Variable "${variableName}" for ${context} must contain only strings`);
+            }
+            return isAbsolute(value) ? value : resolve(workspaceRoot, value);
+        });
+        validateDynamicPaths(values, this.allowedRoots, context);
+        return values;
+    }
+    createDeadlineController() {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => {
+            controller.abort(new Error(`Workflow timeout exceeded after ${String(this.definition.settings.timeout_seconds)} seconds`));
+        }, this.definition.settings.timeout_seconds * 1000);
+        if (this.signal != null) {
+            this.signal.addEventListener("abort", () => controller.abort(new WorkflowCancellationError()), { once: true });
+        }
+        return {
+            signal: controller.signal,
+            dispose: () => clearTimeout(timeout),
+        };
+    }
+    throwIfAborted(signal) {
+        if (!signal.aborted) {
+            return;
+        }
+        const reason = signal.reason;
+        if (reason instanceof WorkflowCancellationError) {
+            throw reason;
+        }
+        if (reason instanceof Error && reason.message.includes("Workflow timeout exceeded")) {
+            throw new WorkflowError(reason.message);
+        }
+        throw new WorkflowCancellationError();
+    }
+    validateFinalStage() {
+        const finalStage = this.definition.stages[this.definition.stages.length - 1];
+        if (finalStage == null || finalStage.calls.length !== 1) {
+            throw new WorkflowError("Final stage must contain exactly one call");
+        }
+    }
+    validateAdvertisedCliNames() {
+        const knownCliNames = Array.isArray(this.session.cliNames) ? this.session.cliNames : [];
+        if (knownCliNames.length === 0) {
+            return;
+        }
+        const known = new Set(knownCliNames);
+        const unknownCalls = this.definition.stages.flatMap((stage) => stage.calls
+            .filter((call) => !known.has(call.cli_name))
+            .map((call) => `${stage.id}.${call.id} -> ${call.cli_name}`));
+        if (unknownCalls.length === 0) {
+            return;
+        }
+        throw new WorkflowError(`Workflow references cli_name values not advertised by the child: ${unknownCalls.join(", ")}. ` +
+            `Known cli_name values: ${knownCliNames.join(", ")}`);
+    }
+    defaultAllowedRoots() {
+        const workspaceRoot = resolveWorkspaceRoot();
+        const stateDir = getStateDir();
+        const configuredArtifactsDir = getArtifactsDir();
+        return [
+            workspaceRoot,
+            stateDir,
+            configuredArtifactsDir,
+            this.runDir,
+            join(this.runDir, "artifacts"),
+        ];
+    }
+    buildCallInput(stage, call, callKey, callIndex) {
+        const resumedInput = this.resumePreparedInputs.get(callKey);
+        if (resumedInput != null) {
+            return structuredClone(resumedInput);
+        }
+        const prompt = renderCallPrompt(call.prompt, this.definition.variables, this.variables, {
+            workflow: { run_id: this.runId },
+            stage: { id: stage.id },
+            call: { id: call.id },
+        });
+        const contextArtifacts = call.anonymize_context === true
+            ? this.artifactStore.buildAnonymizedContext(this.definition, call.context_from, callIndex)
+            : this.artifactStore.buildContext(this.definition, call.context_from);
+        const staticFiles = call.absolute_file_paths ?? [];
+        const dynamicFiles = this.resolveDynamicPaths(call.absolute_file_paths_from, `${stage.id}.${call.id}.absolute_file_paths_from`);
+        const staticImages = call.images ?? [];
+        const dynamicImages = this.resolveDynamicPaths(call.images_from, `${stage.id}.${call.id}.images_from`);
+        const absoluteFilePaths = [
+            ...contextArtifacts.absoluteFilePaths,
+            ...staticFiles,
+            ...dynamicFiles,
+        ];
+        const images = [...staticImages, ...dynamicImages];
+        const estimate = estimatePromptBudget({
+            promptText: prompt,
+            contextText: contextArtifacts.context,
+            fileContributors: [
+                ...contextArtifacts.contributors,
+                ...staticFiles.map((path) => createPathContributor(`absolute_file_paths:${path}`, path, "file")),
+                ...dynamicFiles.map((path) => createPathContributor(`absolute_file_paths_from:${path}`, path, "file")),
+            ],
+            imageContributors: images.map((path) => createPathContributor(`image:${path}`, path, "image")),
+            maxBytes: this.maxPromptBytes,
+            reserveBytes: this.promptReserveBytes,
+        });
+        enforcePromptBudget(estimate);
+        const input = {
+            cli_name: call.cli_name,
+            role: call.role,
+            prompt,
+        };
+        if (absoluteFilePaths.length > 0) {
+            input["absolute_file_paths"] = absoluteFilePaths;
+        }
+        if (images.length > 0) {
+            input["images"] = images;
+        }
+        if (contextArtifacts.context != null) {
+            input["context"] = contextArtifacts.context;
+        }
+        if (call.timeout_seconds != null) {
+            input["timeout_seconds"] = call.timeout_seconds;
+        }
+        if (call.max_response_chars != null) {
+            input["max_response_chars"] = call.max_response_chars;
+        }
+        // Derive JSON enforcement from response_contract or validator_schema_id.
+        // This bridges workflow-level structured-output intent to the child pipeline's
+        // enforceJson gate, decoupling JSON enforcement from role names.
+        if (call.response_contract === "json" || call.validator_schema_id != null) {
+            input["expect_json"] = true;
+        }
+        return input;
+    }
+    async materializeUnexpectedFailure(stage, call, error) {
+        if (error instanceof WorkflowCancellationError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        this.artifactStore.noteFailedCall(stage.id, call.id, message);
+        logger.error({ run_id: this.runId, stage_id: stage.id, call_id: call.id, err: message }, "parallel stage call rejected unexpectedly");
+        await this.emitCallStateChange({
+            runId: this.runId,
+            workflowName: this.definition.name,
+            stageId: stage.id,
+            callId: call.id,
+            state: "failed",
+            attempt: 1,
+            retryCount: 0,
+            completedAt: new Date().toISOString(),
+            error: message,
+            failureClass: classifyFailureClass(error),
+            childDebugMetadata: error instanceof CallExecutionError ? error.childDebugMetadata : undefined,
+        });
+        await this.emitProgress({
+            runId: this.runId,
+            workflowName: this.definition.name,
+            scope: "call",
+            stageId: stage.id,
+            stageDescription: stage.description,
+            callId: call.id,
+            state: "failed",
+            attempt: 1,
+            retryCount: 0,
+            message: `Call ${stage.id}.${call.id} failed unexpectedly: ${message}`,
+        });
+        return {
+            stageId: stage.id,
+            callId: call.id,
+            ok: false,
+            error: message,
+        };
+    }
+    async emitRunStateChange(event) {
+        await this.hooks.onRunStateChange?.(event);
+    }
+    async emitCallPrepared(event) {
+        await this.hooks.onCallPrepared?.(event);
+    }
+    async emitCallStateChange(event) {
+        await this.hooks.onCallStateChange?.(event);
+    }
+    async emitRetryScheduled(event) {
+        await this.hooks.onRetryScheduled?.(event);
+    }
+    async emitProgress(event) {
+        await this.hooks.onProgress?.(event);
+    }
+    seedResumedArtifacts() {
+        for (const executedCall of this.resumeCompletedCalls.values()) {
+            if (executedCall.artifact != null) {
+                this.artifactStore.seedArtifact(executedCall.artifact);
+            }
+        }
+        for (const failedCall of this.resumeFailedCalls.values()) {
+            this.artifactStore.seedFailedCall(failedCall.stageId, failedCall.callId, failedCall.error);
+        }
+    }
+    /**
+     * Pre-flight validation: check that all user-supplied file/image paths exist
+     * before any stage executes. Skips already-completed calls on resume.
+     *
+     * - ENOENT → collect as missing (fail-fast after checking all)
+     * - EACCES/EIO → warn but don't fail (NFS/FUSE transient)
+     * - context_from artifacts are NOT validated (engine-generated)
+     */
+    async validateInputPathsExist() {
+        const pathsToCheck = new Set();
+        const resolutionErrors = [];
+        for (const stage of this.definition.stages) {
+            for (const call of stage.calls) {
+                const callKey = `${stage.id}.${call.id}`;
+                // Skip already-completed calls (resume edge case)
+                if (this.resumeCompletedCalls.has(callKey)) {
+                    continue;
+                }
+                // For calls with persisted inputs (resumed but not completed),
+                // validate the PERSISTED paths — buildCallInput() returns the
+                // persisted input verbatim via structuredClone, ignoring current
+                // variable resolution.
+                const persistedInput = this.resumePreparedInputs.get(callKey);
+                if (persistedInput != null) {
+                    const persistedFiles = persistedInput["absolute_file_paths"];
+                    if (Array.isArray(persistedFiles)) {
+                        for (const p of persistedFiles) {
+                            if (typeof p === "string") {
+                                pathsToCheck.add(p);
+                            }
+                        }
+                    }
+                    const persistedImages = persistedInput["images"];
+                    if (Array.isArray(persistedImages)) {
+                        for (const p of persistedImages) {
+                            if (typeof p === "string") {
+                                pathsToCheck.add(p);
+                            }
+                        }
+                    }
+                    continue;
+                }
+                // Static file paths
+                if (call.absolute_file_paths != null) {
+                    for (const p of call.absolute_file_paths) {
+                        pathsToCheck.add(p);
+                    }
+                }
+                // Dynamic file paths (variable-resolved)
+                try {
+                    const dynamicFiles = this.resolveDynamicPaths(call.absolute_file_paths_from, `${stage.id}.${call.id}.absolute_file_paths_from`);
+                    for (const p of dynamicFiles) {
+                        pathsToCheck.add(p);
+                    }
+                }
+                catch (error) {
+                    resolutionErrors.push(error.message);
+                }
+                // Static image paths
+                if (call.images != null) {
+                    for (const p of call.images) {
+                        pathsToCheck.add(p);
+                    }
+                }
+                // Dynamic image paths (variable-resolved)
+                try {
+                    const dynamicImages = this.resolveDynamicPaths(call.images_from, `${stage.id}.${call.id}.images_from`);
+                    for (const p of dynamicImages) {
+                        pathsToCheck.add(p);
+                    }
+                }
+                catch (error) {
+                    resolutionErrors.push(error.message);
+                }
+            }
+        }
+        if (pathsToCheck.size === 0 && resolutionErrors.length === 0) {
+            return;
+        }
+        const missing = [];
+        const accessErrors = [];
+        if (pathsToCheck.size > 0) {
+            await Promise.all([...pathsToCheck].map(async (filePath) => {
+                try {
+                    await fsStat(filePath);
+                }
+                catch (error) {
+                    const code = error.code;
+                    if (code === "ENOENT") {
+                        missing.push(filePath);
+                    }
+                    else if (code === "EACCES" || code === "EIO") {
+                        logger.warn({ path: filePath, err: error.message }, "input path preflight: transient access error, proceeding");
+                    }
+                    else {
+                        const errCode = error.code ?? "UNKNOWN";
+                        accessErrors.push(`${filePath} (${errCode})`);
+                    }
+                }
+            }));
+        }
+        const hasErrors = missing.length > 0 || accessErrors.length > 0 || resolutionErrors.length > 0;
+        if (!hasErrors) {
+            return;
+        }
+        const sections = [];
+        if (missing.length > 0) {
+            missing.sort();
+            sections.push(`Missing files:\n    - ${missing.join("\n    - ")}`);
+        }
+        if (accessErrors.length > 0) {
+            accessErrors.sort();
+            sections.push(`Access errors:\n    - ${accessErrors.join("\n    - ")}`);
+        }
+        if (resolutionErrors.length > 0) {
+            resolutionErrors.sort();
+            sections.push(`Resolution errors:\n    - ${resolutionErrors.join("\n    - ")}`);
+        }
+        throw new WorkflowError(`Input validation failed before workflow execution:\n  ${sections.join("\n  ")}`);
+    }
+}
+function collectContextProducingCalls(definition) {
+    const referenced = new Set();
+    for (const stage of definition.stages) {
+        for (const call of stage.calls) {
+            if (call.context_from == null) {
+                continue;
+            }
+            for (const ref of call.context_from) {
+                const dot = ref.indexOf(".");
+                if (dot === -1) {
+                    const referencedStage = definition.stages.find((candidate) => candidate.id === ref);
+                    if (referencedStage == null) {
+                        continue;
+                    }
+                    for (const referencedCall of referencedStage.calls) {
+                        referenced.add(`${referencedStage.id}.${referencedCall.id}`);
+                    }
+                }
+                else {
+                    referenced.add(ref);
+                }
+            }
+        }
+    }
+    return referenced;
+}
+function classifyFailureClass(error) {
+    if (error instanceof InvalidCallError) {
+        return "permanent";
+    }
+    if (error instanceof CallExecutionError) {
+        return error.failureClass;
+    }
+    if (error instanceof WorkflowCancellationError) {
+        return "permanent";
+    }
+    return "permanent";
+}
+/**
+ * Determine whether an error is retryable based on the retry mode (5-1, 5-2).
+ *
+ * - InvalidCallError (-32602): ALWAYS permanent — never retry.
+ * - transport_only (default): retry only on transient failures
+ *   (child crash, transport death, wall timeout, idle timeout).
+ * - all: retry on any failure except InvalidCallError.
+ */
+function isRetryable(error, failureClass, retryMode) {
+    // Child -32602 (InvalidParams) is ALWAYS permanent
+    if (error instanceof InvalidCallError) {
+        return false;
+    }
+    if (retryMode === "all") {
+        return true;
+    }
+    // transport_only: retry only on transient failures
+    return failureClass === "transient";
+}
+/**
+ * Compute retry delay with exponential backoff and jitter (5-1).
+ *
+ * delay = min(backoff_seconds * 2^retryCount, max_backoff_seconds) + random 0-25% jitter
+ */
+function computeRetryDelay(retryCount, backoffSeconds, maxBackoffSeconds) {
+    const baseDelay = Math.min(backoffSeconds * Math.pow(2, retryCount), maxBackoffSeconds);
+    const jitter = baseDelay * Math.random() * 0.25;
+    return Math.round((baseDelay + jitter) * 1000);
+}
+/**
+ * Delay that respects AbortSignal — resolves early on abort.
+ */
+function abortableDelay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+//# sourceMappingURL=engine.js.map