pi-crew 0.1.0

package/src/extension/tool-result.ts

@@ -0,0 +1,16 @@
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import type { TeamToolDetails } from "./team-tool.ts";
+
+export type PiTeamsToolResult<TDetails = TeamToolDetails> = AgentToolResult<TDetails> & { isError?: boolean };
+
+export function toolResult<TDetails>(text: string, details: TDetails, isError = false): PiTeamsToolResult<TDetails> {
+	return { content: [{ type: "text", text }], details, isError };
+}
+
+export function isToolError(result: { isError?: boolean }): boolean {
+	return result.isError === true;
+}
+
+export function textFromToolResult(result: { content?: Array<{ type: string; text?: string }> }): string {
+	return result.content?.map((item) => item.text ?? "").join("\n") ?? "";
+}

package/src/extension/validate-resources.ts

@@ -0,0 +1,77 @@
+import { allAgents, discoverAgents } from "../agents/discover-agents.ts";
+import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
+import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
+import { validateWorkflowForTeam } from "../workflows/validate-workflow.ts";
+
+export interface ValidationIssue {
+	level: "error" | "warning";
+	resource: string;
+	message: string;
+}
+
+export interface ValidationReport {
+	issues: ValidationIssue[];
+	agents: number;
+	teams: number;
+	workflows: number;
+}
+
+export function validateResources(cwd: string): ValidationReport {
+	const agents = allAgents(discoverAgents(cwd));
+	const teams = allTeams(discoverTeams(cwd));
+	const workflows = allWorkflows(discoverWorkflows(cwd));
+	const agentNames = new Set(agents.map((agent) => agent.name));
+	const workflowNames = new Set(workflows.map((workflow) => workflow.name));
+	const issues: ValidationIssue[] = [];
+
+	for (const agent of agents) {
+		const modelValues = [agent.model, ...(agent.fallbackModels ?? [])].filter((value): value is string => typeof value === "string" && value.length > 0);
+		for (const model of modelValues) {
+			if (/\s/.test(model)) {
+				issues.push({ level: "warning", resource: `agent:${agent.name}`, message: `Model reference '${model}' contains whitespace.` });
+			}
+			if (model.includes("/") && model.split("/").some((part) => part.trim() === "")) {
+				issues.push({ level: "warning", resource: `agent:${agent.name}`, message: `Model reference '${model}' has an empty provider/model segment.` });
+			}
+		}
+	}
+
+	for (const team of teams) {
+		for (const role of team.roles) {
+			if (!agentNames.has(role.agent)) {
+				issues.push({ level: "error", resource: `team:${team.name}`, message: `Role '${role.name}' references unknown agent '${role.agent}'.` });
+			}
+		}
+		if (team.defaultWorkflow && !workflowNames.has(team.defaultWorkflow)) {
+			issues.push({ level: "error", resource: `team:${team.name}`, message: `defaultWorkflow references unknown workflow '${team.defaultWorkflow}'.` });
+		}
+		const workflow = workflows.find((candidate) => candidate.name === team.defaultWorkflow);
+		if (workflow) {
+			for (const error of validateWorkflowForTeam(workflow, team)) {
+				issues.push({ level: "error", resource: `workflow:${workflow.name}`, message: `Team '${team.name}': ${error}` });
+			}
+		}
+	}
+
+	for (const workflow of workflows) {
+		if (workflow.steps.length === 0) {
+			issues.push({ level: "warning", resource: `workflow:${workflow.name}`, message: "Workflow has no steps." });
+		}
+	}
+
+	return { issues, agents: agents.length, teams: teams.length, workflows: workflows.length };
+}
+
+export function formatValidationReport(report: ValidationReport): string {
+	const lines = [
+		"pi-crew resource validation:",
+		`Agents: ${report.agents}`,
+		`Teams: ${report.teams}`,
+		`Workflows: ${report.workflows}`,
+		`Issues: ${report.issues.length}`,
+	];
+	if (report.issues.length > 0) {
+		lines.push("", ...report.issues.map((issue) => `- ${issue.level.toUpperCase()} ${issue.resource}: ${issue.message}`));
+	}
+	return lines.join("\n");
+}

package/src/prompt/prompt-runtime.ts

