pi-cohort 2.0.0

package/src/runs/shared/nested-path.ts

@@ -0,0 +1,52 @@
+import * as path from "node:path";
+
+const MAX_NESTED_ID_LENGTH = 128;
+export const MAX_NESTED_PATH_ENTRIES = 4;
+
+export type NestedPathEntry = { runId: string; stepIndex?: number; agent?: string };
+
+export function isSafeNestedPathId(value: unknown): value is string {
+	return typeof value === "string"
+		&& value.length > 0
+		&& value.length <= MAX_NESTED_ID_LENGTH
+		&& !path.isAbsolute(value)
+		&& !value.includes("/")
+		&& !value.includes("\\")
+		&& !value.includes("..");
+}
+
+function finiteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function nonEmptyString(value: unknown, max: number): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value.slice(0, max) : undefined;
+}
+
+export function sanitizeNestedPath(value: unknown): NestedPathEntry[] {
+	if (!Array.isArray(value)) return [];
+	return value.map((part) => {
+		if (!part || typeof part !== "object") return undefined;
+		const record = part as Record<string, unknown>;
+		if (!isSafeNestedPathId(record.runId)) return undefined;
+		return {
+			runId: record.runId,
+			...(finiteNumber(record.stepIndex) !== undefined ? { stepIndex: finiteNumber(record.stepIndex) } : {}),
+			...(nonEmptyString(record.agent, 128) ? { agent: nonEmptyString(record.agent, 128) } : {}),
+		};
+	}).filter((part): part is NestedPathEntry => Boolean(part)).slice(0, MAX_NESTED_PATH_ENTRIES);
+}
+
+export function parseNestedPathEnv(value: string | undefined): NestedPathEntry[] {
+	if (!value) return [];
+	try {
+		return sanitizeNestedPath(JSON.parse(value) as unknown);
+	} catch {
+		return [];
+	}
+}
+
+export function encodeNestedPathEnv(value: NestedPathEntry[]): string {
+	const sanitized = sanitizeNestedPath(value);
+	return sanitized.length ? JSON.stringify(sanitized) : "";
+}

package/src/runs/shared/nested-render.ts

