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

package/src/core/mcp/types.ts

@@ -0,0 +1,220 @@
+/**
+ * MCP (Model Context Protocol) type definitions.
+ *
+ * Based on MCP specification 2025-03-26:
+ * https://modelcontextprotocol.io/specification/2025-03-26/
+ */
+
+// =============================================================================
+// JSON-RPC 2.0 Types
+// =============================================================================
+
+export interface JsonRpcRequest {
+	jsonrpc: "2.0";
+	id: string | number;
+	method: string;
+	params?: Record<string, unknown>;
+}
+
+export interface JsonRpcNotification {
+	jsonrpc: "2.0";
+	method: string;
+	params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+	jsonrpc: "2.0";
+	id: string | number;
+	result?: unknown;
+	error?: JsonRpcError;
+}
+
+export interface JsonRpcError {
+	code: number;
+	message: string;
+	data?: unknown;
+}
+
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+
+// =============================================================================
+// MCP Server Configuration (.mcp.json format)
+// =============================================================================
+
+/** Stdio server configuration */
+export interface MCPStdioServerConfig {
+	type?: "stdio"; // Default if not specified
+	command: string;
+	args?: string[];
+	env?: Record<string, string>;
+	cwd?: string;
+}
+
+/** HTTP server configuration (Streamable HTTP transport) */
+export interface MCPHttpServerConfig {
+	type: "http";
+	url: string;
+	headers?: Record<string, string>;
+}
+
+/** SSE server configuration (deprecated, use HTTP) */
+export interface MCPSseServerConfig {
+	type: "sse";
+	url: string;
+	headers?: Record<string, string>;
+}
+
+export type MCPServerConfig = MCPStdioServerConfig | MCPHttpServerConfig | MCPSseServerConfig;
+
+/** Root .mcp.json file structure */
+export interface MCPConfigFile {
+	mcpServers?: Record<string, MCPServerConfig>;
+}
+
+// =============================================================================
+// MCP Protocol Types
+// =============================================================================
+
+/** MCP implementation info */
+export interface MCPImplementation {
+	name: string;
+	version: string;
+}
+
+/** MCP client capabilities */
+export interface MCPClientCapabilities {
+	roots?: { listChanged?: boolean };
+	sampling?: Record<string, never>;
+	experimental?: Record<string, unknown>;
+}
+
+/** MCP server capabilities */
+export interface MCPServerCapabilities {
+	tools?: { listChanged?: boolean };
+	resources?: { subscribe?: boolean; listChanged?: boolean };
+	prompts?: { listChanged?: boolean };
+	logging?: Record<string, never>;
+	experimental?: Record<string, unknown>;
+}
+
+/** Initialize request params */
+export interface MCPInitializeParams {
+	protocolVersion: string;
+	capabilities: MCPClientCapabilities;
+	clientInfo: MCPImplementation;
+}
+
+/** Initialize response result */
+export interface MCPInitializeResult {
+	protocolVersion: string;
+	capabilities: MCPServerCapabilities;
+	serverInfo: MCPImplementation;
+	instructions?: string;
+}
+
+/** MCP tool definition */
+export interface MCPToolDefinition {
+	name: string;
+	description?: string;
+	inputSchema: {
+		type: "object";
+		properties?: Record<string, unknown>;
+		required?: string[];
+		[key: string]: unknown;
+	};
+}
+
+/** tools/list response */
+export interface MCPToolsListResult {
+	tools: MCPToolDefinition[];
+	nextCursor?: string;
+}
+
+/** tools/call params */
+export interface MCPToolCallParams {
+	name: string;
+	arguments?: Record<string, unknown>;
+}
+
+/** Content types in tool results */
+export interface MCPTextContent {
+	type: "text";
+	text: string;
+}
+
+export interface MCPImageContent {
+	type: "image";
+	data: string; // base64
+	mimeType: string;
+}
+
+export interface MCPResourceContent {
+	type: "resource";
+	resource: {
+		uri: string;
+		mimeType?: string;
+		text?: string;
+		blob?: string;
+	};
+}
+
+export type MCPContent = MCPTextContent | MCPImageContent | MCPResourceContent;
+
+/** tools/call response */
+export interface MCPToolCallResult {
+	content: MCPContent[];
+	isError?: boolean;
+}
+
+// =============================================================================
+// Transport Types
+// =============================================================================
+
+/** Transport interface - abstracts stdio/http */
+export interface MCPTransport {
+	/** Send a request and wait for response */
+	request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+
+	/** Send a notification (no response expected) */
+	notify(method: string, params?: Record<string, unknown>): Promise<void>;
+
+	/** Close the transport */
+	close(): Promise<void>;
+
+	/** Whether the transport is connected */
+	readonly connected: boolean;
+
+	/** Event handlers */
+	onClose?: () => void;
+	onError?: (error: Error) => void;
+	onNotification?: (method: string, params: unknown) => void;
+}
+
+/** Transport factory function */
+export type TransportFactory = (config: MCPServerConfig) => Promise<MCPTransport>;
+
+// =============================================================================
+// MCP Client Types
+// =============================================================================
+
+/** Connected MCP server state */
+export interface MCPServerConnection {
+	/** Server name from config */
+	name: string;
+	/** Original config */
+	config: MCPServerConfig;
+	/** Transport instance */
+	transport: MCPTransport;
+	/** Server info from initialize */
+	serverInfo: MCPImplementation;
+	/** Server capabilities */
+	capabilities: MCPServerCapabilities;
+	/** Cached tools (populated on demand) */
+	tools?: MCPToolDefinition[];
+}
+
+/** MCP tool with server context */
+export interface MCPToolWithServer {
+	server: MCPServerConnection;
+	tool: MCPToolDefinition;
+}

package/src/core/messages.ts

