mcp-researchpowerpack 3.9.4 → 4.3.0

package/dist/src/utils/errors.js

@@ -0,0 +1,211 @@
+import { mcpLog } from "./logger.js";
+const ErrorCode = {
+  // Retryable errors
+  RATE_LIMITED: "RATE_LIMITED",
+  TIMEOUT: "TIMEOUT",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+  // Non-retryable errors
+  AUTH_ERROR: "AUTH_ERROR",
+  INVALID_INPUT: "INVALID_INPUT",
+  NOT_FOUND: "NOT_FOUND",
+  QUOTA_EXCEEDED: "QUOTA_EXCEEDED",
+  // Internal errors
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  PARSE_ERROR: "PARSE_ERROR",
+  UNKNOWN_ERROR: "UNKNOWN_ERROR"
+};
+const DEFAULT_RETRY_OPTIONS = {
+  maxRetries: 3,
+  baseDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  retryableStatuses: [408, 429, 500, 502, 503, 504, 510]
+};
+function classifyDomException(error) {
+  if (error.name === "AbortError") {
+    return { code: ErrorCode.TIMEOUT, message: "Request timed out", retryable: true };
+  }
+  return { code: ErrorCode.UNKNOWN_ERROR, message: error.message, retryable: false };
+}
+function classifyByErrorCode(error) {
+  const errCode = error.code;
+  if (!errCode) return null;
+  const networkErrorMessages = {
+    ECONNREFUSED: "Connection refused \u2014 service may be down",
+    ECONNRESET: "Connection was reset \u2014 please retry",
+    ECONNABORTED: "Connection aborted \u2014 please retry",
+    ENOTFOUND: "Service not reachable \u2014 check your network",
+    EPIPE: "Connection lost \u2014 please retry",
+    EAI_AGAIN: "DNS lookup failed \u2014 check your network"
+  };
+  if (errCode === "ECONNREFUSED" || errCode === "ENOTFOUND" || errCode === "ECONNRESET") {
+    return { code: ErrorCode.NETWORK_ERROR, message: networkErrorMessages[errCode] || "Network connection failed", retryable: true, cause: error.message };
+  }
+  if (errCode === "ECONNABORTED" || errCode === "ETIMEDOUT") {
+    return { code: ErrorCode.TIMEOUT, message: networkErrorMessages[errCode] || "Request timed out", retryable: true, cause: error.message };
+  }
+  return null;
+}
+function classifyByStatusCode(error) {
+  const status = error.response?.status || error.status || error.statusCode;
+  if (!status) return null;
+  return classifyHttpError(status, error.message || String(error));
+}
+function classifyByMessage(message) {
+  const lower = message.toLowerCase();
+  if (lower.includes("timeout") || lower.includes("timed out") || lower.includes("aborterror")) {
+    return { code: ErrorCode.TIMEOUT, message: "Request timed out", retryable: true, cause: message };
+  }
+  if (lower.includes("rate limit") || lower.includes("too many requests")) {
+    return { code: ErrorCode.RATE_LIMITED, message: "Rate limit exceeded", retryable: true, cause: message };
+  }
+  if (message.includes("API_KEY") || message.includes("api_key") || message.includes("Invalid API")) {
+    return { code: ErrorCode.AUTH_ERROR, message: "API key missing or invalid", retryable: false, cause: message };
+  }
+  if (message.includes("JSON") || message.includes("parse") || message.includes("Unexpected token")) {
+    return { code: ErrorCode.PARSE_ERROR, message: "Failed to parse response", retryable: false, cause: message };
+  }
+  return null;
+}
+function classifyFallback(message, cause) {
+  return {
+    code: ErrorCode.UNKNOWN_ERROR,
+    message,
+    retryable: false,
+    cause: cause ? String(cause) : void 0
+  };
+}
+function classifyError(error) {
+  if (error == null) {
+    return { code: ErrorCode.UNKNOWN_ERROR, message: "An unknown error occurred", retryable: false };
+  }
+  if (error instanceof DOMException) return classifyDomException(error);
+  if (!isErrorLike(error)) {
+    return { code: ErrorCode.UNKNOWN_ERROR, message: String(error), retryable: false };
+  }
+  return classifyByErrorCode(error) ?? classifyByStatusCode(error) ?? classifyByMessage(error.message ?? String(error)) ?? classifyFallback(error.message ?? String(error), error.cause);
+}
+function isErrorLike(value) {
+  return typeof value === "object" && value !== null;
+}
+function classifyHttpError(status, message) {
+  switch (status) {
+    case 400:
+      return { code: ErrorCode.INVALID_INPUT, message: "Bad request", retryable: false, statusCode: status };
+    case 401:
+      return { code: ErrorCode.AUTH_ERROR, message: "Invalid API key", retryable: false, statusCode: status };
+    case 403:
+      return { code: ErrorCode.QUOTA_EXCEEDED, message: "Access forbidden or quota exceeded", retryable: false, statusCode: status };
+    case 404:
+      return { code: ErrorCode.NOT_FOUND, message: "Resource not found", retryable: false, statusCode: status };
+    case 408:
+      return { code: ErrorCode.TIMEOUT, message: "Request timeout", retryable: true, statusCode: status };
+    case 429:
+      return { code: ErrorCode.RATE_LIMITED, message: "Rate limit exceeded", retryable: true, statusCode: status };
+    case 500:
+      return { code: ErrorCode.INTERNAL_ERROR, message: "Server error", retryable: true, statusCode: status };
+    case 502:
+      return { code: ErrorCode.SERVICE_UNAVAILABLE, message: "Bad gateway", retryable: true, statusCode: status };
+    case 503:
+      return { code: ErrorCode.SERVICE_UNAVAILABLE, message: "Service unavailable", retryable: true, statusCode: status };
+    case 504:
+      return { code: ErrorCode.TIMEOUT, message: "Gateway timeout", retryable: true, statusCode: status };
+    case 510:
+      return { code: ErrorCode.SERVICE_UNAVAILABLE, message: "Request canceled", retryable: true, statusCode: status };
+    default:
+      if (status >= 500) {
+        return { code: ErrorCode.SERVICE_UNAVAILABLE, message: `Server error: ${status}`, retryable: true, statusCode: status };
+      }
+      if (status >= 400) {
+        return { code: ErrorCode.INVALID_INPUT, message: `Client error: ${status}`, retryable: false, statusCode: status };
+      }
+      return { code: ErrorCode.UNKNOWN_ERROR, message: `HTTP ${status}: ${message}`, retryable: false, statusCode: status };
+  }
+}
+function calculateBackoff(attempt, options) {
+  const exponentialDelay = options.baseDelayMs * Math.pow(2, attempt);
+  const jitter = Math.random() * 0.3 * exponentialDelay;
+  return Math.min(exponentialDelay + jitter, options.maxDelayMs);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException("Aborted", "AbortError"));
+      return;
+    }
+    function onAbort() {
+      clearTimeout(timeout);
+      reject(new DOMException("Aborted", "AbortError"));
+    }
+    const timeout = setTimeout(() => {
+      if (signal) signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+    }
+  });
+}
+function fetchWithTimeout(url, options = {}) {
+  const { timeoutMs = 3e4, signal: externalSignal, ...fetchOptions } = options;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  let onExternalAbort;
+  if (externalSignal) {
+    onExternalAbort = () => controller.abort();
+    externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+    if (externalSignal.aborted) {
+      controller.abort();
+    }
+  }
+  return fetch(url, { ...fetchOptions, signal: controller.signal }).finally(() => {
+    clearTimeout(timeoutId);
+    if (externalSignal && onExternalAbort) {
+      externalSignal.removeEventListener("abort", onExternalAbort);
+    }
+  });
+}
+async function withStallProtection(fn, stallMs, maxAttempts = 2, label = "request") {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const controller = new AbortController();
+    let stallTimer;
+    const stallPromise = new Promise((_, reject) => {
+      stallTimer = setTimeout(() => {
+        controller.abort();
+        reject(Object.assign(new Error(`Service temporarily unavailable \u2014 no response received (attempt ${attempt + 1}/${maxAttempts})`), {
+          code: "ESTALLED",
+          retryable: attempt < maxAttempts - 1
+        }));
+      }, stallMs);
+    });
+    let fnPromise;
+    try {
+      fnPromise = fn(controller.signal);
+      const result = await Promise.race([fnPromise, stallPromise]);
+      clearTimeout(stallTimer);
+      return result;
+    } catch (err) {
+      fnPromise?.catch(() => {
+      });
+      clearTimeout(stallTimer);
+      const isStall = err instanceof Error && err.code === "ESTALLED";
+      if (isStall && attempt < maxAttempts - 1) {
+        const backoff = calculateBackoff(attempt, DEFAULT_RETRY_OPTIONS);
+        mcpLog("warning", `${label} stalled, retrying in ${backoff}ms (attempt ${attempt + 1})`, "stability");
+        await sleep(backoff);
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw new Error(`${label} failed after ${maxAttempts} stall-protection attempts`);
+}
+export {
+  ErrorCode,
+  classifyError,
+  fetchWithTimeout,
+  sleep,
+  withStallProtection
+};
+//# sourceMappingURL=errors.js.map

package/dist/src/utils/errors.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/errors.ts"],
+  "sourcesContent": ["/**\n * Robust error handling utilities for MCP server\n * Ensures the server NEVER crashes and always returns structured responses\n */\n\nimport { mcpLog } from './logger.js';\n\n// ============================================================================\n// Error Codes (MCP-compliant)\n// ============================================================================\n\nexport const ErrorCode = {\n  // Retryable errors\n  RATE_LIMITED: 'RATE_LIMITED',\n  TIMEOUT: 'TIMEOUT',\n  NETWORK_ERROR: 'NETWORK_ERROR',\n  SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',\n  \n  // Non-retryable errors\n  AUTH_ERROR: 'AUTH_ERROR',\n  INVALID_INPUT: 'INVALID_INPUT',\n  NOT_FOUND: 'NOT_FOUND',\n  QUOTA_EXCEEDED: 'QUOTA_EXCEEDED',\n  \n  // Internal errors\n  INTERNAL_ERROR: 'INTERNAL_ERROR',\n  PARSE_ERROR: 'PARSE_ERROR',\n  UNKNOWN_ERROR: 'UNKNOWN_ERROR',\n} as const;\n\ntype ErrorCodeType = typeof ErrorCode[keyof typeof ErrorCode];\n\n// ============================================================================\n// Structured Error Types\n// ============================================================================\n\nexport interface StructuredError {\n  code: ErrorCodeType;\n  message: string;\n  retryable: boolean;\n  statusCode?: number;\n  cause?: string;\n}\n\ninterface RetryOptions {\n  readonly maxRetries: number;\n  readonly baseDelayMs: number;\n  readonly maxDelayMs: number;\n  readonly retryableStatuses: readonly number[];\n  readonly onRetry?: (attempt: number, error: StructuredError, delayMs: number) => void;\n}\n\nconst DEFAULT_RETRY_OPTIONS: RetryOptions = {\n  maxRetries: 3,\n  baseDelayMs: 1000,\n  maxDelayMs: 30000,\n  retryableStatuses: [408, 429, 500, 502, 503, 504, 510],\n};\n\n// ============================================================================\n// Error Classification \u2014 Atomic Classifiers\n// ============================================================================\n\n/**\n * Classify DOMException (AbortError from AbortController timeouts)\n */\nfunction classifyDomException(error: DOMException): StructuredError {\n  if (error.name === 'AbortError') {\n    return { code: ErrorCode.TIMEOUT, message: 'Request timed out', retryable: true };\n  }\n  return { code: ErrorCode.UNKNOWN_ERROR, message: error.message, retryable: false };\n}\n\n/**\n * Classify by Node.js error codes (ECONNREFUSED, ENOTFOUND, etc.)\n * Returns null if no matching code is found.\n */\nfunction classifyByErrorCode(error: { code?: string; message?: string }): StructuredError | null {\n  const errCode = error.code;\n  if (!errCode) return null;\n\n  const networkErrorMessages: Record<string, string> = {\n    ECONNREFUSED: 'Connection refused \u2014 service may be down',\n    ECONNRESET: 'Connection was reset \u2014 please retry',\n    ECONNABORTED: 'Connection aborted \u2014 please retry',\n    ENOTFOUND: 'Service not reachable \u2014 check your network',\n    EPIPE: 'Connection lost \u2014 please retry',\n    EAI_AGAIN: 'DNS lookup failed \u2014 check your network',\n  };\n\n  if (errCode === 'ECONNREFUSED' || errCode === 'ENOTFOUND' || errCode === 'ECONNRESET') {\n    return { code: ErrorCode.NETWORK_ERROR, message: networkErrorMessages[errCode] || 'Network connection failed', retryable: true, cause: error.message };\n  }\n\n  if (errCode === 'ECONNABORTED' || errCode === 'ETIMEDOUT') {\n    return { code: ErrorCode.TIMEOUT, message: networkErrorMessages[errCode] || 'Request timed out', retryable: true, cause: error.message };\n  }\n\n  return null;\n}\n\n/**\n * Classify by HTTP status code extracted from error objects (axios-style, fetch-style, etc.)\n * Returns null if no status code is found.\n */\nfunction classifyByStatusCode(error: { status?: number; statusCode?: number; response?: { status?: number }; message?: string }): StructuredError | null {\n  const status = error.response?.status || error.status || error.statusCode;\n  if (!status) return null;\n  return classifyHttpError(status, error.message || String(error));\n}\n\n/**\n * Classify by error message patterns (timeout, rate-limit, auth, parse errors)\n * Returns null if no pattern matches.\n */\nfunction classifyByMessage(message: string): StructuredError | null {\n  const lower = message.toLowerCase();\n\n  // Timeout patterns\n  if (lower.includes('timeout') || lower.includes('timed out') || lower.includes('aborterror')) {\n    return { code: ErrorCode.TIMEOUT, message: 'Request timed out', retryable: true, cause: message };\n  }\n\n  // Rate-limit patterns\n  if (lower.includes('rate limit') || lower.includes('too many requests')) {\n    return { code: ErrorCode.RATE_LIMITED, message: 'Rate limit exceeded', retryable: true, cause: message };\n  }\n\n  // API key errors\n  if (message.includes('API_KEY') || message.includes('api_key') || message.includes('Invalid API')) {\n    return { code: ErrorCode.AUTH_ERROR, message: 'API key missing or invalid', retryable: false, cause: message };\n  }\n\n  // Parse errors\n  if (message.includes('JSON') || message.includes('parse') || message.includes('Unexpected token')) {\n    return { code: ErrorCode.PARSE_ERROR, message: 'Failed to parse response', retryable: false, cause: message };\n  }\n\n  return null;\n}\n\n/**\n * Catch-all fallback classification when no other classifier matches.\n */\nfunction classifyFallback(message: string, cause?: unknown): StructuredError {\n  return {\n    code: ErrorCode.UNKNOWN_ERROR,\n    message,\n    retryable: false,\n    cause: cause ? String(cause) : undefined,\n  };\n}\n\n// ============================================================================\n// Main Error Classification Pipeline\n// ============================================================================\n\n/**\n * Classify any error into a structured format.\n * NEVER throws \u2014 always returns a valid StructuredError.\n */\nexport function classifyError(error: unknown): StructuredError {\n  if (error == null) {\n    return { code: ErrorCode.UNKNOWN_ERROR, message: 'An unknown error occurred', retryable: false };\n  }\n\n  if (error instanceof DOMException) return classifyDomException(error);\n\n  if (!isErrorLike(error)) {\n    return { code: ErrorCode.UNKNOWN_ERROR, message: String(error), retryable: false };\n  }\n\n  return classifyByErrorCode(error)\n    ?? classifyByStatusCode(error)\n    ?? classifyByMessage(error.message ?? String(error))\n    ?? classifyFallback(error.message ?? String(error), error.cause);\n}\n\n/**\n * Type guard for error-like objects with common error properties\n */\nfunction isErrorLike(value: unknown): value is {\n  message?: string;\n  response?: { status?: number; data?: unknown };\n  status?: number;\n  statusCode?: number;\n  code?: string;\n  name?: string;\n  cause?: unknown;\n} {\n  return typeof value === 'object' && value !== null;\n}\n\n/**\n * Classify HTTP status codes into structured errors.\n * Exhaustive switch with grouped default handling for unknown ranges.\n */\nfunction classifyHttpError(status: number, message: string): StructuredError {\n  switch (status) {\n    case 400:\n      return { code: ErrorCode.INVALID_INPUT, message: 'Bad request', retryable: false, statusCode: status };\n    case 401:\n      return { code: ErrorCode.AUTH_ERROR, message: 'Invalid API key', retryable: false, statusCode: status };\n    case 403:\n      return { code: ErrorCode.QUOTA_EXCEEDED, message: 'Access forbidden or quota exceeded', retryable: false, statusCode: status };\n    case 404:\n      return { code: ErrorCode.NOT_FOUND, message: 'Resource not found', retryable: false, statusCode: status };\n    case 408:\n      return { code: ErrorCode.TIMEOUT, message: 'Request timeout', retryable: true, statusCode: status };\n    case 429:\n      return { code: ErrorCode.RATE_LIMITED, message: 'Rate limit exceeded', retryable: true, statusCode: status };\n    case 500:\n      return { code: ErrorCode.INTERNAL_ERROR, message: 'Server error', retryable: true, statusCode: status };\n    case 502:\n      return { code: ErrorCode.SERVICE_UNAVAILABLE, message: 'Bad gateway', retryable: true, statusCode: status };\n    case 503:\n      return { code: ErrorCode.SERVICE_UNAVAILABLE, message: 'Service unavailable', retryable: true, statusCode: status };\n    case 504:\n      return { code: ErrorCode.TIMEOUT, message: 'Gateway timeout', retryable: true, statusCode: status };\n    case 510:\n      return { code: ErrorCode.SERVICE_UNAVAILABLE, message: 'Request canceled', retryable: true, statusCode: status };\n    default:\n      if (status >= 500) {\n        return { code: ErrorCode.SERVICE_UNAVAILABLE, message: `Server error: ${status}`, retryable: true, statusCode: status };\n      }\n      if (status >= 400) {\n        return { code: ErrorCode.INVALID_INPUT, message: `Client error: ${status}`, retryable: false, statusCode: status };\n      }\n      return { code: ErrorCode.UNKNOWN_ERROR, message: `HTTP ${status}: ${message}`, retryable: false, statusCode: status };\n  }\n}\n\n// ============================================================================\n// Retry Logic with Exponential Backoff\n// ============================================================================\n\n/**\n * Calculate delay with exponential backoff and jitter\n */\nfunction calculateBackoff(attempt: number, options: RetryOptions): number {\n  const exponentialDelay = options.baseDelayMs * Math.pow(2, attempt);\n  const jitter = Math.random() * 0.3 * exponentialDelay; // 0-30% jitter\n  return Math.min(exponentialDelay + jitter, options.maxDelayMs);\n}\n\n/**\n * Sleep utility that respects abort signals\n */\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new DOMException('Aborted', 'AbortError'));\n      return;\n    }\n\n    function onAbort() {\n      clearTimeout(timeout);\n      reject(new DOMException('Aborted', 'AbortError'));\n    }\n\n    const timeout = setTimeout(() => {\n      if (signal) signal.removeEventListener('abort', onAbort);\n      resolve();\n    }, ms);\n\n    signal?.addEventListener('abort', onAbort, { once: true });\n    // Re-check: signal may have aborted between initial check and listener registration\n    if (signal?.aborted) {\n      onAbort();\n    }\n  });\n}\n\n/**\n * Wrap a fetch call with timeout via AbortController\n */\nexport function fetchWithTimeout(\n  url: string,\n  options: RequestInit & { timeoutMs?: number } = {}\n): Promise<Response> {\n  const { timeoutMs = 30000, signal: externalSignal, ...fetchOptions } = options;\n\n  const controller = new AbortController();\n  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);\n\n  let onExternalAbort: (() => void) | undefined;\n  if (externalSignal) {\n    onExternalAbort = () => controller.abort();\n    externalSignal.addEventListener('abort', onExternalAbort, { once: true });\n    if (externalSignal.aborted) {\n      controller.abort();\n    }\n  }\n\n  return fetch(url, { ...fetchOptions, signal: controller.signal }).finally(() => {\n    clearTimeout(timeoutId);\n    if (externalSignal && onExternalAbort) {\n      externalSignal.removeEventListener('abort', onExternalAbort);\n    }\n  });\n}\n\n// ============================================================================\n// Stability Wrappers \u2014 Network resilience for LLM API calls\n// ============================================================================\n\n/**\n * Wrap a non-streaming API call with activity-based timeout detection.\n * If the call hasn't completed within `stallMs`, abort and retry.\n * This catches \"stuck\" connections where TCP stays open but no data flows.\n *\n * @param fn - Async function that accepts an AbortSignal\n * @param stallMs - Max milliseconds to wait for the call to complete before considering it stuck\n * @param maxAttempts - Max retry attempts for stalled requests\n * @param label - Label for log messages\n * @returns The result of the function\n */\nexport async function withStallProtection<T>(\n  fn: (signal: AbortSignal) => Promise<T>,\n  stallMs: number,\n  maxAttempts: number = 2,\n  label: string = 'request',\n): Promise<T> {\n  for (let attempt = 0; attempt < maxAttempts; attempt++) {\n    const controller = new AbortController();\n    let stallTimer: ReturnType<typeof setTimeout> | undefined;\n\n    const stallPromise = new Promise<never>((_, reject) => {\n      stallTimer = setTimeout(() => {\n        controller.abort();\n        reject(Object.assign(new Error(`Service temporarily unavailable \u2014 no response received (attempt ${attempt + 1}/${maxAttempts})`), {\n          code: 'ESTALLED',\n          retryable: attempt < maxAttempts - 1,\n        }));\n      }, stallMs);\n    });\n\n    let fnPromise: Promise<T> | undefined;\n    try {\n      fnPromise = fn(controller.signal);\n      const result = await Promise.race([fnPromise, stallPromise]);\n      clearTimeout(stallTimer);\n      return result;\n    } catch (err) {\n      // Suppress unhandled rejection from the losing promise\n      // (e.g. fnPromise rejects after stallPromise wins the race)\n      fnPromise?.catch(() => {});\n      clearTimeout(stallTimer);\n      const isStall = err instanceof Error && (err as NodeJS.ErrnoException).code === 'ESTALLED';\n      if (isStall && attempt < maxAttempts - 1) {\n        const backoff = calculateBackoff(attempt, DEFAULT_RETRY_OPTIONS);\n        mcpLog('warning', `${label} stalled, retrying in ${backoff}ms (attempt ${attempt + 1})`, 'stability');\n        await sleep(backoff);\n        continue;\n      }\n      throw err;\n    }\n  }\n  // Should never reach here, but TypeScript needs it\n  throw new Error(`${label} failed after ${maxAttempts} stall-protection attempts`);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/src/utils/logger.js

@@ -0,0 +1,25 @@
+import { Logger } from "mcp-use";
+function getLogger(name) {
+  return Logger.get(name);
+}
+function mcpLog(level, message, loggerName) {
+  const logger = getLogger(loggerName ?? "research-powerpack");
+  switch (level) {
+    case "debug":
+      logger.debug(message);
+      break;
+    case "info":
+      logger.info(message);
+      break;
+    case "warning":
+      logger.warn(message);
+      break;
+    case "error":
+      logger.error(message);
+      break;
+  }
+}
+export {
+  mcpLog
+};
+//# sourceMappingURL=logger.js.map

package/dist/src/utils/logger.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/logger.ts"],
+  "sourcesContent": ["/**\n * Server logging utility.\n *\n * This server is HTTP-only, so logging must never depend on a transport-bound\n * MCP server instance. All logs flow through mcp-use's Logger, which writes to\n * stderr in Node and console in the browser.\n */\n\nimport { Logger } from 'mcp-use';\n\nexport type LogLevel = 'debug' | 'info' | 'warning' | 'error';\n\nfunction getLogger(name: string) {\n  return Logger.get(name);\n}\n\n/**\n * Structured log helper backed by mcp-use's Logger.\n *\n * @param level - Log level.\n * @param message - Message to emit.\n * @param loggerName - Tool/component name for context (falls back to \"research-powerpack\").\n */\nexport function mcpLog(level: LogLevel, message: string, loggerName?: string): void {\n  const logger = getLogger(loggerName ?? 'research-powerpack');\n\n  switch (level) {\n    case 'debug':\n      logger.debug(message);\n      break;\n    case 'info':\n      logger.info(message);\n      break;\n    case 'warning':\n      logger.warn(message);\n      break;\n    case 'error':\n      logger.error(message);\n      break;\n  }\n}\n"],
+  "mappings": "AAQA,SAAS,cAAc;AAIvB,SAAS,UAAU,MAAc;AAC/B,SAAO,OAAO,IAAI,IAAI;AACxB;AASO,SAAS,OAAO,OAAiB,SAAiB,YAA2B;AAClF,QAAM,SAAS,UAAU,cAAc,oBAAoB;AAE3D,UAAQ,OAAO;AAAA,IACb,KAAK;AACH,aAAO,MAAM,OAAO;AACpB;AAAA,IACF,KAAK;AACH,aAAO,KAAK,OAAO;AACnB;AAAA,IACF,KAAK;AACH,aAAO,KAAK,OAAO;AACnB;AAAA,IACF,KAAK;AACH,aAAO,MAAM,OAAO;AACpB;AAAA,EACJ;AACF;",
+  "names": []
+}

package/dist/src/utils/markdown-formatter.js

@@ -0,0 +1,15 @@
+function removeMetaTags(content) {
+  if (!content || typeof content !== "string") {
+    return content;
+  }
+  const lines = content.split("\n");
+  const filteredLines = lines.filter((line) => {
+    const trimmed = line.trim();
+    return !trimmed.startsWith("- Meta:") && !trimmed.startsWith("Meta:");
+  });
+  return filteredLines.join("\n");
+}
+export {
+  removeMetaTags
+};
+//# sourceMappingURL=markdown-formatter.js.map

package/dist/src/utils/markdown-formatter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/markdown-formatter.ts"],
+  "sourcesContent": ["/**\n * Markdown formatting utilities\n */\n\nexport function removeMetaTags(content: string): string {\n  if (!content || typeof content !== 'string') {\n    return content;\n  }\n\n  const lines = content.split('\\n');\n  const filteredLines = lines.filter(line => {\n    const trimmed = line.trim();\n    return !trimmed.startsWith('- Meta:') && !trimmed.startsWith('Meta:');\n  });\n\n  return filteredLines.join('\\n');\n}\n"],
+  "mappings": "AAIO,SAAS,eAAe,SAAyB;AACtD,MAAI,CAAC,WAAW,OAAO,YAAY,UAAU;AAC3C,WAAO;AAAA,EACT;AAEA,QAAM,QAAQ,QAAQ,MAAM,IAAI;AAChC,QAAM,gBAAgB,MAAM,OAAO,UAAQ;AACzC,UAAM,UAAU,KAAK,KAAK;AAC1B,WAAO,CAAC,QAAQ,WAAW,SAAS,KAAK,CAAC,QAAQ,WAAW,OAAO;AAAA,EACtE,CAAC;AAED,SAAO,cAAc,KAAK,IAAI;AAChC;",
+  "names": []
+}

package/dist/src/utils/reddit-keyword-guard.js

@@ -0,0 +1,29 @@
+import { error } from "mcp-use/server";
+import {
+  getWorkflowStateStore
+} from "../services/workflow-state.js";
+import { buildWorkflowKey } from "./workflow-key.js";
+const REDDIT_KEYWORD_PATTERN = /\breddit\b/i;
+async function redditKeywordGuard(ctx, queries, store = getWorkflowStateStore()) {
+  const matchedQuery = queries.find((query) => REDDIT_KEYWORD_PATTERN.test(query));
+  if (!matchedQuery) {
+    return null;
+  }
+  const workflowKey = buildWorkflowKey(ctx);
+  const state = await store.get(workflowKey);
+  if (state.redditWarningShown) {
+    return null;
+  }
+  await store.patch(workflowKey, { redditWarningShown: true });
+  return error([
+    "\u274C Putting `reddit` in a `web-search` query without setting the scope flag wastes a turn \u2014 the result is biased toward subreddit homepages and namesake hits.",
+    "",
+    `Blocked query: ${matchedQuery}`,
+    "",
+    'For Reddit discovery, call `web-search` with `scope: "reddit"` \u2014 the server appends `site:reddit.com` and filters results to post permalinks. For non-Reddit web search, drop the word "reddit" from the query.'
+  ].join("\n"));
+}
+export {
+  redditKeywordGuard
+};
+//# sourceMappingURL=reddit-keyword-guard.js.map

package/dist/src/utils/reddit-keyword-guard.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/reddit-keyword-guard.ts"],
+  "sourcesContent": ["import { error, type TypedCallToolResult } from 'mcp-use/server';\n\nimport {\n  getWorkflowStateStore,\n  type WorkflowStateStore,\n} from '../services/workflow-state.js';\nimport { buildWorkflowKey, type WorkflowKeyContext } from './workflow-key.js';\n\nconst REDDIT_KEYWORD_PATTERN = /\\breddit\\b/i;\n\nexport async function redditKeywordGuard(\n  ctx: WorkflowKeyContext,\n  queries: string[],\n  store: WorkflowStateStore = getWorkflowStateStore(),\n): Promise<TypedCallToolResult<never> | null> {\n  const matchedQuery = queries.find((query) => REDDIT_KEYWORD_PATTERN.test(query));\n  if (!matchedQuery) {\n    return null;\n  }\n\n  const workflowKey = buildWorkflowKey(ctx);\n  const state = await store.get(workflowKey);\n  if (state.redditWarningShown) {\n    return null;\n  }\n\n  await store.patch(workflowKey, { redditWarningShown: true });\n\n  return error([\n    '\u274C Putting `reddit` in a `web-search` query without setting the scope flag wastes a turn \u2014 the result is biased toward subreddit homepages and namesake hits.',\n    '',\n    `Blocked query: ${matchedQuery}`,\n    '',\n    'For Reddit discovery, call `web-search` with `scope: \"reddit\"` \u2014 the server appends `site:reddit.com` and filters results to post permalinks. For non-Reddit web search, drop the word \"reddit\" from the query.',\n  ].join('\\n'));\n}\n"],
+  "mappings": "AAAA,SAAS,aAAuC;AAEhD;AAAA,EACE;AAAA,OAEK;AACP,SAAS,wBAAiD;AAE1D,MAAM,yBAAyB;AAE/B,eAAsB,mBACpB,KACA,SACA,QAA4B,sBAAsB,GACN;AAC5C,QAAM,eAAe,QAAQ,KAAK,CAAC,UAAU,uBAAuB,KAAK,KAAK,CAAC;AAC/E,MAAI,CAAC,cAAc;AACjB,WAAO;AAAA,EACT;AAEA,QAAM,cAAc,iBAAiB,GAAG;AACxC,QAAM,QAAQ,MAAM,MAAM,IAAI,WAAW;AACzC,MAAI,MAAM,oBAAoB;AAC5B,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,MAAM,aAAa,EAAE,oBAAoB,KAAK,CAAC;AAE3D,SAAO,MAAM;AAAA,IACX;AAAA,IACA;AAAA,IACA,kBAAkB,YAAY;AAAA,IAC9B;AAAA,IACA;AAAA,EACF,EAAE,KAAK,IAAI,CAAC;AACd;",
+  "names": []
+}

