mcp-researchpowerpack-http 3.10.0

package/dist/src/clients/research.js

@@ -0,0 +1,282 @@
+import OpenAI from "openai";
+import { RESEARCH } from "../config/index.js";
+import { calculateBackoff } from "../utils/retry.js";
+import {
+  classifyError,
+  sleep,
+  ErrorCode,
+  withRequestTimeout,
+  withStallProtection
+} from "../utils/errors.js";
+import { mcpLog } from "../utils/logger.js";
+const DEFAULT_RESEARCH_CONCURRENCY = 3;
+const MAX_RESEARCH_RETRIES = 3;
+const RESEARCH_TEMPERATURE = 0.3;
+const RESEARCH_BASE_DELAY_MS = 5e3;
+const RESEARCH_MAX_DELAY_MS = 6e4;
+const DEFAULT_MAX_TOKENS = 32e3;
+const MAX_SEARCH_RESULTS_CAP = 30;
+const RESEARCH_REQUEST_DEADLINE_MS = 12e4;
+const RESEARCH_STALL_TIMEOUT_MS = 9e4;
+const RETRYABLE_RESEARCH_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+const GEMINI_STYLE_MODELS = /* @__PURE__ */ new Set([
+  "google/gemini-2.5-flash",
+  "google/gemini-2.5-pro",
+  "google/gemini-2.0-flash",
+  "google/gemini-pro"
+]);
+function isGeminiStyleModel(model) {
+  return GEMINI_STYLE_MODELS.has(model) || model.startsWith("google/gemini");
+}
+function buildResearchPayload(model, messages, options) {
+  const { temperature, reasoningEffort, maxTokens, maxSearchResults, responseFormat } = options;
+  if (isGeminiStyleModel(model)) {
+    const payload2 = {
+      model,
+      messages,
+      temperature,
+      max_tokens: maxTokens,
+      tools: [
+        {
+          type: "google_search",
+          googleSearch: {}
+        }
+      ]
+    };
+    if (responseFormat) {
+      payload2.response_format = responseFormat;
+    }
+    return payload2;
+  }
+  const payload = {
+    model,
+    messages,
+    temperature,
+    reasoning_effort: reasoningEffort,
+    max_completion_tokens: maxTokens,
+    search_parameters: {
+      mode: "on",
+      max_search_results: Math.min(maxSearchResults, MAX_SEARCH_RESULTS_CAP),
+      return_citations: true,
+      sources: [{ type: "web" }]
+    }
+  };
+  if (responseFormat) {
+    payload.response_format = responseFormat;
+  }
+  return payload;
+}
+function parseResearchResponse(raw, model) {
+  const { response, choice, message } = raw;
+  return {
+    id: response.id || "",
+    model: response.model || model,
+    created: response.created || Date.now(),
+    content: message?.content || "",
+    finishReason: choice?.finish_reason ?? void 0,
+    usage: response.usage ? {
+      promptTokens: response.usage.prompt_tokens,
+      completionTokens: response.usage.completion_tokens,
+      totalTokens: response.usage.total_tokens,
+      sourcesUsed: response.usage.num_sources_used
+    } : void 0,
+    annotations: message?.annotations?.map((a) => ({
+      type: "url_citation",
+      url: a.url_citation?.url || "",
+      title: a.url_citation?.title || "",
+      startIndex: a.url_citation?.start_index || 0,
+      endIndex: a.url_citation?.end_index || 0
+    }))
+  };
+}
+class ResearchClient {
+  client;
+  constructor() {
+    if (!RESEARCH.API_KEY) {
+      throw new Error("Research capability is not configured. Please set up the required API credentials.");
+    }
+    this.client = new OpenAI({
+      baseURL: RESEARCH.BASE_URL,
+      apiKey: RESEARCH.API_KEY,
+      timeout: RESEARCH.TIMEOUT_MS,
+      maxRetries: 0
+      // We handle retries ourselves
+    });
+  }
+  /**
+   * Check if an error is retryable for research requests
+   */
+  isRetryableError(error) {
+    if (!error) return false;
+    const err = error;
+    if (err.status && RETRYABLE_RESEARCH_CODES.has(err.status)) {
+      return true;
+    }
+    const message = (err.message || "").toLowerCase();
+    if (message.includes("rate limit") || message.includes("timeout") || message.includes("timed out") || message.includes("service unavailable") || message.includes("connection") || message.includes("stalled")) {
+      return true;
+    }
+    if (err.code === "ESTALLED" || err.code === "ETIMEDOUT") {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Make the API call to OpenRouter with retry logic.
+   * Returns the raw response or null if all attempts fail.
+   */
+  async callOpenRouter(payload, model, signal) {
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RESEARCH_RETRIES; attempt++) {
+      try {
+        if (attempt > 0) {
+          mcpLog("warning", `Retry attempt ${attempt}/${MAX_RESEARCH_RETRIES} for ${model}`, "research");
+        }
+        const response = await withStallProtection(
+          (stallSignal) => withRequestTimeout(
+            (timeoutSignal) => {
+              const mergedController = new AbortController();
+              const abortMerged = () => mergedController.abort();
+              signal?.addEventListener("abort", abortMerged, { once: true });
+              stallSignal.addEventListener("abort", abortMerged, { once: true });
+              timeoutSignal.addEventListener("abort", abortMerged, { once: true });
+              return this.client.chat.completions.create(
+                payload,
+                { signal: mergedController.signal }
+              ).finally(() => {
+                signal?.removeEventListener("abort", abortMerged);
+                stallSignal.removeEventListener("abort", abortMerged);
+                timeoutSignal.removeEventListener("abort", abortMerged);
+              });
+            },
+            RESEARCH_REQUEST_DEADLINE_MS,
+            `research (${model})`
+          ),
+          RESEARCH_STALL_TIMEOUT_MS,
+          2,
+          `research (${model})`
+        );
+        const choice = response.choices?.[0];
+        const message = choice?.message;
+        if (!message?.content && !choice) {
+          lastError = {
+            code: ErrorCode.INTERNAL_ERROR,
+            message: "Research API returned empty response",
+            retryable: true
+          };
+          if (attempt < MAX_RESEARCH_RETRIES) {
+            const delayMs = calculateBackoff(attempt, RESEARCH_BASE_DELAY_MS, RESEARCH_MAX_DELAY_MS);
+            mcpLog("warning", `Empty response, retrying in ${delayMs}ms...`, "research");
+            await sleep(delayMs, signal);
+            continue;
+          }
+        }
+        return { raw: { response, choice, message } };
+      } catch (error) {
+        lastError = classifyError(error);
+        const err = error;
+        mcpLog("error", `Error with ${model} (attempt ${attempt + 1}): ${lastError.message} (status: ${err.status})`, "research");
+        if (this.isRetryableError(error) && attempt < MAX_RESEARCH_RETRIES) {
+          const delayMs = calculateBackoff(attempt, RESEARCH_BASE_DELAY_MS, RESEARCH_MAX_DELAY_MS);
+          mcpLog("warning", `Retrying in ${delayMs}ms...`, "research");
+          try {
+            await sleep(delayMs, signal);
+          } catch {
+            break;
+          }
+          continue;
+        }
+        break;
+      }
+    }
+    return {
+      error: lastError || {
+        code: ErrorCode.UNKNOWN_ERROR,
+        message: "Unknown research error",
+        retryable: false
+      }
+    };
+  }
+  /**
+   * Execute a single research request with a specific model.
+   * Thin orchestrator: build payload → call API → parse response.
+   */
+  async executeResearch(model, messages, options, signal) {
+    const payload = buildResearchPayload(model, messages, options);
+    const result = await this.callOpenRouter(payload, model, signal);
+    if (result.raw) {
+      return parseResearchResponse(result.raw, model);
+    }
+    return {
+      id: "",
+      model,
+      created: Date.now(),
+      content: "",
+      error: result.error
+    };
+  }
+  /**
+   * Perform research with retry logic and fallback to secondary model
+   * Returns a ResearchResponse - may contain error field on failure
+   * NEVER throws - always returns a valid response object
+   */
+  async research(params, signal) {
+    const {
+      question,
+      systemPrompt,
+      reasoningEffort = RESEARCH.REASONING_EFFORT,
+      maxSearchResults = RESEARCH.MAX_URLS,
+      maxTokens = DEFAULT_MAX_TOKENS,
+      temperature = RESEARCH_TEMPERATURE,
+      responseFormat
+    } = params;
+    if (!question?.trim()) {
+      return {
+        id: "",
+        model: RESEARCH.MODEL,
+        created: Date.now(),
+        content: "",
+        error: {
+          code: ErrorCode.INVALID_INPUT,
+          message: "Research question cannot be empty",
+          retryable: false
+        }
+      };
+    }
+    const messages = [];
+    if (systemPrompt) {
+      messages.push({ role: "system", content: systemPrompt });
+    }
+    messages.push({ role: "user", content: question });
+    const options = { temperature, reasoningEffort, maxTokens, maxSearchResults, responseFormat };
+    mcpLog("info", `Trying primary model: ${RESEARCH.MODEL}`, "research");
+    const primaryResult = await this.executeResearch(RESEARCH.MODEL, messages, options, signal);
+    if (!primaryResult.error) {
+      return primaryResult;
+    }
+    if (RESEARCH.FALLBACK_MODEL && RESEARCH.FALLBACK_MODEL !== RESEARCH.MODEL) {
+      mcpLog("warning", `Primary model failed, trying fallback: ${RESEARCH.FALLBACK_MODEL}`, "research");
+      const fallbackResult = await this.executeResearch(RESEARCH.FALLBACK_MODEL, messages, options, signal);
+      if (!fallbackResult.error) {
+        return fallbackResult;
+      }
+      mcpLog("error", `Both models failed. Primary: ${primaryResult.error?.message}, Fallback: ${fallbackResult.error?.message}`, "research");
+      return {
+        ...fallbackResult,
+        content: `Research failed with both models. Primary (${RESEARCH.MODEL}): ${primaryResult.error?.message}. Fallback (${RESEARCH.FALLBACK_MODEL}): ${fallbackResult.error?.message}`
+      };
+    }
+    mcpLog("error", `All attempts failed: ${primaryResult.error?.message}`, "research");
+    return {
+      ...primaryResult,
+      content: `Research failed: ${primaryResult.error?.message}`
+    };
+  }
+}
+export {
+  DEFAULT_RESEARCH_CONCURRENCY,
+  MAX_RESEARCH_RETRIES,
+  RESEARCH_TEMPERATURE,
+  ResearchClient
+};
+//# sourceMappingURL=research.js.map

package/dist/src/clients/research.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/clients/research.ts"],
+  "sourcesContent": ["/**\n * Deep Research Client\n * Handles research API requests with web search capabilities\n * Implements robust retry logic and NEVER crashes the server\n */\n\nimport OpenAI from 'openai';\nimport { RESEARCH } from '../config/index.js';\nimport { calculateBackoff } from '../utils/retry.js';\nimport {\n  classifyError,\n  sleep,\n  ErrorCode,\n  withRequestTimeout,\n  withStallProtection,\n  type StructuredError,\n} from '../utils/errors.js';\nimport { mcpLog } from '../utils/logger.js';\n\n// \u2500\u2500 Constants \u2500\u2500\n\nconst DEFAULT_RESEARCH_CONCURRENCY = 3 as const;\nconst MAX_RESEARCH_RETRIES = 3 as const;\nconst RESEARCH_TEMPERATURE = 0.3 as const;\nconst RESEARCH_BASE_DELAY_MS = 5_000 as const;\nconst RESEARCH_MAX_DELAY_MS = 60_000 as const;\nconst DEFAULT_MAX_TOKENS = 32_000 as const;\nconst MAX_SEARCH_RESULTS_CAP = 30 as const;\n\n/** Hard deadline for a single research API call */\nconst RESEARCH_REQUEST_DEADLINE_MS = 120_000 as const;\n\n/** Stall detection \u2014 abort if no response for this duration */\nconst RESEARCH_STALL_TIMEOUT_MS = 90_000 as const;\n\n// Retryable status codes for research API\nconst RETRYABLE_RESEARCH_CODES = new Set([429, 500, 502, 503, 504]);\n\n// Models that use Gemini-style google_search tool instead of search_parameters\nconst GEMINI_STYLE_MODELS = new Set([\n  'google/gemini-2.5-flash',\n  'google/gemini-2.5-pro',\n  'google/gemini-2.0-flash',\n  'google/gemini-pro',\n]);\n\n// \u2500\u2500 Interfaces \u2500\u2500\n\ninterface ResearchParams {\n  readonly question: string;\n  readonly systemPrompt?: string;\n  readonly reasoningEffort?: 'low' | 'medium' | 'high';\n  readonly maxSearchResults?: number;\n  readonly maxTokens?: number;\n  readonly temperature?: number;\n  readonly responseFormat?: { readonly type: 'json_object' | 'text' };\n}\n\nexport interface ResearchResponse {\n  readonly id: string;\n  readonly model: string;\n  readonly created: number;\n  readonly content: string;\n  readonly finishReason?: string;\n  readonly usage?: {\n    readonly promptTokens: number;\n    readonly completionTokens: number;\n    readonly totalTokens: number;\n    readonly sourcesUsed?: number;\n  };\n  readonly annotations?: ReadonlyArray<{\n    readonly type: 'url_citation';\n    readonly url: string;\n    readonly title: string;\n    readonly startIndex: number;\n    readonly endIndex: number;\n  }>;\n  readonly error?: StructuredError;\n}\n\n/** OpenRouter extension for response messages with annotations */\ninterface OpenRouterMessage {\n  readonly role: string;\n  readonly content: string | null;\n  readonly annotations?: readonly OpenRouterAnnotation[];\n}\n\n/** Single annotation from OpenRouter response */\ninterface OpenRouterAnnotation {\n  readonly type: string;\n  readonly url_citation?: {\n    readonly url: string;\n    readonly title?: string;\n    readonly start_index?: number;\n    readonly end_index?: number;\n  };\n  readonly [key: string]: unknown;\n}\n\n/** OpenRouter extensions to usage stats */\ninterface OpenRouterUsage {\n  readonly prompt_tokens: number;\n  readonly completion_tokens: number;\n  readonly total_tokens: number;\n  readonly num_sources_used?: number;\n}\n\n/** Raw response shape from OpenRouter API call */\ninterface OpenRouterRawResponse {\n  readonly response: OpenAI.ChatCompletion;\n  readonly choice: OpenAI.ChatCompletion.Choice | undefined;\n  readonly message: OpenRouterMessage | undefined;\n}\n\n/** Options passed through the research execution pipeline */\ninterface ResearchExecutionOptions {\n  readonly temperature: number;\n  readonly reasoningEffort: 'low' | 'medium' | 'high';\n  readonly maxTokens: number;\n  readonly maxSearchResults: number;\n  readonly responseFormat?: { readonly type: 'json_object' | 'text' };\n}\n\n// \u2500\u2500 Helpers \u2500\u2500\n\n/**\n * Check if a model uses Gemini-style google_search tool\n */\nfunction isGeminiStyleModel(model: string): boolean {\n  return GEMINI_STYLE_MODELS.has(model) || model.startsWith('google/gemini');\n}\n\n/**\n * Build the OpenRouter request payload based on model type.\n * Gemini models use tools with google_search, others use search_parameters.\n */\nfunction buildResearchPayload(\n  model: string,\n  messages: ReadonlyArray<{ readonly role: 'system' | 'user'; readonly content: string }>,\n  options: ResearchExecutionOptions,\n): Record<string, unknown> {\n  const { temperature, reasoningEffort, maxTokens, maxSearchResults, responseFormat } = options;\n\n  if (isGeminiStyleModel(model)) {\n    const payload: Record<string, unknown> = {\n      model,\n      messages,\n      temperature,\n      max_tokens: maxTokens,\n      tools: [\n        {\n          type: 'google_search',\n          googleSearch: {},\n        },\n      ],\n    };\n    if (responseFormat) {\n      payload.response_format = responseFormat;\n    }\n    return payload;\n  }\n\n  // Default: use search_parameters (for Grok, Perplexity, etc.)\n  const payload: Record<string, unknown> = {\n    model,\n    messages,\n    temperature,\n    reasoning_effort: reasoningEffort,\n    max_completion_tokens: maxTokens,\n    search_parameters: {\n      mode: 'on',\n      max_search_results: Math.min(maxSearchResults, MAX_SEARCH_RESULTS_CAP),\n      return_citations: true,\n      sources: [{ type: 'web' }],\n    },\n  };\n  if (responseFormat) {\n    payload.response_format = responseFormat;\n  }\n  return payload;\n}\n\n/**\n * Parse an OpenRouter raw response into a structured ResearchResponse.\n * Extracts content, token usage, and citation annotations.\n */\nfunction parseResearchResponse(\n  raw: OpenRouterRawResponse,\n  model: string,\n): ResearchResponse {\n  const { response, choice, message } = raw;\n\n  return {\n    id: response.id || '',\n    model: response.model || model,\n    created: response.created || Date.now(),\n    content: message?.content || '',\n    finishReason: choice?.finish_reason ?? undefined,\n    usage: response.usage ? {\n      promptTokens: response.usage.prompt_tokens,\n      completionTokens: response.usage.completion_tokens,\n      totalTokens: response.usage.total_tokens,\n      sourcesUsed: (response.usage as unknown as OpenRouterUsage).num_sources_used,\n    } : undefined,\n    annotations: message?.annotations?.map((a: OpenRouterAnnotation) => ({\n      type: 'url_citation' as const,\n      url: a.url_citation?.url || '',\n      title: a.url_citation?.title || '',\n      startIndex: a.url_citation?.start_index || 0,\n      endIndex: a.url_citation?.end_index || 0,\n    })),\n  };\n}\n\n// \u2500\u2500 Client \u2500\u2500\n\nexport { DEFAULT_RESEARCH_CONCURRENCY, MAX_RESEARCH_RETRIES, RESEARCH_TEMPERATURE };\n\nexport class ResearchClient {\n  private client: OpenAI;\n\n  constructor() {\n    if (!RESEARCH.API_KEY) {\n      throw new Error('Research capability is not configured. Please set up the required API credentials.');\n    }\n\n    this.client = new OpenAI({\n      baseURL: RESEARCH.BASE_URL,\n      apiKey: RESEARCH.API_KEY,\n      timeout: RESEARCH.TIMEOUT_MS,\n      maxRetries: 0, // We handle retries ourselves\n    });\n  }\n\n  /**\n   * Check if an error is retryable for research requests\n   */\n  private isRetryableError(error: unknown): boolean {\n    if (!error) return false;\n\n    const err = error as {\n      status?: number;\n      code?: string;\n      message?: string;\n    };\n\n    if (err.status && RETRYABLE_RESEARCH_CODES.has(err.status)) {\n      return true;\n    }\n\n    const message = (err.message || '').toLowerCase();\n    if (\n      message.includes('rate limit') ||\n      message.includes('timeout') ||\n      message.includes('timed out') ||\n      message.includes('service unavailable') ||\n      message.includes('connection') ||\n      message.includes('stalled')\n    ) {\n      return true;\n    }\n\n    // Check for stall protection errors\n    if (err.code === 'ESTALLED' || err.code === 'ETIMEDOUT') {\n      return true;\n    }\n\n    return false;\n  }\n\n  /**\n   * Make the API call to OpenRouter with retry logic.\n   * Returns the raw response or null if all attempts fail.\n   */\n  private async callOpenRouter(\n    payload: Record<string, unknown>,\n    model: string,\n    signal?: AbortSignal,\n  ): Promise<{ raw: OpenRouterRawResponse; error?: undefined } | { raw?: undefined; error: StructuredError }> {\n    let lastError: StructuredError | undefined;\n\n    for (let attempt = 0; attempt <= MAX_RESEARCH_RETRIES; attempt++) {\n      try {\n        if (attempt > 0) {\n          mcpLog('warning', `Retry attempt ${attempt}/${MAX_RESEARCH_RETRIES} for ${model}`, 'research');\n        }\n\n        const response = await withStallProtection(\n          (stallSignal) => withRequestTimeout(\n            (timeoutSignal) => {\n              // Merge all abort signals (external + stall + timeout)\n              const mergedController = new AbortController();\n              const abortMerged = () => mergedController.abort();\n              signal?.addEventListener('abort', abortMerged, { once: true });\n              stallSignal.addEventListener('abort', abortMerged, { once: true });\n              timeoutSignal.addEventListener('abort', abortMerged, { once: true });\n\n              return this.client.chat.completions.create(\n                payload as unknown as OpenAI.ChatCompletionCreateParamsNonStreaming,\n                { signal: mergedController.signal }\n              ).finally(() => {\n                signal?.removeEventListener('abort', abortMerged);\n                stallSignal.removeEventListener('abort', abortMerged);\n                timeoutSignal.removeEventListener('abort', abortMerged);\n              });\n            },\n            RESEARCH_REQUEST_DEADLINE_MS,\n            `research (${model})`,\n          ),\n          RESEARCH_STALL_TIMEOUT_MS,\n          2,\n          `research (${model})`,\n        );\n        const choice = response.choices?.[0];\n        const message = choice?.message as unknown as OpenRouterMessage;\n\n        // Validate response \u2014 retry on empty\n        if (!message?.content && !choice) {\n          lastError = {\n            code: ErrorCode.INTERNAL_ERROR,\n            message: 'Research API returned empty response',\n            retryable: true,\n          };\n\n          if (attempt < MAX_RESEARCH_RETRIES) {\n            const delayMs = calculateBackoff(attempt, RESEARCH_BASE_DELAY_MS, RESEARCH_MAX_DELAY_MS);\n            mcpLog('warning', `Empty response, retrying in ${delayMs}ms...`, 'research');\n            await sleep(delayMs, signal);\n            continue;\n          }\n        }\n\n        return { raw: { response, choice, message } };\n\n      } catch (error: unknown) {\n        lastError = classifyError(error);\n\n        const err = error as { status?: number; message?: string };\n        mcpLog('error', `Error with ${model} (attempt ${attempt + 1}): ${lastError.message} (status: ${err.status})`, 'research');\n\n        if (this.isRetryableError(error) && attempt < MAX_RESEARCH_RETRIES) {\n          const delayMs = calculateBackoff(attempt, RESEARCH_BASE_DELAY_MS, RESEARCH_MAX_DELAY_MS);\n          mcpLog('warning', `Retrying in ${delayMs}ms...`, 'research');\n          try { await sleep(delayMs, signal); } catch { break; }\n          continue;\n        }\n\n        break;\n      }\n    }\n\n    return {\n      error: lastError || {\n        code: ErrorCode.UNKNOWN_ERROR,\n        message: 'Unknown research error',\n        retryable: false,\n      },\n    };\n  }\n\n  /**\n   * Execute a single research request with a specific model.\n   * Thin orchestrator: build payload \u2192 call API \u2192 parse response.\n   */\n  private async executeResearch(\n    model: string,\n    messages: ReadonlyArray<{ readonly role: 'system' | 'user'; readonly content: string }>,\n    options: ResearchExecutionOptions,\n    signal?: AbortSignal,\n  ): Promise<ResearchResponse> {\n    const payload = buildResearchPayload(model, messages, options);\n    const result = await this.callOpenRouter(payload, model, signal);\n\n    if (result.raw) {\n      return parseResearchResponse(result.raw, model);\n    }\n\n    return {\n      id: '',\n      model,\n      created: Date.now(),\n      content: '',\n      error: result.error,\n    };\n  }\n\n  /**\n   * Perform research with retry logic and fallback to secondary model\n   * Returns a ResearchResponse - may contain error field on failure\n   * NEVER throws - always returns a valid response object\n   */\n  async research(params: ResearchParams, signal?: AbortSignal): Promise<ResearchResponse> {\n    const {\n      question,\n      systemPrompt,\n      reasoningEffort = RESEARCH.REASONING_EFFORT,\n      maxSearchResults = RESEARCH.MAX_URLS,\n      maxTokens = DEFAULT_MAX_TOKENS,\n      temperature = RESEARCH_TEMPERATURE,\n      responseFormat,\n    } = params;\n\n    // Validate input\n    if (!question?.trim()) {\n      return {\n        id: '',\n        model: RESEARCH.MODEL,\n        created: Date.now(),\n        content: '',\n        error: {\n          code: ErrorCode.INVALID_INPUT,\n          message: 'Research question cannot be empty',\n          retryable: false,\n        },\n      };\n    }\n\n    const messages: Array<{ role: 'system' | 'user'; content: string }> = [];\n    if (systemPrompt) {\n      messages.push({ role: 'system', content: systemPrompt });\n    }\n    messages.push({ role: 'user', content: question });\n\n    const options: ResearchExecutionOptions = { temperature, reasoningEffort, maxTokens, maxSearchResults, responseFormat };\n\n    // Try primary model first\n    mcpLog('info', `Trying primary model: ${RESEARCH.MODEL}`, 'research');\n    const primaryResult = await this.executeResearch(RESEARCH.MODEL, messages, options, signal);\n\n    if (!primaryResult.error) {\n      return primaryResult;\n    }\n\n    // Primary failed - try fallback model if different\n    if (RESEARCH.FALLBACK_MODEL && RESEARCH.FALLBACK_MODEL !== RESEARCH.MODEL) {\n      mcpLog('warning', `Primary model failed, trying fallback: ${RESEARCH.FALLBACK_MODEL}`, 'research');\n      const fallbackResult = await this.executeResearch(RESEARCH.FALLBACK_MODEL, messages, options, signal);\n\n      if (!fallbackResult.error) {\n        return fallbackResult;\n      }\n\n      // Both failed - return the fallback error (more recent)\n      mcpLog('error', `Both models failed. Primary: ${primaryResult.error?.message}, Fallback: ${fallbackResult.error?.message}`, 'research');\n      return {\n        ...fallbackResult,\n        content: `Research failed with both models. Primary (${RESEARCH.MODEL}): ${primaryResult.error?.message}. Fallback (${RESEARCH.FALLBACK_MODEL}): ${fallbackResult.error?.message}`,\n      };\n    }\n\n    // No fallback or same model - return primary error\n    mcpLog('error', `All attempts failed: ${primaryResult.error?.message}`, 'research');\n    return {\n      ...primaryResult,\n      content: `Research failed: ${primaryResult.error?.message}`,\n    };\n  }\n}\n"],
+  "mappings": "AAMA,OAAO,YAAY;AACnB,SAAS,gBAAgB;AACzB,SAAS,wBAAwB;AACjC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AACP,SAAS,cAAc;AAIvB,MAAM,+BAA+B;AACrC,MAAM,uBAAuB;AAC7B,MAAM,uBAAuB;AAC7B,MAAM,yBAAyB;AAC/B,MAAM,wBAAwB;AAC9B,MAAM,qBAAqB;AAC3B,MAAM,yBAAyB;AAG/B,MAAM,+BAA+B;AAGrC,MAAM,4BAA4B;AAGlC,MAAM,2BAA2B,oBAAI,IAAI,CAAC,KAAK,KAAK,KAAK,KAAK,GAAG,CAAC;AAGlE,MAAM,sBAAsB,oBAAI,IAAI;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAoFD,SAAS,mBAAmB,OAAwB;AAClD,SAAO,oBAAoB,IAAI,KAAK,KAAK,MAAM,WAAW,eAAe;AAC3E;AAMA,SAAS,qBACP,OACA,UACA,SACyB;AACzB,QAAM,EAAE,aAAa,iBAAiB,WAAW,kBAAkB,eAAe,IAAI;AAEtF,MAAI,mBAAmB,KAAK,GAAG;AAC7B,UAAMA,WAAmC;AAAA,MACvC;AAAA,MACA;AAAA,MACA;AAAA,MACA,YAAY;AAAA,MACZ,OAAO;AAAA,QACL;AAAA,UACE,MAAM;AAAA,UACN,cAAc,CAAC;AAAA,QACjB;AAAA,MACF;AAAA,IACF;AACA,QAAI,gBAAgB;AAClB,MAAAA,SAAQ,kBAAkB;AAAA,IAC5B;AACA,WAAOA;AAAA,EACT;AAGA,QAAM,UAAmC;AAAA,IACvC;AAAA,IACA;AAAA,IACA;AAAA,IACA,kBAAkB;AAAA,IAClB,uBAAuB;AAAA,IACvB,mBAAmB;AAAA,MACjB,MAAM;AAAA,MACN,oBAAoB,KAAK,IAAI,kBAAkB,sBAAsB;AAAA,MACrE,kBAAkB;AAAA,MAClB,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;AAAA,IAC3B;AAAA,EACF;AACA,MAAI,gBAAgB;AAClB,YAAQ,kBAAkB;AAAA,EAC5B;AACA,SAAO;AACT;AAMA,SAAS,sBACP,KACA,OACkB;AAClB,QAAM,EAAE,UAAU,QAAQ,QAAQ,IAAI;AAEtC,SAAO;AAAA,IACL,IAAI,SAAS,MAAM;AAAA,IACnB,OAAO,SAAS,SAAS;AAAA,IACzB,SAAS,SAAS,WAAW,KAAK,IAAI;AAAA,IACtC,SAAS,SAAS,WAAW;AAAA,IAC7B,cAAc,QAAQ,iBAAiB;AAAA,IACvC,OAAO,SAAS,QAAQ;AAAA,MACtB,cAAc,SAAS,MAAM;AAAA,MAC7B,kBAAkB,SAAS,MAAM;AAAA,MACjC,aAAa,SAAS,MAAM;AAAA,MAC5B,aAAc,SAAS,MAAqC;AAAA,IAC9D,IAAI;AAAA,IACJ,aAAa,SAAS,aAAa,IAAI,CAAC,OAA6B;AAAA,MACnE,MAAM;AAAA,MACN,KAAK,EAAE,cAAc,OAAO;AAAA,MAC5B,OAAO,EAAE,cAAc,SAAS;AAAA,MAChC,YAAY,EAAE,cAAc,eAAe;AAAA,MAC3C,UAAU,EAAE,cAAc,aAAa;AAAA,IACzC,EAAE;AAAA,EACJ;AACF;AAMO,MAAM,eAAe;AAAA,EAClB;AAAA,EAER,cAAc;AACZ,QAAI,CAAC,SAAS,SAAS;AACrB,YAAM,IAAI,MAAM,oFAAoF;AAAA,IACtG;AAEA,SAAK,SAAS,IAAI,OAAO;AAAA,MACvB,SAAS,SAAS;AAAA,MAClB,QAAQ,SAAS;AAAA,MACjB,SAAS,SAAS;AAAA,MAClB,YAAY;AAAA;AAAA,IACd,CAAC;AAAA,EACH;AAAA;AAAA;AAAA;AAAA,EAKQ,iBAAiB,OAAyB;AAChD,QAAI,CAAC,MAAO,QAAO;AAEnB,UAAM,MAAM;AAMZ,QAAI,IAAI,UAAU,yBAAyB,IAAI,IAAI,MAAM,GAAG;AAC1D,aAAO;AAAA,IACT;AAEA,UAAM,WAAW,IAAI,WAAW,IAAI,YAAY;AAChD,QACE,QAAQ,SAAS,YAAY,KAC7B,QAAQ,SAAS,SAAS,KAC1B,QAAQ,SAAS,WAAW,KAC5B,QAAQ,SAAS,qBAAqB,KACtC,QAAQ,SAAS,YAAY,KAC7B,QAAQ,SAAS,SAAS,GAC1B;AACA,aAAO;AAAA,IACT;AAGA,QAAI,IAAI,SAAS,cAAc,IAAI,SAAS,aAAa;AACvD,aAAO;AAAA,IACT;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAc,eACZ,SACA,OACA,QAC0G;AAC1G,QAAI;AAEJ,aAAS,UAAU,GAAG,WAAW,sBAAsB,WAAW;AAChE,UAAI;AACF,YAAI,UAAU,GAAG;AACf,iBAAO,WAAW,iBAAiB,OAAO,IAAI,oBAAoB,QAAQ,KAAK,IAAI,UAAU;AAAA,QAC/F;AAEA,cAAM,WAAW,MAAM;AAAA,UACrB,CAAC,gBAAgB;AAAA,YACf,CAAC,kBAAkB;AAEjB,oBAAM,mBAAmB,IAAI,gBAAgB;AAC7C,oBAAM,cAAc,MAAM,iBAAiB,MAAM;AACjD,sBAAQ,iBAAiB,SAAS,aAAa,EAAE,MAAM,KAAK,CAAC;AAC7D,0BAAY,iBAAiB,SAAS,aAAa,EAAE,MAAM,KAAK,CAAC;AACjE,4BAAc,iBAAiB,SAAS,aAAa,EAAE,MAAM,KAAK,CAAC;AAEnE,qBAAO,KAAK,OAAO,KAAK,YAAY;AAAA,gBAClC;AAAA,gBACA,EAAE,QAAQ,iBAAiB,OAAO;AAAA,cACpC,EAAE,QAAQ,MAAM;AACd,wBAAQ,oBAAoB,SAAS,WAAW;AAChD,4BAAY,oBAAoB,SAAS,WAAW;AACpD,8BAAc,oBAAoB,SAAS,WAAW;AAAA,cACxD,CAAC;AAAA,YACH;AAAA,YACA;AAAA,YACA,aAAa,KAAK;AAAA,UACpB;AAAA,UACA;AAAA,UACA;AAAA,UACA,aAAa,KAAK;AAAA,QACpB;AACA,cAAM,SAAS,SAAS,UAAU,CAAC;AACnC,cAAM,UAAU,QAAQ;AAGxB,YAAI,CAAC,SAAS,WAAW,CAAC,QAAQ;AAChC,sBAAY;AAAA,YACV,MAAM,UAAU;AAAA,YAChB,SAAS;AAAA,YACT,WAAW;AAAA,UACb;AAEA,cAAI,UAAU,sBAAsB;AAClC,kBAAM,UAAU,iBAAiB,SAAS,wBAAwB,qBAAqB;AACvF,mBAAO,WAAW,+BAA+B,OAAO,SAAS,UAAU;AAC3E,kBAAM,MAAM,SAAS,MAAM;AAC3B;AAAA,UACF;AAAA,QACF;AAEA,eAAO,EAAE,KAAK,EAAE,UAAU,QAAQ,QAAQ,EAAE;AAAA,MAE9C,SAAS,OAAgB;AACvB,oBAAY,cAAc,KAAK;AAE/B,cAAM,MAAM;AACZ,eAAO,SAAS,cAAc,KAAK,aAAa,UAAU,CAAC,MAAM,UAAU,OAAO,aAAa,IAAI,MAAM,KAAK,UAAU;AAExH,YAAI,KAAK,iBAAiB,KAAK,KAAK,UAAU,sBAAsB;AAClE,gBAAM,UAAU,iBAAiB,SAAS,wBAAwB,qBAAqB;AACvF,iBAAO,WAAW,eAAe,OAAO,SAAS,UAAU;AAC3D,cAAI;AAAE,kBAAM,MAAM,SAAS,MAAM;AAAA,UAAG,QAAQ;AAAE;AAAA,UAAO;AACrD;AAAA,QACF;AAEA;AAAA,MACF;AAAA,IACF;AAEA,WAAO;AAAA,MACL,OAAO,aAAa;AAAA,QAClB,MAAM,UAAU;AAAA,QAChB,SAAS;AAAA,QACT,WAAW;AAAA,MACb;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAc,gBACZ,OACA,UACA,SACA,QAC2B;AAC3B,UAAM,UAAU,qBAAqB,OAAO,UAAU,OAAO;AAC7D,UAAM,SAAS,MAAM,KAAK,eAAe,SAAS,OAAO,MAAM;AAE/D,QAAI,OAAO,KAAK;AACd,aAAO,sBAAsB,OAAO,KAAK,KAAK;AAAA,IAChD;AAEA,WAAO;AAAA,MACL,IAAI;AAAA,MACJ;AAAA,MACA,SAAS,KAAK,IAAI;AAAA,MAClB,SAAS;AAAA,MACT,OAAO,OAAO;AAAA,IAChB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,SAAS,QAAwB,QAAiD;AACtF,UAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA,kBAAkB,SAAS;AAAA,MAC3B,mBAAmB,SAAS;AAAA,MAC5B,YAAY;AAAA,MACZ,cAAc;AAAA,MACd;AAAA,IACF,IAAI;AAGJ,QAAI,CAAC,UAAU,KAAK,GAAG;AACrB,aAAO;AAAA,QACL,IAAI;AAAA,QACJ,OAAO,SAAS;AAAA,QAChB,SAAS,KAAK,IAAI;AAAA,QAClB,SAAS;AAAA,QACT,OAAO;AAAA,UACL,MAAM,UAAU;AAAA,UAChB,SAAS;AAAA,UACT,WAAW;AAAA,QACb;AAAA,MACF;AAAA,IACF;AAEA,UAAM,WAAgE,CAAC;AACvE,QAAI,cAAc;AAChB,eAAS,KAAK,EAAE,MAAM,UAAU,SAAS,aAAa,CAAC;AAAA,IACzD;AACA,aAAS,KAAK,EAAE,MAAM,QAAQ,SAAS,SAAS,CAAC;AAEjD,UAAM,UAAoC,EAAE,aAAa,iBAAiB,WAAW,kBAAkB,eAAe;AAGtH,WAAO,QAAQ,yBAAyB,SAAS,KAAK,IAAI,UAAU;AACpE,UAAM,gBAAgB,MAAM,KAAK,gBAAgB,SAAS,OAAO,UAAU,SAAS,MAAM;AAE1F,QAAI,CAAC,cAAc,OAAO;AACxB,aAAO;AAAA,IACT;AAGA,QAAI,SAAS,kBAAkB,SAAS,mBAAmB,SAAS,OAAO;AACzE,aAAO,WAAW,0CAA0C,SAAS,cAAc,IAAI,UAAU;AACjG,YAAM,iBAAiB,MAAM,KAAK,gBAAgB,SAAS,gBAAgB,UAAU,SAAS,MAAM;AAEpG,UAAI,CAAC,eAAe,OAAO;AACzB,eAAO;AAAA,MACT;AAGA,aAAO,SAAS,gCAAgC,cAAc,OAAO,OAAO,eAAe,eAAe,OAAO,OAAO,IAAI,UAAU;AACtI,aAAO;AAAA,QACL,GAAG;AAAA,QACH,SAAS,8CAA8C,SAAS,KAAK,MAAM,cAAc,OAAO,OAAO,eAAe,SAAS,cAAc,MAAM,eAAe,OAAO,OAAO;AAAA,MAClL;AAAA,IACF;AAGA,WAAO,SAAS,wBAAwB,cAAc,OAAO,OAAO,IAAI,UAAU;AAClF,WAAO;AAAA,MACL,GAAG;AAAA,MACH,SAAS,oBAAoB,cAAc,OAAO,OAAO;AAAA,IAC3D;AAAA,EACF;AACF;",
+  "names": ["payload"]
+}

