pi-subagents 0.8.2 → 0.8.4

package/execution.ts

@@ -7,7 +7,6 @@ import * as fs from "node:fs";
 import type { Message } from "@mariozechner/pi-ai";
 import type { AgentConfig } from "./agents.js";
 import {
-	appendJsonl,
 	ensureArtifactsDir,
 	getArtifactPaths,
 	writeArtifact,
@@ -31,6 +30,8 @@ import {
 	extractTextFromContent,
 } from "./utils.js";
 import { buildSkillInjection, resolveSkills } from "./skills.js";
+import { getPiSpawnCommand } from "./pi-spawn.js";
+import { createJsonlWriter } from "./jsonl-writer.js";
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 
@@ -78,13 +79,16 @@ export async function runSync(
 	}
 	const effectiveModel = modelOverride ?? agent.model;
 	const modelArg = applyThinkingSuffix(effectiveModel, agent.thinking);
-	if (modelArg) args.push("--model", modelArg);
+	// Use --models (not --model) because pi CLI silently ignores --model
+	// without a companion --provider flag. --models resolves the provider
+	// automatically via resolveModelScope. See: #8
+	if (modelArg) args.push("--models", modelArg);
+	const toolExtensionPaths: string[] = [];
 	if (agent.tools?.length) {
 		const builtinTools: string[] = [];
-		const extensionPaths: string[] = [];
 		for (const tool of agent.tools) {
 			if (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")) {
-				extensionPaths.push(tool);
+				toolExtensionPaths.push(tool);
 			} else {
 				builtinTools.push(tool);
 			}
@@ -92,7 +96,14 @@ export async function runSync(
 		if (builtinTools.length > 0) {
 			args.push("--tools", builtinTools.join(","));
 		}
-		for (const extPath of extensionPaths) {
+	}
+	if (agent.extensions !== undefined) {
+		args.push("--no-extensions");
+		for (const extPath of agent.extensions) {
+			args.push("--extension", extPath);
+		}
+	} else {
+		for (const extPath of toolExtensionPaths) {
 			args.push("--extension", extPath);
 		}
 	}
@@ -140,15 +151,18 @@ export async function runSync(
 	result.progress = progress;
 
 	const startTime = Date.now();
-	const jsonlLines: string[] = [];
 
 	let artifactPathsResult: ArtifactPaths | undefined;
+	let jsonlPath: string | undefined;
 	if (artifactsDir && artifactConfig?.enabled !== false) {
 		artifactPathsResult = getArtifactPaths(artifactsDir, runId, agentName, index);
 		ensureArtifactsDir(artifactsDir);
 		if (artifactConfig?.includeInput !== false) {
 			writeArtifact(artifactPathsResult.inputPath, `# Task for ${agentName}\n\n${task}`);
 		}
+		if (artifactConfig?.includeJsonl !== false) {
+			jsonlPath = artifactPathsResult.jsonlPath;
+		}
 	}
 
 	const spawnEnv = { ...process.env, ...getSubagentDepthEnv() };
@@ -159,8 +173,16 @@ export async function runSync(
 		spawnEnv.MCP_DIRECT_TOOLS = "__none__";
 	}
 
+	let closeJsonlWriter: (() => Promise<void>) | undefined;
 	const exitCode = await new Promise<number>((resolve) => {
-		const proc = spawn("pi", args, { cwd: cwd ?? runtimeCwd, env: spawnEnv, stdio: ["ignore", "pipe", "pipe"] });
+		const spawnSpec = getPiSpawnCommand(args);
+		const proc = spawn(spawnSpec.command, spawnSpec.args, {
+			cwd: cwd ?? runtimeCwd,
+			env: spawnEnv,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		const jsonlWriter = createJsonlWriter(jsonlPath, proc.stdout);
+		closeJsonlWriter = () => jsonlWriter.close();
 		let buf = "";
 
 		// Throttled update mechanism - consolidates all updates
@@ -209,7 +231,7 @@ export async function runSync(
 
 		const processLine = (line: string) => {
 			if (!line.trim()) return;
-			jsonlLines.push(line);
+			jsonlWriter.writeLine(line);
 			try {
 				const evt = JSON.parse(line) as { type?: string; message?: Message; toolName?: string; args?: unknown };
 				const now = Date.now();
@@ -329,6 +351,12 @@ export async function runSync(
 		}
 	});
 
+	if (closeJsonlWriter) {
+		try {
+			await closeJsonlWriter();
+		} catch {}
+	}
+
 	if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
 	result.exitCode = exitCode;
 
@@ -365,11 +393,6 @@ export async function runSync(
 		if (artifactConfig?.includeOutput !== false) {
 			writeArtifact(artifactPathsResult.outputPath, fullOutput);
 		}
-		if (artifactConfig?.includeJsonl !== false) {
-			for (const line of jsonlLines) {
-				appendJsonl(artifactPathsResult.jsonlPath, line);
-			}
-		}
 		if (artifactConfig?.includeMetadata !== false) {
 			writeMetadata(artifactPathsResult.metadataPath, {
 				runId,

package/file-coalescer.ts

@@ -0,0 +1,40 @@
+interface TimerApi {
+	setTimeout(handler: () => void, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+}
+
+interface FileCoalescer {
+	schedule(file: string, delayMs?: number): boolean;
+	clear(): void;
+}
+
+const defaultTimerApi: TimerApi = {
+	setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+export function createFileCoalescer(
+	handler: (file: string) => void,
+	defaultDelayMs: number,
+	timerApi: TimerApi = defaultTimerApi,
+): FileCoalescer {
+	const pending = new Map<string, unknown>();
+
+	return {
+		schedule(file: string, delayMs = defaultDelayMs): boolean {
+			if (pending.has(file)) return false;
+			const timer = timerApi.setTimeout(() => {
+				pending.delete(file);
+				handler(file);
+			}, delayMs);
+			pending.set(file, timer);
+			return true;
+		},
+		clear(): void {
+			for (const timer of pending.values()) {
+				timerApi.clearTimeout(timer);
+			}
+			pending.clear();
+		},
+	};
+}

package/index.ts

@@ -19,9 +19,10 @@ import * as path from "node:path";
 import { type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { type AgentConfig, type AgentScope, discoverAgents, discoverAgentsAll } from "./agents.js";
+import { resolveExecutionAgentScope } from "./agent-scope.js";
 import { cleanupOldChainDirs, getStepAgents, isParallelStep, resolveStepBehavior, type ChainStep, type SequentialStep } from "./settings.js";
 import { ChainClarifyComponent, type ChainClarifyResult, type ModelInfo } from "./chain-clarify.js";
-import { cleanupOldArtifacts, getArtifactsDir } from "./artifacts.js";
+import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "./artifacts.js";
 import {
 	type AgentProgress,
 	type ArtifactConfig,
@@ -41,12 +42,15 @@ import {
 	checkSubagentDepth,
 } from "./types.js";
 import { readStatus, findByPrefix, getFinalOutput, mapConcurrent } from "./utils.js";
+import { buildCompletionKey, markSeenWithTtl } from "./completion-dedupe.js";
+import { createFileCoalescer } from "./file-coalescer.js";
 import { runSync } from "./execution.js";
 import { renderWidget, renderSubagentResult } from "./render.js";
 import { SubagentParams, StatusParams } from "./schemas.js";
 import { executeChain } from "./chain-execution.js";
 import { isAsyncAvailable, executeAsyncChain, executeAsyncSingle } from "./async-execution.js";
 import { discoverAvailableSkills, normalizeSkillInput } from "./skills.js";
+import { finalizeSingleOutput, injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.js";
 import { AgentManagerComponent, type ManagerResult } from "./agent-manager.js";
 import { recordRun } from "./run-history.js";
 import { handleManagementAction } from "./agent-management.js";
@@ -74,7 +78,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const asyncByDefault = config.asyncByDefault === true;
 
 	const tempArtifactsDir = getArtifactsDir(null);
-	cleanupOldArtifacts(tempArtifactsDir, DEFAULT_ARTIFACT_CONFIG.cleanupDays);
+	cleanupAllArtifactDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
 	let baseCwd = process.cwd();
 	let currentSessionId: string | null = null;
 	const asyncJobs = new Map<string, AsyncJobState>();
@@ -125,6 +129,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		poller.unref?.();
 	};
 
+	const completionSeen = new Map<string, number>();
+	const completionTtlMs = 10 * 60 * 1000;
 	const handleResult = (file: string) => {
 		const p = path.join(RESULTS_DIR, file);
 		if (!fs.existsSync(p)) return;
@@ -132,19 +138,30 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			const data = JSON.parse(fs.readFileSync(p, "utf-8"));
 			if (data.sessionId && data.sessionId !== currentSessionId) return;
 			if (!data.sessionId && data.cwd && data.cwd !== baseCwd) return;
+			const now = Date.now();
+			const completionKey = buildCompletionKey(data, `result:${file}`);
+			if (markSeenWithTtl(completionSeen, completionKey, now, completionTtlMs)) {
+				try {
+					fs.unlinkSync(p);
+				} catch {}
+				return;
+			}
 			pi.events.emit("subagent:complete", data);
-			pi.events.emit("subagent_enhanced:complete", data);
 			fs.unlinkSync(p);
 		} catch {}
 	};
 
+	const resultFileCoalescer = createFileCoalescer(handleResult, 50);
 	const watcher = fs.watch(RESULTS_DIR, (ev, file) => {
-		if (ev === "rename" && file?.toString().endsWith(".json")) setTimeout(() => handleResult(file.toString()), 50);
+		if (ev !== "rename" || !file) return;
+		const fileName = file.toString();
+		if (!fileName.endsWith(".json")) return;
+		resultFileCoalescer.schedule(fileName);
 	});
 	watcher.unref?.();
 	fs.readdirSync(RESULTS_DIR)
 		.filter((f) => f.endsWith(".json"))
-		.forEach(handleResult);
+		.forEach((file) => resultFileCoalescer.schedule(file, 0));
 
 	const tool: ToolDefinition<typeof SubagentParams, Details> = {
 		name: "subagent",
@@ -159,7 +176,7 @@ EXECUTION (use exactly ONE mode):
 CHAIN TEMPLATE VARIABLES (use in task strings):
 • {task} - The original task/request from the user
 • {previous} - Text response from the previous step (empty for first step)
-• {chain_dir} - Shared directory for chain files (e.g., /tmp/pi-chain-runs/abc123/)
+• {chain_dir} - Shared directory for chain files (e.g., <tmpdir>/pi-chain-runs/abc123/)
 
 CHAIN DATA FLOW:
 1. Each step's text response automatically becomes {previous} for the next step
@@ -208,7 +225,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 				};
 			}
 
-			const scope: AgentScope = params.agentScope ?? "user";
+			const scope: AgentScope = resolveExecutionAgentScope(params.agentScope);
 			currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 			const agents = discoverAgents(ctx.cwd, scope).agents;
 			const runId = randomUUID().slice(0, 8);
@@ -352,6 +369,8 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 							details: { mode: "single" as const, results: [] },
 						};
 					}
+					const rawOutput = params.output !== undefined ? params.output : a.output;
+					const effectiveOutput: string | false | undefined = rawOutput === true ? a.output : rawOutput;
 					return executeAsyncSingle(id, {
 						agent: params.agent!,
 						task: params.task!,
@@ -369,6 +388,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 							if (normalized === undefined) return undefined;
 							return normalized;
 						})(),
+						output: effectiveOutput,
 					});
 				}
 			}
@@ -425,7 +445,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 
 				// Mutable copies for TUI modifications
 				let tasks = params.tasks.map(t => t.task);
-				const modelOverrides: (string | undefined)[] = new Array(params.tasks.length).fill(undefined);
+				const modelOverrides: (string | undefined)[] = params.tasks.map(t => (t as { model?: string }).model);
 				// Initialize skill overrides from task-level skill params (may be overridden by TUI)
 				const skillOverrides: (string[] | false | undefined)[] = params.tasks.map(t => 
 					normalizeSkillInput((t as { skill?: string | string[] | boolean }).skill)
@@ -598,17 +618,9 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 					if (override?.skills !== undefined) skillOverride = override.skills;
 				}
 
-				// Compute output path at runtime (uses effectiveOutput which may be TUI-modified)
 				const cleanTask = task;
-				let outputPath: string | undefined;
-				if (typeof effectiveOutput === 'string' && effectiveOutput) {
-					const outputDir = `/tmp/pi-${agentConfig.name}-${runId}`;
-					fs.mkdirSync(outputDir, { recursive: true });
-					outputPath = `${outputDir}/${effectiveOutput}`;
-
-					// Inject output instruction into task
-					task += `\n\n---\n**Output:** Write your findings to: ${outputPath}`;
-				}
+				const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, params.cwd);
+				task = injectSingleOutputInstruction(task, outputPath);
 
 				const effectiveSkills = skillOverride === false
 					? []
@@ -634,11 +646,13 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 				if (r.progress) allProgress.push(r.progress);
 				if (r.artifactPaths) allArtifactPaths.push(r.artifactPaths);
 
-				// Get output and append file path if applicable
-				let output = r.truncation?.text || getFinalOutput(r.messages);
-				if (outputPath && r.exitCode === 0) {
-					output += `\n\n📄 Output saved to: ${outputPath}`;
-				}
+				const fullOutput = getFinalOutput(r.messages);
+				const finalizedOutput = finalizeSingleOutput({
+					fullOutput,
+					truncatedOutput: r.truncation?.text,
+					outputPath,
+					exitCode: r.exitCode,
+				});
 
 				if (r.exitCode !== 0)
 					return {
@@ -653,7 +667,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 						isError: true,
 					};
 				return {
-					content: [{ type: "text", text: output || "(no output)" }],
+					content: [{ type: "text", text: finalizedOutput.displayOutput || "(no output)" }],
 					details: {
 						mode: "single",
 						results: [r],
@@ -1129,12 +1143,23 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 		}
 	});
 
+	const cleanupSessionArtifacts = (ctx: ExtensionContext) => {
+		try {
+			const sessionFile = ctx.sessionManager.getSessionFile();
+			if (sessionFile) {
+				cleanupOldArtifacts(getArtifactsDir(sessionFile), DEFAULT_ARTIFACT_CONFIG.cleanupDays);
+			}
+		} catch {}
+	};
+
 	pi.on("session_start", (_event, ctx) => {
 		baseCwd = ctx.cwd;
 		currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+		cleanupSessionArtifacts(ctx);
 		for (const timer of cleanupTimers.values()) clearTimeout(timer);
 		cleanupTimers.clear();
 		asyncJobs.clear();
+		resultFileCoalescer.clear();
 		if (ctx.hasUI) {
 			lastUiContext = ctx;
 			renderWidget(ctx, []);
@@ -1143,9 +1168,11 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 	pi.on("session_switch", (_event, ctx) => {
 		baseCwd = ctx.cwd;
 		currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+		cleanupSessionArtifacts(ctx);
 		for (const timer of cleanupTimers.values()) clearTimeout(timer);
 		cleanupTimers.clear();
 		asyncJobs.clear();
+		resultFileCoalescer.clear();
 		if (ctx.hasUI) {
 			lastUiContext = ctx;
 			renderWidget(ctx, []);
@@ -1154,9 +1181,11 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 	pi.on("session_branch", (_event, ctx) => {
 		baseCwd = ctx.cwd;
 		currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+		cleanupSessionArtifacts(ctx);
 		for (const timer of cleanupTimers.values()) clearTimeout(timer);
 		cleanupTimers.clear();
 		asyncJobs.clear();
+		resultFileCoalescer.clear();
 		if (ctx.hasUI) {
 			lastUiContext = ctx;
 			renderWidget(ctx, []);
@@ -1172,6 +1201,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 		}
 		cleanupTimers.clear();
 		asyncJobs.clear();
+		resultFileCoalescer.clear();
 		if (lastUiContext?.hasUI) {
 			lastUiContext.ui.setWidget(WIDGET_KEY, undefined);
 		}

package/jsonl-writer.ts

@@ -0,0 +1,81 @@
+import * as fs from "node:fs";
+
+export interface DrainableSource {
+	pause(): void;
+	resume(): void;
+}
+
+export interface JsonlWriteStream {
+	write(chunk: string): boolean;
+	once(event: "drain", listener: () => void): JsonlWriteStream;
+	end(callback?: () => void): void;
+}
+
+const DEFAULT_MAX_JSONL_BYTES = 50 * 1024 * 1024;
+
+export interface JsonlWriterDeps {
+	createWriteStream?: (filePath: string) => JsonlWriteStream;
+	maxBytes?: number;
+}
+
+export interface JsonlWriter {
+	writeLine(line: string): void;
+	close(): Promise<void>;
+}
+
+export function createJsonlWriter(
+	filePath: string | undefined,
+	source: DrainableSource,
+	deps: JsonlWriterDeps = {},
+): JsonlWriter {
+	if (!filePath) {
+		return {
+			writeLine() {},
+			async close() {},
+		};
+	}
+
+	const createWriteStream = deps.createWriteStream ?? ((targetPath: string) => fs.createWriteStream(targetPath, { flags: "a" }));
+	let stream: JsonlWriteStream | undefined;
+	try {
+		stream = createWriteStream(filePath);
+	} catch {
+		return {
+			writeLine() {},
+			async close() {},
+		};
+	}
+
+	let backpressured = false;
+	let closed = false;
+	let bytesWritten = 0;
+	const maxBytes = deps.maxBytes ?? DEFAULT_MAX_JSONL_BYTES;
+
+	return {
+		writeLine(line: string) {
+			if (!stream || closed || !line.trim()) return;
+			const chunk = `${line}\n`;
+			const chunkBytes = Buffer.byteLength(chunk, "utf-8");
+			if (bytesWritten + chunkBytes > maxBytes) return;
+			try {
+				const ok = stream.write(chunk);
+				bytesWritten += chunkBytes;
+				if (!ok && !backpressured) {
+					backpressured = true;
+					source.pause();
+					stream.once("drain", () => {
+						backpressured = false;
+						if (!closed) source.resume();
+					});
+				}
+			} catch {}
+		},
+		async close() {
+			if (!stream || closed) return;
+			closed = true;
+			const current = stream;
+			stream = undefined;
+			await new Promise<void>((resolve) => current.end(() => resolve()));
+		},
+	};
+}

package/notify.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "./completion-dedupe.js";
 
 interface ChainStepResult {
 	agent: string;
@@ -27,22 +28,14 @@ interface SubagentResult {
 }
 
 export default function registerSubagentNotify(pi: ExtensionAPI): void {
-	const seen = new Map<string, number>();
+	const seen = getGlobalSeenMap("__pi_subagents_notify_seen__");
 	const ttlMs = 10 * 60 * 1000;
 
-	const prune = (now: number) => {
-		for (const [key, ts] of seen.entries()) {
-			if (now - ts > ttlMs) seen.delete(key);
-		}
-	};
-
 	const handleComplete = (data: unknown) => {
 		const result = data as SubagentResult;
 		const now = Date.now();
-		const key = `${result.id ?? "no-id"}:${result.agent ?? "unknown"}:${result.timestamp ?? now}`;
-		prune(now);
-		if (seen.has(key)) return;
-		seen.set(key, now);
+		const key = buildCompletionKey(result, "notify");
+		if (markSeenWithTtl(seen, key, now, ttlMs)) return;
 
 		const agent = result.agent ?? "unknown";
 		const status = result.success ? "completed" : "failed";
@@ -82,6 +75,4 @@ export default function registerSubagentNotify(pi: ExtensionAPI): void {
 	};
 
 	pi.events.on("subagent:complete", handleComplete);
-	pi.events.on("subagent_enhanced:complete", handleComplete);
-	pi.events.on("async_subagent:complete", handleComplete);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --experimental-strip-types --test recursion-guard.test.ts"
+    "test": "node --experimental-strip-types --test *.test.ts"
   },
   "pi": {
     "extensions": [

package/pi-spawn.ts

@@ -0,0 +1,77 @@
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+export interface PiSpawnDeps {
+	platform?: NodeJS.Platform;
+	execPath?: string;
+	argv1?: string;
+	existsSync?: (filePath: string) => boolean;
+	readFileSync?: (filePath: string, encoding: "utf-8") => string;
+	resolvePackageJson?: () => string;
+}
+
+export 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 ?? (() => require.resolve("@mariozechner/pi-coding-agent/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 = normalizePath(path.resolve(path.dirname(packageJsonPath), binPath));
+		if (isRunnableNodeScript(candidate, existsSync)) {
+			return candidate;
+		}
+	} catch {
+		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 };
+}