@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/src/shared/agent-context-policy.ts

@@ -0,0 +1,184 @@
+import type { AgentConfig } from "../agents/agents.ts";
+import type { ChainStep, SequentialStep } from "./settings.ts";
+import { getStepAgents, isDynamicParallelStep, isParallelStep } from "./settings.ts";
+import { createForkContextResolver, resolveSubagentContext } from "./fork-context.ts";
+import { wrapForkTask } from "./types.ts";
+
+export type SubagentExecutionContext = "fresh" | "fork";
+
+interface ForkableSessionManager {
+	getSessionFile(): string | undefined;
+	getLeafId(): string | null;
+	getSessionDir(): string;
+}
+
+export interface SubagentParamsLikeForContext {
+	agent?: string;
+	model?: string;
+	tasks?: Array<{ agent: string; model?: string }>;
+	chain?: ChainStep[];
+	context?: SubagentExecutionContext;
+}
+
+interface InvocationAgentTarget {
+	agent: string;
+	model?: string;
+}
+
+export function resolveAgentContext(
+	explicitContext: unknown,
+	agentName: string | undefined,
+	agents: readonly AgentConfig[],
+): SubagentExecutionContext {
+	if (explicitContext !== undefined) {
+		return resolveSubagentContext(explicitContext);
+	}
+	if (!agentName) return "fresh";
+	const agent = agents.find((entry) => entry.name === agentName);
+	return agent?.defaultContext === "fork" ? "fork" : "fresh";
+}
+
+function collectInvocationAgentTargets(params: SubagentParamsLikeForContext): InvocationAgentTarget[] {
+	if (params.tasks?.length) {
+		return params.tasks.map((task) => ({ agent: task.agent, model: task.model }));
+	}
+	if (params.chain?.length) {
+		const targets: InvocationAgentTarget[] = [];
+		for (const step of params.chain) {
+			if (isParallelStep(step)) {
+				for (const task of step.parallel) targets.push({ agent: task.agent, model: task.model });
+			} else if (isDynamicParallelStep(step)) {
+				targets.push({ agent: step.parallel.agent, model: step.parallel.model });
+			} else {
+				targets.push({ agent: step.agent, model: step.model });
+			}
+		}
+		return targets;
+	}
+	return params.agent ? [{ agent: params.agent, model: params.model }] : [];
+}
+
+export function validateForkContextModelPolicy(
+	params: SubagentParamsLikeForContext,
+	agents: readonly AgentConfig[],
+	resolveModel?: (model: string) => string | undefined,
+): string | undefined {
+	for (const target of collectInvocationAgentTargets(params)) {
+		const agent = agents.find((entry) => entry.name === target.agent);
+		if (!agent || resolveAgentContext(params.context, target.agent, agents) !== "fork") continue;
+		const anthropicModel = (target.model ? [target.model] : [agent.model, ...(agent.fallbackModels ?? [])])
+			.filter((model): model is string => Boolean(model?.trim()))
+			.map((model) => resolveModel?.(model) ?? model)
+			.find((model) => model.trim().toLowerCase().startsWith("anthropic/"));
+		if (anthropicModel) {
+			return `Fork context cannot be used with anthropic/* models. Agent '${target.agent}' has effective model candidate '${anthropicModel}'. Use context: "fresh" or a non-Anthropic model; this restriction cannot be overridden.`;
+		}
+	}
+	return undefined;
+}
+
+export function invocationUsesForkContext(
+	explicitContext: unknown,
+	agentNames: readonly string[],
+	agents: readonly AgentConfig[],
+): boolean {
+	if (explicitContext !== undefined) {
+		return resolveSubagentContext(explicitContext) === "fork";
+	}
+	return agentNames.some((name) => resolveAgentContext(undefined, name, agents) === "fork");
+}
+
+export function buildFlatAgentNameResolver(params: SubagentParamsLikeForContext): (index: number) => string | undefined {
+	if (params.agent && !params.tasks?.length && !params.chain?.length) {
+		return () => params.agent;
+	}
+	if (params.tasks?.length) {
+		return (index) => params.tasks![index]?.agent;
+	}
+	if (params.chain?.length) {
+		const flatAgents: string[] = [];
+		for (const step of params.chain) {
+			if (isParallelStep(step)) {
+				for (const task of step.parallel) flatAgents.push(task.agent);
+				continue;
+			}
+			flatAgents.push(...getStepAgents(step));
+		}
+		return (index) => flatAgents[index];
+	}
+	return () => undefined;
+}
+
+export function wrapTaskForAgentContext(
+	task: string,
+	explicitContext: unknown,
+	agentName: string | undefined,
+	agents: readonly AgentConfig[],
+): string {
+	return resolveAgentContext(explicitContext, agentName, agents) === "fork" ? wrapForkTask(task) : task;
+}
+
+export function wrapChainTasksForAgentContext(
+	chain: ChainStep[],
+	explicitContext: unknown,
+	agents: readonly AgentConfig[],
+): ChainStep[] {
+	return chain.map((step, stepIndex) => {
+		if (isParallelStep(step)) {
+			return {
+				...step,
+				parallel: step.parallel.map((task) => ({
+					...task,
+					task: wrapTaskForAgentContext(task.task ?? "{previous}", explicitContext, task.agent, agents),
+				})),
+			};
+		}
+		if (isDynamicParallelStep(step)) {
+			return {
+				...step,
+				parallel: {
+					...step.parallel,
+					task: wrapTaskForAgentContext(
+						step.parallel.task ?? "{previous}",
+						explicitContext,
+						step.parallel.agent,
+						agents,
+					),
+				},
+			};
+		}
+		const sequential = step as SequentialStep;
+		const agentName = getStepAgents(step)[0];
+		return {
+			...sequential,
+			task: wrapTaskForAgentContext(
+				sequential.task ?? (stepIndex === 0 ? "{task}" : "{previous}"),
+				explicitContext,
+				agentName,
+				agents,
+			),
+		};
+	});
+}
+
+export function createPerAgentForkContextResolver(
+	sessionManager: ForkableSessionManager,
+	resolveContextForIndex: (index?: number) => SubagentExecutionContext,
+	options: { resolveContextForAgentIndex?: (agentName: string | undefined, index?: number) => SubagentExecutionContext } = {},
+): { sessionFileForIndex(index?: number): string | undefined; sessionFileForAgentIndex(agentName: string | undefined, index?: number): string | undefined } {
+	let forkResolver: ReturnType<typeof createForkContextResolver> | undefined;
+	const sessionFileForContext = (context: SubagentExecutionContext, index = 0): string | undefined => {
+		if (context !== "fork") return undefined;
+		if (!forkResolver) forkResolver = createForkContextResolver(sessionManager, "fork");
+		return forkResolver.sessionFileForIndex(index);
+	};
+	return {
+		sessionFileForIndex(index = 0): string | undefined {
+			return sessionFileForContext(resolveContextForIndex(index), index);
+		},
+		sessionFileForAgentIndex(agentName, index = 0): string | undefined {
+			const context = options.resolveContextForAgentIndex?.(agentName, index) ?? resolveContextForIndex(index);
+			return sessionFileForContext(context, index);
+		},
+	};
+}

