@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/shared/settings.ts

@@ -1,384 +1,199 @@
-/**
- * Chain behavior, template resolution, and directory management
- */
-
-import * as fs from "node:fs";
+/** Chain step traversal, behavior resolution, and instruction composition. */
 import * as path from "node:path";
-import type { AgentConfig } from "../agents/agents.ts";
+import type { AgentConfig } from "./types/config.ts";
+import type {
+  ChainStep,
+  ParallelStep,
+  DynamicParallelStep,
+  ParallelTaskItem,
+  ResolvedStepBehavior,
+  StepOverrides,
+} from "./types/workflow.ts";
+import type { ReadonlyInput } from "./types/inputs.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;
-	}
+export type {
+  ChainStep,
+  ParallelStep,
+  DynamicParallelStep,
+  SequentialStep,
+  ParallelTaskItem,
+  ResolvedStepBehavior,
+  StepOverrides,
+  DynamicExpandSpec,
+  DynamicParallelTemplate,
+  DynamicCollectSpec,
+} from "./types/workflow.ts";
+export {
+  createChainDir,
+  removeChainDir,
+  cleanupOldChainDirs,
+  writeInitialProgressFile,
+} from "./chain-files.ts";
+export {
+  resolveTaskTextForFileUpdatePolicy,
+  taskDisallowsFileUpdates,
+  suppressProgressForReadOnlyTask,
+} from "./task-file-policy.ts";
+export type { ParallelTaskResult } from "../runs/shared/parallel-utils.ts";
 
-	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
-		}
-	}
+export function isParallelStep(
+  step: ReadonlyInput<ChainStep>,
+): step is ReadonlyInput<ParallelStep> {
+  return "parallel" in step && Array.isArray(step.parallel);
+}
+export function isDynamicParallelStep(
+  step: ReadonlyInput<ChainStep>,
+): step is ReadonlyInput<DynamicParallelStep> {
+  return (
+    "expand" in step && "collect" in step && "parallel" in step && !Array.isArray(step.parallel)
+  );
+}
+export function getStepAgents(step: ReadonlyInput<ChainStep>): string[] {
+  if (isParallelStep(step)) {
+    return step.parallel.map((task) => task.agent);
+  }
+  if (isDynamicParallelStep(step)) {
+    return [step.parallel.agent];
+  }
+  return [step.agent];
+}
+export function collectInvocationAgentNames(
+  params: ReadonlyInput<{ agent?: string; tasks?: Array<{ agent: string }>; chain?: ChainStep[] }>,
+): string[] {
+  const names: string[] = [];
+  if (params.agent !== undefined && params.agent.length > 0) {
+    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;
 }
-
-// =============================================================================
-// 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}";
-	});
+export function resolveChainTemplates(steps: readonly ChainStep[]): ResolvedTemplates {
+  return steps.map((step, index) => {
+    if (isParallelStep(step)) {
+      return step.parallel.map((task) =>
+        task.task !== undefined && task.task.length > 0 ? task.task : "{previous}",
+      );
+    }
+    if (isDynamicParallelStep(step)) {
+      return step.parallel.task ?? "{previous}";
+    }
+    if (step.task !== undefined && step.task.length > 0) {
+      return step.task;
+    }
+    return index === 0 ? "{task}" : "{previous}";
+  });
 }
-
-// =============================================================================
-// Behavior Resolution
-// =============================================================================
-
-/**
- * Resolve effective chain behavior per step.
- * Priority: step override > agent frontmatter > false (disabled)
- */
+function normalizeOutputOverride(output: string | false | undefined): string | false | undefined {
+  return output === "false" ? false : output;
+}
+function resolveStepSkills(
+  agentSkills: readonly string[] | undefined,
+  overrideSkills: readonly string[] | false | undefined,
+  chainSkills: readonly string[] | false | undefined,
+): string[] | false {
+  if (chainSkills === false || overrideSkills === false) {
+    return false;
+  }
+  const skills = [...(overrideSkills ?? agentSkills ?? [])];
+  return chainSkills !== undefined && chainSkills.length > 0
+    ? [...new Set([...skills, ...chainSkills])]
+    : skills;
+}
+/** Per-field precedence: step override, agent defaults, then disabled/unset. */
 export function resolveStepBehavior(
-	agentConfig: AgentConfig,
-	stepOverrides: StepOverrides,
-	chainSkills?: string[] | false,
+  agentConfig: AgentConfig,
+  stepOverrides: StepOverrides,
+  chainSkills?: readonly 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;
+  return {
+    output:
+      normalizeOutputOverride(stepOverrides.output) ??
+      normalizeOutputOverride(agentConfig.output) ??
+      false,
+    outputMode: stepOverrides.outputMode ?? "inline",
+    reads: stepOverrides.reads ?? agentConfig.defaultReads ?? false,
+    progress: stepOverrides.progress ?? agentConfig.defaultProgress ?? false,
+    skills: resolveStepSkills(agentConfig.skills, stepOverrides.skills, chainSkills),
+    model: stepOverrides.model ?? agentConfig.model,
+  };
 }
-
-// =============================================================================
-// 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;
-	}
+  return path.isAbsolute(filePath) ? filePath : path.join(chainDir, filePath);
 }
-
+/** Prepend read/output paths so task prose cannot accidentally override the chosen destination. */
 export function buildChainInstructions(
-	behavior: ResolvedStepBehavior,
-	chainDir: string,
-	isFirstProgressAgent: boolean,
+  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 };
+  const prefixParts: string[] = [];
+  const suffixParts: string[] = [];
+  if (behavior.reads !== false && behavior.reads.length > 0) {
+    prefixParts.push(
+      `[Read from: ${behavior.reads.map((file) => resolveChainPath(file, chainDir)).join(", ")}]`,
+    );
+  }
+  if (behavior.output !== false && behavior.output.length > 0) {
+    prefixParts.push(`[Write to: ${resolveChainPath(behavior.output, chainDir)}]`);
+  }
+  if (behavior.progress) {
+    const progressPath = path.join(chainDir, "progress.md");
+    suffixParts.push(
+      isFirstProgressAgent
+        ? `Create and maintain progress at: ${progressPath}`
+        : `Update progress at: ${progressPath}`,
+    );
+  }
+  return {
+    prefix: prefixParts.length > 0 ? `${prefixParts.join("\n")}\n\n` : "",
+    suffix: suffixParts.length > 0 ? `\n\n---\n${suffixParts.join("\n")}` : "",
+  };
 }
-
-// =============================================================================
-// 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,
+  tasks: readonly ParallelTaskItem[],
+  agentConfigs: readonly AgentConfig[],
+  stepIndex: number,
+  chainSkills?: readonly 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) };
-	});
+  return tasks.map((task, taskIndex) => {
+    const config = agentConfigs.find((agent) => agent.name === task.agent);
+    if (config === undefined) {
+      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 {
+  if (output === undefined || output === false || output.length === 0) {
+    return false;
+  }
+  return path.isAbsolute(output)
+    ? output
+    : path.join(`parallel-${stepIndex}`, `${taskIndex}-${agent}`, output);
 }
-
-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";