@fitchmultz/pi-subagents 0.44.7 → 0.45.0

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

@@ -1,184 +1,215 @@
-import type { AgentConfig } from "../agents/agents.ts";
-import type { ChainStep, SequentialStep } from "./settings.ts";
-import { getStepAgents, isDynamicParallelStep, isParallelStep } from "./settings.ts";
+import type { AgentConfig } from "./types/config.ts";
+import type { ReadonlyInput } from "./types/inputs.ts";
+import {
+  type ChainStep,
+  type SequentialStep,
+  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;
+  readonly getSessionFile: () => string | undefined;
+  readonly getLeafId: () => string | null;
+  readonly getSessionDir: () => string;
 }
 
 export interface SubagentParamsLikeForContext {
-	agent?: string;
-	model?: string;
-	tasks?: Array<{ agent: string; model?: string }>;
-	chain?: ChainStep[];
-	context?: SubagentExecutionContext;
+  agent?: string;
+  model?: string;
+  tasks?: Array<{ agent: string; model?: string }>;
+  chain?: ChainStep[];
+  context?: SubagentExecutionContext;
 }
 
 interface InvocationAgentTarget {
-	agent: string;
-	model?: string;
+  agent: string;
+  model?: string;
 }
 
 export function resolveAgentContext(
-	explicitContext: unknown,
-	agentName: string | undefined,
-	agents: readonly AgentConfig[],
+  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";
+  if (explicitContext !== undefined) {
+    return resolveSubagentContext(explicitContext);
+  }
+  if (agentName === undefined || 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 }] : [];
+function chainAgentTargets(step: ReadonlyInput<ChainStep>): InvocationAgentTarget[] {
+  if (isParallelStep(step)) {
+    return step.parallel.map((task) => ({ agent: task.agent, model: task.model }));
+  }
+  const task = isDynamicParallelStep(step) ? step.parallel : step;
+  return [{ agent: task.agent, model: task.model }];
+}
+
+function collectInvocationAgentTargets(
+  params: ReadonlyInput<SubagentParamsLikeForContext>,
+): InvocationAgentTarget[] {
+  if (params.tasks !== undefined && params.tasks.length > 0) {
+    return params.tasks.map((task) => ({ agent: task.agent, model: task.model }));
+  }
+  if (params.chain !== undefined && params.chain.length > 0) {
+    return params.chain.flatMap(chainAgentTargets);
+  }
+  return params.agent !== undefined && params.agent !== ""
+    ? [{ agent: params.agent, model: params.model }]
+    : [];
 }
 
 export function validateForkContextModelPolicy(
-	params: SubagentParamsLikeForContext,
-	agents: readonly AgentConfig[],
-	resolveModel?: (model: string) => string | undefined,
+  params: ReadonlyInput<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;
+  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 !== undefined && 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 !== undefined && 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[],
+  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");
+  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 buildFlatAgentNameResolver(
+  params: ReadonlyInput<SubagentParamsLikeForContext>,
+): (index: number) => string | undefined {
+  if ((params.tasks?.length ?? 0) > 0 || (params.chain?.length ?? 0) > 0) {
+    const names = collectInvocationAgentTargets(params).map((target) => target.agent);
+    return (index) => names[index];
+  }
+  return () => (params.agent === "" ? undefined : params.agent);
 }
 
 export function wrapTaskForAgentContext(
-	task: string,
-	explicitContext: unknown,
-	agentName: string | undefined,
-	agents: readonly AgentConfig[],
+  task: string,
+  explicitContext: unknown,
+  agentName: string | undefined,
+  agents: readonly AgentConfig[],
 ): string {
-	return resolveAgentContext(explicitContext, agentName, agents) === "fork" ? wrapForkTask(task) : task;
+  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,
-			),
-		};
-	});
+  chain: readonly ReadonlyInput<ChainStep>[],
+  explicitContext: unknown,
+  agents: readonly AgentConfig[],
+): ReadonlyInput<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: ReadonlyInput<SequentialStep> = step;
+    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);
-		},
-	};
+  sessionManager: ForkableSessionManager,
+  resolveContextForIndex: (index?: number) => SubagentExecutionContext,
+  options: {
+    readonly resolveContextForAgentIndex?: (
+      agentName: string | undefined,
+      index?: number,
+    ) => SubagentExecutionContext;
+  } = {},
+): {
+  readonly sessionFileForIndex: (index?: number) => string | undefined;
+  readonly 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);
+    }
+    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/agent-dir.ts

