mcp-researchpowerpack 7.0.11 → 7.0.13

package/dist/src/effect/runtime.js

@@ -1,12 +1,1901 @@
-import { Effect, Layer } from "effect";
-import { JinaServiceLive, LlmServiceLive, SearchServiceLive } from "./services.js";
-const BaseExternalLive = Layer.mergeAll(
+// src/effect/runtime.ts
+import { Effect as Effect2, Layer as Layer2 } from "effect";
+
+// src/effect/services.ts
+import { Context, Effect, Layer } from "effect";
+
+// src/config/index.ts
+import { Logger } from "mcp-use";
+
+// src/version.ts
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+var DEFAULT_PACKAGE_INFO = {
+  version: "3.9.5",
+  name: "mcp-researchpowerpack-http",
+  description: "Research Powerpack MCP Server"
+};
+var packageJson = { ...DEFAULT_PACKAGE_INFO };
+try {
+  if (typeof import.meta.url === "string" && import.meta.url.startsWith("file:")) {
+    const _require = createRequire(import.meta.url);
+    const _dirname = dirname(fileURLToPath(import.meta.url));
+    try {
+      packageJson = _require(join(_dirname, "..", "package.json"));
+    } catch {
+      packageJson = _require(join(_dirname, "..", "..", "package.json"));
+    }
+  }
+} catch {
+}
+var VERSION = packageJson.version;
+var PACKAGE_NAME = packageJson.name;
+var PACKAGE_DESCRIPTION = packageJson.description;
+var USER_AGENT_VERSION = `${PACKAGE_NAME}/${VERSION}`;
+
+// src/config/index.ts
+function safeParseInt(value, defaultVal, min, max) {
+  const logger = Logger.get("config");
+  if (!value) {
+    return defaultVal;
+  }
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed)) {
+    logger.warn(`Invalid number "${value}", using default ${defaultVal}`);
+    return defaultVal;
+  }
+  if (parsed < min) {
+    logger.warn(`Value ${parsed} below minimum ${min}, clamping to ${min}`);
+    return min;
+  }
+  if (parsed > max) {
+    logger.warn(`Value ${parsed} above maximum ${max}, clamping to ${max}`);
+    return max;
+  }
+  return parsed;
+}
+var cachedEnv = null;
+function parseEnv() {
+  if (cachedEnv) return cachedEnv;
+  cachedEnv = {
+    SCRAPER_API_KEY: process.env.SCRAPEDO_API_KEY || "",
+    SEARCH_API_KEY: process.env.SERPER_API_KEY || void 0,
+    REDDIT_CLIENT_ID: process.env.REDDIT_CLIENT_ID || void 0,
+    REDDIT_CLIENT_SECRET: process.env.REDDIT_CLIENT_SECRET || void 0,
+    JINA_API_KEY: process.env.JINA_API_KEY || void 0,
+    KERNEL_API_KEY: process.env.KERNEL_API_KEY || void 0,
+    KERNEL_PROJECT: process.env.KERNEL_PROJECT || void 0
+  };
+  return cachedEnv;
+}
+function getCapabilities() {
+  const env = parseEnv();
+  return {
+    reddit: !!(env.REDDIT_CLIENT_ID && env.REDDIT_CLIENT_SECRET),
+    search: !!(env.SEARCH_API_KEY || env.JINA_API_KEY),
+    serperSearch: !!env.SEARCH_API_KEY,
+    jina: !!env.JINA_API_KEY,
+    scraping: !!env.SCRAPER_API_KEY,
+    kernel: !!env.KERNEL_API_KEY,
+    llmExtraction: getLLMConfigStatus().configured
+  };
+}
+var CONCURRENCY = {
+  SEARCH: safeParseInt(process.env.CONCURRENCY_SEARCH, 50, 1, 200),
+  SCRAPER: safeParseInt(process.env.CONCURRENCY_SCRAPER, 50, 1, 200),
+  JINA_READER: safeParseInt(process.env.CONCURRENCY_JINA_READER, 50, 1, 200),
+  REDDIT: safeParseInt(process.env.CONCURRENCY_REDDIT, 50, 1, 200),
+  LLM_EXTRACTION: safeParseInt(process.env.LLM_CONCURRENCY, 50, 1, 200),
+  KERNEL: safeParseInt(process.env.CONCURRENCY_KERNEL, 3, 1, 20)
+};
+var cachedLlmConfigStatus = null;
+function getLLMConfigStatus() {
+  if (cachedLlmConfigStatus) return cachedLlmConfigStatus;
+  const apiKeyPresent = !!process.env.LLM_API_KEY?.trim();
+  const baseUrlPresent = !!process.env.LLM_BASE_URL?.trim();
+  const modelPresent = !!process.env.LLM_MODEL?.trim();
+  const missingVars = [];
+  if (!apiKeyPresent) missingVars.push("LLM_API_KEY");
+  if (!baseUrlPresent) missingVars.push("LLM_BASE_URL");
+  if (!modelPresent) missingVars.push("LLM_MODEL");
+  const configured = missingVars.length === 0;
+  cachedLlmConfigStatus = {
+    configured,
+    apiKeyPresent,
+    baseUrlPresent,
+    modelPresent,
+    missingVars,
+    error: configured ? null : `LLM disabled: missing ${missingVars.join(", ")}`
+  };
+  return cachedLlmConfigStatus;
+}
+var cachedLlmExtraction = null;
+function getLlmExtraction() {
+  if (cachedLlmExtraction) return cachedLlmExtraction;
+  const apiKey = process.env.LLM_API_KEY?.trim() || "";
+  const baseUrl = process.env.LLM_BASE_URL?.trim();
+  const model = process.env.LLM_MODEL?.trim();
+  const fallbackModel = process.env.LLM_FALLBACK_MODEL?.trim() || "";
+  if (apiKey && !baseUrl) {
+    throw new Error(
+      "LLM_BASE_URL is required when LLM_API_KEY is set. Set LLM_BASE_URL to your OpenAI-compatible endpoint."
+    );
+  }
+  if (apiKey && !model) {
+    throw new Error(
+      "LLM_MODEL is required when LLM_API_KEY is set."
+    );
+  }
+  cachedLlmExtraction = {
+    API_KEY: apiKey,
+    BASE_URL: baseUrl || "",
+    MODEL: model || "",
+    FALLBACK_MODEL: fallbackModel
+  };
+  return cachedLlmExtraction;
+}
+var LLM_EXTRACTION = new Proxy({}, {
+  get(_target, prop) {
+    return getLlmExtraction()[prop];
+  }
+});
+
+// src/utils/logger.ts
+import { Logger as Logger2 } from "mcp-use";
+function getLogger(name) {
+  return Logger2.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;
+  }
+}
+
+// src/utils/errors.ts
+var 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",
+  UNSUPPORTED_BINARY_CONTENT: "UNSUPPORTED_BINARY_CONTENT",
+  // Internal errors
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  PARSE_ERROR: "PARSE_ERROR",
+  UNKNOWN_ERROR: "UNKNOWN_ERROR"
+};
+var 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`);
+}
+
+// src/utils/retry.ts
+var JITTER_FACTOR = 0.3;
+var EXPONENTIAL_BASE = 2;
+var DEFAULT_BASE_DELAY_MS = 1e3;
+var DEFAULT_MAX_DELAY_MS = 3e4;
+function calculateBackoff2(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);
+}
+
+// src/utils/concurrency.ts
+import pMapLib from "p-map";
+async function pMap(items, mapper, concurrency = 6, signal) {
+  if (items.length === 0) return [];
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  return pMapLib(items, mapper, { concurrency: limit, signal });
+}
+
+// src/clients/search.ts
+var SERPER_API_URL = "https://google.serper.dev/search";
+var DEFAULT_RESULTS_PER_QUERY = 10;
+var MAX_RETRIES = 3;
+var SEARCH_RETRY_CONFIG = {
+  maxRetries: MAX_RETRIES,
+  baseDelayMs: 1e3,
+  maxDelayMs: 1e4,
+  timeoutMs: 3e4
+};
+var RETRYABLE_SEARCH_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var REDDIT_SITE_REGEX = /site:\s*reddit\.com/i;
+var REDDIT_SUBREDDIT_SUFFIX_REGEX = / : r\/\w+$/;
+var REDDIT_SUFFIX_REGEX = / - Reddit$/;
+function parseSearchResponses(responses, queries) {
+  return responses.map((resp, index) => {
+    try {
+      const organic = resp.organic || [];
+      const results = organic.map((item, idx) => ({
+        title: item.title || "No title",
+        link: item.link || "#",
+        snippet: item.snippet || "",
+        date: item.date,
+        position: item.position || idx + 1
+      }));
+      const searchInfo = resp.searchInformation;
+      const totalResults = searchInfo?.totalResults ? parseInt(String(searchInfo.totalResults).replace(/,/g, ""), 10) : results.length;
+      const relatedSearches = resp.relatedSearches || [];
+      const related = relatedSearches.map((r) => r.query || "");
+      return { query: queries[index] || "", results, totalResults, related };
+    } catch {
+      return { query: queries[index] || "", results: [], totalResults: 0, related: [] };
+    }
+  });
+}
+async function executeSearchWithRetry(apiKey, body, isRetryable) {
+  let lastError;
+  for (let attempt = 0; attempt <= SEARCH_RETRY_CONFIG.maxRetries; attempt++) {
+    try {
+      if (attempt > 0) {
+        mcpLog("warning", `Retry attempt ${attempt}/${SEARCH_RETRY_CONFIG.maxRetries}`, "search");
+      }
+      const response = await fetchWithTimeout(SERPER_API_URL, {
+        method: "POST",
+        headers: {
+          "X-API-KEY": apiKey,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body),
+        timeoutMs: SEARCH_RETRY_CONFIG.timeoutMs
+      });
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        lastError = classifyError({ status: response.status, message: errorText });
+        if (isRetryable(response.status) && attempt < SEARCH_RETRY_CONFIG.maxRetries) {
+          const delayMs = calculateBackoff2(attempt, SEARCH_RETRY_CONFIG.baseDelayMs, SEARCH_RETRY_CONFIG.maxDelayMs);
+          mcpLog("warning", `API returned ${response.status}, retrying in ${delayMs}ms...`, "search");
+          await sleep(delayMs);
+          continue;
+        }
+        return { data: void 0, error: lastError };
+      }
+      try {
+        const data = await response.json();
+        return { data };
+      } catch {
+        return {
+          data: void 0,
+          error: { code: ErrorCode.PARSE_ERROR, message: "Failed to parse search response", retryable: false }
+        };
+      }
+    } catch (error) {
+      lastError = classifyError(error);
+      if (isRetryable(void 0, error) && attempt < SEARCH_RETRY_CONFIG.maxRetries) {
+        const delayMs = calculateBackoff2(attempt, SEARCH_RETRY_CONFIG.baseDelayMs, SEARCH_RETRY_CONFIG.maxDelayMs);
+        mcpLog("warning", `${lastError.code}: ${lastError.message}, retrying in ${delayMs}ms...`, "search");
+        await sleep(delayMs);
+        continue;
+      }
+      return { data: void 0, error: lastError };
+    }
+  }
+  return {
+    data: void 0,
+    error: lastError || { code: ErrorCode.UNKNOWN_ERROR, message: "Search failed", retryable: false }
+  };
+}
+var SearchClient = class {
+  apiKey;
+  constructor(apiKey) {
+    const env = parseEnv();
+    this.apiKey = apiKey || env.SEARCH_API_KEY || "";
+    if (!this.apiKey) {
+      throw new Error("Web search capability is not configured. Please set up the required API credentials.");
+    }
+  }
+  /**
+   * Check if error is retryable
+   */
+  isRetryable(status, error) {
+    if (status && RETRYABLE_SEARCH_CODES.has(status)) return true;
+    if (error == null) return false;
+    const message = typeof error === "object" && "message" in error && typeof error.message === "string" ? error.message.toLowerCase() : "";
+    return message.includes("timeout") || message.includes("rate limit") || message.includes("connection");
+  }
+  /**
+   * Search multiple queries in parallel
+   * NEVER throws - always returns a valid response
+   */
+  async searchMultiple(queries) {
+    const startTime = Date.now();
+    if (queries.length === 0) {
+      return {
+        searches: [],
+        totalQueries: 0,
+        executionTime: 0,
+        error: { code: ErrorCode.INVALID_INPUT, message: "No queries provided", retryable: false }
+      };
+    }
+    const searchQueries = queries.map((query) => ({ q: query }));
+    const { data, error } = await executeSearchWithRetry(
+      this.apiKey,
+      searchQueries,
+      (status, err) => this.isRetryable(status, err)
+    );
+    if (error || data === void 0) {
+      return {
+        searches: [],
+        totalQueries: queries.length,
+        executionTime: Date.now() - startTime,
+        error: error ?? { code: ErrorCode.UNKNOWN_ERROR, message: "Search provider returned no data", retryable: false }
+      };
+    }
+    const responses = Array.isArray(data) ? data : [data];
+    const searches = parseSearchResponses(responses, queries);
+    return { searches, totalQueries: queries.length, executionTime: Date.now() - startTime };
+  }
+  /**
+   * Search Reddit via Google (adds site:reddit.com automatically)
+   * NEVER throws - returns empty array on failure
+   */
+  async searchReddit(query, dateAfter) {
+    if (!query?.trim()) {
+      return [];
+    }
+    let q = query.replace(REDDIT_SITE_REGEX, "").trim() + " site:reddit.com";
+    if (dateAfter) {
+      q += ` after:${dateAfter}`;
+    }
+    for (let attempt = 0; attempt <= SEARCH_RETRY_CONFIG.maxRetries; attempt++) {
+      try {
+        const res = await fetchWithTimeout(SERPER_API_URL, {
+          method: "POST",
+          headers: { "X-API-KEY": this.apiKey, "Content-Type": "application/json" },
+          body: JSON.stringify({ q, num: DEFAULT_RESULTS_PER_QUERY }),
+          timeoutMs: SEARCH_RETRY_CONFIG.timeoutMs
+        });
+        if (!res.ok) {
+          if (this.isRetryable(res.status) && attempt < SEARCH_RETRY_CONFIG.maxRetries) {
+            const delayMs = calculateBackoff2(attempt, SEARCH_RETRY_CONFIG.baseDelayMs, SEARCH_RETRY_CONFIG.maxDelayMs);
+            mcpLog("warning", `Reddit search ${res.status}, retrying in ${delayMs}ms...`, "search");
+            await sleep(delayMs);
+            continue;
+          }
+          mcpLog("error", `Reddit search failed with status ${res.status}`, "search");
+          return [];
+        }
+        const data = await res.json();
+        return (data.organic || []).map((r) => ({
+          title: (r.title || "").replace(REDDIT_SUBREDDIT_SUFFIX_REGEX, "").replace(REDDIT_SUFFIX_REGEX, ""),
+          url: r.link || "",
+          snippet: r.snippet || "",
+          date: r.date
+        }));
+      } catch (error) {
+        const err = classifyError(error);
+        if (this.isRetryable(void 0, error) && attempt < SEARCH_RETRY_CONFIG.maxRetries) {
+          const delayMs = calculateBackoff2(attempt, SEARCH_RETRY_CONFIG.baseDelayMs, SEARCH_RETRY_CONFIG.maxDelayMs);
+          mcpLog("warning", `Reddit search ${err.code}, retrying in ${delayMs}ms...`, "search");
+          await sleep(delayMs);
+          continue;
+        }
+        mcpLog("error", `Reddit search failed: ${err.message}`, "search");
+        return [];
+      }
+    }
+    return [];
+  }
+  /**
+   * Search Reddit with multiple queries (bounded concurrency)
+   * NEVER throws - searchReddit never throws, pMap preserves order
+   */
+  async searchRedditMultiple(queries, dateAfter) {
+    if (queries.length === 0) {
+      return /* @__PURE__ */ new Map();
+    }
+    const results = await pMap(
+      queries,
+      (q) => this.searchReddit(q, dateAfter),
+      CONCURRENCY.SEARCH
+    );
+    return new Map(queries.map((q, i) => [q, results[i] || []]));
+  }
+};
+
+// src/clients/jina.ts
+var JINA_READER_BASE = "https://r.jina.ai/";
+var JINA_SEARCH_BASE = "https://s.jina.ai/";
+var DEFAULT_TIMEOUT_SECONDS = 15;
+var DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_SECONDS * 1e3;
+var MAX_RETRIES2 = 2;
+var SEARCH_RESULTS_PER_QUERY = 10;
+function buildJinaSearchUrl(query) {
+  const params = new URLSearchParams({ q: query });
+  return `${JINA_SEARCH_BASE}?${params.toString()}`;
+}
+var JinaClient = class {
+  apiKey;
+  constructor(apiKey) {
+    const fromEnv = process.env.JINA_API_KEY?.trim();
+    this.apiKey = apiKey?.trim() || fromEnv || void 0;
+  }
+  /**
+   * Convert a URL to markdown via Jina Reader.
+   * NEVER throws — always returns a JinaConvertResponse (possibly with error).
+   */
+  async convert(request) {
+    const {
+      url,
+      timeoutSeconds = DEFAULT_TIMEOUT_SECONDS,
+      proxyUrl,
+      noCache = false,
+      allowProxyRetry = false
+    } = request;
+    try {
+      new URL(url);
+    } catch {
+      return {
+        content: `Invalid URL: ${url}`,
+        statusCode: 400,
+        credits: 0,
+        error: { code: ErrorCode.INVALID_INPUT, message: `Invalid URL: ${url}`, retryable: false }
+      };
+    }
+    const first = await this.convertOnce({
+      url,
+      timeoutSeconds,
+      proxyUrl,
+      noCache
+    });
+    if (!first.error || !allowProxyRetry || proxyUrl || isTerminalReaderError(first.error)) {
+      return first;
+    }
+    mcpLog("warning", `Jina Reader failed for ${url}; retrying with Jina proxy`, "jina");
+    return this.convertOnce({
+      url,
+      timeoutSeconds,
+      proxyUrl: "auto",
+      noCache: true
+    });
+  }
+  async searchMultiple(queries) {
+    const startTime = Date.now();
+    if (queries.length === 0) {
+      return {
+        searches: [],
+        totalQueries: 0,
+        executionTime: 0,
+        error: { code: ErrorCode.INVALID_INPUT, message: "No queries provided", retryable: false }
+      };
+    }
+    if (!this.apiKey) {
+      return {
+        searches: [],
+        totalQueries: queries.length,
+        executionTime: Date.now() - startTime,
+        error: { code: ErrorCode.AUTH_ERROR, message: "Jina Search requires JINA_API_KEY", retryable: false }
+      };
+    }
+    const searches = await Promise.all(queries.map((query) => this.searchOne(query)));
+    const firstError = searches.find((search) => search.error)?.error;
+    const allFailed = searches.every((search) => search.error);
+    return {
+      searches,
+      totalQueries: queries.length,
+      executionTime: Date.now() - startTime,
+      ...allFailed && firstError ? { error: firstError } : {}
+    };
+  }
+  async convertOnce(request) {
+    const headers = {
+      Accept: "application/json",
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    if (request.proxyUrl && request.proxyUrl !== "auto") {
+      headers["X-Proxy-Url"] = request.proxyUrl;
+    }
+    const body = {
+      url: request.url,
+      respondWith: "markdown",
+      timeout: request.timeoutSeconds,
+      base: "final",
+      removeOverlay: true
+    };
+    if (request.proxyUrl === "auto") body["proxy"] = "auto";
+    if (request.noCache) body["noCache"] = true;
+    return this.fetchReader(body, headers, request.timeoutSeconds);
+  }
+  async fetchReader(body, headers, timeoutSeconds) {
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES2; attempt++) {
+      try {
+        const response = await fetchWithTimeout(JINA_READER_BASE, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          timeoutMs: (timeoutSeconds + 5) * 1e3
+        });
+        const raw = await response.text().catch(
+          (readError) => `Failed to read Jina response: ${readError instanceof Error ? readError.message : String(readError)}`
+        );
+        const usageHeader = response.headers.get("x-usage-tokens");
+        const usageTokens = usageHeader ? Number(usageHeader) : void 0;
+        const parsed = parseReaderContent(raw);
+        if (response.ok) {
+          if (!parsed.content.trim()) {
+            return emptyReaderResponse(response.status, usageTokens);
+          }
+          return {
+            content: parsed.content,
+            statusCode: response.status,
+            credits: 0,
+            usageTokens: Number.isFinite(usageTokens) ? usageTokens : void 0
+          };
+        }
+        const terminal = terminalReaderResponse(response.status, parsed.content || raw);
+        if (terminal) return terminal;
+        lastError = classifyError({ status: response.status, message: raw.slice(0, 200) });
+        if (lastError.retryable && attempt < MAX_RETRIES2) {
+          const delayMs = calculateBackoff2(attempt);
+          mcpLog(
+            "warning",
+            `Jina ${response.status} on attempt ${attempt + 1}/${MAX_RETRIES2 + 1}. Retrying in ${delayMs}ms`,
+            "jina"
+          );
+          await sleep(delayMs);
+          continue;
+        }
+        return {
+          content: `Jina Reader error (${response.status}): ${raw.slice(0, 200)}`,
+          statusCode: response.status,
+          credits: 0,
+          error: lastError
+        };
+      } catch (error) {
+        lastError = classifyError(error);
+        if (lastError.retryable && attempt < MAX_RETRIES2) {
+          const delayMs = calculateBackoff2(attempt);
+          mcpLog(
+            "warning",
+            `Jina ${lastError.code}: ${lastError.message}. Retry ${attempt + 1}/${MAX_RETRIES2 + 1} in ${delayMs}ms`,
+            "jina"
+          );
+          await sleep(delayMs);
+          continue;
+        }
+        return {
+          content: `Jina Reader failed: ${lastError.message}`,
+          statusCode: lastError.statusCode ?? 500,
+          credits: 0,
+          error: lastError
+        };
+      }
+    }
+    return {
+      content: `Jina Reader failed after ${MAX_RETRIES2 + 1} attempts: ${lastError?.message ?? "Unknown error"}`,
+      statusCode: lastError?.statusCode ?? 500,
+      credits: 0,
+      error: lastError ?? { code: ErrorCode.UNKNOWN_ERROR, message: "All retries exhausted", retryable: false }
+    };
+  }
+  async searchOne(query) {
+    const headers = {
+      Accept: "application/json",
+      Authorization: `Bearer ${this.apiKey ?? ""}`
+    };
+    try {
+      const response = await fetchWithTimeout(buildJinaSearchUrl(query), {
+        method: "GET",
+        headers,
+        timeoutMs: DEFAULT_TIMEOUT_MS
+      });
+      const raw = await response.text().catch(
+        (readError) => `Failed to read Jina Search response: ${readError instanceof Error ? readError.message : String(readError)}`
+      );
+      if (!response.ok) {
+        return {
+          query,
+          results: [],
+          totalResults: 0,
+          related: [],
+          error: classifyError({ status: response.status, message: raw.slice(0, 200) })
+        };
+      }
+      const results = parseSearchResults(raw);
+      return { query, results, totalResults: results.length, related: [] };
+    } catch (error) {
+      return {
+        query,
+        results: [],
+        totalResults: 0,
+        related: [],
+        error: classifyError(error)
+      };
+    }
+  }
+};
+function parseReaderContent(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    const data = readRecord(parsed, "data");
+    const content = readString(data, "content");
+    if (content) return { content };
+  } catch {
+  }
+  return { content: raw };
+}
+function emptyReaderResponse(statusCode, usageTokens) {
+  return {
+    content: "Jina returned an empty body",
+    statusCode,
+    credits: 0,
+    usageTokens: Number.isFinite(usageTokens) ? usageTokens : void 0,
+    error: {
+      code: ErrorCode.UNSUPPORTED_BINARY_CONTENT,
+      message: "Jina Reader returned empty content for this URL",
+      retryable: false
+    }
+  };
+}
+function terminalReaderResponse(statusCode, content) {
+  if (statusCode === 401 || statusCode === 403) {
+    return {
+      content: `Jina auth/quota error (${statusCode}): ${content.slice(0, 200)}`,
+      statusCode,
+      credits: 0,
+      error: {
+        code: statusCode === 401 ? ErrorCode.AUTH_ERROR : ErrorCode.QUOTA_EXCEEDED,
+        message: statusCode === 401 ? "Jina Reader auth failed \u2014 check JINA_API_KEY" : "Jina Reader quota exceeded",
+        retryable: false,
+        statusCode
+      }
+    };
+  }
+  if (statusCode === 404) {
+    return {
+      content: "Jina could not fetch the target URL (404)",
+      statusCode: 404,
+      credits: 0,
+      error: {
+        code: ErrorCode.NOT_FOUND,
+        message: "Target URL not reachable by Jina Reader",
+        retryable: false,
+        statusCode: 404
+      }
+    };
+  }
+  if (statusCode >= 400 && statusCode < 500 && statusCode !== 429) {
+    return {
+      content: `Jina Reader error (${statusCode}): ${content.slice(0, 200)}`,
+      statusCode,
+      credits: 0,
+      error: {
+        code: ErrorCode.INVALID_INPUT,
+        message: `Jina Reader returned ${statusCode}`,
+        retryable: false,
+        statusCode
+      }
+    };
+  }
+  return null;
+}
+function isTerminalReaderError(error) {
+  return !error.retryable && (error.code === ErrorCode.AUTH_ERROR || error.code === ErrorCode.QUOTA_EXCEEDED || error.code === ErrorCode.NOT_FOUND || error.code === ErrorCode.INVALID_INPUT);
+}
+function parseSearchResults(raw) {
+  let data;
+  try {
+    const parsed = JSON.parse(raw);
+    data = readUnknown(parsed, "data");
+  } catch {
+    data = parseMarkdownSearchResults(raw);
+  }
+  const items = Array.isArray(data) ? data : [];
+  return items.map((item, index) => normalizeSearchItem(item, index)).filter((item) => item !== null).slice(0, SEARCH_RESULTS_PER_QUERY);
+}
+function normalizeSearchItem(item, index) {
+  const link = readString(item, "url") ?? readString(item, "link");
+  if (!link) return null;
+  return {
+    title: readString(item, "title") || link,
+    link,
+    snippet: (readString(item, "snippet") || readString(item, "description") || readString(item, "content") || "").slice(0, 500),
+    date: readString(item, "date") ?? readString(item, "publishedTime"),
+    position: index + 1
+  };
+}
+function parseMarkdownSearchResults(raw) {
+  const items = [];
+  const markdownLink = /\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g;
+  let match;
+  while ((match = markdownLink.exec(raw)) !== null && items.length < SEARCH_RESULTS_PER_QUERY) {
+    const title = match[1];
+    const url = match[2];
+    if (title && url) items.push({ title, url });
+  }
+  return items;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function readUnknown(value, key) {
+  return isRecord(value) ? value[key] : void 0;
+}
+function readRecord(value, key) {
+  const child = readUnknown(value, key);
+  return isRecord(child) ? child : void 0;
+}
+function readString(value, key) {
+  const child = readUnknown(value, key);
+  return typeof child === "string" ? child : void 0;
+}
+
+// src/clients/kernel.ts
+import Kernel from "@onkernel/sdk";
+var DEFAULT_RENDER_TIMEOUT_SECONDS = 15;
+var BROWSER_IDLE_TIMEOUT_SECONDS = 300;
+var KernelClient = class {
+  kernel;
+  constructor(apiKey) {
+    const env = parseEnv();
+    const resolvedKey = apiKey?.trim() || env.KERNEL_API_KEY;
+    if (!resolvedKey) {
+      throw new Error("Kernel browser rendering is not configured. Set KERNEL_API_KEY.");
+    }
+    this.kernel = new Kernel({
+      apiKey: resolvedKey,
+      timeout: 3e4,
+      maxRetries: 1,
+      ...env.KERNEL_PROJECT ? { defaultHeaders: { "X-Kernel-Project-Id": env.KERNEL_PROJECT } } : {}
+    });
+  }
+  async render(request) {
+    const { url, timeoutSeconds = DEFAULT_RENDER_TIMEOUT_SECONDS } = request;
+    try {
+      new URL(url);
+    } catch {
+      return {
+        content: `Invalid URL: ${url}`,
+        statusCode: 400,
+        credits: 0,
+        error: { code: ErrorCode.INVALID_INPUT, message: `Invalid URL: ${url}`, retryable: false }
+      };
+    }
+    let sessionId;
+    try {
+      const session = await this.kernel.browsers.create({
+        headless: true,
+        stealth: true,
+        timeout_seconds: BROWSER_IDLE_TIMEOUT_SECONDS,
+        viewport: { width: 1280, height: 800 }
+      });
+      sessionId = session.session_id;
+      const response = await this.kernel.browsers.playwright.execute(session.session_id, {
+        code: buildRenderScript(url, timeoutSeconds),
+        timeout_sec: Math.min(timeoutSeconds + 5, 300)
+      });
+      if (!response.success) {
+        const message = response.error || response.stderr || "Kernel Playwright execution failed";
+        return {
+          content: `Kernel render failed: ${message}`,
+          statusCode: 500,
+          credits: 0,
+          error: { code: ErrorCode.SERVICE_UNAVAILABLE, message, retryable: true }
+        };
+      }
+      const rendered = parseRenderedPage(response.result);
+      if (!rendered) {
+        return {
+          content: "Kernel render returned an invalid payload",
+          statusCode: 500,
+          credits: 0,
+          error: {
+            code: ErrorCode.PARSE_ERROR,
+            message: "Kernel render returned an invalid payload",
+            retryable: false
+          }
+        };
+      }
+      return {
+        content: rendered.html,
+        statusCode: 200,
+        credits: 0,
+        finalUrl: rendered.finalUrl,
+        title: rendered.title,
+        text: rendered.text
+      };
+    } catch (error) {
+      const err = formatKernelError(error);
+      return {
+        content: `Kernel render failed: ${err.message}`,
+        statusCode: err.statusCode ?? 500,
+        credits: 0,
+        error: err
+      };
+    } finally {
+      if (sessionId) {
+        try {
+          await this.kernel.browsers.deleteByID(sessionId);
+        } catch (deleteError) {
+          const err = formatKernelError(deleteError);
+          mcpLog("warning", `Kernel browser cleanup failed for ${sessionId}: ${err.message}`, "kernel");
+        }
+      }
+    }
+  }
+};
+function buildRenderScript(url, timeoutSeconds) {
+  const timeoutMs = timeoutSeconds * 1e3;
+  return `
+const targetUrl = ${JSON.stringify(url)};
+const timeoutMs = ${timeoutMs};
+await page.goto(targetUrl, { waitUntil: 'domcontentloaded', timeout: timeoutMs });
+await page.waitForLoadState('networkidle', { timeout: Math.min(5000, timeoutMs) }).catch(() => {});
+const html = await page.content();
+const text = await page.locator('body').innerText({ timeout: 2000 }).catch(() => '');
+return {
+  html,
+  text,
+  title: await page.title(),
+  finalUrl: page.url(),
+};
+`;
+}
+function parseRenderedPage(value) {
+  if (!isRecord2(value)) return null;
+  const html = readString2(value, "html");
+  const finalUrl = readString2(value, "finalUrl");
+  const title = readString2(value, "title");
+  const text = readString2(value, "text");
+  if (!html || !finalUrl || title === void 0 || text === void 0) return null;
+  return { html, finalUrl, title, text };
+}
+function formatKernelError(error) {
+  if (error instanceof Kernel.APIError) {
+    return {
+      ...classifyError({ status: error.status, message: error.message }),
+      cause: error.message
+    };
+  }
+  return classifyError(error);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function readString2(value, key) {
+  const child = value[key];
+  return typeof child === "string" ? child : void 0;
+}
+
+// src/clients/reddit.ts
+import { Logger as Logger3 } from "mcp-use";
+var DEBUG_TOKEN_CACHE = process.env.DEBUG_REDDIT === "true";
+var clientLogger = Logger3.get("reddit-client");
+
+// src/services/llm-processor.ts
+import OpenAI from "openai";
+
+// src/schemas/web-search.ts
+import { z } from "zod";
+var QUERY_REWRITE_PAIR_EXAMPLES = [
+  'Bad: `<feature> support` \u2192 Better: `site:<official-docs-domain> "<feature>" "<platform-or-version>"`',
+  'Bad: `<product> pricing` \u2192 Better: `site:<vendor-domain> "<product>" pricing "enterprise" OR "free tier"`',
+  'Bad: `<library> bug fix` \u2192 Better: `"<exact error text>" "<library-or-package>" "<version>" site:github.com`',
+  'Bad: `<tool> reviews` \u2192 Better: `site:reddit.com/r/<community>/comments "<tool>" "migration" OR "regression"`'
+];
+var QUERY_REWRITE_PAIR_GUIDANCE = [
+  "Write Google retrieval probes, not topic labels.",
+  "For each broad idea, rewrite it into a query that names the evidence source class, discriminating anchor terms, and one useful operator when possible.",
+  "Use rewrite-pair thinking before searching:",
+  ...QUERY_REWRITE_PAIR_EXAMPLES,
+  "Do not repeat the same noun phrase with adjectives changed; fan out by source type and evidence need."
+];
+var QUERY_REWRITE_PAIR_GUIDANCE_TEXT = QUERY_REWRITE_PAIR_GUIDANCE.join(" ");
+var keywordSchema = z.string().min(1, { message: "search: Keyword cannot be empty" }).describe(
+  `A single search keyword/query. Each item runs as a separate parallel search. ${QUERY_REWRITE_PAIR_GUIDANCE_TEXT}`
+);
+var keywordsSchema = z.array(keywordSchema).min(1, { message: "search: At least 1 keyword required" }).max(50, { message: "search: At most 50 keywords allowed per call" }).describe(
+  `Search keywords to run in parallel. Serper is primary when configured; Jina Search is fallback when Serper is missing, fails, or yields empty query results. ${QUERY_REWRITE_PAIR_GUIDANCE_TEXT} Think of keywords as retrieval probes, not topic labels. Pack distinct facets in one call: official docs, implementation, failures, comparisons, sentiment, changelog, CVE, pricing, or other source classes.`
+);
+var rawWebSearchParamsSchema = z.object({
+  keywords: keywordsSchema,
+  extract: z.never().optional(),
+  scope: z.never().optional(),
+  verbose: z.never().optional()
+}).strict();
+var smartWebSearchParamsSchema = z.object({
+  keywords: keywordsSchema,
+  extract: z.string().min(1, { message: "smart-web-search: extract cannot be empty" }).describe(
+    'Semantic instruction for the relevance classifier \u2014 what "relevant" means for THIS goal. This is the post-sort target, so name the evidence you need and the source-of-truth expectation: e.g. official docs/release notes for specs, issue/PR/error text for bugs, Reddit/HN/blogs for lived experience, vendor pricing pages for pricing, CVE databases for security. Drives tiering (HIGHLY_RELEVANT / MAYBE_RELEVANT / OTHER), synthesis, gap analysis, and refine-query suggestions. Be specific: "OAuth 2.1 support in TypeScript MCP frameworks \u2014 runnable code, not marketing", not "MCP OAuth".'
+  ),
+  scope: z.enum(["web", "reddit", "both"]).default("web").describe(
+    'Search scope. "web" (default) = open web, no augmentation. "reddit" = server appends `site:reddit.com` to every keyword and filters results to post permalinks (`/r/.+/comments/[a-z0-9]+/`); subreddit homepages are dropped. "both" = runs every keyword twice (open web + reddit-scoped), merges the result set, and tags each row with its source. Use "reddit" for sentiment/migration/lived-experience research; use "both" when opinion-heavy AND official sources also matter.'
+  ),
+  verbose: z.boolean().default(false).describe(
+    "Include per-row scoring/coverage metadata, the trailing Signals block, and CONSENSUS labels even when they carry little signal. Default false."
+  )
+}).strict();
+
+// src/services/llm-processor.ts
+var MAX_LLM_INPUT_CHARS = 5e5;
+var MAX_PRIMARY_MODEL_INPUT_CHARS = 1e5;
+var LLM_CLIENT_TIMEOUT_MS = 6e5;
+var BACKOFF_JITTER_FACTOR = 0.3;
+var LLM_STALL_TIMEOUT_MS = 75e3;
+var LLM_REQUEST_DEADLINE_MS = 15e4;
+var llmHealth = {
+  lastPlannerOk: false,
+  lastExtractorOk: false,
+  lastPlannerCheckedAt: null,
+  lastExtractorCheckedAt: null,
+  lastPlannerError: null,
+  lastExtractorError: null,
+  consecutivePlannerFailures: 0,
+  consecutiveExtractorFailures: 0
+};
+function markLLMSuccess(kind) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString();
+  if (kind === "planner") {
+    llmHealth.lastPlannerOk = true;
+    llmHealth.lastPlannerCheckedAt = ts;
+    llmHealth.lastPlannerError = null;
+    llmHealth.consecutivePlannerFailures = 0;
+  } else {
+    llmHealth.lastExtractorOk = true;
+    llmHealth.lastExtractorCheckedAt = ts;
+    llmHealth.lastExtractorError = null;
+    llmHealth.consecutiveExtractorFailures = 0;
+  }
+}
+function markLLMFailure(kind, err) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString();
+  const message = err instanceof Error ? err.message : String(err ?? "unknown error");
+  if (kind === "planner") {
+    llmHealth.lastPlannerOk = false;
+    llmHealth.lastPlannerCheckedAt = ts;
+    llmHealth.lastPlannerError = message;
+    llmHealth.consecutivePlannerFailures += 1;
+  } else {
+    llmHealth.lastExtractorOk = false;
+    llmHealth.lastExtractorCheckedAt = ts;
+    llmHealth.lastExtractorError = message;
+    llmHealth.consecutiveExtractorFailures += 1;
+  }
+}
+var LLM_RETRY_CONFIG = {
+  maxRetries: 2,
+  baseDelayMs: 1e3,
+  maxDelayMs: 5e3
+};
+var FALLBACK_RETRY_COUNT = 3;
+var RETRYABLE_LLM_ERROR_CODES = /* @__PURE__ */ new Set([
+  "rate_limit_exceeded",
+  "server_error",
+  "timeout",
+  "service_unavailable"
+]);
+function hasStatus(error) {
+  return typeof error === "object" && error !== null && "status" in error && typeof error.status === "number";
+}
+var llmClient = null;
+function createLLMProcessor() {
+  if (!getCapabilities().llmExtraction) return null;
+  if (!llmClient) {
+    llmClient = new OpenAI({
+      baseURL: LLM_EXTRACTION.BASE_URL,
+      apiKey: LLM_EXTRACTION.API_KEY,
+      timeout: LLM_CLIENT_TIMEOUT_MS,
+      maxRetries: 0,
+      defaultHeaders: { "X-Title": "mcp-research-powerpack" }
+    });
+    mcpLog("info", `LLM extraction configured (model: ${LLM_EXTRACTION.MODEL}, baseURL: ${LLM_EXTRACTION.BASE_URL})`, "llm");
+  }
+  return llmClient;
+}
+function buildChatRequestBody(model, prompt) {
+  return {
+    model,
+    messages: [{ role: "user", content: prompt }],
+    reasoning_effort: "low"
+  };
+}
+function normalizeProviderError(err, message) {
+  if (typeof err === "object" && err !== null) return err;
+  return new Error(message);
+}
+function getProviderFailure(response) {
+  if (response.content !== null || response.failureKind !== "provider") return null;
+  return response.errorCause;
+}
+function emptyLLMExtractionResult(content) {
+  return {
+    content,
+    processed: false,
+    error: "LLM returned empty response",
+    errorDetails: {
+      code: ErrorCode.INTERNAL_ERROR,
+      message: "LLM returned empty response",
+      retryable: false
+    }
+  };
+}
+async function requestText(processor, prompt, operationLabel, signal, modelOverride) {
+  const model = modelOverride || LLM_EXTRACTION.MODEL;
+  try {
+    const response = await withStallProtection(
+      (stallSignal) => processor.chat.completions.create(
+        buildChatRequestBody(model, prompt),
+        {
+          signal: signal ? AbortSignal.any([stallSignal, signal]) : stallSignal,
+          timeout: LLM_REQUEST_DEADLINE_MS
+        }
+      ),
+      LLM_STALL_TIMEOUT_MS,
+      3,
+      `${operationLabel} (${model})`
+    );
+    const content = response.choices?.[0]?.message?.content?.trim();
+    if (content) {
+      return { content, model };
+    }
+    const err = `Empty response from model ${model}`;
+    mcpLog("warning", `${operationLabel} returned empty content for model ${model}`, "llm");
+    return { content: null, model, error: err, failureKind: "empty" };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    mcpLog("warning", `${operationLabel} failed for model ${model}: ${message}`, "llm");
+    return {
+      content: null,
+      model,
+      error: message,
+      failureKind: "provider",
+      errorCause: normalizeProviderError(err, message)
+    };
+  }
+}
+async function requestTextWithFallback(processor, prompt, operationLabel, signal) {
+  const primary = await requestText(processor, prompt, operationLabel, signal);
+  if (primary.content !== null) return primary;
+  const fallbackModel = LLM_EXTRACTION.FALLBACK_MODEL;
+  if (!fallbackModel) return primary;
+  mcpLog("warning", `Primary model failed, switching to fallback ${fallbackModel}`, "llm");
+  let lastFailure = primary;
+  for (let attempt = 0; attempt < FALLBACK_RETRY_COUNT; attempt++) {
+    if (attempt > 0) {
+      const delayMs = calculateLLMBackoff(attempt - 1);
+      mcpLog("warning", `Fallback retry ${attempt}/${FALLBACK_RETRY_COUNT - 1} in ${delayMs}ms`, "llm");
+      try {
+        await sleep(delayMs, signal);
+      } catch {
+        break;
+      }
+    }
+    const result = await requestText(processor, prompt, `${operationLabel} [fallback]`, signal, fallbackModel);
+    if (result.content !== null) return result;
+    lastFailure = result;
+  }
+  return lastFailure;
+}
+function isRetryableLLMError(error) {
+  if (!error || typeof error !== "object") return false;
+  const stallCode = error?.code;
+  if (stallCode === "ESTALLED" || stallCode === "ETIMEDOUT") {
+    return true;
+  }
+  if (hasStatus(error)) {
+    if (error.status === 429 || error.status === 500 || error.status === 502 || error.status === 503 || error.status === 504) {
+      return true;
+    }
+  }
+  const record = error;
+  const code = typeof record.code === "string" ? record.code : void 0;
+  const nested = typeof record.error === "object" && record.error !== null ? record.error : null;
+  const errorCode = code ?? (nested && typeof nested.code === "string" ? nested.code : void 0) ?? (nested && typeof nested.type === "string" ? nested.type : void 0);
+  if (errorCode && RETRYABLE_LLM_ERROR_CODES.has(errorCode)) {
+    return true;
+  }
+  const message = typeof record.message === "string" ? record.message.toLowerCase() : "";
+  if (message.includes("rate limit") || message.includes("timeout") || message.includes("timed out") || message.includes("service unavailable") || message.includes("server error") || message.includes("connection") || message.includes("econnreset")) {
+    return true;
+  }
+  return false;
+}
+function isContextWindowError(error) {
+  if (!error || typeof error !== "object") return false;
+  const record = error;
+  const nested = typeof record.error === "object" && record.error !== null ? record.error : null;
+  const code = typeof record.code === "string" ? record.code : void 0;
+  const nestedCode = nested && typeof nested.code === "string" ? nested.code : void 0;
+  if (code === "context_length_exceeded" || nestedCode === "context_length_exceeded") {
+    return true;
+  }
+  const messages = [];
+  if (typeof record.message === "string") messages.push(record.message);
+  if (nested && typeof nested.message === "string") messages.push(nested.message);
+  const combined = messages.join(" ").toLowerCase();
+  return combined.includes("context length") || combined.includes("context window") || combined.includes("maximum context") || combined.includes("maximum tokens") || combined.includes("token limit") || combined.includes("too many tokens") || combined.includes("prompt is too long") || combined.includes("reduce the length");
+}
+function calculateLLMBackoff(attempt) {
+  const exponentialDelay = LLM_RETRY_CONFIG.baseDelayMs * Math.pow(2, attempt);
+  const jitter = Math.random() * BACKOFF_JITTER_FACTOR * exponentialDelay;
+  return Math.min(exponentialDelay + jitter, LLM_RETRY_CONFIG.maxDelayMs);
+}
+async function processContentWithLLM(content, config, processor, signal) {
+  if (!config.enabled) {
+    return { content, processed: false };
+  }
+  if (!processor) {
+    return {
+      content,
+      processed: false,
+      error: "LLM processor not available (LLM_API_KEY, LLM_BASE_URL, and LLM_MODEL must all be set)",
+      errorDetails: {
+        code: ErrorCode.AUTH_ERROR,
+        message: "LLM processor not available",
+        retryable: false
+      }
+    };
+  }
+  if (!content?.trim()) {
+    return { content: content || "", processed: false, error: "Empty content provided" };
+  }
+  const truncatedContent = content.length > MAX_LLM_INPUT_CHARS ? content.substring(0, MAX_LLM_INPUT_CHARS) + "\n\n[Content truncated due to length]" : content;
+  const skipPrimaryForSize = truncatedContent.length > MAX_PRIMARY_MODEL_INPUT_CHARS && !!LLM_EXTRACTION.FALLBACK_MODEL;
+  const safeUrl = (() => {
+    if (!config.url) return void 0;
+    try {
+      const u = new URL(config.url);
+      return `${u.origin}${u.pathname}`;
+    } catch {
+      return void 0;
+    }
+  })();
+  const urlLine = safeUrl ? `PAGE URL: ${safeUrl}
+
+` : "";
+  const prompt = config.extract ? `You are a factual extractor for a research agent. Extract ONLY the information that matches the instruction below. Do not summarize, interpret, or editorialize.
+
+${urlLine}EXTRACTION INSTRUCTION: ${config.extract}
+
+STEP 1 \u2014 Classify this page. Look at the URL if present, plus structural cues (code blocks, table patterns, comment threads, marketing copy). Pick ONE:
+\`docs | changelog | github-readme | github-thread | reddit | hackernews | forum | blog | marketing | announcement | qa | cve | paper | release-notes | other\`
+
+STEP 2 \u2014 Adjust emphasis by page type:
+- docs / changelog / github-readme / release-notes \u2192 API signatures, version numbers, flags, exact config keys, code blocks. Copy verbatim. Preserve tables as tables.
+- github-thread \u2192 weight MAINTAINER comments (label "[maintainer]") over drive-by commenters. Preserve stacktraces verbatim. Capture chronological resolution \u2014 what was decided and when. Link the accepted-fix commit/PR if referenced.
+- reddit / hackernews / forum \u2192 lived experience. Quote verbatim with attribution ("u/foo wrote: \u2026" or "user <name>"). Prioritize replies with stack details, specific failure stories, or replies that contradict the OP. Record overall sentiment distribution as one bullet if clear skew ("~70% agree / ~20% dissent / rest off-topic"). Drop context-free opinions ("this sucks") from Matches.
+- blog \u2192 prioritize concrete reproductions, code, measurements. If the author makes a claim without evidence, mark "[unsourced claim]".
+- marketing / announcement \u2192 pricing tiers, feature matrices verbatim, free-tier quotas, enterprise contact. Preserve tables as tables. Treat roadmap/future-tense claims skeptically \u2014 note them as "[announced, not shipped]" when framing is future-tense.
+- qa (stackoverflow) \u2192 accepted answer's code + high-voted disagreements. Always note the answer date \u2014 SO rots.
+- cve \u2192 CVSS vector verbatim, CWE, CPE ranges, affected versions, fix version, references. Each with its label.
+- paper \u2192 claim, method, dataset, benchmark numbers, comparison baseline. Preserve numeric deltas verbatim.
+
+STEP 3 \u2014 Emit markdown with these sections, in order:
+
+## Source
+- URL: <verbatim if visible, else "unknown">
+- Page type: <the type you picked>
+- Page date: <verbatim if visible, else "not visible">
+- Author / maintainer (if identifiable): <verbatim>
+
+## Matches
+One bullet per distinct piece of matching info:
+- **<short label>** \u2014 the information. Quote VERBATIM for: numbers, versions, dates, API names, prices, error messages, stacktraces, CVSS vectors, benchmark scores, command flags, proper nouns, and people's words. Backticks for code/identifiers. Preserve tables.
+
+## Not found
+Every part of the extraction instruction this page did NOT answer. Be explicit. Example: "Enterprise pricing contact \u2014 not present on this page."
+
+## Follow-up signals
+Short bullets \u2014 NEW angles this page surfaced that the agent should investigate. Include: new terms, unexpected vendor names, contradicting claims, referenced-but-unscraped URLs. Copy URLs VERBATIM from the source; if only anchor text is visible, write "anchor: <text> (URL not in scraped content)". Skip this section if nothing new surfaced. Do NOT invent.
+
+## Contradictions
+(Include this section only if the page contains internally contradictory claims.) Bullet each contradiction with both sides quoted verbatim.
+
+## Truncation
+(Include only if content appears cut mid-element.) "Content cut mid-<table row / code block / comment / paragraph>; extraction may be incomplete for <section>."
+
+RULES:
+- Never paraphrase numbers, versions, code, or quoted text.
+- If an instruction item is not answered, it goes in "Not found" \u2014 do NOT invent an answer to please the caller.
+- Preserve code blocks, command examples, tables exactly.
+- Do NOT add commentary or recommendations outside "Follow-up signals".
+- Page language \u2260 English: quote verbatim in the original language AND provide a parenthetical gloss in English.
+- Page appears gated (login wall, paywall, JS-render-empty shell) or near-empty: BEFORE dismissing the page, look for ANY visible text \u2014 og:title, og:description, meta description, headline, author name, nav labels, teaser/preview sentences, visible comment snippets. If ANY such text exists, extract it as usual under \`## Source\` + \`## Matches\`, and list the blocked facets under \`## Not found\`. Prefix the first \`## Matches\` bullet with \`**[partial \u2014 <reason>]**\` so the caller knows the body is gated (reasons: \`login-wall | paywall | JS-render-empty | truncated-before-relevant-section\`). ONLY when there is NO visible extractable text at all (< 50 words AND no og:* AND no headline AND no preview), return exactly one line:
+  \`## Matches\\n_Page did not load: <reason>_\`
+  Valid reasons: \`404 | login-wall | paywall | JS-render-empty | non-text-asset | truncated-before-relevant-section\`.
+
+Content:
+${truncatedContent}` : `Clean the following page content: drop navigation, ads, cookie banners, footers, author bios, related-article lists. Preserve headings, paragraphs, code blocks, tables, and inline links as \`[text](url)\`. Do NOT summarize \u2014 preserve the full body.
+
+${urlLine}Content:
+${truncatedContent}`;
+  let lastError;
+  if (skipPrimaryForSize) {
+    mcpLog(
+      "info",
+      `Input ${truncatedContent.length} chars exceeds primary model cap (${MAX_PRIMARY_MODEL_INPUT_CHARS}); routing directly to fallback`,
+      "llm"
+    );
+  } else {
+    for (let attempt = 0; attempt <= LLM_RETRY_CONFIG.maxRetries; attempt++) {
+      try {
+        if (attempt === 0) {
+          mcpLog("info", `Starting extraction with ${LLM_EXTRACTION.MODEL}`, "llm");
+        } else {
+          mcpLog("warning", `Retry attempt ${attempt}/${LLM_RETRY_CONFIG.maxRetries}`, "llm");
+        }
+        const response = await requestText(processor, prompt, "LLM extraction", signal);
+        if (response.content !== null) {
+          mcpLog("info", `Successfully extracted ${response.content.length} characters`, "llm");
+          markLLMSuccess("extractor");
+          return { content: response.content, processed: true };
+        }
+        const providerFailure = getProviderFailure(response);
+        if (providerFailure) {
+          throw providerFailure;
+        }
+        mcpLog("warning", "Received empty response from LLM", "llm");
+        markLLMFailure("extractor", "LLM returned empty response");
+        return emptyLLMExtractionResult(content);
+      } catch (err) {
+        lastError = classifyError(err);
+        const status = hasStatus(err) ? err.status : void 0;
+        const code = typeof err === "object" && err !== null && "code" in err ? String(err.code) : void 0;
+        const ctxErr = isContextWindowError(err);
+        mcpLog("error", `Error (attempt ${attempt + 1}): ${lastError.message} [status=${status}, code=${code}, retryable=${isRetryableLLMError(err)}, context_window=${ctxErr}]`, "llm");
+        if (ctxErr) {
+          mcpLog("warning", "Context window exceeded on primary \u2014 skipping remaining retries, routing to fallback", "llm");
+          break;
+        }
+        if (isRetryableLLMError(err) && attempt < LLM_RETRY_CONFIG.maxRetries) {
+          const delayMs = calculateLLMBackoff(attempt);
+          mcpLog("warning", `Retrying in ${delayMs}ms...`, "llm");
+          try {
+            await sleep(delayMs, signal);
+          } catch {
+            break;
+          }
+          continue;
+        }
+        break;
+      }
+    }
+  }
+  const fallbackModel = LLM_EXTRACTION.FALLBACK_MODEL;
+  if (fallbackModel) {
+    mcpLog("warning", `Primary exhausted, switching to fallback ${fallbackModel}`, "llm");
+    for (let attempt = 0; attempt < FALLBACK_RETRY_COUNT; attempt++) {
+      if (attempt > 0) {
+        const delayMs = calculateLLMBackoff(attempt - 1);
+        mcpLog("warning", `Fallback retry ${attempt}/${FALLBACK_RETRY_COUNT - 1} in ${delayMs}ms`, "llm");
+        try {
+          await sleep(delayMs, signal);
+        } catch {
+          break;
+        }
+      }
+      try {
+        const response = await requestText(processor, prompt, "LLM extraction [fallback]", signal, fallbackModel);
+        if (response.content !== null) {
+          mcpLog("info", `Fallback extracted ${response.content.length} characters`, "llm");
+          markLLMSuccess("extractor");
+          return { content: response.content, processed: true };
+        }
+        const providerFailure = getProviderFailure(response);
+        if (providerFailure) {
+          throw providerFailure;
+        }
+        mcpLog("warning", "Fallback returned empty response", "llm");
+        markLLMFailure("extractor", "LLM returned empty response");
+        return emptyLLMExtractionResult(content);
+      } catch (err) {
+        lastError = classifyError(err);
+        mcpLog("error", `Fallback error (attempt ${attempt + 1}): ${lastError.message}`, "llm");
+        if (isContextWindowError(err) || !isRetryableLLMError(err)) break;
+      }
+    }
+  }
+  const errorMessage = lastError?.message || "Unknown LLM error";
+  mcpLog("error", `All attempts failed: ${errorMessage}. Returning original content.`, "llm");
+  markLLMFailure("extractor", errorMessage);
+  return {
+    content,
+    processed: false,
+    error: `LLM extraction failed: ${errorMessage}`,
+    errorDetails: lastError || {
+      code: ErrorCode.UNKNOWN_ERROR,
+      message: errorMessage,
+      retryable: false
+    }
+  };
+}
+var MAX_CLASSIFICATION_URLS = 50;
+async function classifySearchResults(rankedUrls, objective, totalQueries, processor, previousQueries = []) {
+  const urlsToClassify = rankedUrls.slice(0, MAX_CLASSIFICATION_URLS);
+  const STATIC_WEIGHTS = [30, 20, 15, 10, 8, 6, 5, 4, 3, 2];
+  const weightForRank = (rank) => STATIC_WEIGHTS[rank - 1] ?? 1;
+  const lines = [];
+  for (const url of urlsToClassify) {
+    let domain;
+    try {
+      domain = new URL(url.url).hostname.replace(/^www\./, "");
+    } catch {
+      domain = url.url;
+    }
+    const snippet = url.snippet.length > 120 ? url.snippet.slice(0, 117) + "..." : url.snippet;
+    lines.push(`[${url.rank}] w=${weightForRank(url.rank)} ${url.title} \u2014 ${domain} \u2014 ${snippet}`);
+  }
+  const prevQueriesBlock = previousQueries.length > 0 ? previousQueries.map((q) => `- ${q}`).join("\n") : "- (none provided)";
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const prompt = `You are the relevance filter for a research agent. Classify each search result below against the objective and produce a structured analysis.
+
+OBJECTIVE: ${objective}
+TODAY: ${today}
+
+PREVIOUS QUERIES (already run \u2014 do NOT paraphrase in refine_queries):
+${prevQueriesBlock}
+
+Return ONLY a JSON object (no markdown, no code fences):
+
+{
+  "title": "2\u20138 word label for this RESULT CLUSTER (not the objective)",
+  "synthesis": "3\u20135 sentences grounded in the results. Every non-trivial claim cites a rank in [brackets], e.g. '[3] documents the flag; [7][12] report it is broken on macOS.' A synthesis with zero citations is invalid.",
+  "confidence": "high | medium | low",
+  "confidence_reason": "one sentence \u2014 why",
+  "gaps": [
+    { "id": 0, "description": "specific, actionable thing the current results do NOT answer \u2014 not 'more info needed'" }
+  ],
+  "refine_queries": [
+    { "query": "concrete next search", "gap_id": 0, "rationale": "\u226412 words" }
+  ],
+  "results": [
+    {
+      "rank": 1,
+      "tier": "HIGHLY_RELEVANT | MAYBE_RELEVANT | OTHER",
+      "source_type": "vendor_doc | github | reddit | hackernews | blog | news | marketing | stackoverflow | cve | paper | release_notes | aggregator | other",
+      "reason": "\u226412 words citing the snippet cue that drove the tier"
+    }
+  ]
+}
+
+WEIGHT SCHEME: each row is prefixed with a weight (w=N). Higher weight means the URL ranked better across input queries \u2014 prefer HIGHLY_RELEVANT for high-weight rows when content matches the objective. Weight alone never justifies HIGHLY_RELEVANT; snippet cues still drive the decision.
+
+SOURCE-OF-TRUTH RUBRIC (the "primary source" is goal-dependent \u2014 infer goal type from the objective):
+- spec / API / config questions \u2192 vendor_doc, github (README, RFC), release_notes are primary
+- bug / failure-mode questions \u2192 github (issue/PR), stackoverflow are primary
+- migration / sentiment / lived-experience \u2192 reddit, hackernews, blog are primary; docs are secondary
+- pricing / commercial \u2192 marketing (the vendor's own pricing page IS the primary source, but treat feature lists skeptically)
+- security / CVE \u2192 cve databases, distro security trackers (nvd.nist.gov, security-tracker.debian.org, ubuntu.com/security) are primary
+- synthesis / open-ended \u2192 blend; no single type is primary
+- product launch \u2192 vendor_doc + news + marketing for the launch itself; blogs + reddit for independent verification
+
+FRESHNESS: proportional to topic velocity. For a week-old release, demote anything older than 30 days. For general tech questions, demote older than 18 months. For stable protocols (HTTP, TCP, POSIX), don't demote by age.
+
+CONFIDENCE:
+- high = \u22653 HIGHLY_RELEVANT results from INDEPENDENT domains agree on the core answer
+- medium = \u22652 HIGHLY_RELEVANT exist but disagree or share a domain; OR a single authoritative primary source answers it
+- low = otherwise; snippet-only judgments cap at medium
+
+REFINE QUERIES \u2014 each MUST differ from every previousQuery by:
+- a new operator (site:, quotes, verbatim version number), OR
+- a domain-specific noun ABSENT from every prior query
+Adding a year alone does NOT count as differentiation.
+Each refine_query MUST reference a specific gap_id from the gaps array above.
+Produce 4\u20138 refine_queries total. Cover: (a) a primary-source probe, (b) a temporal sharpener, (c) a failure-mode or comparison probe, (d) at least one new-term probe seeded by a specific result's snippet.
+
+RULES:
+- Classify ALL ${urlsToClassify.length} results. Do not skip or collapse any.
+- Use only the three tier values.
+- Judge from title + domain + snippet only. Do NOT invent facts not present in the snippet.
+- If ALL results are OTHER: synthesis = "", confidence = "low", and \`gaps\` must explicitly state why the current queries missed the target.
+- Casing: tier = UPPERCASE_WITH_UNDERSCORES, confidence = lowercase.
+
+SEARCH RESULTS (${urlsToClassify.length} URLs from ${totalQueries} queries):
+${lines.join("\n")}`;
+  try {
+    mcpLog("info", `Classifying ${urlsToClassify.length} URLs against objective`, "llm");
+    const response = await requestTextWithFallback(
+      processor,
+      prompt,
+      "Search classification"
+    );
+    if (response.content === null) {
+      const errMsg = response.error ?? "LLM returned empty classification response";
+      markLLMFailure("planner", errMsg);
+      return { result: null, error: errMsg };
+    }
+    const cleaned = response.content.replace(/^```(?:json)?\s*\n?/m, "").replace(/\n?```\s*$/m, "").trim();
+    const parsed = JSON.parse(cleaned);
+    if (!parsed.title || typeof parsed.synthesis !== "string" || !Array.isArray(parsed.results)) {
+      const errMsg = "LLM response missing required fields (title, synthesis, results)";
+      markLLMFailure("planner", errMsg);
+      return { result: null, error: errMsg };
+    }
+    mcpLog("info", `Classification complete: ${parsed.results.filter((r) => r.tier === "HIGHLY_RELEVANT").length} highly relevant`, "llm");
+    markLLMSuccess("planner");
+    return { result: parsed };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    mcpLog("error", `Classification failed: ${message}`, "llm");
+    markLLMFailure("planner", message);
+    return { result: null, error: `Classification failed: ${message}` };
+  }
+}
+async function suggestRefineQueriesForRawMode(rankedUrls, objective, originalQueries, processor) {
+  const urlsToSummarize = rankedUrls.slice(0, 12);
+  const lines = urlsToSummarize.map((url) => {
+    let domain;
+    try {
+      domain = new URL(url.url).hostname.replace(/^www\./, "");
+    } catch {
+      domain = url.url;
+    }
+    return `[${url.rank}] ${url.title} \u2014 ${domain}`;
+  });
+  const prompt = `You are generating follow-up search queries for an agent using raw search results.
+
+Return ONLY a JSON object (no markdown, no code fences):
+{
+  "refine_queries": [
+    { "query": "next search query", "gap_description": "what gap this closes", "rationale": "\u226412 words on why" }
+  ]
+}
+
+OBJECTIVE: ${objective}
+
+PREVIOUS QUERIES (already run \u2014 do NOT paraphrase):
+${originalQueries.map((query) => `- ${query}`).join("\n")}
+
+TOP RESULT TITLES (to seed new-term probes):
+${lines.join("\n")}
+
+RULES:
+- Produce 4\u20136 diverse follow-ups. Cover: (a) a primary-source probe (site:, RFC, vendor docs); (b) a temporal sharpener (changelog, version number); (c) a failure-mode or comparison probe; (d) at least one new-term probe seeded by a specific result title.
+- Each query MUST differ from every previousQuery by either a new operator (site:, quotes, a verbatim version number) OR a domain-specific noun absent from every prior query. Adding a year alone does NOT count.
+- Each refine_query MUST include a \`gap_description\` naming what the current results don't answer.
+- Do not include URLs.
+- Keep rationales \u226412 words.`;
+  try {
+    const response = await requestTextWithFallback(
+      processor,
+      prompt,
+      "Raw-mode refine query generation"
+    );
+    if (response.content === null) {
+      const errMsg = response.error ?? "LLM returned empty raw-mode refine query response";
+      markLLMFailure("planner", errMsg);
+      return { result: [], error: errMsg };
+    }
+    const cleaned = response.content.replace(/^```(?:json)?\s*\n?/m, "").replace(/\n?```\s*$/m, "").trim();
+    const parsed = JSON.parse(cleaned);
+    markLLMSuccess("planner");
+    return { result: Array.isArray(parsed.refine_queries) ? parsed.refine_queries : [] };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    mcpLog("error", `Raw-mode refine query generation failed: ${message}`, "llm");
+    markLLMFailure("planner", message);
+    return { result: [], error: message };
+  }
+}
+var VALID_GOAL_CLASSES = /* @__PURE__ */ new Set([
+  "spec",
+  "bug",
+  "migration",
+  "sentiment",
+  "pricing",
+  "security",
+  "synthesis",
+  "product_launch",
+  "other"
+]);
+var VALID_FRESHNESS = /* @__PURE__ */ new Set(["days", "weeks", "months", "years"]);
+var VALID_BRANCHES = /* @__PURE__ */ new Set(["reddit", "web", "both"]);
+var VALID_STEP_TOOLS = /* @__PURE__ */ new Set(["raw-web-search", "smart-web-search", "raw-scrape-links", "smart-scrape-links"]);
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+function isStepArray(value) {
+  return Array.isArray(value) && value.every((s) => {
+    if (typeof s !== "object" || s === null) return false;
+    const tool = s.tool;
+    const reason = s.reason;
+    return typeof tool === "string" && VALID_STEP_TOOLS.has(tool) && typeof reason === "string" && reason.trim().length > 0;
+  });
+}
+function parseResearchBrief(raw) {
+  try {
+    const cleaned = raw.replace(/^```(?:json)?\s*\n?/m, "").replace(/\n?```\s*$/m, "").trim();
+    const parsed = JSON.parse(cleaned);
+    const goal_class = typeof parsed.goal_class === "string" ? parsed.goal_class : null;
+    if (!goal_class || !VALID_GOAL_CLASSES.has(goal_class)) return null;
+    const freshness_window = typeof parsed.freshness_window === "string" ? parsed.freshness_window : null;
+    if (!freshness_window || !VALID_FRESHNESS.has(freshness_window)) return null;
+    const primary_branch = parsed.primary_branch;
+    if (typeof primary_branch !== "string" || !VALID_BRANCHES.has(primary_branch)) return null;
+    if (!isStepArray(parsed.first_call_sequence) || parsed.first_call_sequence.length === 0) return null;
+    if (!isStringArray(parsed.keyword_seeds) || parsed.keyword_seeds.length === 0) return null;
+    return {
+      goal_class,
+      goal_class_reason: typeof parsed.goal_class_reason === "string" ? parsed.goal_class_reason : "",
+      primary_branch,
+      primary_branch_reason: typeof parsed.primary_branch_reason === "string" ? parsed.primary_branch_reason : "",
+      freshness_window,
+      first_call_sequence: parsed.first_call_sequence,
+      keyword_seeds: parsed.keyword_seeds.filter((s) => s.trim().length > 0),
+      iteration_hints: isStringArray(parsed.iteration_hints) ? parsed.iteration_hints : [],
+      gaps_to_watch: isStringArray(parsed.gaps_to_watch) ? parsed.gaps_to_watch : [],
+      stop_criteria: isStringArray(parsed.stop_criteria) ? parsed.stop_criteria : []
+    };
+  } catch {
+    return null;
+  }
+}
+async function generateResearchBrief(goal, processor, signal) {
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const prompt = `You are a research planner. An agent is about to run a multi-pass research loop on the goal below using 5 tools:
+
+  - start-research: orientation and this brief
+  - raw-web-search: raw search fan-out, keywords only, up to 50 keywords per call, no LLM; best for breadth, audit trails, and candidate URL capture
+  - smart-web-search: search fan-out + required LLM prioritization/classification over titles/snippets, scope: web|reddit|both, up to 50 keywords per call; best for triage after a strong diverse keyword set
+  - raw-scrape-links: fetch URLs as full markdown, urls only, no LLM; Reddit permalinks return threaded comments; best for complete context and ambiguous sources
+  - smart-scrape-links: fetch URLs then required LLM extraction over page bodies; Reddit permalinks return threaded comments before extraction; best for focused evidence extraction once facets are known
+
+Produce a tailored JSON brief.
+
+GOAL: ${goal}
+TODAY: ${today}
+
+Return ONLY a JSON object (no markdown, no code fences):
+
+{
+  "goal_class": "spec | bug | migration | sentiment | pricing | security | synthesis | product_launch | other",
+  "goal_class_reason": "one sentence \u2014 why this class",
+  "primary_branch": "reddit | web | both",
+  "primary_branch_reason": "one sentence \u2014 why this branch leads",
+  "freshness_window": "days | weeks | months | years",
+  "first_call_sequence": [
+    { "tool": "raw-web-search | smart-web-search | raw-scrape-links | smart-scrape-links", "reason": "what this call establishes for the agent" }
+  ],
+  "keyword_seeds": ["25\u201350 concrete search keywords \u2014 flat list, to be fired in the first search call as keywords"],
+  "iteration_hints": ["2\u20135 pointers on which harvested terms / follow-up signals to watch for after pass 1"],
+  "gaps_to_watch": ["2\u20135 concrete questions the agent MUST verify or the answer is incomplete"],
+  "stop_criteria": ["2\u20134 checkable conditions \u2014 all must hold before the agent declares done"]
+}
+
+RULES:
+
+primary_branch:
+- "reddit"  \u2192 sentiment / migration / lived-experience / community-consensus goals. Usually leads with raw-web-search using Reddit-focused keywords, then raw-scrape-links on post permalinks to preserve full comments.
+- "web"     \u2192 spec / bug / pricing / CVE / API / primary-source goals. Usually leads with raw-web-search for maximum candidate breadth OR smart-web-search scope:"web" when the initial keyword set is already diverse and needs prioritization.
+- "both"    \u2192 opinion-heavy AND needs official sources (e.g. product launch + practitioner reception).
+
+first_call_sequence:
+- 1\u20133 steps.
+- Use raw-web-search when the first need is recall: many distinct source classes, exact candidate URLs, Reddit permalink discovery, or cheap follow-up passes.
+- Use smart-web-search when the first need is prioritization: the agent has 10\u201350 distinct keyword probes and needs HIGHLY/MAYBE tiers, gaps, and refine queries. Smart search reads snippets only; never plan it as final evidence.
+- Use raw-scrape-links when complete page/thread context is valuable, the extraction shape is unclear, or Reddit comments are the source of truth.
+- Use smart-scrape-links when the extraction shape is known (facets separated by |) and the agent needs compact evidence from page bodies; this is usually the highest-value smart tool for answer construction.
+- reddit-first: step 1 = raw-web-search with Reddit permalink probes; step 2 = raw-scrape-links on best post permalinks for full comments. Add smart-web-search only when there are many candidate posts to triage.
+- web-first:    step 1 = raw-web-search for broad URL capture OR smart-web-search scope:"web" for prioritizing a diverse keyword fan-out; step 2 = smart-scrape-links on selected URLs when extraction facets are known, otherwise raw-scrape-links first.
+- both:         step 1 = parallel search calls split by source need; step 2 = raw-scrape-links for full evidence and smart-scrape-links for final extraction.
+
+keyword_seeds:
+- 25\u201350 total. Narrow bug \u2192 fewer. Open synthesis \u2192 more.
+- Write Google retrieval probes, not topic labels.
+- For each broad idea, first do a bad \u2192 better rewrite in your head: replace a vague phrase with a query that names the evidence source class, discriminating anchor terms, and one useful operator when possible.
+- ${QUERY_REWRITE_PAIR_GUIDANCE_TEXT}
+- Use operators where helpful (site:, quotes, verbatim version numbers, exact error text, package names, release/version strings).
+- DIVERSE facets \u2014 same noun-phrase cannot repeat across seeds with adjectives-only variation.
+- Optimize keyword_seeds for distinct coverage first. Smart-web-search can prioritize a broad result set, but it cannot compensate for a narrow or repetitive keyword set.
+- Do NOT invent vendor names you are uncertain exist.
+- For \`site:<domain>\` filters, ONLY use domains you are highly confident are real. Safe choices: \`github.com\`, \`stackoverflow.com\`, \`reddit.com\`, \`news.ycombinator.com\`, \`arxiv.org\`, \`nvd.nist.gov\`, \`pypi.org\`, \`npmjs.com\`, plus any canonical homepage/docs domain explicitly spelled out in the goal itself (e.g. goal names "Cursor" \u2192 \`cursor.com\`/\`docs.cursor.com\` is acceptable). If you don't know the product's real docs domain, leave the query open (no \`site:\`) instead of guessing.
+
+freshness_window:
+- If the goal mentions a recent release / date / version, use "days" or "weeks".
+- Stable protocols / APIs \u2192 "months" or "years".`;
+  try {
+    const response = await requestTextWithFallback(
+      processor,
+      prompt,
+      "Research brief generation",
+      signal
+    );
+    if (response.content === null) {
+      mcpLog("warning", `Research brief generation returned no content: ${response.error ?? "unknown"}`, "llm");
+      markLLMFailure("planner", response.error ?? "empty response");
+      return null;
+    }
+    const brief = parseResearchBrief(response.content);
+    if (!brief) {
+      mcpLog("warning", "Research brief JSON parse or shape validation failed", "llm");
+      markLLMFailure("planner", "brief parse/validation failed");
+      return null;
+    }
+    markLLMSuccess("planner");
+    return brief;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    mcpLog("warning", `Research brief generation failed: ${message}`, "llm");
+    markLLMFailure("planner", message);
+    return null;
+  }
+}
+
+// src/effect/errors.ts
+import { Data } from "effect";
+var ProviderRequestError = class extends Data.TaggedError("ProviderRequestError") {
+};
+var ProviderTimeoutError = class extends Data.TaggedError("ProviderTimeoutError") {
+};
+var WeakContentError = class extends Data.TaggedError("WeakContentError") {
+};
+var AllStrategiesExhaustedError = class extends Data.TaggedError("AllStrategiesExhaustedError") {
+};
+function providerError(provider, operation, error) {
+  return new ProviderRequestError({
+    provider,
+    operation,
+    error: classifyError(error)
+  });
+}
+
+// src/effect/services.ts
+var SearchService = Context.GenericTag("SearchService");
+var JinaService = Context.GenericTag("JinaService");
+var KernelService = Context.GenericTag("KernelService");
+var RedditService = Context.GenericTag("RedditService");
+var LlmService = Context.GenericTag("LlmService");
+var SearchServiceLive = Layer.sync(SearchService, () => {
+  const env = parseEnv();
+  return {
+    serperSearchMultiple: (queries) => Effect.tryPromise({
+      try: () => new SearchClient(env.SEARCH_API_KEY).searchMultiple([...queries]),
+      catch: (error) => providerError("serper", "searchMultiple", error)
+    }),
+    jinaSearchMultiple: (queries) => Effect.tryPromise({
+      try: () => new JinaClient(env.JINA_API_KEY).searchMultiple([...queries]),
+      catch: (error) => providerError("jina", "searchMultiple", error)
+    })
+  };
+});
+var JinaServiceLive = Layer.sync(JinaService, () => {
+  const env = parseEnv();
+  const client = new JinaClient(env.JINA_API_KEY);
+  return {
+    convert: (request) => Effect.tryPromise({
+      try: () => client.convert(request),
+      catch: (error) => providerError("jina", "convert", error)
+    })
+  };
+});
+var KernelServiceLive = Layer.sync(KernelService, () => {
+  const client = new KernelClient();
+  return {
+    render: (request) => Effect.tryPromise({
+      try: () => client.render(request),
+      catch: (error) => providerError("kernel", "render", error)
+    })
+  };
+});
+var LlmServiceLive = Layer.succeed(LlmService, {
+  extractContent: (content, config) => Effect.tryPromise({
+    try: () => processContentWithLLM(content, config, createLLMProcessor()),
+    catch: (error) => providerError("llm", "extractContent", error)
+  }),
+  classifySearchResults: (rankedUrls, objective, totalQueries, processor, previousQueries) => Effect.tryPromise({
+    try: () => classifySearchResults(rankedUrls, objective, totalQueries, processor, previousQueries),
+    catch: (error) => providerError("llm", "classifySearchResults", error)
+  }),
+  suggestRefineQueriesForRawMode: (rankedUrls, objective, originalQueries, processor) => Effect.tryPromise({
+    try: () => suggestRefineQueriesForRawMode(rankedUrls, objective, originalQueries, processor),
+    catch: (error) => providerError("llm", "suggestRefineQueriesForRawMode", error)
+  }),
+  generateResearchBrief: (goal, processor) => Effect.tryPromise({
+    try: () => generateResearchBrief(goal, processor),
+    catch: (error) => providerError("llm", "generateResearchBrief", error)
+  })
+});
+
+// src/effect/runtime.ts
+var BaseExternalLive = Layer2.mergeAll(
   JinaServiceLive,
   SearchServiceLive,
   LlmServiceLive
 );
 function runExternalEffect(effect, layer) {
-  return Effect.runPromise(effect.pipe(Effect.provide(layer)));
+  return Effect2.runPromise(effect.pipe(Effect2.provide(layer)));
 }
 export {
   BaseExternalLive,