package/dist/src/utils/response.js

@@ -0,0 +1,81 @@
+const SECONDS_MS = 1e3;
+const MINUTES_MS = 6e4;
+function formatSuccess(opts) {
+  const parts = [];
+  parts.push(`\u2713 ${opts.title}`);
+  parts.push("");
+  parts.push(opts.summary);
+  if (opts.data) {
+    parts.push("");
+    parts.push("---");
+    parts.push(opts.data);
+  }
+  if (opts.nextSteps?.length) {
+    parts.push("");
+    parts.push("---");
+    parts.push("**Next Steps:**");
+    opts.nextSteps.forEach((step) => parts.push(`\u2192 ${step}`));
+  }
+  if (opts.metadata && Object.keys(opts.metadata).length > 0) {
+    parts.push("");
+    parts.push("---");
+    const metaStr = Object.entries(opts.metadata).map(([k, v]) => `${k}: ${v}`).join(" | ");
+    parts.push(`*${metaStr}*`);
+  }
+  return parts.join("\n");
+}
+function formatError(opts) {
+  const parts = [];
+  const prefix = opts.toolName ? `[${opts.toolName}] ` : "";
+  parts.push(`\u274C ${prefix}${opts.code}: ${opts.message}`);
+  if (opts.retryable) {
+    parts.push("*Retryable.*");
+  }
+  if (opts.howToFix?.length) {
+    parts.push("");
+    parts.push("**How to Fix:**");
+    opts.howToFix.forEach((step, i) => parts.push(`${i + 1}. ${step}`));
+  }
+  if (opts.alternatives?.length) {
+    parts.push("");
+    parts.push("**Alternatives:**");
+    opts.alternatives.forEach((alt, i) => parts.push(`${i + 1}. ${alt}`));
+  }
+  return parts.join("\n");
+}
+function formatBatchHeader(opts) {
+  const parts = [];
+  const successRate = opts.totalItems > 0 ? opts.successful / opts.totalItems : 0;
+  const emoji = successRate === 1 ? "\u2713" : successRate >= 0.5 ? "\u26A0\uFE0F" : "\u274C";
+  parts.push(`${emoji} ${opts.title}`);
+  parts.push("");
+  parts.push(`\u2022 Total: ${opts.totalItems}`);
+  parts.push(`\u2022 Successful: ${opts.successful}`);
+  if (opts.failed > 0) {
+    parts.push(`\u2022 Failed: ${opts.failed}`);
+  }
+  if (opts.tokensPerItem) {
+    parts.push(`\u2022 Tokens/item: ~${opts.tokensPerItem.toLocaleString()}`);
+  }
+  if (opts.batches) {
+    parts.push(`\u2022 Batches: ${opts.batches}`);
+  }
+  if (opts.extras) {
+    Object.entries(opts.extras).forEach(([key, val]) => {
+      parts.push(`\u2022 ${key}: ${val}`);
+    });
+  }
+  return parts.join("\n");
+}
+function formatDuration(ms) {
+  if (ms < SECONDS_MS) return `${ms}ms`;
+  if (ms < MINUTES_MS) return `${(ms / SECONDS_MS).toFixed(1)}s`;
+  return `${(ms / MINUTES_MS).toFixed(1)}m`;
+}
+export {
+  formatBatchHeader,
+  formatDuration,
+  formatError,
+  formatSuccess
+};
+//# sourceMappingURL=response.js.map