@@ -0,0 +1,115 @@
+import { formatDuration, formatTokens, shortenPath } from "../../shared/formatters.ts";
+import { formatActivityLabel } from "../../shared/status-format.ts";
+import type { ActivityState, NestedRunSummary, NestedStepSummary } from "../../shared/types.ts";
+
+export interface NestedRunCounts {
+	total: number;
+	running: number;
+	paused: number;
+	complete: number;
+	failed: number;
+	queued: number;
+}
+
+export function countNestedRuns(children: NestedRunSummary[] | undefined): NestedRunCounts {
+	const counts: NestedRunCounts = { total: 0, running: 0, paused: 0, complete: 0, failed: 0, queued: 0 };
+	for (const child of children ?? []) {
+		counts.total++;
+		counts[child.state]++;
+		const nested = countNestedRuns([...(child.children ?? []), ...(child.steps?.flatMap((step) => step.children ?? []) ?? [])]);
+		counts.total += nested.total;
+		counts.running += nested.running;
+		counts.paused += nested.paused;
+		counts.complete += nested.complete;
+		counts.failed += nested.failed;
+		counts.queued += nested.queued;
+	}
+	return counts;
+}
+
+export function formatNestedAggregate(children: NestedRunSummary[] | undefined): string | undefined {
+	const counts = countNestedRuns(children);
+	if (counts.total === 0) return undefined;
+	const parts = [
+		counts.running > 0 ? `${counts.running} running` : "",
+		counts.paused > 0 ? `${counts.paused} paused` : "",
+		counts.failed > 0 ? `${counts.failed} failed` : "",
+		counts.complete > 0 ? `${counts.complete} complete` : "",
+		counts.queued > 0 ? `${counts.queued} queued` : "",
+	].filter(Boolean);
+	return `+${counts.total} nested run${counts.total === 1 ? "" : "s"}${parts.length ? ` (${parts.join(", ")})` : ""}`;
+}
+
+function nestedRunLabel(run: NestedRunSummary): string {
+	if (run.agent) return run.agent;
+	if (run.agents?.length) return run.agents.length === 1 ? run.agents[0]! : `${run.agents.slice(0, 2).join(", ")}${run.agents.length > 2 ? ` +${run.agents.length - 2}` : ""}`;
+	return run.id;
+}
+
+function formatNestedActivity(input: {
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	toolCount?: number;
+	totalTokens?: NestedRunSummary["totalTokens"];
+}): string | undefined {
+	const facts: string[] = [];
+	if (input.currentTool && input.currentToolStartedAt !== undefined) facts.push(`tool ${input.currentTool} ${formatDuration(Math.max(0, Date.now() - input.currentToolStartedAt))}`);
+	else if (input.currentTool) facts.push(`tool ${input.currentTool}`);
+	if (input.currentPath) facts.push(shortenPath(input.currentPath));
+	if (input.turnCount !== undefined) facts.push(`${input.turnCount} turns`);
+	if (input.toolCount !== undefined) facts.push(`${input.toolCount} tools`);
+	if (input.totalTokens) facts.push(`${formatTokens(input.totalTokens.total)} tok`);
+	const activity = formatActivityLabel(input.lastActivityAt, input.activityState as ActivityState | undefined);
+	return activity || facts.length ? [activity, ...facts].filter(Boolean).join(" | ") : undefined;
+}
+
+function formatNestedRunLines(children: NestedRunSummary[] | undefined, options: { indent: string; maxDepth: number; maxLines: number; commandHints?: boolean }): string[] {
+	const lines: string[] = [];
+	const append = (items: NestedRunSummary[] | undefined, depth: number, indent: string): void => {
+		if (!items?.length || lines.length >= options.maxLines) return;
+		if (depth > options.maxDepth) {
+			const aggregate = formatNestedAggregate(items);
+			if (aggregate && lines.length < options.maxLines) lines.push(`${indent}↳ ${aggregate}`);
+			return;
+		}
+		for (let index = 0; index < items.length; index++) {
+			const child = items[index]!;
+			if (lines.length >= options.maxLines) {
+				const aggregate = formatNestedAggregate(items.slice(index));
+				if (aggregate) lines[lines.length - 1] = `${indent}↳ ${aggregate}`;
+				return;
+			}
+			const activity = child.state === "running" ? formatNestedActivity(child) : undefined;
+			const error = child.error ? ` | error: ${child.error}` : "";
+			lines.push(`${indent}↳ ${nestedRunLabel(child)} [${child.id}] ${child.state}${activity ? ` | ${activity}` : ""}${error}`);
+			if (options.commandHints && lines.length < options.maxLines) lines.push(`${indent}  Status: subagent({ action: "status", id: "${child.id}" })`);
+			if (depth === options.maxDepth) {
+				const aggregate = formatNestedAggregate([...(child.steps?.flatMap((step) => step.children ?? []) ?? []), ...(child.children ?? [])]);
+				if (aggregate && lines.length < options.maxLines) lines.push(`${indent}  ↳ ${aggregate}`);
+				continue;
+			}
+			for (const [stepIndex, step] of (child.steps ?? []).entries()) {
+				if (lines.length >= options.maxLines) return;
+				const stepActivity = step.status === "running" ? formatNestedActivity(step) : undefined;
+				lines.push(`${indent}  ${stepIndex + 1}. ${step.agent} ${step.status}${stepActivity ? ` | ${stepActivity}` : ""}${step.error ? ` | error: ${step.error}` : ""}`);
+				append(step.children, depth + 1, `${indent}    `);
+			}
+			append(child.children, depth + 1, `${indent}  `);
+		}
+	};
+	append(children, 0, options.indent);
+	return lines;
+}
+
+export function formatNestedRunStatusLines(children: NestedRunSummary[] | undefined, options: { indent?: string; maxDepth?: number; maxLines?: number; commandHints?: boolean } = {}): string[] {
+	return formatNestedRunLines(children, {
+		indent: options.indent ?? "  ",
+		maxDepth: options.maxDepth ?? 2,
+		maxLines: options.maxLines ?? 40,
+		commandHints: options.commandHints ?? false,
+	});
+}

