@oh-my-pi/pi-coding-agent 3.21.0 → 3.24.0

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

@@ -0,0 +1,238 @@
+/**
+ * Worker thread for subagent execution.
+ *
+ * This worker runs in a separate thread via Bun's Worker API. It creates a minimal
+ * AgentSession and forwards events back to the parent thread.
+ *
+ * ## Event Flow
+ *
+ * 1. Parent sends { type: "start", payload } with task config
+ * 2. Worker creates AgentSession and subscribes to events
+ * 3. Worker forwards AgentEvent messages via postMessage
+ * 4. Worker sends { type: "done", exitCode, ... } on completion
+ * 5. Parent can send { type: "abort" } to request cancellation
+ */
+
+import type { Api, Model } from "@mariozechner/pi-ai";
+import type { AgentEvent, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { AgentSessionEvent } from "../../agent-session";
+import { parseModelPattern, parseModelString } from "../../model-resolver";
+import { createAgentSession, discoverAuthStorage, discoverModels } from "../../sdk";
+import { SessionManager } from "../../session-manager";
+import type { SubagentWorkerRequest, SubagentWorkerResponse, SubagentWorkerStartPayload } from "./worker-protocol";
+
+type PostMessageFn = (message: SubagentWorkerResponse) => void;
+
+const postMessageSafe: PostMessageFn = (message) => {
+	(globalThis as typeof globalThis & { postMessage: PostMessageFn }).postMessage(message);
+};
+
+interface WorkerMessageEvent<T> {
+	data: T;
+}
+
+/** Agent event types to forward to parent (excludes session-only events like compaction) */
+const agentEventTypes = new Set<AgentEvent["type"]>([
+	"agent_start",
+	"agent_end",
+	"turn_start",
+	"turn_end",
+	"message_start",
+	"message_update",
+	"message_end",
+	"tool_execution_start",
+	"tool_execution_update",
+	"tool_execution_end",
+]);
+
+const isAgentEvent = (event: AgentSessionEvent): event is AgentEvent => {
+	return agentEventTypes.has(event.type as AgentEvent["type"]);
+};
+
+let running = false;
+let abortRequested = false;
+let activeSession: { abort: () => Promise<void>; dispose: () => Promise<void> } | null = null;
+
+/**
+ * Resolve model string to Model object with optional thinking level.
+ * Supports both exact "provider/id" format and fuzzy matching ("sonnet", "opus").
+ */
+function resolveModelOverride(
+	override: string | undefined,
+	modelRegistry: { getAvailable: () => Model<Api>[]; find: (provider: string, id: string) => Model<Api> | undefined },
+): { model?: Model<Api>; thinkingLevel?: ThinkingLevel } {
+	if (!override) return {};
+
+	// Try exact "provider/id" format first
+	const parsed = parseModelString(override);
+	if (parsed) {
+		return { model: modelRegistry.find(parsed.provider, parsed.id) };
+	}
+
+	// Fall back to fuzzy pattern matching
+	const result = parseModelPattern(override, modelRegistry.getAvailable());
+	return {
+		model: result.model,
+		thinkingLevel: result.thinkingLevel !== "off" ? result.thinkingLevel : undefined,
+	};
+}
+
+/**
+ * Main task execution function.
+ *
+ * Equivalent to CLI flow:
+ * 1. omp --mode json --non-interactive
+ * 2. --append-system-prompt <agent.systemPrompt>
+ * 3. --tools <toolNames> (if specified)
+ * 4. --model <model> (if specified)
+ * 5. --session <sessionFile> OR --no-session
+ * 6. --prompt <task>
+ *
+ * Environment equivalent:
+ * - OMP_BLOCKED_AGENT: payload.blockedAgent (prevents same-agent recursion)
+ * - OMP_SPAWNS: payload.spawnsEnv (controls nested spawn permissions)
+ */
+async function runTask(payload: SubagentWorkerStartPayload): Promise<void> {
+	const startTime = Date.now();
+	let exitCode = 0;
+	let error: string | undefined;
+	let aborted = false;
+
+	try {
+		// Check for pre-start abort
+		if (abortRequested) {
+			aborted = true;
+			exitCode = 1;
+			return;
+		}
+
+		// Set working directory (CLI does this implicitly)
+		process.chdir(payload.cwd);
+
+		// Discover auth and models (equivalent to CLI's discoverAuthStorage/discoverModels)
+		const authStorage = await discoverAuthStorage();
+		const modelRegistry = await discoverModels(authStorage);
+
+		// Resolve model override (equivalent to CLI's parseModelPattern with --model)
+		const { model, thinkingLevel } = resolveModelOverride(payload.model, modelRegistry);
+
+		// Create session manager (equivalent to CLI's --session or --no-session)
+		const sessionManager = payload.sessionFile
+			? await SessionManager.open(payload.sessionFile)
+			: SessionManager.inMemory(payload.cwd);
+
+		// Create agent session (equivalent to CLI's createAgentSession)
+		// Note: hasUI: false disables interactive features
+		const { session } = await createAgentSession({
+			cwd: payload.cwd,
+			authStorage,
+			modelRegistry,
+			model,
+			thinkingLevel,
+			toolNames: payload.toolNames,
+			// Append system prompt (equivalent to CLI's --append-system-prompt)
+			systemPrompt: (defaultPrompt) => `${defaultPrompt}\n\n${payload.systemPrompt}`,
+			sessionManager,
+			hasUI: false,
+			// Pass spawn restrictions to nested tasks
+			spawns: payload.spawnsEnv,
+		});
+
+		activeSession = session;
+
+		// Initialize extensions (equivalent to CLI's extension initialization)
+		// Note: Does not support --extension CLI flag or extension CLI flags
+		const extensionRunner = session.extensionRunner;
+		if (extensionRunner) {
+			extensionRunner.initialize({
+				getModel: () => session.model,
+				sendMessageHandler: (message, options) => {
+					session.sendCustomMessage(message, options).catch((e) => {
+						console.error(`Extension sendMessage failed: ${e instanceof Error ? e.message : String(e)}`);
+					});
+				},
+				appendEntryHandler: (customType, data) => {
+					session.sessionManager.appendCustomEntry(customType, data);
+				},
+				getActiveToolsHandler: () => session.getActiveToolNames(),
+				getAllToolsHandler: () => session.getAllToolNames(),
+				setActiveToolsHandler: (toolNamesList: string[]) => session.setActiveToolsByName(toolNamesList),
+			});
+			extensionRunner.onError((err) => {
+				console.error(`Extension error (${err.extensionPath}): ${err.error}`);
+			});
+			await extensionRunner.emit({ type: "session_start" });
+		}
+
+		// Subscribe to events and forward to parent (equivalent to --mode json output)
+		session.subscribe((event: AgentSessionEvent) => {
+			if (isAgentEvent(event)) {
+				postMessageSafe({ type: "event", event });
+			}
+		});
+
+		// Run the prompt (equivalent to --prompt flag)
+		await session.prompt(payload.task);
+
+		// Check if aborted during execution
+		const lastMessage = session.state.messages[session.state.messages.length - 1];
+		if (lastMessage?.role === "assistant" && lastMessage.stopReason === "aborted") {
+			aborted = true;
+			exitCode = 1;
+		}
+	} catch (err) {
+		exitCode = 1;
+		error = err instanceof Error ? err.stack || err.message : String(err);
+	} finally {
+		// Handle abort requested during execution
+		if (abortRequested) {
+			aborted = true;
+			if (exitCode === 0) exitCode = 1;
+		}
+
+		// Cleanup session
+		if (activeSession) {
+			try {
+				await activeSession.dispose();
+			} catch {
+				// Ignore cleanup errors
+			}
+			activeSession = null;
+		}
+
+		// Send completion message to parent
+		postMessageSafe({
+			type: "done",
+			exitCode,
+			durationMs: Date.now() - startTime,
+			error,
+			aborted,
+		});
+	}
+}
+
+/** Handle abort request from parent */
+function handleAbort(): void {
+	abortRequested = true;
+	if (activeSession) {
+		void activeSession.abort();
+	}
+}
+
+// Message handler - receives start/abort commands from parent
+globalThis.addEventListener("message", (event: WorkerMessageEvent<SubagentWorkerRequest>) => {
+	const message = event.data;
+	if (!message) return;
+
+	if (message.type === "abort") {
+		handleAbort();
+		return;
+	}
+
+	if (message.type === "start") {
+		// Only allow one task per worker
+		if (running) return;
+		running = true;
+		void runTask(message.payload);
+	}
+});

package/src/core/tools/web-fetch.ts

@@ -5,6 +5,7 @@ import { Type } from "@sinclair/typebox";
 import { parse as parseHtml } from "node-html-parser";
 import webFetchDescription from "../../prompts/tools/web-fetch.md" with { type: "text" };
 import { logger } from "../logger";
+import type { ToolSession } from "./index";
 
 // =============================================================================
 // Types and Constants
@@ -1239,9 +1240,7 @@ async function handleStackOverflow(url: string, timeout: number): Promise<Render
 		md += `**Score:** ${question.score} · **Answers:** ${question.answer_count}`;
 		md += question.is_answered ? " (Answered)" : "";
 		md += `\n**Tags:** ${question.tags.join(", ")}\n`;
-		md += `**Asked by:** ${question.owner.display_name} · ${
-			new Date(question.creation_date * 1000).toISOString().split("T")[0]
-		}\n\n`;
+		md += `**Asked by:** ${question.owner.display_name} · ${new Date(question.creation_date * 1000).toISOString().split("T")[0]}\n\n`;
 		md += `---\n\n## Question\n\n${htmlToBasicMarkdown(question.body)}\n\n`;
 
 		// Fetch answers
@@ -2270,7 +2269,7 @@ export interface WebFetchToolDetails {
 	notes: string[];
 }
 
-export function createWebFetchTool(_cwd: string): AgentTool<typeof webFetchSchema> {
+export function createWebFetchTool(_session: ToolSession): AgentTool<typeof webFetchSchema> {
 	return {
 		name: "web_fetch",
 		label: "Web Fetch",
@@ -2316,9 +2315,6 @@ export function createWebFetchTool(_cwd: string): AgentTool<typeof webFetchSchem
 	};
 }
 
-/** Default web fetch tool using process.cwd() - for backwards compatibility */
-export const webFetchTool = createWebFetchTool(process.cwd());
-
 // =============================================================================
 // TUI Rendering
 // =============================================================================
@@ -2326,7 +2322,7 @@ export const webFetchTool = createWebFetchTool(process.cwd());
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { type Theme, theme } from "../../modes/interactive/theme/theme";
-import type { CustomTool, CustomToolContext, RenderResultOptions } from "../custom-tools/types";
+import type { RenderResultOptions } from "../custom-tools/types";
 
 /** Truncate text to max length with ellipsis */
 function truncate(text: string, maxLen: number, ellipsis: string): string {
@@ -2490,31 +2486,3 @@ export const webFetchToolRenderer = {
 	renderCall: renderWebFetchCall,
 	renderResult: renderWebFetchResult,
 };
-
-type WebFetchParams = { url: string; timeout?: number; raw?: boolean };
-
-/** Web fetch tool as CustomTool (for TUI rendering support) */
-export const webFetchCustomTool: CustomTool<typeof webFetchSchema, WebFetchToolDetails> = {
-	name: "web_fetch",
-	label: "Web Fetch",
-	description: webFetchDescription,
-	parameters: webFetchSchema,
-
-	async execute(
-		toolCallId: string,
-		params: WebFetchParams,
-		_onUpdate,
-		_ctx: CustomToolContext,
-		_signal?: AbortSignal,
-	) {
-		return webFetchTool.execute(toolCallId, params);
-	},
-
-	renderCall(args: WebFetchParams, uiTheme: Theme) {
-		return renderWebFetchCall(args, uiTheme);
-	},
-
-	renderResult(result, options: RenderResultOptions, uiTheme: Theme) {
-		return renderWebFetchResult(result, options, uiTheme);
-	},
-};

package/src/core/tools/web-search/index.ts

@@ -20,6 +20,7 @@ import type { CustomTool, CustomToolContext, RenderResultOptions } from "../../c
 import { callExaTool, findApiKey as findExaKey, formatSearchResults, isSearchResponse } from "../exa/mcp-client";
 import { renderExaCall, renderExaResult } from "../exa/render";
 import type { ExaRenderDetails } from "../exa/types";
+import type { ToolSession } from "../index";
 import { formatAge } from "../render-utils";
 import { findAnthropicAuth } from "./auth";
 import { searchAnthropic } from "./providers/anthropic";
@@ -365,7 +366,7 @@ export const webSearchCustomTool: CustomTool<typeof webSearchSchema, WebSearchRe
 };
 
 /** Factory function for backward compatibility */
-export function createWebSearchTool(_cwd: string): AgentTool<typeof webSearchSchema> {
+export function createWebSearchTool(_session: ToolSession): AgentTool<typeof webSearchSchema> {
 	return webSearchTool;
 }
 

package/src/core/tools/web-search/render.ts

@@ -257,10 +257,7 @@ export function renderWebSearchResult(
 	}
 	if (response.requestId) {
 		metaLines.push(
-			`${theme.fg("muted", "Request:")} ${theme.fg(
-				"text",
-				truncate(response.requestId, MAX_REQUEST_ID_LEN, theme.format.ellipsis),
-			)}`,
+			`${theme.fg("muted", "Request:")} ${theme.fg("text", truncate(response.requestId, MAX_REQUEST_ID_LEN, theme.format.ellipsis))}`,
 		);
 	}
 	if (searchQueries.length > 0) {

package/src/core/tools/write.ts

@@ -5,7 +5,8 @@ import { Type } from "@sinclair/typebox";
 import { getLanguageFromPath, highlightCode, type Theme } from "../../modes/interactive/theme/theme";
 import writeDescription from "../../prompts/tools/write.md" with { type: "text" };
 import type { RenderResultOptions } from "../custom-tools/types";
-import { type FileDiagnosticsResult, type WritethroughCallback, writethroughNoop } from "./lsp/index";
+import type { ToolSession } from "../sdk";
+import { createLspWritethrough, type FileDiagnosticsResult } from "./lsp/index";
 import { resolveToCwd } from "./path-utils";
 import { formatDiagnostics, replaceTabs, shortenPath } from "./render-utils";
 
@@ -14,21 +15,15 @@ const writeSchema = Type.Object({
 	content: Type.String({ description: "Content to write to the file" }),
 });
 
-/** Options for creating the write tool */
-export interface WriteToolOptions {
-	writethrough?: WritethroughCallback;
-}
-
 /** Details returned by the write tool for TUI rendering */
 export interface WriteToolDetails {
 	diagnostics?: FileDiagnosticsResult;
 }
 
-export function createWriteTool(
-	cwd: string,
-	options: WriteToolOptions = {},
-): AgentTool<typeof writeSchema, WriteToolDetails> {
-	const writethrough = options.writethrough ?? writethroughNoop;
+export function createWriteTool(session: ToolSession): AgentTool<typeof writeSchema, WriteToolDetails> {
+	const enableFormat = session.settings?.getLspFormatOnWrite() ?? true;
+	const enableDiagnostics = session.settings?.getLspDiagnosticsOnWrite() ?? true;
+	const writethrough = createLspWritethrough(session.cwd, { enableFormat, enableDiagnostics });
 	return {
 		name: "write",
 		label: "Write",
@@ -39,7 +34,7 @@ export function createWriteTool(
 			{ path, content }: { path: string; content: string },
 			signal?: AbortSignal,
 		) => {
-			const absolutePath = resolveToCwd(path, cwd);
+			const absolutePath = resolveToCwd(path, session.cwd);
 
 			const diagnostics = await writethrough(absolutePath, content, signal);
 
@@ -64,9 +59,6 @@ export function createWriteTool(
 	};
 }
 
-/** Default write tool using process.cwd() - for backwards compatibility */
-export const writeTool = createWriteTool(process.cwd());
-
 // =============================================================================
 // TUI Renderer
 // =============================================================================

package/src/discovery/helpers.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test } from "bun:test";
 import { parseFrontmatter } from "./helpers";
 
 describe("parseFrontmatter", () => {

package/src/index.ts

@@ -81,6 +81,8 @@ export { ModelRegistry } from "./core/model-registry";
 export type { PromptTemplate } from "./core/prompt-templates";
 // SDK for programmatic usage
 export {
+	// Tool factories
+	BUILTIN_TOOLS,
 	type BuildSystemPromptOptions,
 	buildSystemPrompt,
 	type CreateAgentSessionOptions,
@@ -88,14 +90,12 @@ export {
 	// Factory
 	createAgentSession,
 	createBashTool,
-	// Tool factories (for custom cwd)
-	createCodingTools,
 	createEditTool,
 	createFindTool,
 	createGrepTool,
 	createLsTool,
-	createReadOnlyTools,
 	createReadTool,
+	createTools,
 	createWriteTool,
 	// Discovery
 	discoverAuthStorage,
@@ -107,8 +107,7 @@ export {
 	discoverPromptTemplates,
 	discoverSkills,
 	loadSettings,
-	// Pre-built tools (use process.cwd())
-	readOnlyTools,
+	type ToolSession,
 } from "./core/sdk";
 export {
 	type BranchSummaryEntry,
@@ -154,27 +153,17 @@ export {
 } from "./core/skills";
 // Slash commands
 export { type FileSlashCommand, loadSlashCommands as discoverSlashCommands } from "./core/slash-commands";
-// Tools
+// Tools (detail types only - factories exported from sdk)
 export {
 	type BashToolDetails,
-	bashTool,
-	type CodingToolsOptions,
-	codingTools,
-	editTool,
 	type FindToolDetails,
-	findTool,
 	type GitToolDetails,
 	type GrepToolDetails,
 	gitTool,
-	grepTool,
 	type LsToolDetails,
-	lsTool,
 	type ReadToolDetails,
-	readTool,
 	type TruncationResult,
 	type WriteToolDetails,
-	type WriteToolOptions,
-	writeTool,
 } from "./core/tools/index";
 export type { FileDiagnosticsResult } from "./core/tools/lsp/index";
 // Main entry point

package/src/main.ts

@@ -24,7 +24,6 @@ import { SessionManager } from "./core/session-manager";
 import { SettingsManager } from "./core/settings-manager";
 import { resolvePromptInput } from "./core/system-prompt";
 import { printTimings, time } from "./core/timings";
-import { allTools } from "./core/tools/index";
 import { runMigrations, showDeprecationWarnings } from "./migrations";
 import { InteractiveMode, installTerminalCrashHandlers, runPrintMode, runRpcMode } from "./modes/index";
 import { initTheme, stopThemeWatcher } from "./modes/interactive/theme/theme";
@@ -210,7 +209,9 @@ async function buildSessionOptions(
 	modelRegistry: ModelRegistry,
 	settingsManager: SettingsManager,
 ): Promise<CreateAgentSessionOptions> {
-	const options: CreateAgentSessionOptions = {};
+	const options: CreateAgentSessionOptions = {
+		cwd: parsed.cwd ?? process.cwd(),
+	};
 
 	// Auto-discover SYSTEM.md if no CLI system prompt provided
 	const systemPromptSource = parsed.systemPrompt ?? discoverSystemPromptFile();
@@ -263,8 +264,7 @@ async function buildSessionOptions(
 
 	// Tools
 	if (parsed.tools) {
-		options.tools = parsed.tools.map((name) => allTools[name]);
-		options.explicitTools = parsed.tools;
+		options.toolNames = parsed.tools;
 	}
 
 	// Skills

package/src/modes/interactive/theme/theme.ts

@@ -1367,9 +1367,9 @@ export class Theme {
 		return (str: string) => this.fg("bashMode", str);
 	}
 
-	// -------------------------------------------------------------------------
+	// ============================================================================
 	// Symbol Methods
-	// -------------------------------------------------------------------------
+	// ============================================================================
 
 	/**
 	 * Get a symbol by key.
@@ -1392,9 +1392,9 @@ export class Theme {
 		return this.symbolPreset;
 	}
 
-	// -------------------------------------------------------------------------
+	// ============================================================================
 	// Symbol Category Accessors
-	// -------------------------------------------------------------------------
+	// ============================================================================
 
 	get status() {
 		return {

package/src/prompts/task.md

@@ -1,10 +1,3 @@
----
-name: task
-description: General-purpose subagent with full capabilities for delegated multi-step tasks
-spawns: explore
-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.

package/src/prompts/tools/output.md

@@ -1,16 +1,16 @@
-# TaskOutput
-
 Retrieves complete output from background tasks spawned with the Task tool.
 
 ## When to Use
 
 Use TaskOutput when:
+
 - Task tool returns truncated preview with "Output truncated" message
 - You need full output to debug errors or analyze detailed results
 - Task tool's summary shows substantial line/character counts but preview is incomplete
 - You're analyzing multi-step task output requiring full context
 
 Do NOT use when:
+
 - Task preview already shows complete output (no truncation indicator)
 - Summary alone answers your question
 

package/src/prompts/tools/task.md

@@ -0,0 +1,68 @@
+Launch a new agent to handle complex, multi-step tasks autonomously.
+
+The Task tool launches specialized agents (workers) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+
+## Available Agents
+
+{{AGENTS_LIST}}
+
+## When NOT to Use
+
+- Reading a specific file path → Use Read or Glob tool instead
+- Searching for a specific class/function definition → Use Glob tool instead
+- Searching code within 2-3 specific files → Use Read tool instead
+- Tasks unrelated to the agent descriptions above
+
+## Usage Notes
+
+- Always include a short description of the task in the task parameter
+- **Plan-then-execute**: Put shared constraints in `context`, keep each task focused, specify output format and acceptance criteria
+- **Minimize tool chatter**: Avoid repeating large context; use Output tool with output ids for full logs
+- **Parallelize**: Launch multiple agents concurrently whenever possible
+- **Results are intermediate data**: Agent findings provide context for YOU to perform actual work. Do not treat agent reports as "task complete" signals.
+- **Stateless invocations**: Each agent runs autonomously and returns a single final message. Include all necessary context and specify exactly what information to return.
+- **Trust outputs**: Agent results should generally be trusted
+- **Clarify intent**: Tell the agent whether you expect code changes or just research (search, file reads, web fetches)
+- **Proactive use**: If an agent description says to use it proactively, do so without waiting for explicit user request
+
+## Parameters
+
+- `tasks`: Array of `{agent, task, description?, model?}` - tasks to run in parallel (max {{MAX_PARALLEL_TASKS}}, {{MAX_CONCURRENCY}} concurrent)
+  - `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 omp's default model
+- `context`: (optional) Shared context string prepended to all task prompts - use this to avoid repeating instructions
+
+## Examples
+
+<example>
+user: "Please write a function that checks if a number is prime"
+assistant: Sure let me write a function that checks if a number is prime
+assistant: I'm going to use the Write tool to write the following code:
+<code>
+function isPrime(n) {
+  if (n <= 1) return false
+  for (let i = 2; i * i <= n; i++) {
+    if (n % i === 0) return false
+  }
+  return true
+}
+</code>
+<commentary>
+Since a significant piece of code was written and the task was completed, now use the code-reviewer agent to review the code
+</commentary>
+assistant: Now let me use the code-reviewer agent to review the code
+assistant: Uses the Task tool: { tasks: [{ agent: "code-reviewer", task: "Review the isPrime function" }] }
+</example>
+
+<example>
+user: "Find all TODO comments in the codebase"
+assistant: I'll use multiple explore agents to search different directories in parallel
+assistant: Uses the Task tool:
+{
+  "context": "Find all TODO comments. Return file:line:content format.",
+  "tasks": [
+    { "agent": "explore", "task": "Search in src/" },
+    { "agent": "explore", "task": "Search in lib/" },
+    { "agent": "explore", "task": "Search in tests/" }
+  ]
+}
+</example>