@oh-my-pi/pi-coding-agent 1.337.0

package/src/core/tools/task/index.ts

@@ -0,0 +1,388 @@
+/**
+ * Task tool - Delegate tasks to specialized agents.
+ *
+ * Discovers agent definitions from:
+ *   - Bundled agents (shipped with pi-coding-agent)
+ *   - ~/.pi/agent/agents/*.md (user-level)
+ *   - .pi/agents/*.md (project-level)
+ *
+ * Supports:
+ *   - Single agent execution
+ *   - Parallel execution with concurrency limits
+ *   - Progress tracking via JSON events
+ *   - Session artifacts for debugging
+ */
+
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import type { Theme } from "../../../modes/interactive/theme/theme.js";
+import { cleanupTempDir, createTempArtifactsDir, getArtifactsDir, writeArtifacts } from "./artifacts.js";
+import { discoverAgents, getAgent } from "./discovery.js";
+import { runSubprocess } from "./executor.js";
+import { mapWithConcurrencyLimit } from "./parallel.js";
+import { formatDuration, renderCall, renderResult } from "./render.js";
+import {
+	type AgentProgress,
+	MAX_AGENTS_IN_DESCRIPTION,
+	MAX_CONCURRENCY,
+	MAX_PARALLEL_TASKS,
+	PI_NO_SUBAGENTS_ENV,
+	type TaskToolDetails,
+	taskSchema,
+} from "./types.js";
+
+/** Session context interface */
+interface SessionContext {
+	getSessionFile: () => string | null;
+}
+
+// Re-export types and utilities
+export { loadBundledAgents as BUNDLED_AGENTS } from "./agents.js";
+export { discoverCommands, expandCommand, getCommand } from "./commands.js";
+export { discoverAgents, getAgent } from "./discovery.js";
+export type { AgentDefinition, AgentProgress, SingleResult, TaskParams, TaskToolDetails } from "./types.js";
+export { taskSchema } from "./types.js";
+
+/**
+ * Build dynamic tool description listing available agents.
+ */
+function buildDescription(cwd: string): string {
+	const { agents } = discoverAgents(cwd);
+
+	const lines: string[] = [];
+
+	lines.push("Launch a new agent to handle complex, multi-step tasks autonomously.");
+	lines.push("");
+	lines.push(
+		"The Task tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.",
+	);
+	lines.push("");
+	lines.push("Available agent types and the tools they have access to:");
+
+	for (const agent of agents.slice(0, MAX_AGENTS_IN_DESCRIPTION)) {
+		const tools = agent.tools?.join(", ") || "All tools";
+		lines.push(`- ${agent.name}: ${agent.description} (Tools: ${tools})`);
+	}
+	if (agents.length > MAX_AGENTS_IN_DESCRIPTION) {
+		lines.push(`  ...and ${agents.length - MAX_AGENTS_IN_DESCRIPTION} more agents`);
+	}
+
+	lines.push("");
+	lines.push("When NOT to use the Task tool:");
+	lines.push(
+		"- If you want to read a specific file path, use the Read or Glob tool instead of the Task tool, to find the match more quickly",
+	);
+	lines.push(
+		'- If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly',
+	);
+	lines.push(
+		"- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Task tool, to find the match more quickly",
+	);
+	lines.push("- Other tasks that are not related to the agent descriptions above");
+	lines.push("");
+	lines.push("");
+	lines.push("Usage notes:");
+	lines.push("- Always include a short description of the task in the task parameter");
+	lines.push("- Launch multiple agents concurrently whenever possible, to maximize performance");
+	lines.push(
+		"- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.",
+	);
+	lines.push(
+		"- Each agent invocation is stateless. You will not be able to send additional messages to the agent, nor will the agent be able to communicate with you outside of its final report. Therefore, your task should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.",
+	);
+	lines.push(
+		"- IMPORTANT: Agent results are intermediate data, not task completions. Use the agent's findings to continue executing the user's request. Do not treat agent reports as 'task complete' signals - they provide context for you to perform the actual work.",
+	);
+	lines.push("- The agent's outputs should generally be trusted");
+	lines.push(
+		"- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent",
+	);
+	lines.push(
+		"- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.",
+	);
+	lines.push("");
+	lines.push("Parameters:");
+	lines.push(
+		`- tasks: Array of {agent, task, model?} - tasks to run in parallel (max ${MAX_PARALLEL_TASKS}, ${MAX_CONCURRENCY} concurrent)`,
+	);
+	lines.push(
+		'  - model: (optional) Override the agent\'s default model with fuzzy matching (e.g., "sonnet", "codex", "5.2"). Supports comma-separated fallbacks: "gpt, opus" tries gpt first, then opus. Use "default" for pi\'s default model',
+	);
+	lines.push(
+		"- context: (optional) Shared context string prepended to all task prompts - use this to avoid repeating instructions",
+	);
+	lines.push("");
+	lines.push("Results are always written to {tempdir}/pi-task-{runId}/task_{agent}_{index}.md");
+	lines.push("");
+	lines.push("Example usage:");
+	lines.push("");
+	lines.push("<example_agent_descriptions>");
+	lines.push('"code-reviewer": use this agent after you are done writing a significant piece of code');
+	lines.push('"explore": use this agent for fast codebase exploration and research');
+	lines.push("</example_agent_descriptions>");
+	lines.push("");
+	lines.push("<example>");
+	lines.push('user: "Please write a function that checks if a number is prime"');
+	lines.push("assistant: Sure let me write a function that checks if a number is prime");
+	lines.push("assistant: I'm going to use the Write tool to write the following code:");
+	lines.push("<code>");
+	lines.push("function isPrime(n) {");
+	lines.push("  if (n <= 1) return false");
+	lines.push("  for (let i = 2; i * i <= n; i++) {");
+	lines.push("    if (n % i === 0) return false");
+	lines.push("  }");
+	lines.push("  return true");
+	lines.push("}");
+	lines.push("</code>");
+	lines.push("<commentary>");
+	lines.push(
+		"Since a significant piece of code was written and the task was completed, now use the code-reviewer agent to review the code",
+	);
+	lines.push("</commentary>");
+	lines.push("assistant: Now let me use the code-reviewer agent to review the code");
+	lines.push(
+		'assistant: Uses the Task tool: { tasks: [{ agent: "code-reviewer", task: "Review the isPrime function" }] }',
+	);
+	lines.push("</example>");
+	lines.push("");
+	lines.push("<example>");
+	lines.push('user: "Find all TODO comments in the codebase"');
+	lines.push("assistant: I'll use multiple explore agents to search different directories in parallel");
+	lines.push("assistant: Uses the Task tool:");
+	lines.push("{");
+	lines.push('  "context": "Find all TODO comments. Return file:line:content format.",');
+	lines.push('  "tasks": [');
+	lines.push('    { "agent": "explore", "task": "Search in src/" },');
+	lines.push('    { "agent": "explore", "task": "Search in lib/" },');
+	lines.push('    { "agent": "explore", "task": "Search in tests/" }');
+	lines.push("  ]");
+	lines.push("}");
+	lines.push("Results → {tempdir}/pi-task-{runId}/task_explore_*.md");
+	lines.push("</example>");
+
+	return lines.join("\n");
+}
+
+/**
+ * Create the task tool configured for a specific working directory.
+ */
+export function createTaskTool(
+	cwd: string,
+	sessionContext?: SessionContext,
+): AgentTool<typeof taskSchema, TaskToolDetails, Theme> {
+	// Check if subagents are inhibited (recursion prevention)
+	if (process.env[PI_NO_SUBAGENTS_ENV]) {
+		return {
+			name: "task",
+			label: "Task",
+			description: "Sub-agents disabled (recursion prevention)",
+			parameters: taskSchema,
+			execute: async () => ({
+				content: [{ type: "text", text: "Sub-agents are disabled for this agent (recursion prevention)." }],
+				details: {
+					projectAgentsDir: null,
+					results: [],
+					totalDurationMs: 0,
+				},
+			}),
+		};
+	}
+
+	return {
+		name: "task",
+		label: "Task",
+		description: buildDescription(cwd),
+		parameters: taskSchema,
+		renderCall,
+		renderResult,
+		execute: async (_toolCallId, params, signal, onUpdate) => {
+			const startTime = Date.now();
+			const { agents, projectAgentsDir } = discoverAgents(cwd);
+			const context = params.context;
+
+			// Handle empty or missing tasks
+			if (!params.tasks || params.tasks.length === 0) {
+				const available = agents.map((a) => a.name).join(", ") || "none";
+				return {
+					content: [
+						{
+							type: "text",
+							text: `No tasks provided. Use: { tasks: [{agent, task}, ...] }\nAvailable agents: ${available}`,
+						},
+					],
+					details: {
+						projectAgentsDir,
+						results: [],
+						totalDurationMs: 0,
+					},
+				};
+			}
+
+			// Validate task count
+			if (params.tasks.length > MAX_PARALLEL_TASKS) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Too many tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.`,
+						},
+					],
+					details: {
+						projectAgentsDir,
+						results: [],
+						totalDurationMs: 0,
+					},
+				};
+			}
+
+			// Derive artifacts directory
+			const sessionFile = sessionContext?.getSessionFile() ?? null;
+			const artifactsDir = sessionFile ? getArtifactsDir(sessionFile) : null;
+			const tempArtifactsDir = artifactsDir ? null : createTempArtifactsDir();
+			const effectiveArtifactsDir = artifactsDir || tempArtifactsDir!;
+
+			// Initialize progress tracking
+			const progressMap = new Map<number, AgentProgress>();
+
+			// Update callback
+			const emitProgress = () => {
+				const progress = Array.from(progressMap.values()).sort((a, b) => a.index - b.index);
+				onUpdate?.({
+					content: [{ type: "text", text: `Running ${params.tasks.length} agents...` }],
+					details: {
+						projectAgentsDir,
+						results: [],
+						totalDurationMs: Date.now() - startTime,
+						progress,
+					},
+				});
+			};
+
+			try {
+				const tasks = params.tasks;
+
+				// Validate all agents exist
+				for (const task of tasks) {
+					if (!getAgent(agents, task.agent)) {
+						const available = agents.map((a) => a.name).join(", ");
+						return {
+							content: [{ type: "text", text: `Unknown agent: ${task.agent}. Available: ${available}` }],
+							details: {
+								projectAgentsDir,
+								results: [],
+								totalDurationMs: Date.now() - startTime,
+							},
+						};
+					}
+				}
+
+				// Initialize progress for all tasks
+				for (let i = 0; i < tasks.length; i++) {
+					const agentCfg = getAgent(agents, tasks[i].agent);
+					progressMap.set(i, {
+						index: i,
+						agent: tasks[i].agent,
+						agentSource: agentCfg?.source ?? "user",
+						status: "pending",
+						task: tasks[i].task,
+						recentTools: [],
+						recentOutput: [],
+						toolCount: 0,
+						tokens: 0,
+						durationMs: 0,
+						modelOverride: tasks[i].model,
+					});
+				}
+				emitProgress();
+
+				// Build full prompts with context prepended
+				const tasksWithContext = tasks.map((t) => ({
+					agent: t.agent,
+					task: context ? `${context}\n\n${t.task}` : t.task,
+					model: t.model,
+				}));
+
+				// Execute in parallel with concurrency limit
+				const results = await mapWithConcurrencyLimit(tasksWithContext, MAX_CONCURRENCY, async (task, index) => {
+					const agent = getAgent(agents, task.agent)!;
+					return runSubprocess({
+						cwd,
+						agent,
+						task: task.task,
+						index,
+						context: undefined, // Already prepended above
+						modelOverride: task.model,
+						sessionFile,
+						persistArtifacts: !!artifactsDir,
+						artifactsDir: effectiveArtifactsDir,
+						signal,
+						onProgress: (progress) => {
+							progressMap.set(index, progress);
+							emitProgress();
+						},
+					});
+				});
+
+				// Write artifacts
+				const outputPaths: string[] = [];
+				for (const result of results) {
+					const fullTask = context ? `${context}\n\n${result.task}` : result.task;
+					const paths = await writeArtifacts(
+						effectiveArtifactsDir,
+						result.agent,
+						result.index,
+						fullTask,
+						result.output,
+						result.jsonlEvents,
+					);
+					outputPaths.push(paths.outputPath);
+					result.artifactPaths = paths;
+				}
+
+				// Build final output - match plugin format
+				const successCount = results.filter((r) => r.exitCode === 0).length;
+				const totalDuration = Date.now() - startTime;
+
+				const summaries = results.map((r, i) => {
+					const status = r.exitCode === 0 ? "completed" : `failed (exit ${r.exitCode})`;
+					const output = r.output.trim() || r.stderr.trim() || "(no output)";
+					const preview = output.split("\n").slice(0, 5).join("\n");
+					return `[${r.agent}] ${status} → ${outputPaths[i]}\n${preview}`;
+				});
+
+				const summary = `${successCount}/${results.length} succeeded [${formatDuration(totalDuration)}]\n\n${summaries.join("\n\n---\n\n")}`;
+
+				// Cleanup temp directory if used
+				if (tempArtifactsDir) {
+					await cleanupTempDir(tempArtifactsDir);
+				}
+
+				return {
+					content: [{ type: "text", text: summary }],
+					details: {
+						projectAgentsDir,
+						results,
+						totalDurationMs: totalDuration,
+						outputPaths,
+					},
+				};
+			} catch (err) {
+				// Cleanup temp directory on error
+				if (tempArtifactsDir) {
+					await cleanupTempDir(tempArtifactsDir);
+				}
+
+				return {
+					content: [{ type: "text", text: `Task execution failed: ${err}` }],
+					details: {
+						projectAgentsDir,
+						results: [],
+						totalDurationMs: Date.now() - startTime,
+					},
+				};
+			}
+		},
+	};
+}
+
+// Default task tool using process.cwd()
+export const taskTool = createTaskTool(process.cwd());

package/src/core/tools/task/model-resolver.ts

@@ -0,0 +1,115 @@
+/**
+ * Model resolution with fuzzy pattern matching.
+ *
+ * Supports:
+ *   - Exact match: "claude-opus-4-5"
+ *   - Fuzzy match: "opus" → "claude-opus-4-5"
+ *   - Comma fallback: "gpt, opus" → tries gpt first, then opus
+ *   - "default" → undefined (use system default)
+ */
+
+import { spawnSync } from "node:child_process";
+
+/** pi command: 'pi.cmd' on Windows, 'pi' elsewhere */
+const PI_CMD = process.platform === "win32" ? "pi.cmd" : "pi";
+
+/** Windows shell option for spawn/spawnSync */
+const PI_SHELL_OPT = process.platform === "win32";
+
+/** Cache for available models */
+let cachedModels: string[] | null = null;
+
+/** Cache expiry time (5 minutes) */
+let cacheExpiry = 0;
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * Get available models from `pi --list-models`.
+ * Caches the result for performance.
+ */
+export function getAvailableModels(): string[] {
+	const now = Date.now();
+	if (cachedModels !== null && now < cacheExpiry) {
+		return cachedModels;
+	}
+
+	try {
+		const result = spawnSync(PI_CMD, ["--list-models"], {
+			encoding: "utf-8",
+			timeout: 5000,
+			shell: PI_SHELL_OPT,
+		});
+
+		if (result.status !== 0 || !result.stdout) {
+			cachedModels = [];
+			cacheExpiry = now + CACHE_TTL_MS;
+			return cachedModels;
+		}
+
+		// Parse output: skip header line, extract model column
+		const lines = result.stdout.trim().split("\n");
+		cachedModels = lines
+			.slice(1) // Skip header
+			.map((line) => {
+				const parts = line.trim().split(/\s+/);
+				return parts[1]; // Model name is second column
+			})
+			.filter(Boolean);
+
+		cacheExpiry = now + CACHE_TTL_MS;
+		return cachedModels;
+	} catch {
+		cachedModels = [];
+		cacheExpiry = now + CACHE_TTL_MS;
+		return cachedModels;
+	}
+}
+
+/**
+ * Clear the model cache (for testing).
+ */
+export function clearModelCache(): void {
+	cachedModels = null;
+	cacheExpiry = 0;
+}
+
+/**
+ * Resolve a fuzzy model pattern to an actual model name.
+ *
+ * Supports comma-separated patterns (e.g., "gpt, opus") - tries each in order.
+ * Returns undefined if pattern is "default", undefined, or no match found.
+ *
+ * @param pattern - Model pattern to resolve
+ * @param availableModels - Optional pre-fetched list of available models
+ */
+export function resolveModelPattern(pattern: string | undefined, availableModels?: string[]): string | undefined {
+	if (!pattern || pattern === "default") {
+		return undefined;
+	}
+
+	const models = availableModels ?? getAvailableModels();
+	if (models.length === 0) {
+		// Fallback: return pattern as-is if we can't get available models
+		return pattern;
+	}
+
+	// Split by comma, try each pattern in order
+	const patterns = pattern
+		.split(",")
+		.map((p) => p.trim().toLowerCase())
+		.filter(Boolean);
+
+	for (const p of patterns) {
+		// Try exact match first
+		const exactMatch = models.find((m) => m.toLowerCase() === p);
+		if (exactMatch) return exactMatch;
+
+		// Try fuzzy match (substring)
+		const fuzzyMatch = models.find((m) => m.toLowerCase().includes(p));
+		if (fuzzyMatch) return fuzzyMatch;
+	}
+
+	// No match found - use default model
+	return undefined;
+}

package/src/core/tools/task/parallel.ts

@@ -0,0 +1,38 @@
+/**
+ * Parallel execution with concurrency control.
+ */
+
+import { MAX_CONCURRENCY } from "./types.js";
+
+/**
+ * Execute items with a concurrency limit using a worker pool pattern.
+ * Results are returned in the same order as input items.
+ *
+ * @param items - Items to process
+ * @param concurrency - Maximum concurrent operations
+ * @param fn - Async function to execute for each item
+ */
+export async function mapWithConcurrencyLimit<T, R>(
+	items: T[],
+	concurrency: number,
+	fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+	const limit = Math.max(1, Math.min(concurrency, items.length, MAX_CONCURRENCY));
+	const results: R[] = new Array(items.length);
+	let nextIndex = 0;
+
+	const worker = async (): Promise<void> => {
+		while (nextIndex < items.length) {
+			const index = nextIndex++;
+			results[index] = await fn(items[index], index);
+		}
+	};
+
+	// Create worker pool
+	const workers = Array(limit)
+		.fill(null)
+		.map(() => worker());
+
+	await Promise.all(workers);
+	return results;
+}