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

package/src/core/custom-tools/loader.ts

@@ -0,0 +1,248 @@
+/**
+ * Custom tool loader - loads TypeScript tool modules using native Bun import.
+ *
+ * Dependencies (@sinclair/typebox and pi-coding-agent) are injected via the CustomToolAPI
+ * to avoid import resolution issues with custom tools loaded from user directories.
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+import * as typebox from "@sinclair/typebox";
+import { toolCapability } from "../../capability/tool";
+import { type CustomTool, loadSync } from "../../discovery";
+import * as piCodingAgent from "../../index";
+import { theme } from "../../modes/interactive/theme/theme";
+import type { ExecOptions } from "../exec";
+import { execCommand } from "../exec";
+import type { HookUIContext } from "../hooks/types";
+import { logger } from "../logger";
+import { getAllPluginToolPaths } from "../plugins/loader";
+import type { CustomToolAPI, CustomToolFactory, CustomToolsLoadResult, LoadedCustomTool } from "./types";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+function normalizeUnicodeSpaces(str: string): string {
+	return str.replace(UNICODE_SPACES, " ");
+}
+
+function expandPath(p: string): string {
+	const normalized = normalizeUnicodeSpaces(p);
+	if (normalized.startsWith("~/")) {
+		return path.join(os.homedir(), normalized.slice(2));
+	}
+	if (normalized.startsWith("~")) {
+		return path.join(os.homedir(), normalized.slice(1));
+	}
+	return normalized;
+}
+
+/**
+ * Resolve tool path.
+ * - Absolute paths used as-is
+ * - Paths starting with ~ expanded to home directory
+ * - Relative paths resolved from cwd
+ */
+function resolveToolPath(toolPath: string, cwd: string): string {
+	const expanded = expandPath(toolPath);
+
+	if (path.isAbsolute(expanded)) {
+		return expanded;
+	}
+
+	// Relative paths resolved from cwd
+	return path.resolve(cwd, expanded);
+}
+
+/**
+ * Create a no-op UI context for headless modes.
+ */
+function createNoOpUIContext(): HookUIContext {
+	return {
+		select: async () => undefined,
+		confirm: async () => false,
+		input: async () => undefined,
+		notify: () => {},
+		setStatus: () => {},
+		custom: async () => undefined as never,
+		setEditorText: () => {},
+		getEditorText: () => "",
+		editor: async () => undefined,
+		get theme() {
+			return theme;
+		},
+	};
+}
+
+/** Error with source metadata */
+interface ToolLoadError {
+	path: string;
+	error: string;
+	source?: { provider: string; providerName: string; level: "user" | "project" };
+}
+
+/**
+ * Load a single tool module using native Bun import.
+ */
+async function loadTool(
+	toolPath: string,
+	cwd: string,
+	sharedApi: CustomToolAPI,
+	source?: { provider: string; providerName: string; level: "user" | "project" },
+): Promise<{ tools: LoadedCustomTool[] | null; error: ToolLoadError | null }> {
+	const resolvedPath = resolveToolPath(toolPath, cwd);
+
+	// Skip declarative tool files (.md, .json) - these are metadata only, not executable modules
+	if (resolvedPath.endsWith(".md") || resolvedPath.endsWith(".json")) {
+		return {
+			tools: null,
+			error: {
+				path: toolPath,
+				error: "Declarative tool files (.md, .json) cannot be loaded as executable modules",
+				source,
+			},
+		};
+	}
+
+	try {
+		const module = await import(resolvedPath);
+		const factory = (module.default ?? module) as CustomToolFactory;
+
+		if (typeof factory !== "function") {
+			return { tools: null, error: { path: toolPath, error: "Tool must export a default function", source } };
+		}
+
+		const toolResult = await factory(sharedApi);
+		const toolsArray = Array.isArray(toolResult) ? toolResult : [toolResult];
+
+		const loadedTools: LoadedCustomTool[] = toolsArray.map((tool) => ({
+			path: toolPath,
+			resolvedPath,
+			tool,
+			source,
+		}));
+
+		return { tools: loadedTools, error: null };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { tools: null, error: { path: toolPath, error: `Failed to load tool: ${message}`, source } };
+	}
+}
+
+/** Tool path with optional source metadata */
+interface ToolPathWithSource {
+	path: string;
+	source?: { provider: string; providerName: string; level: "user" | "project" };
+}
+
+/**
+ * Load all tools from configuration.
+ * @param pathsWithSources - Array of tool paths with optional source metadata
+ * @param cwd - Current working directory for resolving relative paths
+ * @param builtInToolNames - Names of built-in tools to check for conflicts
+ */
+export async function loadCustomTools(
+	pathsWithSources: ToolPathWithSource[],
+	cwd: string,
+	builtInToolNames: string[],
+): Promise<CustomToolsLoadResult> {
+	const tools: LoadedCustomTool[] = [];
+	const errors: ToolLoadError[] = [];
+	const seenNames = new Set<string>(builtInToolNames);
+
+	// Shared API object - all tools get the same instance
+	const sharedApi: CustomToolAPI = {
+		cwd,
+		exec: (command: string, args: string[], options?: ExecOptions) =>
+			execCommand(command, args, options?.cwd ?? cwd, options),
+		ui: createNoOpUIContext(),
+		hasUI: false,
+		logger,
+		typebox,
+		pi: piCodingAgent,
+	};
+
+	for (const { path: toolPath, source } of pathsWithSources) {
+		const { tools: loadedTools, error } = await loadTool(toolPath, cwd, sharedApi, source);
+
+		if (error) {
+			errors.push(error);
+			continue;
+		}
+
+		if (loadedTools) {
+			for (const loadedTool of loadedTools) {
+				// Check for name conflicts
+				if (seenNames.has(loadedTool.tool.name)) {
+					errors.push({
+						path: toolPath,
+						error: `Tool name "${loadedTool.tool.name}" conflicts with existing tool`,
+						source,
+					});
+					continue;
+				}
+
+				seenNames.add(loadedTool.tool.name);
+				tools.push(loadedTool);
+			}
+		}
+	}
+
+	return {
+		tools,
+		errors,
+		setUIContext(uiContext, hasUI) {
+			sharedApi.ui = uiContext;
+			sharedApi.hasUI = hasUI;
+		},
+	};
+}
+
+/**
+ * Discover and load tools from standard locations via capability system:
+ * 1. User and project tools discovered by capability providers
+ * 2. Installed plugins (~/.omp/plugins/node_modules/*)
+ * 3. Explicitly configured paths from settings or CLI
+ *
+ * @param configuredPaths - Explicit paths from settings.json and CLI --tool flags
+ * @param cwd - Current working directory
+ * @param builtInToolNames - Names of built-in tools to check for conflicts
+ */
+export async function discoverAndLoadCustomTools(
+	configuredPaths: string[],
+	cwd: string,
+	builtInToolNames: string[],
+): Promise<CustomToolsLoadResult> {
+	const allPathsWithSources: ToolPathWithSource[] = [];
+	const seen = new Set<string>();
+
+	// Helper to add paths without duplicates
+	const addPath = (p: string, source?: { provider: string; providerName: string; level: "user" | "project" }) => {
+		const resolved = path.resolve(p);
+		if (!seen.has(resolved)) {
+			seen.add(resolved);
+			allPathsWithSources.push({ path: p, source });
+		}
+	};
+
+	// 1. Discover tools via capability system (user + project from all providers)
+	const discoveredTools = loadSync<CustomTool>(toolCapability.id, { cwd });
+	for (const tool of discoveredTools.items) {
+		addPath(tool.path, {
+			provider: tool._source.provider,
+			providerName: tool._source.providerName,
+			level: tool.level,
+		});
+	}
+
+	// 2. Plugin tools: ~/.omp/plugins/node_modules/*/
+	for (const pluginPath of getAllPluginToolPaths(cwd)) {
+		addPath(pluginPath, { provider: "plugin", providerName: "Plugin", level: "user" });
+	}
+
+	// 3. Explicitly configured paths (can override/add)
+	for (const configPath of configuredPaths) {
+		addPath(resolveToolPath(configPath, cwd), { provider: "config", providerName: "Config", level: "project" });
+	}
+
+	return loadCustomTools(allPathsWithSources, cwd, builtInToolNames);
+}

