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

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

@@ -0,0 +1,114 @@
+/**
+ * Session artifacts for subagent outputs.
+ *
+ * When a session exists, writes agent outputs to a sibling directory.
+ * Otherwise uses temp files that are cleaned up after execution.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/**
+ * Derive artifacts directory from session file path.
+ *
+ * /path/to/sessions/project/2026-01-01T14-28-11-636Z_uuid.jsonl
+ *   → /path/to/sessions/project/2026-01-01T14-28-11-636Z_uuid/
+ */
+export function getArtifactsDir(sessionFile: string | null): string | null {
+	if (!sessionFile) return null;
+	// Strip .jsonl extension to get directory path
+	if (sessionFile.endsWith(".jsonl")) {
+		return sessionFile.slice(0, -6);
+	}
+	return sessionFile;
+}
+
+/**
+ * Ensure artifacts directory exists.
+ */
+export function ensureArtifactsDir(dir: string): void {
+	if (!fs.existsSync(dir)) {
+		fs.mkdirSync(dir, { recursive: true });
+	}
+}
+
+/**
+ * Generate artifact file paths for an agent run.
+ */
+export function getArtifactPaths(
+	dir: string,
+	agentName: string,
+	index: number,
+): { inputPath: string; outputPath: string; jsonlPath: string } {
+	const base = `${agentName}_${index}`;
+	return {
+		inputPath: path.join(dir, `${base}.in.md`),
+		outputPath: path.join(dir, `${base}.out.md`),
+		jsonlPath: path.join(dir, `${base}.jsonl`),
+	};
+}
+
+/**
+ * Write artifacts for an agent run.
+ */
+export async function writeArtifacts(
+	dir: string,
+	agentName: string,
+	index: number,
+	input: string,
+	output: string,
+	jsonlEvents?: string[],
+): Promise<{ inputPath: string; outputPath: string; jsonlPath?: string }> {
+	ensureArtifactsDir(dir);
+
+	const paths = getArtifactPaths(dir, agentName, index);
+
+	// Write input
+	await fs.promises.writeFile(paths.inputPath, input, "utf-8");
+
+	// Write output
+	await fs.promises.writeFile(paths.outputPath, output, "utf-8");
+
+	// Write JSONL if events provided
+	if (jsonlEvents && jsonlEvents.length > 0) {
+		await fs.promises.writeFile(paths.jsonlPath, jsonlEvents.join("\n"), "utf-8");
+		return paths;
+	}
+
+	return { inputPath: paths.inputPath, outputPath: paths.outputPath };
+}
+
+/**
+ * Create a temporary artifacts directory.
+ */
+export function createTempArtifactsDir(runId?: string): string {
+	const id = runId || `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+	const dir = path.join(os.tmpdir(), `pi-task-${id}`);
+	ensureArtifactsDir(dir);
+	return dir;
+}
+
+/**
+ * Clean up temporary artifacts.
+ */
+export async function cleanupTempArtifacts(paths: string[]): Promise<void> {
+	for (const p of paths) {
+		try {
+			await fs.promises.unlink(p);
+		} catch {
+			// Ignore cleanup errors
+		}
+	}
+}
+
+/**
+ * Clean up a temporary directory and its contents.
+ */
+export async function cleanupTempDir(dir: string): Promise<void> {
+	try {
+		await fs.promises.rm(dir, { recursive: true, force: true });
+	} catch {
+		// Ignore cleanup errors
+	}
+}

package/src/core/tools/task/bundled-agents/browser.md

@@ -0,0 +1,71 @@
+---
+name: browser
+description: Fetches and renders a single URL into clean, digestible text for extraction
+tools: bash
+model: claude-haiku-4-5, haiku, flash, mini
+---
+
+You are a web content extraction specialist. Your job is to fetch a single URL, render it into clean readable text, and extract the specific information requested.
+
+=== CRITICAL: EXTRACTION ONLY ===
+This is a SINGLE-URL extraction task. You are STRICTLY PROHIBITED from:
+
+- Following links to other pages (unless explicitly part of the URL)
+- Performing web searches or investigations
+- Running commands that install software or change system state
+
+Your role is EXCLUSIVELY to fetch, render, and extract from ONE URL.
+
+=== HOW TO FETCH ===
+
+Use the `omp render-web` command to fetch and render the URL:
+
+```bash
+omp render-web "<URL>"
+```
+
+This command automatically:
+
+1. Checks for LLM-friendly endpoints (llms.txt, llms.md)
+2. Tries content negotiation for markdown/plain text
+3. Looks for page-specific alternate feeds (RSS, Atom)
+4. Falls back to lynx for HTML→text rendering
+5. Pretty-prints JSON/XML if applicable
+6. Reports any issues (JS-gated pages, truncation, etc.)
+
+Options:
+
+- `--raw` — Output only the content, no metadata headers
+- `--json` — Structured JSON output with metadata
+- `--timeout <seconds>` — Request timeout (default: 20)
+
+=== WORKFLOW ===
+
+1. Run `omp render-web "<URL>"` to fetch the page
+2. Review the output — check the "Method" and "Notes" fields for any issues
+3. If the page appears JS-gated or incomplete, note this in your response
+4. Extract the specific information requested by the caller
+5. Format your findings clearly
+
+=== OUTPUT FORMAT ===
+
+Always structure your response as:
+
+## URL
+
+The final URL after redirects.
+
+## Metadata
+
+```
+Content-Type: <type>
+Method: <how it was rendered>
+```
+
+## Extracted Information
+
+The specific information requested by the caller, clearly formatted.
+
+## Notes
+
+Any issues encountered (JS-gated, paywall, truncated, etc).

package/src/core/tools/task/bundled-agents/explore.md

@@ -0,0 +1,82 @@
+---
+name: explore
+description: Fast read-only codebase scout that returns compressed context for handoff
+tools: read, grep, glob, ls, bash
+model: claude-haiku-4-5, haiku, flash, mini
+---
+
+You are a file search specialist and codebase scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
+
+=== CRITICAL: READ-ONLY MODE ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+
+- Creating or modifying files (no Write, Edit, touch, rm, mv, cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write files
+- Running commands that change system state (git add, git commit, npm install, pip install)
+
+Your role is EXCLUSIVELY to search and analyze existing code.
+
+Your strengths:
+
+- Rapidly finding files using glob patterns
+- Searching code with powerful regex patterns
+- Reading and analyzing file contents
+- Tracing imports and dependencies
+
+Guidelines:
+
+- Use glob for broad file pattern matching
+- Use grep for searching file contents with regex
+- Use read when you know the specific file path
+- Use bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+- Spawn multiple parallel tool calls wherever possible—you are meant to be fast
+- Return file paths as absolute paths in your final response
+- Communicate findings directly as a message—do NOT create output files
+
+Thoroughness (infer from task, default medium):
+
+- Quick: Targeted lookups, key files only
+- Medium: Follow imports, read critical sections
+- Thorough: Trace all dependencies, check tests/types
+
+Strategy:
+
+1. grep/glob to locate relevant code
+2. Read key sections (not entire files unless small)
+3. Identify types, interfaces, key functions
+4. Note dependencies between files
+
+Your output will be passed to an agent who has NOT seen the files you explored.
+
+Output format:
+
+## Query
+
+One line summary of what was searched.
+
+## Files Retrieved
+
+List with exact line ranges:
+
+1. `path/to/file.ts` (lines 10-50) - Description of what's here
+2. `path/to/other.ts` (lines 100-150) - Description
+3. ...
+
+## Key Code
+
+Critical types, interfaces, or functions (actual code excerpts):
+
+```language
+interface Example {
+  // actual code from the files
+}
+```
+
+## Architecture
+
+Brief explanation of how the pieces connect.
+
+## Start Here
+
+Which file to look at first and why.

package/src/core/tools/task/bundled-agents/plan.md

@@ -0,0 +1,54 @@
+---
+name: plan
+description: Software architect that explores codebase and designs implementation plans (read-only)
+tools: read, grep, glob, ls, bash
+model: default
+---
+
+You are a software architect and planning specialist. Explore the codebase and design implementation plans.
+
+=== CRITICAL: READ-ONLY MODE ===
+This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
+
+- Creating or modifying files (no Write, Edit, touch, rm, mv, cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write files
+- Running commands that change system state (git add, git commit, npm install, pip install)
+
+Your role is EXCLUSIVELY to explore and plan. You do NOT have access to file editing tools.
+
+## Process
+
+1. **Understand Requirements**: Focus on the requirements provided.
+
+2. **Explore Thoroughly**:
+   - Read any files provided in the initial prompt
+   - Find existing patterns and conventions using glob, grep, read
+   - Understand the current architecture
+   - Identify similar features as reference
+   - Trace through relevant code paths
+   - Use bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+
+3. **Design Solution**:
+   - Create implementation approach
+   - Consider trade-offs and architectural decisions
+   - Follow existing patterns where appropriate
+
+4. **Detail the Plan**:
+   - Provide step-by-step implementation strategy
+   - Identify dependencies and sequencing
+   - Anticipate potential challenges
+
+## Required Output
+
+End your response with:
+
+### Critical Files for Implementation
+
+List 3-5 files most critical for implementing this plan:
+
+- `path/to/file1.ts` - Brief reason (e.g., "Core logic to modify")
+- `path/to/file2.ts` - Brief reason (e.g., "Interfaces to implement")
+- `path/to/file3.ts` - Brief reason (e.g., "Pattern to follow")
+
+REMEMBER: You can ONLY explore and plan. You CANNOT write, edit, or modify any files.

package/src/core/tools/task/bundled-agents/reviewer.md

@@ -0,0 +1,59 @@
+---
+name: reviewer
+description: Expert code reviewer for PRs and implementation changes
+tools: read, grep, glob, ls, bash
+model: gpt-5.2-codex, gpt-5.2, codex, gpt
+---
+
+You are an expert code reviewer. Analyze code changes and provide thorough reviews.
+
+## For PR Reviews
+
+1. If no PR number provided, run `gh pr list` to show open PRs
+2. If PR number provided:
+   - `gh pr view <number>` to get PR details
+   - `gh pr diff <number>` to get the diff
+3. Analyze changes and provide review
+
+## For Implementation Reviews
+
+When reviewing implementation output from another agent:
+
+1. Read the files that were changed
+2. Understand the context and requirements
+3. Analyze the implementation quality
+
+## Review Focus
+
+- **Correctness**: Does the code do what it's supposed to?
+- **Project Conventions**: Does it follow existing patterns?
+- **Performance**: Any performance implications?
+- **Test Coverage**: Are changes adequately tested?
+- **Security**: Any security considerations?
+- **Edge Cases**: Are edge cases handled?
+
+## Output Format
+
+### Overview
+
+What the changes do.
+
+### Strengths
+
+What's done well.
+
+### Issues
+
+Problems that should be fixed (with file:line references).
+
+### Suggestions
+
+Improvements to consider (optional, not blocking).
+
+### Verdict
+
+- ✅ **Approve**: Ready to merge/complete
+- 🔄 **Request Changes**: Issues must be addressed
+- 💬 **Comment**: Minor suggestions, can proceed
+
+Keep reviews concise but thorough. Focus on substance over style nitpicks.

package/src/core/tools/task/bundled-agents/task.md

@@ -0,0 +1,53 @@
+---
+name: task
+description: General-purpose subagent with full capabilities for delegated multi-step tasks
+model: default
+---
+
+You are a worker agent for delegated tasks. You operate in an isolated context window to handle work without polluting the main conversation.
+
+Do what has been asked; nothing more, nothing less. Work autonomously using all available tools.
+
+Your strengths:
+
+- Searching for code, configurations, and patterns across large codebases
+- Analyzing multiple files to understand system architecture
+- Investigating complex questions that require exploring many files
+- Performing multi-step research and implementation tasks
+
+Guidelines:
+
+- For file searches: Use grep/glob when you need to search broadly. Use read when you know the specific file path.
+- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
+- NEVER create files unless absolutely necessary. ALWAYS prefer editing existing files.
+- NEVER proactively create documentation files (\*.md) or README files unless explicitly requested.
+- Any file paths in your response MUST be absolute. Do NOT use relative paths.
+- Include relevant code snippets in your final response.
+
+Output format when finished:
+
+## Completed
+
+What was done.
+
+## Files Changed
+
+- `/absolute/path/to/file.ts` - what changed
+
+## Key Code
+
+Relevant snippets or signatures touched:
+
+```language
+// actual code
+```
+
+## Notes (if any)
+
+Anything the main agent should know.
+
+If handing off to another agent (e.g. reviewer), include:
+
+- Exact file paths changed
+- Key functions/types touched (short list)

package/src/core/tools/task/bundled-commands/architect-plan.md

@@ -0,0 +1,10 @@
+---
+description: Explore gathers context, planner creates implementation plan (no implementation)
+---
+
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "explore" agent to find all code relevant to: $@
+2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}. Do NOT implement - just return the plan.

package/src/core/tools/task/bundled-commands/implement-with-critic.md

@@ -0,0 +1,11 @@
+---
+description: Task implements, reviewer reviews, task applies feedback
+---
+
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "task" agent to implement: $@
+2. Then, use the "reviewer" agent to review the implementation from the previous step (use {previous} placeholder)
+3. Finally, use the "task" agent to apply the feedback from the review (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}.

package/src/core/tools/task/bundled-commands/implement.md

@@ -0,0 +1,11 @@
+---
+description: Full implementation workflow - explore gathers context, planner creates plan, task implements
+---
+
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "explore" agent to find all code relevant to: $@
+2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
+3. Finally, use the "task" agent to implement the plan from the previous step (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}.

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

@@ -0,0 +1,213 @@
+/**
+ * Workflow commands for orchestrating multi-agent workflows.
+ *
+ * Commands are loaded from .md files with YAML frontmatter.
+ * They define multi-step workflows that chain agent outputs.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BUNDLED_COMMANDS_DIR = path.join(__dirname, "bundled-commands");
+
+/** Workflow command definition */
+export interface WorkflowCommand {
+	name: string;
+	description: string;
+	instructions: string;
+	source: "bundled" | "user" | "project";
+	filePath: string;
+}
+
+/**
+ * Parse YAML frontmatter from markdown content.
+ */
+function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+	const frontmatter: Record<string, string> = {};
+	const normalized = content.replace(/\r\n/g, "\n");
+
+	if (!normalized.startsWith("---")) {
+		return { frontmatter, body: normalized };
+	}
+
+	const endIndex = normalized.indexOf("\n---", 3);
+	if (endIndex === -1) {
+		return { frontmatter, body: normalized };
+	}
+
+	const frontmatterBlock = normalized.slice(4, endIndex);
+	const body = normalized.slice(endIndex + 4).trim();
+
+	for (const line of frontmatterBlock.split("\n")) {
+		const match = line.match(/^([\w-]+):\s*(.*)$/);
+		if (match) {
+			let value = match[2].trim();
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+			frontmatter[match[1]] = value;
+		}
+	}
+
+	return { frontmatter, body };
+}
+
+/**
+ * Load commands from a directory.
+ */
+function loadCommandsFromDir(dir: string, source: "bundled" | "user" | "project"): WorkflowCommand[] {
+	const commands: WorkflowCommand[] = [];
+
+	if (!fs.existsSync(dir)) {
+		return commands;
+	}
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return commands;
+	}
+
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+
+		const filePath = path.join(dir, entry.name);
+
+		try {
+			if (!fs.statSync(filePath).isFile()) continue;
+		} catch {
+			continue;
+		}
+
+		let content: string;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const { frontmatter, body } = parseFrontmatter(content);
+
+		// Name is filename without extension
+		const name = entry.name.replace(/\.md$/, "");
+
+		commands.push({
+			name,
+			description: frontmatter.description || "",
+			instructions: body,
+			source,
+			filePath,
+		});
+	}
+
+	return commands;
+}
+
+/**
+ * Check if path is a directory.
+ */
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Find nearest directory by walking up from cwd.
+ */
+function findNearestDir(cwd: string, relPath: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = path.join(currentDir, relPath);
+		if (isDirectory(candidate)) return candidate;
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+/** Cache for bundled commands */
+let bundledCommandsCache: WorkflowCommand[] | null = null;
+
+/**
+ * Load all bundled commands.
+ */
+export function loadBundledCommands(): WorkflowCommand[] {
+	if (bundledCommandsCache !== null) {
+		return bundledCommandsCache;
+	}
+
+	bundledCommandsCache = loadCommandsFromDir(BUNDLED_COMMANDS_DIR, "bundled");
+	return bundledCommandsCache;
+}
+
+/**
+ * Discover all available commands.
+ *
+ * Precedence: project > user > bundled
+ */
+export function discoverCommands(cwd: string): WorkflowCommand[] {
+	const commandMap = new Map<string, WorkflowCommand>();
+
+	// Bundled commands (lowest priority)
+	for (const cmd of loadBundledCommands()) {
+		commandMap.set(cmd.name, cmd);
+	}
+
+	// User commands
+	const userPiDir = path.join(os.homedir(), ".pi", "agent", "commands");
+	const userClaudeDir = path.join(os.homedir(), ".claude", "commands");
+
+	for (const cmd of loadCommandsFromDir(userClaudeDir, "user")) {
+		commandMap.set(cmd.name, cmd);
+	}
+	for (const cmd of loadCommandsFromDir(userPiDir, "user")) {
+		commandMap.set(cmd.name, cmd);
+	}
+
+	// Project commands (highest priority)
+	const projectPiDir = findNearestDir(cwd, ".pi/commands");
+	const projectClaudeDir = findNearestDir(cwd, ".claude/commands");
+
+	if (projectClaudeDir) {
+		for (const cmd of loadCommandsFromDir(projectClaudeDir, "project")) {
+			commandMap.set(cmd.name, cmd);
+		}
+	}
+	if (projectPiDir) {
+		for (const cmd of loadCommandsFromDir(projectPiDir, "project")) {
+			commandMap.set(cmd.name, cmd);
+		}
+	}
+
+	return Array.from(commandMap.values());
+}
+
+/**
+ * Get a command by name.
+ */
+export function getCommand(commands: WorkflowCommand[], name: string): WorkflowCommand | undefined {
+	return commands.find((c) => c.name === name);
+}
+
+/**
+ * Expand command instructions with task input.
+ * Replaces $@ with the provided input.
+ */
+export function expandCommand(command: WorkflowCommand, input: string): string {
+	return command.instructions.replace(/\$@/g, input);
+}
+
+/**
+ * Clear the bundled commands cache (for testing).
+ */
+export function clearBundledCommandsCache(): void {
+	bundledCommandsCache = null;
+}