@@ -0,0 +1,189 @@
+/**
+ * Custom message types and transformers for the coding agent.
+ *
+ * Extends the base AgentMessage type with coding-agent specific message types,
+ * and provides a transformer to convert them to LLM-compatible messages.
+ */
+
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { ImageContent, Message, TextContent } from "@oh-my-pi/pi-ai";
+
+export const COMPACTION_SUMMARY_PREFIX = `The conversation history before this point was compacted into the following summary:
+
+<summary>
+`;
+
+export const COMPACTION_SUMMARY_SUFFIX = `
+</summary>`;
+
+export const BRANCH_SUMMARY_PREFIX = `The following is a summary of a branch that this conversation came back from:
+
+<summary>
+`;
+
+export const BRANCH_SUMMARY_SUFFIX = `</summary>`;
+
+/**
+ * Message type for bash executions via the ! command.
+ */
+export interface BashExecutionMessage {
+	role: "bashExecution";
+	command: string;
+	output: string;
+	exitCode: number | undefined;
+	cancelled: boolean;
+	truncated: boolean;
+	fullOutputPath?: string;
+	timestamp: number;
+}
+
+/**
+ * Message type for hook-injected messages via sendMessage().
+ * These are custom messages that hooks can inject into the conversation.
+ */
+export interface HookMessage<T = unknown> {
+	role: "hookMessage";
+	customType: string;
+	content: string | (TextContent | ImageContent)[];
+	display: boolean;
+	details?: T;
+	timestamp: number;
+}
+
+export interface BranchSummaryMessage {
+	role: "branchSummary";
+	summary: string;
+	fromId: string;
+	timestamp: number;
+}
+
+export interface CompactionSummaryMessage {
+	role: "compactionSummary";
+	summary: string;
+	tokensBefore: number;
+	timestamp: number;
+}
+
+// Extend CustomAgentMessages via declaration merging
+declare module "@oh-my-pi/pi-agent-core" {
+	interface CustomAgentMessages {
+		bashExecution: BashExecutionMessage;
+		hookMessage: HookMessage;
+		branchSummary: BranchSummaryMessage;
+		compactionSummary: CompactionSummaryMessage;
+	}
+}
+
+/**
+ * Convert a BashExecutionMessage to user message text for LLM context.
+ */
+export function bashExecutionToText(msg: BashExecutionMessage): string {
+	let text = `Ran \`${msg.command}\`\n`;
+	if (msg.output) {
+		text += `\`\`\`\n${msg.output}\n\`\`\``;
+	} else {
+		text += "(no output)";
+	}
+	if (msg.cancelled) {
+		text += "\n\n(command cancelled)";
+	} else if (msg.exitCode !== null && msg.exitCode !== undefined && msg.exitCode !== 0) {
+		text += `\n\nCommand exited with code ${msg.exitCode}`;
+	}
+	if (msg.truncated && msg.fullOutputPath) {
+		text += `\n\n[Output truncated. Full output: ${msg.fullOutputPath}]`;
+	}
+	return text;
+}
+
+export function createBranchSummaryMessage(summary: string, fromId: string, timestamp: string): BranchSummaryMessage {
+	return {
+		role: "branchSummary",
+		summary,
+		fromId,
+		timestamp: new Date(timestamp).getTime(),
+	};
+}
+
+export function createCompactionSummaryMessage(
+	summary: string,
+	tokensBefore: number,
+	timestamp: string,
+): CompactionSummaryMessage {
+	return {
+		role: "compactionSummary",
+		summary: summary,
+		tokensBefore,
+		timestamp: new Date(timestamp).getTime(),
+	};
+}
+
+/** Convert CustomMessageEntry to AgentMessage format */
+export function createHookMessage(
+	customType: string,
+	content: string | (TextContent | ImageContent)[],
+	display: boolean,
+	details: unknown | undefined,
+	timestamp: string,
+): HookMessage {
+	return {
+		role: "hookMessage",
+		customType,
+		content,
+		display,
+		details,
+		timestamp: new Date(timestamp).getTime(),
+	};
+}
+
+/**
+ * Transform AgentMessages (including custom types) to LLM-compatible Messages.
+ *
+ * This is used by:
+ * - Agent's transormToLlm option (for prompt calls and queued messages)
+ * - Compaction's generateSummary (for summarization)
+ * - Custom hooks and tools
+ */
+export function convertToLlm(messages: AgentMessage[]): Message[] {
+	return messages
+		.map((m): Message | undefined => {
+			switch (m.role) {
+				case "bashExecution":
+					return {
+						role: "user",
+						content: [{ type: "text", text: bashExecutionToText(m) }],
+						timestamp: m.timestamp,
+					};
+				case "hookMessage": {
+					const content = typeof m.content === "string" ? [{ type: "text" as const, text: m.content }] : m.content;
+					return {
+						role: "user",
+						content,
+						timestamp: m.timestamp,
+					};
+				}
+				case "branchSummary":
+					return {
+						role: "user",
+						content: [{ type: "text" as const, text: BRANCH_SUMMARY_PREFIX + m.summary + BRANCH_SUMMARY_SUFFIX }],
+						timestamp: m.timestamp,
+					};
+				case "compactionSummary":
+					return {
+						role: "user",
+						content: [
+							{ type: "text" as const, text: COMPACTION_SUMMARY_PREFIX + m.summary + COMPACTION_SUMMARY_SUFFIX },
+						],
+						timestamp: m.timestamp,
+					};
+				case "user":
+				case "assistant":
+				case "toolResult":
+					return m;
+				default:
+					// biome-ignore lint/correctness/noSwitchDeclarations: fine
+					const _exhaustiveCheck: never = m;
+					return undefined;
+			}
+		})
+		.filter((m) => m !== undefined);
+}