@@ -0,0 +1,58 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export const PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV = "PI_TEAMS_INHERIT_PROJECT_CONTEXT";
+export const PI_TEAMS_INHERIT_SKILLS_ENV = "PI_TEAMS_INHERIT_SKILLS";
+
+const PROJECT_CONTEXT_HEADER = "\n\n# Project Context\n\nProject-specific instructions and guidelines:\n\n";
+const SKILLS_HEADER = "\n\nThe following skills provide specialized instructions for specific tasks.";
+const DATE_HEADER = "\nCurrent date:";
+
+function readBooleanEnv(name: string): boolean | undefined {
+	const value = process.env[name];
+	if (value === undefined) return undefined;
+	return value !== "0";
+}
+
+function findSectionEnd(prompt: string, startIndex: number, nextHeaders: string[]): number {
+	let endIndex = prompt.length;
+	for (const header of nextHeaders) {
+		const index = prompt.indexOf(header, startIndex);
+		if (index !== -1 && index < endIndex) endIndex = index;
+	}
+	return endIndex;
+}
+
+export function stripProjectContext(prompt: string): string {
+	const startIndex = prompt.indexOf(PROJECT_CONTEXT_HEADER);
+	if (startIndex === -1) return prompt;
+	const endIndex = findSectionEnd(prompt, startIndex + PROJECT_CONTEXT_HEADER.length, [SKILLS_HEADER, DATE_HEADER]);
+	return `${prompt.slice(0, startIndex)}${prompt.slice(endIndex)}`;
+}
+
+export function stripInheritedSkills(prompt: string): string {
+	const startIndex = prompt.indexOf(SKILLS_HEADER);
+	if (startIndex === -1) return prompt;
+	const endIndex = findSectionEnd(prompt, startIndex + SKILLS_HEADER.length, [DATE_HEADER]);
+	return `${prompt.slice(0, startIndex)}${prompt.slice(endIndex)}`;
+}
+
+export function rewriteTeamWorkerPrompt(prompt: string, options: { inheritProjectContext: boolean; inheritSkills: boolean }): string {
+	let rewritten = prompt;
+	if (!options.inheritProjectContext) rewritten = stripProjectContext(rewritten);
+	if (!options.inheritSkills) rewritten = stripInheritedSkills(rewritten);
+	return rewritten;
+}
+
+export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", (event) => {
+		const inheritProjectContext = readBooleanEnv(PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV);
+		const inheritSkills = readBooleanEnv(PI_TEAMS_INHERIT_SKILLS_ENV);
+		if (inheritProjectContext === undefined && inheritSkills === undefined) return;
+		const rewritten = rewriteTeamWorkerPrompt(event.systemPrompt, {
+			inheritProjectContext: inheritProjectContext ?? true,
+			inheritSkills: inheritSkills ?? true,
+		});
+		if (rewritten === event.systemPrompt) return;
+		return { systemPrompt: rewritten };
+	});
+}

package/src/runtime/async-runner.ts

@@ -0,0 +1,26 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { TeamRunManifest } from "../state/types.ts";
+
+export interface SpawnBackgroundTeamRunResult {
+	pid?: number;
+	logPath: string;
+}
+
+export function spawnBackgroundTeamRun(manifest: TeamRunManifest): SpawnBackgroundTeamRunResult {
+	const runnerPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "background-runner.ts");
+	const logPath = path.join(manifest.stateRoot, "background.log");
+	fs.mkdirSync(manifest.stateRoot, { recursive: true });
+	const logFd = fs.openSync(logPath, "a");
+	const child = spawn(process.execPath, ["--experimental-strip-types", runnerPath, "--cwd", manifest.cwd, "--run-id", manifest.runId], {
+		cwd: manifest.cwd,
+		detached: true,
+		stdio: ["ignore", logFd, logFd],
+		env: { ...process.env },
+	});
+	child.unref();
+	fs.closeSync(logFd);
+	return { pid: child.pid, logPath };
+}

package/src/runtime/background-runner.ts