package/dist/src/utils/response.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/response.ts"],
+  "sourcesContent": ["/**\n * MCP Response Formatters\n */\n\n/** Duration thresholds in milliseconds */\nconst SECONDS_MS = 1_000 as const;\nconst MINUTES_MS = 60_000 as const;\n\n// ============================================================================\n// Success Response Formatter\n// ============================================================================\n\nexport interface SuccessOptions {\n  /** Title/header for the response */\n  readonly title: string;\n  /** Summary section (70% of content) */\n  readonly summary: string;\n  /** Optional data section (20% of content) */\n  readonly data?: string;\n  /** Optional next steps (10% of content) */\n  readonly nextSteps?: string[];\n  /** Optional metadata footer */\n  readonly metadata?: Record<string, string | number>;\n}\n\n/**\n * Format a successful response using 70/20/10 pattern\n */\nexport function formatSuccess(opts: SuccessOptions): string {\n  const parts: string[] = [];\n\n  // Title\n  parts.push(`\u2713 ${opts.title}`);\n  parts.push('');\n\n  // Summary (70%)\n  parts.push(opts.summary);\n\n  // Data section (20%)\n  if (opts.data) {\n    parts.push('');\n    parts.push('---');\n    parts.push(opts.data);\n  }\n\n  // Next steps (10%)\n  if (opts.nextSteps?.length) {\n    parts.push('');\n    parts.push('---');\n    parts.push('**Next Steps:**');\n    opts.nextSteps.forEach(step => parts.push(`\u2192 ${step}`));\n  }\n\n  // Metadata footer\n  if (opts.metadata && Object.keys(opts.metadata).length > 0) {\n    parts.push('');\n    parts.push('---');\n    const metaStr = Object.entries(opts.metadata)\n      .map(([k, v]) => `${k}: ${v}`)\n      .join(' | ');\n    parts.push(`*${metaStr}*`);\n  }\n\n  return parts.join('\\n');\n}\n\n// ============================================================================\n// Error Response Formatter\n// ============================================================================\n\nexport interface ErrorOptions {\n  /** Error code (e.g., RATE_LIMITED, TIMEOUT) */\n  readonly code: string;\n  /** Human-readable error message */\n  readonly message: string;\n  /** Is this error retryable? */\n  readonly retryable?: boolean;\n  /** How to fix the error */\n  readonly howToFix?: string[];\n  /** Alternative actions */\n  readonly alternatives?: string[];\n  /** Tool name for context */\n  readonly toolName?: string;\n}\n\n/**\n * Format an error response with recovery guidance\n * Designed to keep agents moving \u2014 every error includes actionable alternatives\n */\nexport function formatError(opts: ErrorOptions): string {\n  const parts: string[] = [];\n\n  // Error header\n  const prefix = opts.toolName ? `[${opts.toolName}] ` : '';\n  parts.push(`\u274C ${prefix}${opts.code}: ${opts.message}`);\n\n  // Retryable hint\n  if (opts.retryable) {\n    parts.push('*Retryable.*');\n  }\n\n  // How to fix\n  if (opts.howToFix?.length) {\n    parts.push('');\n    parts.push('**How to Fix:**');\n    opts.howToFix.forEach((step, i) => parts.push(`${i + 1}. ${step}`));\n  }\n\n  // Alternatives\n  if (opts.alternatives?.length) {\n    parts.push('');\n    parts.push('**Alternatives:**');\n    opts.alternatives.forEach((alt, i) => parts.push(`${i + 1}. ${alt}`));\n  }\n\n  return parts.join('\\n');\n}\n\n// ============================================================================\n// Batch Header Formatter\n// ============================================================================\n\nexport interface BatchHeaderOptions {\n  /** Batch operation title */\n  readonly title: string;\n  /** Total items attempted */\n  readonly totalItems: number;\n  /** Successfully processed count */\n  readonly successful: number;\n  /** Failed count */\n  readonly failed: number;\n  /** Optional tokens per item */\n  readonly tokensPerItem?: number;\n  /** Optional batch count */\n  readonly batches?: number;\n  /** Extra stats to include */\n  readonly extras?: Record<string, string | number>;\n}\n\n/**\n * Format a batch operation header with stats\n */\nexport function formatBatchHeader(opts: BatchHeaderOptions): string {\n  const parts: string[] = [];\n\n  // Title with emoji based on success rate\n  const successRate = opts.totalItems > 0 ? opts.successful / opts.totalItems : 0;\n  const emoji = successRate === 1 ? '\u2713' : successRate >= 0.5 ? '\u26A0\uFE0F' : '\u274C';\n  parts.push(`${emoji} ${opts.title}`);\n  parts.push('');\n\n  // Stats\n  parts.push(`\u2022 Total: ${opts.totalItems}`);\n  parts.push(`\u2022 Successful: ${opts.successful}`);\n  if (opts.failed > 0) {\n    parts.push(`\u2022 Failed: ${opts.failed}`);\n  }\n  if (opts.tokensPerItem) {\n    parts.push(`\u2022 Tokens/item: ~${opts.tokensPerItem.toLocaleString()}`);\n  }\n  if (opts.batches) {\n    parts.push(`\u2022 Batches: ${opts.batches}`);\n  }\n\n  // Extra stats\n  if (opts.extras) {\n    Object.entries(opts.extras).forEach(([key, val]) => {\n      parts.push(`\u2022 ${key}: ${val}`);\n    });\n  }\n\n  return parts.join('\\n');\n}\n\n// ============================================================================\n// Duration Formatter\n// ============================================================================\n\n/**\n * Format duration in human-readable form\n */\nexport function formatDuration(ms: number): string {\n  if (ms < SECONDS_MS) return `${ms}ms`;\n  if (ms < MINUTES_MS) return `${(ms / SECONDS_MS).toFixed(1)}s`;\n  return `${(ms / MINUTES_MS).toFixed(1)}m`;\n}\n\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/src/utils/retry.js

@@ -0,0 +1,13 @@
+const JITTER_FACTOR = 0.3;
+const EXPONENTIAL_BASE = 2;
+const DEFAULT_BASE_DELAY_MS = 1e3;
+const DEFAULT_MAX_DELAY_MS = 3e4;
+function calculateBackoff(attempt, baseDelayMs = DEFAULT_BASE_DELAY_MS, maxDelayMs = DEFAULT_MAX_DELAY_MS) {
+  const exponentialDelay = baseDelayMs * Math.pow(EXPONENTIAL_BASE, attempt);
+  const jitter = JITTER_FACTOR * exponentialDelay * Math.random();
+  return Math.min(exponentialDelay + jitter, maxDelayMs);
+}
+export {
+  calculateBackoff
+};
+//# sourceMappingURL=retry.js.map

package/dist/src/utils/retry.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/retry.ts"],
+  "sourcesContent": ["/**\n * Shared retry and backoff utilities\n */\n\n/** Jitter factor to prevent thundering herd */\nconst JITTER_FACTOR = 0.3 as const;\n\n/** Exponential base for backoff calculation */\nconst EXPONENTIAL_BASE = 2 as const;\n\n/** Default base delay for exponential backoff (ms) */\nconst DEFAULT_BASE_DELAY_MS = 1_000 as const;\n\n/** Default maximum backoff delay cap (ms) */\nconst DEFAULT_MAX_DELAY_MS = 30_000 as const;\n\n/**\n * Calculate exponential backoff delay with jitter.\n * Formula: min(base * 2^attempt + random_jitter, maxDelay)\n *\n * @param attempt - Zero-based retry attempt number\n * @param baseDelayMs - Base delay in milliseconds (default: 1000)\n * @param maxDelayMs - Maximum delay cap in milliseconds (default: 30000)\n * @returns Delay in milliseconds with jitter applied\n */\nexport function calculateBackoff(\n  attempt: number,\n  baseDelayMs: number = DEFAULT_BASE_DELAY_MS,\n  maxDelayMs: number = DEFAULT_MAX_DELAY_MS,\n): number {\n  const exponentialDelay = baseDelayMs * Math.pow(EXPONENTIAL_BASE, attempt);\n  const jitter = JITTER_FACTOR * exponentialDelay * Math.random();\n  return Math.min(exponentialDelay + jitter, maxDelayMs);\n}\n"],
+  "mappings": "AAKA,MAAM,gBAAgB;AAGtB,MAAM,mBAAmB;AAGzB,MAAM,wBAAwB;AAG9B,MAAM,uBAAuB;AAWtB,SAAS,iBACd,SACA,cAAsB,uBACtB,aAAqB,sBACb;AACR,QAAM,mBAAmB,cAAc,KAAK,IAAI,kBAAkB,OAAO;AACzE,QAAM,SAAS,gBAAgB,mBAAmB,KAAK,OAAO;AAC9D,SAAO,KAAK,IAAI,mBAAmB,QAAQ,UAAU;AACvD;",
+  "names": []
+}

