@agwab/pi-workflow 0.2.0 → 0.2.1

package/src/extension.ts

@@ -39,7 +39,10 @@ import {
 	type ThinkingLevel,
 	WorkflowValidationError,
 } from "./types.js";
-import { toWorkflowModelInfo } from "./workflow-runtime.js";
+import {
+	toWorkflowModelInfo,
+	type WorkflowRuntimeDefaults,
+} from "./workflow-runtime.js";
 
 const UNFINISHED_RUN_NOTICE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 const UNFINISHED_RUN_NOTICE_MAX_RUNS = 5;
@@ -337,7 +340,8 @@ async function deliverMissedWorkflowFeedback(
 		const run = await readRunRecord(ctx.cwd, summary.runId).catch(
 			() => undefined,
 		);
-		if (run) await deliverWorkflowFeedback(ctx, api, run).catch(() => undefined);
+		if (run)
+			await deliverWorkflowFeedback(ctx, api, run).catch(() => undefined);
 	}
 }
 
@@ -548,13 +552,13 @@ interface WorkflowRunToolRequest {
 	workflow: string;
 	task: string;
 	detach: boolean;
-	runtimeDefaults?: { model?: string; thinking?: ThinkingLevel };
+	runtimeOverrides?: WorkflowRuntimeDefaults;
 }
 
 interface WorkflowDynamicToolRequest {
 	task: string;
 	detach: boolean;
-	runtimeDefaults?: { model?: string; thinking?: ThinkingLevel };
+	runtimeOverrides?: WorkflowRuntimeDefaults;
 }
 
 function parseWorkflowListToolParams(params: unknown): void {
@@ -602,9 +606,9 @@ function parseWorkflowDynamicToolParams(
 		"workflow_dynamic",
 	)?.trim();
 	const thinking = rawThinking ? parseThinkingLevel(rawThinking) : undefined;
-	const runtimeDefaults =
+	const runtimeOverrides =
 		model || thinking ? { model: model || undefined, thinking } : undefined;
-	return { task, detach: detachValue === true, runtimeDefaults };
+	return { task, detach: detachValue === true, runtimeOverrides };
 }
 
 function stringParam(
@@ -704,8 +708,8 @@ async function startWorkflowRunFromRequest(
 		);
 	const run = await runWorkflowSpec(workflow, ctx.cwd, {
 		task,
-		runtimeDefaults:
-			request.runtimeDefaults ?? currentRuntimeDefaults(ctx, api),
+		runtimeOverrides: request.runtimeOverrides,
+		runtimeDefaults: currentRuntimeDefaults(ctx, api),
 		availableModels: availableWorkflowModels(ctx),
 		dynamicUi: dynamicUiFromContext(ctx),
 	});
@@ -736,8 +740,8 @@ async function startDynamicRunFromRequest(
 		);
 	const run = await runDynamicTask(ctx.cwd, {
 		task,
-		runtimeDefaults:
-			request.runtimeDefaults ?? currentRuntimeDefaults(ctx, api),
+		runtimeOverrides: request.runtimeOverrides,
+		runtimeDefaults: currentRuntimeDefaults(ctx, api),
 		availableModels: availableWorkflowModels(ctx),
 		dynamicUi: dynamicUiFromContext(ctx),
 	});
@@ -1047,7 +1051,7 @@ async function handleWorkflowCommand(
 			const specPath =
 				parsed.specPath ||
 				requireArg(tokens, 1, '/workflow run <workflow-name-or-path> "<task>"');
-			const runtimeDefaults =
+			const runtimeOverrides =
 				parsed.model || parsed.thinking
 					? { model: parsed.model, thinking: parsed.thinking }
 					: undefined;
@@ -1056,7 +1060,7 @@ async function handleWorkflowCommand(
 					workflow: specPath,
 					task: parsed.task,
 					detach: parsed.detach,
-					runtimeDefaults,
+					runtimeOverrides,
 				},
 				ctx,
 				api,
@@ -1067,7 +1071,7 @@ async function handleWorkflowCommand(
 
 		if (action === "dynamic") {
 			const parsed = parseWorkflowDynamicArgs(args);
-			const runtimeDefaults =
+			const runtimeOverrides =
 				parsed.model || parsed.thinking
 					? { model: parsed.model, thinking: parsed.thinking }
 					: undefined;
@@ -1075,7 +1079,7 @@ async function handleWorkflowCommand(
 				{
 					task: parsed.task,
 					detach: parsed.detach,
-					runtimeDefaults,
+					runtimeOverrides,
 				},
 				ctx,
 				api,

package/src/store.ts

@@ -43,6 +43,12 @@ const TERMINAL_INDEX_LIMIT = 50;
 const LEASE_STALE_MS = 30_000;
 const INDEX_LOCK_WAIT_MS = 5_000;
 const INDEX_LOCK_RETRY_MS = 50;
+const DEFAULT_INDEX_UPDATE_DEBOUNCE_MS = 500;
+let indexUpdateDebounceMs = DEFAULT_INDEX_UPDATE_DEBOUNCE_MS;
+const pendingIndexUpdates = new Map<
+	string,
+	{ cwd: string; runId: string; timer: ReturnType<typeof setTimeout> }
+>();
 const runLeaseContext = new AsyncLocalStorage<{
 	cwd: string;
 	runId: string;
@@ -350,7 +356,56 @@ export async function writeRunRecord(
 	const derived = deriveRunStatus(run);
 	Object.assign(run, derived);
 	await writeJsonAtomic(workflowRunPath(cwd, run.runId), run);
-	await updateIndex(cwd).catch(() => undefined);
+	scheduleIndexUpdate(cwd, run.runId, {
+		immediate: isTerminalWorkflowStatus(run.status),
+	});
+}
+
+function indexUpdateKey(cwd: string, runId: string): string {
+	return `${cwd}\0${runId}`;
+}
+
+function scheduleIndexUpdate(
+	cwd: string,
+	runId: string,
+	options: { immediate: boolean },
+): void {
+	const key = indexUpdateKey(cwd, runId);
+	const existing = pendingIndexUpdates.get(key);
+	if (existing) {
+		clearTimeout(existing.timer);
+		pendingIndexUpdates.delete(key);
+	}
+
+	const runUpdate = (): void => {
+		pendingIndexUpdates.delete(key);
+		void updateIndex(cwd, runId).catch(() => undefined);
+	};
+
+	if (options.immediate) {
+		runUpdate();
+		return;
+	}
+
+	// Pending debounced index writes are intentionally not flushed on process exit:
+	// the next explicit index rebuild/read path self-heals from run.json records.
+	const timer = setTimeout(runUpdate, indexUpdateDebounceMs);
+	timer.unref?.();
+	pendingIndexUpdates.set(key, { cwd, runId, timer });
+}
+
+export async function flushPendingIndexUpdatesForTests(): Promise<void> {
+	const pending = [...pendingIndexUpdates.values()];
+	pendingIndexUpdates.clear();
+	for (const item of pending) clearTimeout(item.timer);
+	await Promise.all(pending.map((item) => updateIndex(item.cwd, item.runId)));
+}
+
+export function setIndexUpdateDebounceMsForTests(value?: number): void {
+	indexUpdateDebounceMs =
+		value === undefined
+			? DEFAULT_INDEX_UPDATE_DEBOUNCE_MS
+			: Math.max(0, Math.floor(value));
 }
 
 export async function writeCompiledRunArtifact(
@@ -1088,55 +1143,19 @@ function isRunRecordLike(value: unknown): value is WorkflowRunRecord {
 	);
 }
 
-export async function updateIndex(cwd: string): Promise<WorkflowIndexRecord> {
+export async function updateIndex(
+	cwd: string,
+	changedRunId?: string,
+): Promise<WorkflowIndexRecord> {
 	const lockFile = join(workflowsRoot(cwd), "index.lock");
 	const ownerId = `${process.pid}-${randomBytes(3).toString("hex")}`;
 	await ensureDir(workflowsRoot(cwd));
 	await acquireLockWithWait(lockFile, ownerId);
 
 	try {
-		const runs = (await listRunRecords(cwd)).sort((left, right) =>
-			right.updatedAt.localeCompare(left.updatedAt),
-		);
-		const active = runs.filter((run) => !isTerminalWorkflowStatus(run.status));
-		const terminal = runs
-			.filter((run) => isTerminalWorkflowStatus(run.status))
-			.slice(0, TERMINAL_INDEX_LIMIT);
-		const selected = [...active, ...terminal].sort((left, right) =>
-			right.updatedAt.localeCompare(left.updatedAt),
-		);
-
-		const index: WorkflowIndexRecord = {
-			schemaVersion: 1,
-			updatedAt: nowIso(),
-			runs: selected.map((run) => ({
-				runId: run.runId,
-				name: run.name,
-				type: run.type,
-				artifactGraph: run.artifactGraph,
-				status: run.status,
-				taskSummary: run.taskSummary,
-				createdAt: run.createdAt,
-				updatedAt: run.updatedAt,
-				parentRunId: run.parentRunId,
-				rootRunId: run.rootRunId,
-				round: run.round,
-				fanout: run.fanout,
-				runJson: toProjectPath(cwd, workflowRunPath(cwd, run.runId)),
-				tasks: run.tasks.map((task) => ({
-					taskId: task.taskId,
-					displayName: task.displayName,
-					agent: task.agent,
-					kind: task.kind,
-					stageId: task.stageId,
-					backendHandle: task.backendHandle,
-					status: task.status,
-					statusDetail: task.statusDetail,
-					lastMessage: task.lastMessage,
-				})),
-			})),
-		};
-
+		const index = changedRunId
+			? await updateIndexIncremental(cwd, changedRunId)
+			: await rebuildIndex(cwd);
 		await writeJsonAtomic(workflowIndexPath(cwd), index);
 		return index;
 	} finally {
@@ -1144,6 +1163,122 @@ export async function updateIndex(cwd: string): Promise<WorkflowIndexRecord> {
 	}
 }
 
+type WorkflowIndexRunEntry = WorkflowIndexRecord["runs"][number];
+
+async function updateIndexIncremental(
+	cwd: string,
+	changedRunId: string,
+): Promise<WorkflowIndexRecord> {
+	const existing = await readIndexForIncremental(cwd);
+	if (!existing) return rebuildIndex(cwd);
+
+	let changedRun: WorkflowRunRecord;
+	try {
+		changedRun = await readRunRecord(cwd, changedRunId);
+	} catch {
+		return rebuildIndex(cwd);
+	}
+
+	const changedEntry = buildIndexEntry(cwd, changedRun);
+	const entries = existing.runs
+		.filter((entry) => entry.runId !== changedRun.runId)
+		.concat(changedEntry);
+	return {
+		schemaVersion: 1,
+		updatedAt: nowIso(),
+		runs: selectIndexEntries(entries),
+	};
+}
+
+async function readIndexForIncremental(
+	cwd: string,
+): Promise<WorkflowIndexRecord | undefined> {
+	let index: WorkflowIndexRecord | undefined;
+	try {
+		index = await readIndex(cwd);
+	} catch {
+		return undefined;
+	}
+	if (!isIndexRecordLike(index)) return undefined;
+	return index;
+}
+
+async function rebuildIndex(cwd: string): Promise<WorkflowIndexRecord> {
+	const runs = await listRunRecords(cwd);
+	return {
+		schemaVersion: 1,
+		updatedAt: nowIso(),
+		runs: selectIndexEntries(runs.map((run) => buildIndexEntry(cwd, run))),
+	};
+}
+
+function selectIndexEntries(
+	entries: WorkflowIndexRunEntry[],
+): WorkflowIndexRunEntry[] {
+	const sorted = [...entries].sort((left, right) =>
+		right.updatedAt.localeCompare(left.updatedAt),
+	);
+	const active = sorted.filter(
+		(entry) => !isTerminalWorkflowStatus(entry.status),
+	);
+	const terminal = sorted
+		.filter((entry) => isTerminalWorkflowStatus(entry.status))
+		.slice(0, TERMINAL_INDEX_LIMIT);
+	return [...active, ...terminal].sort((left, right) =>
+		right.updatedAt.localeCompare(left.updatedAt),
+	);
+}
+
+function buildIndexEntry(
+	cwd: string,
+	run: WorkflowRunRecord,
+): WorkflowIndexRunEntry {
+	return {
+		runId: run.runId,
+		name: run.name,
+		type: run.type,
+		artifactGraph: run.artifactGraph,
+		status: run.status,
+		taskSummary: run.taskSummary,
+		createdAt: run.createdAt,
+		updatedAt: run.updatedAt,
+		parentRunId: run.parentRunId,
+		rootRunId: run.rootRunId,
+		round: run.round,
+		fanout: run.fanout,
+		runJson: toProjectPath(cwd, workflowRunPath(cwd, run.runId)),
+		tasks: run.tasks.map((task) => ({
+			taskId: task.taskId,
+			displayName: task.displayName,
+			agent: task.agent,
+			kind: task.kind,
+			stageId: task.stageId,
+			backendHandle: task.backendHandle,
+			status: task.status,
+			statusDetail: task.statusDetail,
+			lastMessage: task.lastMessage,
+		})),
+	};
+}
+
+function isIndexRecordLike(
+	value: WorkflowIndexRecord | undefined,
+): value is WorkflowIndexRecord {
+	return (
+		value?.schemaVersion === 1 &&
+		Array.isArray(value.runs) &&
+		value.runs.every(
+			(entry) =>
+				entry &&
+				typeof entry === "object" &&
+				typeof entry.runId === "string" &&
+				typeof entry.updatedAt === "string" &&
+				typeof entry.status === "string" &&
+				Array.isArray(entry.tasks),
+		)
+	);
+}
+
 export function deriveRunStatus(run: WorkflowRunRecord): WorkflowRunRecord {
 	const next = { ...run, tasks: run.tasks };
 	next.taskSummary = summarizeTasks(next.tasks);

package/src/subagent-backend.ts

@@ -17,6 +17,7 @@ import {
 	resolve,
 	sep,
 } from "node:path";
+import { availableParallelism } from "node:os";
 import { fileURLToPath } from "node:url";
 
 import type {
@@ -55,6 +56,10 @@ const FETCH_CONTENT_CACHE_ENV = "PI_WORKFLOW_FETCH_CONTENT_CACHE";
 const LEGACY_FETCH_CACHE_ENV = "PI_WORKFLOW_FETCH_CACHE";
 const DEFAULT_TRANSIENT_MODEL_FAILURE_RETRIES = 5;
 const DEFAULT_ARTIFACT_OUTPUT_RETRIES = 2;
+const MAX_CONCURRENT_LAUNCHES_ENV = "PI_WORKFLOW_MAX_CONCURRENT_LAUNCHES";
+const DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS = 3_000;
+const MIN_TRANSIENT_RETRY_JITTER_MS = 1_000;
+const MAX_TRANSIENT_RETRY_JITTER_MS = 5_000;
 const MODULE_PATH = fileURLToPath(import.meta.url);
 const MODULE_DIR = dirname(MODULE_PATH);
 const BUNDLED_PI_WEB_ACCESS_EXTENSION = bundledNodeModulePath(
@@ -175,6 +180,103 @@ async function loadSubagentApi(): Promise<SubagentApi> {
 	return cachedSubagentApi;
 }
 
+let launchSlotReleaseDelayMs = DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS;
+let transientRetryJitterForTests: (() => number) | undefined;
+const launchWaitQueue: Array<() => void> = [];
+let activeLaunchSlots = 0;
+
+function resolveMaxConcurrentLaunches(): number {
+	const override = Number.parseInt(
+		process.env[MAX_CONCURRENT_LAUNCHES_ENV] ?? "",
+		10,
+	);
+	if (Number.isFinite(override)) return Math.max(1, Math.floor(override));
+	return Math.max(2, Math.floor(availableParallelism() / 2));
+}
+
+function isLaunchGateSaturated(): boolean {
+	return activeLaunchSlots >= resolveMaxConcurrentLaunches();
+}
+
+async function acquireLaunchSlot(): Promise<() => void> {
+	if (!isLaunchGateSaturated()) {
+		activeLaunchSlots += 1;
+		return releaseLaunchSlot;
+	}
+	await new Promise<void>((resolveWait) => launchWaitQueue.push(resolveWait));
+	return releaseLaunchSlot;
+}
+
+function releaseLaunchSlot(): void {
+	const next = launchWaitQueue.shift();
+	if (next) {
+		// Transfer the occupied slot directly to the queued launcher.
+		next();
+		return;
+	}
+	activeLaunchSlots = Math.max(0, activeLaunchSlots - 1);
+}
+
+function releaseLaunchSlotAfterDelay(
+	delayMs: number,
+	release: () => void,
+): void {
+	if (delayMs <= 0) {
+		release();
+		return;
+	}
+	const timer = setTimeout(release, delayMs);
+	timer.unref?.();
+}
+
+async function runWithLaunchSlot<T>(action: () => Promise<T>): Promise<T> {
+	const release = await acquireLaunchSlot();
+	let holdAfterReturn = false;
+	try {
+		const result = await action();
+		holdAfterReturn = true;
+		return result;
+	} finally {
+		releaseLaunchSlotAfterDelay(
+			holdAfterReturn ? launchSlotReleaseDelayMs : 0,
+			release,
+		);
+	}
+}
+
+function transientRetryJitterMs(): number {
+	if (transientRetryJitterForTests) return transientRetryJitterForTests();
+	return (
+		MIN_TRANSIENT_RETRY_JITTER_MS +
+		Math.floor(
+			Math.random() *
+				(MAX_TRANSIENT_RETRY_JITTER_MS - MIN_TRANSIENT_RETRY_JITTER_MS + 1),
+		)
+	);
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function setSubagentLaunchControlsForTests(options?: {
+	releaseDelayMs?: number;
+	retryJitterMs?: number | (() => number);
+}): void {
+	launchSlotReleaseDelayMs =
+		options?.releaseDelayMs === undefined
+			? DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS
+			: Math.max(0, Math.floor(options.releaseDelayMs));
+	transientRetryJitterForTests =
+		options?.retryJitterMs === undefined
+			? undefined
+			: typeof options.retryJitterMs === "function"
+				? options.retryJitterMs
+				: () => Math.max(0, Math.floor(options.retryJitterMs as number));
+	activeLaunchSlots = 0;
+	while (launchWaitQueue.length > 0) launchWaitQueue.shift()?.();
+}
+
 export async function cleanupSubagentRun(
 	_cwd: string,
 	run: WorkflowRunRecord,
@@ -212,6 +314,14 @@ export async function launchSubagentTask(
 		};
 	}
 
+	if ((task.launchRetry?.attempts ?? 0) > 0) {
+		const jitterMs = transientRetryJitterMs();
+		task.statusDetail = "retry_model_failure";
+		task.lastMessage = `waiting ${jitterMs}ms before retrying transient-model launch`;
+		await writeRunRecord(cwd, run);
+		if (jitterMs > 0) await sleep(jitterMs);
+	}
+
 	const systemPromptFile = fromProjectPath(cwd, task.files.systemPrompt);
 	const taskPromptFile = fromProjectPath(cwd, task.files.taskPrompt);
 	const outputFile = fromProjectPath(cwd, task.files.output);
@@ -267,7 +377,11 @@ export async function launchSubagentTask(
 		};
 		subagentOptions.extensions = extensions;
 		if (captureToolCallsEnabled()) subagentOptions.captureToolCalls = true;
-		launched = await api.runSubagent(subagentOptions);
+		if (isLaunchGateSaturated()) {
+			task.lastMessage = `waiting for pi-subagent launch slot (${resolveMaxConcurrentLaunches()} max)`;
+			await writeRunRecord(cwd, run).catch(() => undefined);
+		}
+		launched = await runWithLaunchSlot(() => api.runSubagent(subagentOptions));
 	} catch (error) {
 		task.status = "pending";
 		task.statusDetail = "pending";
@@ -432,12 +546,29 @@ async function materializeTerminalSubagentResult(
 		artifactRoot,
 	);
 	const outputText = await readFile(outputFile, "utf8").catch(() => "");
+	const stderrText = await readFile(stderrFile, "utf8").catch(() => "");
 	const outputBytes = Buffer.byteLength(outputText, "utf8");
-	const statusInfo = workflowStatusFromSubagent(
+	let statusInfo = workflowStatusFromSubagent(
 		snapshot,
 		subagentResult,
 		outputBytes,
 	);
+	const deterministicBootFailure = classifyDeterministicBootFailure({
+		statusInfo,
+		stderrText,
+		outputBytes,
+		contextLengthExceeded: Boolean(
+			(subagentResult?.metadata as any)?.contextLengthExceeded ??
+				snapshot.metadata?.contextLengthExceeded,
+		),
+	});
+	if (deterministicBootFailure) {
+		statusInfo = {
+			status: "failed",
+			failureKind: "deterministic_boot",
+			errorMessage: deterministicBootFailure,
+		};
+	}
 	const completedAt =
 		typeof subagentResult?.completedAt === "string"
 			? subagentResult.completedAt
@@ -1005,6 +1136,36 @@ function failArtifactGraphTask(
 	return true;
 }
 
+function classifyDeterministicBootFailure(options: {
+	statusInfo: {
+		status: WorkflowTaskRunRecord["status"];
+		failureKind?: string;
+		errorMessage?: string;
+	};
+	stderrText: string;
+	outputBytes: number;
+	contextLengthExceeded: boolean;
+}): string | undefined {
+	if (
+		options.statusInfo.status !== "failed" ||
+		options.statusInfo.failureKind !== "model" ||
+		options.outputBytes !== 0 ||
+		options.contextLengthExceeded
+	) {
+		return undefined;
+	}
+	const text = options.stderrText;
+	const deterministicPattern =
+		/(Failed to load extension|Cannot find module|(?:failed to load|invalid|missing) (?:workflow )?config(?:uration)?|config(?:uration)? (?:error|failed|invalid))/i;
+	if (!deterministicPattern.test(text)) return undefined;
+	const excerpt =
+		text
+			.split(/\r?\n/)
+			.map((line) => line.trim())
+			.find((line) => deterministicPattern.test(line)) ?? text.trim();
+	return `deterministic-boot failure: ${excerpt.slice(0, 500)}`;
+}
+
 function shouldRetryTransientModelFailure(
 	statusInfo: {
 		status: WorkflowTaskRunRecord["status"];
@@ -1056,14 +1217,14 @@ function retryOrFailTransientSubagentFailure(
 	if (!exhausted) {
 		task.status = "pending";
 		task.statusDetail = "retry_model_failure";
-		task.lastMessage = `${options.message}; retrying transient model failure (${attempt}/${maxAttempts})`;
+		task.lastMessage = `${options.message}; retrying transient-model failure (${attempt}/${maxAttempts})`;
 		return true;
 	}
 	task.status = "failed";
 	task.statusDetail = task.launchRetry.reason ?? "model_exhausted";
 	task.exitCode = 1;
 	task.completedAt = nowIso();
-	task.lastMessage = `${options.message}; transient model failure retries exhausted (${maxAttempts})`;
+	task.lastMessage = `${options.message}; transient-model failure retries exhausted (${maxAttempts})`;
 	return true;
 }
 
@@ -1317,7 +1478,10 @@ async function workflowTaskExtensions(
 			},
 		});
 		const capturedProviderExtensions = new Set(
-			workflowWebSourceProviderExtensions(tools, compiledTask.runtime.toolProviders),
+			workflowWebSourceProviderExtensions(
+				tools,
+				compiledTask.runtime.toolProviders,
+			),
 		);
 		extensions = uniqueStrings([
 			...extensions.filter(
@@ -1673,7 +1837,7 @@ function buildSystemPrompt(task: CompiledTask): string {
 		enabledTools.includes("workflow_web_source_read")
 			? "Workflow web-source tools return compact source cards. Preserve sourceRef values in structured outputs. Use workflow_web_source_read for exact evidence snippets; when several snippets are needed from the same sourceRef, batch them with queries:[...] or reads:[...] instead of making repeated calls. If the exact quote is unknown, pass claim plus 2-6 distinctive terms to harvest a candidate source window and preserve its match metadata. Do not read workflow cache files directly."
 			: !enabledTools.includes("get_search_content") &&
-				  (enabledTools.includes("web_search") ||
+					(enabledTools.includes("web_search") ||
 						enabledTools.includes("fetch_content"))
 				? "Full cached search-content hydration is unavailable here. Use web_search/fetch_content results and report evidence gaps instead of broad raw document retrieval."
 				: undefined,

package/src/types.ts

@@ -1,4 +1,8 @@
-import type { WorkflowRuntimeThinkingResolution } from "./workflow-runtime.js";
+import type {
+	WorkflowModelInfo,
+	WorkflowRuntimeDefaults,
+	WorkflowRuntimeThinkingResolution,
+} from "./workflow-runtime.js";
 
 export const THINKING_LEVELS = [
 	"off",
@@ -472,6 +476,8 @@ export interface CompiledDynamicWorkflowTask {
 	helpers: Record<string, CompiledDynamicWorkflowHelper>;
 	workflows: Record<string, CompiledDynamicNestedWorkflow>;
 	decisionLoop?: CompiledDynamicDecisionLoop;
+	runtimeOverrides?: WorkflowRuntimeDefaults;
+	availableModels?: WorkflowModelInfo[];
 }
 
 export interface CompiledArtifactGraphTask {

package/src/workflow-runtime.ts

@@ -46,6 +46,41 @@ export interface ResolveWorkflowRuntimeOptions {
 	prompt?: WorkflowRuntimePrompt;
 }
 
+export type WorkflowRuntimeLayer = WorkflowRuntimeDefaults | undefined;
+
+export function selectWorkflowRuntime(
+	...layers: WorkflowRuntimeLayer[]
+): WorkflowRuntimeResolutionInput {
+	const modelLayer = layers.find((layer) => modelOf(layer));
+	const model = modelOf(modelLayer);
+	let thinking: ThinkingLevel | undefined;
+	for (const layer of layers) {
+		if (!layer) continue;
+		if (layer.thinking) {
+			thinking = layer.thinking;
+			break;
+		}
+		const layerModel = modelOf(layer);
+		const modelThinking = layerModel
+			? splitKnownThinkingSuffix(layerModel).thinking
+			: undefined;
+		if (modelThinking) {
+			thinking = modelThinking;
+			break;
+		}
+	}
+	return {
+		...(model ? { model } : {}),
+		...(thinking ? { thinking } : {}),
+	};
+}
+
+function modelOf(layer: WorkflowRuntimeLayer): string | undefined {
+	return typeof layer?.model === "string" && layer.model.trim()
+		? layer.model.trim()
+		: undefined;
+}
+
 export function toWorkflowModelInfo(model: {
 	provider: string;
 	id: string;