@@ -0,0 +1,43 @@
+import { allAgents, discoverAgents } from "../agents/discover-agents.ts";
+import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { loadRunManifestById, updateRunStatus } from "../state/state-store.ts";
+import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
+import { executeTeamRun } from "./team-runner.ts";
+
+function argValue(name: string): string | undefined {
+	const index = process.argv.indexOf(name);
+	if (index === -1) return undefined;
+	return process.argv[index + 1];
+}
+
+async function main(): Promise<void> {
+	const cwd = argValue("--cwd");
+	const runId = argValue("--run-id");
+	if (!cwd || !runId) throw new Error("Usage: background-runner.ts --cwd <cwd> --run-id <runId>");
+
+	const loaded = loadRunManifestById(cwd, runId);
+	if (!loaded) throw new Error(`Run '${runId}' not found.`);
+	let { manifest, tasks } = loaded;
+	appendEvent(manifest.eventsPath, { type: "async.started", runId: manifest.runId, data: { pid: process.pid } });
+
+	try {
+		const team = allTeams(discoverTeams(cwd)).find((candidate) => candidate.name === manifest.team);
+		if (!team) throw new Error(`Team '${manifest.team}' not found.`);
+		const workflow = allWorkflows(discoverWorkflows(cwd)).find((candidate) => candidate.name === manifest.workflow);
+		if (!workflow) throw new Error(`Workflow '${manifest.workflow ?? ""}' not found.`);
+		const agents = allAgents(discoverAgents(cwd));
+		const executeWorkers = process.env.PI_TEAMS_EXECUTE_WORKERS === "1";
+		const result = await executeTeamRun({ manifest, tasks, team, workflow, agents, executeWorkers });
+		manifest = result.manifest;
+		tasks = result.tasks;
+		appendEvent(manifest.eventsPath, { type: "async.completed", runId: manifest.runId, data: { status: manifest.status, tasks: tasks.length } });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		manifest = updateRunStatus(manifest, "failed", message);
+		appendEvent(manifest.eventsPath, { type: "async.failed", runId: manifest.runId, message });
+		process.exitCode = 1;
+	}
+}
+
+await main();

package/src/runtime/child-pi.ts

