pi-crew 0.1.51 → 0.2.0

package/src/runtime/phase-progress.ts

@@ -0,0 +1,217 @@
+/**
+ * Phase progress calculator for pi-crew runs.
+ *
+ * Groups tasks by their adaptive phase metadata and computes per-phase
+ * and overall progress metrics including estimated remaining time.
+ */
+import type { TeamTaskState } from "../state/types.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PhaseInfo {
+	/** Phase name, e.g. "explore", "plan", "execute", "verify" */
+	phase: string;
+	/** 0-based index among all phases */
+	index: number;
+	/** Total tasks in this phase */
+	total: number;
+	/** Completed tasks */
+	completed: number;
+	/** Failed tasks */
+	failed: number;
+	/** Currently running tasks */
+	running: number;
+	/** Still queued (not started) */
+	queued: number;
+	/** (completed + failed) / total * 100, rounded to 1 decimal */
+	percentage: number;
+}
+
+export interface RunProgress {
+	/** Breakdown per phase, in phase order */
+	phases: PhaseInfo[];
+	/** Overall (completed + failed) / total * 100 */
+	overallPercentage: number;
+	/** Phase that currently has running or queued tasks, or null */
+	currentPhase: string | null;
+	/** Estimated remaining ms based on avg task duration × remaining tasks */
+	estimatedRemainingMs: number;
+	/** Total task count */
+	totalTasks: number;
+	/** Completed task count */
+	completedTasks: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled", "skipped"]);
+
+/**
+ * Extract the phase label for a task.
+ *
+ * Priority:
+ * 1. `task.adaptive.phase` (set by adaptive planner)
+ * 2. Infer from stepId prefix: `adaptive-<phaseIndex>-...` → use the numeric phase index
+ * 3. Fallback: `"default"`
+ */
+function extractPhase(task: TeamTaskState): string {
+	if (task.adaptive?.phase) return task.adaptive.phase;
+	if (task.stepId?.startsWith("adaptive-")) {
+		const parts = task.stepId.split("-");
+		// adaptive-<phaseIndex>-<taskIndex>-<role> → parts[1] is the phase index
+		if (parts.length >= 3 && parts[1]) return parts[1];
+	}
+	return "default";
+}
+
+/**
+ * Compute task duration in ms from startedAt → finishedAt.
+ * Returns undefined if timestamps are missing or invalid.
+ */
+function taskDurationMs(task: TeamTaskState): number | undefined {
+	if (!task.startedAt || !task.finishedAt) return undefined;
+	const start = new Date(task.startedAt).getTime();
+	const end = new Date(task.finishedAt).getTime();
+	const duration = end - start;
+	return Number.isFinite(duration) && duration > 0 ? duration : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute phase-aware progress for a set of tasks.
+ *
+ * Groups tasks by phase, calculates per-phase and overall percentages,
+ * and estimates remaining time from the average duration of completed tasks.
+ */
+export function computePhaseProgress(tasks: TeamTaskState[]): RunProgress {
+	if (tasks.length === 0) {
+		return {
+			phases: [],
+			overallPercentage: 0,
+			currentPhase: null,
+			estimatedRemainingMs: 0,
+			totalTasks: 0,
+			completedTasks: 0,
+		};
+	}
+
+	// Preserve insertion order of first-seen phase
+	const phaseOrder: string[] = [];
+	const phaseGroups = new Map<string, TeamTaskState[]>();
+
+	for (const task of tasks) {
+		const phase = extractPhase(task);
+		if (!phaseGroups.has(phase)) {
+			phaseGroups.set(phase, []);
+			phaseOrder.push(phase);
+		}
+		phaseGroups.get(phase)!.push(task);
+	}
+
+	let totalCompleted = 0;
+	let totalTerminal = 0;
+	let totalDurationSum = 0;
+	let totalDurationCount = 0;
+	let currentPhase: string | null = null;
+
+	const phases: PhaseInfo[] = phaseOrder.map((phase, index) => {
+		const group = phaseGroups.get(phase)!;
+		let completed = 0;
+		let failed = 0;
+		let running = 0;
+		let queued = 0;
+		let hasRunningOrQueued = false;
+
+		for (const task of group) {
+			const status = task.status;
+			if (status === "completed") {
+				completed++;
+				totalCompleted++;
+				totalTerminal++;
+				const dur = taskDurationMs(task);
+				if (dur !== undefined) {
+					totalDurationSum += dur;
+					totalDurationCount++;
+				}
+			} else if (status === "failed") {
+				failed++;
+				totalTerminal++;
+				const dur = taskDurationMs(task);
+				if (dur !== undefined) {
+					totalDurationSum += dur;
+					totalDurationCount++;
+				}
+			} else if (status === "running" || status === "waiting") {
+				running++;
+				hasRunningOrQueued = true;
+			} else if (status === "queued") {
+				queued++;
+				hasRunningOrQueued = true;
+			}
+			// cancelled, skipped → counted in total but not completed/failed
+		}
+
+		if (hasRunningOrQueued && currentPhase === null) {
+			currentPhase = phase;
+		}
+
+		const terminal = completed + failed;
+		const percentage = group.length > 0 ? Math.round((terminal / group.length) * 1000) / 10 : 0;
+
+		return {
+			phase,
+			index,
+			total: group.length,
+			completed,
+			failed,
+			running,
+			queued,
+			percentage,
+		};
+	});
+
+	const overallPercentage = tasks.length > 0 ? Math.round((totalTerminal / tasks.length) * 1000) / 10 : 0;
+
+	// Estimate remaining time: avg duration × remaining non-terminal tasks
+	const remainingTasks = tasks.length - totalTerminal;
+	let estimatedRemainingMs = 0;
+	if (totalDurationCount > 0 && remainingTasks > 0) {
+		const avgDuration = totalDurationSum / totalDurationCount;
+		estimatedRemainingMs = Math.round(avgDuration * remainingTasks);
+	}
+
+	return {
+		phases,
+		overallPercentage,
+		currentPhase,
+		estimatedRemainingMs,
+		totalTasks: tasks.length,
+		completedTasks: totalCompleted,
+	};
+}
+
+/**
+ * Format a human-readable phase progress line.
+ *
+ * Example: "Phase 2/4 execute: 60.0% (3/5)"
+ * Returns empty string when there are no phases.
+ */
+export function formatPhaseProgressLine(runProgress: RunProgress): string {
+	if (runProgress.phases.length === 0) return "";
+	const current = runProgress.currentPhase;
+	if (!current) {
+		// All done — show summary
+		return `All ${runProgress.phases.length} phases done: ${runProgress.overallPercentage}% (${runProgress.completedTasks}/${runProgress.totalTasks})`;
+	}
+	const currentPhaseInfo = runProgress.phases.find((p) => p.phase === current);
+	if (!currentPhaseInfo) return `${runProgress.overallPercentage}% done`;
+	const done = currentPhaseInfo.completed + currentPhaseInfo.failed;
+	return `Phase ${currentPhaseInfo.index + 1}/${runProgress.phases.length} ${current}: ${currentPhaseInfo.percentage}% (${done}/${currentPhaseInfo.total})`;
+}

package/src/runtime/pi-args.ts

@@ -57,6 +57,33 @@ export function checkCrewDepth(inputMaxDepth?: number, env: NodeJS.ProcessEnv =
 	return { depth, maxDepth, blocked: depth >= maxDepth };
 }
 
+/**
+ * Create a safe temp directory with symlink protection.
+ * 1. mkdtempSync to create the directory
+ * 2. lstatSync to verify it is not a symlink (TOCTOU safety)
+ * 3. realpathSync to resolve the canonical path
+ */
+function createSafeTempDir(base: string, prefix: string): string {
+	if (!fs.existsSync(base)) fs.mkdirSync(base, { recursive: true });
+	// Verify base dir is not a symlink (TOCTOU safety)
+	const baseStat = fs.lstatSync(base);
+	if (baseStat.isSymbolicLink()) throw new Error("Refusing to create temp dir in symlinked base: " + base);
+	// Resolve base to canonical path before joining
+	const resolvedBase = fs.realpathSync(base);
+	const rawTempDir = fs.mkdtempSync(path.join(resolvedBase, prefix));
+	try {
+		const stat = fs.lstatSync(rawTempDir);
+		if (stat.isSymbolicLink()) throw new Error("temp dir is a symlink");
+	} catch (e) {
+		if (e instanceof Error && e.message.includes("symlink")) {
+			fs.rmSync(rawTempDir, { recursive: true, force: true });
+			throw new Error("Refusing to use symlinked temp directory.");
+		}
+		throw e;
+	}
+	return fs.realpathSync(rawTempDir);
+}
+
 export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerArgsResult {
 	const args = ["--mode", "json", "-p"];
 	if (input.sessionEnabled === false) args.push("--no-session");
@@ -83,23 +110,23 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 
 	let tempDir: string | undefined;
 	if (input.agent.systemPrompt) {
-		tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `pi-crew-${process.pid}-`));
-		// Verify temp dir is not a symlink (TOCTOU safety)
-		try {
-			const stat = fs.lstatSync(tempDir);
-			if (stat.isSymbolicLink()) throw new Error("temp dir is a symlink");
-		} catch {
-			fs.rmSync(tempDir, { recursive: true, force: true });
-			tempDir = undefined;
-			throw new Error("Refusing to use symlinked temp directory.");
-		}
+		// On Windows, prefer a subdirectory within the user's profile over system temp
+		const tmpBase = process.platform === "win32" && os.homedir()
+			? path.join(os.homedir(), ".pi-crew", "tmp")
+			: os.tmpdir();
+		tempDir = createSafeTempDir(tmpBase, `pi-crew-${process.pid}-`);
 		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-${process.pid}-`));
+		if (!tempDir) {
+			const tmpBase = process.platform === "win32" && os.homedir()
+				? path.join(os.homedir(), ".pi-crew", "tmp")
+				: os.tmpdir();
+			tempDir = createSafeTempDir(tmpBase, `pi-crew-${process.pid}-`);
+		}
 		const taskPath = path.join(tempDir, "task.md");
 		fs.writeFileSync(taskPath, input.task, { mode: 0o600 });
 		args.push(`@${taskPath}`);

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

@@ -1,111 +1,111 @@
-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 message = asRecord(obj.message);
-	if (message?.role !== undefined && message.role !== "assistant") 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);
-	if (!message) text.push(...textFromContent(obj.content));
-	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,
-	};
-}
+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 message = asRecord(obj.message);
+	if (message?.role !== undefined && message.role !== "assistant") 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);
+	if (!message) text.push(...textFromContent(obj.content));
+	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

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 
@@ -11,6 +12,48 @@ function isRunnableNodeScript(filePath: string): boolean {
 	return fs.existsSync(filePath) && /\.(?:mjs|cjs|js)$/i.test(filePath);
 }
 
+/**
+ * Check that a resolved path is within known safe prefixes.
+ * Allowed prefixes: npm global bin (APPDATA/npm), project node_modules/.bin,
+ * or the current process's execPath directory.
+ */
+function isWithinAllowedPrefixes(resolvedPath: string): boolean {
+	const normalized = path.resolve(resolvedPath).toLowerCase();
+
+	const allowedPrefixes: string[] = [];
+
+	// Current process execPath directory (e.g. node installation)
+	try {
+		const execDir = path.dirname(fs.realpathSync.native(process.execPath));
+		allowedPrefixes.push(execDir.toLowerCase());
+	} catch { /* ignore */ }
+
+	// npm global bin via APPDATA
+	if (process.env.APPDATA) {
+		allowedPrefixes.push(path.join(process.env.APPDATA, "npm").toLowerCase());
+	}
+
+	// Project-local node_modules/.bin
+	try {
+		const projectBin = path.resolve("node_modules", ".bin");
+		allowedPrefixes.push(projectBin.toLowerCase());
+	} catch { /* ignore */ }
+
+	// User home npm-global
+	try {
+		const homeNpm = path.join(os.homedir(), ".npm-global", "bin");
+		allowedPrefixes.push(homeNpm.toLowerCase());
+	} catch { /* ignore */ }
+
+	// User home .local/bin
+	try {
+		const homeLocal = path.join(os.homedir(), ".local", "bin");
+		allowedPrefixes.push(homeLocal.toLowerCase());
+	} catch { /* ignore */ }
+
+	return allowedPrefixes.some((prefix) => normalized.startsWith(prefix));
+}
+
 function resolvePiPackageRoot(): string | undefined {
 	try {
 		const entry = process.argv[1];
@@ -61,9 +104,6 @@ function findPiPackageJsonFrom(startDir: string): string | 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);
@@ -87,14 +127,24 @@ function resolvePiCliScript(): string | undefined {
 
 function validateExplicitBin(explicit: string): string | undefined {
 	const resolved = path.resolve(explicit);
-	// Reject paths outside the project or user directories
-	if (resolved.includes("..")) return undefined;
 	if (!fs.existsSync(resolved)) return undefined;
+	// Reject paths outside allowed safe prefixes
+	if (!isWithinAllowedPrefixes(resolved)) {
+		throw new Error(
+			`PI_TEAMS_PI_BIN path '${resolved}' is outside allowed prefixes. ` +
+			`Allowed: npm global bin, project node_modules/.bin, APPDATA/npm, or process execPath directory.`,
+		);
+	}
 	// Reject if symlink points outside expected directories
 	try {
 		const real = fs.realpathSync(resolved);
-		if (real.includes("..")) return undefined;
-	} catch {
+		if (!isWithinAllowedPrefixes(real)) {
+			throw new Error(
+				`PI_TEAMS_PI_BIN symlink target '${real}' is outside allowed prefixes.`,
+			);
+		}
+	} catch (e) {
+		if (e instanceof Error && e.message.includes("allowed prefixes")) throw e;
 		return undefined;
 	}
 	return resolved;