package/src/shared/artifacts.ts

@@ -0,0 +1,95 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { TEMP_ARTIFACTS_DIR, type ArtifactPaths } from "./types.ts";
+import { getAgentDir } from "./utils.ts";
+import { ensureSafeTempPath } from "./temp-root.ts";
+const CLEANUP_MARKER_FILE = ".last-cleanup";
+export const ARTIFACT_CLEANUP_DAYS = 7;
+
+export function getArtifactsDir(sessionFile: string | null): string {
+	if (sessionFile) {
+		const sessionDir = path.dirname(sessionFile);
+		return path.join(sessionDir, "subagent-artifacts");
+	}
+	return TEMP_ARTIFACTS_DIR;
+}
+
+export function getArtifactPaths(artifactsDir: string, runId: string, agent: string, index?: number): ArtifactPaths {
+	ensureSafeTempPath(artifactsDir);
+	const suffix = index !== undefined ? `_${index}` : "";
+	const safeAgent = agent.replace(/[^\w.-]/g, "_").slice(0, 128);
+	const base = `${runId}_${safeAgent}${suffix}`;
+	return {
+		inputPath: path.join(artifactsDir, `${base}_input.md`),
+		outputPath: path.join(artifactsDir, `${base}_output.md`),
+		metadataPath: path.join(artifactsDir, `${base}_meta.json`),
+	};
+}
+
+export function appendJsonl(filePath: string, line: string): void {
+	fs.appendFileSync(filePath, `${line}\n`);
+}
+
+export async function cleanupOldArtifacts(dir: string, maxAgeDays: number): Promise<void> {
+	ensureSafeTempPath(dir);
+	try { await fs.promises.access(dir); } catch { return; }
+
+	const markerPath = path.join(dir, CLEANUP_MARKER_FILE);
+	const now = Date.now();
+
+	try {
+		const stat = await fs.promises.lstat(markerPath);
+		if (!stat.isSymbolicLink() && now - stat.mtimeMs < 24 * 60 * 60 * 1000) return;
+		await fs.promises.unlink(markerPath);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") return;
+	}
+
+	const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+	const cutoff = now - maxAgeMs;
+
+	for (const file of await fs.promises.readdir(dir)) {
+		if (file === CLEANUP_MARKER_FILE) continue;
+		const filePath = path.join(dir, file);
+		try {
+			const stat = await fs.promises.lstat(filePath);
+			if (stat.mtimeMs < cutoff) {
+				await fs.promises.unlink(filePath);
+			}
+		} catch {
+			// Artifact cleanup is best-effort housekeeping. Skip files that disappear
+			// or become unreadable while scanning so one bad entry does not block the rest.
+		}
+	}
+
+	try {
+		await fs.promises.writeFile(markerPath, String(now), { flag: "wx", mode: 0o600 });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+	}
+}
+
+export async function cleanupAllArtifactDirs(maxAgeDays: number): Promise<void> {
+	await cleanupOldArtifacts(TEMP_ARTIFACTS_DIR, maxAgeDays);
+
+	const sessionsBase = path.join(getAgentDir(), "sessions");
+
+	let dirs: string[];
+	try {
+		dirs = await fs.promises.readdir(sessionsBase);
+	} catch {
+		// Session artifact cleanup is best-effort. If the sessions root cannot be read,
+		// skip cleanup instead of failing extension startup.
+		return;
+	}
+
+	for (const dir of dirs) {
+		const artifactsDir = path.join(sessionsBase, dir, "subagent-artifacts");
+		try {
+			await cleanupOldArtifacts(artifactsDir, maxAgeDays);
+		} catch {
+			// Session cleanup is best-effort. Keep going so one unreadable session dir
+			// does not block cleanup for the rest.
+		}
+	}
+}

