@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/src/shared/post-exit-stdio-guard.ts

@@ -0,0 +1,204 @@
+import { execFileSync, type ChildProcess } from "node:child_process";
+import { readLinuxProcess } from "../pi-intercom/broker/pid.ts";
+import type { AgentProcessExit } from "./types.ts";
+
+interface PostExitStdioGuardOptions {
+	idleMs: number;
+	hardMs: number;
+}
+
+interface ChildWithPipedStdio {
+	stdout: ChildProcess["stdout"];
+	stderr: ChildProcess["stderr"];
+	on: ChildProcess["on"];
+}
+
+interface ChildWithKill {
+	pid?: number;
+	kill(signal?: NodeJS.Signals | number): boolean;
+}
+
+/** Capture the detached group leader's birth identity; Pi may replace its command-line title. */
+export function readChildProcessIdentity(pid: number): string | undefined {
+	if (!Number.isSafeInteger(pid) || pid <= 0) return undefined;
+	if (process.platform === "linux") return readLinuxProcess(pid)?.identity;
+	try {
+		const identity = execFileSync("ps", ["-p", String(pid), "-o", "lstart=", "-o", "pgid="], {
+			encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"],
+			env: { ...process.env, LC_ALL: "C" },
+		}).trim().replace(/\s+/g, " ");
+		return Number(identity.split(" ").at(-1)) === pid ? identity : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function trySignalChild(child: ChildWithKill, signal: NodeJS.Signals): boolean {
+	try {
+		return child.kill(signal);
+	} catch {
+		return false;
+	}
+}
+
+export function isChildTreeAlive(child: ChildWithKill): boolean {
+	if (child.pid) {
+		try {
+			process.kill(-child.pid, 0);
+			return true;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EPERM") return true;
+		}
+	}
+	try {
+		return child.kill(0);
+	} catch {
+		return false;
+	}
+}
+
+/** Signal the detached child's process group, falling back if it is not a group leader. */
+export function trySignalChildTree(child: ChildWithKill, signal: NodeJS.Signals): boolean {
+	if (child.pid) {
+		try {
+			process.kill(-child.pid, signal);
+			return true;
+		} catch {
+			// Fall back when the child is not a process-group leader.
+		}
+	}
+	return trySignalChild(child, signal);
+}
+
+/** One lifetime for the owned process group, including descendants holding its pipes open. */
+export function attachChildProcessLifecycle(child: ChildWithPipedStdio & ChildWithKill) {
+	let closed = false;
+	let exited = false;
+	let stopping = false;
+	let settledCleanup = false;
+	let agentProcessExit: AgentProcessExit | undefined;
+	let drainTimer: NodeJS.Timeout | undefined;
+	let escalationTimer: NodeJS.Timeout | undefined;
+	const clearDrain = () => {
+		clearTimeout(drainTimer);
+		drainTimer = undefined;
+	};
+	const clearTimers = () => {
+		clearDrain();
+		clearTimeout(escalationTimer);
+		escalationTimer = undefined;
+	};
+	const signalTree = () => {
+		// Pi print mode uses SIGTERM to dispose its own detached tool processes.
+		const sent = trySignalChildTree(child, "SIGTERM");
+		escalationTimer = setTimeout(() => {
+			if (isChildTreeAlive(child)) trySignalChildTree(child, "SIGKILL");
+		}, 3000);
+		escalationTimer.unref();
+		return sent;
+	};
+	const terminate = () => {
+		// Cancellation overrides a pending or already-started successful settlement cleanup.
+		settledCleanup = false;
+		clearDrain();
+		if (closed || stopping) return;
+		stopping = true;
+		signalTree();
+	};
+	const clearStdioGuard = attachPostExitStdioGuard(child, { idleMs: 2000, hardMs: 8000 });
+	child.on("exit", (code, signal) => {
+		exited = true;
+		agentProcessExit = { pid: child.pid, code, signal, at: Date.now() };
+		clearTimers();
+		// The leader may exit before resistant descendants release inherited stdio.
+		trySignalChildTree(child, "SIGKILL");
+	});
+	const dispose = () => {
+		closed = true;
+		clearTimers();
+		clearStdioGuard();
+	};
+	child.on("close", dispose);
+	child.on("error", dispose);
+	return {
+		terminate,
+		get stopping() { return stopping; },
+		get agentProcessExit() { return agentProcessExit; },
+		get settledCleanup() { return settledCleanup; },
+		observeEvent(type: string | undefined) {
+			if (closed || exited || stopping) return;
+			if (type === "agent_settled") {
+				if (drainTimer) return;
+				drainTimer = setTimeout(() => {
+					drainTimer = undefined;
+					stopping = true;
+					settledCleanup = signalTree();
+				}, 1000);
+				drainTimer.unref();
+			} else if (type === "agent_start" || type === "turn_start" || type?.startsWith("message_") || type?.startsWith("tool_execution_")) {
+				clearDrain();
+			}
+		},
+	};
+}
+
+export function attachPostExitStdioGuard(
+	child: ChildWithPipedStdio,
+	options: PostExitStdioGuardOptions,
+): () => void {
+	const { idleMs, hardMs } = options;
+	let exited = false;
+	let stdoutEnded = false;
+	let stderrEnded = false;
+	let idleTimer: NodeJS.Timeout | undefined;
+	let hardTimer: NodeJS.Timeout | undefined;
+
+	const destroyUnendedStdio = () => {
+		if (!stdoutEnded) {
+			try { child.stdout?.destroy(); } catch {}
+		}
+		if (!stderrEnded) {
+			try { child.stderr?.destroy(); } catch {}
+		}
+	};
+
+	const clearTimers = () => {
+		if (idleTimer) {
+			clearTimeout(idleTimer);
+			idleTimer = undefined;
+		}
+		if (hardTimer) {
+			clearTimeout(hardTimer);
+			hardTimer = undefined;
+		}
+	};
+
+	const armIdleTimer = () => {
+		if (!exited) return;
+		if (idleTimer) clearTimeout(idleTimer);
+		idleTimer = setTimeout(destroyUnendedStdio, idleMs);
+		idleTimer.unref?.();
+	};
+
+	child.stdout?.on("data", armIdleTimer);
+	child.stderr?.on("data", armIdleTimer);
+	child.stdout?.on("end", () => {
+		stdoutEnded = true;
+		if (stdoutEnded && stderrEnded) clearTimers();
+	});
+	child.stderr?.on("end", () => {
+		stderrEnded = true;
+		if (stdoutEnded && stderrEnded) clearTimers();
+	});
+	child.on("exit", () => {
+		exited = true;
+		armIdleTimer();
+		if (hardTimer) return;
+		hardTimer = setTimeout(destroyUnendedStdio, hardMs);
+		hardTimer.unref?.();
+	});
+	child.on("close", clearTimers);
+	child.on("error", clearTimers);
+
+	return clearTimers;
+}

package/src/shared/prompt-sections.ts

@@ -0,0 +1,10 @@
+import type { NormalizedBuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
+
+export function setPromptSection(options: NormalizedBuildSystemPromptOptions, name: string, content: string): void {
+	options.sections[name] = content;
+	// Pi projects an earlier exact override instead of sections. Preserve its content;
+	// this compatibility path replaces the leading prompt and cannot preserve its cache prefix.
+	if (options.forceSystemPrompt !== undefined) {
+		options.forceSystemPrompt += `\n\n<${name}>\n${content}\n</${name}>`;
+	}
+}

package/src/shared/session-entries.ts

@@ -0,0 +1,49 @@
+import type { SessionManager, SessionEntry } from "@earendil-works/pi-coding-agent";
+
+type EntrySource = Pick<SessionManager, "getEntries" | "getSessionId"> & Partial<Pick<SessionManager, "getSessionFile" | "getEntry" | "getLeafId" | "getEntryCount">>;
+
+/** Follow append-only parent links; rescan when entries were replaced or appended off the active branch. */
+export class SessionEntryCursor {
+	private manager?: EntrySource;
+	private sessionId?: string;
+	private file?: string | null;
+	private known = new Map<string, SessionEntry>();
+	private anchor?: SessionEntry;
+
+	reset(): void {
+		this.manager = undefined;
+		this.known.clear();
+		this.anchor = undefined;
+	}
+
+	read(manager: EntrySource): { entries: SessionEntry[]; reset: boolean } {
+		const sessionId = manager.getSessionId(), file = manager.getSessionFile?.(), count = manager.getEntryCount?.();
+		let reset = this.manager !== manager || this.sessionId !== sessionId || this.file !== file
+			|| count !== undefined && count < this.known.size
+			|| Boolean(this.anchor && manager.getEntry && manager.getEntry(this.anchor.id) !== this.known.get(this.anchor.id));
+		let entries: SessionEntry[] | undefined;
+		if (!reset && count !== undefined && manager.getEntry && manager.getLeafId) {
+			const appended: SessionEntry[] = [], visited = new Set<string>();
+			let id = manager.getLeafId();
+			while (id && !this.known.has(id) && !visited.has(id)) {
+				visited.add(id);
+				const entry = manager.getEntry(id);
+				if (!entry) break;
+				appended.push(entry);
+				id = entry.parentId;
+			}
+			if (count === this.known.size + appended.length && (!id || this.known.has(id))) entries = appended.reverse();
+		}
+		if (!entries) {
+			const all = manager.getEntries();
+			entries = all.filter((entry) => !this.known.has(entry.id));
+			if (all.length !== this.known.size + entries.length
+				|| all.some((entry) => this.known.has(entry.id) && this.known.get(entry.id) !== entry)) reset = true;
+			if (reset) { this.known.clear(); entries = all; }
+		}
+		for (const entry of entries) this.known.set(entry.id, entry);
+		this.anchor = entries.at(-1) ?? (reset ? undefined : this.anchor);
+		this.manager = manager; this.sessionId = sessionId; this.file = file;
+		return { entries, reset };
+	}
+}

package/src/shared/session-identity.ts

@@ -0,0 +1,18 @@
+interface SessionIdentityManager {
+	getSessionFile(): string | null | undefined;
+	getSessionId(): string | null | undefined;
+}
+
+// Only delegation supplies this identity; Pi's ordinary fork/clone ancestry does not.
+export function resolveRootSessionId(sessionManager: SessionIdentityManager, env: NodeJS.ProcessEnv = process.env): string {
+	const rootId = env.PI_SUBAGENT_CHILD === "1" ? env.PI_SUBAGENT_ROOT_SESSION_ID : undefined;
+	const sessionId = rootId || sessionManager.getSessionId();
+	if (!sessionId) throw new Error("Root session identity is unavailable.");
+	return sessionId;
+}
+
+export function resolveCurrentSessionId(sessionManager: SessionIdentityManager): string {
+	const sessionId = sessionManager.getSessionId();
+	if (!sessionId) throw new Error("Current session identity is unavailable.");
+	return sessionId;
+}

package/src/shared/settings.ts

@@ -0,0 +1,384 @@
+/**
+ * Chain behavior, template resolution, and directory management
+ */
+
+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 { ensureSafeTempPath, ensureTempRoot } from "./temp-root.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";
+
+// =============================================================================
+// Behavior Resolution Types
+// =============================================================================
+
+export interface ResolvedStepBehavior {
+	output: string | false;
+	outputMode: OutputMode;
+	reads: string[] | false;
+	progress: boolean;
+	skills: string[] | false;
+	model?: string;
+}
+
+export type StepOverrides = Partial<ResolvedStepBehavior>;
+
+function normalizeOutputOverride(output: string | false | undefined): string | false | undefined {
+	return output === "false" ? false : output;
+}
+
+// =============================================================================
+// Chain Step Types
+// =============================================================================
+
+/** Sequential step: single agent execution */
+export interface SequentialStep {
+	agent: string;
+	task?: string;
+	phase?: string;
+	label?: string;
+	as?: string;
+	outputSchema?: JsonSchemaObject;
+	cwd?: string;
+	output?: string | false;
+	outputMode?: OutputMode;
+	outputFromAgentDefault?: boolean;
+	reads?: string[] | false;
+	progress?: boolean;
+	skill?: string | string[] | false;
+	model?: string;
+	acceptance?: AcceptanceInput;
+}
+
+/** Parallel task item within a parallel step */
+export interface ParallelTaskItem extends SequentialStep {
+	count?: number;
+}
+
+export interface DynamicExpandSpec {
+	from: {
+		output: string;
+		path: string;
+	};
+	item?: string;
+	key?: string;
+	maxItems?: number;
+	onEmpty?: "skip" | "fail";
+}
+
+export type DynamicParallelTemplate = Omit<ParallelTaskItem, "as" | "count">;
+
+export interface DynamicCollectSpec {
+	as: string;
+	outputSchema?: JsonSchemaObject;
+}
+
+export interface DynamicParallelStep {
+	expand: DynamicExpandSpec;
+	parallel: DynamicParallelTemplate;
+	collect: DynamicCollectSpec;
+	concurrency?: number;
+	failFast?: boolean;
+	phase?: string;
+	label?: string;
+}
+
+/** Parallel step: multiple agents running concurrently */
+export interface ParallelStep {
+	parallel: ParallelTaskItem[];
+	concurrency?: number;
+	failFast?: boolean;
+	worktree?: boolean;
+	cwd?: string;
+}
+
+/** Union type for chain steps */
+export type ChainStep = SequentialStep | ParallelStep | DynamicParallelStep;
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+export function isParallelStep(step: ChainStep): step is ParallelStep {
+	return "parallel" in step && Array.isArray((step as ParallelStep).parallel);
+}
+
+export function isDynamicParallelStep(step: ChainStep): step is DynamicParallelStep {
+	return "expand" in step && "collect" in step && "parallel" in step && !Array.isArray((step as { parallel?: unknown }).parallel);
+}
+
+/** Get all agent names in a step (single for sequential, multiple for parallel) */
+export function getStepAgents(step: ChainStep): string[] {
+	if (isParallelStep(step)) {
+		return step.parallel.map((t) => t.agent);
+	}
+	if (isDynamicParallelStep(step)) {
+		return [step.parallel.agent];
+	}
+	return [step.agent];
+}
+
+export function collectInvocationAgentNames(params: { agent?: string; tasks?: Array<{ agent: string }>; chain?: ChainStep[] }): string[] {
+	const names: string[] = [];
+	if (params.agent) names.push(params.agent);
+	for (const task of params.tasks ?? []) names.push(task.agent);
+	for (const step of params.chain ?? []) names.push(...getStepAgents(step));
+	return names;
+}
+
+// =============================================================================
+// Chain Directory Management
+// =============================================================================
+
+export function createChainDir(runId: string, baseDir?: string, cwd = process.cwd()): string {
+	if (!baseDir) ensureTempRoot();
+	const chainDir = path.join(baseDir ? path.resolve(cwd, baseDir) : CHAIN_RUNS_DIR, runId);
+	if (!baseDir) ensureSafeTempPath(chainDir);
+	fs.mkdirSync(chainDir, { recursive: true });
+	return chainDir;
+}
+
+export function removeChainDir(chainDir: string): void {
+	try {
+		fs.rmSync(chainDir, { recursive: true });
+	} catch {
+		// Chain cleanup is best-effort. Runs can already have cleaned their temp dir.
+	}
+}
+
+export async function cleanupOldChainDirs(): Promise<void> {
+	ensureSafeTempPath(CHAIN_RUNS_DIR);
+	const now = Date.now();
+	let dirs: string[];
+	try {
+		dirs = await fs.promises.readdir(CHAIN_RUNS_DIR);
+	} catch {
+		// Startup cleanup is best-effort. If the scoped temp root is unreadable,
+		// skip cleanup instead of failing extension startup.
+		return;
+	}
+
+	for (const dir of dirs) {
+		try {
+			const dirPath = path.join(CHAIN_RUNS_DIR, dir);
+			const stat = await fs.promises.lstat(dirPath);
+			if (stat.isDirectory() && now - stat.mtimeMs > CHAIN_DIR_MAX_AGE_MS) {
+				await fs.promises.rm(dirPath, { recursive: true });
+			}
+		} catch {
+			// Skip directories that can't be processed; continue with others
+		}
+	}
+}
+
+// =============================================================================
+// Template Resolution
+// =============================================================================
+
+/** Resolved templates for a chain - string for sequential, string[] for parallel */
+export type ResolvedTemplates = (string | string[])[];
+
+/**
+ * Resolve templates for a chain with parallel step support.
+ * Returns string for sequential steps, string[] for parallel steps.
+ */
+export function resolveChainTemplates(
+	steps: ChainStep[],
+): ResolvedTemplates {
+	return steps.map((step, i) => {
+		if (isParallelStep(step)) {
+			// Parallel step: resolve each task's template
+			return step.parallel.map((task) => {
+				if (task.task) return task.task;
+				// Default for parallel tasks is {previous}
+				return "{previous}";
+			});
+		}
+		if (isDynamicParallelStep(step)) {
+			return step.parallel.task ?? "{previous}";
+		}
+		// Sequential step: existing logic
+		const seq = step as SequentialStep;
+		if (seq.task) return seq.task;
+		// Default: first step uses {task}, others use {previous}
+		return i === 0 ? "{task}" : "{previous}";
+	});
+}
+
+// =============================================================================
+// Behavior Resolution
+// =============================================================================
+
+/**
+ * Resolve effective chain behavior per step.
+ * Priority: step override > agent frontmatter > false (disabled)
+ */
+export function resolveStepBehavior(
+	agentConfig: AgentConfig,
+	stepOverrides: StepOverrides,
+	chainSkills?: string[] | false,
+): ResolvedStepBehavior {
+	// Output: step override > frontmatter > false (no output)
+	const stepOutput = normalizeOutputOverride(stepOverrides.output);
+	const output =
+		stepOutput !== undefined
+			? stepOutput
+			: normalizeOutputOverride(agentConfig.output) ?? false;
+
+	// Reads: step override > frontmatter defaultReads > false (no reads)
+	const reads =
+		stepOverrides.reads !== undefined
+			? stepOverrides.reads
+			: agentConfig.defaultReads ?? false;
+
+	// Progress: step override > frontmatter defaultProgress > false
+	const progress =
+		stepOverrides.progress !== undefined
+			? stepOverrides.progress
+			: agentConfig.defaultProgress ?? false;
+
+	let skills: string[] | false;
+	if (chainSkills === false || stepOverrides.skills === false) {
+		skills = false;
+	} else if (stepOverrides.skills !== undefined) {
+		skills = [...stepOverrides.skills];
+		if (chainSkills && chainSkills.length > 0) {
+			skills = [...new Set([...skills, ...chainSkills])];
+		}
+	} else {
+		skills = agentConfig.skills ? [...agentConfig.skills] : [];
+		if (chainSkills && chainSkills.length > 0) {
+			skills = [...new Set([...skills, ...chainSkills])];
+		}
+	}
+
+	const outputMode = stepOverrides.outputMode ?? "inline";
+	const model = stepOverrides.model ?? agentConfig.model;
+	return { output, outputMode, reads, progress, skills, model };
+}
+
+export function resolveTaskTextForFileUpdatePolicy(task: string | undefined, originalTask?: string): string | undefined {
+	if (!task) return originalTask;
+	return originalTask ? task.replaceAll("{task}", () => originalTask) : task;
+}
+
+export function taskDisallowsFileUpdates(task: string | undefined): boolean {
+	if (!task) return false;
+	return /\breview[- ]only\b/i.test(task)
+		|| /\bread[- ]only\s+(?:review|audit|inspection|pass)\b/i.test(task)
+		|| /\b(?:no|without)\s+(?:file\s+)?edits?\b/i.test(task)
+		|| /\b(?:do not|don't|must not)\s+(?:edit|modify|write|touch)\b/i.test(task)
+		|| /\bleave\s+files?\s+unchanged\b/i.test(task);
+}
+
+export function suppressProgressForReadOnlyTask(behavior: ResolvedStepBehavior, task: string | undefined, originalTask?: string): ResolvedStepBehavior {
+	const policyTask = resolveTaskTextForFileUpdatePolicy(task, originalTask);
+	return behavior.progress && taskDisallowsFileUpdates(policyTask) ? { ...behavior, progress: false } : behavior;
+}
+
+// =============================================================================
+// Chain Instruction Injection
+// =============================================================================
+
+/**
+ * Resolve a file path: absolute paths pass through, relative paths get chainDir prepended.
+ */
+function resolveChainPath(filePath: string, chainDir: string): string {
+	return path.isAbsolute(filePath) ? filePath : path.join(chainDir, filePath);
+}
+
+/**
+ * Build chain instructions from resolved behavior.
+ * These are appended to the task to tell the agent what to read/write.
+ */
+export function writeInitialProgressFile(progressDir: string): void {
+	fs.mkdirSync(progressDir, { recursive: true });
+	try {
+		fs.writeFileSync(path.join(progressDir, "progress.md"), INITIAL_PROGRESS_CONTENT, { encoding: "utf-8", flag: "wx" });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+	}
+}
+
+export function buildChainInstructions(
+	behavior: ResolvedStepBehavior,
+	chainDir: string,
+	isFirstProgressAgent: boolean,
+): { prefix: string; suffix: string } {
+	const prefixParts: string[] = [];
+	const suffixParts: string[] = [];
+
+	// READS - prepend to override any hardcoded filenames in task text
+	if (behavior.reads && behavior.reads.length > 0) {
+		const files = behavior.reads.map((f) => resolveChainPath(f, chainDir));
+		prefixParts.push(`[Read from: ${files.join(", ")}]`);
+	}
+
+	// OUTPUT - prepend so agent knows where to write
+	if (behavior.output) {
+		const outputPath = resolveChainPath(behavior.output, chainDir);
+		prefixParts.push(`[Write to: ${outputPath}]`);
+	}
+
+	// Progress instructions in suffix (less critical)
+	if (behavior.progress) {
+		const progressPath = path.join(chainDir, "progress.md");
+		if (isFirstProgressAgent) {
+			suffixParts.push(`Create and maintain progress at: ${progressPath}`);
+		} else {
+			suffixParts.push(`Update progress at: ${progressPath}`);
+		}
+	}
+
+	const prefix = prefixParts.length > 0 
+		? prefixParts.join("\n") + "\n\n"
+		: "";
+	
+	const suffix = suffixParts.length > 0
+		? "\n\n---\n" + suffixParts.join("\n")
+		: "";
+
+	return { prefix, suffix };
+}
+
+// =============================================================================
+// Parallel Step Support
+// =============================================================================
+
+/**
+ * Resolve behaviors for all tasks in a parallel step.
+ * Creates namespaced output paths to avoid collisions.
+ */
+export function resolveParallelBehaviors(
+	tasks: ParallelTaskItem[],
+	agentConfigs: AgentConfig[],
+	stepIndex: number,
+	chainSkills?: string[] | false,
+): ResolvedStepBehavior[] {
+	return tasks.map((task, taskIndex) => {
+		const config = agentConfigs.find((a) => a.name === task.agent);
+		if (!config) {
+			throw new Error(`Unknown agent: ${task.agent}`);
+		}
+
+		const behavior = resolveStepBehavior(config, {
+			output: task.output,
+			outputMode: task.outputMode,
+			reads: task.reads,
+			progress: task.progress,
+			skills: normalizeSkillInput(task.skill),
+			model: task.model,
+		}, chainSkills);
+		return { ...behavior, output: namespaceParallelOutput(behavior.output, task.agent, stepIndex, taskIndex) };
+	});
+}
+
+export function namespaceParallelOutput(output: string | false | undefined, agent: string, stepIndex: number, taskIndex: number): string | false {
+	return output ? path.isAbsolute(output) ? output : path.join(`parallel-${stepIndex}`, `${taskIndex}-${agent}`, output) : false;
+}
+
+export type { ParallelTaskResult } from "../runs/shared/parallel-utils.ts";
+export { aggregateParallelOutputs } from "../runs/shared/parallel-utils.ts";