@@ -0,0 +1,15 @@
+import * as os from "node:os";
+import * as path from "node:path";
+
+export function getAgentDir(): string {
+  const configured = process.env.PI_CODING_AGENT_DIR;
+  if (configured === "~") {
+    return os.homedir();
+  }
+  if (configured?.startsWith("~/") === true) {
+    return path.join(os.homedir(), configured.slice(2));
+  }
+  return configured !== undefined && configured !== ""
+    ? configured
+    : path.join(os.homedir(), ".pi", "agent");
+}

package/src/shared/artifacts.ts

@@ -1,95 +1,126 @@
 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 { getAgentDir } from "./agent-dir.ts";
 import { ensureSafeTempPath } from "./temp-root.ts";
+import { hasErrorCode } from "./unknown.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;
+  if (sessionFile !== null && 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 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`);
+  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; }
+async function claimCleanup(dir: string, now: number): Promise<boolean> {
+  try {
+    await fs.promises.access(dir);
+  } catch {
+    return false;
+  }
 
-	const markerPath = path.join(dir, CLEANUP_MARKER_FILE);
-	const now = Date.now();
+  const markerPath = path.join(dir, CLEANUP_MARKER_FILE);
 
-	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;
-	}
+  try {
+    const stat = await fs.promises.lstat(markerPath);
+    if (!stat.isSymbolicLink() && now - stat.mtimeMs < 24 * 60 * 60 * 1000) {
+      return false;
+    }
+    await fs.promises.unlink(markerPath);
+  } catch (error) {
+    if (!hasErrorCode(error, "ENOENT")) {
+      return false;
+    }
+  }
 
-	const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
-	const cutoff = now - maxAgeMs;
+  return true;
+}
+export async function cleanupOldArtifacts(dir: string, maxAgeDays: number): Promise<void> {
+  ensureSafeTempPath(dir);
+  const now = Date.now();
+  if (!(await claimCleanup(dir, now))) {
+    return;
+  }
+  const markerPath = path.join(dir, CLEANUP_MARKER_FILE);
+  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.
-		}
-	}
+  for (const file of await fs.promises.readdir(dir)) {
+    if (file === CLEANUP_MARKER_FILE) {
+      continue;
+    }
+    const filePath = path.join(dir, file);
+    try {
+      // Process one filesystem entry at a time to keep cleanup's I/O bounded.
+      // oxlint-disable-next-line no-await-in-loop
+      const stat = await fs.promises.lstat(filePath);
+      if (stat.mtimeMs < cutoff) {
+        // Finish deleting this entry before inspecting the next artifact.
+        // oxlint-disable-next-line no-await-in-loop
+        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;
-	}
+  try {
+    await fs.promises.writeFile(markerPath, String(now), { flag: "wx", mode: 0o600 });
+  } catch (error) {
+    if (!hasErrorCode(error, "EEXIST")) {
+      throw error;
+    }
+  }
 }
 
 export async function cleanupAllArtifactDirs(maxAgeDays: number): Promise<void> {
-	await cleanupOldArtifacts(TEMP_ARTIFACTS_DIR, maxAgeDays);
+  await cleanupOldArtifacts(TEMP_ARTIFACTS_DIR, maxAgeDays);
 
-	const sessionsBase = path.join(getAgentDir(), "sessions");
+  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;
-	}
+  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.
-		}
-	}
+  for (const dir of dirs) {
+    const artifactsDir = path.join(sessionsBase, dir, "subagent-artifacts");
+    try {
+      // Finish each session directory before starting another retention scan.
+      // oxlint-disable-next-line no-await-in-loop
+      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

@@ -2,15 +2,18 @@ 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 });
-	}
+  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 });
+  }
 }