@od-oneapp/ai-platform 0.1.0

package/src/tools/generic/web-search.ts

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview Web search tool factories for AI SDK agents.
+ *
+ * Provides factory functions to create web search tools compatible with
+ * Vercel AI SDK's tool system. Supports Exa API and custom search backends
+ * via dependency injection.
+ *
+ * Migrated from @repo/ai/tools/server/web-search.ts
+ *
+ * @module @od-oneapp/ai-platform/tools/generic/web-search
+ */
+
+import 'server-only';
+
+import { z } from 'zod/v4';
+
+import { tool } from '../../shared';
+
+/** Result shape returned by web search tools. */
+export interface WebSearchResult {
+  readonly title: string;
+  readonly url: string;
+  readonly content: string;
+  readonly publishedDate?: string;
+}
+
+/** Configuration for the Exa-based search tool. */
+export interface ExaSearchConfig {
+  /** Exa API key. */
+  readonly apiKey: string;
+  /** Maximum number of results to return. */
+  readonly numResults?: number;
+  /** Livecrawl strategy for Exa. */
+  readonly livecrawl?: 'always' | 'fallback' | 'never';
+}
+
+/**
+ * Minimal interface for the Exa client.
+ * Consumers pass their own Exa instance so ai-platform does not depend on `exa-js`.
+ */
+export interface ExaClient {
+  searchAndContents: (
+    query: string,
+    options: { livecrawl?: string; numResults?: number },
+  ) => Promise<{
+    results: Array<{
+      title: string;
+      url: string;
+      text?: string;
+      publishedDate?: string;
+    }>;
+  }>;
+}
+
+/**
+ * Create a web search tool using an Exa API client.
+ *
+ * @param config - Exa search configuration
+ * @param exaClient - Exa client instance (from `exa-js`)
+ * @returns AI SDK tool for web search via Exa
+ *
+ * @example
+ * ```ts
+ * import Exa from 'exa-js';
+ * import { createExaSearchTool } from '@od-oneapp/ai-platform/tools';
+ *
+ * const exa = new Exa(process.env.EXA_API_KEY!);
+ * const searchTool = createExaSearchTool(
+ *   { apiKey: process.env.EXA_API_KEY!, numResults: 5 },
+ *   exa,
+ * );
+ * ```
+ */
+export function createExaSearchTool(config: ExaSearchConfig, exaClient: ExaClient) {
+  return tool({
+    description: 'Search the web for up-to-date information using Exa',
+    inputSchema: z.object({
+      query: z.string().min(1).max(100).describe('The search query'),
+    }),
+    execute: async ({ query }: { query: string }) => {
+      const { results } = await exaClient.searchAndContents(query, {
+        livecrawl: config.livecrawl ?? 'always',
+        numResults: config.numResults ?? 3,
+      });
+
+      return results.map(result => ({
+        title: result.title,
+        url: result.url,
+        content: result.text?.slice(0, 1000) ?? result.title ?? '',
+        publishedDate: result.publishedDate,
+      })) as WebSearchResult[];
+    },
+  });
+}
+
+/**
+ * Create a generic web search tool with a custom search function.
+ *
+ * @param searchFunction - Custom search implementation
+ * @returns AI SDK tool for web search
+ *
+ * @example
+ * ```ts
+ * import { createWebSearchTool } from '@od-oneapp/ai-platform/tools';
+ *
+ * const tool = createWebSearchTool(async (query) => {
+ *   const resp = await fetch(`https://api.search.com?q=${query}`);
+ *   return resp.json();
+ * });
+ * ```
+ */
+export function createWebSearchTool(searchFunction: (query: string) => Promise<WebSearchResult[]>) {
+  return tool({
+    description: 'Search the web for up-to-date information',
+    inputSchema: z.object({
+      query: z.string().min(1).max(100).describe('The search query'),
+    }),
+    execute: async ({ query }: { query: string }) => {
+      return searchFunction(query);
+    },
+  });
+}
+
+/**
+ * Pre-configured search tool factories for common APIs.
+ */
+export const webSearchTools = {
+  /**
+   * Exa search tool factory.
+   *
+   * @param exaClient - Exa client instance
+   * @param options - Configuration options
+   */
+  exa: (exaClient: ExaClient, options?: Partial<ExaSearchConfig> & { apiKey: string }) =>
+    createExaSearchTool(options ?? { apiKey: '' }, exaClient),
+
+  /**
+   * Custom search implementation factory.
+   */
+  custom: (searchFunction: (query: string) => Promise<WebSearchResult[]>) =>
+    createWebSearchTool(searchFunction),
+};