@@ -0,0 +1,75 @@
+import { spawn } from "node:child_process";
+import type { AgentConfig } from "../agents/agent-config.ts";
+import { buildPiWorkerArgs, cleanupTempDir } from "./pi-args.ts";
+import { getPiSpawnCommand } from "./pi-spawn.ts";
+
+export interface ChildPiRunInput {
+	cwd: string;
+	task: string;
+	agent: AgentConfig;
+	model?: string;
+	signal?: AbortSignal;
+}
+
+export interface ChildPiRunResult {
+	exitCode: number | null;
+	stdout: string;
+	stderr: string;
+	error?: string;
+}
+
+export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResult> {
+	const mock = process.env.PI_TEAMS_MOCK_CHILD_PI;
+	if (mock) {
+		if (mock === "success") return { exitCode: 0, stdout: `Mock child Pi success for ${input.agent.name}\n`, stderr: "" };
+		if (mock === "json-success") return { exitCode: 0, stdout: `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text: `Mock JSON success for ${input.agent.name}` }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`, stderr: "" };
+		if (mock === "retryable-failure") return { exitCode: 1, stdout: "", stderr: "rate limit: mock failure" };
+		return { exitCode: 1, stdout: "", stderr: `mock failure: ${mock}` };
+	}
+	const built = buildPiWorkerArgs({ task: input.task, agent: input.agent, model: input.model, sessionEnabled: false });
+	const spawnSpec = getPiSpawnCommand(built.args);
+	try {
+		return await new Promise<ChildPiRunResult>((resolve) => {
+			const child = spawn(spawnSpec.command, spawnSpec.args, {
+				cwd: input.cwd,
+				env: { ...process.env, ...built.env },
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			let stdout = "";
+			let stderr = "";
+			let settled = false;
+
+			const settle = (result: ChildPiRunResult): void => {
+				if (settled) return;
+				settled = true;
+				cleanupTempDir(built.tempDir);
+				resolve(result);
+			};
+
+			const abort = (): void => {
+				try {
+					child.kill(process.platform === "win32" ? undefined : "SIGTERM");
+				} catch {
+					// Ignore kill races.
+				}
+			};
+
+			input.signal?.addEventListener("abort", abort, { once: true });
+			child.stdout?.on("data", (chunk: Buffer) => {
+				stdout += chunk.toString("utf-8");
+			});
+			child.stderr?.on("data", (chunk: Buffer) => {
+				stderr += chunk.toString("utf-8");
+			});
+			child.on("error", (error) => {
+				settle({ exitCode: null, stdout, stderr, error: error.message });
+			});
+			child.on("close", (exitCode) => {
+				input.signal?.removeEventListener("abort", abort);
+				settle({ exitCode, stdout, stderr });
+			});
+		});
+	} finally {
+		cleanupTempDir(built.tempDir);
+	}
+}

package/src/runtime/model-fallback.ts

@@ -0,0 +1,101 @@
+export interface AvailableModelInfo {
+	provider: string;
+	id: string;
+	fullId: string;
+}
+
+export interface ModelAttemptSummary {
+	model: string;
+	success: boolean;
+	exitCode?: number | null;
+	error?: string;
+}
+
+export function splitThinkingSuffix(model: string): { baseModel: string; thinkingSuffix: string } {
+	const colonIdx = model.lastIndexOf(":");
+	if (colonIdx === -1) return { baseModel: model, thinkingSuffix: "" };
+	return {
+		baseModel: model.substring(0, colonIdx),
+		thinkingSuffix: model.substring(colonIdx),
+	};
+}
+
+export function resolveModelCandidate(
+	model: string | undefined,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string | undefined {
+	if (!model) return undefined;
+	if (model.includes("/")) return model;
+	if (!availableModels || availableModels.length === 0) return model;
+
+	const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
+	const matches = availableModels.filter((entry) => entry.id === baseModel);
+	if (preferredProvider) {
+		const preferredMatch = matches.find((entry) => entry.provider === preferredProvider);
+		if (preferredMatch) return `${preferredMatch.fullId}${thinkingSuffix}`;
+	}
+	if (matches.length !== 1) return model;
+	return `${matches[0]!.fullId}${thinkingSuffix}`;
+}
+
+const RETRYABLE_MODEL_FAILURE_PATTERNS = [
+	/rate\s*limit/i,
+	/too many requests/i,
+	/\b429\b/,
+	/quota/i,
+	/billing/i,
+	/credit/i,
+	/auth(?:entication)?/i,
+	/unauthori[sz]ed/i,
+	/forbidden/i,
+	/api key/i,
+	/token expired/i,
+	/invalid key/i,
+	/provider.*unavailable/i,
+	/model.*unavailable/i,
+	/model.*disabled/i,
+	/model.*not found/i,
+	/unknown model/i,
+	/overloaded/i,
+	/service unavailable/i,
+	/temporar(?:ily)? unavailable/i,
+	/connection refused/i,
+	/fetch failed/i,
+	/network error/i,
+	/socket hang up/i,
+	/upstream/i,
+	/timed? out/i,
+	/timeout/i,
+	/\b502\b/,
+	/\b503\b/,
+	/\b504\b/,
+];
+
+export function isRetryableModelFailure(error: string | undefined): boolean {
+	if (!error) return false;
+	return RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(error));
+}
+
+export function formatModelAttemptNote(attempt: ModelAttemptSummary, nextModel?: string): string {
+	const failure = attempt.error?.trim() || `exit ${attempt.exitCode ?? 1}`;
+	return nextModel ? `[fallback] ${attempt.model} failed: ${failure}. Retrying with ${nextModel}.` : `[fallback] ${attempt.model} failed: ${failure}.`;
+}
+
+export function buildModelCandidates(
+	primaryModel: string | undefined,
+	fallbackModels: string[] | undefined,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string[] {
+	const seen = new Set<string>();
+	const candidates: string[] = [];
+	for (const raw of [primaryModel, ...(fallbackModels ?? [])]) {
+		if (!raw) continue;
+		const normalized = resolveModelCandidate(raw.trim(), availableModels, preferredProvider);
+		if (!normalized || seen.has(normalized)) continue;
+		seen.add(normalized);
+		candidates.push(normalized);
+	}
+	return candidates;
+}

package/src/runtime/pi-args.ts

@@ -0,0 +1,81 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AgentConfig } from "../agents/agent-config.ts";
+
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
+const PROMPT_RUNTIME_EXTENSION_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "prompt", "prompt-runtime.ts");
+const TASK_ARG_LIMIT = 8000;
+
+export interface BuildPiWorkerArgsInput {
+	task: string;
+	agent: AgentConfig;
+	model?: string;
+	sessionEnabled?: boolean;
+}
+
+export interface BuildPiWorkerArgsResult {
+	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 buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerArgsResult {
+	const args = ["--mode", "json", "-p"];
+	if (input.sessionEnabled === false) args.push("--no-session");
+
+	const model = applyThinkingSuffix(input.model ?? input.agent.model, input.agent.thinking);
+	if (model) args.push("--model", model);
+
+	if (input.agent.tools?.length) args.push("--tools", input.agent.tools.join(","));
+	if (input.agent.extensions !== undefined) {
+		args.push("--no-extensions");
+		for (const extension of [PROMPT_RUNTIME_EXTENSION_PATH, ...input.agent.extensions]) args.push("--extension", extension);
+	} else {
+		args.push("--extension", PROMPT_RUNTIME_EXTENSION_PATH);
+	}
+	if (!input.agent.inheritSkills) args.push("--no-skills");
+
+	let tempDir: string | undefined;
+	if (input.agent.systemPrompt) {
+		tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-crew-"));
+		const promptPath = path.join(tempDir, `${input.agent.name.replace(/[^\w.-]/g, "_")}.md`);
+		fs.writeFileSync(promptPath, input.agent.systemPrompt, { mode: 0o600 });
+		args.push(input.agent.systemPromptMode === "append" ? "--append-system-prompt" : "--system-prompt", promptPath);
+	}
+
+	if (input.task.length > TASK_ARG_LIMIT) {
+		if (!tempDir) tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-crew-"));
+		const taskPath = path.join(tempDir, "task.md");
+		fs.writeFileSync(taskPath, input.task, { mode: 0o600 });
+		args.push(`@${taskPath}`);
+	} else {
+		args.push(`Task: ${input.task}`);
+	}
+
+	return {
+		args,
+		env: {
+			PI_TEAMS_INHERIT_PROJECT_CONTEXT: input.agent.inheritProjectContext ? "1" : "0",
+			PI_TEAMS_INHERIT_SKILLS: input.agent.inheritSkills ? "1" : "0",
+		},
+		tempDir,
+	};
+}
+
+export function cleanupTempDir(tempDir: string | undefined): void {
+	if (!tempDir) return;
+	try {
+		fs.rmSync(tempDir, { recursive: true, force: true });
+	} catch {
+		// Best effort.
+	}
+}

package/src/runtime/pi-json-output.ts

@@ -0,0 +1,110 @@
+export interface ParsedPiUsage {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+	cost?: number;
+	turns?: number;
+}
+
+export interface ParsedPiJsonOutput {
+	jsonEvents: number;
+	textEvents: string[];
+	finalText?: string;
+	usage?: ParsedPiUsage;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function numberField(obj: Record<string, unknown>, keys: string[]): number | undefined {
+	for (const key of keys) {
+		const value = obj[key];
+		if (typeof value === "number" && Number.isFinite(value)) return value;
+	}
+	return undefined;
+}
+
+function mergeUsage(target: ParsedPiUsage, source: ParsedPiUsage): ParsedPiUsage {
+	return {
+		input: source.input ?? target.input,
+		output: source.output ?? target.output,
+		cacheRead: source.cacheRead ?? target.cacheRead,
+		cacheWrite: source.cacheWrite ?? target.cacheWrite,
+		cost: source.cost ?? target.cost,
+		turns: source.turns ?? target.turns,
+	};
+}
+
+function extractUsage(value: unknown): ParsedPiUsage | undefined {
+	const obj = asRecord(value);
+	if (!obj) return undefined;
+	const direct: ParsedPiUsage = {
+		input: numberField(obj, ["input", "inputTokens", "input_tokens"]),
+		output: numberField(obj, ["output", "outputTokens", "output_tokens"]),
+		cacheRead: numberField(obj, ["cacheRead", "cache_read", "cacheReadTokens", "cache_read_tokens"]),
+		cacheWrite: numberField(obj, ["cacheWrite", "cache_write", "cacheWriteTokens", "cache_write_tokens"]),
+		cost: numberField(obj, ["cost", "costUsd", "cost_usd"]),
+		turns: numberField(obj, ["turns", "turnCount", "turn_count"]),
+	};
+	if (Object.values(direct).some((entry) => entry !== undefined)) return direct;
+	for (const key of ["usage", "tokenUsage", "tokens", "stats"]) {
+		const nested = extractUsage(obj[key]);
+		if (nested) return nested;
+	}
+	return undefined;
+}
+
+function textFromContent(content: unknown): string[] {
+	if (typeof content === "string") return [content];
+	if (!Array.isArray(content)) return [];
+	const text: string[] = [];
+	for (const part of content) {
+		const obj = asRecord(part);
+		if (!obj) continue;
+		if (obj.type === "text" && typeof obj.text === "string") text.push(obj.text);
+		else if (typeof obj.content === "string") text.push(obj.content);
+	}
+	return text;
+}
+
+function extractText(value: unknown): string[] {
+	const obj = asRecord(value);
+	if (!obj) return [];
+	const text: string[] = [];
+	if (typeof obj.text === "string") text.push(obj.text);
+	if (typeof obj.output === "string") text.push(obj.output);
+	if (typeof obj.finalOutput === "string") text.push(obj.finalOutput);
+	if (typeof obj.final_output === "string") text.push(obj.final_output);
+	text.push(...textFromContent(obj.content));
+	const message = asRecord(obj.message);
+	if (message) text.push(...textFromContent(message.content));
+	return text.filter((entry) => entry.trim().length > 0);
+}
+
+export function parsePiJsonOutput(stdout: string): ParsedPiJsonOutput {
+	let jsonEvents = 0;
+	const textEvents: string[] = [];
+	let usage: ParsedPiUsage | undefined;
+	for (const line of stdout.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		let event: unknown;
+		try {
+			event = JSON.parse(trimmed) as unknown;
+		} catch {
+			continue;
+		}
+		jsonEvents++;
+		textEvents.push(...extractText(event));
+		const eventUsage = extractUsage(event);
+		if (eventUsage) usage = mergeUsage(usage ?? {}, eventUsage);
+	}
+	return {
+		jsonEvents,
+		textEvents,
+		finalText: textEvents.length > 0 ? textEvents[textEvents.length - 1] : undefined,
+		usage,
+	};
+}

package/src/runtime/pi-spawn.ts

@@ -0,0 +1,96 @@
+import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as path from "node:path";
+
+export interface PiSpawnCommand {
+	command: string;
+	args: string[];
+}
+
+function isRunnableNodeScript(filePath: string): boolean {
+	return fs.existsSync(filePath) && /\.(?:mjs|cjs|js)$/i.test(filePath);
+}
+
+function resolvePiPackageRoot(): string | undefined {
+	try {
+		const entry = process.argv[1];
+		if (!entry) return undefined;
+		let dir = path.dirname(fs.realpathSync(entry));
+		while (dir !== path.dirname(dir)) {
+			try {
+				const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8")) as { name?: string };
+				if (pkg.name === "@mariozechner/pi-coding-agent") return dir;
+			} catch {
+				// Continue walking upward.
+			}
+			dir = path.dirname(dir);
+		}
+	} catch {
+		return undefined;
+	}
+	return undefined;
+}
+
+function packageBinScript(packageJsonPath: string): string | undefined {
+	try {
+		const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) as { bin?: string | Record<string, string> };
+		const binPath = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.pi ?? Object.values(pkg.bin ?? {})[0];
+		if (!binPath) return undefined;
+		const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
+		return isRunnableNodeScript(candidate) ? candidate : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function findPiPackageJsonFrom(startDir: string): string | undefined {
+	let dir = startDir;
+	while (dir !== path.dirname(dir)) {
+		const direct = path.join(dir, "package.json");
+		try {
+			const pkg = JSON.parse(fs.readFileSync(direct, "utf-8")) as { name?: string };
+			if (pkg.name === "@mariozechner/pi-coding-agent") return direct;
+		} catch {
+			// Continue searching upward and in node_modules.
+		}
+		const dependency = path.join(dir, "node_modules", "@mariozechner", "pi-coding-agent", "package.json");
+		if (fs.existsSync(dependency)) return dependency;
+		dir = path.dirname(dir);
+	}
+	return undefined;
+}
+
+function resolvePiCliScript(): string | undefined {
+	const explicit = process.env.PI_TEAMS_PI_BIN?.trim();
+	if (explicit && isRunnableNodeScript(explicit)) return explicit;
+
+	const argv1 = process.argv[1];
+	if (argv1) {
+		const argvPath = path.isAbsolute(argv1) ? argv1 : path.resolve(argv1);
+		if (isRunnableNodeScript(argvPath)) return argvPath;
+	}
+
+	const roots = [
+		resolvePiPackageRoot(),
+		process.env.APPDATA ? path.join(process.env.APPDATA, "npm", "node_modules", "@mariozechner", "pi-coding-agent") : undefined,
+		path.dirname(fileURLToPath(import.meta.url)),
+		process.cwd(),
+	].filter((entry): entry is string => Boolean(entry));
+
+	for (const root of roots) {
+		const packageJsonPath = root.endsWith("package.json") ? root : findPiPackageJsonFrom(root) ?? path.join(root, "package.json");
+		const script = packageBinScript(packageJsonPath);
+		if (script) return script;
+	}
+	return undefined;
+}
+
+export function getPiSpawnCommand(args: string[]): PiSpawnCommand {
+	const explicit = process.env.PI_TEAMS_PI_BIN?.trim();
+	if (explicit && fs.existsSync(explicit) && !isRunnableNodeScript(explicit)) return { command: explicit, args };
+	if (process.platform === "win32") {
+		const script = resolvePiCliScript();
+		if (script) return { command: process.execPath, args: [script, ...args] };
+	}
+	return { command: "pi", args };
+}