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

package/src/core/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Core modules shared between all run modes.
+ */
+
+export {
+	AgentSession,
+	type AgentSessionConfig,
+	type AgentSessionEvent,
+	type AgentSessionEventListener,
+	type ModelCycleResult,
+	type PromptOptions,
+	type SessionStats,
+} from "./agent-session";
+export { type BashExecutorOptions, type BashResult, executeBash } from "./bash-executor";
+export type { CompactionResult } from "./compaction/index";
+export {
+	type CustomTool,
+	type CustomToolAPI,
+	type CustomToolFactory,
+	type CustomToolsLoadResult,
+	type CustomToolUIContext,
+	discoverAndLoadCustomTools,
+	type ExecResult,
+	type LoadedCustomTool,
+	loadCustomTools,
+	type RenderResultOptions,
+} from "./custom-tools/index";
+export {
+	type HookAPI,
+	type HookContext,
+	type HookError,
+	type HookEvent,
+	type HookFactory,
+	HookRunner,
+	type HookUIContext,
+	loadHooks,
+} from "./hooks/index";
+export {
+	createMCPManager,
+	discoverAndLoadMCPTools,
+	loadAllMCPConfigs,
+	type MCPConfigFile,
+	type MCPLoadResult,
+	MCPManager,
+	type MCPServerConfig,
+	type MCPServerConnection,
+	type MCPToolDefinition,
+	type MCPToolDetails,
+	type MCPToolsLoadResult,
+	type MCPTransport,
+} from "./mcp/index";
+
+export * as utils from "./utils";

package/src/core/logger.ts

@@ -0,0 +1,112 @@
+/**
+ * Centralized file logger for omp.
+ *
+ * Logs to ~/.omp/logs/ with size-based rotation, supporting concurrent omp instances.
+ * Each log entry includes process.pid for traceability.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import winston from "winston";
+import DailyRotateFile from "winston-daily-rotate-file";
+import { CONFIG_DIR_NAME } from "../config";
+
+/** Get the logs directory (~/.omp/logs/) */
+function getLogsDir(): string {
+	return join(homedir(), CONFIG_DIR_NAME, "logs");
+}
+
+/** Ensure logs directory exists */
+function ensureLogsDir(): string {
+	const logsDir = getLogsDir();
+	if (!existsSync(logsDir)) {
+		mkdirSync(logsDir, { recursive: true });
+	}
+	return logsDir;
+}
+
+/** Custom format that includes pid and flattens metadata */
+const logFormat = winston.format.combine(
+	winston.format.timestamp({ format: "YYYY-MM-DDTHH:mm:ss.SSSZ" }),
+	winston.format.printf(({ timestamp, level, message, ...meta }) => {
+		const entry: Record<string, unknown> = {
+			timestamp,
+			level,
+			pid: process.pid,
+			message,
+		};
+		// Flatten metadata into entry
+		for (const [key, value] of Object.entries(meta)) {
+			if (key !== "level" && key !== "timestamp" && key !== "message") {
+				entry[key] = value;
+			}
+		}
+		return JSON.stringify(entry);
+	}),
+);
+
+/** Size-based rotating file transport */
+const fileTransport = new DailyRotateFile({
+	dirname: ensureLogsDir(),
+	filename: "omp.%DATE%.log",
+	datePattern: "YYYY-MM-DD",
+	maxSize: "10m",
+	maxFiles: 5,
+	zippedArchive: true,
+});
+
+/** The winston logger instance */
+const winstonLogger = winston.createLogger({
+	level: "debug",
+	format: logFormat,
+	transports: [fileTransport],
+	// Don't exit on error - logging failures shouldn't crash the app
+	exitOnError: false,
+});
+
+/** Logger type exposed to plugins and internal code */
+export interface Logger {
+	error(message: string, context?: Record<string, unknown>): void;
+	warn(message: string, context?: Record<string, unknown>): void;
+	debug(message: string, context?: Record<string, unknown>): void;
+}
+
+/**
+ * Centralized logger for omp.
+ *
+ * Logs to ~/.omp/logs/omp.YYYY-MM-DD.log with size-based rotation.
+ * Safe for concurrent access from multiple omp instances.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from "../core/logger";
+ *
+ * logger.error("MCP request failed", { url, method });
+ * logger.warn("Theme file invalid, using fallback", { path });
+ * logger.debug("LSP fallback triggered", { reason });
+ * ```
+ */
+export const logger: Logger = {
+	error(message: string, context?: Record<string, unknown>): void {
+		try {
+			winstonLogger.error(message, context);
+		} catch {
+			// Silently ignore logging failures
+		}
+	},
+	warn(message: string, context?: Record<string, unknown>): void {
+		try {
+			winstonLogger.warn(message, context);
+		} catch {
+			// Silently ignore logging failures
+		}
+	},
+	debug(message: string, context?: Record<string, unknown>): void {
+		try {
+			winstonLogger.debug(message, context);
+		} catch {
+			// Silently ignore logging failures
+		}
+	},
+};

