pi-subagents 0.52.0 → 0.53.0

package/src/workflows/scripted-workflow.ts

@@ -249,7 +249,7 @@ function formatRef(result) {
   return "[" + parts.join("; ") + "]";
 }
 
-const runFingerprints = new Map();
+let runFingerprints = new Map();
 
 function validateRunCall(key, params, label, fingerprints) {
   if (typeof key !== "string" || !runKeyPattern.test(key)) throw new Error(label + " has an invalid key.");
@@ -263,7 +263,16 @@ 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.resume !== undefined && (typeof params.resume !== "string" || !params.resume.trim())) throw new Error(label + " resume must be a non-empty retained run id.");
+  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.");
+    const fields = Object.keys(reference);
+    if (fields.some((field) => field !== "workflowRunId" && field !== "key" && field !== "latest")) throw new Error(label + " keyed resume contains unsupported fields.");
+    if (typeof reference.workflowRunId !== "string" || !reference.workflowRunId.trim()) throw new Error(label + " keyed resume workflowRunId must be non-empty.");
+    if (typeof reference.key !== "string" || !runKeyPattern.test(reference.key)) throw new Error(label + " keyed resume key is invalid.");
+    if (reference.latest !== true) throw new Error(label + " keyed resume requires latest: true.");
+  }
+  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.");
   assertJsonValue(params, label + " params");
@@ -290,7 +299,7 @@ const runs = Object.freeze({
       validateRunCall(key, params, "runs.all item " + index, fingerprints);
       calls.push({ key, params });
     }
-    for (const { key, params } of calls) runFingerprints.set(key, stableRunJson(params));
+    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)));
@@ -538,6 +547,11 @@ export interface WorkflowScriptChildResult {
 	error?: string;
 	detached?: boolean;
 	structuredOutput?: unknown;
+	requestedContext?: "fresh" | "fork";
+	resolvedContext?: "fresh" | "fork" | "mixed";
+	outputReference?: string;
+	resumability?: { state: "resumable" } | { state: "not-resumable"; reason: string };
+	continuation?: { runIds: string[] };
 	artifactPaths: string[];
 	results?: unknown[];
 }
@@ -570,6 +584,17 @@ export interface WorkflowSteerResult {
 	error?: string;
 }
 