package/dist/src/utils/sanitize.js

@@ -0,0 +1,10 @@
+const CONTROL_CHARS = /[\x00-\x1f\x7f]/g;
+const URLS = /https?:\/\/\S+/gi;
+const MARKDOWN_LINKS = /\[([^\]]+)\]\([^)]+\)/g;
+function sanitizeSuggestion(input) {
+  return input.replace(CONTROL_CHARS, " ").replace(MARKDOWN_LINKS, "$1").replace(URLS, "").replace(/\s+/g, " ").trim();
+}
+export {
+  sanitizeSuggestion
+};
+//# sourceMappingURL=sanitize.js.map

package/dist/src/utils/sanitize.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/sanitize.ts"],
+  "sourcesContent": ["const CONTROL_CHARS = /[\\x00-\\x1f\\x7f]/g;\nconst URLS = /https?:\\/\\/\\S+/gi;\nconst MARKDOWN_LINKS = /\\[([^\\]]+)\\]\\([^)]+\\)/g;\n\nexport function sanitizeSuggestion(input: string): string {\n  return input\n    .replace(CONTROL_CHARS, ' ')\n    .replace(MARKDOWN_LINKS, '$1')\n    .replace(URLS, '')\n    .replace(/\\s+/g, ' ')\n    .trim();\n}\n"],
+  "mappings": "AAAA,MAAM,gBAAgB;AACtB,MAAM,OAAO;AACb,MAAM,iBAAiB;AAEhB,SAAS,mBAAmB,OAAuB;AACxD,SAAO,MACJ,QAAQ,eAAe,GAAG,EAC1B,QAAQ,gBAAgB,IAAI,EAC5B,QAAQ,MAAM,EAAE,EAChB,QAAQ,QAAQ,GAAG,EACnB,KAAK;AACV;",
+  "names": []
+}