package/src/core/mcp/client.ts

@@ -0,0 +1,185 @@
+/**
+ * MCP Client.
+ *
+ * Handles connection initialization, tool listing, and tool calling.
+ */
+
+import { createHttpTransport } from "./transports/http";
+import { createStdioTransport } from "./transports/stdio";
+import type {
+	MCPHttpServerConfig,
+	MCPInitializeParams,
+	MCPInitializeResult,
+	MCPServerCapabilities,
+	MCPServerConfig,
+	MCPServerConnection,
+	MCPSseServerConfig,
+	MCPStdioServerConfig,
+	MCPToolCallParams,
+	MCPToolCallResult,
+	MCPToolDefinition,
+	MCPToolsListResult,
+	MCPTransport,
+} from "./types";
+
+/** MCP protocol version we support */
+const PROTOCOL_VERSION = "2025-03-26";
+
+/** Default connection timeout in ms */
+const CONNECTION_TIMEOUT_MS = 30_000;
+
+/** Client info sent during initialization */
+const CLIENT_INFO = {
+	name: "omp-coding-agent",
+	version: "1.0.0",
+};
+
+/** Wrap a promise with a timeout */
+function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(message)), ms);
+		promise.then(
+			(value) => {
+				clearTimeout(timer);
+				resolve(value);
+			},
+			(error) => {
+				clearTimeout(timer);
+				reject(error);
+			},
+		);
+	});
+}
+
+/**
+ * Create a transport for the given server config.
+ */
+async function createTransport(config: MCPServerConfig): Promise<MCPTransport> {
+	const serverType = config.type ?? "stdio";
+
+	switch (serverType) {
+		case "stdio":
+			return createStdioTransport(config as MCPStdioServerConfig);
+		case "http":
+		case "sse":
+			return createHttpTransport(config as MCPHttpServerConfig | MCPSseServerConfig);
+		default:
+			throw new Error(`Unknown server type: ${serverType}`);
+	}
+}
+
+/**
+ * Initialize connection with MCP server.
+ */
+async function initializeConnection(transport: MCPTransport): Promise<MCPInitializeResult> {
+	const params: MCPInitializeParams = {
+		protocolVersion: PROTOCOL_VERSION,
+		capabilities: {
+			roots: { listChanged: false },
+		},
+		clientInfo: CLIENT_INFO,
+	};
+
+	const result = await transport.request<MCPInitializeResult>(
+		"initialize",
+		params as unknown as Record<string, unknown>,
+	);
+
+	// Send initialized notification
+	await transport.notify("notifications/initialized");
+
+	return result;
+}
+
+/**
+ * Connect to an MCP server.
+ * Has a 30 second timeout to prevent blocking startup.
+ */
+export async function connectToServer(name: string, config: MCPServerConfig): Promise<MCPServerConnection> {
+	const timeoutMs = config.timeout ?? CONNECTION_TIMEOUT_MS;
+
+	const connect = async (): Promise<MCPServerConnection> => {
+		const transport = await createTransport(config);
+
+		try {
+			const initResult = await initializeConnection(transport);
+
+			return {
+				name,
+				config,
+				transport,
+				serverInfo: initResult.serverInfo,
+				capabilities: initResult.capabilities,
+			};
+		} catch (error) {
+			await transport.close();
+			throw error;
+		}
+	};
+
+	return withTimeout(connect(), timeoutMs, `Connection to MCP server "${name}" timed out after ${timeoutMs}ms`);
+}
+
+/**
+ * List tools from a connected server.
+ */
+export async function listTools(connection: MCPServerConnection): Promise<MCPToolDefinition[]> {
+	// Check if server supports tools
+	if (!connection.capabilities.tools) {
+		return [];
+	}
+
+	// Return cached tools if available
+	if (connection.tools) {
+		return connection.tools;
+	}
+
+	const allTools: MCPToolDefinition[] = [];
+	let cursor: string | undefined;
+
+	do {
+		const params: Record<string, unknown> = {};
+		if (cursor) {
+			params.cursor = cursor;
+		}
+
+		const result = await connection.transport.request<MCPToolsListResult>("tools/list", params);
+		allTools.push(...result.tools);
+		cursor = result.nextCursor;
+	} while (cursor);
+
+	// Cache tools
+	connection.tools = allTools;
+
+	return allTools;
+}
+
+/**
+ * Call a tool on a connected server.
+ */
+export async function callTool(
+	connection: MCPServerConnection,
+	toolName: string,
+	args: Record<string, unknown> = {},
+): Promise<MCPToolCallResult> {
+	const params: MCPToolCallParams = {
+		name: toolName,
+		arguments: args,
+	};
+
+	return connection.transport.request<MCPToolCallResult>("tools/call", params as unknown as Record<string, unknown>);
+}
+
+/**
+ * Disconnect from a server.
+ */
+export async function disconnectServer(connection: MCPServerConnection): Promise<void> {
+	await connection.transport.close();
+}
+
+/**
+ * Check if a server supports tools.
+ */
+export function serverSupportsTools(capabilities: MCPServerCapabilities): boolean {
+	return capabilities.tools !== undefined;
+}