package/src/shared/atomic-json.ts

@@ -0,0 +1,16 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function writeAtomicJson(filePath: string, payload: object): void {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	const tempPath = path.join(
+		path.dirname(filePath),
+		`.${path.basename(filePath)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`,
+	);
+	try {
+		fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2), { encoding: "utf-8", mode: 0o600 });
+		fs.renameSync(tempPath, filePath);
+	} finally {
+		fs.rmSync(tempPath, { force: true });
+	}
+}

package/src/shared/cooperative.ts

@@ -0,0 +1,21 @@
+import { setImmediate as yieldToInput } from "node:timers/promises";
+
+export function runSynchronously<T>(steps: Generator<void, T>): T {
+	let step = steps.next();
+	while (!step.done) step = steps.next();
+	return step.value;
+}
+
+/** Batched recovery and delivery leave room for input between records. */
+export async function runCooperatively<T>(steps: Generator<void, T>): Promise<T> {
+	let step = steps.next();
+	for (let count = 0; !step.done; step = steps.next()) {
+		// ponytail: one recovery record remains atomic; move a demonstrated
+		// single-record stall off-thread rather than increasing this batch size.
+		if (++count === 32) {
+			await yieldToInput();
+			count = 0;
+		}
+	}
+	return step.value;
+}

package/src/shared/execution-cwd.ts

