pi-subagents 0.56.0 → 0.58.0

package/src/workflows/scripted-workflow.ts

@@ -6,6 +6,17 @@ import { Worker } from "node:worker_threads";
 const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const requireFromPackage = createRequire(import.meta.url);
 
+export interface WorkflowScriptValidationError {
+	message: string;
+	line?: number;
+	column?: number;
+}
+
+export interface WorkflowScriptValidationResult {
+	ok: boolean;
+	errors: WorkflowScriptValidationError[];
+}
+
 const WORKER_SOURCE = String.raw`
 const { parentPort, workerData } = require("node:worker_threads");
 const vm = require("node:vm");
@@ -440,7 +451,7 @@ function isSyntaxError(error) {
   return error instanceof SyntaxError || error?.name === "SyntaxError";
 }
 
-const NESTED_ASYNC_WORKFLOW_ERROR = "workflowScript does not support nested async functions. Use top-level await, plain helper functions that return runs.run(...), or explicit Promise chains so workflows stay portable across Node and Bun.";
+const NESTED_ASYNC_WORKFLOW_ERROR = "workflowScript validation failed before child launch; no children launched. workflowScript does not support nested async functions. Use top-level await, plain helper functions that return runs.run(...), or explicit Promise chains so workflows stay portable across Node and Bun. Parallel plus sequential rewrite: const a = runs.run(\"a\", { agent: \"worker\", task: \"A\" }); const writer = await runs.run(\"writer\", { agent: \"worker\", task: \"Write\" }); const review = await runs.run(\"review\", { agent: \"reviewer\", task: writer.output }); const [aResult] = await Promise.all([a]); return { a: aResult.output, issue: { writerRunId: writer.runId, reviewRunId: review.runId } };";
 const AST_SCALAR_KEYS = new Set(["type", "start", "end"]);
 
 function assertPortableWorkflowScript(source) {
@@ -627,7 +638,12 @@ parentPort.on("message", async (message) => {
       }
     }
     const persistedValue = value === undefined ? null : omitUndefinedWorkflowValues(value);
-    assertJsonValue(persistedValue, "return");
+    try {
+      assertJsonValue(persistedValue, "return");
+    } catch (error) {
+      parentPort.postMessage({ type: "error", errorPhase: "return-serialization", error: formatWorkflowScriptError(error) });
+      return;
+    }
     parentPort.postMessage({ type: "complete", value: persistedValue });
   } catch (error) {
     parentPort.postMessage({ type: "error", error: isSyntaxError(error) ? formatWorkflowScriptSyntaxError(error) : formatWorkflowScriptError(error), ...(error && error.workflowErrorKind === "detached-child" ? { errorKind: "detached-child" } : {}) });
@@ -638,6 +654,7 @@ parentPort.on("message", async (message) => {
 export interface WorkflowScriptChildResult {
 	key: string;
 	ok: boolean;
+	terminalOutcome?: import("../shared/types.ts").WorkflowTerminalOutcome;
 	stopped?: boolean;
 	/** Canonical child agent name when launch resolution produced one. */
 	agent?: string;
@@ -650,6 +667,8 @@ export interface WorkflowScriptChildResult {
 	requestedContext?: "fresh" | "fork";
 	resolvedContext?: "fresh" | "fork" | "mixed";
 	outputReference?: string;
+	outputPathMapping?: { requestedPath: string; savedPath: string };
+	externalAdapter?: import("../shared/types.ts").ExternalCliReceiptMetadata;
 	resumability?: { state: "resumable" } | { state: "not-resumable"; reason: string };
 	continuation?: { runIds: string[] };
 	artifactPaths: string[];
@@ -705,9 +724,9 @@ export interface WorkflowScriptResult {
 
 export class WorkflowScriptError extends Error {
 	readonly partial: Omit<WorkflowScriptResult, "value">;
-	readonly errorKind?: "detached-child";
+	readonly errorKind?: "detached-child" | "timeout";
 
-	constructor(message: string, partial: Omit<WorkflowScriptResult, "value">, errorKind?: "detached-child") {
+	constructor(message: string, partial: Omit<WorkflowScriptResult, "value">, errorKind?: "detached-child" | "timeout") {
 		super(message);
 		this.name = "WorkflowScriptError";
 		this.partial = partial;
@@ -717,10 +736,12 @@ export class WorkflowScriptError extends Error {
 
 export interface RunWorkflowScriptOptions {
 	script: string;
+	/** Host-only first-slice admission context. It is never sent to the workflow worker. */
+	oneUsePermit?: { claim: (key: string) => string | undefined };
 	timeoutMs?: number;
 	signal?: AbortSignal;
 	admit?: (calls: Array<{ key: string; params: Record<string, unknown> }>) => void | Promise<void>;
-	launch: (key: string, params: Record<string, unknown>, signal: AbortSignal, admission: { admitted: boolean }) => Promise<WorkflowScriptChildResult>;
+	launch: (key: string, params: Record<string, unknown>, signal: AbortSignal, admission: { admitted: boolean; batch: boolean }) => Promise<WorkflowScriptChildResult>;
 	resolveResume?: (reference: WorkflowReceiptResumeReference, signal: AbortSignal) => string | WorkflowResolvedResumeReference | Promise<string | WorkflowResolvedResumeReference>;
 	status: (keyOrRunId: string, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
 	steer?: (key: string, message: string, options: WorkflowSteerOptions, signal: AbortSignal) => Promise<WorkflowSteerResult>;
@@ -827,6 +848,15 @@ export function formatWorkflowJsonPreview(value: unknown, maxLength: number): st
 	}
 }
 
+function workflowReturnRecoveryHint(children: WorkflowScriptChildResult[]): string {
+	if (children.length === 0) return " Return only plain JSON data. For a child result, select fields such as { runId: child.runId, ok: child.ok, outputReference: child.outputReference }.";
+	const references = children.slice(0, 10).map((child) => {
+		const fields = [child.runId ? `runId=${child.runId.slice(0, 500)}` : undefined, child.outputReference ? `outputReference=${child.outputReference.slice(0, 500)}` : undefined, child.artifactPaths[0] ? `artifact=${child.artifactPaths[0].slice(0, 500)}` : undefined].filter((field): field is string => field !== undefined);
+		return `'${child.key}'${fields.length > 0 ? ` (${fields.join(", ")})` : ""}`;
+	});
+	return ` Child work completed before return serialization failed. Recover outputs from: ${references.join(", ")}${children.length > references.length ? `, and ${children.length - references.length} more` : ""}. Return a plain projection such as { runId: child.runId, ok: child.ok, outputReference: child.outputReference }.`;
+}
+
 export interface SimpleWorkflowRunPreview {
 	agent?: string;
 	task?: string;
@@ -864,6 +894,194 @@ function validateKey(value: unknown, owner = "runs.run"): string {
 	return value;
 }
 
+type AstNode = {
+	type: string;
+	loc?: { start: { line: number; column: number } };
+	[key: string]: unknown;
+};
+
+const AST_LOCATION_KEYS = new Set(["type", "start", "end", "loc", "range"]);
+
+function astNode(value: unknown): value is AstNode {
+	return Boolean(value) && typeof value === "object" && typeof (value as { type?: unknown }).type === "string";
+}
+
+function literalString(node: unknown): string | undefined {
+	if (!astNode(node)) return undefined;
+	if (node.type === "Literal" && typeof node.value === "string") return node.value;
+	if (node.type === "TemplateLiteral" && Array.isArray(node.expressions) && node.expressions.length === 0 && Array.isArray(node.quasis)) {
+		const first = node.quasis[0] as { value?: { cooked?: unknown } } | undefined;
+		if (typeof first?.value?.cooked === "string") return first.value.cooked;
+	}
+	return undefined;
+}
+
+function directRunsCall(node: unknown, method: "run" | "all"): node is AstNode {
+	if (!astNode(node) || node.type !== "CallExpression" || !astNode(node.callee) || node.callee.type !== "MemberExpression") return false;
+	const property = node.callee.computed === true ? literalString(node.callee.property) : astNode(node.callee.property) && node.callee.property.type === "Identifier" ? node.callee.property.name : undefined;
+	return property === method && astNode(node.callee.object) && node.callee.object.type === "Identifier" && node.callee.object.name === "runs";
+}
+
+function nodeLocation(node: AstNode): Pick<WorkflowScriptValidationError, "line" | "column"> {
+	return node.loc ? { line: Math.max(1, node.loc.start.line - 1), column: node.loc.start.column + 1 } : {};
+}
+
+function walkAst(node: unknown, visit: (node: AstNode) => void, includeNestedFunctions = true): void {
+	if (Array.isArray(node)) {
+		for (const item of node) walkAst(item, visit, includeNestedFunctions);
+		return;
+	}
+	if (!astNode(node)) return;
+	visit(node);
+	if (!includeNestedFunctions && (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression")) return;
+	for (const [key, child] of Object.entries(node)) {
+		if (!AST_LOCATION_KEYS.has(key)) walkAst(child, visit, includeNestedFunctions);
+	}
+}
+
+function definitelyNonJson(node: AstNode, normalizeUndefined = false): string | undefined {
+	if (node.type === "Literal") {
+		if (typeof node.bigint === "string") return "BigInt values are not JSON-representable";
+		if (node.regex !== undefined) return "regular expressions are not JSON-representable";
+		return undefined;
+	}
+	if (node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") return "functions are not JSON-representable";
+	if (node.type === "Identifier" && node.name === "undefined") return normalizeUndefined ? undefined : "undefined is not JSON-representable";
+	if (node.type === "UnaryExpression" && node.operator === "void") return normalizeUndefined ? undefined : "undefined is not JSON-representable";
+	if (node.type === "ArrayExpression" && Array.isArray(node.elements)) {
+		if (node.elements.some((entry) => entry === null)) return "sparse arrays are not JSON-representable";
+		for (const entry of node.elements) if (astNode(entry)) {
+			const error = definitelyNonJson(entry, normalizeUndefined);
+			if (error) return error;
+		}
+	}
+	if (node.type === "ObjectExpression" && Array.isArray(node.properties)) {
+		const values = new Map<string, AstNode>();
+		for (const property of node.properties) {
+			if (!astNode(property) || property.type !== "Property" || !astNode(property.value)) return undefined;
+			const key = staticPropertyKey(property);
+			if (key === undefined) return undefined;
+			values.set(key, property.value);
+		}
+		for (const value of values.values()) {
+			const error = definitelyNonJson(value, normalizeUndefined);
+			if (error) return error;
+		}
+	}
+	return undefined;
+}
+
+function staticPropertyKey(property: AstNode): string | undefined {
+	return property.computed === true
+		? literalString(property.key)
+		: literalString(property.key) ?? (astNode(property.key) && property.key.type === "Identifier" ? property.key.name as string : undefined);
+}
+
+function directObjectPropertyValue(node: AstNode, name: string): AstNode | undefined {
+	if (node.type !== "ObjectExpression" || !Array.isArray(node.properties)) return undefined;
+	let value: AstNode | undefined;
+	for (const property of node.properties) {
+		if (!astNode(property) || property.type !== "Property" || !astNode(property.value)) continue;
+		if (staticPropertyKey(property) === name) value = property.value;
+	}
+	return value;
+}
+
+function directRunsAllKeys(call: AstNode): Array<{ key: string; node: AstNode }> {
+	const args = Array.isArray(call.arguments) ? call.arguments : [];
+	const items = astNode(args[0]) && args[0].type === "ArrayExpression" && Array.isArray(args[0].elements) ? args[0].elements : [];
+	return items.flatMap((item) => {
+		if (!astNode(item)) return [];
+		const keyNode = directObjectPropertyValue(item, "key");
+		const key = literalString(keyNode);
+		return keyNode && key !== undefined ? [{ key, node: keyNode }] : [];
+	});
+}
+
+/** Parse a workflowScript and apply only rules that are decidable from its local syntax. */
+export function validateWorkflowScript(script: string): WorkflowScriptValidationResult {
+	const errors: WorkflowScriptValidationError[] = [];
+	if (!script.trim()) return { ok: false, errors: [{ message: "workflowScript must not be empty." }] };
+	let root: AstNode;
+	try {
+		const parser = requireFromPackage(resolveWorkflowParserEntry()) as { parse(source: string, options: Record<string, unknown>): unknown };
+		root = parser.parse(`(async () => {\n${script}\n})()`, { ecmaVersion: "latest", sourceType: "script", locations: true }) as AstNode;
+	} catch (error) {
+		const location = error && typeof error === "object" && "loc" in error && error.loc && typeof error.loc === "object"
+			? error.loc as { line?: unknown; column?: unknown }
+			: undefined;
+		const message = (error instanceof Error ? error.message : String(error)).replace(/\s+\(\d+:\d+\)$/, "");
+		return { ok: false, errors: [{ message, ...(typeof location?.line === "number" ? { line: Math.max(1, location.line - 1) } : {}), ...(typeof location?.column === "number" ? { column: location.column + 1 } : {}) }] };
+	}
+
+	const wrapper = astNode(root.body) ? undefined : Array.isArray(root.body) && astNode(root.body[0]) && astNode(root.body[0].expression) && astNode(root.body[0].expression.callee)
+		? root.body[0].expression.callee
+		: undefined;
+	const workflowBody = wrapper && astNode(wrapper.body) ? wrapper.body : root;
+	walkAst(workflowBody, (node) => {
+		if (node !== wrapper && node.async === true && (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression")) {
+			errors.push({ message: "workflowScript does not support nested async functions. Use top-level await, plain helper functions that return runs.run(...), or explicit Promise chains.", ...nodeLocation(node) });
+		}
+		if (directRunsCall(node, "run")) {
+			const args = Array.isArray(node.arguments) ? node.arguments : [];
+			const keyNode = astNode(args[0]) ? args[0] : undefined;
+			const key = literalString(keyNode);
+			if (keyNode && key !== undefined && !KEY_PATTERN.test(key)) errors.push({ message: "runs.run key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.", ...nodeLocation(keyNode) });
+			if (astNode(args[1])) {
+				const message = definitelyNonJson(args[1]);
+				if (message) errors.push({ message: `runs.run params are invalid: ${message}.`, ...nodeLocation(args[1]) });
+			}
+		}
+		if (directRunsCall(node, "all")) {
+			for (const entry of directRunsAllKeys(node)) if (!KEY_PATTERN.test(entry.key)) errors.push({ message: "runs.all item key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.", ...nodeLocation(entry.node) });
+			const args = Array.isArray(node.arguments) ? node.arguments : [];
+			if (astNode(args[0]) && args[0].type === "ArrayExpression" && Array.isArray(args[0].elements)) {
+				for (const item of args[0].elements) if (astNode(item)) {
+					const message = definitelyNonJson(item);
+					if (message) errors.push({ message: `runs.all item params are invalid: ${message}.`, ...nodeLocation(item) });
+				}
+			}
+		}
+		const boundaryValue = node.type === "CallExpression" && astNode(node.callee) && node.callee.type === "Identifier" && node.callee.name === "emit" && Array.isArray(node.arguments) && astNode(node.arguments[0])
+			? node.arguments[0]
+			: node.type === "CallExpression" && astNode(node.callee) && node.callee.type === "MemberExpression" && astNode(node.callee.object) && node.callee.object.type === "Identifier" && node.callee.object.name === "state" && astNode(node.callee.property) && node.callee.property.type === "Identifier" && node.callee.property.name === "set" && Array.isArray(node.arguments) && astNode(node.arguments[1])
+				? node.arguments[1]
+				: undefined;
+		if (boundaryValue) {
+			const message = definitelyNonJson(boundaryValue);
+			if (message) errors.push({ message: `workflowScript boundary value is invalid: ${message}.`, ...nodeLocation(boundaryValue) });
+		}
+	});
+	walkAst(workflowBody, (node) => {
+		if (node.type !== "ReturnStatement" || !astNode(node.argument)) return;
+		const message = definitelyNonJson(node.argument, true);
+		if (message) errors.push({ message: `workflowScript boundary value is invalid: ${message}.`, ...nodeLocation(node.argument) });
+	}, false);
+
+	if (workflowBody.type === "BlockStatement" && Array.isArray(workflowBody.body)) {
+		for (let statementIndex = 0; statementIndex < workflowBody.body.length; statementIndex++) {
+			const statement = workflowBody.body[statementIndex];
+			if (!astNode(statement) || statement.type !== "VariableDeclaration" || !Array.isArray(statement.declarations)) continue;
+			for (const declaration of statement.declarations) {
+				if (!astNode(declaration) || !astNode(declaration.id) || declaration.id.type !== "Identifier" || !astNode(declaration.init) || declaration.init.type !== "AwaitExpression" || !directRunsCall(declaration.init.argument, "all")) continue;
+				const name = declaration.id.name as string;
+				const keys = new Set(directRunsAllKeys(declaration.init.argument).map((entry) => entry.key));
+				if (keys.size === 0) continue;
+				const args = Array.isArray(declaration.init.argument.arguments) ? declaration.init.argument.arguments : [];
+				const itemCount = astNode(args[0]) && args[0].type === "ArrayExpression" && Array.isArray(args[0].elements) ? args[0].elements.length : 0;
+				const arrayResultShape = Array.from({ length: itemCount });
+				for (const later of workflowBody.body.slice(statementIndex + 1)) walkAst(later, (node) => {
+					if (node.type !== "MemberExpression" || !astNode(node.object) || node.object.type !== "Identifier" || node.object.name !== name) return;
+					const property = node.computed === true ? literalString(node.property) : astNode(node.property) && node.property.type === "Identifier" ? node.property.name as string : undefined;
+					if (property && keys.has(property) && !(property in arrayResultShape)) errors.push({ message: `runs.all returns an ordered array; '${name}.${property}' is keyed access. Use an index, destructuring, or map(...).`, ...nodeLocation(node) });
+				}, false);
+			}
+		}
+	}
+
+	const unique = errors.filter((error, index) => errors.findIndex((candidate) => candidate.message === error.message && candidate.line === error.line && candidate.column === error.column) === index);
+	return { ok: unique.length === 0, errors: unique };
+}
 function workflowStringMetadata(params: Record<string, unknown>): Pick<WorkflowScriptTraceEntry, "phase" | "label" | "agent"> {
 	return {
 		...(typeof params.phase === "string" && params.phase.trim() ? { phase: params.phase.trim() } : {}),
@@ -893,6 +1111,41 @@ function resolveWorkflowParserEntry(): string {
 	}
 }
 
+const AUTO_RESUME_PARAM_KEYS = ["acceptance", "agentContract", "index", "intercomBridge", "label", "maxRuntimeMs", "output", "outputMode", "outputSchema", "phase", "skill", "skills", "task", "timeoutMs", "toolBudget", "turnBudget", "worktree"] as const;
+
+function isZeroUsage(usage: unknown): boolean {
+	if (!isRecord(usage)) return false;
+	const cost = usage.cost;
+	return (usage.input ?? 0) === 0
+		&& (usage.output ?? 0) === 0
+		&& (usage.cacheRead ?? 0) === 0
+		&& (usage.cacheWrite ?? 0) === 0
+		&& (!isRecord(cost) || (cost.total ?? 0) === 0);
+}
+
+function setupAbortResumeParams(params: Record<string, unknown>, result: WorkflowScriptChildResult, signal: AbortSignal): Record<string, unknown> | undefined {
+	if (signal.aborted || result.ok || result.stopped || result.interrupted || !result.runId) return undefined;
+	const childResult = Array.isArray(result.results) && result.results.length === 1 && isRecord(result.results[0]) ? result.results[0] : undefined;
+	const error = typeof childResult?.error === "string" ? childResult.error : result.error;
+	if (error !== "This operation was aborted" || !isZeroUsage(childResult?.usage)) return undefined;
+	const messages = Array.isArray(childResult?.messages) ? childResult.messages : [];
+	const message = messages.findLast((entry) => isRecord(entry) && entry.role === "assistant");
+	if (message !== undefined) {
+		if (!isRecord(message)) return undefined;
+		if (message.stopReason !== "error" || message.errorMessage !== error) return undefined;
+		if (!Array.isArray(message.content) || message.content.length > 0 || !isZeroUsage(message.usage)) return undefined;
+		if (Object.hasOwn(message, "diagnostics") || Object.hasOwn(message, "responseId")) return undefined;
+	}
+	const task = typeof params.task === "string" && params.task.trim() ? params.task.trim() : "Continue after the setup abort.";
+	const resumeParams: Record<string, unknown> = { resume: result.runId, task };
+	for (const key of AUTO_RESUME_PARAM_KEYS) {
+		if (Object.hasOwn(params, key)) resumeParams[key] = params[key];
+	}
+	resumeParams.resume = result.runId;
+	resumeParams.task = task;
+	return resumeParams;
+}
+
 export async function runWorkflowScript(options: RunWorkflowScriptOptions): Promise<WorkflowScriptResult> {
 	if (!options.script.trim()) throw new Error("workflowScript must not be empty.");
 	if (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1)) throw new Error("workflow script timeout must be a positive integer.");
@@ -978,7 +1231,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 							return unobservedSteers.length > 0 ? new Error(`workflowScript completed with unawaited runs.steer call(s): ${unobservedSteers.map((key) => `'${key}'`).join(", ")}. Await or return each call.`) : undefined;
 						})()
 						: undefined;
-				if ("error" in outcome) reject(new WorkflowScriptError(outcome.error.message, partial(), outcome.error.workflowErrorKind === "detached-child" ? "detached-child" : undefined));
+				if ("error" in outcome) reject(new WorkflowScriptError(outcome.error.message, partial(), outcome.error.workflowErrorKind === "detached-child" || outcome.error.workflowErrorKind === "timeout" ? outcome.error.workflowErrorKind : undefined));
 				else if (completionError) reject(new WorkflowScriptError(completionError.message, partial()));
 				else resolve({ value: outcome.value, ...partial() });
 			});
@@ -1009,7 +1262,11 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 		};
 		const timer = options.timeoutMs === undefined
 			? undefined
-			: setTimeout(() => finish({ error: new Error(`Workflow script timed out after ${options.timeoutMs}ms.`) }), options.timeoutMs);
+			: setTimeout(() => {
+				const error = new Error(`Workflow script timed out after ${options.timeoutMs}ms.`) as Error & { workflowErrorKind: "timeout" };
+				error.workflowErrorKind = "timeout";
+				finish({ error });
+			}, options.timeoutMs);
 		options.signal?.addEventListener("abort", onAbort, { once: true });
 		if (options.signal?.aborted) return onAbort();
 
@@ -1049,7 +1306,9 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				return finish({ value: message.value });
 			}
 			if (message.type === "error") {
-				const workflowError = new Error(typeof message.error === "string" ? message.error : "Workflow script failed.") as Error & { workflowErrorKind?: "detached-child" };
+				const rawError = typeof message.error === "string" ? message.error : "Workflow script failed.";
+				const text = message.errorPhase === "return-serialization" ? `${rawError}${workflowReturnRecoveryHint(partial().children)}` : rawError;
+				const workflowError = new Error(text) as Error & { workflowErrorKind?: "detached-child" };
 				if (message.errorKind === "detached-child") workflowError.workflowErrorKind = "detached-child";
 				return finish({ error: workflowError });
 			}
@@ -1165,6 +1424,31 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			}
 			const params = message.args.params;
 			if (!isRecord(params)) return respond(Promise.reject(new Error(`runs.run('${key}', params) requires a params object.`)));
+			const collectFailure = message.args.collectFailure === true;
+			const callObserved = observedRunCalls.delete(message.callId);
+			const deliver = (promise: Promise<WorkflowScriptChildResult>) => collectFailure
+				? promise
+				: promise.then((result) => {
+					if (!result.ok && !result.stopped) {
+						const childError = new Error(result.detached ? `Run '${key}' detached: ${result.error ?? result.output}` : `Run '${key}' failed: ${result.error ?? result.output}`) as Error & { workflowErrorKind?: "detached-child" };
+						if (result.detached) childError.workflowErrorKind = "detached-child";
+						throw childError;
+					}
+					return result;
+				});
+			const fingerprint = stableJson(params);
+			const existing = launches.get(key);
+			if (existing) {
+				if (existing.fingerprint !== fingerprint) return respond(Promise.reject(new Error(`Duplicate workflow key '${key}' used with incompatible launch params.`)));
+				if (callObserved) existing.observed = true;
+				trace.push({ operation: "run", key, state: "reused", ...workflowStringMetadata(params) });
+				traceChanged();
+				return respond(deliver(existing.promise), `runs.run('${key}') result`);
+			}
+			const permitError = options.oneUsePermit?.claim(key);
+			if (permitError) return respond(Promise.reject(new Error(permitError)));
+			if (options.oneUsePermit && message.args.batch !== undefined) return respond(Promise.reject(new Error("Workflow child permit does not support runs.all.")));
+			if (options.oneUsePermit && params.resume !== undefined) return respond(Promise.reject(new Error("Workflow child permit does not support retained resume.")));
 			if (params.action !== undefined) return respond(Promise.reject(new Error(`runs.run('${key}') accepts execution params only; management action is not allowed.`)));
 			if (params.workflowScript !== undefined) return respond(Promise.reject(new Error(`runs.run('${key}') cannot start a nested workflow script.`)));
 			if (params.tasks !== undefined || params.chain !== undefined || params.parallel !== undefined || params.concurrency !== undefined || params.chainDir !== undefined) {
@@ -1195,28 +1479,6 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			if (params.resume !== undefined && (typeof params.task !== "string" || !params.task.trim())) {
 				return respond(Promise.reject(new Error(`runs.run('${key}') resume requires a non-empty task follow-up.`)));
 			}
-			const collectFailure = message.args.collectFailure === true;
-			const callObserved = observedRunCalls.delete(message.callId);
-			const deliver = (promise: Promise<WorkflowScriptChildResult>) => collectFailure
-				? promise
-				: promise.then((result) => {
-					if (!result.ok && !result.stopped) {
-						const childError = new Error(result.detached ? `Run '${key}' detached: ${result.error ?? result.output}` : `Run '${key}' failed: ${result.error ?? result.output}`) as Error & { workflowErrorKind?: "detached-child" };
-						if (result.detached) childError.workflowErrorKind = "detached-child";
-						throw childError;
-					}
-					return result;
-				});
-			const fingerprint = stableJson(params);
-			const existing = launches.get(key);
-			if (existing) {
-				if (existing.fingerprint !== fingerprint) return respond(Promise.reject(new Error(`Duplicate workflow key '${key}' used with incompatible launch params.`)));
-				if (callObserved) existing.observed = true;
-				trace.push({ operation: "run", key, state: "reused", ...workflowStringMetadata(params) });
-				traceChanged();
-				return respond(deliver(existing.promise), `runs.run('${key}') result`);
-			}
-
 			const startedAt = Date.now();
 			const batch = isRecord(message.args.batch) && typeof message.args.batch.id === "string" && Array.isArray(message.args.batch.calls)
 				? { id: message.args.batch.id, calls: message.args.batch.calls.filter((call): call is { key: string; params: Record<string, unknown> } => isRecord(call) && typeof call.key === "string" && isRecord(call.params)) }
@@ -1266,7 +1528,13 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 					if (resolvedResumeLineage.at(-1) !== resolvedResumeId) resolvedResumeLineage.push(resolvedResumeId!);
 				}
 				const launchParams = resolvedResumeId ? { ...params, resume: resolvedResumeId } : params;
-				return options.launch(key, launchParams, childSignal, { admitted: true });
+				const result = await options.launch(key, launchParams, childSignal, { admitted: true, batch: batch !== undefined });
+				const autoResumeParams = setupAbortResumeParams(params, result, childSignal);
+				if (!autoResumeParams) return result;
+				resolvedResumeLineage = [...new Set([...(resolvedResumeLineage ?? []), result.runId!])];
+				trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(autoResumeParams), phase: "auto-resume", runId: result.runId });
+				traceChanged();
+				return options.launch(key, autoResumeParams, childSignal, { admitted: true, batch: batch !== undefined });
 			}).then((result) => {
 				let normalized = !result.ok && !result.error ? { ...result, error: result.output } : result;
 				if (resolvedResumeLineage?.length && normalized.runId) {

package/src/workflows/workflow-child-summary.ts

@@ -0,0 +1,117 @@
+import type { AsyncStatus, WorkflowChildSummaryV1 } from "../shared/types.ts";
+import type { WorkflowScriptChildResult, WorkflowScriptTraceEntry } from "./scripted-workflow.ts";
+
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const TERMINAL_STATES = new Set(["completed", "failed", "paused", "stopped", "rejected", "detached"]);
+
+function bounded(value: unknown, maxBytes: number): string | undefined {
+	if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value, "utf8") > maxBytes) return undefined;
+	return value;
+}
+
+function requiredId(value: string, label: string): string {
+	const id = bounded(value, 256);
+	if (!id) throw new Error(`${label} must be a non-empty identifier of at most 256 UTF-8 bytes.`);
+	return id;
+}
+
+export function workflowChildSummary(input: {
+	parentToolCallId: string;
+	workflowRunId: string;
+	workflowState: WorkflowChildSummaryV1["workflowState"];
+	inventoryComplete: boolean;
+	trace?: WorkflowScriptTraceEntry[];
+	children?: WorkflowScriptChildResult[];
+	steps?: NonNullable<AsyncStatus["steps"]>;
+}): WorkflowChildSummaryV1 {
+	const rows = new Map<string, WorkflowChildSummaryV1["children"][number]>();
+	for (const entry of input.trace ?? []) {
+		if (entry.operation !== "run" || !KEY_PATTERN.test(entry.key)) continue;
+		const previous = rows.get(entry.key);
+		const state = entry.state === "completed" ? "completed"
+			: entry.state === "failed" ? "failed"
+				: entry.state === "stopped" ? "stopped"
+					: entry.state === "detached" ? "detached"
+						: previous?.state ?? "running";
+		rows.set(entry.key, {
+			childId: entry.key,
+			state,
+			...(bounded(entry.runId, 256) ? { runId: bounded(entry.runId, 256) } : {}),
+			...(previous?.agent ? { agent: previous.agent } : {}),
+			...(previous?.model ? { model: previous.model } : {}),
+			...(previous?.thinking ? { thinking: previous.thinking } : {}),
+		});
+	}
+	for (const step of input.steps ?? []) {
+		const key = step.workflowKey;
+		if (!key || !KEY_PATTERN.test(key)) continue;
+		const state = step.status === "complete" || step.status === "completed" ? "completed"
+			: step.status === "failed" ? "failed"
+				: step.status === "paused" ? "paused"
+					: step.status === "stopped" ? "stopped"
+						: step.status === "rejected" ? "rejected"
+							: step.status === "pending" ? "pending" : "running";
+		const launchResolved = step.async !== undefined || step.sessionFile !== undefined || step.runId !== undefined || step.model !== undefined;
+		rows.set(key, {
+			childId: key,
+			state,
+			...(bounded(step.runId, 256) ? { runId: bounded(step.runId, 256) } : {}),
+			...(launchResolved && bounded(step.agent, 256) ? { agent: bounded(step.agent, 256) } : {}),
+			...(bounded(step.model, 256) ? { model: bounded(step.model, 256) } : {}),
+			...(bounded(step.thinking, 32) ? { thinking: bounded(step.thinking, 32) } : {}),
+		});
+	}
+	for (const child of input.children ?? []) {
+		if (!KEY_PATTERN.test(child.key)) continue;
+		const result = Array.isArray(child.results) ? child.results.find((value) => value && typeof value === "object") as Record<string, unknown> | undefined : undefined;
+		const state = child.detached ? "detached" : child.stopped ? "stopped" : child.interrupted ? "paused" : child.ok ? "completed" : result?.acceptance && typeof result.acceptance === "object" && (result.acceptance as { status?: unknown }).status === "rejected" ? "rejected" : "failed";
+		rows.set(child.key, {
+			childId: child.key,
+			state,
+			...(bounded(child.runId, 256) ? { runId: bounded(child.runId, 256) } : {}),
+			...(bounded(child.agent, 256) ? { agent: bounded(child.agent, 256) } : {}),
+			...(bounded(result?.model, 256) ? { model: bounded(result?.model, 256) } : {}),
+			...(bounded(result?.thinking, 32) ? { thinking: bounded(result?.thinking, 32) } : {}),
+		});
+	}
+	if (input.inventoryComplete) {
+		for (const [key, row] of rows) {
+			if (!TERMINAL_STATES.has(row.state)) rows.set(key, { ...row, state: input.workflowState === "stopped" ? "stopped" : "failed" });
+		}
+	}
+	return {
+		version: 1,
+		parentToolCallId: requiredId(input.parentToolCallId, "parentToolCallId"),
+		workflowRunId: requiredId(input.workflowRunId, "workflowRunId"),
+		inventoryComplete: input.inventoryComplete,
+		workflowState: input.workflowState,
+		children: [...rows.values()],
+	};
+}
+
+export function parseWorkflowChildSummary(value: unknown): WorkflowChildSummaryV1 | undefined {
+	if (value === undefined) return undefined;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("workflowChildren must be an object.");
+	const input = value as Record<string, unknown>;
+	const allowed = new Set(["version", "parentToolCallId", "workflowRunId", "inventoryComplete", "workflowState", "children"]);
+	if (Object.keys(input).some((key) => !allowed.has(key))) throw new Error("workflowChildren has unsupported fields.");
+	if (input.version !== 1 || typeof input.inventoryComplete !== "boolean" || !Array.isArray(input.children)) throw new Error("workflowChildren is invalid.");
+	const workflowState = input.workflowState;
+	if (workflowState !== "queued" && workflowState !== "running" && workflowState !== "completed" && workflowState !== "failed" && workflowState !== "paused" && workflowState !== "stopped") throw new Error("workflowChildren.workflowState is invalid.");
+	const children = input.children.map((row): WorkflowChildSummaryV1["children"][number] => {
+		if (!row || typeof row !== "object" || Array.isArray(row)) throw new Error("workflowChildren child row is invalid.");
+		const child = row as Record<string, unknown>;
+		if (Object.keys(child).some((key) => !["childId", "runId", "agent", "model", "thinking", "state"].includes(key))) throw new Error("workflowChildren child row has unsupported fields.");
+		if (typeof child.childId !== "string" || !KEY_PATTERN.test(child.childId)) throw new Error("workflowChildren childId is invalid.");
+		const state = child.state;
+		if (state !== "pending" && state !== "running" && state !== "completed" && state !== "failed" && state !== "paused" && state !== "stopped" && state !== "rejected" && state !== "detached") throw new Error("workflowChildren child state is invalid.");
+		for (const [field, maxBytes] of [["runId", 256], ["agent", 256], ["model", 256], ["thinking", 32]] as const) {
+			if (child[field] !== undefined && bounded(child[field], maxBytes) === undefined) throw new Error(`workflowChildren child ${field} is invalid.`);
+		}
+		return { childId: child.childId, state, ...(child.runId ? { runId: child.runId as string } : {}), ...(child.agent ? { agent: child.agent as string } : {}), ...(child.model ? { model: child.model as string } : {}), ...(child.thinking ? { thinking: child.thinking as string } : {}) };
+	});
+	if (new Set(children.map((child) => child.childId)).size !== children.length) throw new Error("workflowChildren has duplicate childId values.");
+	if (typeof input.parentToolCallId !== "string") throw new Error("workflowChildren.parentToolCallId is invalid.");
+	if (typeof input.workflowRunId !== "string") throw new Error("workflowChildren.workflowRunId is invalid.");
+	return { version: 1, parentToolCallId: requiredId(input.parentToolCallId, "parentToolCallId"), workflowRunId: requiredId(input.workflowRunId, "workflowRunId"), inventoryComplete: input.inventoryComplete, workflowState, children };
+}