package/src/core/mcp/config.ts

@@ -0,0 +1,248 @@
+/**
+ * MCP configuration loader.
+ *
+ * Uses the capability system to load MCP servers from multiple sources.
+ */
+
+import { mcpCapability } from "../../capability/mcp";
+import type { MCPServer } from "../../discovery";
+import { load } from "../../discovery";
+import type { MCPServerConfig } from "./types";
+
+/** Options for loading MCP configs */
+export interface LoadMCPConfigsOptions {
+	/** Whether to load project-level config (default: true) */
+	enableProjectConfig?: boolean;
+	/** Whether to filter out Exa MCP servers (default: true) */
+	filterExa?: boolean;
+}
+
+/** Result of loading MCP configs */
+export interface LoadMCPConfigsResult {
+	/** Loaded server configs */
+	configs: Record<string, MCPServerConfig>;
+	/** Extracted Exa API keys (if any were filtered) */
+	exaApiKeys: string[];
+	/** Source metadata for each server */
+	sources: Record<string, import("../../capability/types").SourceMeta>;
+}
+
+/**
+ * Convert canonical MCPServer to legacy MCPServerConfig.
+ */
+function convertToLegacyConfig(server: MCPServer): MCPServerConfig {
+	// Determine transport type
+	const transport = server.transport ?? (server.command ? "stdio" : server.url ? "http" : "stdio");
+
+	if (transport === "stdio") {
+		const config: MCPServerConfig = {
+			type: "stdio" as const,
+			command: server.command ?? "",
+		};
+		if (server.args) config.args = server.args;
+		if (server.env) config.env = server.env;
+		return config;
+	}
+
+	if (transport === "http") {
+		const config: MCPServerConfig = {
+			type: "http" as const,
+			url: server.url ?? "",
+		};
+		if (server.headers) config.headers = server.headers;
+		return config;
+	}
+
+	if (transport === "sse") {
+		const config: MCPServerConfig = {
+			type: "sse" as const,
+			url: server.url ?? "",
+		};
+		if (server.headers) config.headers = server.headers;
+		return config;
+	}
+
+	// Fallback to stdio
+	return {
+		type: "stdio" as const,
+		command: server.command ?? "",
+	};
+}
+
+/**
+ * Load all MCP server configs from standard locations.
+ * Uses the capability system for multi-source discovery.
+ *
+ * @param cwd Working directory (project root)
+ * @param options Load options
+ */
+export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOptions): Promise<LoadMCPConfigsResult> {
+	const enableProjectConfig = options?.enableProjectConfig ?? true;
+	const filterExa = options?.filterExa ?? true;
+
+	// Load MCP servers via capability system
+	const result = await load<MCPServer>(mcpCapability.id, { cwd });
+
+	// Filter out project-level configs if disabled
+	const servers = enableProjectConfig
+		? result.items
+		: result.items.filter((server) => server._source.level !== "project");
+
+	// Convert to legacy format and preserve source metadata
+	const configs: Record<string, MCPServerConfig> = {};
+	const sources: Record<string, import("../../capability/types").SourceMeta> = {};
+	for (const server of servers) {
+		configs[server.name] = convertToLegacyConfig(server);
+		sources[server.name] = server._source;
+	}
+
+	const exaApiKeys: string[] = [];
+
+	if (filterExa) {
+		const filterResult = filterExaMCPServers(configs, sources);
+		return { configs: filterResult.configs, exaApiKeys: filterResult.exaApiKeys, sources: filterResult.sources };
+	}
+
+	return { configs, exaApiKeys, sources };
+}
+
+/** Pattern to match Exa MCP servers */
+const EXA_MCP_URL_PATTERN = /mcp\.exa\.ai/i;
+const EXA_API_KEY_PATTERN = /exaApiKey=([^&\s]+)/i;
+
+/**
+ * Check if a server config is an Exa MCP server.
+ */
+export function isExaMCPServer(name: string, config: MCPServerConfig): boolean {
+	// Check by server name
+	if (name.toLowerCase() === "exa") {
+		return true;
+	}
+
+	// Check by URL for HTTP/SSE servers
+	if (config.type === "http" || config.type === "sse") {
+		const httpConfig = config as { url?: string };
+		if (httpConfig.url && EXA_MCP_URL_PATTERN.test(httpConfig.url)) {
+			return true;
+		}
+	}
+
+	// Check by args for stdio servers (e.g., mcp-remote to exa)
+	if (!config.type || config.type === "stdio") {
+		const stdioConfig = config as { args?: string[] };
+		if (stdioConfig.args?.some((arg) => EXA_MCP_URL_PATTERN.test(arg))) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Extract Exa API key from an MCP server config.
+ */
+export function extractExaApiKey(config: MCPServerConfig): string | undefined {
+	// Check URL for HTTP/SSE servers
+	if (config.type === "http" || config.type === "sse") {
+		const httpConfig = config as { url?: string };
+		if (httpConfig.url) {
+			const match = EXA_API_KEY_PATTERN.exec(httpConfig.url);
+			if (match) return match[1];
+		}
+	}
+
+	// Check args for stdio servers
+	if (!config.type || config.type === "stdio") {
+		const stdioConfig = config as { args?: string[] };
+		if (stdioConfig.args) {
+			for (const arg of stdioConfig.args) {
+				const match = EXA_API_KEY_PATTERN.exec(arg);
+				if (match) return match[1];
+			}
+		}
+	}
+
+	// Check env vars
+	if ("env" in config && config.env) {
+		const envConfig = config as { env: Record<string, string> };
+		if (envConfig.env.EXA_API_KEY) {
+			return envConfig.env.EXA_API_KEY;
+		}
+	}
+
+	return undefined;
+}
+
+/** Result of filtering Exa MCP servers */
+export interface ExaFilterResult {
+	/** Configs with Exa servers removed */
+	configs: Record<string, MCPServerConfig>;
+	/** Extracted Exa API keys (if any) */
+	exaApiKeys: string[];
+	/** Source metadata for remaining servers */
+	sources: Record<string, import("../../capability/types").SourceMeta>;
+}
+
+/**
+ * Filter out Exa MCP servers and extract their API keys.
+ * Since we have native Exa integration, we don't need the MCP server.
+ */
+export function filterExaMCPServers(
+	configs: Record<string, MCPServerConfig>,
+	sources: Record<string, import("../../capability/types").SourceMeta>,
+): ExaFilterResult {
+	const filtered: Record<string, MCPServerConfig> = {};
+	const filteredSources: Record<string, import("../../capability/types").SourceMeta> = {};
+	const exaApiKeys: string[] = [];
+
+	for (const [name, config] of Object.entries(configs)) {
+		if (isExaMCPServer(name, config)) {
+			// Extract API key before filtering
+			const apiKey = extractExaApiKey(config);
+			if (apiKey) {
+				exaApiKeys.push(apiKey);
+			}
+		} else {
+			filtered[name] = config;
+			if (sources[name]) {
+				filteredSources[name] = sources[name];
+			}
+		}
+	}
+
+	return { configs: filtered, exaApiKeys, sources: filteredSources };
+}
+
+/**
+ * Validate server config has required fields.
+ */
+export function validateServerConfig(name: string, config: MCPServerConfig): string[] {
+	const errors: string[] = [];
+
+	const serverType = config.type ?? "stdio";
+
+	// Check for conflicting transport fields
+	const hasCommand = "command" in config && config.command;
+	const hasUrl = "url" in config && (config as { url?: string }).url;
+	if (hasCommand && hasUrl) {
+		errors.push(
+			`Server "${name}": both "command" and "url" are set - server should be either stdio (command) OR http/sse (url), not both`,
+		);
+	}
+
+	if (serverType === "stdio") {
+		const stdioConfig = config as { command?: string };
+		if (!stdioConfig.command) {
+			errors.push(`Server "${name}": stdio server requires "command" field`);
+		}
+	} else if (serverType === "http" || serverType === "sse") {
+		const httpConfig = config as { url?: string };
+		if (!httpConfig.url) {
+			errors.push(`Server "${name}": ${serverType} server requires "url" field`);
+		}
+	} else {
+		errors.push(`Server "${name}": unknown server type "${serverType}"`);
+	}
+
+	return errors;
+}

package/src/core/mcp/index.ts

@@ -0,0 +1,45 @@
+/**
+ * MCP (Model Context Protocol) support.
+ *
+ * Provides per-project .mcp.json configuration for connecting to
+ * MCP servers via stdio or HTTP transports.
+ */
+
+// Client
+export { callTool, connectToServer, disconnectServer, listTools, serverSupportsTools } from "./client";
+
+// Config
+export type { ExaFilterResult, LoadMCPConfigsOptions, LoadMCPConfigsResult } from "./config";
+export {
+	extractExaApiKey,
+	filterExaMCPServers,
+	isExaMCPServer,
+	loadAllMCPConfigs,
+	validateServerConfig,
+} from "./config";
+// Loader (for SDK integration)
+export type { MCPToolsLoadOptions, MCPToolsLoadResult } from "./loader";
+export { discoverAndLoadMCPTools } from "./loader";
+// Manager
+export type { MCPDiscoverOptions, MCPLoadResult } from "./manager";
+export { createMCPManager, MCPManager } from "./manager";
+// Tool bridge
+export type { MCPToolDetails } from "./tool-bridge";
+export { createMCPTool, createMCPToolName, createMCPTools, parseMCPToolName } from "./tool-bridge";
+// Transports
+export { createHttpTransport, HttpTransport } from "./transports/http";
+export { createStdioTransport, StdioTransport } from "./transports/stdio";
+// Types
+export type {
+	MCPConfigFile,
+	MCPContent,
+	MCPHttpServerConfig,
+	MCPServerCapabilities,
+	MCPServerConfig,
+	MCPServerConnection,
+	MCPSseServerConfig,
+	MCPStdioServerConfig,
+	MCPToolDefinition,
+	MCPToolWithServer,
+	MCPTransport,
+} from "./types";