package/dist/src/utils/source-type.js

@@ -0,0 +1,41 @@
+const RULES = [
+  // Reddit post permalinks (subreddit homepages are filtered out upstream).
+  [/(?:^|\.)reddit\.com\//i, "reddit"],
+  [/(?:^|\.)github\.com\//i, "github"],
+  [/(?:^|\.)gitlab\.com\//i, "github"],
+  // CVE-prefixed paths are unambiguous regardless of host.
+  [/\/CVE-\d{4}-\d+/i, "cve"],
+  [/(?:^|\.)nvd\.nist\.gov\//i, "cve"],
+  [/(?:^|\.)stackoverflow\.com\//i, "qa"],
+  [/(?:^|\.)stackexchange\.com\//i, "qa"],
+  [/(?:^|\.)arxiv\.org\//i, "paper"],
+  [/(?:^|\.)medium\.com\//i, "blog"],
+  [/(?:^|\.)dev\.to\//i, "blog"],
+  [/(?:^|\.)substack\.com\//i, "blog"],
+  // Docs subdomains and /docs/ paths.
+  [/^(?:[a-z0-9-]+\.)*docs\./i, "docs"],
+  [/\/docs\//i, "docs"],
+  [/(?:^|\.)readthedocs\.io\//i, "docs"],
+  // Video.
+  [/(?:^|\.)youtube\.com\/watch/i, "video"],
+  [/(?:^|\.)youtu\.be\//i, "video"],
+  // News / engineering blogs (last so it doesn't capture vendor docs).
+  [/(?:^|\.)(?:news|blog|engineering)\.[a-z0-9-]+\.[a-z]{2,}\//i, "news"]
+];
+function classifySourceByUrl(url) {
+  let candidate;
+  try {
+    const u = new URL(url);
+    candidate = `${u.hostname}${u.pathname}`;
+  } catch {
+    candidate = url;
+  }
+  for (const [re, type] of RULES) {
+    if (re.test(candidate)) return type;
+  }
+  return "web";
+}
+export {
+  classifySourceByUrl
+};
+//# sourceMappingURL=source-type.js.map

package/dist/src/utils/source-type.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/utils/source-type.ts"],
+  "sourcesContent": ["/**\n * Hostname/path-heuristic source-type tagging. Works without the LLM\n * classifier so degraded-mode web-search responses still carry a\n * `source_type` field per result. When the LLM classifier IS available,\n * its tag wins (the classifier sees title + snippet as well, not just URL).\n *\n * See: mcp-revisions/output-shaping/06-source-type-tagging-without-llm.md.\n */\n\nexport type SourceType =\n  | 'reddit'\n  | 'github'\n  | 'docs'\n  | 'blog'\n  | 'paper'\n  | 'qa'\n  | 'cve'\n  | 'news'\n  | 'video'\n  | 'web';\n\nconst RULES: Array<[RegExp, SourceType]> = [\n  // Reddit post permalinks (subreddit homepages are filtered out upstream).\n  [/(?:^|\\.)reddit\\.com\\//i, 'reddit'],\n  [/(?:^|\\.)github\\.com\\//i, 'github'],\n  [/(?:^|\\.)gitlab\\.com\\//i, 'github'],\n  // CVE-prefixed paths are unambiguous regardless of host.\n  [/\\/CVE-\\d{4}-\\d+/i, 'cve'],\n  [/(?:^|\\.)nvd\\.nist\\.gov\\//i, 'cve'],\n  [/(?:^|\\.)stackoverflow\\.com\\//i, 'qa'],\n  [/(?:^|\\.)stackexchange\\.com\\//i, 'qa'],\n  [/(?:^|\\.)arxiv\\.org\\//i, 'paper'],\n  [/(?:^|\\.)medium\\.com\\//i, 'blog'],\n  [/(?:^|\\.)dev\\.to\\//i, 'blog'],\n  [/(?:^|\\.)substack\\.com\\//i, 'blog'],\n  // Docs subdomains and /docs/ paths.\n  [/^(?:[a-z0-9-]+\\.)*docs\\./i, 'docs'],\n  [/\\/docs\\//i, 'docs'],\n  [/(?:^|\\.)readthedocs\\.io\\//i, 'docs'],\n  // Video.\n  [/(?:^|\\.)youtube\\.com\\/watch/i, 'video'],\n  [/(?:^|\\.)youtu\\.be\\//i, 'video'],\n  // News / engineering blogs (last so it doesn't capture vendor docs).\n  [/(?:^|\\.)(?:news|blog|engineering)\\.[a-z0-9-]+\\.[a-z]{2,}\\//i, 'news'],\n];\n\nexport function classifySourceByUrl(url: string): SourceType {\n  let candidate: string;\n  try {\n    const u = new URL(url);\n    // Match against `host + pathname` so rules can use either or both.\n    candidate = `${u.hostname}${u.pathname}`;\n  } catch {\n    candidate = url;\n  }\n  for (const [re, type] of RULES) {\n    if (re.test(candidate)) return type;\n  }\n  return 'web';\n}\n"],
+  "mappings": "AAqBA,MAAM,QAAqC;AAAA;AAAA,EAEzC,CAAC,0BAA0B,QAAQ;AAAA,EACnC,CAAC,0BAA0B,QAAQ;AAAA,EACnC,CAAC,0BAA0B,QAAQ;AAAA;AAAA,EAEnC,CAAC,oBAAoB,KAAK;AAAA,EAC1B,CAAC,6BAA6B,KAAK;AAAA,EACnC,CAAC,iCAAiC,IAAI;AAAA,EACtC,CAAC,iCAAiC,IAAI;AAAA,EACtC,CAAC,yBAAyB,OAAO;AAAA,EACjC,CAAC,0BAA0B,MAAM;AAAA,EACjC,CAAC,sBAAsB,MAAM;AAAA,EAC7B,CAAC,4BAA4B,MAAM;AAAA;AAAA,EAEnC,CAAC,6BAA6B,MAAM;AAAA,EACpC,CAAC,aAAa,MAAM;AAAA,EACpB,CAAC,8BAA8B,MAAM;AAAA;AAAA,EAErC,CAAC,gCAAgC,OAAO;AAAA,EACxC,CAAC,wBAAwB,OAAO;AAAA;AAAA,EAEhC,CAAC,+DAA+D,MAAM;AACxE;AAEO,SAAS,oBAAoB,KAAyB;AAC3D,MAAI;AACJ,MAAI;AACF,UAAM,IAAI,IAAI,IAAI,GAAG;AAErB,gBAAY,GAAG,EAAE,QAAQ,GAAG,EAAE,QAAQ;AAAA,EACxC,QAAQ;AACN,gBAAY;AAAA,EACd;AACA,aAAW,CAAC,IAAI,IAAI,KAAK,OAAO;AAC9B,QAAI,GAAG,KAAK,SAAS,EAAG,QAAO;AAAA,EACjC;AACA,SAAO;AACT;",
+  "names": []
+}