@toolplex/ai-engine 0.1.0

package/src/core/ToolBuilder.ts

@@ -0,0 +1,323 @@
+/**
+ * @toolplex/ai-engine - Tool Builder
+ *
+ * Builds AI SDK tools from MCP tools, handling:
+ * - Schema cleaning and sanitization
+ * - Tool confirmation flows
+ * - Tool execution with cancellation support
+ */
+
+import { tool, jsonSchema } from "ai";
+import type { EngineAdapter } from "../adapters/types.js";
+import type {
+  MCPTool,
+  MCPToolResult,
+  ConfirmationRequest,
+} from "../types/index.js";
+import { deepSanitizeParams, cleanToolSchema } from "../utils/schema.js";
+import { isChatGPTModel, isGoogleGeminiModel } from "../utils/models.js";
+
+export interface BuildToolsOptions {
+  sessionId: string;
+  streamId: string;
+  modelId: string;
+  abortSignal: AbortSignal;
+  adapter: EngineAdapter;
+  /** Tools to hide from AI agents (e.g., 'initialize_toolplex') */
+  hiddenTools?: string[];
+  /** Callback for when tool args are edited during confirmation */
+  onArgsEdited?: (
+    toolName: string,
+    editedArgs: any,
+    configEdited: boolean,
+  ) => void;
+}
+
+/**
+ * Build AI SDK tools from MCP tools
+ */
+export async function buildMCPTools(
+  options: BuildToolsOptions,
+): Promise<Record<string, any>> {
+  const {
+    sessionId,
+    streamId,
+    modelId,
+    abortSignal,
+    adapter,
+    hiddenTools = ["initialize_toolplex"],
+    onArgsEdited,
+  } = options;
+
+  const logger = adapter.logger;
+  const isGemini = isGoogleGeminiModel(modelId);
+
+  // Get tools from MCP
+  const mcpToolsResult = await adapter.mcp.listTools(sessionId);
+  const mcpTools: MCPTool[] = mcpToolsResult?.tools || [];
+
+  const aiSdkTools: Record<string, any> = {};
+
+  // Track active tool executions for cancellation
+  const activeToolExecutions = new Map<string, AbortController>();
+
+  // Clean up when stream is aborted
+  abortSignal.addEventListener("abort", () => {
+    logger.debug(
+      "Tool builder: Stream aborted, cancelling active tool executions",
+      {
+        sessionId,
+        streamId,
+        activeToolCount: activeToolExecutions.size,
+      },
+    );
+
+    for (const [
+      toolExecutionId,
+      controller,
+    ] of activeToolExecutions.entries()) {
+      logger.debug("Tool builder: Aborting tool execution", {
+        toolExecutionId,
+      });
+      controller.abort();
+    }
+
+    activeToolExecutions.clear();
+  });
+
+  for (const mcpTool of mcpTools) {
+    // Skip hidden tools
+    if (hiddenTools.includes(mcpTool.name)) {
+      continue;
+    }
+
+    const toolSchema = mcpTool.inputSchema || {
+      type: "object",
+      properties: {},
+    };
+    const finalSchema = cleanToolSchema(toolSchema, isGemini, logger);
+
+    aiSdkTools[mcpTool.name] = tool({
+      description: mcpTool.description || `Tool: ${mcpTool.name}`,
+      inputSchema: jsonSchema<any>(finalSchema),
+      execute: async (params: any): Promise<MCPToolResult> => {
+        const toolExecutionId = `${mcpTool.name}-${Date.now()}`;
+        const toolAbortController = new AbortController();
+        activeToolExecutions.set(toolExecutionId, toolAbortController);
+
+        // Check if stream was already aborted
+        if (abortSignal.aborted) {
+          logger.debug(
+            "Tool builder: Stream already aborted, skipping tool execution",
+            {
+              toolName: mcpTool.name,
+              sessionId,
+            },
+          );
+          activeToolExecutions.delete(toolExecutionId);
+          throw new Error("Stream cancelled");
+        }
+
+        try {
+          // Normalize ChatGPT args -> arguments workaround
+          if (
+            mcpTool.name === "call_tool" &&
+            isChatGPTModel(modelId) &&
+            params?.args &&
+            !params?.arguments
+          ) {
+            logger.info(
+              "Tool builder: Normalizing call_tool params for ChatGPT",
+              {
+                modelId,
+                originalKeys: Object.keys(params),
+              },
+            );
+            const { args, ...rest } = params;
+            params = { ...rest, arguments: args };
+          }
+
+          // Deep sanitize params
+          const sanitizedParams = deepSanitizeParams(
+            params,
+            toolSchema,
+            undefined,
+            logger,
+          );
+
+          // Log when sanitization modifies parameters
+          if (JSON.stringify(params) !== JSON.stringify(sanitizedParams)) {
+            logger.debug(
+              "Tool builder: deepSanitizeParams modified tool arguments",
+              {
+                toolName: mcpTool.name,
+                sessionId,
+              },
+            );
+          }
+
+          // Check abort before confirmation
+          if (toolAbortController.signal.aborted) {
+            throw new Error("Tool execution cancelled");
+          }
+
+          // Handle confirmation if adapter supports it
+          let finalParams = sanitizedParams;
+
+          if (adapter.confirmations.isInteractive()) {
+            const confirmationRequest = await checkToolConfirmation(
+              mcpTool.name,
+              sanitizedParams,
+              { sessionId, streamId },
+            );
+
+            if (confirmationRequest) {
+              logger.debug("Tool builder: Tool requires user confirmation", {
+                sessionId,
+                toolName: mcpTool.name,
+                confirmationType: confirmationRequest.type,
+              });
+
+              try {
+                const result = await adapter.confirmations.requestConfirmation(
+                  streamId,
+                  confirmationRequest,
+                );
+
+                if (!result.allowed) {
+                  return {
+                    content: [
+                      {
+                        type: "text",
+                        text: `Operation cancelled: ${result.reason || "User denied the operation"}`,
+                      },
+                    ],
+                  };
+                }
+
+                // Apply edited config if provided
+                if (result.editedConfig) {
+                  finalParams = { ...sanitizedParams };
+                  if (confirmationRequest.type === "install") {
+                    finalParams.config = result.editedConfig;
+                  }
+
+                  if (onArgsEdited) {
+                    onArgsEdited(
+                      mcpTool.name,
+                      finalParams,
+                      result.wasEdited === true,
+                    );
+                  }
+                }
+              } catch (confirmationError: any) {
+                if (confirmationError?.message === "Stream cancelled by user") {
+                  throw new Error("Tool execution cancelled");
+                }
+                throw confirmationError;
+              }
+            }
+          }
+
+          // Check abort before MCP call
+          if (toolAbortController.signal.aborted) {
+            throw new Error("Tool execution cancelled");
+          }
+
+          // Execute the MCP tool
+          const result = await adapter.mcp.callTool(
+            sessionId,
+            mcpTool.name,
+            finalParams,
+          );
+
+          return result;
+        } catch (error: any) {
+          activeToolExecutions.delete(toolExecutionId);
+
+          if (
+            toolAbortController.signal.aborted ||
+            abortSignal.aborted ||
+            error?.message === "Tool execution cancelled"
+          ) {
+            throw new Error("Tool execution cancelled");
+          }
+
+          logger.error("Tool builder: Tool execution failed", {
+            sessionId,
+            toolName: mcpTool.name,
+            error,
+          });
+
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`,
+              },
+            ],
+          };
+        }
+      },
+    } as any);
+  }
+
+  return aiSdkTools;
+}
+
+/**
+ * Check if a tool requires confirmation
+ * This is a simplified version - the full implementation would be in the confirmation registry
+ */
+async function checkToolConfirmation(
+  toolName: string,
+  params: any,
+  _context: { sessionId: string; streamId: string },
+): Promise<ConfirmationRequest | null> {
+  // Install/uninstall operations always require confirmation
+  if (toolName === "install_server" || toolName === "install_mcp_server") {
+    return {
+      type: "install",
+      data: {
+        serverId: params.server_id,
+        serverName: params.server_name,
+        config: params.config,
+      },
+    };
+  }
+
+  if (toolName === "uninstall_server" || toolName === "uninstall_mcp_server") {
+    return {
+      type: "uninstall",
+      data: {
+        serverId: params.server_id,
+        serverName: params.server_name,
+      },
+    };
+  }
+
+  if (toolName === "save_playbook") {
+    return {
+      type: "save-playbook",
+      data: {
+        playbookName: params.playbook_name,
+        description: params.description,
+        actions: params.actions,
+        privacy: params.privacy,
+      },
+    };
+  }
+
+  if (toolName === "submit_feedback") {
+    return {
+      type: "submit-feedback",
+      data: {
+        vote: params.vote,
+        message: params.message,
+      },
+    };
+  }
+
+  return null;
+}

package/src/core/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @toolplex/ai-engine - Core Components
+ */
+
+export { ChatEngine, type ChatEngineOptions } from "./ChatEngine.js";
+export { buildMCPTools, type BuildToolsOptions } from "./ToolBuilder.js";

package/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * @toolplex/ai-engine
+ *
+ * Core AI chat engine for ToolPlex.
+ * Powers desktop, cloud, and CLI environments through adapter pattern.
+ *
+ * @example
+ * ```typescript
+ * import { ChatEngine, createElectronAdapter } from '@toolplex/ai-engine';
+ *
+ * const adapter = createElectronAdapter({ webContents });
+ * const engine = new ChatEngine(adapter);
+ *
+ * await engine.stream({
+ *   sessionId: 'session-123',
+ *   modelId: 'anthropic/claude-sonnet-4',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ * ```
+ */
+
+// Types
+export * from "./types/index.js";
+
+// Adapters
+export * from "./adapters/index.js";
+
+// Providers
+export {
+  getProvider,
+  getModel,
+  isProviderAvailable,
+  toolplexUsageMap,
+  type GetProviderOptions,
+} from "./providers/index.js";
+export { createToolPlex, type ToolPlexConfig } from "./providers/toolplex.js";
+
+// Utilities
+export {
+  deepSanitizeParams,
+  resolveSchemaRefs,
+  sanitizeSchemaForGemini,
+  cleanToolSchema,
+} from "./utils/schema.js";
+export {
+  isChatGPTModel,
+  isGoogleGeminiModel,
+  isAnthropicModel,
+  parseModelId,
+} from "./utils/models.js";
+
+// Core engine
+export { ChatEngine, type ChatEngineOptions } from "./core/ChatEngine.js";
+export { buildMCPTools, type BuildToolsOptions } from "./core/ToolBuilder.js";
+
+// MCP Client
+export { MCPClient } from "./mcp/MCPClient.js";
+export type {
+  MCPSession,
+  MCPResult,
+  MCPTool,
+  MCPToolResult,
+  TransportFactory,
+  MCPClientConfig,
+} from "./mcp/types.js";
+
+// MCP path utilities and default transport
+export { getToolplexClientPath } from "./mcp/paths.js";
+export {
+  DefaultStdioTransportFactory,
+  defaultStdioTransportFactory,
+} from "./mcp/DefaultStdioTransportFactory.js";
+
+// Re-export AI SDK primitives for consumers
+export { streamText, tool, jsonSchema, stepCountIs } from "ai";
+export type { ToolResultPart, ToolCallPart, TextPart, ImagePart } from "ai";
+
+// Re-export provider factory functions
+export { createOpenAI } from "@ai-sdk/openai";
+export { createAnthropic } from "@ai-sdk/anthropic";
+export { createGoogleGenerativeAI } from "@ai-sdk/google";
+export { createOpenRouter } from "@openrouter/ai-sdk-provider";
+
+// Re-export MCP SDK for transport implementations
+export { Client as MCPSDKClient } from "@modelcontextprotocol/sdk/client/index.js";
+export { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

package/src/mcp/DefaultStdioTransportFactory.ts

@@ -0,0 +1,71 @@
+/**
+ * @toolplex/ai-engine - Default Stdio Transport Factory
+ *
+ * Default implementation of TransportFactory that spawns @toolplex/client
+ * using the system's Node.js. This works out-of-box for CLI usage.
+ *
+ * For desktop apps with bundled dependencies, override this with a custom
+ * TransportFactory implementation.
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { TransportFactory, MCPSession } from "./types.js";
+import { getToolplexClientPath } from "./paths.js";
+
+/**
+ * Default Transport Factory - spawns @toolplex/client using system Node.js
+ *
+ * This is suitable for:
+ * - CLI applications
+ * - Development environments
+ * - Any context where system Node.js is available
+ *
+ * For Electron/desktop apps with bundled Node.js, create a custom
+ * TransportFactory that uses the bundled runtime.
+ */
+export class DefaultStdioTransportFactory implements TransportFactory {
+  async createTransport(
+    apiKey: string,
+    sessionResumeHistory?: string,
+  ): Promise<MCPSession> {
+    const toolplexPath = getToolplexClientPath();
+
+    // Build environment for the MCP server
+    const env: Record<string, string> = {
+      ...(process.env as Record<string, string>),
+      TOOLPLEX_API_KEY: apiKey,
+      CLIENT_NAME: "toolplex-ai-engine",
+    };
+
+    // Add session resume history if provided
+    if (sessionResumeHistory) {
+      env.TOOLPLEX_SESSION_RESUME_HISTORY = sessionResumeHistory;
+    }
+
+    const transport = new StdioClientTransport({
+      command: "node", // Uses system Node.js
+      args: [toolplexPath],
+      env,
+    });
+
+    const client = new Client({
+      name: "toolplex-ai-engine-client",
+      version: "1.0.0",
+    });
+
+    await client.connect(transport);
+    return { transport, client };
+  }
+
+  async closeTransport(session: MCPSession): Promise<void> {
+    try {
+      await session.client.close();
+    } catch {
+      // Silently continue to ensure cleanup
+    }
+  }
+}
+
+// Export singleton instance for convenience
+export const defaultStdioTransportFactory = new DefaultStdioTransportFactory();

package/src/mcp/MCPClient.ts

@@ -0,0 +1,209 @@
+/**
+ * @toolplex/ai-engine - MCP Client
+ *
+ * Core MCP client that manages sessions and tool operations.
+ * Uses a TransportFactory for platform-specific transport creation.
+ */
+
+import type {
+  MCPSession,
+  MCPResult,
+  MCPToolResult,
+  MCPClientConfig,
+  TransportFactory,
+} from "./types.js";
+
+/**
+ * MCP Client - manages sessions and provides tool operations
+ */
+export class MCPClient {
+  private sessions = new Map<string, MCPSession>();
+  private transportFactory: TransportFactory;
+  private logger: MCPClientConfig["logger"];
+  private imageHandler: MCPClientConfig["imageHandler"];
+  private getCurrentUserId: MCPClientConfig["getCurrentUserId"];
+
+  constructor(config: MCPClientConfig) {
+    this.transportFactory = config.transportFactory;
+    this.logger = config.logger;
+    this.imageHandler = config.imageHandler;
+    this.getCurrentUserId = config.getCurrentUserId;
+  }
+
+  /**
+   * Creates an MCP session and waits for tools to be initialized
+   *
+   * CRITICAL: The ToolPlex MCP server fetches tool schemas from the API during startup.
+   * This is asynchronous and can take time. We MUST wait for this to complete before
+   * returning, otherwise listTools() will return empty schemas.
+   */
+  async createSession(
+    sessionId: string,
+    apiKey: string,
+    sessionResumeHistory?: string,
+  ): Promise<MCPResult> {
+    try {
+      // Clean up existing session if it exists
+      await this.destroySession(sessionId);
+
+      this.logger?.debug("MCPClient: Creating session", { sessionId });
+
+      const session = await this.transportFactory.createTransport(
+        apiKey,
+        sessionResumeHistory,
+      );
+
+      this.sessions.set(sessionId, session);
+      this.logger?.debug("MCPClient: Session created and stored", {
+        sessionId,
+      });
+
+      return { success: true };
+    } catch (error) {
+      this.logger?.error("MCPClient: Transport creation failed", { error });
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error",
+      };
+    }
+  }
+
+  /**
+   * Lists available tools for a session
+   */
+  async listTools(sessionId: string): Promise<{ tools: any[] }> {
+    this.logger?.debug("MCPClient: Listing tools for session", {
+      sessionId,
+      availableSessions: Array.from(this.sessions.keys()),
+    });
+
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      this.logger?.error("MCPClient: No session found in registry", {
+        sessionId,
+        availableSessions: Array.from(this.sessions.keys()),
+      });
+      throw new Error(`No MCP client found for session: ${sessionId}`);
+    }
+
+    try {
+      const result = await session.client.listTools();
+      this.logger?.debug("MCPClient: Tools listed successfully", {
+        sessionId,
+        toolCount: result?.tools?.length || 0,
+      });
+      return result;
+    } catch (error) {
+      this.logger?.error("MCPClient: Failed to list tools", {
+        sessionId,
+        error,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Calls a tool for a session
+   */
+  async callTool(
+    sessionId: string,
+    toolName: string,
+    args: any,
+  ): Promise<MCPToolResult> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`No MCP client found for session: ${sessionId}`);
+    }
+
+    const toolCall = {
+      name: toolName,
+      arguments: args || {},
+    };
+    const result = await session.client.callTool(toolCall);
+
+    // Process the result to handle images if handler is available
+    if (
+      this.imageHandler &&
+      this.getCurrentUserId &&
+      result?.content &&
+      Array.isArray(result.content)
+    ) {
+      const hasImages = result.content.some(
+        (item: any) => item?.type === "image" && item?.data,
+      );
+
+      if (hasImages) {
+        const userId = this.getCurrentUserId();
+        if (userId) {
+          await this.imageHandler.initialize(userId);
+          const processed = await this.imageHandler.processToolResult(result);
+
+          return {
+            ...result,
+            content: processed.content,
+            savedImages: processed.savedImages,
+          };
+        }
+      }
+    }
+
+    return result as MCPToolResult;
+  }
+
+  /**
+   * Destroys an MCP session
+   */
+  async destroySession(sessionId: string): Promise<MCPResult> {
+    try {
+      const session = this.sessions.get(sessionId);
+      if (session) {
+        await this.transportFactory.closeTransport(session);
+        this.sessions.delete(sessionId);
+      }
+
+      return { success: true };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error",
+      };
+    }
+  }
+
+  /**
+   * Gets all active session IDs
+   */
+  getActiveSessions(): string[] {
+    return Array.from(this.sessions.keys());
+  }
+
+  /**
+   * Destroys all MCP sessions (cleanup)
+   */
+  async destroyAllSessions(): Promise<void> {
+    const sessionIds = this.getActiveSessions();
+    await Promise.all(sessionIds.map((id) => this.destroySession(id)));
+  }
+
+  /**
+   * Gets session info
+   */
+  getSessionInfo(sessionId: string): {
+    exists: boolean;
+    isConnected?: boolean;
+  } {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      return { exists: false };
+    }
+
+    return { exists: true, isConnected: true };
+  }
+
+  /**
+   * Check if a session exists
+   */
+  hasSession(sessionId: string): boolean {
+    return this.sessions.has(sessionId);
+  }
+}