@agwab/pi-workflow 0.2.0 → 0.3.0

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,15 @@ 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 PARENT_SUBAGENT_CWD_ENV = "PI_WORKFLOW_PARENT_SUBAGENT_CWD";
+const PARENT_SUBAGENT_RUNS_DIR_ENV = "PI_WORKFLOW_PARENT_SUBAGENT_RUNS_DIR";
+const PARENT_SUBAGENT_RUN_ID_ENV = "PI_WORKFLOW_PARENT_SUBAGENT_RUN_ID";
+const PARENT_SUBAGENT_ATTEMPT_ID_ENV = "PI_WORKFLOW_PARENT_SUBAGENT_ATTEMPT_ID";
+const DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS = 3_000;
+const STALE_LAUNCH_CLAIM_GRACE_MS = 30_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(
@@ -156,8 +166,31 @@ interface SubagentApi {
 	): Promise<SubagentRunStatusSnapshot | null>;
 	interruptSubagent(options: Record<string, unknown>): Promise<unknown>;
 	reconcileSubagentRun(options: Record<string, unknown>): Promise<unknown>;
+	recordSubagentChildEvent?(
+		options: Record<string, unknown>,
+	): Promise<unknown>;
+}
+
+type ParentSubagentChildEvent =
+	| "started"
+	| "completed"
+	| "failed"
+	| "cancelled";
+
+interface ParentSubagentRef {
+	cwd: string;
+	runsDir: string;
+	runId: string;
+	attemptId?: string;
 }
 
+const GENERIC_TASK_STATUS_DETAILS = new Set([
+	"completed",
+	"failed",
+	"interrupted",
+	"running",
+]);
+
 const subagentApiSpecifier = "@agwab/pi-subagent/api";
 let cachedSubagentApi: Promise<SubagentApi> | undefined;
 let injectedSubagentApi: SubagentApi | undefined;
@@ -175,12 +208,186 @@ async function loadSubagentApi(): Promise<SubagentApi> {
 	return cachedSubagentApi;
 }
 