package/src/runs/shared/parallel-utils.ts

@@ -0,0 +1,136 @@
+export interface RunnerSubagentStep {
+	agent: string;
+	task: string;
+	phase?: string;
+	label?: string;
+	outputName?: string;
+	structured?: boolean;
+	cwd?: string;
+	model?: string;
+	thinking?: string;
+	modelCandidates?: string[];
+	tools?: string[];
+	extensions?: string[];
+	completionGuard?: boolean;
+	systemPrompt?: string | null;
+	systemPromptMode?: "append" | "replace";
+	inheritProjectContext: boolean;
+	inheritSkills: boolean;
+	skills?: string[];
+	outputPath?: string;
+	outputMode?: "inline" | "file-only";
+	sessionFile?: string;
+	maxSubagentDepth?: number;
+	structuredOutput?: {
+		schema: import("../../shared/types.ts").JsonSchemaObject;
+		schemaPath: string;
+		outputPath: string;
+	};
+	structuredOutputSchema?: import("../../shared/types.ts").JsonSchemaObject;
+	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
+}
+
+export interface ParallelStepGroup {
+	parallel: RunnerSubagentStep[];
+	concurrency?: number;
+	failFast?: boolean;
+	worktree?: boolean;
+}
+
+export interface DynamicRunnerGroup {
+	expand: import("../../shared/settings.ts").DynamicExpandSpec;
+	parallel: RunnerSubagentStep;
+	collect: import("../../shared/settings.ts").DynamicCollectSpec;
+	concurrency?: number;
+	failFast?: boolean;
+	phase?: string;
+	label?: string;
+	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
+}
+
+export type RunnerStep = RunnerSubagentStep | ParallelStepGroup | DynamicRunnerGroup;
+
+export function isParallelGroup(step: RunnerStep): step is ParallelStepGroup {
+	return "parallel" in step && Array.isArray(step.parallel);
+}
+
+export function isDynamicRunnerGroup(step: RunnerStep): step is DynamicRunnerGroup {
+	return "expand" in step && "collect" in step && "parallel" in step && !Array.isArray((step as { parallel?: unknown }).parallel);
+}
+
+export function flattenSteps(steps: RunnerStep[]): RunnerSubagentStep[] {
+	const flat: RunnerSubagentStep[] = [];
+	for (const step of steps) {
+		if (isParallelGroup(step)) {
+			for (const task of step.parallel) flat.push(task);
+		} else if (isDynamicRunnerGroup(step)) {
+			continue;
+		} else {
+			flat.push(step);
+		}
+	}
+	return flat;
+}
+
+export async function mapConcurrent<T, R>(
+	items: T[],
+	limit: number,
+	fn: (item: T, i: number) => Promise<R>,
+): Promise<R[]> {
+	const safeLimit = Math.max(1, Math.floor(limit) || 1);
+	const results: R[] = new Array(items.length);
+	let next = 0;
+
+	async function worker(_workerIndex: number): Promise<void> {
+		while (next < items.length) {
+			const i = next++;
+			results[i] = await fn(items[i], i);
+		}
+	}
+
+	await Promise.all(
+		Array.from({ length: Math.min(safeLimit, items.length) }, (_, wi) => worker(wi)),
+	);
+	return results;
+}
+
+export interface ParallelTaskResult {
+	agent: string;
+	taskIndex?: number;
+	output: string;
+	exitCode: number | null;
+	error?: string;
+	model?: string;
+	attemptedModels?: string[];
+	outputTargetPath?: string;
+	outputTargetExists?: boolean;
+}
+
+export function aggregateParallelOutputs(
+	results: ParallelTaskResult[],
+	headerFormat: (index: number, agent: string) => string = (i, agent) =>
+		`=== Parallel Task ${i + 1} (${agent}) ===`,
+): string {
+	return results
+		.map((r, i) => {
+			const header = headerFormat(r.taskIndex ?? i, r.agent);
+			const hasOutput = Boolean(r.output?.trim());
+			const status =
+				r.exitCode === -1
+					? "SKIPPED"
+					: r.exitCode !== 0 && r.exitCode !== null
+						? `FAILED (exit code ${r.exitCode})${r.error ? `: ${r.error}` : ""}`
+						: r.error
+							? `WARNING: ${r.error}`
+							: !hasOutput && r.outputTargetPath && r.outputTargetExists === false
+								? `EMPTY OUTPUT (expected output file missing: ${r.outputTargetPath})`
+								: !hasOutput && !r.outputTargetPath
+									? "EMPTY OUTPUT (no textual response returned)"
+							: "";
+			const body = status ? (hasOutput ? `${status}\n${r.output}` : status) : r.output;
+			return `${header}\n${body}`;
+		})
+		.join("\n\n");
+}
+
+export const MAX_PARALLEL_CONCURRENCY = 4;

