pi-cohort 7.2.2 → 7.3.0

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

@@ -1,36 +1,8 @@
 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 (true) {
-		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;
-		}
-		if (dir === path.dirname(dir)) return undefined;
-		dir = path.dirname(dir);
-	}
-}
-
-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 {
-		// Non-launch package inspection is best-effort.
-		return undefined;
-	}
-}
-
 export interface PiRuntimeIdentity {
 	readonly nodeExecPath: string;
 	readonly piEntryPath: string;
@@ -90,13 +62,46 @@ function checkAvailability(file: string, executable: boolean): void {
 	}
 }
 
-export function capturePiRuntime(deps: { execPath?: string; argv1?: string } = {}): PiRuntimeIdentity {
-	const nodeExecPath = canonicalPath(deps.execPath ?? process.execPath, "Node executable");
-	const piEntryPath = canonicalPath(deps.argv1 ?? process.argv[1], "Pi entry");
-	checkAvailability(nodeExecPath, true);
+function identifyFromEntry(entry: string | undefined): { piEntryPath: string; piPackageRoot: string } {
+	const piEntryPath = canonicalPath(entry, "Pi entry");
 	checkAvailability(piEntryPath, false);
 	const piPackageRoot = canonicalPath(owningPackageRoot(piEntryPath), "Pi package root");
-	return { nodeExecPath, piEntryPath, piPackageRoot };
+	return { piEntryPath, piPackageRoot };
+}
+
+function identifyFromInstallRoot(installRoot: string): { piEntryPath: string; piPackageRoot: string } {
+	const piPackageRoot = canonicalPath(installRoot, "Pi installation root");
+	const manifest = path.join(piPackageRoot, "package.json");
+	let bin: unknown;
+	try {
+		const pkg = JSON.parse(fs.readFileSync(manifest, "utf-8"));
+		if (pkg?.name !== PI_CODING_AGENT_PACKAGE) {
+			throw new PiRuntimeLaunchError(`${manifest}: installation is not ${PI_CODING_AGENT_PACKAGE}`);
+		}
+		bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.pi;
+	} catch (error) {
+		if (error instanceof PiRuntimeLaunchError) throw error;
+		throw new PiRuntimeLaunchError(`${manifest}: ${String(error)}`);
+	}
+	if (typeof bin !== "string" || !bin) throw new PiRuntimeLaunchError(`${manifest}: missing declared Pi bin`);
+	const piEntryPath = canonicalPath(path.resolve(piPackageRoot, bin), "Declared Pi bin");
+	checkAvailability(piEntryPath, false);
+	const owner = canonicalPath(owningPackageRoot(piEntryPath), "Pi package root");
+	if (owner !== piPackageRoot) {
+		throw new PiRuntimeLaunchError(`${piEntryPath}: owning package ${owner} does not match installation ${piPackageRoot}`);
+	}
+	return { piEntryPath, piPackageRoot };
+}
+
+export function capturePiRuntime(deps: { execPath?: string; argv1?: string; installRoot?: string } = {}): PiRuntimeIdentity {
+	const nodeExecPath = canonicalPath(deps.execPath ?? process.execPath, "Node executable");
+	checkAvailability(nodeExecPath, true);
+	try {
+		return { nodeExecPath, ...identifyFromEntry(deps.argv1 ?? process.argv[1]) };
+	} catch (error) {
+		if (!(error instanceof PiRuntimeLaunchError) || deps.installRoot === undefined) throw error;
+		return { nodeExecPath, ...identifyFromInstallRoot(deps.installRoot) };
+	}
 }
 
 export function parsePiRuntime(value: unknown, source: string): PiRuntimeIdentity {

package/src/runs/shared/stop-conditions.ts

@@ -0,0 +1,100 @@
+import { isDynamicParallelStep, isParallelStep, type ChainStep, type SequentialStep } from "../../shared/settings.ts";
+import type { StopCondition, StopMatch, StopRecord } from "../../shared/types.ts";
+import { assertJsonPointer, DynamicFanoutError, resolveJsonPointer } from "./dynamic-fanout.ts";
+
+export interface StopEvaluationTask {
+	agent: string;
+	as?: string;
+	label?: string;
+	exitCode: number | null | undefined;
+	structuredOutput?: unknown;
+}
+
+/** Shape check for one condition value; `label` prefixes the message (`Chain step 1 stopOn`, `config.steps[0].stopOn`). */
+export function stopConditionShapeError(value: unknown, label: string): string | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return `${label} must be an object with path and in.`;
+	const record = value as Record<string, unknown>;
+	try {
+		if (typeof record.path !== "string") throw new DynamicFanoutError("Invalid JSON Pointer type.");
+		assertJsonPointer(record.path, `${label}.path`);
+	} catch (error) {
+		if (!(error instanceof DynamicFanoutError)) throw error;
+		return `${label}.path '${String(record.path)}' is not a JSON Pointer (must be "" or start with "/").`;
+	}
+	const list = record.in;
+	if (!Array.isArray(list) || list.length === 0 || list.some((member) => typeof member !== "string")) {
+		return `${label}.in must be a non-empty array of strings.`;
+	}
+	return undefined;
+}
+
+/** Pre-run check across a chain; returns the first error message or undefined. */
+export function validateStopConditions(steps: ChainStep[]): string | undefined {
+	for (let stepIndex = 0; stepIndex < steps.length; stepIndex++) {
+		const step = steps[stepIndex]!;
+		const stopOn = (step as { stopOn?: unknown }).stopOn;
+		if (stopOn === undefined) continue;
+		const stepNumber = stepIndex + 1;
+		const shapeError = stopConditionShapeError(stopOn, `Chain step ${stepNumber} stopOn`);
+		if (shapeError) return shapeError;
+		if (isParallelStep(step)) {
+			for (let taskIndex = 0; taskIndex < step.parallel.length; taskIndex++) {
+				if (!step.parallel[taskIndex]!.outputSchema) {
+					return `Chain step ${stepNumber} task ${taskIndex + 1} has no outputSchema; stopOn requires one on every task.`;
+				}
+			}
+			continue;
+		}
+		if (isDynamicParallelStep(step)) {
+			if (!step.parallel.outputSchema) return `Chain step ${stepNumber} task 1 has no outputSchema; stopOn requires one on every task.`;
+			continue;
+		}
+		if (!(step as SequentialStep).outputSchema) return `Chain step ${stepNumber} has stopOn but no outputSchema.`;
+	}
+	return undefined;
+}
+
+function resolveStringAt(value: unknown, pointer: string): string | undefined {
+	let resolved: unknown;
+	try {
+		resolved = resolveJsonPointer(value, pointer, "stopOn.path");
+	} catch (error) {
+		if (error instanceof DynamicFanoutError) return undefined;
+		throw error;
+	}
+	return typeof resolved === "string" ? resolved : undefined;
+}
+
+/** Matches in task order; only exit-0 tasks with structured output are considered. Never throws for data. */
+export function evaluateStopCondition(
+	condition: StopCondition,
+	stepIndex: number,
+	tasks: StopEvaluationTask[],
+	options: { sequential?: boolean } = {},
+): StopMatch[] {
+	const matches: StopMatch[] = [];
+	for (let taskIndex = 0; taskIndex < tasks.length; taskIndex++) {
+		const task = tasks[taskIndex]!;
+		if (task.exitCode !== 0 || task.structuredOutput === undefined) continue;
+		const value = resolveStringAt(task.structuredOutput, condition.path);
+		if (value === undefined || !condition.in.includes(value)) continue;
+		matches.push({
+			stepIndex,
+			...(options.sequential ? {} : { taskIndex }),
+			...(task.as ? { as: task.as } : {}),
+			...(task.label ? { label: task.label } : {}),
+			agent: task.agent,
+			value,
+		});
+	}
+	return matches;
+}
+
+export function buildStopRecord(condition: StopCondition, stepIndex: number, matches: StopMatch[]): StopRecord {
+	return { reason: "condition", stepIndex, condition, matches };
+}
+
+export function formatStopCondition(condition: StopCondition): string {
+	const pointer = condition.path === "" ? '""' : condition.path;
+	return `${pointer} in [${condition.in.join(", ")}]`;
+}

package/src/runs/shared/worktree.ts

@@ -18,7 +18,7 @@ interface WorktreeInfo {
 	syntheticPaths: string[];
 }
 
-interface WorktreeDiff {
+export interface WorktreeDiff {
 	index: number;
 	agent: string;
 	branch: string;
@@ -490,6 +490,12 @@ function hasWorktreeChanges(diff: WorktreeDiff): boolean {
 	return diff.filesChanged > 0 || diff.insertions > 0 || diff.deletions > 0 || diff.diffStat.trim().length > 0;
 }
 
+/** The patch a later chain step may reference: only a clean capture with real changes qualifies. */
+export function patchPathForDiff(diff: WorktreeDiff): string | undefined {
+	if (diff.captureError) return undefined;
+	return hasWorktreeChanges(diff) ? diff.patchPath : undefined;
+}
+
 export function createWorktrees(cwd: string, runId: string, count: number, options?: CreateWorktreesOptions): WorktreeSetup {
 	const repo = resolveRepoState(cwd);
 	const setupHook = resolveWorktreeSetupHook(repo.toplevel, options?.setupHook);

package/src/shared/formatters.ts

@@ -4,7 +4,8 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { Usage, SingleResult } from "./types.ts";
+import type { Usage, SingleResult, ChainTaskOutputEntry, StopRecord } from "./types.ts";
+import { formatStopCondition } from "../runs/shared/stop-conditions.ts";
 import type { ChainStep } from "./settings.ts";
 import { isDynamicParallelStep, isParallelStep } from "./settings.ts";
 import { splitKnownThinkingSuffix, THINKING_LEVELS } from "./model-info.ts";
@@ -52,15 +53,62 @@ export function formatDuration(ms: number): string {
 	return `${Math.floor(ms / 60000)}m${Math.floor((ms % 60000) / 1000)}s`;
 }
 
+export interface ChainSummaryOptions {
+	stop?: StopRecord;
+	outputs?: ChainTaskOutputEntry[];
+}
+
+function renderTaskHeading(entry: ChainTaskOutputEntry): string {
+	const asPart = entry.as ? `, as ${entry.as}` : "";
+	const base = `#### Task ${entry.taskIndex + 1} (${entry.agent}${asPart})`;
+	if (entry.exitCode === -1) return `${base} - skipped (fail-fast)`;
+	if (entry.exitCode !== 0) return `${base} - failed`;
+	return base;
+}
+
+/** `## Outputs`, grouped by step in execution order; skipped tasks get a heading only, failed tasks their error line. */
+export function buildChainOutputsSection(entries: ChainTaskOutputEntry[]): string {
+	const lines: string[] = ["## Outputs"];
+	let currentStep = -1;
+	for (const entry of entries) {
+		if (entry.stepIndex !== currentStep) {
+			currentStep = entry.stepIndex;
+			lines.push(`### Step ${currentStep + 1}`);
+		}
+		lines.push(renderTaskHeading(entry));
+		if (entry.exitCode === -1) continue;
+		if (entry.exitCode !== 0) {
+			lines.push(entry.error || "failed");
+			continue;
+		}
+		if (entry.text) lines.push(entry.text);
+		if (entry.structured !== undefined) lines.push("```json", JSON.stringify(entry.structured), "```");
+	}
+	return lines.join("\n");
+}
+
+export function buildChainStopSection(stop: StopRecord): string {
+	return `## Stop\n\`\`\`json\n${JSON.stringify(stop, null, 2)}\n\`\`\``;
+}
+
+function appendChainSections(text: string, options: ChainSummaryOptions | undefined): string {
+	if (!options) return text;
+	const sections: string[] = [];
+	if (options.stop) sections.push(buildChainStopSection(options.stop));
+	if (options.outputs) sections.push(buildChainOutputsSection(options.outputs));
+	return sections.length ? `${text}\n\n${sections.join("\n\n")}\n` : text;
+}
+
 /**
- * Build a summary string for a completed/failed chain
+ * Build a summary string for a completed/failed/stopped chain
  */
 export function buildChainSummary(
 	steps: ChainStep[],
 	results: SingleResult[],
 	chainDir: string,
-	status: "completed" | "failed",
+	status: "completed" | "failed" | "stopped",
 	failedStep?: { index: number; error: string },
+	options?: ChainSummaryOptions,
 ): string {
 	const stepNames = steps
 		.map((step) => (isParallelStep(step) ? `parallel[${step.parallel.length}]` : isDynamicParallelStep(step) ? `expand:${step.parallel.agent}` : step.agent))
@@ -77,20 +125,21 @@ export function buildChainSummary(
 	}
 	const skillsLine = allSkills.size > 0 ? `🔧 Skills: ${[...allSkills].join(", ")}` : "";
 
-	if (status === "completed") {
-		const stepWord = results.length === 1 ? "step" : "steps";
-		return `✅ Chain completed: ${stepNames} (${results.length} ${stepWord}, ${durationStr})${skillsLine ? `\n${skillsLine}` : ""}
-
-📋 Progress: ${hasProgress ? progressPath : "(none)"}
-📁 Artifacts: ${chainDir}`;
-	} else {
-		const stepInfo = failedStep ? ` at step ${failedStep.index + 1}` : "";
-		const errorInfo = failedStep?.error ? `: ${failedStep.error}` : "";
-		return `❌ Chain failed${stepInfo}${errorInfo}${skillsLine ? `\n${skillsLine}` : ""}
+	const footer = `\n\n📋 Progress: ${hasProgress ? progressPath : "(none)"}\n📁 Artifacts: ${chainDir}`;
 
-📋 Progress: ${hasProgress ? progressPath : "(none)"}
-📁 Artifacts: ${chainDir}`;
+	if (status === "stopped" && options?.stop) {
+		const header = `⏹ Chain stopped at step ${options.stop.stepIndex + 1}/${steps.length} by condition ${formatStopCondition(options.stop.condition)}`;
+		return appendChainSections(`${header}${skillsLine ? `\n${skillsLine}` : ""}${footer}`, options);
+	}
+	if (status === "completed" || status === "stopped") {
+		const stepWord = results.length === 1 ? "step" : "steps";
+		const header = `✅ Chain completed: ${stepNames} (${results.length} ${stepWord}, ${durationStr})${skillsLine ? `\n${skillsLine}` : ""}`;
+		return appendChainSections(`${header}${footer}`, options);
 	}
+	const stepInfo = failedStep ? ` at step ${failedStep.index + 1}` : "";
+	const errorInfo = failedStep?.error ? `: ${failedStep.error}` : "";
+	const header = `❌ Chain failed${stepInfo}${errorInfo}${skillsLine ? `\n${skillsLine}` : ""}`;
+	return appendChainSections(`${header}${footer}`, options);
 }
 
 /**

package/src/shared/settings.ts

@@ -6,7 +6,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentConfig } from "../agents/agents.ts";
 import { normalizeSkillInput } from "../agents/skills.ts";
-import { CHAIN_RUNS_DIR, type AcceptanceInput, type JsonSchemaObject, type OutputMode } from "./types.ts";
+import { CHAIN_RUNS_DIR, type AcceptanceInput, type JsonSchemaObject, type OutputMode, type StopCondition } from "./types.ts";
 const CHAIN_DIR_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
 const INITIAL_PROGRESS_CONTENT = "# Progress\n\n## Status\nIn Progress\n\n## Tasks\n\n## Files Changed\n\n## Notes\n";
 
@@ -56,6 +56,7 @@ export interface SequentialStep {
 	skill?: string | string[] | false;
 	model?: string;
 	acceptance?: AcceptanceInput;
+	stopOn?: StopCondition;
 }
 
 /** Parallel task item within a parallel step */
@@ -104,6 +105,7 @@ export interface DynamicParallelStep {
 	phase?: string;
 	label?: string;
 	acceptance?: AcceptanceInput;
+	stopOn?: StopCondition;
 }
 
 /** Parallel step: multiple agents running concurrently */
@@ -113,6 +115,7 @@ export interface ParallelStep {
 	failFast?: boolean;
 	worktree?: boolean;
 	cwd?: string;
+	stopOn?: StopCondition;
 }
 
 /** Union type for chain steps */

package/src/shared/types.ts

@@ -23,11 +23,47 @@ export type OutputMode = "inline" | "file-only";
 
 export type JsonSchemaObject = Record<string, unknown>;
 
+export interface StopCondition {
+	path: string;
+	in: string[];
+}
+
+export interface StopMatch {
+	stepIndex: number;
+	taskIndex?: number;
+	as?: string;
+	label?: string;
+	agent: string;
+	value: string;
+}
+
+export interface StopRecord {
+	reason: "condition";
+	stepIndex: number;
+	condition: StopCondition;
+	matches: StopMatch[];
+}
+
+/** One finished task's output as rendered in the chain result's `## Outputs` section. */
+export interface ChainTaskOutputEntry {
+	stepIndex: number;
+	taskIndex: number;
+	agent: string;
+	as?: string;
+	label?: string;
+	text: string;
+	structured?: unknown;
+	exitCode: number | null | undefined;
+	error?: string;
+}
+
 export interface ChainOutputMapEntry {
 	text: string;
 	structured?: unknown;
 	agent: string;
 	stepIndex: number;
+	patchPath?: string;
+	patchError?: string;
 }
 
 export type ChainOutputMap = Record<string, ChainOutputMapEntry>;
@@ -435,6 +471,7 @@ export interface Details {
 	currentStepIndex?: number;   // 0-indexed current step (for running chains)
 	workflowGraph?: WorkflowGraphSnapshot;
 	outputs?: ChainOutputMap;
+	stop?: StopRecord;
 }
 
 // ============================================================================

package/src/slash/slash-commands.ts

@@ -174,6 +174,7 @@ const mapSavedChainSteps = (chain: ChainConfig, worktree = false): ChainStep[] =
 			progress: step.progress,
 			skill: step.skill ?? step.skills,
 			model: step.model,
+			...(step.stopOn ? { stopOn: step.stopOn } : {}),
 		};
 	});
 };