+function nonEmptyEnv(
+	env: Record<string, string | undefined>,
+	key: string,
+): string | undefined {
+	const value = env[key]?.trim();
+	return value ? value : undefined;
+}
+
+function parentSubagentRefFromEnv(
+	env: Record<string, string | undefined> = process.env,
+): ParentSubagentRef | undefined {
+	const cwd = nonEmptyEnv(env, PARENT_SUBAGENT_CWD_ENV);
+	const runsDir = nonEmptyEnv(env, PARENT_SUBAGENT_RUNS_DIR_ENV);
+	const runId = nonEmptyEnv(env, PARENT_SUBAGENT_RUN_ID_ENV);
+	if (!cwd || !runsDir || !runId) return undefined;
+	const attemptId = nonEmptyEnv(env, PARENT_SUBAGENT_ATTEMPT_ID_ENV);
+	return { cwd, runsDir, runId, ...(attemptId ? { attemptId } : {}) };
+}
+
+function terminalChildEventForTaskStatus(
+	status: WorkflowTaskRunRecord["status"],
+): ParentSubagentChildEvent | undefined {
+	if (status === "completed") return "completed";
+	if (status === "failed") return "failed";
+	if (status === "interrupted") return "cancelled";
+	return undefined;
+}
+
+async function recordParentSubagentChildEvent(options: {
+	event: ParentSubagentChildEvent;
+	childRunId: string;
+	run: WorkflowRunRecord;
+	task: WorkflowTaskRunRecord;
+	failureKind?: string | null;
+	message?: string;
+}): Promise<void> {
+	const parent = parentSubagentRefFromEnv();
+	if (!parent) return;
+	const api = await loadSubagentApi().catch(() => undefined);
+	if (!api?.recordSubagentChildEvent) return;
+	await api
+		.recordSubagentChildEvent({
+			...parent,
+			event: options.event,
+			childRunId: options.childRunId,
+			workflowRunId: options.run.runId,
+			childTaskId: options.task.taskId,
+			...(options.failureKind === undefined
+				? {}
+				: { failureKind: options.failureKind }),
+			...(options.message === undefined ? {} : { message: options.message }),
+		})
+		.catch(() => undefined);
+}
+
+async function recordTerminalParentSubagentChildEvent(
+	run: WorkflowRunRecord,
+	task: WorkflowTaskRunRecord,
+	snapshot: SubagentRunStatusSnapshot,
+): Promise<void> {
+	const event = terminalChildEventForTaskStatus(task.status);
+	if (!event) return;
+	const taskFailureKind =
+		task.statusDetail && !GENERIC_TASK_STATUS_DETAILS.has(task.statusDetail)
+			? task.statusDetail
+			: undefined;
+	await recordParentSubagentChildEvent({
+		event,
+		childRunId: snapshot.runId,
+		run,
+		task,
+		failureKind:
+			event === "completed"
+				? undefined
+				: (snapshot.failureKind ?? taskFailureKind ?? task.statusDetail),
+		message: task.lastMessage,
+	});
+}
+
+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;
+	}
+	setTimeout(release, delayMs);
+}
+
+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,
 ): Promise<void> {
 	for (const task of run.tasks) {
-		if (isTerminalTaskStatus(task.status)) continue;
 		const handle = getSubagentHandle(task);
 		if (!handle) continue;
 		const api = await loadSubagentApi();
@@ -212,6 +419,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 +482,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";
@@ -295,6 +514,13 @@ export async function launchSubagentTask(
 	task.statusDetail = "running";
 	task.lastMessage = "launched via pi-subagent/headless";
 	await writeRunRecord(cwd, run).catch(() => undefined);
+	await recordParentSubagentChildEvent({
+		event: "started",
+		childRunId: launched.runId,
+		run,
+		task,
+		message: task.lastMessage,
+	});
 	return { kind: "launched" };
 }
 
@@ -326,8 +552,13 @@ export async function refreshRunFromSubagentArtifacts(
 			}
 		}
 		if (!handle) {
+			if (isStaleLaunchClaim(task)) {
+				resetStaleLaunchClaim(task);
+				changed = true;
+				continue;
+			}
 			if (isTaskTimedOut(task)) {
-				markTaskTimedOut(task);
+				markSubagentTaskTimedOut(task);
 				changed = true;
 			}
 			continue;
@@ -352,16 +583,8 @@ export async function refreshRunFromSubagentArtifacts(
 
 		if (snapshot === null) {
 			if (isTaskTimedOut(task)) {
-				await api
-					.interruptSubagent({
-						cwd: handle.cwd,
-						runsDir: handle.runsDir,
-						runId: handle.runId,
-						attemptId: handle.attemptId,
-						reason: "workflow timeout",
-					})
-					.catch(() => undefined);
-				markTaskTimedOut(task);
+				await interruptTimedOutSubagent(api, handle);
+				markSubagentTaskTimedOut(task);
 				changed = true;
 			}
 			continue;
@@ -378,16 +601,8 @@ export async function refreshRunFromSubagentArtifacts(
 				? `pi-subagent heartbeat ${activeAttempt.heartbeatAt}`
 				: "pi-subagent running";
 			if (isTaskTimedOut(task)) {
-				await api
-					.interruptSubagent({
-						cwd: handle.cwd,
-						runsDir: handle.runsDir,
-						runId: handle.runId,
-						attemptId: handle.attemptId,
-						reason: "workflow timeout",
-					})
-					.catch(() => undefined);
-				markTaskTimedOut(task);
+				await interruptTimedOutSubagent(api, handle);
+				markSubagentTaskTimedOut(task);
 				changed = true;
 			}
 			continue;
@@ -401,6 +616,48 @@ export async function refreshRunFromSubagentArtifacts(
 	return run;
 }
 
+async function interruptTimedOutSubagent(
+	api: Awaited<ReturnType<typeof loadSubagentApi>>,
+	handle: NonNullable<WorkflowTaskRunRecord["backendHandle"]>,
+): Promise<void> {
+	await api
+		.interruptSubagent({
+			cwd: handle.cwd,
+			runsDir: handle.runsDir,
+			runId: handle.runId,
+			attemptId: handle.attemptId,
+			reason: "workflow timeout",
+		})
+		.catch(() => undefined);
+}
+
+function markSubagentTaskTimedOut(task: WorkflowTaskRunRecord): void {
+	markTaskTimedOut(task);
+	task.backendHandle = undefined;
+	task.backendTaskId = task.taskId;
+	task.pid = undefined;
+}
+
+function isStaleLaunchClaim(task: WorkflowTaskRunRecord): boolean {
+	if (task.statusDetail !== "launching" || !task.startedAt) return false;
+	const startedAtMs = Date.parse(task.startedAt);
+	return (
+		Number.isFinite(startedAtMs) &&
+		Date.now() - startedAtMs > STALE_LAUNCH_CLAIM_GRACE_MS
+	);
+}
+
+function resetStaleLaunchClaim(task: WorkflowTaskRunRecord): void {
+	task.status = "pending";
+	task.statusDetail = "pending";
+	task.startedAt = undefined;
+	task.backendHandle = undefined;
+	task.backendFiles = undefined;
+	task.backendTaskId = task.taskId;
+	task.pid = undefined;
+	task.lastMessage = "stale pi-subagent launch claim reset";
+}
+
 async function materializeTerminalSubagentResult(
 	cwd: string,
 	run: WorkflowRunRecord,
@@ -432,12 +689,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
@@ -462,7 +736,7 @@ async function materializeTerminalSubagentResult(
 			snapshot.metadata?.contextLengthExceeded,
 	);
 	if (task.artifactGraph?.enabled && statusInfo.status === "completed") {
-		return await materializeTerminalArtifactGraphResult(cwd, run, task, {
+		const changed = await materializeTerminalArtifactGraphResult(cwd, run, task, {
 			outputFile,
 			stderrFile,
 			resultFile,
@@ -471,6 +745,8 @@ async function materializeTerminalSubagentResult(
 			exitCode,
 			subagentResult,
 		});
+		await recordTerminalParentSubagentChildEvent(run, task, snapshot);
+		return changed;
 	}
 	if (
 		shouldAttemptArtifactGraphSalvage({
@@ -484,7 +760,7 @@ async function materializeTerminalSubagentResult(
 			snapshot,
 		})
 	) {
-		return await materializeTerminalArtifactGraphResult(cwd, run, task, {
+		const changed = await materializeTerminalArtifactGraphResult(cwd, run, task, {
 			outputFile,
 			stderrFile,
 			resultFile,
@@ -498,6 +774,8 @@ async function materializeTerminalSubagentResult(
 				subagentFailureKind: snapshot.failureKind,
 			},
 		});
+		await recordTerminalParentSubagentChildEvent(run, task, snapshot);
+		return changed;
 	}
 	const workflowResult = {
 		status: statusInfo.status,
@@ -533,10 +811,12 @@ async function materializeTerminalSubagentResult(
 			),
 			workflowResult,
 		);
-		return retryOrFailTransientSubagentFailure(task, {
+		const changed = retryOrFailTransientSubagentFailure(task, {
 			reason: statusInfo.failureKind ?? "model",
 			message: errorMessage ?? "pi-subagent run failed before producing output",
 		});
+		await recordTerminalParentSubagentChildEvent(run, task, snapshot);
+		return changed;
 	}
 	await writeJson(resultFile, workflowResult);
 
@@ -551,6 +831,7 @@ async function materializeTerminalSubagentResult(
 		delete task.backendHandle;
 		delete task.backendFiles;
 	}
+	await recordTerminalParentSubagentChildEvent(run, task, snapshot);
 	return changed;
 }
 
@@ -1005,6 +1286,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 +1367,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 +1628,10 @@ async function workflowTaskExtensions(
 			},
 		});
 		const capturedProviderExtensions = new Set(
-			workflowWebSourceProviderExtensions(tools, compiledTask.runtime.toolProviders),
+			workflowWebSourceProviderExtensions(
+				tools,
+				compiledTask.runtime.toolProviders,
+			),
 		);
 		extensions = uniqueStrings([
 			...extensions.filter(
@@ -1510,6 +1824,7 @@ async function recoverSubagentHandle(
 	const runsDir = subagentRunsDir(run, task);
 	const absoluteRunsDir = resolve(task.cwd, runsDir);
 	const expectedCorrelationId = `${run.runId}:${task.taskId}`;
+	const claimStartedAtMs = timestampMs(task.startedAt);
 	const entries = await readdir(absoluteRunsDir, { withFileTypes: true }).catch(
 		() => [],
 	);
@@ -1524,6 +1839,7 @@ async function recoverSubagentHandle(
 			join(absoluteRunsDir, entry.name, "run.json"),
 		);
 		if (!record || record.correlationId !== expectedCorrelationId) continue;
+		if (isPreClaimSubagentRecord(record, claimStartedAtMs)) continue;
 		const attemptId =
 			record.activeAttemptId ??
 			record.latestAttemptId ??
@@ -1550,6 +1866,20 @@ async function recoverSubagentHandle(
 	return candidates[0]?.handle;
 }
 
+function isPreClaimSubagentRecord(
+	record: SubagentRunRecordLike,
+	claimStartedAtMs: number | undefined,
+): boolean {
+	if (claimStartedAtMs === undefined) return false;
+	const recordStartedAtMs =
+		timestampMs(record.startedAt) ??
+		timestampMs(record.attempts?.[0]?.startedAt) ??
+		timestampMs(record.updatedAt);
+	return (
+		recordStartedAtMs !== undefined && recordStartedAtMs < claimStartedAtMs
+	);
+}
+
 function timestampMs(value: string | undefined): number | undefined {
 	if (value === undefined) return undefined;
 	const time = Date.parse(value);
@@ -1610,7 +1940,14 @@ function subagentSessionId(
 	task: WorkflowTaskRunRecord,
 ): string | undefined {
 	if (!task.artifactGraph?.enabled) return undefined;
-	return task.outputRetry?.sessionId ?? baseSubagentSessionId(run, task);
+	const baseSessionId = baseSubagentSessionId(run, task);
+	if (task.outputRetry?.sessionId) return task.outputRetry.sessionId;
+	const launchAttempt = task.launchRetry?.attempts ?? 0;
+	if (launchAttempt > 0)
+		return `${baseSessionId}:launch-retry-${launchAttempt}`;
+	const resumeAttempt = task.resumeEvents?.length ?? 0;
+	if (resumeAttempt > 0) return `${baseSessionId}:resume-${resumeAttempt}`;
+	return baseSessionId;
 }
 
 function baseSubagentSessionId(
@@ -1673,7 +2010,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 {
@@ -536,6 +542,9 @@ export interface CompiledTask {
 		branchId?: string;
 		outputProfile?: string;
 	};
+	foreachGenerated?: {
+		placeholderSpecId: string;
+	};
 	loopChild?: CompiledLoopChildTaskRef;
 	loopPlaceholder?: {
 		loopId: string;
@@ -628,6 +637,9 @@ export interface WorkflowTaskRunRecord {
 		branchId?: string;
 		outputProfile?: string;
 	};
+	foreachGenerated?: {
+		placeholderSpecId: string;
+	};
 	launchRetry?: {
 		attempts: number;
 		maxAttempts?: number;

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;
@@ -310,9 +345,25 @@ export function readSimpleJsonPath(value: unknown, path: string): unknown {
 	const parts = path.slice(2).split(".").filter(Boolean);
 	let current = value as any;
 	for (const part of parts) {
-		if (current === null || typeof current !== "object" || !(part in current))
-			return undefined;
+		if (!canReadJsonPathPart(current, part)) return undefined;
 		current = current[part];
 	}
 	return current;
 }
+
+function canReadJsonPathPart(
+	value: unknown,
+	part: string,
+): value is Record<string, unknown> {
+	return (
+		isSafeJsonPathPart(part) && isRecord(value) && Object.hasOwn(value, part)
+	);
+}
+
+function isSafeJsonPathPart(part: string): boolean {
+	return part !== "__proto__" && part !== "prototype" && part !== "constructor";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}