package/src/runs/shared/pi-args.ts

@@ -0,0 +1,221 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { encodeNestedPathEnv, parseNestedPathEnv, type NestedPathEntry } from "./nested-path.ts";
+import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV } from "./structured-output.ts";
+import type { JsonSchemaObject } from "../../shared/types.ts";
+
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
+const TASK_ARG_LIMIT = 8000;
+const PROMPT_RUNTIME_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-prompt-runtime.ts");
+const FANOUT_CHILD_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "extension", "fanout-child.ts");
+export const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
+export const SUBAGENT_ORCHESTRATOR_TARGET_ENV = "PI_SUBAGENT_ORCHESTRATOR_TARGET";
+export const SUBAGENT_RUN_ID_ENV = "PI_SUBAGENT_RUN_ID";
+export const SUBAGENT_CHILD_AGENT_ENV = "PI_SUBAGENT_CHILD_AGENT";
+export const SUBAGENT_CHILD_INDEX_ENV = "PI_SUBAGENT_CHILD_INDEX";
+export const SUBAGENT_FANOUT_CHILD_ENV = "PI_SUBAGENT_FANOUT_CHILD";
+export const SUBAGENT_PARENT_EVENT_SINK_ENV = "PI_SUBAGENT_PARENT_EVENT_SINK";
+export const SUBAGENT_PARENT_CONTROL_INBOX_ENV = "PI_SUBAGENT_PARENT_CONTROL_INBOX";
+export const SUBAGENT_PARENT_ROOT_RUN_ID_ENV = "PI_SUBAGENT_PARENT_ROOT_RUN_ID";
+export const SUBAGENT_PARENT_RUN_ID_ENV = "PI_SUBAGENT_PARENT_RUN_ID";
+export const SUBAGENT_PARENT_CHILD_INDEX_ENV = "PI_SUBAGENT_PARENT_CHILD_INDEX";
+export const SUBAGENT_PARENT_DEPTH_ENV = "PI_SUBAGENT_PARENT_DEPTH";
+export const SUBAGENT_PARENT_PATH_ENV = "PI_SUBAGENT_PARENT_PATH";
+export const SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV = "PI_SUBAGENT_PARENT_CAPABILITY_TOKEN";
+
+interface BuildPiArgsInput {
+	baseArgs: string[];
+	task: string;
+	sessionEnabled: boolean;
+	sessionDir?: string;
+	sessionFile?: string;
+	model?: string;
+	thinking?: string;
+	systemPromptMode?: "append" | "replace";
+	inheritProjectContext: boolean;
+	inheritSkills: boolean;
+	tools?: string[];
+	extensions?: string[];
+	systemPrompt?: string | null;
+	cwd?: string;
+	promptFileStem?: string;
+	intercomSessionName?: string;
+	orchestratorIntercomTarget?: string;
+	runId?: string;
+	childAgentName?: string;
+	childIndex?: number;
+	parentEventSink?: string;
+	parentControlInbox?: string;
+	parentRootRunId?: string;
+	parentRunId?: string;
+	parentChildIndex?: number;
+	parentDepth?: number;
+	parentPath?: NestedPathEntry[];
+	parentCapabilityToken?: string;
+	structuredOutput?: {
+		schema: JsonSchemaObject;
+		schemaPath: string;
+		outputPath: string;
+	};
+}
+
+interface BuildPiArgsResult {
+	args: string[];
+	env: Record<string, string | undefined>;
+	tempDir?: string;
+}
+
+export function applyThinkingSuffix(model: string | undefined, thinking: string | undefined): string | undefined {
+	if (!model || !thinking || thinking === "off") return model;
+	const colonIdx = model.lastIndexOf(":");
+	if (colonIdx !== -1 && THINKING_LEVELS.includes(model.substring(colonIdx + 1))) return model;
+	return `${model}:${thinking}`;
+}
+
+export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
+	const args = [...input.baseArgs];
+
+	if (input.sessionFile) {
+		fs.mkdirSync(path.dirname(input.sessionFile), { recursive: true });
+		args.push("--session", input.sessionFile);
+	} else {
+		if (!input.sessionEnabled) {
+			args.push("--no-session");
+		}
+		if (input.sessionDir) {
+			fs.mkdirSync(input.sessionDir, { recursive: true });
+			args.push("--session-dir", input.sessionDir);
+		}
+	}
+
+	const modelArg = applyThinkingSuffix(input.model, input.thinking);
+	if (modelArg) {
+		args.push("--model", modelArg);
+	}
+
+	const declaredBuiltinTools = input.tools?.filter((tool) => !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) ?? [];
+	const fanoutAuthorized = declaredBuiltinTools.includes("subagent");
+	const toolExtensionPaths: string[] = [];
+	if (input.tools?.length) {
+		const builtinTools = [...declaredBuiltinTools];
+		for (const tool of input.tools) {
+			if (!declaredBuiltinTools.includes(tool) && (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) {
+				toolExtensionPaths.push(tool);
+			}
+		}
+		if (builtinTools.length > 0) {
+			args.push("--tools", builtinTools.join(","));
+		}
+	}
+
+	const runtimeExtensions = fanoutAuthorized
+		? [PROMPT_RUNTIME_EXTENSION_PATH, FANOUT_CHILD_EXTENSION_PATH]
+		: [PROMPT_RUNTIME_EXTENSION_PATH];
+	if (input.extensions !== undefined) {
+		args.push("--no-extensions");
+		for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths, ...input.extensions])]) {
+			args.push("--extension", extPath);
+		}
+	} else {
+		for (const extPath of [...new Set([...runtimeExtensions, ...toolExtensionPaths])]) {
+			args.push("--extension", extPath);
+		}
+	}
+
+	if (!input.inheritSkills) {
+		args.push("--no-skills");
+	}
+
+	let tempDir: string | undefined;
+	if (input.systemPrompt !== undefined && input.systemPrompt !== null) {
+		tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+		const stem = (input.promptFileStem ?? "prompt").replace(/[^\w.-]/g, "_");
+		const promptPath = path.join(tempDir, `${stem}.md`);
+		fs.writeFileSync(promptPath, input.systemPrompt, { mode: 0o600 });
+		args.push(input.systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt", promptPath);
+	}
+
+	if (input.task.length > TASK_ARG_LIMIT) {
+		if (!tempDir) {
+			tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+		}
+		const taskFilePath = path.join(tempDir, "task.md");
+		fs.writeFileSync(taskFilePath, `Task: ${input.task}`, { mode: 0o600 });
+		args.push(`@${taskFilePath}`);
+	} else {
+		args.push(`Task: ${input.task}`);
+	}
+
+	const env: Record<string, string | undefined> = {};
+	env[SUBAGENT_CHILD_ENV] = "1";
+	env[SUBAGENT_FANOUT_CHILD_ENV] = fanoutAuthorized ? "1" : "0";
+	const inheritedNestedRoute = Boolean(process.env[SUBAGENT_PARENT_EVENT_SINK_ENV] && process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] && process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV]);
+	const parentRunId = input.parentRunId ?? input.runId ?? (inheritedNestedRoute ? process.env[SUBAGENT_RUN_ID_ENV] : undefined) ?? process.env[SUBAGENT_PARENT_RUN_ID_ENV] ?? "";
+	const parentChildIndex = input.parentChildIndex !== undefined
+		? String(input.parentChildIndex)
+		: input.childIndex !== undefined
+			? String(input.childIndex)
+			: process.env[SUBAGENT_PARENT_CHILD_INDEX_ENV] ?? "";
+	const inheritedDepth = Number(process.env[SUBAGENT_PARENT_DEPTH_ENV]);
+	const parentDepth = input.parentDepth ?? (inheritedNestedRoute && Number.isFinite(inheritedDepth) ? inheritedDepth + 1 : 1);
+	const parentPath = input.parentPath ?? [
+		...parseNestedPathEnv(process.env[SUBAGENT_PARENT_PATH_ENV]),
+		...(parentRunId ? [{
+			runId: parentRunId,
+			...(parentChildIndex && /^\d+$/.test(parentChildIndex) ? { stepIndex: Number(parentChildIndex) } : {}),
+			...(input.childAgentName ? { agent: input.childAgentName } : {}),
+		}] : []),
+	];
+	env[SUBAGENT_PARENT_EVENT_SINK_ENV] = fanoutAuthorized
+		? input.parentEventSink ?? process.env[SUBAGENT_PARENT_EVENT_SINK_ENV] ?? ""
+		: "";
+	env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] = fanoutAuthorized
+		? input.parentControlInbox ?? process.env[SUBAGENT_PARENT_CONTROL_INBOX_ENV] ?? ""
+		: "";
+	env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] = fanoutAuthorized
+		? input.parentRootRunId ?? process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] ?? input.runId ?? ""
+		: "";
+	env[SUBAGENT_PARENT_RUN_ID_ENV] = fanoutAuthorized ? parentRunId : "";
+	env[SUBAGENT_PARENT_CHILD_INDEX_ENV] = fanoutAuthorized ? parentChildIndex : "";
+	env[SUBAGENT_PARENT_DEPTH_ENV] = fanoutAuthorized ? String(parentDepth) : "";
+	env[SUBAGENT_PARENT_PATH_ENV] = fanoutAuthorized ? encodeNestedPathEnv(parentPath) : "";
+	env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] = fanoutAuthorized
+		? input.parentCapabilityToken ?? process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] ?? ""
+		: "";
+	env.PI_SUBAGENT_INHERIT_PROJECT_CONTEXT = input.inheritProjectContext ? "1" : "0";
+	env.PI_SUBAGENT_INHERIT_SKILLS = input.inheritSkills ? "1" : "0";
+	if (input.intercomSessionName) {
+		env.PI_SUBAGENT_INTERCOM_SESSION_NAME = input.intercomSessionName;
+	}
+	if (input.orchestratorIntercomTarget) {
+		env[SUBAGENT_ORCHESTRATOR_TARGET_ENV] = input.orchestratorIntercomTarget;
+	}
+	if (input.runId) {
+		env[SUBAGENT_RUN_ID_ENV] = input.runId;
+	}
+	if (input.childAgentName) {
+		env[SUBAGENT_CHILD_AGENT_ENV] = input.childAgentName;
+	}
+	if (input.childIndex !== undefined) {
+		env[SUBAGENT_CHILD_INDEX_ENV] = String(input.childIndex);
+	}
+	if (input.structuredOutput) {
+		env[STRUCTURED_OUTPUT_CAPTURE_ENV] = input.structuredOutput.outputPath;
+		env[STRUCTURED_OUTPUT_SCHEMA_ENV] = input.structuredOutput.schemaPath;
+	}
+
+	return { args, env, tempDir };
+}
+
+export const parseParentPathEnv = parseNestedPathEnv;
+
+export function cleanupTempDir(tempDir: string | null | undefined): void {
+	if (!tempDir) return;
+	try {
+		fs.rmSync(tempDir, { recursive: true, force: true });
+	} catch {
+		// Temp cleanup is best effort.
+	}
+}

