@agwab/pi-workflow 0.2.0 → 0.3.0

package/README.md

@@ -64,6 +64,8 @@ If you want deterministic manual control, use the slash command form:
 /workflow run deep-research "Research this repository and summarize the architecture tradeoffs."
 ```
 
+For opt-in lower-latency runs, add `--thinking low`; defaults remain conservative pending holdout evidence. See [`docs/usage.md`](./docs/usage.md).
+
 For a one-off adaptive workflow that should plan, fan out, and synthesize without choosing a saved workflow, use:
 
 ```text

package/dist/compiler.d.ts

@@ -1,5 +1,5 @@
-import { type ArtifactGraphWorkflowSpec, type ThinkingLevel } from "./types.js";
-import { type WorkflowModelInfo } from "./workflow-runtime.js";
+import { type ArtifactGraphWorkflowSpec } from "./types.js";
+import { type WorkflowModelInfo, type WorkflowRuntimeDefaults } from "./workflow-runtime.js";
 interface CompileOptions {
     cwd: string;
     specPath?: string;
@@ -7,9 +7,7 @@ interface CompileOptions {
 }
 export declare function compileWorkflow(spec: ArtifactGraphWorkflowSpec, options: CompileOptions & {
     task?: string;
-    runtimeDefaults?: {
-        model?: string;
-        thinking?: ThinkingLevel;
-    };
+    runtimeOverrides?: WorkflowRuntimeDefaults;
+    runtimeDefaults?: WorkflowRuntimeDefaults;
 }): Promise<any>;
 export {};

package/dist/compiler.js

@@ -2,9 +2,10 @@ import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { loadAgentByName } from "./agents.js";
 import { DYNAMIC_OUTPUT_PROFILES } from "./dynamic-profiles.js";
+import { compileRole } from "./roles.js";
 import { classifyToolCapability, effectiveToolClassification, providersForSelectedTools, resolveToolSelection, TOOL_NAME_PATTERN, toolAllowedByAuthorityCeiling, toolNameForSpec, } from "./tool-metadata.js";
 import { WorkflowValidationError, WORKFLOW_RUN_TYPE, } from "./types.js";
-import { resolveWorkflowRuntime, } from "./workflow-runtime.js";
+import { resolveWorkflowRuntime, selectWorkflowRuntime, } from "./workflow-runtime.js";
 const DELEGATION_TOOLS = new Set([
     "skill_test_subagent",
     "workflow",
@@ -413,6 +414,17 @@ async function collectForeachPathWarnings(stages, specDir) {
     }
     return warnings;
 }
+function runtimeSettings(value) {
+    if (!isPlainRecord(value))
+        return undefined;
+    const model = typeof value.model === "string" && value.model.trim()
+        ? value.model.trim()
+        : undefined;
+    const thinking = typeof value.thinking === "string" && value.thinking.trim()
+        ? value.thinking.trim()
+        : undefined;
+    return model || thinking ? { model, thinking } : undefined;
+}
 async function compileArtifactGraphPlan(spec, options) {
     const stages = spec.stages;
     if (!Array.isArray(stages)) {
@@ -431,14 +443,11 @@ async function compileArtifactGraphPlan(spec, options) {
         return defaultAgent;
     };
     const roleEntries = Object.entries(spec.roles ?? {});
-    const roles = roleEntries.map(([name, role]) => ({
-        name,
-        fromAgent: role.fromAgent,
-        content: role.prompt ?? "",
-        maxChars: role.maxChars ?? 8000,
-        truncated: false,
-        includedSections: [],
-        excludedSections: [],
+    const roles = await Promise.all(roleEntries.map(async ([name, role]) => {
+        const sourceAgent = role.fromAgent
+            ? await loadWorkflowAgent(role.fromAgent, options.cwd, agentCache, `$.roles.${name}.fromAgent`)
+            : undefined;
+        return compileRole(name, role, sourceAgent);
     }));
     const roleText = roles.length
         ? `# Role Context\n\n${roles.map((r) => `## Role: ${r.name}\n${r.content}`).join("\n\n")}`
@@ -450,8 +459,9 @@ async function compileArtifactGraphPlan(spec, options) {
         Object.keys(workflowInput).length > 0
         ? `# Workflow Input\n\n${JSON.stringify(workflowInput, null, 2)}`
         : "";
-    const defaultModel = options.runtimeDefaults?.model ?? spec.defaults?.model;
-    const defaultThinking = options.runtimeDefaults?.thinking ?? spec.defaults?.thinking;
+    const runtimeOverrides = options.runtimeOverrides;
+    const runtimeDefaults = options.runtimeDefaults;
+    const specRuntimeDefaults = runtimeSettings(spec.defaults);
     const tasks = [];
     const stageRecords = [];
     const issues = [];
@@ -475,17 +485,26 @@ async function compileArtifactGraphPlan(spec, options) {
                     : `$.artifactGraph.stages.${jsonKey(stage.id)}.dynamic`;
             validateDelegationBoundary(rawDynamicToolSelection.tools, issues, dynamicToolPath);
             const dynamicToolSelection = filterToolSelection(rawDynamicToolSelection);
-            const dynamicTask = buildDynamicTask(stage, taskId, key, prompt, dependencyKeys, options.cwd, specDir, workflowInputText, options.task, defaultModel, defaultThinking, overrides);
-            const resolvedDynamicRuntime = await resolveWorkflowRuntime({ model: defaultModel, thinking: defaultThinking }, {
+            const requestedRuntime = selectWorkflowRuntime(runtimeOverrides, runtimeSettings(stage), runtimeDefaults, specRuntimeDefaults);
+            const resolvedDynamicRuntime = await resolveWorkflowRuntime(requestedRuntime, {
                 taskKey: key,
                 stageId: stage.id,
                 taskId,
                 agent: "dynamic",
             }, { availableModels: options.availableModels });
+            const dynamicTask = buildDynamicTask(stage, taskId, key, prompt, dependencyKeys, options.cwd, specDir, workflowInputText, options.task, resolvedDynamicRuntime, {
+                runtimeOverrides,
+                runtimeDefaults,
+                specRuntimeDefaults,
+                stageRuntime: runtimeSettings(stage),
+            }, overrides);
             dynamicTask.runtime = {
                 ...dynamicTask.runtime,
                 ...resolvedDynamicRuntime,
             };
+            if (options.availableModels?.length) {
+                dynamicTask.dynamic.availableModels = options.availableModels;
+            }
             if (dynamicToolSelection.tools || dynamicToolSelection.toolProviders) {
                 dynamicTask.runtime = {
                     ...dynamicTask.runtime,
@@ -539,13 +558,7 @@ async function compileArtifactGraphPlan(spec, options) {
         validateToolSubset(toolSelection.tools, stageAgent, issues, toolPath);
         validateDelegationBoundary(toolSelection.tools, issues, toolPath);
         const filteredToolSelection = filterToolSelection(toolSelection);
-        // Explicit runtime overrides outrank stage pins; spec defaults fill last.
-        const requestedRuntime = {
-            model: options.runtimeDefaults?.model ?? stage.model ?? spec.defaults?.model,
-            thinking: options.runtimeDefaults?.thinking ??
-                stage.thinking ??
-                spec.defaults?.thinking,
-        };
+        const requestedRuntime = selectWorkflowRuntime(runtimeOverrides, runtimeSettings(stage), runtimeDefaults, specRuntimeDefaults);
         const resolvedRuntime = await resolveWorkflowRuntime(requestedRuntime, {
             taskKey: key,
             stageId: stage.id,
@@ -825,11 +838,33 @@ async function compileArtifactGraphPlan(spec, options) {
         tasks,
         warnings,
         budget: {
-            models: defaultModel ? [{ model: defaultModel }] : [],
+            models: budgetModelRows(tasks),
             unratedModels: [],
         },
     };
 }
+function budgetModelRows(tasks) {
+    const models = new Set();
+    for (const task of tasks) {
+        if (typeof task?.runtime?.model === "string" && task.runtime.model.trim()) {
+            models.add(task.runtime.model.trim());
+        }
+        const loop = task?.dynamic?.decisionLoop;
+        if (!loop || typeof loop !== "object")
+            continue;
+        for (const profile of [
+            loop.planner,
+            loop.workerDefaults,
+            loop.verifier,
+            loop.synthesis,
+        ]) {
+            if (typeof profile?.model === "string" && profile.model.trim()) {
+                models.add(profile.model.trim());
+            }
+        }
+    }
+    return [...models].sort().map((model) => ({ model }));
+}
 function isSupportStage(stage) {
     return stage?.support !== undefined && stage?.type === undefined;
 }
@@ -889,7 +924,7 @@ function buildSupportTask(stage, taskId, key, prompt, dependencyKeys, cwd, workf
         ...overrides,
     };
 }
-function buildDynamicTask(stage, taskId, key, prompt, dependencyKeys, cwd, specDir, workflowInputText, runtimeTask, defaultModel, defaultThinking, overrides) {
+function buildDynamicTask(stage, taskId, key, prompt, dependencyKeys, cwd, specDir, workflowInputText, runtimeTask, controllerRuntime, runtimePriority, overrides) {
     const dynamic = stage.dynamic ?? {};
     const uses = String(dynamic.uses);
     const normalizedPrompt = String(prompt ?? "").replace(/\$\{item\}/g, "the relevant item from the dependency context");
@@ -942,7 +977,7 @@ function buildDynamicTask(stage, taskId, key, prompt, dependencyKeys, cwd, specD
             usesPath: resolve(specDir, String(workflow.uses)),
         };
     }
-    const decisionLoop = compileDynamicDecisionLoop(dynamic.decisionLoop, defaultModel, defaultThinking);
+    const decisionLoop = compileDynamicDecisionLoop(dynamic.decisionLoop, runtimePriority);
     return {
         key,
         id: key,
@@ -960,8 +995,7 @@ function buildDynamicTask(stage, taskId, key, prompt, dependencyKeys, cwd, specD
         explicitWorktreePolicy: false,
         runtime: {
             approvalMode: "non-interactive",
-            model: defaultModel,
-            thinking: defaultThinking,
+            ...controllerRuntime,
             maxRuntimeMs: dynamic.budget?.maxRuntimeMs ?? DEFAULT_DYNAMIC_MAX_RUNTIME_MS,
         },
         safety: {
@@ -999,21 +1033,24 @@ function buildDynamicTask(stage, taskId, key, prompt, dependencyKeys, cwd, specD
             helpers,
             workflows,
             ...(decisionLoop ? { decisionLoop } : {}),
+            ...(runtimePriority.runtimeOverrides
+                ? { runtimeOverrides: runtimePriority.runtimeOverrides }
+                : {}),
         },
         ...overrides,
     };
 }
-function compileDynamicDecisionLoop(value, defaultModel, defaultThinking) {
+function compileDynamicDecisionLoop(value, runtimePriority) {
     if (!isPlainRecord(value))
         return undefined;
     const allowedToolSelection = filterToolSelection(resolveToolSelection([Array.isArray(value.allowedTools) ? value.allowedTools : undefined], undefined));
     const maxFindings = positiveInteger(recordValue(value.stateIndex, "maxFindings"));
     const deprecatedRequiredFindingIds = stringArray(recordValue(value.stateIndex, "requiredFindingIds"));
     return {
-        planner: compileDynamicDecisionLoopProfile(value.planner, defaultModel, defaultThinking),
-        workerDefaults: compileDynamicDecisionLoopProfile(value.workerDefaults, defaultModel, defaultThinking),
-        verifier: compileDynamicDecisionLoopProfile(value.verifier, defaultModel, defaultThinking),
-        synthesis: compileDynamicDecisionLoopProfile(value.synthesis, defaultModel, defaultThinking),
+        planner: compileDynamicDecisionLoopProfile(value.planner, runtimePriority),
+        workerDefaults: compileDynamicDecisionLoopProfile(value.workerDefaults, runtimePriority),
+        verifier: compileDynamicDecisionLoopProfile(value.verifier, runtimePriority),
+        synthesis: compileDynamicDecisionLoopProfile(value.synthesis, runtimePriority),
         allowedAgents: stringArray(value.allowedAgents),
         ...(allowedToolSelection.tools
             ? { allowedTools: allowedToolSelection.tools }
@@ -1054,22 +1091,16 @@ function compileDynamicDecisionLoop(value, defaultModel, defaultThinking) {
         },
     };
 }
-function compileDynamicDecisionLoopProfile(value, defaultModel, defaultThinking) {
+function compileDynamicDecisionLoopProfile(value, runtimePriority) {
     if (!isPlainRecord(value))
         return undefined;
     const toolSelection = filterToolSelection(resolveToolSelection([Array.isArray(value.tools) ? value.tools : undefined], undefined));
-    const model = typeof value.model === "string" && value.model.trim()
-        ? value.model.trim()
-        : defaultModel;
-    const thinking = typeof value.thinking === "string" && value.thinking.trim()
-        ? value.thinking.trim()
-        : defaultThinking;
+    const runtime = selectWorkflowRuntime(runtimePriority.runtimeOverrides, runtimeSettings(value), runtimePriority.stageRuntime, runtimePriority.runtimeDefaults, runtimePriority.specRuntimeDefaults);
     return {
         ...(typeof value.agent === "string" && value.agent.trim()
             ? { agent: value.agent.trim() }
             : {}),
-        ...(model ? { model } : {}),
-        ...(thinking ? { thinking } : {}),
+        ...runtime,
         ...(toolSelection.tools ? { tools: toolSelection.tools } : {}),
         ...(toolSelection.toolProviders
             ? { toolProviders: toolSelection.toolProviders }

package/dist/dynamic-decision.d.ts

@@ -97,7 +97,6 @@ export interface DynamicDecisionArtifactWriteResult {
     hash?: string;
 }
 export declare function validateDynamicDecision(value: unknown, context?: DynamicDecisionValidationContext): DynamicDecisionValidationResult;
-export declare function assertValidDynamicDecision(value: unknown, context?: DynamicDecisionValidationContext): NormalizedDynamicDecision;
 export declare function hashDynamicDecision(value: unknown): string;
 export declare function dynamicLoopSignature(decision: NormalizedDynamicDecision): string;
 export declare function writeDynamicDecisionArtifacts(input: DynamicDecisionArtifactWriteInput): Promise<DynamicDecisionArtifactWriteResult>;

package/dist/dynamic-decision.js

@@ -121,13 +121,6 @@ export function validateDynamicDecision(value, context = {}) {
         hash: hashDynamicDecision(decision),
     };
 }
-export function assertValidDynamicDecision(value, context = {}) {
-    const result = validateDynamicDecision(value, context);
-    if (!result.ok || !result.decision) {
-        throw new Error(`invalid dynamic decision: ${result.errors.join("; ")}`);
-    }
-    return result.decision;
-}
 export function hashDynamicDecision(value) {
     return createHash("sha256")
         .update(stableStringify(toJsonNormalizedValue(value)))

package/dist/dynamic-generated-task-runtime.d.ts

@@ -1,4 +1,5 @@
 import type { CompiledDynamicWorkflowTask, CompiledTask, CompiledWorkflow, ThinkingLevel, WorkflowRunRecord, WorkflowTaskRunRecord } from "./types.js";
+import { type WorkflowModelInfo } from "./workflow-runtime.js";
 export interface DynamicArtifactInput {
     kind: "workflow-artifact-ref";
     name: string;
@@ -41,6 +42,7 @@ export declare function buildDynamicGeneratedCompiledTask(input: {
     branchId?: string;
     request: DynamicAgentRequest;
     dynamic: CompiledDynamicWorkflowTask;
+    availableModels?: WorkflowModelInfo[];
 }): Promise<CompiledTask>;
 export declare function isDynamicCompiledTaskPayload(value: unknown): value is CompiledTask;
 export declare function assertDynamicGeneratedMetadataMatches(compiledTask: CompiledTask, expected: {

package/dist/dynamic-generated-task-runtime.js

@@ -6,6 +6,7 @@ import { readOrRebuildDynamicState } from "./dynamic-state.js";
 import { sanitizeTaskId } from "./engine-run-graph.js";
 import { fromProjectPath, isTerminalTaskStatus, readJson } from "./store.js";
 import { classifyToolCapability, effectiveToolClassification, providersForSelectedTools, toolAllowedByAuthorityCeiling, } from "./tool-metadata.js";
+import { resolveWorkflowRuntime, selectWorkflowRuntime, } from "./workflow-runtime.js";
 const DYNAMIC_OUTPUT_MAX_DIGEST_CHARS = 1000;
 const DYNAMIC_DELEGATION_TOOLS = new Set([
     "skill_test_subagent",
@@ -69,6 +70,13 @@ export async function buildDynamicGeneratedCompiledTask(input) {
     }
     const toolProviders = executionProfile?.toolProviders ??
         providersForSelectedTools(tools, new Map(Object.entries(input.controllerCompiledTask.runtime.toolProviders ?? {})));
+    const selectedRuntime = selectWorkflowRuntime(input.dynamic.runtimeOverrides, runtimeSettings(input.request), runtimeSettings(executionProfile), runtimeSettings(input.controllerCompiledTask.runtime), runtimeSettings(agentDefinition));
+    const resolvedRuntime = await resolveWorkflowRuntime(selectedRuntime, {
+        taskKey: input.generatedSpecId,
+        stageId: input.controllerStageId,
+        taskId: input.request.id,
+        agent: requestedAgent,
+    }, { availableModels: input.availableModels ?? input.dynamic.availableModels });
     const unknownTools = (tools ?? []).filter((tool) => effectiveToolClassification(tool, toolProviders) === undefined);
     if (unknownTools.length > 0) {
         throw new Error(`dynamic agent requested tools without trusted classification metadata: ${unknownTools.join(", ")}`);
@@ -135,14 +143,7 @@ export async function buildDynamicGeneratedCompiledTask(input) {
         explicitWorktreePolicy: requiresWorktree,
         runtime: {
             approvalMode: "non-interactive",
-            model: input.request.model ??
-                executionProfile?.model ??
-                input.controllerCompiledTask.runtime.model ??
-                agentDefinition.model,
-            thinking: input.request.thinking ??
-                executionProfile?.thinking ??
-                input.controllerCompiledTask.runtime.thinking ??
-                agentDefinition.thinking,
+            ...resolvedRuntime,
             tools,
             ...(toolProviders ? { toolProviders } : {}),
             maxRuntimeMs: input.request.maxRuntimeMs ??
@@ -461,6 +462,18 @@ function requiredDynamicString(value, field, api = "ctx.agent()") {
     }
     return value.trim();
 }
+function runtimeSettings(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const model = typeof record.model === "string" && record.model.trim()
+        ? record.model.trim()
+        : undefined;
+    const thinking = typeof record.thinking === "string" && record.thinking.trim()
+        ? record.thinking.trim()
+        : undefined;
+    return model || thinking ? { model, thinking } : undefined;
+}
 function optionalDynamicString(value, field) {
     if (value === undefined)
         return undefined;

package/dist/dynamic-profiles.d.ts

@@ -5,4 +5,3 @@ export declare const DYNAMIC_TERMINAL_OUTPUT_PROFILES: readonly ["synthesis_v1"]
 export declare function isDynamicOutputProfile(value: unknown): value is DynamicOutputProfile;
 export declare function isExtractableDynamicOutputProfile(value: unknown): value is (typeof DYNAMIC_EXTRACTABLE_OUTPUT_PROFILES)[number];
 export declare function isTerminalDynamicOutputProfile(value: unknown): value is (typeof DYNAMIC_TERMINAL_OUTPUT_PROFILES)[number];
-export declare function dynamicOutputProfileValues(): string[];

package/dist/dynamic-profiles.js

@@ -26,6 +26,3 @@ export function isExtractableDynamicOutputProfile(value) {
 export function isTerminalDynamicOutputProfile(value) {
     return typeof value === "string" && TERMINAL_OUTPUT_PROFILE_SET.has(value);
 }
-export function dynamicOutputProfileValues() {
-    return [...DYNAMIC_OUTPUT_PROFILES];
-}

package/dist/engine-run-graph.d.ts

@@ -2,6 +2,7 @@ import type { CompiledTask, CompiledWorkflow, WorkflowRunRecord, WorkflowTaskRun
 export declare function reconcileLoopTaskRecordsInMemory(cwd: string, run: WorkflowRunRecord, compiledFlow: CompiledWorkflow, loopIds: Set<string>): boolean;
 export declare function recoverStaleRunningDynamicControllers(run: WorkflowRunRecord, compiledFlow: CompiledWorkflow): boolean;
 export declare function reconcileDynamicGeneratedRunRecords(cwd: string, run: WorkflowRunRecord, compiledFlow: CompiledWorkflow): boolean;
+export declare function reconcileForeachGeneratedRunRecords(cwd: string, run: WorkflowRunRecord, compiledFlow: CompiledWorkflow): boolean;
 export declare function assertRunTaskPositionalAlignment(run: WorkflowRunRecord, compiledFlow: CompiledWorkflow): void;
 export declare function assertLoopTaskPositionalAlignment(run: WorkflowRunRecord, compiledFlow: CompiledWorkflow, loopIds?: Set<string>): void;
 export declare function upsertCompiledLoopTasksAtInsertion(compiledFlow: CompiledWorkflow, loopId: string, placeholderIndex: number, tasks: CompiledTask[]): void;

package/dist/engine-run-graph.js

@@ -92,6 +92,107 @@ export function reconcileDynamicGeneratedRunRecords(cwd, run, compiledFlow) {
     }
     return changed;
 }
+export function reconcileForeachGeneratedRunRecords(cwd, run, compiledFlow) {
+    let changed = false;
+    const compiledSpecIds = new Set(compiledFlow.tasks.map((task) => compiledTaskSpecId(task)));
+    const placeholderToGeneratedSpecIds = new Map();
+    for (const compiledTask of compiledFlow.tasks) {
+        const specId = compiledTaskSpecId(compiledTask);
+        const placeholderSpecId = foreachGeneratedPlaceholderSpecId(compiledTask, compiledFlow, specId);
+        if (!placeholderSpecId)
+            continue;
+        if (compiledTask.foreachGenerated?.placeholderSpecId !== placeholderSpecId) {
+            compiledTask.foreachGenerated = { placeholderSpecId };
+            changed = true;
+        }
+        const generated = placeholderToGeneratedSpecIds.get(placeholderSpecId) ?? [];
+        generated.push(specId);
+        placeholderToGeneratedSpecIds.set(placeholderSpecId, generated);
+    }
+    if (placeholderToGeneratedSpecIds.size === 0)
+        return changed;
+    const filteredRunTasks = [];
+    const seenGeneratedSpecIds = new Set();
+    for (const task of run.tasks) {
+        const generatedSpecIds = placeholderToGeneratedSpecIds.get(task.specId);
+        let placeholderSpecId = foreachGeneratedPlaceholderSpecId(task, compiledFlow, task.specId);
+        if (generatedSpecIds && !placeholderSpecId) {
+            if (generatedSpecIds.includes(task.specId)) {
+                placeholderSpecId = task.specId;
+                task.foreachGenerated = { placeholderSpecId };
+                changed = true;
+            }
+            else {
+                changed = true;
+                continue;
+            }
+        }
+        if (placeholderSpecId && !compiledSpecIds.has(task.specId)) {
+            changed = true;
+            continue;
+        }
+        if (placeholderSpecId && seenGeneratedSpecIds.has(task.specId)) {
+            changed = true;
+            continue;
+        }
+        if (placeholderSpecId) {
+            seenGeneratedSpecIds.add(task.specId);
+            if (task.foreachGenerated?.placeholderSpecId !== placeholderSpecId) {
+                task.foreachGenerated = { placeholderSpecId };
+                changed = true;
+            }
+        }
+        filteredRunTasks.push(task);
+    }
+    const runTaskBySpecId = new Map();
+    for (const task of filteredRunTasks) {
+        if (!runTaskBySpecId.has(task.specId))
+            runTaskBySpecId.set(task.specId, task);
+    }
+    const reordered = [];
+    const usedSpecIds = new Set();
+    let nextIndex = nextTaskRecordIndex({ ...run, tasks: filteredRunTasks });
+    for (const compiledTask of compiledFlow.tasks) {
+        const specId = compiledTaskSpecId(compiledTask);
+        const existing = runTaskBySpecId.get(specId);
+        if (existing) {
+            const placeholderSpecId = compiledTask.foreachGenerated?.placeholderSpecId;
+            if (placeholderSpecId &&
+                existing.foreachGenerated?.placeholderSpecId !== placeholderSpecId) {
+                existing.foreachGenerated = { placeholderSpecId };
+                changed = true;
+            }
+            reordered.push(existing);
+            usedSpecIds.add(specId);
+            continue;
+        }
+        if (!compiledTask.foreachGenerated)
+            continue;
+        const created = createTaskRunRecord(cwd, run.runId, compiledTask, nextIndex);
+        nextIndex += 1;
+        reordered.push(created);
+        usedSpecIds.add(specId);
+        changed = true;
+    }
+    for (const task of filteredRunTasks) {
+        if (!usedSpecIds.has(task.specId))
+            reordered.push(task);
+    }
+    if (!sameTaskRecordOrder(run.tasks, reordered))
+        changed = true;
+    for (const task of reordered) {
+        if (!task.dependsOn)
+            continue;
+        const replaced = replaceForeachGeneratedDependencies(task.dependsOn, placeholderToGeneratedSpecIds);
+        if (!sameStringList(task.dependsOn, replaced)) {
+            task.dependsOn = replaced;
+            changed = true;
+        }
+    }
+    if (changed)
+        run.tasks = reordered;
+    return changed;
+}
 export function assertRunTaskPositionalAlignment(run, compiledFlow) {
     const maxLength = Math.max(run.tasks.length, compiledFlow.tasks.length);
     for (let index = 0; index < maxLength; index += 1) {
@@ -141,6 +242,40 @@ export function compiledTaskSpecId(task) {
     const specId = task.specId;
     return typeof specId === "string" && specId.trim() !== "" ? specId : task.id;
 }
+function foreachGeneratedPlaceholderSpecId(task, compiledFlow, specId) {
+    const explicit = task.foreachGenerated?.placeholderSpecId;
+    if (typeof explicit === "string" && explicit.trim() !== "")
+        return explicit;
+    if (task.foreach)
+        return undefined;
+    if (task.kind !== "foreach" || !task.stageId)
+        return undefined;
+    const placeholderSpecId = foreachPlaceholderSpecId(compiledFlow, task.stageId);
+    if (!placeholderSpecId || specId === placeholderSpecId)
+        return undefined;
+    return placeholderSpecId;
+}
+function foreachPlaceholderSpecId(compiledFlow, stageId) {
+    const stage = (compiledFlow.stages ?? []).find((candidate) => candidate?.id === stageId);
+    if (stage?.type !== "foreach")
+        return undefined;
+    return `${stageId}.item`;
+}
+function replaceForeachGeneratedDependencies(dependsOn, placeholderToGeneratedSpecIds) {
+    const replaced = [];
+    for (const dep of dependsOn) {
+        const generatedSpecIds = placeholderToGeneratedSpecIds.get(dep);
+        if (generatedSpecIds)
+            replaced.push(...generatedSpecIds);
+        else
+            replaced.push(dep);
+    }
+    return [...new Set(replaced)];
+}
+function sameStringList(left, right) {
+    return (left.length === right.length &&
+        left.every((value, index) => value === right[index]));
+}
 function isLoopGeneratedCompiledTask(task, loopIds) {
     return Boolean((task.loopChild?.loopId && loopIds.has(task.loopChild.loopId)) ||
         (task.loopExhausted?.loopId && loopIds.has(task.loopExhausted.loopId)));
@@ -228,7 +363,7 @@ export function buildForeachGeneratedTasks(template, runtimeTask, items) {
         seen.add(taskId);
         const specId = `${template.stageId}.${taskId}`;
         const itemText = formatForeachItem(item);
-        const instructions = template.foreach.prompt.replace(/\$\{item\}/g, itemText);
+        const instructions = template.foreach.prompt.replace(/\$\{item\}/g, escapeReplacementText(itemText));
         const compiledPrompt = [
             template.foreach.injectRuntimeTask && runtimeTask
                 ? `# Task\n\n${runtimeTask}`
@@ -249,6 +384,7 @@ export function buildForeachGeneratedTasks(template, runtimeTask, items) {
             compiledPrompt,
             dependsOn: [...(template.dependsOn ?? [])],
             foreach: undefined,
+            foreachGenerated: { placeholderSpecId: template.id },
         });
     }
     return { tasks };
@@ -274,6 +410,9 @@ export function sanitizeTaskId(value) {
 function formatForeachItem(item) {
     return typeof item === "string" ? item : JSON.stringify(item);
 }
+function escapeReplacementText(value) {
+    return value.replace(/\$/g, "$$$$");
+}
 export function sourceStageIdsForFrom(from) {
     if (Array.isArray(from))
         return from.filter((item) => typeof item === "string");
@@ -321,7 +460,8 @@ export function markDagDependentsSkipped(run, compiledFlow) {
                 const status = bySpecId.get(dep)?.status;
                 return (status === "failed" ||
                     status === "interrupted" ||
-                    status === "skipped");
+                    status === "skipped" ||
+                    status === "blocked");
             });
             if (!failedDep)
                 continue;

package/dist/engine.d.ts

@@ -1,15 +1,13 @@
-import { type WorkflowModelInfo } from "./workflow-runtime.js";
+import { type WorkflowModelInfo, type WorkflowRuntimeDefaults } from "./workflow-runtime.js";
 import { type DynamicWorkflowUi } from "./dynamic-controller-policy.js";
-import { type CompiledWorkflow, type ThinkingLevel, type WorkflowRunRecord } from "./types.js";
+import { type CompiledWorkflow, type WorkflowRunRecord } from "./types.js";
 export { buildRunSourceContext } from "./workflow-source-context-runtime.js";
 export { evaluateLoopUntilCondition } from "./loop-runtime.js";
 export type { DynamicWorkflowUi } from "./dynamic-controller-policy.js";
 export interface WorkflowRunOptions {
     task?: string;
-    runtimeDefaults?: {
-        model?: string;
-        thinking?: ThinkingLevel;
-    };
+    runtimeOverrides?: WorkflowRuntimeDefaults;
+    runtimeDefaults?: WorkflowRuntimeDefaults;
     availableModels?: WorkflowModelInfo[];
     dynamicUi?: DynamicWorkflowUi;
     runId?: string;
@@ -17,6 +15,7 @@ export interface WorkflowRunOptions {
 }
 interface WorkflowScheduleOptions {
     dynamicUi?: DynamicWorkflowUi;
+    availableModels?: WorkflowModelInfo[];
 }
 export declare function runWorkflowSpec(specPath: string, cwd: string, options?: WorkflowRunOptions): Promise<WorkflowRunRecord>;
 export declare function runDynamicTask(cwd: string, options?: WorkflowRunOptions): Promise<WorkflowRunRecord>;
@@ -26,6 +25,11 @@ export interface ResumeRunSummary {
     run: WorkflowRunRecord;
     resetTaskIds: string[];
 }
+export interface StopRunSummary {
+    run: WorkflowRunRecord;
+    interruptedTaskIds: string[];
+}
+export declare function stopRun(cwd: string, runIdOrPrefix: string): Promise<StopRunSummary>;
 export declare function resumeRun(cwd: string, runIdOrPrefix: string, options?: WorkflowScheduleOptions): Promise<ResumeRunSummary>;
 export declare function resumeSupervisors(cwd: string, options?: WorkflowScheduleOptions): Promise<void>;
 export declare function watchRun(cwd: string, runId: string, options?: WorkflowScheduleOptions): void;