package/src/tools/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Tools Module
+ *
+ * Tool execution patterns for AI agents:
+ * - Core tool definitions
+ * - Computer use (browser automation)
+ * - MCP integration
+ * - Specialized capabilities (superpowers)
+ *
+ * @module tools
+ */
+
+// Simplified tool factories
+export * from './simple-factory';
+export * from './validation-wrapper';
+
+// Core tool patterns
+export * from "./core";
+
+// Generic tools
+export * from "./generic";
+
+// Advanced tool patterns
+export * from "./advanced";
+
+// Artifact handling
+export * from "./artifacts";
+
+// Computer use (browser automation)
+export * from "./computer";
+
+// MCP integration
+export * from "./mcp";
+
+// Specialized capabilities
+export * from "./superpowers";

package/src/tools/mcp/ai-sdk-error-integration.ts

@@ -0,0 +1,401 @@
+/**
+ * @fileoverview ai-sdk-error-integration.ts
+ */
+
+import { logError, logInfo, logWarn } from '@repo/shared/logs';
+
+import 'server-only';
+import { getErrorCode } from '../../server/errors';
+
+/**
+ * AI SDK v6 Error Integration for MCP
+ * Provides standardized error handling patterns that integrate with AI SDK v6 error callbacks
+ *
+ * Key Features:
+ * - onUncaughtError handler integration
+ * - Stream error forwarding
+ * - Proper error type conformance with AI SDK conventions
+ * - Resource cleanup coordination
+ * - Error recovery mechanisms
+ */
+
+/**
+ * AI SDK v6 compatible error types
+ * These align with the error types expected by AI SDK callbacks
+ */
+export type AISDKErrorType =
+  | 'connection-error'
+  | 'transport-error'
+  | 'tool-execution-error'
+  | 'timeout-error'
+  | 'validation-error'
+  | 'resource-exhausted'
+  | 'unknown-error';
+
+/**
+ * Enhanced error class that conforms to AI SDK v6 error handling patterns
+ */
+export class AISDKCompatibleMCPError extends Error {
+  public readonly errorType: AISDKErrorType;
+  public readonly timestamp: Date;
+  public readonly recoverable: boolean;
+  public readonly metadata: Record<string, unknown>;
+
+  constructor(
+    message: string,
+    errorType: AISDKErrorType = 'unknown-error',
+    originalError?: Error,
+    metadata: Record<string, unknown> = {},
+    recoverable: boolean = false,
+  ) {
+    super(message);
+    this.name = 'AISDKCompatibleMCPError';
+    this.errorType = errorType;
+    this.timestamp = new Date();
+    this.recoverable = recoverable;
+    this.metadata = {
+      ...metadata,
+      originalError: originalError?.message,
+      originalStack: originalError?.stack,
+    };
+
+    // Maintain stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, AISDKCompatibleMCPError);
+    }
+  }
+
+  /**
+   * Convert to AI SDK error format for logging
+   */
+  toAISDKFormat() {
+    return {
+      name: this.name,
+      message: this.message,
+      errorType: this.errorType,
+      timestamp: this.timestamp.toISOString(),
+      recoverable: this.recoverable,
+      metadata: this.metadata,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Error handler factory for MCP operations
+ * Creates standardized error handlers that integrate with AI SDK v6 patterns
+ */
+export class MCPErrorHandlerFactory {
+  private clientName: string;
+  private operationContext: string;
+
+  constructor(clientName: string, operationContext: string = 'mcp-operation') {
+    this.clientName = clientName;
+    this.operationContext = operationContext;
+  }
+
+  /**
+   * Create an onUncaughtError handler for AI SDK v6 integration
+   */
+  createUncaughtErrorHandler(
+    cleanupFn: () => Promise<void>,
+    options: {
+      enableRecovery?: boolean;
+      maxRecoveryAttempts?: number;
+      logLevel?: 'error' | 'warn' | 'info';
+    } = {},
+  ): (error: Error) => void {
+    const { enableRecovery = false, maxRecoveryAttempts = 1, logLevel = 'error' } = options;
+    let recoveryAttempts = 0;
+
+    return (error: Error) => {
+      const aiError = this.convertToAISDKError(error);
+
+      // Log the error according to AI SDK patterns
+      const logFn = logLevel === 'warn' ? logWarn : logLevel === 'info' ? logInfo : logError;
+      logFn(`MCP uncaught error in ${this.operationContext}`, {
+        operation: 'mcp_uncaught_error_handler',
+        metadata: {
+          clientName: this.clientName,
+          errorType: aiError.errorType,
+          recoverable: aiError.recoverable,
+          recoveryAttempts,
+          maxRecoveryAttempts,
+          ...aiError.metadata,
+        },
+        error: aiError,
+      });
+
+      // Attempt recovery if enabled and error is recoverable
+      if (enableRecovery && aiError.recoverable && recoveryAttempts < maxRecoveryAttempts) {
+        recoveryAttempts++;
+        logInfo(
+          `Attempting recovery for MCP error (attempt ${recoveryAttempts}/${maxRecoveryAttempts})`,
+          {
+            operation: 'mcp_error_recovery_attempt',
+            metadata: {
+              clientName: this.clientName,
+              recoveryAttempt: recoveryAttempts,
+              errorType: aiError.errorType,
+            },
+          },
+        );
+
+        // Recovery is handled by not calling cleanup immediately
+        // The caller should implement retry logic
+        return;
+      }
+
+      // Perform cleanup for non-recoverable errors or exhausted recovery attempts
+      void (async () => {
+        try {
+          await cleanupFn();
+        } catch (cleanupError) {
+          logError(`Failed to cleanup after uncaught error in ${this.operationContext}`, {
+            operation: 'mcp_cleanup_after_uncaught_error',
+            metadata: {
+              clientName: this.clientName,
+              originalError: aiError.message,
+              cleanupError:
+                cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+            },
+            error: cleanupError instanceof Error ? cleanupError : new Error(String(cleanupError)),
+          });
+        }
+      })();
+    };
+  }
+
+  /**
+   * Create a stream error handler for AI SDK v6 streaming integration
+   */
+  createStreamErrorHandler(
+    cleanupFn: () => Promise<void>,
+    onStreamError?: (error: AISDKCompatibleMCPError) => void,
+  ): (error: Error) => void {
+    return (error: Error) => {
+      const aiError = this.convertToAISDKError(error, 'transport-error');
+
+      logError(`MCP stream error in ${this.operationContext}`, {
+        operation: 'mcp_stream_error_handler',
+        metadata: {
+          clientName: this.clientName,
+          errorType: aiError.errorType,
+          streamContext: this.operationContext,
+          ...aiError.metadata,
+        },
+        error: aiError,
+      });
+
+      // Notify stream error callback if provided
+      if (onStreamError) {
+        try {
+          onStreamError(aiError);
+        } catch (callbackError) {
+          logError(`Stream error callback failed in ${this.operationContext}`, {
+            operation: 'mcp_stream_error_callback_failure',
+            metadata: {
+              clientName: this.clientName,
+              callbackError:
+                callbackError instanceof Error ? callbackError.message : String(callbackError),
+            },
+            error:
+              callbackError instanceof Error ? callbackError : new Error(String(callbackError)),
+          });
+        }
+      }
+
+      // Always attempt cleanup for stream errors
+      void (async () => {
+        try {
+          await cleanupFn();
+        } catch (cleanupError) {
+          logError(`Failed to cleanup after stream error in ${this.operationContext}`, {
+            operation: 'mcp_stream_cleanup_error',
+            metadata: {
+              clientName: this.clientName,
+              originalError: aiError.message,
+              cleanupError:
+                cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+            },
+            error: cleanupError instanceof Error ? cleanupError : new Error(String(cleanupError)),
+          });
+        }
+      })();
+    };
+  }
+
+  /**
+   * Create a finish handler for proper AI SDK v6 lifecycle management
+   */
+  createFinishHandler(
+    cleanupFn: () => Promise<void>,
+    successCallback?: () => void,
+  ): () => Promise<void> {
+    return async () => {
+      try {
+        await cleanupFn();
+
+        logInfo(`MCP operation completed successfully in ${this.operationContext}`, {
+          operation: 'mcp_finish_handler_success',
+          metadata: {
+            clientName: this.clientName,
+            operationContext: this.operationContext,
+          },
+        });
+
+        // Call success callback if provided
+        if (successCallback) {
+          try {
+            successCallback();
+          } catch (callbackError) {
+            logWarn(`Success callback failed in ${this.operationContext}`, {
+              operation: 'mcp_success_callback_failure',
+              metadata: {
+                clientName: this.clientName,
+                callbackError:
+                  callbackError instanceof Error ? callbackError.message : String(callbackError),
+              },
+            });
+          }
+        }
+      } catch (error) {
+        const aiError = this.convertToAISDKError(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+
+        logError(`MCP finish handler failed in ${this.operationContext}`, {
+          operation: 'mcp_finish_handler_error',
+          metadata: {
+            clientName: this.clientName,
+            errorType: aiError.errorType,
+            ...aiError.metadata,
+          },
+          error: aiError,
+        });
+
+        // Re-throw to maintain AI SDK error handling flow
+        throw aiError;
+      }
+    };
+  }
+
+  /**
+   * Convert generic error to AI SDK compatible error
+   */
+  private convertToAISDKError(
+    error: Error,
+    defaultType: AISDKErrorType = 'unknown-error',
+  ): AISDKCompatibleMCPError {
+    // Check if already an AI SDK compatible error
+    if (error instanceof AISDKCompatibleMCPError) {
+      return error;
+    }
+
+    // Map common error patterns to AI SDK error types
+    let errorType: AISDKErrorType = defaultType;
+    let recoverable = false;
+
+    if (error.message.includes('ECONNREFUSED') || error.message.includes('ENOTFOUND')) {
+      errorType = 'connection-error';
+      recoverable = true;
+    } else if (error.message.includes('timeout') || error.message.includes('TIMEOUT')) {
+      errorType = 'timeout-error';
+      recoverable = true;
+    } else if (error.message.includes('transport') || error.message.includes('Transport')) {
+      errorType = 'transport-error';
+      recoverable = true;
+    } else if (error.message.includes('validation') || error.message.includes('invalid')) {
+      errorType = 'validation-error';
+      recoverable = false;
+    } else if (error.message.includes('resource') || error.message.includes('limit')) {
+      errorType = 'resource-exhausted';
+      recoverable = true;
+    } else if (error.message.includes('tool') || error.message.includes('execution')) {
+      errorType = 'tool-execution-error';
+      recoverable = false;
+    }
+
+    return new AISDKCompatibleMCPError(
+      error.message,
+      errorType,
+      error,
+      {
+        clientName: this.clientName,
+        operationContext: this.operationContext,
+        originalErrorName: error.name,
+      },
+      recoverable,
+    );
+  }
+}
+
+/**
+ * Utility functions for AI SDK v6 error integration
+ */
+export const MCPErrorUtils = {
+  /**
+   * Create a standardized error context for MCP operations
+   */
+  createErrorContext(clientName: string, operation: string): MCPErrorHandlerFactory {
+    return new MCPErrorHandlerFactory(clientName, operation);
+  },
+
+  /**
+   * Check if an error is recoverable according to AI SDK patterns
+   */
+  isRecoverableError(error: Error): boolean {
+    if (error instanceof AISDKCompatibleMCPError) {
+      return error.recoverable;
+    }
+
+    // Common recoverable error patterns
+    const recoverablePatterns = [
+      'ECONNREFUSED',
+      'ENOTFOUND',
+      'TIMEOUT',
+      'timeout',
+      'network',
+      'temporary',
+      'rate limit',
+      'throttle',
+    ];
+
+    return recoverablePatterns.some(pattern =>
+      error.message.toLowerCase().includes(pattern.toLowerCase()),
+    );
+  },
+
+  /**
+   * Extract error metadata for AI SDK logging
+   */
+  extractErrorMetadata(error: Error): Record<string, unknown> {
+    const metadata: Record<string, unknown> = {
+      errorName: error.name,
+      errorMessage: error.message,
+      timestamp: new Date().toISOString(),
+    };
+
+    if (error instanceof AISDKCompatibleMCPError) {
+      metadata.errorType = error.errorType;
+      metadata.recoverable = error.recoverable;
+      metadata.customMetadata = error.metadata;
+    }
+
+    // Extract common error properties
+    const errorCode = getErrorCode(error);
+    if (errorCode) {
+      metadata.errorCode = errorCode;
+    }
+
+    const errorDetails = error as { errno?: unknown; syscall?: unknown };
+    if (typeof errorDetails.errno === 'string' || typeof errorDetails.errno === 'number') {
+      metadata.errno = errorDetails.errno;
+    }
+    if (typeof errorDetails.syscall === 'string') {
+      metadata.syscall = errorDetails.syscall;
+    }
+
+    return metadata;
+  },
+};