package/src/runs/shared/pi-spawn.ts

@@ -0,0 +1,115 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
+
+export function findPiPackageRootFromEntry(entryPoint: string): string | undefined {
+	let dir = path.dirname(entryPoint);
+	while (dir !== path.dirname(dir)) {
+		const packageJsonPath = path.join(dir, "package.json");
+		if (fs.existsSync(packageJsonPath)) {
+			const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) as { name?: unknown };
+			if (pkg.name === PI_CODING_AGENT_PACKAGE) return dir;
+		}
+		dir = path.dirname(dir);
+	}
+	return undefined;
+}
+
+export function resolveInstalledPiPackageRoot(): string | undefined {
+	return findPiPackageRootFromEntry(fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)));
+}
+
+export function resolvePiPackageRoot(): string | undefined {
+	try {
+		const entry = process.argv[1];
+		return entry ? findPiPackageRootFromEntry(fs.realpathSync(entry)) : undefined;
+	} catch {
+		// process.argv[1] probing is best-effort; callers can fall back to PATH/package resolution.
+		return undefined;
+	}
+}
+
+export interface PiSpawnDeps {
+	platform?: NodeJS.Platform;
+	execPath?: string;
+	argv1?: string;
+	existsSync?: (filePath: string) => boolean;
+	readFileSync?: (filePath: string, encoding: "utf-8") => string;
+	resolvePackageJson?: () => string;
+	resolvePackageEntry?: () => string;
+	piPackageRoot?: string;
+}
+
+interface PiSpawnCommand {
+	command: string;
+	args: string[];
+}
+
+function isRunnableNodeScript(filePath: string, existsSync: (filePath: string) => boolean): boolean {
+	if (!existsSync(filePath)) return false;
+	return /\.(?:mjs|cjs|js)$/i.test(filePath);
+}
+
+function normalizePath(filePath: string): string {
+	return path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
+}
+
+export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | undefined {
+	const existsSync = deps.existsSync ?? fs.existsSync;
+	const readFileSync = deps.readFileSync ?? ((filePath, encoding) => fs.readFileSync(filePath, encoding));
+	const argv1 = deps.argv1 ?? process.argv[1];
+
+	if (argv1) {
+		const argvPath = normalizePath(argv1);
+		if (isRunnableNodeScript(argvPath, existsSync)) {
+			return argvPath;
+		}
+	}
+
+	try {
+		const resolvePackageJson = deps.resolvePackageJson ?? (() => {
+			const root = deps.piPackageRoot ?? resolvePiPackageRoot();
+			if (root) return path.join(root, "package.json");
+			const packageRoot = deps.resolvePackageEntry
+				? findPiPackageRootFromEntry(deps.resolvePackageEntry())
+				: resolveInstalledPiPackageRoot();
+			if (!packageRoot) throw new Error(`Could not resolve ${PI_CODING_AGENT_PACKAGE} package root`);
+			return path.join(packageRoot, "package.json");
+		});
+		const packageJsonPath = resolvePackageJson();
+		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
+			bin?: string | Record<string, string>;
+		};
+		const binField = packageJson.bin;
+		const binPath = typeof binField === "string"
+			? binField
+			: binField?.pi ?? Object.values(binField ?? {})[0];
+		if (!binPath) return undefined;
+		const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
+		if (isRunnableNodeScript(candidate, existsSync)) {
+			return candidate;
+		}
+	} catch {
+		// Windows CLI resolution is optional; falling back to `pi` lets PATH handle execution.
+		return undefined;
+	}
+
+	return undefined;
+}
+
+export function getPiSpawnCommand(args: string[], deps: PiSpawnDeps = {}): PiSpawnCommand {
+	const platform = deps.platform ?? process.platform;
+	if (platform === "win32") {
+		const piCliPath = resolveWindowsPiCliScript(deps);
+		if (piCliPath) {
+			return {
+				command: deps.execPath ?? process.execPath,
+				args: [piCliPath, ...args],
+			};
+		}
+	}
+
+	return { command: "pi", args };
+}