pi-subagents 0.55.0 → 0.57.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");
@@ -150,7 +161,15 @@ function trackObservationTracker(tracker, promise, allowFutureObservations = fal
     get(promiseTarget, prop) {
       if (prop === "then") return function promiseThen(onFulfilled, onRejected) {
         consumeTrackedObservations(tracker);
-        return trackObservationTracker({ observations: tracker.observations, consumed: false, dependencies: [tracker] }, promiseTarget.then(onFulfilled, onRejected), true);
+        const chainTracker = { observations: tracker.observations, consumed: false, dependencies: [tracker] };
+        const wrapHandler = (handler) => typeof handler === "function"
+          ? function trackedThenHandler(...args) {
+            const value = handler.apply(this, args);
+            addTrackerDependency(chainTracker, promiseObservationTracker(value));
+            return trackedPromiseTarget(value);
+          }
+          : handler;
+        return trackObservationTracker(chainTracker, promiseTarget.then(wrapHandler(onFulfilled), wrapHandler(onRejected)), true);
       };
       if (prop === "catch") return function promiseCatch(onRejected) {
         consumeTrackedObservations(tracker);
@@ -276,8 +295,43 @@ function formatRef(result) {
   return "[" + parts.join("; ") + "]";
 }
 
+function formatChildResultString(result) {
+  const output = typeof result?.output === "string" ? result.output.trim() : "";
+  return output || formatRef(result);
+}
+
+function decorateWorkflowChildResult(result) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) return result;
+  Object.defineProperties(result, {
+    toString: { value() { return formatChildResultString(this); }, enumerable: false, configurable: true },
+  });
+  return result;
+}
+
 let runFingerprints = new Map();
 
+function validateExtensionBindings(value, label) {
+  if (value === undefined) return;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(label + " extensionBindings must be a plain JSON object.");
+  const keys = Object.keys(value);
+  if (keys.length > 16) throw new Error(label + " extensionBindings supports at most 16 namespaces.");
+  for (const key of keys) if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62})\/[1-9][0-9]{0,8}$/.test(key)) throw new Error(label + " extensionBindings namespace '" + key + "' must use a package-like name followed by '/<positive-version>'.");
+  assertJsonValue(value, label + " extensionBindings");
+  let propertyCount = 0;
+  function visit(entry, depth) {
+    if (!entry || typeof entry !== "object") return;
+    if (depth > 16) throw new Error(label + " extensionBindings exceeds the maximum nesting depth of 16.");
+    if (Array.isArray(entry)) { for (const item of entry) visit(item, depth + 1); return; }
+    for (const child of Object.values(entry)) {
+      propertyCount++;
+      if (propertyCount > 256) throw new Error(label + " extensionBindings exceeds 256 total properties.");
+      visit(child, depth + 1);
+    }
+  }
+  visit(value, 0);
+  if (new TextEncoder().encode(stableRunJson(value)).byteLength > 16384) throw new Error(label + " extensionBindings canonical JSON exceeds 16384 bytes.");
+}
+
 function validateRunCall(key, params, label, fingerprints) {
   if (typeof key !== "string" || !runKeyPattern.test(key)) throw new Error(label + " has an invalid key.");
   if (!params || typeof params !== "object" || Array.isArray(params)) throw new Error(label + " requires a params object.");
@@ -290,6 +344,7 @@ function validateRunCall(key, params, label, fingerprints) {
   if (params.gate !== undefined && (typeof params.gate !== "string" || !params.gate.trim())) throw new Error(label + " gate must be a non-empty command string.");
   if (params.gate !== undefined && params.acceptance !== undefined) throw new Error(label + " gate cannot be combined with acceptance; use one gate command or acceptance.verify.");
   if (params.gate !== undefined && params.resume !== undefined) throw new Error(label + " gate is not supported with retained resume.");
+  if (params.extensionBindings !== undefined && params.resume !== undefined) throw new Error(label + " extensionBindings is not supported with retained resume; resume uses the original retained child binding.");
   if (params.resume !== undefined && typeof params.resume !== "string") {
     const reference = params.resume;
     if (!reference || typeof reference !== "object" || Array.isArray(reference)) throw new Error(label + " resume must be a retained run id or keyed workflow receipt reference.");
@@ -302,6 +357,7 @@ function validateRunCall(key, params, label, fingerprints) {
   if (typeof params.resume === "string" && !params.resume.trim()) throw new Error(label + " resume must be a non-empty retained run id.");
   if (params.resume !== undefined && params.agent !== undefined) throw new Error(label + " resume and agent are mutually exclusive.");
   if (params.resume !== undefined && (typeof params.task !== "string" || !params.task.trim())) throw new Error(label + " resume requires a non-empty task follow-up.");
+  validateExtensionBindings(params.extensionBindings, label);
   assertJsonValue(params, label + " params");
   const fingerprint = stableRunJson(params);
   const existing = fingerprints.get(key);
@@ -312,7 +368,8 @@ function validateRunCall(key, params, label, fingerprints) {
 const runs = Object.freeze({
   run(key, params) {
     validateRunCall(key, params, "runs.run", runFingerprints);
-    return hostCall("run", { key, params }, { key, operation: "run" });
+    const launched = runHostCall(key, params, false);
+    return trackRunObservation([{ key, operation: "run", callId: launched.callId }], launched.promise.then(decorateWorkflowChildResult));
   },
   all(items) {
     if (!Array.isArray(items)) throw new Error("runs.all(items) requires an array.");
@@ -329,7 +386,7 @@ const runs = Object.freeze({
     runFingerprints = fingerprints;
     const batch = { id: "batch-" + (++nextCallId), calls };
     const launched = calls.map(({ key, params }) => runHostCall(key, params, true, batch));
-    return trackRunObservation(launched.map(({ key, callId }) => ({ key, operation: "run", callId })), Promise.all(launched.map(({ promise }) => promise)).then((results) => wrapRunsAllResults(results, calls.map(({ key }) => key))));
+    return trackRunObservation(launched.map(({ key, callId }) => ({ key, operation: "run", callId })), Promise.all(launched.map(({ promise }) => promise)).then((results) => wrapRunsAllResults(results.map(decorateWorkflowChildResult), calls.map(({ key }) => key))));
   },
   steer(key, message, options = {}) {
     if (typeof key !== "string" || !runKeyPattern.test(key)) throw new Error("runs.steer has an invalid key.");
@@ -394,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) {
@@ -581,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" } : {}) });
@@ -599,10 +661,12 @@ export interface WorkflowScriptChildResult {
 	output: string;
 	error?: string;
 	detached?: boolean;
+	interrupted?: boolean;
 	structuredOutput?: unknown;
 	requestedContext?: "fresh" | "fork";
 	resolvedContext?: "fresh" | "fork" | "mixed";
 	outputReference?: string;
+	externalAdapter?: import("../shared/types.ts").ExternalCliReceiptMetadata;
 	resumability?: { state: "resumable" } | { state: "not-resumable"; reason: string };
 	continuation?: { runIds: string[] };
 	artifactPaths: string[];
@@ -670,10 +734,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>;
@@ -780,6 +846,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;
@@ -817,6 +892,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() } : {}),
@@ -1002,7 +1265,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 });
 			}
@@ -1118,6 +1383,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) {
@@ -1148,28 +1438,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)) }
@@ -1219,7 +1487,7 @@ 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 });
+				return options.launch(key, launchParams, 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 };
+}