@@ -0,0 +1,14 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { hasExecutionCwdOwner } from "../runs/shared/child-execution-cwd.ts";
+
+/** Capture the active directory owner once per invocation, before asynchronous preparation. */
+export function resolveExecutionCwd(pi: Pick<ExtensionAPI, "events"> & Partial<Pick<ExtensionAPI, "getAllTools" | "getCommands">>, ctx: ExtensionContext): string {
+	const request: { sessionManager: ExtensionContext["sessionManager"]; result?: { cwd?: string; error?: string } } = { sessionManager: ctx.sessionManager };
+	pi.events.emit("pi-change-working-dir:resolve-execution-cwd", request);
+	if (request.result?.error) throw new Error(request.result.error);
+	if (request.result && !request.result.cwd) throw new Error("Working-directory owner did not return an execution directory.");
+	if (!request.result && pi.getAllTools && pi.getCommands && hasExecutionCwdOwner({ getAllTools: pi.getAllTools, getCommands: pi.getCommands })) {
+		throw new Error("The loaded directory extension did not resolve the execution directory. Update pi-change-working-dir before delegating work.");
+	}
+	return request.result?.cwd ?? ctx.cwd;
+}

package/src/shared/file-coalescer.ts

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

package/src/shared/fork-context.ts

@@ -0,0 +1,68 @@
+import * as fs from "node:fs";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { requestChildExecutionCwd } from "../runs/shared/child-execution-cwd.ts";
+
+type SubagentExecutionContext = "fresh" | "fork";
+
+interface ForkableSessionManager {
+	getSessionFile(): string | undefined;
+	getLeafId(): string | null;
+	getSessionDir(): string;
+}
+
+interface ForkContextResolver {
+	sessionFileForIndex(index?: number): string | undefined;
+}
+
+export function resolveSubagentContext(value: unknown): SubagentExecutionContext {
+	return value === "fork" ? "fork" : "fresh";
+}
+
+export function createForkContextResolver(
+	sessionManager: ForkableSessionManager,
+	requestedContext: unknown,
+): ForkContextResolver {
+	if (resolveSubagentContext(requestedContext) !== "fork") {
+		return {
+			sessionFileForIndex: () => undefined,
+		};
+	}
+
+	const parentSessionFile = sessionManager.getSessionFile();
+	if (!parentSessionFile) {
+		throw new Error("Forked subagent context requires a persisted parent session.");
+	}
+
+	const leafId = sessionManager.getLeafId();
+	if (!leafId) {
+		throw new Error("Forked subagent context requires a current leaf to fork from.");
+	}
+
+	const sessionDir = sessionManager.getSessionDir();
+	const cachedSessionFiles = new Map<number, string>();
+
+	return {
+		sessionFileForIndex(index = 0): string | undefined {
+			const cached = cachedSessionFiles.get(index);
+			if (cached) return cached;
+			try {
+				if (!fs.existsSync(parentSessionFile)) {
+					throw new Error(`Parent session file does not exist: ${parentSessionFile}. Pi has not persisted enough history to fork yet.`);
+				}
+				const sessionFile = SessionManager.open(parentSessionFile, sessionDir).createBranchedSession(leafId);
+				if (!sessionFile) {
+					throw new Error("Session manager did not return a forked session file.");
+				}
+				if (!fs.existsSync(sessionFile)) {
+					throw new Error(`Session manager returned a forked session file that does not exist: ${sessionFile}`);
+				}
+				requestChildExecutionCwd(sessionFile);
+				cachedSessionFiles.set(index, sessionFile);
+				return sessionFile;
+			} catch (error) {
+				const cause = error instanceof Error ? error : new Error(String(error));
+				throw new Error(`Failed to create forked subagent session: ${cause.message}`, { cause });
+			}
+		},
+	};
+}

