fix: normalize workflow child return metadata (#1314)

Author: nicobailon

CHANGELOG.md

@@ -14,6 +14,7 @@
 
 ### Fixed
 - Add a separate classifier for model context-overflow errors. Thanks to [@srcKod](https://github.com/srcKod) for #1312.
+- Normalize child result metadata before workflow return persistence (#1307).
 - Quote only confidently identified leading Windows executable paths in acceptance verification commands. Thanks to [@srcKod](https://github.com/srcKod) for #1294.
 
 ### Changed

docs/workflows.md

@@ -37,6 +37,8 @@ Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the syn
 
 All model-facing subagent execution is expressed through `workflowScript` in the `subagent` tool. Use stable keys and ordinary JavaScript for one child, sequence, and parallelism. For ordinary parallel fanout, use `await runs.all([{ key, agent, task }, ...])`; do not read `.output` from unawaited `runs.run` launches. Store a `runs.run` promise only when the script later observes it with `await`, `Promise.race`, or `Promise.all`, such as steering a live child before awaiting its result. Scripts are ordinary JavaScript statement bodies. Use an explicit `return` for a useful result:
 
+Child results cross into the script as plain JSON data. Non-JSON host metadata is omitted, so use returned fields such as `runId`, `ok`, `output`, and `structuredOutput` for workflow control.
+
 ```js
 subagent({ workflowScript: `
   const scan = await runs.run("scan", { agent: "scout", task: "Scan the codebase" });

src/workflows/scripted-workflow.ts

@@ -665,6 +665,18 @@ function omitUndefinedWorkflowValues(value: unknown, seen = new Set<object>()):
 	return normalized;
 }
 
+function omitNonJsonWorkflowResultMetadata(value: unknown): unknown {
+	const normalized = omitUndefinedWorkflowValues(value);
+	if (!isPlainJsonObject(normalized) || !Object.hasOwn(normalized, "results")) return normalized;
+	try {
+		assertWorkflowJsonValue(normalized.results, "runs.run result.results");
+		return normalized;
+	} catch {
+		const { results: _results, ...safeResult } = normalized;
+		return safeResult;
+	}
+}
+
 export function assertWorkflowJsonValue(value: unknown, path = "value", seen = new Set<object>()): void {
 	if (value === null || typeof value === "string" || typeof value === "boolean") return;
 	if (typeof value === "number") {
@@ -917,10 +929,21 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			}
 			if (message.type !== "call" || typeof message.callId !== "number" || typeof message.method !== "string" || !isRecord(message.args)) return;
 
-			const respond = (promise: Promise<unknown>) => {
+			const respond = (promise: Promise<unknown>, responsePath?: string) => {
 				void promise.then(
 					(value) => {
-						if (!settled) worker.postMessage({ type: "response", callId: message.callId, ok: true, value: omitUndefinedWorkflowValues(value) });
+						if (settled) return;
+						const normalized = responsePath ? omitNonJsonWorkflowResultMetadata(value) : omitUndefinedWorkflowValues(value);
+						if (!responsePath) {
+							worker.postMessage({ type: "response", callId: message.callId, ok: true, value: normalized });
+							return;
+						}
+						try {
+							assertWorkflowJsonValue(normalized, responsePath);
+							worker.postMessage({ type: "response", callId: message.callId, ok: true, value: normalized });
+						} catch (error) {
+							worker.postMessage({ type: "response", callId: message.callId, ok: false, error: `${responsePath} must contain only JSON data before it can be returned from workflowScript. Return a plain projection such as { runId, ok, output }. ${error instanceof Error ? error.message : String(error)}` });
+						}
 					},
 					(error: unknown) => {
 						if (!settled) worker.postMessage({ type: "response", callId: message.callId, ok: false, error: error instanceof Error ? error.message : String(error), ...(error instanceof Error && (error as { workflowErrorKind?: unknown }).workflowErrorKind === "detached-child" ? { errorKind: "detached-child" } : {}) });
@@ -1052,7 +1075,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				if (callObserved) existing.observed = true;
 				trace.push({ operation: "run", key, state: "reused", ...workflowStringMetadata(params) });
 				traceChanged();
-				return respond(deliver(existing.promise));
+				return respond(deliver(existing.promise), `runs.run('${key}') result`);
 			}
 
 			const startedAt = Date.now();
@@ -1126,7 +1149,7 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			childOrder.push(key);
 			trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(params) });
 			traceChanged();
-			respond(deliver(promise));
+			respond(deliver(promise), `runs.run('${key}') result`);
 		});
 
 		worker.postMessage({ type: "start", script: options.script, stateEnabled: options.state !== undefined });

test/unit/scripted-workflow.test.ts

@@ -468,18 +468,30 @@ describe("scripted workflow runtime", () => {
 		assert.deepEqual(result.value, [{ key: "review", output: "completed", values: [null] }]);
 	});
 
-	it("rejects non-plain child result values", async () => {
-		await assert.rejects(
-			runWorkflowScript({
-				script: `return await runs.run("non-plain", { agent: "worker", task: "write output" });`,
-				timeoutMs: 2_000,
-				async launch(key) {
-					return { key, ok: true, output: "Saved output.", artifactPaths: [], results: [{ metadata: new Map([["source", "worker"]]) }] };
-				},
-				async status(key) { return { key, ok: true, output: "ok", artifactPaths: [] }; },
-			}),
-			(error: unknown) => error instanceof WorkflowScriptError && /return.*plain JSON objects/i.test(error.message),
-		);
+	it("omits non-JSON child result metadata before returning reused runs.run results", async () => {
+		let launches = 0;
+		const result = await runWorkflowScript({
+			script: `
+				const first = await runs.run("non-plain", { agent: "worker", task: "write output" });
+				const reused = await runs.run("non-plain", { agent: "worker", task: "write output" });
+				return [first, reused];
+			`,
+			timeoutMs: 2_000,
+			async launch(key) {
+				launches++;
+				return { key, ok: true, output: "Saved output.", artifactPaths: [], results: [{ metadata: new Map([["source", "worker"]]) }] };
+			},
+			async status(key) { return { key, ok: true, output: "ok", artifactPaths: [] }; },
+		});
+
+		assert.equal(launches, 1);
+		assert.deepEqual(result.value, [
+			{ key: "non-plain", ok: true, output: "Saved output.", artifactPaths: [] },
+			{ key: "non-plain", ok: true, output: "Saved output.", artifactPaths: [] },
+		]);
+		assert.equal((result.value as Array<{ results?: unknown }>)[0]?.results, undefined);
+		assert.equal((result.value as Array<{ results?: unknown }>)[1]?.results, undefined);
+		assert.ok(result.children[0]?.results?.[0] && (result.children[0].results[0] as { metadata?: unknown }).metadata instanceof Map);
 	});
 
 	it("passes retained resume items and rejects agent overrides", async () => {