pi-subagents 0.69.0 → 0.70.0

package/src/workflows/workflow-receipt.ts

@@ -1,384 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
-import type { AcceptanceRecoveryMetadata, ExternalCliReceiptMetadata, WorkflowReceipt, WorkflowReceiptEntry, WorkflowReceiptState, WorkflowRecoveryAction, WorkflowResourceProvenance, WorkflowTerminalOutcome, WorkflowTerminalResolution } from "../shared/types.ts";
-import type { WorkflowReceiptResumeReference, WorkflowScriptChildResult } from "./scripted-workflow.ts";
-import { parseWorkflowChildSummary } from "./workflow-child-summary.ts";
-import { HOST_STEP_MAX_COUNT, assertUniqueHostStepIds, parseHostStepNode } from "../runs/shared/host-step-status.ts";
-import { assertWorkflowLaneKey, normalizeWorkflowLaneMetadata } from "../runs/shared/lane-metadata.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 MAX_WORKFLOW_RECEIPT_BYTES = 2 * 1024 * 1024;
-
-const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const RESOURCE_ID_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[];
-	argsDigest?: string;
-	hostSteps?: WorkflowReceipt["hostSteps"];
-	workflowChildren?: WorkflowReceipt["workflowChildren"];
-	resource?: WorkflowResourceProvenance;
-	terminalOutcome?: WorkflowTerminalOutcome;
-	createdAt?: number;
-}): WorkflowReceipt {
-	const workflowRunId = assertSafeRunId(input.workflowRunId, "workflowRunId");
-	if (input.argsDigest !== undefined && !/^[a-f0-9]{64}$/u.test(input.argsDigest)) throw new Error("workflow receipt argsDigest must be a lowercase SHA-256 digest.");
-	if (input.workflowChildren?.workflowRunId !== undefined && input.workflowChildren.workflowRunId !== workflowRunId) throw new Error("workflowChildren workflowRunId does not match its receipt.");
-	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 lane = normalizeWorkflowLaneMetadata(child.lane, `workflow receipt child '${key}'.lane`);
-		assertWorkflowLaneKey(lane, key, `workflow receipt child '${key}'.lane`);
-		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,
-			...(lane ? { lane } : {}),
-			...(child.terminalOutcome ? { terminalOutcome: child.terminalOutcome } : {}),
-			...(child.agent ? { agent: child.agent } : {}),
-			...(child.requestedContext ? { requestedContext: child.requestedContext } : {}),
-			...(child.resolvedContext ? { resolvedContext: child.resolvedContext } : {}),
-			...(child.outputReference ? { outputReference: child.outputReference } : {}),
-			...(child.recovery ? { acceptanceRecovery: child.recovery } : {}),
-			...(child.externalAdapter ? { externalAdapter: child.externalAdapter } : {}),
-			continuation: { runIds },
-		};
-		entries[key] = resumability.state === "resumable"
-			? { ...base, latestRunId: latestRunId!, resumability }
-			: { ...base, ...(latestRunId ? { latestRunId } : {}), resumability };
-	}
-	if (input.hostSteps && input.hostSteps.length > HOST_STEP_MAX_COUNT) throw new Error(`Workflow receipt has more than ${HOST_STEP_MAX_COUNT} host steps.`);
-	const hostSteps = input.hostSteps?.map((hostStep, index) => parseHostStepNode(hostStep, `workflow receipt hostSteps[${index}]`));
-	if (hostSteps) assertUniqueHostStepIds(hostSteps, "workflow receipt");
-	const resource = parseWorkflowResource(input.resource, "workflow receipt");
-	return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries, ...(input.argsDigest ? { argsDigest: input.argsDigest } : {}), ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(input.workflowChildren ? { workflowChildren: input.workflowChildren } : {}), ...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}) };
-}
-
-export function writeWorkflowReceipt(asyncDir: string, receipt: WorkflowReceipt): string {
-	const receiptPath = path.join(asyncDir, WORKFLOW_RECEIPT_FILE);
-	writePrivateAtomicJson(receiptPath, receipt);
-	return receiptPath;
-}
-
-function readWorkflowReceiptFile(receiptPath: string): unknown {
-	let fd: number | undefined;
-	try {
-		fd = fs.openSync(receiptPath, "r");
-		const stat = fs.fstatSync(fd);
-		if (!stat.isFile()) throw new Error("workflow receipt is not a regular file.");
-		if (stat.size > MAX_WORKFLOW_RECEIPT_BYTES) throw new Error(`workflow receipt exceeds the ${MAX_WORKFLOW_RECEIPT_BYTES}-byte limit.`);
-		const buffer = Buffer.allocUnsafe(stat.size);
-		let offset = 0;
-		while (offset < buffer.length) {
-			const bytesRead = fs.readSync(fd, buffer, offset, buffer.length - offset, null);
-			if (bytesRead <= 0) throw new Error("workflow receipt ended before its declared size.");
-			offset += bytesRead;
-		}
-		return JSON.parse(buffer.toString("utf-8")) as unknown;
-	} finally {
-		if (fd !== undefined) fs.closeSync(fd);
-	}
-}
-
-const EXTERNAL_CLI_CAPABILITIES = {
-	stop: true,
-	steer: false,
-	resume: false,
-	structuredOutput: false,
-	toolEvents: false,
-	supervisor: "unsupported",
-	forkContext: false,
-	extensionBindings: false,
-} as const;
-
-function parseExternalCliMachine(value: unknown, label: string): void {
-	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label}.machine must be an object.`);
-	const machine = value as Record<string, unknown>;
-	const unknownMachine = Object.keys(machine).filter((field) => !["provider", "id", "label", "target", "session", "cwd", "remoteGit"].includes(field));
-	if (unknownMachine.length > 0) throw new Error(`${label}.machine has unsupported fields: ${unknownMachine.join(", ")}.`);
-	if (machine.provider !== "herdr" || typeof machine.id !== "string" || !machine.id.trim() || typeof machine.target !== "string" || !machine.target.trim() || typeof machine.cwd !== "string" || !machine.cwd.trim()) throw new Error(`${label}.machine is invalid.`);
-	for (const field of ["label", "session"] as const) if (machine[field] !== undefined && (typeof machine[field] !== "string" || !machine[field].trim())) throw new Error(`${label}.machine.${field} is invalid.`);
-	if (machine.remoteGit === undefined) return;
-	if (!machine.remoteGit || typeof machine.remoteGit !== "object" || Array.isArray(machine.remoteGit)) throw new Error(`${label}.machine.remoteGit must be an object.`);
-	const remoteGit = machine.remoteGit as Record<string, unknown>;
-	const unknownRemoteGit = Object.keys(remoteGit).filter((field) => !["head", "branch", "dirty"].includes(field));
-	if (unknownRemoteGit.length > 0 || (remoteGit.head !== undefined && (typeof remoteGit.head !== "string" || !remoteGit.head.trim())) || (remoteGit.branch !== undefined && (typeof remoteGit.branch !== "string" || !remoteGit.branch.trim())) || (remoteGit.dirty !== undefined && typeof remoteGit.dirty !== "boolean")) throw new Error(`${label}.machine.remoteGit is invalid.`);
-}
-
-function parseExternalCliReceiptMetadata(value: unknown, key: string, source: string): ExternalCliReceiptMetadata | undefined {
-	if (value === undefined) return undefined;
-	const label = `Invalid workflow receipt '${source}': entry '${key}' externalAdapter`;
-	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
-	const metadata = value as Record<string, unknown>;
-	const unknownMetadata = Object.keys(metadata).filter((field) => !["adapter", "capabilities", "machine", "safety", "outputArtifacts", "handoff", "supervisor", "nonResumableReason"].includes(field));
-	if (unknownMetadata.length > 0) throw new Error(`${label} has unsupported fields: ${unknownMetadata.join(", ")}.`);
-	const adapter = metadata.adapter;
-	if (!adapter || typeof adapter !== "object" || Array.isArray(adapter)) throw new Error(`${label}.adapter must be an object.`);
-	const adapterRecord = adapter as Record<string, unknown>;
-	const unknownAdapter = Object.keys(adapterRecord).filter((field) => !["id", "version", "executionMode"].includes(field));
-	if (unknownAdapter.length > 0) throw new Error(`${label}.adapter has unsupported fields: ${unknownAdapter.join(", ")}.`);
-	if ((adapterRecord.id !== "external-cli" && adapterRecord.id !== "codex-exec" && adapterRecord.id !== "codex-exec-writer" && adapterRecord.id !== "claude-code" && adapterRecord.id !== "claude-code-writer" && adapterRecord.id !== "cursor-agent" && adapterRecord.id !== "cursor-agent-writer" && adapterRecord.id !== "grok-build") || adapterRecord.version !== 1 || adapterRecord.executionMode !== (adapterRecord.id === "cursor-agent" || adapterRecord.id === "cursor-agent-writer" || adapterRecord.id === "grok-build" ? "one-shot-prompt-file" : "one-shot-stdin")) throw new Error(`${label}.adapter is invalid.`);
-	const capabilities = metadata.capabilities;
-	if (!capabilities || typeof capabilities !== "object" || Array.isArray(capabilities)) throw new Error(`${label}.capabilities must be an object.`);
-	const capabilityRecord = capabilities as Record<string, unknown>;
-	const unknownCapabilities = Object.keys(capabilityRecord).filter((field) => !(field in EXTERNAL_CLI_CAPABILITIES));
-	if (unknownCapabilities.length > 0) throw new Error(`${label}.capabilities has unsupported fields: ${unknownCapabilities.join(", ")}.`);
-	for (const [capability, expected] of Object.entries(EXTERNAL_CLI_CAPABILITIES)) {
-		if (capabilityRecord[capability] !== expected) throw new Error(`${label}.capabilities.${capability} is invalid.`);
-	}
-	if (metadata.machine !== undefined) parseExternalCliMachine(metadata.machine, label);
-	const safety = metadata.safety;
-	if (adapterRecord.id === "codex-exec") {
-		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
-		const safetyRecord = safety as Record<string, unknown>;
-		const unknownSafety = Object.keys(safetyRecord).filter((field) => !["sandbox", "approvalPolicy", "ephemeral"].includes(field));
-		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
-		if (safetyRecord.sandbox !== "read-only" || safetyRecord.approvalPolicy !== "never" || safetyRecord.ephemeral !== true) throw new Error(`${label}.safety is invalid.`);
-	} else if (adapterRecord.id === "codex-exec-writer") {
-		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
-		const safetyRecord = safety as Record<string, unknown>;
-		const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "sandbox", "approvalPolicy", "ephemeral"].includes(field));
-		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
-		if (safetyRecord.access !== "workspace-write" || safetyRecord.sandbox !== "workspace-write" || safetyRecord.approvalPolicy !== "never" || safetyRecord.ephemeral !== true) throw new Error(`${label}.safety is invalid.`);
-	} else if (adapterRecord.id === "claude-code") {
-		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
-		const safetyRecord = safety as Record<string, unknown>;
-		const legacy = safetyRecord.authentication === undefined;
-		const unknownSafety = Object.keys(safetyRecord).filter((field) => !(legacy
-			? ["permissionMode", "tools", "mcp", "settingSources", "sessionPersistence"]
-			: ["access", "authentication", "permissionMode", "tools", "mcp", "settingSources", "userSettingsTrust", "sessionPersistence"]).includes(field));
-		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
-		if (legacy) {
-			if (safetyRecord.permissionMode !== "plan" || safetyRecord.tools !== "none" || safetyRecord.mcp !== "empty-strict" || safetyRecord.settingSources !== "none" || safetyRecord.sessionPersistence !== false) throw new Error(`${label}.safety is invalid.`);
-		} else if (safetyRecord.access !== "read-only" || safetyRecord.authentication !== "existing-cli-required" || safetyRecord.permissionMode !== "plan" || safetyRecord.tools !== "none" || safetyRecord.mcp !== "empty-strict" || safetyRecord.settingSources !== "user" || safetyRecord.userSettingsTrust !== "required" || safetyRecord.sessionPersistence !== false) throw new Error(`${label}.safety is invalid.`);
-	} else if (adapterRecord.id === "claude-code-writer") {
-		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
-		const safetyRecord = safety as Record<string, unknown>;
-		const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "authentication", "permissionMode", "tools", "mcp", "settingSources", "userSettingsTrust", "sessionPersistence"].includes(field));
-		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
-		if (safetyRecord.access !== "workspace-write" || safetyRecord.authentication !== "existing-cli-required" || safetyRecord.permissionMode !== "acceptEdits" || safetyRecord.tools !== "Read,Write,Edit,Glob,Grep" || safetyRecord.mcp !== "empty-strict" || safetyRecord.settingSources !== "user" || safetyRecord.userSettingsTrust !== "required" || safetyRecord.sessionPersistence !== false) throw new Error(`${label}.safety is invalid.`);
-	} else if (adapterRecord.id === "cursor-agent" || adapterRecord.id === "cursor-agent-writer") {
-		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
-		const safetyRecord = safety as Record<string, unknown>;
-		const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "authentication", "mode", "sandbox", "workspaceTrust", "sessionReuse"].includes(field));
-		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
-		const writer = adapterRecord.id === "cursor-agent-writer";
-		if (safetyRecord.access !== (writer ? "workspace-write" : "read-only") || safetyRecord.authentication !== "cursor-api-key-or-existing-login" || safetyRecord.mode !== (writer ? "print" : "ask") || safetyRecord.sandbox !== "enabled" || safetyRecord.workspaceTrust !== "existing-required" || safetyRecord.sessionReuse !== false) throw new Error(`${label}.safety is invalid.`);
-	} else if (adapterRecord.id === "grok-build") {
-		if (!safety || typeof safety !== "object" || Array.isArray(safety)) throw new Error(`${label}.safety is missing.`);
-		const safetyRecord = safety as Record<string, unknown>;
-		const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "authentication", "permissionMode", "tools", "deniedTools", "sandbox", "webSearch", "subagents", "config", "updates", "sessionPersistence"].includes(field));
-		if (unknownSafety.length > 0) throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
-		if (safetyRecord.access !== "read-only" || safetyRecord.authentication !== "xai-api-key-required" || safetyRecord.permissionMode !== "plan" || safetyRecord.tools !== "read_file,grep,list_dir" || safetyRecord.deniedTools !== "run_terminal_cmd,search_replace,Agent,Bash,Edit,Write,MCPTool" || safetyRecord.sandbox !== "read-only" || safetyRecord.webSearch !== false || safetyRecord.subagents !== false || safetyRecord.config !== "temporary-home" || safetyRecord.updates !== "disabled" || safetyRecord.sessionPersistence !== false) throw new Error(`${label}.safety is invalid.`);
-	} else if (safety !== undefined) throw new Error(`${label}.safety is invalid for the generic adapter.`);
-	const handoff = metadata.handoff;
-	if (!handoff || typeof handoff !== "object" || Array.isArray(handoff)) throw new Error(`${label}.handoff must be an object.`);
-	const handoffRecord = handoff as Record<string, unknown>;
-	const unknownHandoff = Object.keys(handoffRecord).filter((field) => field !== "mode");
-	if (unknownHandoff.length > 0) throw new Error(`${label}.handoff has unsupported fields: ${unknownHandoff.join(", ")}.`);
-	if (handoffRecord.mode !== "fresh") throw new Error(`${label}.handoff is invalid.`);
-	const supervisor = metadata.supervisor;
-	if (!supervisor || typeof supervisor !== "object" || Array.isArray(supervisor)) throw new Error(`${label}.supervisor must be an object.`);
-	const supervisorRecord = supervisor as Record<string, unknown>;
-	const unknownSupervisor = Object.keys(supervisorRecord).filter((field) => !["mode", "reason"].includes(field));
-	if (unknownSupervisor.length > 0) throw new Error(`${label}.supervisor has unsupported fields: ${unknownSupervisor.join(", ")}.`);
-	if (supervisorRecord.mode !== "unsupported" || typeof supervisorRecord.reason !== "string" || !supervisorRecord.reason.trim()) throw new Error(`${label}.supervisor is invalid.`);
-	if (typeof metadata.nonResumableReason !== "string" || !metadata.nonResumableReason.trim()) throw new Error(`${label}.nonResumableReason is missing.`);
-	const outputArtifacts = metadata.outputArtifacts;
-	if (outputArtifacts !== undefined) {
-		if (!outputArtifacts || typeof outputArtifacts !== "object" || Array.isArray(outputArtifacts)) throw new Error(`${label}.outputArtifacts must be an object.`);
-		const unknownArtifacts = Object.keys(outputArtifacts).filter((field) => !["stdoutPath", "stderrPath", "finalOutputPath"].includes(field));
-		if (unknownArtifacts.length > 0) throw new Error(`${label}.outputArtifacts has unsupported fields: ${unknownArtifacts.join(", ")}.`);
-		for (const field of ["stdoutPath", "stderrPath", "finalOutputPath"] as const) {
-			const artifactPath = (outputArtifacts as Record<string, unknown>)[field];
-			if (artifactPath !== undefined && (typeof artifactPath !== "string" || !artifactPath.trim())) throw new Error(`${label}.outputArtifacts.${field} must be a non-empty string.`);
-		}
-	}
-	return value as ExternalCliReceiptMetadata;
-}
-
-function parseTerminalOutcome(value: unknown, label: string): WorkflowTerminalOutcome | undefined {
-	if (value === undefined) return undefined;
-	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
-	const outcome = value as Record<string, unknown>;
-	if (outcome.state !== "partial" || (outcome.reason !== "budget_exhausted" && outcome.reason !== "timeout")) throw new Error(`${label} is invalid.`);
-	return { state: "partial", reason: outcome.reason };
-}
-
-function parseAcceptanceRecoveryMetadata(value: unknown, label: string): AcceptanceRecoveryMetadata | undefined {
-	if (value === undefined) return undefined;
-	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
-	const recovery = value as Record<string, unknown>;
-	if (recovery.status !== "available-for-review" || recovery.reason !== "acceptance-metadata-rejected") throw new Error(`${label} is invalid.`);
-	if (typeof recovery.reportPath !== "string" || !recovery.reportPath.trim() || typeof recovery.reportHash !== "string" || !/^[a-f0-9]{64}$/u.test(recovery.reportHash)) throw new Error(`${label} is invalid.`);
-	return {
-		status: "available-for-review",
-		reason: "acceptance-metadata-rejected",
-		reportPath: recovery.reportPath,
-		reportHash: recovery.reportHash,
-	};
-}
-
-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.`);
-	const terminalOutcome = parseTerminalOutcome(entry.terminalOutcome, `Invalid workflow receipt '${source}': entry '${key}' terminalOutcome`);
-	const acceptanceRecovery = parseAcceptanceRecoveryMetadata(entry.acceptanceRecovery, `Invalid workflow receipt '${source}': entry '${key}' acceptanceRecovery`);
-	parseExternalCliReceiptMetadata(entry.externalAdapter, key, source);
-	const lane = normalizeWorkflowLaneMetadata(entry.lane, `Invalid workflow receipt '${source}': entry '${key}'.lane`);
-	assertWorkflowLaneKey(lane, key, `Invalid workflow receipt '${source}': entry '${key}'.lane`);
-	return { ...(value as WorkflowReceiptEntry), ...(lane ? { lane } : {}), ...(terminalOutcome ? { terminalOutcome } : {}), ...(acceptanceRecovery ? { acceptanceRecovery } : {}) };
-}
-
-function parseWorkflowResolution(value: unknown, source: string): WorkflowTerminalResolution | undefined {
-	if (value === undefined) return undefined;
-	if (value !== "settled-awaiting-resume" && value !== "failed-child" && value !== "interrupted-child") throw new Error(`Invalid workflow receipt '${source}': workflowResolution is invalid.`);
-	return value;
-}
-
-function parseWorkflowResource(value: unknown, source: string): WorkflowResourceProvenance | undefined {
-	if (value === undefined) return undefined;
-	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid workflow receipt '${source}': resource must be an object.`);
-	const resource = value as Record<string, unknown>;
-	if (resource.kind !== "workflow" || typeof resource.name !== "string" || !KEY_PATTERN.test(resource.name) || !Number.isInteger(resource.version) || (resource.version as number) < 1 || (resource.version as number) > 1_000_000 || resource.invocation !== "named" || resource.expansion !== "resolved" || typeof resource.id !== "string" || !RESOURCE_ID_PATTERN.test(resource.id)) {
-		throw new Error(`Invalid workflow receipt '${source}': resource is invalid.`);
-	}
-	return {
-		kind: "workflow",
-		name: resource.name,
-		version: resource.version as number,
-		invocation: "named",
-		expansion: "resolved",
-		id: resource.id,
-	};
-}
-
-function parseRecovery(value: unknown, workflowRunId: string, entries: Record<string, WorkflowReceiptEntry>, source: string): WorkflowRecoveryAction[] | undefined {
-	if (value === undefined) return undefined;
-	if (!Array.isArray(value)) throw new Error(`Invalid workflow receipt '${source}': recovery must be an array.`);
-	return value.map((item, index) => {
-		if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error(`Invalid workflow receipt '${source}': recovery[${index}] must be an object.`);
-		const action = item as Record<string, unknown>;
-		const key = action.key;
-		const resume = action.resume;
-		if (typeof key !== "string" || !entries[key] || action.call !== "runs.run" || action.taskRequired !== true || !resume || typeof resume !== "object" || Array.isArray(resume)) throw new Error(`Invalid workflow receipt '${source}': recovery[${index}] is invalid.`);
-		const reference = resume as Record<string, unknown>;
-		if (reference.workflowRunId !== workflowRunId || reference.key !== key || reference.latest !== true || entries[key].resumability.state !== "resumable") throw new Error(`Invalid workflow receipt '${source}': recovery[${index}] does not identify a resumable entry.`);
-		return { key, call: "runs.run", resume: { workflowRunId, key, latest: true }, taskRequired: true };
-	});
-}
-
-export function readWorkflowReceipt(asyncDirRoot: string, workflowRunId: string): WorkflowReceipt {
-	const receiptPath = workflowReceiptPath(asyncDirRoot, workflowRunId);
-	let value: unknown;
-	try {
-		value = readWorkflowReceiptFile(receiptPath);
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-			const workflowDir = path.dirname(receiptPath);
-			if (fs.existsSync(path.join(workflowDir, "status.json")) || fs.existsSync(path.join(workflowDir, "events.jsonl"))) {
-				throw new Error(`Workflow receipt '${workflowRunId}' is not available because the workflow may still be active or terminal receipt writing failed. Use direct child run IDs from status/events for direct resume after the normal retained-child checks.`);
-			}
-			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);
-	const workflowChildren = parseWorkflowChildSummary(receipt.workflowChildren);
-	if (workflowChildren && workflowChildren.workflowRunId !== workflowRunId) throw new Error(`Workflow receipt '${receiptPath}' is stale: workflowChildren.workflowRunId does not match.`);
-	let hostSteps: NonNullable<WorkflowReceipt["hostSteps"]> | undefined;
-	if (receipt.hostSteps !== undefined) {
-		if (!Array.isArray(receipt.hostSteps)) throw new Error(`Invalid workflow receipt '${receiptPath}': hostSteps must be an array.`);
-		if (receipt.hostSteps.length > HOST_STEP_MAX_COUNT) throw new Error(`Invalid workflow receipt '${receiptPath}': hostSteps exceeds ${HOST_STEP_MAX_COUNT} entries.`);
-		hostSteps = receipt.hostSteps.map((hostStep, index) => parseHostStepNode(hostStep, `${receiptPath} hostSteps[${index}]`));
-		assertUniqueHostStepIds(hostSteps, receiptPath);
-	}
-	const workflowResolution = parseWorkflowResolution(receipt.workflowResolution, receiptPath);
-	if (receipt.argsDigest !== undefined && (typeof receipt.argsDigest !== "string" || !/^[a-f0-9]{64}$/u.test(receipt.argsDigest))) throw new Error(`Invalid workflow receipt '${receiptPath}': argsDigest is invalid.`);
-	const resource = parseWorkflowResource(receipt.resource, receiptPath);
-	const terminalOutcome = parseTerminalOutcome(receipt.terminalOutcome, `Invalid workflow receipt '${receiptPath}': terminalOutcome`);
-	const recovery = parseRecovery(receipt.recovery, workflowRunId, entries, receiptPath);
-	return { version: 1, workflowRunId, state: receipt.state, createdAt: receipt.createdAt, entries, ...(receipt.argsDigest ? { argsDigest: receipt.argsDigest } : {}), ...(resource ? { resource } : {}), ...(hostSteps?.length ? { hostSteps } : {}), ...(workflowChildren ? { workflowChildren } : {}), ...(workflowResolution ? { workflowResolution } : {}), ...(terminalOutcome ? { terminalOutcome } : {}), ...(recovery ? { recovery } : {}) };
-}
-
-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;
-}

package/src/workflows/workflow-resources.ts

@@ -1,236 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { stableJsonDigest } from "../shared/launch-contract.ts";
-import {
-	createWorkflowResourcePermit,
-	type WorkflowResourceHostAuthority,
-	type WorkflowResourcePermit,
-} from "../shared/workflow-child-permit.ts";
-import type { WorkflowResourceProvenance } from "../shared/types.ts";
-
-const RESOURCE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const MAX_ARGS_BYTES = 16 * 1024;
-const MAX_STRING_BYTES = 16 * 1024;
-
-export interface ResolvedWorkflowResource {
-	script: string;
-	permit: WorkflowResourcePermit;
-	provenance: WorkflowResourceProvenance;
-}
-
-export type WorkflowResourceResolution =
-	| { ok: true; resource: ResolvedWorkflowResource }
-	| { ok: false; error: string };
-
-export interface WorkflowResourceDefinition {
-	name: string;
-	version: number;
-	/** Trusted synchronous validation/expansion. The extension owns semantic command binding. */
-	resolve: (args: Readonly<Record<string, unknown>>) => { script: string; hostCommands?: readonly WorkflowResourceHostAuthority[] } | { error: string };
-}
-
-export interface WorkflowResourceRegistration {
-	dispose(): void;
-}
-
-export interface RegisterWorkflowResourceInput {
-	sessionId: string;
-	definition: WorkflowResourceDefinition;
-}
-
-interface WorkflowResourceRegistry {
-	version: 1;
-	bySession: Map<string, Map<string, WorkflowResourceDefinition>>;
-}
-
-function registry(): WorkflowResourceRegistry {
-	const key = Symbol.for("pi-subagents.workflow-resources.v1");
-	const globalObject = globalThis as Record<PropertyKey, unknown>;
-	const existing = globalObject[key];
-	if (existing === undefined) {
-		const created: WorkflowResourceRegistry = { version: 1, bySession: new Map() };
-		globalObject[key] = created;
-		return created;
-	}
-	if (!isPlainRecord(existing) || existing.version !== 1 || !(existing.bySession instanceof Map)) throw new Error("Malformed or unsupported workflow resource registry.");
-	return existing as unknown as WorkflowResourceRegistry;
-}
-
-/** Session ID scopes lookup, not authentication. Dispose on session_shutdown; issued permits remain valid. */
-export function registerWorkflowResource(input: RegisterWorkflowResourceInput): WorkflowResourceRegistration {
-	if (!isPlainRecord(input) || Object.keys(input).some((key) => key !== "sessionId" && key !== "definition")) throw new Error("Workflow registration requires only sessionId and definition.");
-	const { sessionId, definition } = input;
-	if (typeof sessionId !== "string" || !sessionId || sessionId.trim() !== sessionId || sessionId.length > 256 || sessionId.includes("\0")) throw new Error("Workflow registration requires a non-empty trimmed sessionId of at most 256 characters without NUL.");
-	if (!isPlainRecord(definition) || Object.keys(definition).some((key) => !["name", "version", "resolve"].includes(key))) throw new Error("Workflow definition requires only name, version and resolve.");
-	const { name, version, resolve } = definition;
-	if (typeof name !== "string" || !RESOURCE_NAME_PATTERN.test(name)) throw new Error("Workflow definition requires a safe resource name.");
-	if (!Number.isSafeInteger(version) || version < 1) throw new Error("Workflow definition version must be a positive safe integer.");
-	if (typeof resolve !== "function") throw new Error("Workflow definition requires a synchronous resolve function.");
-	if (findWorkflowResource(name)) throw new Error(`Workflow resource '${name}' is a protected builtin.`);
-	const current = registry();
-	const bucket = current.bySession.get(sessionId) ?? new Map<string, WorkflowResourceDefinition>();
-	if (!(bucket instanceof Map)) throw new Error("Malformed workflow resource session registry.");
-	if (bucket.has(name)) throw new Error(`Workflow resource '${name}' is already registered in this session; dispose it first.`);
-	const snapshot = Object.freeze({ name, version, resolve });
-	bucket.set(name, snapshot);
-	current.bySession.set(sessionId, bucket);
-	let disposed = false;
-	return {
-		dispose() {
-			if (disposed) return;
-			disposed = true;
-			if (bucket.get(name) === snapshot) bucket.delete(name);
-			if (bucket.size === 0 && current.bySession.get(sessionId) === bucket) current.bySession.delete(sessionId);
-		},
-	};
-}
-
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	const prototype = Object.getPrototypeOf(value);
-	return prototype === Object.prototype || prototype === null;
-}
-
-function jsonByteLength(value: unknown): number {
-	try {
-		const encoded = JSON.stringify(value);
-		if (encoded === undefined) throw new Error("must contain JSON data");
-		return Buffer.byteLength(encoded, "utf8");
-	} catch (error) {
-		throw new Error(`must contain plain JSON data: ${error instanceof Error ? error.message : String(error)}`);
-	}
-}
-
-function validatePlainJson(value: unknown, path: string, depth = 0): void {
-	if (depth > 8) throw new Error(`${path} is too deeply nested.`);
-	if (value === null || typeof value === "boolean") return;
-	if (typeof value === "string") {
-		if (!value.trim()) throw new Error(`${path} must not be empty.`);
-		if (Buffer.byteLength(value, "utf8") > MAX_STRING_BYTES) throw new Error(`${path} exceeds ${MAX_STRING_BYTES} bytes.`);
-		return;
-	}
-	if (typeof value === "number") {
-		if (!Number.isFinite(value)) throw new Error(`${path} must be finite.`);
-		return;
-	}
-	if (Array.isArray(value)) {
-		if (value.length > 64) throw new Error(`${path} contains too many items.`);
-		for (const [index, entry] of value.entries()) validatePlainJson(entry, `${path}[${index}]`, depth + 1);
-		return;
-	}
-	if (!isPlainRecord(value)) throw new Error(`${path} must contain plain JSON data.`);
-	if (Object.keys(value).length > 16) throw new Error(`${path} contains too many fields.`);
-	for (const [key, entry] of Object.entries(value)) {
-		if (!key.trim()) throw new Error(`${path} contains an empty field name.`);
-		validatePlainJson(entry, `${path}.${key}`, depth + 1);
-	}
-}
-
-export function normalizeWorkflowArgs(value: unknown): { args: Record<string, unknown> } | { error: string } {
-	if (value === undefined) return { args: {} };
-	if (!isPlainRecord(value)) return { error: "workflow args must be a plain JSON object." };
-	try {
-		validatePlainJson(value, "workflow args");
-		if (jsonByteLength(value) > MAX_ARGS_BYTES) return { error: `workflow args exceed ${MAX_ARGS_BYTES} bytes.` };
-		return { args: JSON.parse(JSON.stringify(value)) };
-	} catch (error) {
-		return { error: error instanceof Error ? error.message : String(error) };
-	}
-}
-
-export function deepFreezeWorkflowArgs<T extends Record<string, unknown>>(args: T): Readonly<T> {
-	deepFreezeWorkflowValue(args);
-	return args;
-}
-
-function deepFreezeWorkflowValue(value: unknown): void {
-	if (!Array.isArray(value) && !isPlainRecord(value)) return;
-	for (const entry of Object.values(value)) deepFreezeWorkflowValue(entry);
-	Object.freeze(value);
-}
-
-function resolveRunCi(args: Readonly<Record<string, unknown>>): ReturnType<WorkflowResourceDefinition["resolve"]> {
-	const allowed = new Set(["command", "timeoutMs"]);
-	const unsupported = Object.keys(args).filter((key) => !allowed.has(key));
-	if (unsupported.length > 0) return { error: `workflow 'run-ci' args contain unsupported fields: ${unsupported.join(", ")}.` };
-	const command = args.command === undefined ? "npm test" : args.command;
-	if (command !== "npm test" && command !== "npm run typecheck") return { error: "workflow 'run-ci' args.command must be 'npm test' or 'npm run typecheck'." };
-	const timeoutMs = args.timeoutMs === undefined ? 120_000 : args.timeoutMs;
-	if (typeof timeoutMs !== "number" || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 86_400_000) return { error: "workflow 'run-ci' args.timeoutMs must be an integer from 1 to 86400000." };
-	const params = { kind: "command", command, timeoutMs, role: "ci" };
-	return {
-		script: `return await runs.host("ci", ${JSON.stringify(params)});`,
-		hostCommands: [{ key: "ci", command }],
-	};
-}
-
-function resolveReview(args: Readonly<Record<string, unknown>>): ReturnType<WorkflowResourceDefinition["resolve"]> {
-	const unsupported = Object.keys(args).filter((key) => key !== "task");
-	if (unsupported.length > 0) return { error: `workflow 'review' args contain unsupported fields: ${unsupported.join(", ")}.` };
-	const task = args.task;
-	if (typeof task !== "string" || !task.trim()) return { error: "workflow 'review' requires a non-empty string args.task." };
-	return {
-		script: `return (await runs.run("review", { agent: "reviewer", task: ${JSON.stringify(task.trim())} })).output;`,
-	};
-}
-
-const WORKFLOW_RESOURCES: readonly WorkflowResourceDefinition[] = [
-	{ name: "review", version: 1, resolve: resolveReview },
-	{ name: "run-ci", version: 1, resolve: resolveRunCi },
-];
-
-function findWorkflowResource(name: string): WorkflowResourceDefinition | undefined {
-	return WORKFLOW_RESOURCES.find((resource) => resource.name === name);
-}
-
-function listWorkflowResourceNames(): string[] {
-	return WORKFLOW_RESOURCES.map((resource) => resource.name);
-}
-
-/** Resolve only extension-owned resources so policy can distinguish them from raw scripts; caller-provided script text is never consulted. */
-export function resolveWorkflowResource(nameValue: unknown, argsValue?: unknown, sessionId?: string): WorkflowResourceResolution {
-	try {
-		const result = resolveResource(nameValue, argsValue, sessionId);
-		return result.ok ? result : { ok: false, error: result.error.slice(0, 4096) };
-	} catch (error) {
-		return { ok: false, error: error instanceof Error ? error.message.slice(0, 4096) : "Workflow resource resolution failed." };
-	}
-}
-
-function resolveResource(nameValue: unknown, argsValue?: unknown, sessionId?: string): WorkflowResourceResolution {
-	if (typeof nameValue !== "string" || !nameValue.trim()) return { ok: false, error: "workflow must be a non-empty resource name." };
-	const name = nameValue.trim();
-	if (!RESOURCE_NAME_PATTERN.test(name)) return { ok: false, error: "workflow must use a safe resource name." };
-	const resource = findWorkflowResource(name) ?? (sessionId ? registry().bySession.get(sessionId)?.get(name) : undefined);
-	if (!resource) return { ok: false, error: `Unknown workflow resource '${name}'. Available resources: ${listWorkflowResourceNames().join(", ")}.` };
-	const normalizedArgs = normalizeWorkflowArgs(argsValue);
-	if ("error" in normalizedArgs) return { ok: false, error: normalizedArgs.error };
-	const resolved = resource.resolve(normalizedArgs.args);
-	if (resolved && typeof (resolved as unknown as { then?: unknown }).then === "function") {
-		void Promise.resolve(resolved).catch(() => {});
-		throw new Error("Workflow resource resolve must be synchronous.");
-	}
-	if (!isPlainRecord(resolved)) throw new Error("Workflow resource resolve must return an expansion or error object.");
-	if ("error" in resolved) {
-		if (Object.keys(resolved).some((key) => key !== "error") || typeof resolved.error !== "string" || !resolved.error.trim()) throw new Error("Workflow resource returned an invalid error.");
-		return { ok: false, error: resolved.error };
-	}
-	const { script, hostCommands } = resolved;
-	if (Object.keys(resolved).some((key) => key !== "script" && key !== "hostCommands") || typeof script !== "string" || !script.trim()) throw new Error("Workflow resource returned an invalid expansion.");
-	const resourceId = randomUUID();
-	const permit = createWorkflowResourcePermit({
-		resourceName: resource.name,
-		resourceVersion: resource.version,
-		resourceId,
-		scriptDigest: stableJsonDigest(script),
-		authority: { host: hostCommands },
-	});
-	const provenance: WorkflowResourceProvenance = Object.freeze({
-		kind: "workflow",
-		name: resource.name,
-		version: resource.version,
-		invocation: "named",
-		expansion: "resolved",
-		id: resourceId,
-	});
-	return { ok: true, resource: { script, permit, provenance } };
-}