package/src/shared/formatters.ts

@@ -0,0 +1,84 @@
+/**
+ * Formatting utilities for display output
+ */
+
+import type { Usage } from "./types.ts";
+import { splitKnownThinkingSuffix, THINKING_LEVELS } from "./model-info.ts";
+
+/**
+ * Format token count with k suffix for large numbers
+ */
+export function formatTokens(n: number): string {
+	return n < 1000 ? String(n) : n < 10000 ? `${(n / 1000).toFixed(1)}k` : `${Math.round(n / 1000)}k`;
+}
+
+export function formatModelThinking(model?: string, thinking?: string): string {
+	const parsed = model ? splitKnownThinkingSuffix(model) : undefined;
+	const displayModel = parsed?.baseModel ?? model;
+	const explicitThinking = THINKING_LEVELS.find((level) => level === thinking?.trim());
+	const displayThinking = parsed?.thinkingSuffix ? parsed.thinkingSuffix.slice(1) : explicitThinking;
+	return [displayModel, displayThinking ? `thinking ${displayThinking}` : undefined].filter(Boolean).join(" · ");
+}
+
+/**
+ * Format usage statistics into a compact string
+ */
+export function formatUsage(u: Usage, model?: string): string {
+	const parts: string[] = [];
+	if (u.turns) parts.push(`${u.turns} turn${u.turns > 1 ? "s" : ""}`);
+	if (u.input) parts.push(`in:${formatTokens(u.input)}`);
+	if (u.output) parts.push(`out:${formatTokens(u.output)}`);
+	if (u.cacheRead) parts.push(`R${formatTokens(u.cacheRead)}`);
+	if (u.cacheWrite) parts.push(`W${formatTokens(u.cacheWrite)}`);
+	if (u.cost) parts.push(`$${u.cost.toFixed(4)}`);
+	if (model) parts.push(model);
+	return parts.join(" ");
+}
+
+/**
+ * Format duration in human-readable form
+ */
+export function formatDuration(ms: number): string {
+	if (ms < 1000) return `${ms}ms`;
+	if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+	return `${Math.floor(ms / 60000)}m${Math.floor((ms % 60000) / 1000)}s`;
+}
+
+/**
+ * Format a tool call for display
+ */
+export function formatToolCall(name: string, args: Record<string, unknown>, expanded = false): string {
+	switch (name) {
+		case "bash": {
+			const command = typeof args.command === "string" ? args.command : "";
+			const maxLength = expanded ? 240 : 60;
+			return `$ ${command.slice(0, maxLength)}${command.length > maxLength ? "..." : ""}`;
+		}
+		case "read":
+		case "write":
+		case "edit": {
+			const target = typeof args.path === "string"
+				? args.path
+				: typeof args.file_path === "string"
+					? args.file_path
+					: "";
+			return `${name} ${shortenPath(target)}`;
+		}
+		default: {
+			const s = JSON.stringify(args);
+			const maxLength = expanded ? 160 : 40;
+			return `${name} ${s.slice(0, maxLength)}${s.length > maxLength ? "..." : ""}`;
+		}
+	}
+}
+
+/**
+ * Shorten a path by replacing home directory with ~
+ */
+export function shortenPath(p: string): string {
+	const home = process.env.HOME;
+	if (home && p.startsWith(home)) {
+		return `~${p.slice(home.length)}`;
+	}
+	return p;
+}