+export interface WorkflowReceiptResumeReference {
+	workflowRunId: string;
+	key: string;
+	latest: true;
+}
+
+export interface WorkflowResolvedResumeReference {
+	runId: string;
+	runIds?: string[];
+}
+
 export interface WorkflowScriptResult {
 	value: unknown;
 	emits: unknown[];
@@ -596,6 +621,7 @@ export interface RunWorkflowScriptOptions {
 	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>;
+	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>;
 	state?: {
@@ -616,6 +642,16 @@ function isPlainJsonObject(value: unknown): value is Record<string, unknown> {
 	return prototype === null || prototype === Object.prototype;
 }
 
+function parseWorkflowResumeReference(value: unknown): WorkflowReceiptResumeReference | undefined {
+	if (!isRecord(value)) return undefined;
+	const fields = Object.keys(value);
+	if (fields.some((field) => field !== "workflowRunId" && field !== "key" && field !== "latest")) throw new Error("keyed resume contains unsupported fields.");
+	if (typeof value.workflowRunId !== "string" || !value.workflowRunId.trim()) throw new Error("keyed resume workflowRunId must be non-empty.");
+	const key = validateKey(value.key, "keyed resume");
+	if (value.latest !== true) throw new Error("keyed resume requires latest: true.");
+	return { workflowRunId: value.workflowRunId.trim(), key, latest: true };
+}
+
 function omitUndefinedWorkflowValues(value: unknown, seen = new Set<object>()): unknown {
 	if (value === null || typeof value !== "object") return value;
 	if (seen.has(value)) return value;
@@ -629,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") {
@@ -881,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" } : {}) });
@@ -984,9 +1043,13 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 			if (params.gate !== undefined && params.resume !== undefined) {
 				return respond(Promise.reject(new Error(`runs.run('${key}') gate is not supported with retained resume.`)));
 			}
-			if (params.resume !== undefined && (typeof params.resume !== "string" || !params.resume.trim())) {
-				return respond(Promise.reject(new Error(`runs.run('${key}') resume must be a non-empty retained run id.`)));
+			let resumeReference: WorkflowReceiptResumeReference | undefined;
+			try {
+				if (params.resume !== undefined && typeof params.resume !== "string") resumeReference = parseWorkflowResumeReference(params.resume);
+			} catch (error) {
+				return respond(Promise.reject(new Error(`runs.run('${key}') ${error instanceof Error ? error.message : String(error)}`)));
 			}
+			if (typeof params.resume === "string" && !params.resume.trim()) return respond(Promise.reject(new Error(`runs.run('${key}') resume must be a non-empty retained run id.`)));
 			if (params.resume !== undefined && params.agent !== undefined) {
 				return respond(Promise.reject(new Error(`runs.run('${key}') resume and agent are mutually exclusive.`)));
 			}
@@ -1012,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();
@@ -1033,15 +1096,40 @@ export async function runWorkflowScript(options: RunWorkflowScriptOptions): Prom
 				});
 				if (batch) batchAdmissions.set(batch.id, admission);
 			}
-			const promise = admission.then(() => {
+			let resolvedResumeLineage: string[] | undefined;
+			const promise = admission.then(async () => {
 				if (settled || finishing || stoppedLaunches.has(key)) {
 					const reason = childController.signal.reason;
 					const text = reason instanceof Error ? reason.message : typeof reason === "string" ? reason : "Workflow script aborted.";
 					return { key, ok: false, output: text, error: text, artifactPaths: [] };
 				}
-				return options.launch(key, { ...params, async: params.async ?? false }, childController.signal, { admitted: true });
+				const resolvedResumeValue = resumeReference
+					? await Promise.resolve().then(() => {
+						if (!options.resolveResume) throw new Error("Keyed workflow receipt resume is unavailable in this host.");
+						return options.resolveResume(resumeReference, childController.signal);
+					})
+					: undefined;
+				const resolvedResume = typeof resolvedResumeValue === "string"
+					? resolvedResumeValue
+					: isRecord(resolvedResumeValue) && typeof resolvedResumeValue.runId === "string"
+						? resolvedResumeValue.runId
+						: undefined;
+				if (resumeReference && (typeof resolvedResume !== "string" || !resolvedResume.trim())) throw new Error("Keyed workflow receipt resume resolved without a retained run id.");
+				const resolvedResumeId = resolvedResume?.trim();
+				if (isRecord(resolvedResumeValue)) {
+					const lineage = Array.isArray(resolvedResumeValue.runIds)
+						? resolvedResumeValue.runIds.filter((runId): runId is string => typeof runId === "string" && Boolean(runId.trim())).map((runId) => runId.trim())
+						: [];
+					resolvedResumeLineage = [...new Set(lineage.length ? lineage : [resolvedResumeId!])];
+					if (resolvedResumeLineage.at(-1) !== resolvedResumeId) resolvedResumeLineage.push(resolvedResumeId!);
+				}
+				const launchParams = resolvedResumeId ? { ...params, resume: resolvedResumeId } : params;
+				return options.launch(key, { ...launchParams, async: launchParams.async ?? false }, childController.signal, { admitted: true });
 			}).then((result) => {
-				const normalized = !result.ok && !result.error ? { ...result, error: result.output } : result;
+				let normalized = !result.ok && !result.error ? { ...result, error: result.output } : result;
+				if (resolvedResumeLineage?.length && normalized.runId) {
+					normalized = { ...normalized, continuation: { runIds: [...new Set([...resolvedResumeLineage, normalized.runId])] } };
+				}
 				if (stoppedLaunches.has(key)) return normalized;
 				children.set(key, normalized);
 				const state = normalized.ok ? "completed" : normalized.detached ? "detached" : "failed";
@@ -1061,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 });

package/src/workflows/workflow-receipt.ts

@@ -0,0 +1,140 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
+import type { WorkflowReceipt, WorkflowReceiptEntry, WorkflowReceiptState } from "../shared/types.ts";
+import type { WorkflowReceiptResumeReference, WorkflowScriptChildResult } from "./scripted-workflow.ts";
+
+export type { WorkflowReceipt, WorkflowReceiptEntry, WorkflowReceiptState } from "../shared/types.ts";
+
+export const WORKFLOW_RECEIPT_VERSION = 1;
+export const WORKFLOW_RECEIPT_FILE = "workflow-receipt.json";
+
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function assertSafeRunId(value: string, label: string): string {
+	const normalized = value.trim();
+	if (!normalized || path.basename(normalized) !== normalized || normalized === "." || normalized === "..") {
+		throw new Error(`${label} must be an exact workflow run id, not a path or prefix.`);
+	}
+	return normalized;
+}
+
+function assertKey(value: string, label: string): string {
+	if (!KEY_PATTERN.test(value)) throw new Error(`${label} is invalid.`);
+	return value;
+}
+
+export function workflowReceiptPath(asyncDirRoot: string, workflowRunId: string): string {
+	return path.join(asyncDirRoot, assertSafeRunId(workflowRunId, "workflowRunId"), WORKFLOW_RECEIPT_FILE);
+}
+
+export function buildWorkflowReceipt(input: {
+	workflowRunId: string;
+	state: WorkflowReceiptState;
+	children: WorkflowScriptChildResult[];
+	createdAt?: number;
+}): WorkflowReceipt {
+	const workflowRunId = assertSafeRunId(input.workflowRunId, "workflowRunId");
+	const entries: Record<string, WorkflowReceiptEntry> = Object.create(null) as Record<string, WorkflowReceiptEntry>;
+	for (const child of input.children) {
+		const key = assertKey(child.key, "workflow receipt child key");
+		if (entries[key]) throw new Error(`Workflow receipt has duplicate child key '${key}'.`);
+		const runIds = [...new Set((child.continuation?.runIds ?? (child.runId ? [child.runId] : [])).filter((runId) => typeof runId === "string" && runId.trim()).map((runId) => runId.trim()))];
+		const latestRunId = runIds.at(-1);
+		const resumability = child.resumability ?? { state: "not-resumable", reason: child.runId ? "resumability was not recorded" : "child produced no run id" };
+		if (resumability.state === "resumable" && !latestRunId) throw new Error(`Workflow receipt child '${key}' is resumable but has no retained run id.`);
+		const base = {
+			key,
+			...(child.agent ? { agent: child.agent } : {}),
+			...(child.requestedContext ? { requestedContext: child.requestedContext } : {}),
+			...(child.resolvedContext ? { resolvedContext: child.resolvedContext } : {}),
+			...(child.outputReference ? { outputReference: child.outputReference } : {}),
+			continuation: { runIds },
+		};
+		entries[key] = resumability.state === "resumable"
+			? { ...base, latestRunId: latestRunId!, resumability }
+			: { ...base, ...(latestRunId ? { latestRunId } : {}), resumability };
+	}
+	return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries };
+}
+
+export function writeWorkflowReceipt(asyncDir: string, receipt: WorkflowReceipt): string {
+	const receiptPath = path.join(asyncDir, WORKFLOW_RECEIPT_FILE);
+	writePrivateAtomicJson(receiptPath, receipt);
+	return receiptPath;
+}
+
+function parseEntry(value: unknown, key: string, source: string): WorkflowReceiptEntry {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid workflow receipt '${source}': entry '${key}' must be an object.`);
+	const entry = value as Record<string, unknown>;
+	if (entry.key !== key) throw new Error(`Invalid workflow receipt '${source}': entry '${key}' has a mismatched key.`);
+	const latestRunId = entry.latestRunId;
+	if (latestRunId !== undefined && (typeof latestRunId !== "string" || !latestRunId.trim())) throw new Error(`Invalid workflow receipt '${source}': entry '${key}' latestRunId must be non-empty.`);
+	const continuation = entry.continuation;
+	if (!continuation || typeof continuation !== "object" || Array.isArray(continuation) || !Array.isArray((continuation as Record<string, unknown>).runIds)) {
+		throw new Error(`Invalid workflow receipt '${source}': entry '${key}' continuation is missing.`);
+	}
+	const runIds = (continuation as { runIds: unknown[] }).runIds;
+	if (runIds.some((runId) => typeof runId !== "string" || !runId.trim())) throw new Error(`Invalid workflow receipt '${source}': entry '${key}' continuation contains an invalid run id.`);
+	if (latestRunId !== undefined && runIds.at(-1) !== latestRunId) throw new Error(`Workflow receipt '${source}' entry '${key}' is stale: latestRunId does not match its continuation lineage.`);
+	const resumability = entry.resumability;
+	if (!resumability || typeof resumability !== "object" || Array.isArray(resumability)) throw new Error(`Invalid workflow receipt '${source}': entry '${key}' resumability is missing.`);
+	const state = (resumability as Record<string, unknown>).state;
+	if (state !== "resumable" && state !== "not-resumable") throw new Error(`Invalid workflow receipt '${source}': entry '${key}' resumability state is invalid.`);
+	const reason = (resumability as Record<string, unknown>).reason;
+	if (state === "resumable" && latestRunId === undefined) throw new Error(`Invalid workflow receipt '${source}': entry '${key}' resumable entry has no retained run id.`);
+	if (state === "not-resumable" && (typeof reason !== "string" || !reason.trim())) throw new Error(`Invalid workflow receipt '${source}': entry '${key}' non-resumable reason is missing.`);
+	return value as WorkflowReceiptEntry;
+}
+
+export function readWorkflowReceipt(asyncDirRoot: string, workflowRunId: string): WorkflowReceipt {
+	const receiptPath = workflowReceiptPath(asyncDirRoot, workflowRunId);
+	let value: unknown;
+	try {
+		value = JSON.parse(fs.readFileSync(receiptPath, "utf-8")) as unknown;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new Error(`Workflow receipt '${workflowRunId}' was not found.`);
+		throw new Error(`Workflow receipt '${workflowRunId}' could not be read: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid workflow receipt '${receiptPath}': expected an object.`);
+	const receipt = value as Record<string, unknown>;
+	if (receipt.version !== WORKFLOW_RECEIPT_VERSION) throw new Error(`Invalid workflow receipt '${receiptPath}': unsupported version.`);
+	if (receipt.workflowRunId !== workflowRunId) throw new Error(`Workflow receipt '${receiptPath}' is stale: workflowRunId does not match.`);
+	if (receipt.state !== "complete" && receipt.state !== "failed" && receipt.state !== "paused" && receipt.state !== "stopped") {
+		throw new Error(`Workflow receipt '${receiptPath}' is stale: workflow is not terminal.`);
+	}
+	if (typeof receipt.createdAt !== "number" || !Number.isFinite(receipt.createdAt)) throw new Error(`Invalid workflow receipt '${receiptPath}': createdAt is invalid.`);
+	if (!receipt.entries || typeof receipt.entries !== "object" || Array.isArray(receipt.entries)) throw new Error(`Invalid workflow receipt '${receiptPath}': entries must be an object.`);
+	const entries: Record<string, WorkflowReceiptEntry> = Object.create(null) as Record<string, WorkflowReceiptEntry>;
+	for (const [key, entry] of Object.entries(receipt.entries as Record<string, unknown>)) entries[assertKey(key, "workflow receipt key")] = parseEntry(entry, key, receiptPath);
+	return { version: 1, workflowRunId, state: receipt.state, createdAt: receipt.createdAt, entries };
+}
+
+export function resolveWorkflowReceiptResumeEntry(input: {
+	reference: WorkflowReceiptResumeReference;
+	asyncDirRoot: string;
+	assertResumable?: (runId: string) => void;
+}): WorkflowReceiptEntry & { latestRunId: string; resumability: { state: "resumable" } } {
+	if (input.reference.latest !== true) throw new Error("Keyed workflow receipt resume requires latest: true.");
+	const key = assertKey(input.reference.key, "keyed resume key");
+	const receipt = readWorkflowReceipt(input.asyncDirRoot, input.reference.workflowRunId.trim());
+	const entry = receipt.entries[key];
+	if (!entry) throw new Error(`Workflow receipt '${receipt.workflowRunId}' has no child key '${key}'.`);
+	assertResumableEntry(entry, receipt.workflowRunId, key);
+	input.assertResumable?.(entry.latestRunId);
+	return entry;
+}
+
+function assertResumableEntry(entry: WorkflowReceiptEntry, workflowRunId: string, key: string): asserts entry is WorkflowReceiptEntry & { latestRunId: string; resumability: { state: "resumable" } } {
+	if (entry.resumability.state !== "resumable") throw new Error(`Workflow receipt '${workflowRunId}' child '${key}' is not resumable: ${entry.resumability.reason}.`);
+	if (!entry.latestRunId) throw new Error(`Workflow receipt '${workflowRunId}' child '${key}' has no retained run id.`);
+}
+
+export function resolveWorkflowReceiptResume(input: {
+	reference: WorkflowReceiptResumeReference;
+	asyncDirRoot: string;
+	assertResumable?: (runId: string) => void;
+}): string {
+	const entry = resolveWorkflowReceiptResumeEntry(input);
+	return entry.latestRunId;
+}