package/src/core/custom-tools/types.ts

@@ -0,0 +1,185 @@
+/**
+ * Custom tool types.
+ *
+ * Custom tools are TypeScript modules that define additional tools for the agent.
+ * They can provide custom rendering for tool calls and results in the TUI.
+ */
+
+import type { AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { Model } from "@oh-my-pi/pi-ai";
+import type { Component } from "@oh-my-pi/pi-tui";
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { Theme } from "../../modes/interactive/theme/theme";
+import type { ExecOptions, ExecResult } from "../exec";
+import type { HookUIContext } from "../hooks/types";
+import type { Logger } from "../logger";
+import type { ModelRegistry } from "../model-registry";
+import type { ReadonlySessionManager } from "../session-manager";
+
+/** Alias for clarity */
+export type CustomToolUIContext = HookUIContext;
+
+/** Re-export for custom tools to use in execute signature */
+export type { AgentToolResult, AgentToolUpdateCallback };
+
+// Re-export for backward compatibility
+export type { ExecOptions, ExecResult } from "../exec";
+
+/** API passed to custom tool factory (stable across session changes) */
+export interface CustomToolAPI {
+	/** Current working directory */
+	cwd: string;
+	/** Execute a command */
+	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+	/** UI methods for user interaction (select, confirm, input, notify, custom) */
+	ui: CustomToolUIContext;
+	/** Whether UI is available (false in print/RPC mode) */
+	hasUI: boolean;
+	/** File logger for error/warning/debug messages */
+	logger: Logger;
+	/** Injected @sinclair/typebox module */
+	typebox: typeof import("@sinclair/typebox");
+	/** Injected pi-coding-agent exports */
+	pi: typeof import("../../index.js");
+}
+
+/**
+ * Context passed to tool execute and onSession callbacks.
+ * Provides access to session state and model information.
+ */
+export interface CustomToolContext {
+	/** Session manager (read-only) */
+	sessionManager: ReadonlySessionManager;
+	/** Model registry - use for API key resolution and model retrieval */
+	modelRegistry: ModelRegistry;
+	/** Current model (may be undefined if no model is selected yet) */
+	model: Model<any> | undefined;
+	/** Whether the agent is idle (not streaming) */
+	isIdle(): boolean;
+	/** Whether there are queued messages waiting to be processed */
+	hasQueuedMessages(): boolean;
+	/** Abort the current agent operation (fire-and-forget, does not wait) */
+	abort(): void;
+}
+
+/** Session event passed to onSession callback */
+export interface CustomToolSessionEvent {
+	/** Reason for the session event */
+	reason: "start" | "switch" | "branch" | "tree" | "shutdown";
+	/** Previous session file path, or undefined for "start" and "shutdown" */
+	previousSessionFile: string | undefined;
+}
+
+/** Rendering options passed to renderResult */
+export interface RenderResultOptions {
+	/** Whether the result view is expanded */
+	expanded: boolean;
+	/** Whether this is a partial/streaming result */
+	isPartial: boolean;
+	/** Current spinner frame index for animated elements (0-9, only provided during partial results) */
+	spinnerFrame?: number;
+}
+
+export type CustomToolResult<TDetails = any> = AgentToolResult<TDetails>;
+
+/**
+ * Custom tool definition.
+ *
+ * Custom tools are standalone - they don't extend AgentTool directly.
+ * When loaded, they are wrapped in an AgentTool for the agent to use.
+ *
+ * The execute callback receives a ToolContext with access to session state,
+ * model registry, and current model.
+ *
+ * @example
+ * ```typescript
+ * const factory: CustomToolFactory = (pi) => ({
+ *   name: "my_tool",
+ *   label: "My Tool",
+ *   description: "Does something useful",
+ *   parameters: Type.Object({ input: Type.String() }),
+ *
+ *   async execute(toolCallId, params, onUpdate, ctx, signal) {
+ *     // Access session state via ctx.sessionManager
+ *     // Access model registry via ctx.modelRegistry
+ *     // Current model via ctx.model
+ *     return { content: [{ type: "text", text: "Done" }] };
+ *   },
+ *
+ *   onSession(event, ctx) {
+ *     if (event.reason === "shutdown") {
+ *       // Cleanup
+ *     }
+ *     // Reconstruct state from ctx.sessionManager.getEntries()
+ *   }
+ * });
+ * ```
+ */
+export interface CustomTool<TParams extends TSchema = TSchema, TDetails = any> {
+	/** Tool name (used in LLM tool calls) */
+	name: string;
+	/** Human-readable label for UI */
+	label: string;
+	/** Description for LLM */
+	description: string;
+	/** Parameter schema (TypeBox) */
+	parameters: TParams;
+	/** If true, tool is excluded unless explicitly listed in --tools or agent's tools field */
+	hidden?: boolean;
+
+	/**
+	 * Execute the tool.
+	 * @param toolCallId - Unique ID for this tool call
+	 * @param params - Parsed parameters matching the schema
+	 * @param onUpdate - Callback for streaming partial results (for UI, not LLM)
+	 * @param ctx - Context with session manager, model registry, and current model
+	 * @param signal - Optional abort signal for cancellation
+	 */
+	execute(
+		toolCallId: string,
+		params: Static<TParams>,
+		onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
+		ctx: CustomToolContext,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<TDetails>>;
+
+	/** Called on session lifecycle events - use to reconstruct state or cleanup resources */
+	onSession?: (event: CustomToolSessionEvent, ctx: CustomToolContext) => void | Promise<void>;
+	/** Custom rendering for tool call display - return a Component */
+	renderCall?: (args: Static<TParams>, theme: Theme) => Component;
+
+	/** Custom rendering for tool result display - return a Component */
+	renderResult?: (result: CustomToolResult<TDetails>, options: RenderResultOptions, theme: Theme) => Component;
+}
+
+/** Factory function that creates a custom tool or array of tools */
+export type CustomToolFactory = (
+	pi: CustomToolAPI,
+) => CustomTool<any, any> | CustomTool<any, any>[] | Promise<CustomTool<any, any> | CustomTool<any, any>[]>;
+
+/** Loaded custom tool with metadata and wrapped AgentTool */
+export interface LoadedCustomTool {
+	/** Original path (as specified) */
+	path: string;
+	/** Resolved absolute path */
+	resolvedPath: string;
+	/** The original custom tool instance */
+	tool: CustomTool;
+	/** Source metadata (provider and level) */
+	source?: { provider: string; providerName: string; level: "user" | "project" };
+}
+
+/** Error with source metadata */
+export interface ToolLoadError {
+	path: string;
+	error: string;
+	source?: { provider: string; providerName: string; level: "user" | "project" };
+}
+
+/** Result from loading custom tools */
+export interface CustomToolsLoadResult {
+	tools: LoadedCustomTool[];
+	errors: ToolLoadError[];
+	/** Update the UI context for all loaded tools. Call when mode initializes. */
+	setUIContext(uiContext: CustomToolUIContext, hasUI: boolean): void;
+}

package/src/core/custom-tools/wrapper.ts

@@ -0,0 +1,29 @@
+/**
+ * Wraps CustomTool instances into AgentTool for use with the agent.
+ */
+
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import type { CustomTool, CustomToolContext, LoadedCustomTool } from "./types";
+
+/**
+ * Wrap a CustomTool into an AgentTool.
+ * The wrapper injects the ToolContext into execute calls.
+ */
+export function wrapCustomTool(tool: CustomTool, getContext: () => CustomToolContext): AgentTool {
+	return {
+		name: tool.name,
+		label: tool.label,
+		description: tool.description,
+		parameters: tool.parameters,
+		hidden: tool.hidden,
+		execute: (toolCallId, params, signal, onUpdate, context) =>
+			tool.execute(toolCallId, params, onUpdate, context ?? getContext(), signal),
+	};
+}
+
+/**
+ * Wrap all loaded custom tools into AgentTools.
+ */
+export function wrapCustomTools(loadedTools: LoadedCustomTool[], getContext: () => CustomToolContext): AgentTool[] {
+	return loadedTools.map((lt) => wrapCustomTool(lt.tool, getContext));
+}

package/src/core/exec.ts

@@ -0,0 +1,139 @@
+/**
+ * Shared command execution utilities for hooks and custom tools.
+ */
+
+import type { Subprocess } from "bun";
+import { logger } from "./logger";
+
+/**
+ * Options for executing shell commands.
+ */
+export interface ExecOptions {
+	/** AbortSignal to cancel the command */
+	signal?: AbortSignal;
+	/** Timeout in milliseconds */
+	timeout?: number;
+	/** Working directory */
+	cwd?: string;
+}
+
+/**
+ * Result of executing a shell command.
+ */
+export interface ExecResult {
+	stdout: string;
+	stderr: string;
+	code: number;
+	killed: boolean;
+}
+
+/**
+ * Execute a shell command and return stdout/stderr/code.
+ * Supports timeout and abort signal.
+ */
+export async function execCommand(
+	command: string,
+	args: string[],
+	cwd: string,
+	options?: ExecOptions,
+): Promise<ExecResult> {
+	return new Promise((resolve) => {
+		const proc: Subprocess = Bun.spawn([command, ...args], {
+			cwd,
+			stdin: "ignore",
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+
+		let stdout = "";
+		let stderr = "";
+		let killed = false;
+		let timeoutId: Timer | undefined;
+
+		const killProcess = () => {
+			if (!killed) {
+				killed = true;
+				proc.kill();
+				// Force kill after 5 seconds if first kill doesn't work
+				setTimeout(() => {
+					try {
+						proc.kill(9);
+					} catch {
+						// Ignore if already dead
+					}
+				}, 5000);
+			}
+		};
+
+		// Handle abort signal
+		if (options?.signal) {
+			if (options.signal.aborted) {
+				killProcess();
+			} else {
+				options.signal.addEventListener("abort", killProcess, { once: true });
+			}
+		}
+
+		// Handle timeout
+		if (options?.timeout && options.timeout > 0) {
+			timeoutId = setTimeout(() => {
+				killProcess();
+			}, options.timeout);
+		}
+
+		// Read streams asynchronously
+		(async () => {
+			try {
+				const stdoutReader = (proc.stdout as ReadableStream<Uint8Array>).getReader();
+				const stderrReader = (proc.stderr as ReadableStream<Uint8Array>).getReader();
+
+				// Read both streams and wait for process exit
+				const [stdoutResult, stderrResult, exitCode] = await Promise.all([
+					(async () => {
+						const chunks: Uint8Array[] = [];
+						try {
+							while (true) {
+								const { done, value } = await stdoutReader.read();
+								if (done) break;
+								chunks.push(value);
+							}
+						} finally {
+							stdoutReader.releaseLock();
+						}
+						return Buffer.concat(chunks).toString();
+					})(),
+					(async () => {
+						const chunks: Uint8Array[] = [];
+						try {
+							while (true) {
+								const { done, value } = await stderrReader.read();
+								if (done) break;
+								chunks.push(value);
+							}
+						} finally {
+							stderrReader.releaseLock();
+						}
+						return Buffer.concat(chunks).toString();
+					})(),
+					proc.exited,
+				]);
+
+				stdout = stdoutResult;
+				stderr = stderrResult;
+
+				if (timeoutId) clearTimeout(timeoutId);
+				if (options?.signal) {
+					options.signal.removeEventListener("abort", killProcess);
+				}
+				resolve({ stdout, stderr, code: exitCode ?? 0, killed });
+			} catch (err) {
+				logger.debug("Process stream error", { error: String(err) });
+				if (timeoutId) clearTimeout(timeoutId);
+				if (options?.signal) {
+					options.signal.removeEventListener("abort", killProcess);
+				}
+				resolve({ stdout, stderr, code: 1, killed });
+			}
+		})();
+	});
+}