package/dist/src/clients/scraper.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Web Scraper Client
+ * Generic interface for URL scraping with automatic fallback modes
+ * Implements robust error handling that NEVER crashes
+ */
+import { type StructuredError } from '../utils/errors.js';
+interface ScrapeRequest {
+    readonly url: string;
+    readonly mode?: 'basic' | 'javascript';
+    readonly timeout?: number;
+    readonly country?: string;
+}
+interface ScrapeResponse {
+    readonly content: string;
+    readonly statusCode: number;
+    readonly credits: number;
+    readonly headers?: Record<string, string>;
+    readonly error?: StructuredError;
+}
+interface BatchScrapeResult {
+    readonly results: ReadonlyArray<ScrapeResponse & {
+        readonly url: string;
+    }>;
+    readonly batchesProcessed: number;
+    readonly totalAttempted: number;
+    readonly rateLimitHits: number;
+}
+export declare class ScraperClient {
+    private apiKey;
+    private baseURL;
+    constructor(apiKey?: string);
+    /**
+     * Scrape a single URL with retry logic
+     * NEVER throws - always returns a ScrapeResponse (possibly with error)
+     */
+    scrape(request: ScrapeRequest, maxRetries?: 1): Promise<ScrapeResponse>;
+    /**
+     * Scrape with automatic fallback through different modes
+     * NEVER throws - always returns a ScrapeResponse
+     */
+    scrapeWithFallback(url: string, options?: {
+        timeout?: number;
+    }): Promise<ScrapeResponse>;
+    /**
+     * Execute a single fallback attempt and determine whether to continue.
+     * Returns { done: true } on success/terminal or { done: false } to try the next mode.
+     */
+    private tryFallbackAttempt;
+    /**
+     * Scrape multiple URLs with batching
+     * NEVER throws - always returns results array
+     */
+    scrapeMultiple(urls: string[], options?: {
+        timeout?: number;
+    }): Promise<Array<ScrapeResponse & {
+        url: string;
+    }>>;
+    /**
+     * Batch scrape with progress callback
+     * NEVER throws - uses Promise.allSettled internally
+     */
+    batchScrape(urls: string[], options?: {
+        timeout?: number;
+    }, onBatchComplete?: (batchNum: number, totalBatches: number, processed: number) => void): Promise<BatchScrapeResult>;
+    /**
+     * Process a single batch of URLs
+     * NEVER throws
+     */
+    private processBatch;
+}
+export {};
+//# sourceMappingURL=scraper.d.ts.map

package/dist/src/clients/scraper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scraper.d.ts","sourceRoot":"","sources":["../../../src/clients/scraper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAmB5B,UAAU,aAAa;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,UAAU,cAAc;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AAED,UAAU,iBAAiB;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,cAAc,GAAG;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3E,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAuBD,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAA2B;gBAE9B,MAAM,CAAC,EAAE,MAAM;IAS3B;;;OAGG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,UAAU,IAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IA0JvF;;;OAGG;IACG,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAwClG;;;OAGG;YACW,kBAAkB;IAkDhC;;;OAGG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,KAAK,CAAC,cAAc,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAa1H;;;OAGG;IACG,WAAW,CACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,EAClC,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,GACpF,OAAO,CAAC,iBAAiB,CAAC;IAoE7B;;;OAGG;YACW,YAAY;CAoB3B"}