mcp-researchpowerpack 7.0.10 → 7.0.12

package/dist/index.js

@@ -1,22 +1,4663 @@
 #!/usr/bin/env node
-if (!process.env.UV_THREADPOOL_SIZE) {
-  process.env.UV_THREADPOOL_SIZE = "8";
-}
-import { Logger } from "mcp-use";
+
+// index.ts
+import { Logger as Logger5 } from "mcp-use";
 import {
   InMemorySessionStore,
   InMemoryStreamManager,
   MCPServer,
   object
 } from "mcp-use/server";
-import { SERVER } from "./src/config/index.js";
-import { getLLMHealth } from "./src/services/llm-processor.js";
-import { registerAllTools } from "./src/tools/registry.js";
-const DEFAULT_PORT = 3e3;
-const SHUTDOWN_TIMEOUT_MS = 1e4;
-const WEBSITE_URL = "https://github.com/yigitkonur/mcp-researchpowerpack";
-const LOCAL_DEFAULT_HOST = "127.0.0.1";
-const startupLogger = Logger.get("startup");
+
+// 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 logger2 = Logger.get("config");
+  if (!value) {
+    return defaultVal;
+  }
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed)) {
+    logger2.warn(`Invalid number "${value}", using default ${defaultVal}`);
+    return defaultVal;
+  }
+  if (parsed < min) {
+    logger2.warn(`Value ${parsed} below minimum ${min}, clamping to ${min}`);
+    return min;
+  }
+  if (parsed > max) {
+    logger2.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;
+}
+var SERVER = {
+  NAME: PACKAGE_NAME,
+  VERSION,
+  DESCRIPTION: PACKAGE_DESCRIPTION
+};
+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
+  };
+}
+function getMissingEnvMessage(capability) {
+  const messages = {
+    reddit: '\u274C **Reddit scraping unavailable.** Set `REDDIT_CLIENT_ID` and `REDDIT_CLIENT_SECRET` to enable threaded Reddit post fetching in `raw-scrape-links` and `smart-scrape-links`.\n\n\u{1F449} Create a Reddit app at: https://www.reddit.com/prefs/apps (select "script" type)',
+    search: "\u274C **Search unavailable.** Set `SERPER_API_KEY` or `JINA_API_KEY` to enable `raw-web-search` and `smart-web-search`.\n\n\u{1F449} Serper provides Google SERPs; Jina Search is used as a fallback/search-only provider.",
+    serperSearch: "\u274C **Serper search unavailable.** Set `SERPER_API_KEY` to enable Google-backed primary search.",
+    jina: "\u274C **Jina unavailable.** Set `JINA_API_KEY` to enable Jina Search and authenticated Jina Reader requests.",
+    scraping: "\u26A0\uFE0F **Scrape.do proxy fallback unavailable.** Set `SCRAPEDO_API_KEY` to enable Jina Reader retries through Scrape.do proxy mode.\n\n\u{1F449} Sign up at: https://scrape.do (1,000 free credits)",
+    kernel: "\u274C **Kernel browser rendering unavailable.** Set `KERNEL_API_KEY` to enable optional browser-render fallback for raw/smart scraping.",
+    llmExtraction: "\u26A0\uFE0F **AI extraction disabled.** Set `LLM_API_KEY`, `LLM_BASE_URL`, and `LLM_MODEL` to enable `smart-web-search` and `smart-scrape-links`.\n\nUse the raw tools when you need markdown without LLM processing."
+  };
+  return messages[capability];
+}
+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 SCRAPER = {
+  BATCH_SIZE: 30,
+  EXTRACTION_PREFIX: "Extract from document only \u2014 never hallucinate or add external knowledge.",
+  EXTRACTION_SUFFIX: "First line = content, not preamble. No confirmation messages."
+};
+var REDDIT = {
+  BATCH_SIZE: 10,
+  MAX_WORDS_PER_POST: 5e4,
+  MAX_WORDS_TOTAL: 5e5,
+  MIN_POSTS: 1,
+  MAX_POSTS: 50,
+  RETRY_COUNT: 5,
+  RETRY_DELAYS: [2e3, 4e3, 8e3, 16e3, 32e3]
+};
+var CTR_WEIGHTS = {
+  1: 100,
+  2: 60,
+  3: 48.89,
+  4: 33.33,
+  5: 28.89,
+  6: 26.44,
+  7: 24.44,
+  8: 17.78,
+  9: 13.33,
+  10: 12.56
+};
+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/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/utils/logger.ts
+import { Logger as Logger2 } from "mcp-use";
+function getLogger(name) {
+  return Logger2.get(name);
+}
+function mcpLog(level, message, loggerName) {
+  const logger2 = getLogger(loggerName ?? "research-powerpack");
+  switch (level) {
+    case "debug":
+      logger2.debug(message);
+      break;
+    case "info":
+      logger2.info(message);
+      break;
+    case "warning":
+      logger2.warn(message);
+      break;
+    case "error":
+      logger2.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(error2) {
+  if (error2.name === "AbortError") {
+    return { code: ErrorCode.TIMEOUT, message: "Request timed out", retryable: true };
+  }
+  return { code: ErrorCode.UNKNOWN_ERROR, message: error2.message, retryable: false };
+}
+function classifyByErrorCode(error2) {
+  const errCode = error2.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: error2.message };
+  }
+  if (errCode === "ECONNABORTED" || errCode === "ETIMEDOUT") {
+    return { code: ErrorCode.TIMEOUT, message: networkErrorMessages[errCode] || "Request timed out", retryable: true, cause: error2.message };
+  }
+  return null;
+}
+function classifyByStatusCode(error2) {
+  const status = error2.response?.status || error2.status || error2.statusCode;
+  if (!status) return null;
+  return classifyHttpError(status, error2.message || String(error2));
+}
+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(error2) {
+  if (error2 == null) {
+    return { code: ErrorCode.UNKNOWN_ERROR, message: "An unknown error occurred", retryable: false };
+  }
+  if (error2 instanceof DOMException) return classifyDomException(error2);
+  if (!isErrorLike(error2)) {
+    return { code: ErrorCode.UNKNOWN_ERROR, message: String(error2), retryable: false };
+  }
+  return classifyByErrorCode(error2) ?? classifyByStatusCode(error2) ?? classifyByMessage(error2.message ?? String(error2)) ?? classifyFallback(error2.message ?? String(error2), error2.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/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;
+  }
+}
+function getLLMHealth() {
+  const cap = getCapabilities();
+  return {
+    lastPlannerOk: llmHealth.lastPlannerOk,
+    lastExtractorOk: llmHealth.lastExtractorOk,
+    lastPlannerCheckedAt: llmHealth.lastPlannerCheckedAt,
+    lastExtractorCheckedAt: llmHealth.lastExtractorCheckedAt,
+    lastPlannerError: llmHealth.lastPlannerError,
+    lastExtractorError: llmHealth.lastExtractorError,
+    // Static capability — based on env presence at boot. Runtime health (above)
+    // tells whether the last attempt actually succeeded.
+    plannerConfigured: cap.llmExtraction,
+    extractorConfigured: cap.llmExtraction,
+    consecutivePlannerFailures: llmHealth.consecutivePlannerFailures,
+    consecutiveExtractorFailures: llmHealth.consecutiveExtractorFailures
+  };
+}
+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(error2) {
+  return typeof error2 === "object" && error2 !== null && "status" in error2 && typeof error2.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(error2) {
+  if (!error2 || typeof error2 !== "object") return false;
+  const stallCode = error2?.code;
+  if (stallCode === "ESTALLED" || stallCode === "ETIMEDOUT") {
+    return true;
+  }
+  if (hasStatus(error2)) {
+    if (error2.status === 429 || error2.status === 500 || error2.status === 502 || error2.status === 503 || error2.status === 504) {
+      return true;
+    }
+  }
+  const record = error2;
+  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(error2) {
+  if (!error2 || typeof error2 !== "object") return false;
+  const record = error2;
+  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;
+  }
+}
+function renderResearchBrief(brief) {
+  const lines = [];
+  lines.push("## Your research brief (goal-tailored)");
+  lines.push("");
+  lines.push(`**Goal class**: \`${brief.goal_class}\` \u2014 ${brief.goal_class_reason}`);
+  lines.push(`**Primary branch**: \`${brief.primary_branch}\` \u2014 ${brief.primary_branch_reason}`);
+  lines.push(`**Freshness**: \`${brief.freshness_window}\``);
+  lines.push("");
+  if (brief.first_call_sequence.length > 0) {
+    lines.push("### First-call sequence");
+    brief.first_call_sequence.forEach((step, i) => {
+      lines.push(`${i + 1}. \`${step.tool}\` \u2014 ${step.reason}`);
+    });
+    lines.push("");
+  }
+  if (brief.keyword_seeds.length > 0) {
+    lines.push(`### Keyword seeds (${brief.keyword_seeds.length}) \u2014 fire these in your first search call as a flat \`keywords\` array`);
+    for (const seed of brief.keyword_seeds) {
+      lines.push(`- ${seed}`);
+    }
+    lines.push("");
+  }
+  if (brief.iteration_hints.length > 0) {
+    lines.push("### Iteration hints (harvest new terms from scrape extracts' `## Follow-up signals`)");
+    for (const hint of brief.iteration_hints) lines.push(`- ${hint}`);
+    lines.push("");
+  }
+  if (brief.gaps_to_watch.length > 0) {
+    lines.push("### Gaps to watch");
+    for (const gap of brief.gaps_to_watch) lines.push(`- ${gap}`);
+    lines.push("");
+  }
+  if (brief.stop_criteria.length > 0) {
+    lines.push("### Stop criteria");
+    for (const c of brief.stop_criteria) lines.push(`- ${c}`);
+    lines.push("");
+  }
+  lines.push("---");
+  lines.push("");
+  lines.push("Fire `first_call_sequence` now. After each smart scrape, harvest new terms from `## Follow-up signals`; after each raw scrape, inspect the full markdown/comments and seed the next search round. Stop when every gap is closed.");
+  return lines.join("\n");
+}
+
+// src/tools/scrape.ts
+import { Effect as Effect3, Either } from "effect";
+
+// src/schemas/scrape-links.ts
+import { z as z2 } from "zod";
+var urlSchema = z2.string().url({ message: "scrape: Invalid URL format" }).refine(
+  (url) => url.startsWith("http://") || url.startsWith("https://"),
+  { message: "scrape: URL must use http:// or https://" }
+).describe("A fully-qualified HTTP or HTTPS URL to scrape.");
+var urlsSchema = z2.array(urlSchema).min(1, { message: "scrape: At least 1 URL required" }).max(50, { message: "scrape: At most 50 URLs allowed per call" }).describe("URLs to fetch in parallel. Reddit post permalinks (`reddit.com/r/<sub>/comments/<id>/...`) are auto-detected and routed through the Reddit API (threaded post + comments). Non-Reddit URLs use Jina Reader first, then Jina Reader through Scrape.do proxy when configured, then optional Kernel browser rendering for web pages.");
+var rawScrapeLinksParamsSchema = z2.object({
+  urls: urlsSchema,
+  extract: z2.never().optional()
+}).strict();
+var smartScrapeLinksParamsSchema = z2.object({
+  urls: z2.array(urlSchema).min(1, { message: "scrape: At least 1 URL required" }).max(50, { message: "scrape: At most 50 URLs allowed per call" }).describe("URLs to fetch and extract in parallel. Reddit post permalinks (`reddit.com/r/<sub>/comments/<id>/...`) are auto-detected and routed through the Reddit API (threaded post + comments). Non-Reddit URLs use Jina Reader first, then Jina Reader through Scrape.do proxy when configured, then optional Kernel browser rendering for web pages. Mix reddit + non-reddit URLs freely; branches run concurrently. Prefer contextually grouped batches \u2014 call this tool multiple times in parallel when URL sets are unrelated."),
+  extract: z2.string().min(1, { message: "smart-scrape-links: extract cannot be empty" }).describe(
+    'Required semantic extraction instruction. Describe the SHAPE of what you want, separated by `|`. The extractor classifies each page (docs / github-thread / reddit / marketing / cve / paper / announcement / qa / blog / changelog / release-notes) and adjusts emphasis per type: preserves numbers/versions/stacktraces verbatim from docs and CVE pages, quotes Reddit/HN with attribution plus sentiment distribution, flags what the page did NOT answer in a "Not found" section, and surfaces referenced-but-unscraped URLs in a "Follow-up signals" section. Good examples: "root cause | affected versions | fix | workarounds | timeline"; "pricing tiers | rate limits | enterprise contact | free-tier quotas"; "maintainer decisions | accepted fix commits | stacktraces | resolved version".'
+  )
+}).strict();
+
+// 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/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_RETRIES = 2;
+var SEARCH_RESULTS_PER_QUERY = 10;
+function buildJinaSearchUrl(query) {
+  const params = new URLSearchParams({ q: query });
+  return `${JINA_SEARCH_BASE}?${params.toString()}`;
+}
+function buildScrapeDoProxyUrl(token, parameters = "render=false") {
+  const trimmed = token.trim();
+  if (!trimmed) return "";
+  return `http://${encodeURIComponent(trimmed)}:${parameters}@proxy.scrape.do:8080`;
+}
+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_RETRIES; 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_RETRIES) {
+          const delayMs = calculateBackoff2(attempt);
+          mcpLog(
+            "warning",
+            `Jina ${response.status} on attempt ${attempt + 1}/${MAX_RETRIES + 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 (error2) {
+        lastError = classifyError(error2);
+        if (lastError.retryable && attempt < MAX_RETRIES) {
+          const delayMs = calculateBackoff2(attempt);
+          mcpLog(
+            "warning",
+            `Jina ${lastError.code}: ${lastError.message}. Retry ${attempt + 1}/${MAX_RETRIES + 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_RETRIES + 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 (error2) {
+      return {
+        query,
+        results: [],
+        totalResults: 0,
+        related: [],
+        error: classifyError(error2)
+      };
+    }
+  }
+};
+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(error2) {
+  return !error2.retryable && (error2.code === ErrorCode.AUTH_ERROR || error2.code === ErrorCode.QUOTA_EXCEEDED || error2.code === ErrorCode.NOT_FOUND || error2.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/services/markdown-cleaner.ts
+import { Logger as Logger3 } from "mcp-use";
+import TurndownService from "turndown";
+var logger = Logger3.get("markdown-cleaner");
+var turndown = new TurndownService({
+  headingStyle: "atx",
+  codeBlockStyle: "fenced",
+  bulletListMarker: "-"
+});
+turndown.remove(["script", "style", "nav", "footer", "aside", "noscript"]);
+var MAX_CONTENT_LENGTH = 524288;
+function removeHtmlComments(html) {
+  const parts = [];
+  let pos = 0;
+  while (pos < html.length) {
+    const start = html.indexOf("<!--", pos);
+    if (start === -1) {
+      parts.push(html.substring(pos));
+      break;
+    }
+    if (start > pos) parts.push(html.substring(pos, start));
+    const end = html.indexOf("-->", start + 4);
+    if (end === -1) {
+      parts.push(html.substring(start));
+      break;
+    }
+    pos = end + 3;
+  }
+  return parts.join("");
+}
+var MarkdownCleaner = class {
+  /**
+   * Process HTML content and convert to clean Markdown
+   * NEVER throws - returns original content on any error for graceful degradation
+   */
+  processContent(htmlContent) {
+    try {
+      if (!htmlContent || typeof htmlContent !== "string") {
+        return htmlContent || "";
+      }
+      if (!htmlContent.includes("<")) {
+        return htmlContent.trim();
+      }
+      if (htmlContent.length > MAX_CONTENT_LENGTH) {
+        htmlContent = htmlContent.substring(0, MAX_CONTENT_LENGTH);
+      }
+      let content = removeHtmlComments(htmlContent);
+      content = turndown.turndown(content);
+      content = content.replace(/\n{3,}/g, "\n\n");
+      content = content.trim();
+      return content;
+    } catch (error2) {
+      logger.warn(
+        `processContent failed: ${error2 instanceof Error ? error2.message : String(error2)} | Content length: ${htmlContent?.length ?? 0}`
+      );
+      return htmlContent || "";
+    }
+  }
+};
+
+// src/utils/markdown-formatter.ts
+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");
+}
+
+// src/utils/content-extractor.ts
+import { Readability } from "@mozilla/readability";
+import { JSDOM, VirtualConsole } from "jsdom";
+var MAX_READABILITY_BYTES = 15e5;
+function extractReadableContent(html, url) {
+  if (!html || typeof html !== "string") {
+    return { title: "", content: html ?? "", extracted: false };
+  }
+  if (html.length > MAX_READABILITY_BYTES) {
+    return { title: "", content: html, extracted: false };
+  }
+  if (!html.includes("<")) {
+    return { title: "", content: html, extracted: false };
+  }
+  const virtualConsole = new VirtualConsole();
+  virtualConsole.on("error", () => {
+  });
+  virtualConsole.on("warn", () => {
+  });
+  virtualConsole.on("jsdomError", () => {
+  });
+  let dom;
+  try {
+    dom = new JSDOM(html, {
+      url: url && /^https?:/i.test(url) ? url : "https://example.com/",
+      virtualConsole
+    });
+  } catch (err) {
+    mcpLog("warning", `JSDOM construction failed: ${err instanceof Error ? err.message : String(err)}`, "content-extractor");
+    return { title: "", content: html, extracted: false };
+  }
+  try {
+    const reader = new Readability(dom.window.document, {
+      // Keep classes that downstream cleanup may need; Turndown ignores them.
+      keepClasses: false
+      // Strip <script>/<style> already handled by Readability defaults.
+    });
+    const article = reader.parse();
+    if (!article || !article.content) {
+      return { title: article?.title ?? "", content: html, extracted: false };
+    }
+    return {
+      title: article.title ?? "",
+      content: article.content,
+      byline: article.byline ?? void 0,
+      extracted: true
+    };
+  } catch (err) {
+    mcpLog("warning", `Readability.parse failed: ${err instanceof Error ? err.message : String(err)}`, "content-extractor");
+    return { title: "", content: html, extracted: false };
+  } finally {
+    try {
+      dom.window.close();
+    } catch {
+    }
+  }
+}
+
+// src/utils/source-type.ts
+var DOCUMENT_PATH_SUFFIXES = [
+  ".pdf",
+  ".doc",
+  ".docx",
+  ".ppt",
+  ".pptx",
+  ".xls",
+  ".xlsx"
+];
+function isDocumentUrl(url) {
+  let pathname;
+  try {
+    pathname = new URL(url).pathname.toLowerCase();
+  } catch {
+    return false;
+  }
+  for (const suffix of DOCUMENT_PATH_SUFFIXES) {
+    if (pathname.endsWith(suffix)) return true;
+  }
+  return false;
+}
+
+// src/utils/content-quality.ts
+var MIN_MARKDOWN_CHARS = 800;
+var MIN_MARKDOWN_WORDS = 120;
+var BLOCK_PHRASES = [
+  "access denied",
+  "are you a human",
+  "captcha",
+  "checking your browser",
+  "enable javascript",
+  "just a moment",
+  "login required",
+  "please enable cookies",
+  "please verify you are human",
+  "sign in to continue",
+  "temporarily unavailable"
+];
+function countWords(content) {
+  const matches = content.trim().match(/\S+/g);
+  return matches ? matches.length : 0;
+}
+function findBlockPhrase(content) {
+  const lower = content.toLowerCase();
+  return BLOCK_PHRASES.find((phrase) => lower.includes(phrase));
+}
+function assessMarkdownQuality(content) {
+  const trimmed = content.trim();
+  const charCount = trimmed.length;
+  const wordCount = countWords(trimmed);
+  const blockPhrase = findBlockPhrase(trimmed);
+  if (blockPhrase) {
+    return {
+      weak: true,
+      reason: `blocked_or_interstitial:${blockPhrase}`,
+      charCount,
+      wordCount,
+      blockPhrase
+    };
+  }
+  if (charCount < MIN_MARKDOWN_CHARS) {
+    return {
+      weak: true,
+      reason: `too_few_chars:${charCount}<${MIN_MARKDOWN_CHARS}`,
+      charCount,
+      wordCount
+    };
+  }
+  if (wordCount < MIN_MARKDOWN_WORDS) {
+    return {
+      weak: true,
+      reason: `too_few_words:${wordCount}<${MIN_MARKDOWN_WORDS}`,
+      charCount,
+      wordCount
+    };
+  }
+  return {
+    weak: false,
+    reason: "ok",
+    charCount,
+    wordCount
+  };
+}
+
+// src/effect/runtime.ts
+import { Effect as Effect2, Layer as Layer2 } from "effect";
+
+// src/effect/services.ts
+import { Context, Effect, Layer } from "effect";
+
+// 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 });
+}
+async function pMapSettled(items, mapper, concurrency = 6, signal) {
+  if (items.length === 0) return [];
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  return pMapLib(
+    items,
+    async (item, index) => {
+      try {
+        const value = await mapper(item, index);
+        return { status: "fulfilled", value };
+      } catch (reason) {
+        return { status: "rejected", reason };
+      }
+    },
+    { concurrency: limit, signal, stopOnError: false }
+  );
+}
+
+// src/clients/search.ts
+var SERPER_API_URL = "https://google.serper.dev/search";
+var DEFAULT_RESULTS_PER_QUERY = 10;
+var MAX_RETRIES2 = 3;
+var SEARCH_RETRY_CONFIG = {
+  maxRetries: MAX_RETRIES2,
+  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 (error2) {
+      lastError = classifyError(error2);
+      if (isRetryable(void 0, error2) && 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, error2) {
+    if (status && RETRYABLE_SEARCH_CODES.has(status)) return true;
+    if (error2 == null) return false;
+    const message = typeof error2 === "object" && "message" in error2 && typeof error2.message === "string" ? error2.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: error2 } = await executeSearchWithRetry(
+      this.apiKey,
+      searchQueries,
+      (status, err) => this.isRetryable(status, err)
+    );
+    if (error2 || data === void 0) {
+      return {
+        searches: [],
+        totalQueries: queries.length,
+        executionTime: Date.now() - startTime,
+        error: error2 ?? { 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 (error2) {
+        const err = classifyError(error2);
+        if (this.isRetryable(void 0, error2) && 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/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 (error2) {
+      const err = formatKernelError(error2);
+      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(error2) {
+  if (error2 instanceof Kernel.APIError) {
+    return {
+      ...classifyError({ status: error2.status, message: error2.message }),
+      cause: error2.message
+    };
+  }
+  return classifyError(error2);
+}
+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 Logger4 } from "mcp-use";
+var REDDIT_TOKEN_URL = "https://www.reddit.com/api/v1/access_token";
+var REDDIT_API_BASE = "https://oauth.reddit.com";
+var TOKEN_EXPIRY_MS = 55e3;
+var FETCH_LIMIT = 500;
+var cachedToken = null;
+var cachedTokenExpiry = 0;
+var DEBUG_TOKEN_CACHE = process.env.DEBUG_REDDIT === "true";
+var clientLogger = Logger4.get("reddit-client");
+var pendingAuthPromise = null;
+async function fetchRedditJson(sub, id, token, userAgent) {
+  const limit = Math.min(FETCH_LIMIT, 500);
+  const apiUrl = `${REDDIT_API_BASE}/r/${sub}/comments/${id}?sort=top&limit=${limit}&depth=10&raw_json=1`;
+  const res = await fetchWithTimeout(apiUrl, {
+    headers: {
+      "Authorization": `Bearer ${token}`,
+      "User-Agent": userAgent
+    },
+    timeoutMs: 3e4
+  });
+  if (res.status === 429) {
+    const err = new Error("Rate limited by Reddit API");
+    err.status = 429;
+    throw err;
+  }
+  if (res.status === 404) {
+    throw new Error(`Post not found: /r/${sub}/comments/${id}`);
+  }
+  if (!res.ok) {
+    const err = new Error(`Reddit API error: ${res.status}`);
+    err.status = res.status;
+    throw err;
+  }
+  try {
+    return await res.json();
+  } catch {
+    throw new Error("Failed to parse Reddit API response");
+  }
+}
+function parsePostData(postListing, sub) {
+  const p = postListing?.data?.children?.[0]?.data;
+  if (!p) {
+    throw new Error(`Post data not found in response for /r/${sub}`);
+  }
+  return {
+    title: p.title || "Untitled",
+    author: p.author || "[deleted]",
+    subreddit: p.subreddit || sub,
+    body: formatBody(p),
+    score: p.score || 0,
+    commentCount: p.num_comments || 0,
+    url: `https://reddit.com${p.permalink || ""}`,
+    created: new Date((p.created_utc || 0) * 1e3),
+    flair: p.link_flair_text || void 0,
+    isNsfw: p.over_18 || false,
+    isPinned: p.stickied || false
+  };
+}
+function formatBody(p) {
+  if (p.selftext?.trim()) return p.selftext;
+  if (p.is_self) return "";
+  if (p.url) return `**Link:** ${p.url}`;
+  return "";
+}
+var MAX_COMMENT_DEPTH = 15;
+function parseCommentTree(commentListing, opAuthor) {
+  const result = [];
+  const extract = (items, depth = 0) => {
+    if (depth > MAX_COMMENT_DEPTH) return;
+    const sorted = [...items].sort((a, b) => (b.data?.score || 0) - (a.data?.score || 0));
+    for (const c of sorted) {
+      if (c.kind !== "t1" || !c.data?.author || c.data.author === "[deleted]") continue;
+      result.push({
+        author: c.data.author,
+        body: c.data.body || "",
+        score: c.data.score || 0,
+        depth,
+        isOP: c.data.author === opAuthor
+      });
+      if (typeof c.data.replies === "object" && c.data.replies?.data?.children) {
+        extract(c.data.replies.data.children, depth + 1);
+      }
+    }
+  };
+  extract(commentListing?.data?.children || []);
+  return result;
+}
+async function processBatch(client, batchUrls) {
+  const results = /* @__PURE__ */ new Map();
+  let rateLimitHits = 0;
+  const batchResults = await pMapSettled(
+    batchUrls,
+    (url) => client.getPost(url),
+    CONCURRENCY.REDDIT
+  );
+  for (let i = 0; i < batchResults.length; i++) {
+    const result = batchResults[i];
+    if (!result) continue;
+    const url = batchUrls[i] ?? "";
+    if (result.status === "fulfilled") {
+      results.set(url, result.value);
+    } else {
+      const errorMsg = result.reason?.message || String(result.reason);
+      if (errorMsg.includes("429") || errorMsg.includes("rate")) rateLimitHits++;
+      results.set(url, new Error(errorMsg));
+    }
+  }
+  return { results, rateLimitHits };
+}
+var RedditClient = class {
+  constructor(clientId, clientSecret) {
+    this.clientId = clientId;
+    this.clientSecret = clientSecret;
+  }
+  userAgent = `script:${USER_AGENT_VERSION} (by /u/research-powerpack)`;
+  /**
+   * Authenticate with Reddit API with retry logic
+   * Uses module-level token cache and promise deduplication to prevent
+   * concurrent auth calls from firing multiple token requests
+   * Returns null on failure instead of throwing
+   */
+  async auth() {
+    if (cachedToken && Date.now() < cachedTokenExpiry - TOKEN_EXPIRY_MS) {
+      if (DEBUG_TOKEN_CACHE) clientLogger.debug("Token cache HIT");
+      return cachedToken;
+    }
+    if (pendingAuthPromise) {
+      if (DEBUG_TOKEN_CACHE) clientLogger.debug("Auth already in flight, awaiting...");
+      return pendingAuthPromise;
+    }
+    pendingAuthPromise = this.performAuth();
+    try {
+      return await pendingAuthPromise;
+    } finally {
+      pendingAuthPromise = null;
+    }
+  }
+  async performAuth() {
+    if (DEBUG_TOKEN_CACHE) clientLogger.debug("Token cache MISS - authenticating");
+    const credentials = Buffer.from(`${this.clientId}:${this.clientSecret}`).toString("base64");
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        const res = await fetchWithTimeout(REDDIT_TOKEN_URL, {
+          method: "POST",
+          headers: {
+            "Authorization": `Basic ${credentials}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent": this.userAgent
+          },
+          body: "grant_type=client_credentials",
+          timeoutMs: 15e3
+        });
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          mcpLog("error", `Auth failed (${res.status}): ${text}`, "reddit");
+          if (res.status === 401 || res.status === 403) {
+            cachedToken = null;
+            cachedTokenExpiry = 0;
+            return null;
+          }
+          if (res.status >= 500 && attempt < 2) {
+            await sleep(calculateBackoff2(attempt));
+            continue;
+          }
+          return null;
+        }
+        const data = await res.json();
+        if (!data.access_token) {
+          mcpLog("error", "Auth response missing access_token", "reddit");
+          return null;
+        }
+        cachedToken = data.access_token;
+        cachedTokenExpiry = Date.now() + (data.expires_in || 3600) * 1e3;
+        return cachedToken;
+      } catch (error2) {
+        const err = classifyError(error2);
+        mcpLog("error", `Auth error (attempt ${attempt + 1}): ${err.message}`, "reddit");
+        if (err.code === ErrorCode.AUTH_ERROR) {
+          cachedToken = null;
+          cachedTokenExpiry = 0;
+        }
+        if (attempt < 2 && err.retryable) {
+          await sleep(calculateBackoff2(attempt));
+          continue;
+        }
+        return null;
+      }
+    }
+    return null;
+  }
+  parseUrl(url) {
+    const m = url.match(/reddit\.com\/r\/([^\/]+)\/comments\/([a-z0-9]+)/i);
+    return m ? { sub: m[1], id: m[2] } : null;
+  }
+  /**
+   * Get a single Reddit post with comments
+   * Returns PostResult or throws Error (for use with Promise.allSettled)
+   */
+  async getPost(url) {
+    const parsed = this.parseUrl(url);
+    if (!parsed) {
+      throw new Error(`Invalid Reddit URL format: ${url}`);
+    }
+    const token = await this.auth();
+    if (!token) {
+      throw new Error("Reddit authentication failed - check credentials");
+    }
+    let lastError = null;
+    for (let attempt = 0; attempt < REDDIT.RETRY_COUNT; attempt++) {
+      try {
+        const data = await fetchRedditJson(parsed.sub, parsed.id, token, this.userAgent);
+        const [postListing, commentListing] = data;
+        const post = parsePostData(postListing, parsed.sub);
+        const comments = parseCommentTree(commentListing, post.author);
+        return { post, comments, actualComments: post.commentCount };
+      } catch (error2) {
+        lastError = classifyError(error2);
+        const status = error2.status;
+        if (status === 429) {
+          const delay = REDDIT.RETRY_DELAYS[attempt] || 32e3;
+          mcpLog("warning", `Rate limited. Retry ${attempt + 1}/${REDDIT.RETRY_COUNT} after ${delay}ms`, "reddit");
+          await sleep(delay);
+          continue;
+        }
+        if (!lastError.retryable) {
+          throw error2 instanceof Error ? error2 : new Error(lastError.message);
+        }
+        if (attempt < REDDIT.RETRY_COUNT - 1) {
+          const delay = REDDIT.RETRY_DELAYS[attempt] || 2e3;
+          mcpLog("warning", `${lastError.code}: ${lastError.message}. Retry ${attempt + 1}/${REDDIT.RETRY_COUNT}`, "reddit");
+          await sleep(delay);
+        }
+      }
+    }
+    throw new Error(lastError?.message || "Failed to fetch Reddit post after retries");
+  }
+  async batchGetPosts(urls, fetchComments = true, onBatchComplete) {
+    const allResults = /* @__PURE__ */ new Map();
+    let rateLimitHits = 0;
+    const totalBatches = Math.ceil(urls.length / REDDIT.BATCH_SIZE);
+    mcpLog("info", `Fetching ${urls.length} posts in ${totalBatches} batch(es), up to ${FETCH_LIMIT} comments/post`, "reddit");
+    for (let batchNum = 0; batchNum < totalBatches; batchNum++) {
+      const startIdx = batchNum * REDDIT.BATCH_SIZE;
+      const batchUrls = urls.slice(startIdx, startIdx + REDDIT.BATCH_SIZE);
+      mcpLog("info", `Batch ${batchNum + 1}/${totalBatches} (${batchUrls.length} posts)`, "reddit");
+      const batchResult = await processBatch(this, batchUrls);
+      for (const [url, result] of batchResult.results) {
+        allResults.set(url, result);
+      }
+      rateLimitHits += batchResult.rateLimitHits;
+      try {
+        onBatchComplete?.(batchNum + 1, totalBatches, allResults.size);
+      } catch (callbackError) {
+        mcpLog("error", `onBatchComplete callback error: ${callbackError}`, "reddit");
+      }
+      mcpLog("info", `Batch ${batchNum + 1} complete (${allResults.size}/${urls.length})`, "reddit");
+      if (batchNum < totalBatches - 1) {
+        await sleep(500);
+      }
+    }
+    return { results: allResults, batchesProcessed: totalBatches, totalPosts: urls.length, rateLimitHits };
+  }
+};
+
+// 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, error2) {
+  return new ProviderRequestError({
+    provider,
+    operation,
+    error: classifyError(error2)
+  });
+}
+
+// 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: (error2) => providerError("serper", "searchMultiple", error2)
+    }),
+    jinaSearchMultiple: (queries) => Effect.tryPromise({
+      try: () => new JinaClient(env.JINA_API_KEY).searchMultiple([...queries]),
+      catch: (error2) => providerError("jina", "searchMultiple", error2)
+    })
+  };
+});
+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: (error2) => providerError("jina", "convert", error2)
+    })
+  };
+});
+var KernelServiceLive = Layer.sync(KernelService, () => {
+  const client = new KernelClient();
+  return {
+    render: (request) => Effect.tryPromise({
+      try: () => client.render(request),
+      catch: (error2) => providerError("kernel", "render", error2)
+    })
+  };
+});
+function RedditServiceLive(clientId, clientSecret) {
+  return Layer.sync(RedditService, () => {
+    const client = new RedditClient(clientId, clientSecret);
+    return {
+      batchGetPosts: (urls, includeComments) => Effect.tryPromise({
+        try: () => client.batchGetPosts([...urls], includeComments),
+        catch: (error2) => providerError("reddit", "batchGetPosts", error2)
+      })
+    };
+  });
+}
+var LlmServiceLive = Layer.succeed(LlmService, {
+  extractContent: (content, config) => Effect.tryPromise({
+    try: () => processContentWithLLM(content, config, createLLMProcessor()),
+    catch: (error2) => providerError("llm", "extractContent", error2)
+  }),
+  classifySearchResults: (rankedUrls, objective, totalQueries, processor, previousQueries) => Effect.tryPromise({
+    try: () => classifySearchResults(rankedUrls, objective, totalQueries, processor, previousQueries),
+    catch: (error2) => providerError("llm", "classifySearchResults", error2)
+  }),
+  suggestRefineQueriesForRawMode: (rankedUrls, objective, originalQueries, processor) => Effect.tryPromise({
+    try: () => suggestRefineQueriesForRawMode(rankedUrls, objective, originalQueries, processor),
+    catch: (error2) => providerError("llm", "suggestRefineQueriesForRawMode", error2)
+  }),
+  generateResearchBrief: (goal, processor) => Effect.tryPromise({
+    try: () => generateResearchBrief(goal, processor),
+    catch: (error2) => providerError("llm", "generateResearchBrief", error2)
+  })
+});
+
+// src/effect/runtime.ts
+var BaseExternalLive = Layer2.mergeAll(
+  JinaServiceLive,
+  SearchServiceLive,
+  LlmServiceLive
+);
+function runExternalEffect(effect, layer) {
+  return Effect2.runPromise(effect.pipe(Effect2.provide(layer)));
+}
+
+// src/utils/response.ts
+var SECONDS_MS = 1e3;
+var 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`;
+}
+
+// src/tools/mcp-helpers.ts
+import { error, markdown } from "mcp-use/server";
+var NOOP_REPORTER = {
+  async log() {
+  },
+  async progress() {
+  }
+};
+function toolSuccess(content, structuredContent) {
+  return {
+    isError: false,
+    content,
+    structuredContent
+  };
+}
+function toolFailure(content) {
+  return {
+    isError: true,
+    content
+  };
+}
+function createToolReporter(ctx, loggerName) {
+  return {
+    log(level, message) {
+      return ctx.log(level, message, loggerName);
+    },
+    progress(loaded, total, message) {
+      return ctx.reportProgress?.(loaded, total, message) ?? Promise.resolve();
+    }
+  };
+}
+function toToolResponse(result) {
+  if (result.isError) {
+    return error(result.content);
+  }
+  if (result.structuredContent) {
+    return {
+      ...markdown(result.content),
+      structuredContent: result.structuredContent
+    };
+  }
+  return markdown(result.content);
+}
+
+// src/tools/scrape.ts
+var markdownCleaner = new MarkdownCleaner();
+function formatInputValidationError(toolName, issues) {
+  const details = issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.map(String).join(".") : "<root>";
+    return `- ${path}: ${issue.message}`;
+  }).join("\n");
+  return `Invalid ${toolName} input.
+
+${details}`;
+}
+function enhanceExtractionInstruction(instruction) {
+  const base = instruction || "Extract the main content and key information from this page.";
+  return `${SCRAPER.EXTRACTION_PREFIX}
+
+${base}
+
+${SCRAPER.EXTRACTION_SUFFIX}`;
+}
+function cleanFetchedContent(rawContent, url) {
+  try {
+    const readable = extractReadableContent(rawContent, url);
+    const sourceForCleaner = readable.extracted ? readable.content : rawContent;
+    return markdownCleaner.processContent(sourceForCleaner);
+  } catch {
+    return rawContent;
+  }
+}
+function effectErrorMessage(error2) {
+  if (typeof error2 === "object" && error2 !== null) {
+    if ("error" in error2) {
+      const structured = error2.error;
+      if (typeof structured?.message === "string") return structured.message;
+    }
+    if ("message" in error2 && typeof error2.message === "string") {
+      return error2.message;
+    }
+    if ("_tag" in error2 && typeof error2._tag === "string") {
+      return error2._tag;
+    }
+  }
+  return String(error2);
+}
+var REDDIT_HOST = /(?:^|\.)reddit\.com$/i;
+var REDDIT_POST_PERMALINK = /\/r\/[^/]+\/comments\/[a-z0-9]+/i;
+function isRedditUrl(url) {
+  try {
+    const u = new URL(url);
+    return REDDIT_HOST.test(u.hostname);
+  } catch {
+    return false;
+  }
+}
+function isRedditPostPermalink(url) {
+  try {
+    const u = new URL(url);
+    return REDDIT_HOST.test(u.hostname) && REDDIT_POST_PERMALINK.test(u.pathname);
+  } catch {
+    return false;
+  }
+}
+function createScrapeErrorResponse(code, message, startTime, toolName = "raw-scrape-links", retryable = false, alternatives) {
+  return toolFailure(
+    `${formatError({
+      code,
+      message,
+      retryable,
+      toolName,
+      howToFix: code === "NO_URLS" ? ["Provide at least one valid URL"] : void 0,
+      alternatives
+    })}
+
+Execution time: ${formatDuration(Date.now() - startTime)}`
+  );
+}
+function partitionUrls(urls) {
+  const webInputs = [];
+  const redditInputs = [];
+  const documentInputs = [];
+  const invalidEntries = [];
+  for (let i = 0; i < urls.length; i++) {
+    const url = urls[i];
+    try {
+      new URL(url);
+    } catch {
+      invalidEntries.push({ url, origIndex: i });
+      continue;
+    }
+    if (isDocumentUrl(url)) {
+      documentInputs.push({ url, origIndex: i });
+    } else if (isRedditUrl(url)) {
+      redditInputs.push({ url, origIndex: i });
+    } else {
+      webInputs.push({ url, origIndex: i });
+    }
+  }
+  return { webInputs, redditInputs, documentInputs, invalidEntries };
+}
+function formatJinaFailure(url, jinaError, proxyError) {
+  if (proxyError) {
+    return `## ${url}
+
+\u274C Jina Reader failed. Direct: ${jinaError}. Scrape.do proxy: ${proxyError}.`;
+  }
+  return `## ${url}
+
+\u274C Document conversion failed: ${jinaError}`;
+}
+function jinaResultError(result) {
+  if (result.error || result.statusCode < 200 || result.statusCode >= 300) {
+    return result.error?.message || `HTTP ${result.statusCode}`;
+  }
+  const quality = assessMarkdownQuality(result.content);
+  if (quality.weak) {
+    return `Weak Jina markdown (${quality.reason})`;
+  }
+  return null;
+}
+function canTryKernel(input, directError) {
+  if (isDocumentUrl(input.url)) return false;
+  if (!directError) return true;
+  if (directError.code === ErrorCode.NOT_FOUND || directError.code === ErrorCode.INVALID_INPUT) {
+    return false;
+  }
+  return true;
+}
+function formatJinaFirstFailure(input) {
+  if (input.proxyError) {
+    return formatJinaFailure(input.url, input.directError ?? "Unknown direct failure", input.proxyError);
+  }
+  return formatJinaFailure(input.url, input.directError ?? "Unknown direct failure");
+}
+async function fetchJinaFirstBranch(inputs, kernelEnabled, scrapeDoProxyUrl) {
+  if (inputs.length === 0) {
+    return { successItems: [], failedContents: [], metrics: { successful: 0, failed: 0, totalCredits: 0 } };
+  }
+  mcpLog(
+    "info",
+    `[concurrency] jina direct branch: converting ${inputs.length} URL(s) with limit=${CONCURRENCY.JINA_READER}`,
+    "scrape"
+  );
+  const directResults = await runExternalEffect(
+    Effect3.gen(function* () {
+      const jina = yield* JinaService;
+      return yield* Effect3.forEach(
+        inputs,
+        (input) => jina.convert({ url: input.url, timeoutSeconds: 15, allowProxyRetry: false }).pipe(
+          Effect3.timeoutFail({
+            duration: "20 seconds",
+            onTimeout: () => new ProviderTimeoutError({
+              provider: "jina",
+              operation: "convert:direct",
+              durationMs: 2e4
+            })
+          }),
+          Effect3.either
+        ),
+        { concurrency: CONCURRENCY.JINA_READER }
+      );
+    }),
+    JinaServiceLive
+  );
+  const successItems = [];
+  const failedContents = [];
+  const proxyInputs = [];
+  const kernelInputs = [];
+  let successful = 0;
+  let failed = 0;
+  const enqueueFailure = (input) => {
+    if (kernelEnabled && canTryKernel(input, input.directStructuredError)) {
+      kernelInputs.push({
+        url: input.url,
+        origIndex: input.origIndex,
+        proxyError: input.proxyError ? `Scrape.do proxy: ${input.proxyError}` : void 0,
+        jinaError: input.directError
+      });
+      return;
+    }
+    failed++;
+    failedContents.push({ index: input.origIndex, content: formatJinaFirstFailure(input) });
+  };
+  for (let i = 0; i < directResults.length; i++) {
+    const settled = directResults[i];
+    const input = inputs[i];
+    if (!settled) {
+      proxyInputs.push({ ...input, directError: "No result returned" });
+      continue;
+    }
+    if (Either.isLeft(settled)) {
+      const reason = effectErrorMessage(settled.left);
+      proxyInputs.push({ ...input, directError: reason });
+      continue;
+    }
+    const directError = jinaResultError(settled.right);
+    if (!directError) {
+      successful++;
+      successItems.push({ url: input.url, content: settled.right.content, index: input.origIndex, rawContent: settled.right.content });
+      continue;
+    }
+    const structuredError = settled.right.error;
+    if (structuredError && isTerminalReaderError(structuredError)) {
+      enqueueFailure({ ...input, directError, directStructuredError: structuredError });
+      continue;
+    }
+    proxyInputs.push({ ...input, directError, directStructuredError: structuredError });
+  }
+  if (proxyInputs.length > 0) {
+    if (!scrapeDoProxyUrl) {
+      for (const input of proxyInputs) {
+        enqueueFailure({ ...input, proxyError: "SCRAPEDO_API_KEY is not configured" });
+      }
+    } else {
+      mcpLog(
+        "info",
+        `[concurrency] jina scrape.do proxy branch: retrying ${proxyInputs.length} URL(s) with limit=${CONCURRENCY.JINA_READER}`,
+        "scrape"
+      );
+      const proxyResults = await runExternalEffect(
+        Effect3.gen(function* () {
+          const jina = yield* JinaService;
+          return yield* Effect3.forEach(
+            proxyInputs,
+            (input) => jina.convert({
+              url: input.url,
+              timeoutSeconds: 15,
+              proxyUrl: scrapeDoProxyUrl,
+              noCache: true,
+              allowProxyRetry: false
+            }).pipe(
+              Effect3.timeoutFail({
+                duration: "20 seconds",
+                onTimeout: () => new ProviderTimeoutError({
+                  provider: "jina",
+                  operation: "convert:proxy",
+                  durationMs: 2e4
+                })
+              }),
+              Effect3.either
+            ),
+            { concurrency: CONCURRENCY.JINA_READER }
+          );
+        }),
+        JinaServiceLive
+      );
+      for (let i = 0; i < proxyResults.length; i++) {
+        const settled = proxyResults[i];
+        const input = proxyInputs[i];
+        if (!settled) {
+          enqueueFailure({ ...input, proxyError: "No result returned" });
+          continue;
+        }
+        if (Either.isLeft(settled)) {
+          enqueueFailure({ ...input, proxyError: effectErrorMessage(settled.left) });
+          continue;
+        }
+        const proxyError = jinaResultError(settled.right);
+        if (!proxyError) {
+          successful++;
+          successItems.push({ url: input.url, content: settled.right.content, index: input.origIndex, rawContent: settled.right.content });
+          continue;
+        }
+        enqueueFailure({ ...input, proxyError });
+      }
+    }
+  }
+  if (kernelInputs.length > 0 && kernelEnabled) {
+    const kernelPhase = await fetchKernelBranch(kernelInputs);
+    successItems.push(...kernelPhase.successItems);
+    failedContents.push(...kernelPhase.failedContents);
+    successful += kernelPhase.metrics.successful;
+    failed += kernelPhase.metrics.failed;
+  }
+  return { successItems, failedContents, metrics: { successful, failed, totalCredits: 0 } };
+}
+function formatKernelFailure(url, kernelError, proxyError, jinaError) {
+  const layers = [
+    jinaError ? `Jina Reader: ${jinaError}` : void 0,
+    proxyError ? proxyError : void 0,
+    `Kernel: ${kernelError}`
+  ].filter((line) => Boolean(line));
+  return `## ${url}
+
+\u274C All scrape providers failed. ${layers.join(". ")}.`;
+}
+async function fetchKernelBranch(inputs) {
+  if (inputs.length === 0) {
+    return { successItems: [], failedContents: [], metrics: { successful: 0, failed: 0, totalCredits: 0 } };
+  }
+  mcpLog(
+    "info",
+    `[concurrency] kernel branch: rendering ${inputs.length} URL(s) with limit=${CONCURRENCY.KERNEL}`,
+    "scrape"
+  );
+  const results = await runExternalEffect(
+    Effect3.gen(function* () {
+      const kernel = yield* KernelService;
+      return yield* Effect3.forEach(
+        inputs,
+        (input) => kernel.render({ url: input.url, timeoutSeconds: 15 }).pipe(
+          Effect3.timeoutFail({
+            duration: "25 seconds",
+            onTimeout: () => new ProviderTimeoutError({
+              provider: "kernel",
+              operation: "render",
+              durationMs: 25e3
+            })
+          }),
+          Effect3.either
+        ),
+        { concurrency: CONCURRENCY.KERNEL }
+      );
+    }),
+    KernelServiceLive
+  );
+  const successItems = [];
+  const failedContents = [];
+  let successful = 0;
+  let failed = 0;
+  for (let i = 0; i < results.length; i++) {
+    const settled = results[i];
+    const input = inputs[i];
+    if (!settled) {
+      failed++;
+      failedContents.push({
+        index: input.origIndex,
+        content: formatKernelFailure(input.url, "No result returned", input.proxyError, input.jinaError)
+      });
+      continue;
+    }
+    if (Either.isLeft(settled)) {
+      failed++;
+      const reason = effectErrorMessage(settled.left);
+      failedContents.push({
+        index: input.origIndex,
+        content: formatKernelFailure(input.url, reason, input.proxyError, input.jinaError)
+      });
+      continue;
+    }
+    const result = settled.right;
+    if (result.error || result.statusCode < 200 || result.statusCode >= 300) {
+      failed++;
+      const errorMsg = result.error?.message || `HTTP ${result.statusCode}`;
+      failedContents.push({
+        index: input.origIndex,
+        content: formatKernelFailure(input.url, errorMsg, input.proxyError, input.jinaError)
+      });
+      continue;
+    }
+    const content = cleanFetchedContent(result.content, result.finalUrl ?? input.url);
+    const quality = assessMarkdownQuality(content);
+    if (quality.weak) {
+      failed++;
+      failedContents.push({
+        index: input.origIndex,
+        content: formatKernelFailure(
+          input.url,
+          `Weak Kernel markdown (${quality.reason})`,
+          input.proxyError,
+          input.jinaError
+        )
+      });
+      continue;
+    }
+    successful++;
+    const finalUrl = result.finalUrl ?? input.url;
+    successItems.push({ url: finalUrl, content, index: input.origIndex, rawContent: content });
+  }
+  return { successItems, failedContents, metrics: { successful, failed, totalCredits: 0 } };
+}
+function formatRedditPostAsMarkdown(result) {
+  const { post, comments } = result;
+  const lines = [];
+  lines.push(`# ${post.title}`);
+  lines.push("");
+  lines.push(`**r/${post.subreddit}** \u2022 u/${post.author} \u2022 \u2B06\uFE0F ${post.score} \u2022 \u{1F4AC} ${post.commentCount} comments`);
+  lines.push(`\u{1F517} ${post.url}`);
+  lines.push("");
+  if (post.body) {
+    lines.push("## Post content");
+    lines.push("");
+    lines.push(post.body);
+    lines.push("");
+  }
+  if (comments.length > 0) {
+    lines.push(`## Top comments (${comments.length} total)`);
+    lines.push("");
+    for (const c of comments) {
+      const indent = "  ".repeat(c.depth);
+      const op = c.isOP ? " **[OP]**" : "";
+      const score = c.score >= 0 ? `+${c.score}` : `${c.score}`;
+      lines.push(`${indent}- **u/${c.author}**${op} _(${score})_`);
+      for (const line of c.body.split("\n")) {
+        lines.push(`${indent}  ${line}`);
+      }
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+async function fetchRedditBranch(inputs) {
+  if (inputs.length === 0) {
+    return { successItems: [], failedContents: [], metrics: { successful: 0, failed: 0, totalCredits: 0 } };
+  }
+  const env = parseEnv();
+  if (!env.REDDIT_CLIENT_ID || !env.REDDIT_CLIENT_SECRET) {
+    const failedContents2 = inputs.map(
+      (i) => ({
+        index: i.origIndex,
+        content: `## ${i.url}
+
+\u274C Reddit URL detected, but Reddit API is not configured. Set \`REDDIT_CLIENT_ID\` and \`REDDIT_CLIENT_SECRET\` in the server env to enable threaded Reddit scraping.`
+      })
+    );
+    return {
+      successItems: [],
+      failedContents: failedContents2,
+      metrics: { successful: 0, failed: inputs.length, totalCredits: 0 }
+    };
+  }
+  const [postInputs, nonPermalinks] = inputs.reduce(
+    ([posts, rest], input) => {
+      if (isRedditPostPermalink(input.url)) posts.push(input);
+      else rest.push(input);
+      return [posts, rest];
+    },
+    [[], []]
+  );
+  const nonPermalinkFailed = nonPermalinks.map(
+    (i) => ({
+      index: i.origIndex,
+      content: `## ${i.url}
+
+\u274C Only Reddit post permalinks (/r/<sub>/comments/<id>/...) are supported. Use raw-web-search with explicit Reddit permalink probes or smart-web-search with scope:"reddit" to discover post permalinks first.`
+    })
+  );
+  if (postInputs.length === 0) {
+    return {
+      successItems: [],
+      failedContents: nonPermalinkFailed,
+      metrics: { successful: 0, failed: nonPermalinks.length, totalCredits: 0 }
+    };
+  }
+  mcpLog("info", `[concurrency] reddit branch: fetching ${postInputs.length} post(s) with limit=${CONCURRENCY.REDDIT}`, "scrape");
+  const urls = postInputs.map((i) => i.url);
+  const batchResult = await runExternalEffect(
+    Effect3.gen(function* () {
+      const reddit = yield* RedditService;
+      return yield* reddit.batchGetPosts(urls, true).pipe(
+        Effect3.timeoutFail({
+          duration: "60 seconds",
+          onTimeout: () => new ProviderTimeoutError({
+            provider: "reddit",
+            operation: "batchGetPosts",
+            durationMs: 6e4
+          })
+        })
+      );
+    }),
+    RedditServiceLive(env.REDDIT_CLIENT_ID, env.REDDIT_CLIENT_SECRET)
+  );
+  const urlToIndex = new Map(postInputs.map((i) => [i.url, i.origIndex]));
+  const successItems = [];
+  const failedContents = [...nonPermalinkFailed];
+  let successful = 0;
+  let failed = nonPermalinks.length;
+  for (const [url, result] of batchResult.results) {
+    const origIndex = urlToIndex.get(url) ?? -1;
+    if (result instanceof Error) {
+      failed++;
+      failedContents.push({ index: origIndex, content: `## ${url}
+
+\u274C Reddit fetch failed: ${result.message}` });
+      continue;
+    }
+    successful++;
+    const md = formatRedditPostAsMarkdown(result);
+    successItems.push({ url, content: md, index: origIndex, rawContent: md });
+  }
+  return { successItems, failedContents, metrics: { successful, failed, totalCredits: 0 } };
+}
+var TERSE_LLM_FAILURE_RE = /^\s*##\s*Matches\s*\n+\s*_Page did not load:\s*([a-z0-9_-]+)_\s*\.?\s*$/i;
+var RAW_FALLBACK_CHAR_CAP = 4e3;
+function detectTerseFailure(llmOutput) {
+  const m = llmOutput.trim().match(TERSE_LLM_FAILURE_RE);
+  return m ? m[1] : null;
+}
+function mergeLlmWithRawFallback(llmOutput, rawContent) {
+  const reason = detectTerseFailure(llmOutput);
+  if (!reason) return llmOutput;
+  const trimmed = rawContent?.trim();
+  if (!trimmed) return llmOutput;
+  const snippet = trimmed.length > RAW_FALLBACK_CHAR_CAP ? trimmed.slice(0, RAW_FALLBACK_CHAR_CAP) + "\n\n\u2026[raw truncated]" : trimmed;
+  return `${llmOutput.trim()}
+
+## Raw content (LLM flagged page as ${reason})
+
+${snippet}`;
+}
+async function processItemsWithLlm(successItems, enhancedInstruction, llmProcessor, reporter) {
+  let llmErrors = 0;
+  if (!enhancedInstruction) {
+    if (successItems.length > 0) {
+      mcpLog("info", "Raw mode: extract omitted \u2014 returning cleaned scraped content without LLM pass", "scrape");
+    }
+    return { items: successItems, llmErrors, llmAttempted: 0 };
+  }
+  if (!llmProcessor || successItems.length === 0) {
+    if (!llmProcessor && successItems.length > 0) {
+      mcpLog("warning", "LLM unavailable (LLM_API_KEY not set). Returning raw scraped content.", "scrape");
+      void reporter.log("warning", "llm_extractor_unreachable: planner not configured; raw scraped content returned");
+    }
+    return { items: successItems, llmErrors, llmAttempted: 0 };
+  }
+  mcpLog("info", `[concurrency] llm extraction: fanning out ${successItems.length} item(s) with limit=${CONCURRENCY.LLM_EXTRACTION}`, "scrape");
+  const llmResults = await runExternalEffect(
+    Effect3.gen(function* () {
+      const llm = yield* LlmService;
+      return yield* Effect3.forEach(
+        successItems,
+        (item) => llm.extractContent(
+          item.content,
+          { enabled: true, extract: enhancedInstruction, url: item.url }
+        ).pipe(
+          Effect3.timeoutFail({
+            duration: "155 seconds",
+            onTimeout: () => new ProviderTimeoutError({
+              provider: "llm",
+              operation: "extractContent",
+              durationMs: 155e3
+            })
+          }),
+          Effect3.either,
+          Effect3.map((result) => ({ item, result }))
+        ),
+        { concurrency: CONCURRENCY.LLM_EXTRACTION }
+      );
+    }),
+    LlmServiceLive
+  );
+  const processedItems = llmResults.map(({ item, result }) => {
+    mcpLog("debug", `LLM extracting ${item.url}...`, "scrape");
+    if (Either.isLeft(result)) {
+      llmErrors++;
+      const errorMessage = effectErrorMessage(result.left);
+      mcpLog("warning", `LLM extraction failed for ${item.url}: ${errorMessage}`, "scrape");
+      void reporter.log("warning", `llm_extractor_unreachable: ${item.url} \u2014 ${errorMessage}`);
+      const raw2 = item.rawContent?.trim();
+      const rawSnippet2 = raw2 ? `
+
+## Raw content (unextracted)
+
+${raw2.length > RAW_FALLBACK_CHAR_CAP ? raw2.slice(0, RAW_FALLBACK_CHAR_CAP) + "\n\n...[raw truncated]" : raw2}` : "";
+      return {
+        ...item,
+        content: `\u274C LLM extraction failed: ${errorMessage}${rawSnippet2}`
+      };
+    }
+    const llmResult = result.right;
+    if (llmResult.processed) {
+      const merged = mergeLlmWithRawFallback(llmResult.content, item.rawContent);
+      if (merged !== llmResult.content) {
+        mcpLog("warning", `LLM emitted terse escape line for ${item.url} \u2014 preserved raw fallback`, "scrape");
+        void reporter.log("warning", `llm_terse_escape: ${item.url} \u2014 preserving raw fallback`);
+      }
+      return { ...item, content: merged };
+    }
+    llmErrors++;
+    mcpLog("warning", `LLM extraction failed for ${item.url}: ${llmResult.error || "unknown reason"}`, "scrape");
+    void reporter.log("warning", `llm_extractor_unreachable: ${item.url} \u2014 ${llmResult.error || "unknown reason"}`);
+    const raw = item.rawContent?.trim();
+    const rawSnippet = raw ? `
+
+## Raw content (unextracted)
+
+${raw.length > RAW_FALLBACK_CHAR_CAP ? raw.slice(0, RAW_FALLBACK_CHAR_CAP) + "\n\n...[raw truncated]" : raw}` : "";
+    return {
+      ...item,
+      content: `\u274C LLM extraction failed: ${llmResult.error || "unknown reason"}${rawSnippet}`
+    };
+  });
+  return { items: processedItems, llmErrors, llmAttempted: successItems.length };
+}
+function assembleContentEntries(successItems, failedContents) {
+  const successEntries = successItems.map((item) => {
+    let content = item.content;
+    try {
+      content = removeMetaTags(content);
+    } catch {
+    }
+    return { index: item.index, content: `## ${item.url}
+
+${content}` };
+  });
+  return [...failedContents, ...successEntries].sort((a, b) => a.index - b.index).map((entry) => entry.content);
+}
+function buildScrapeResponse(params, contents, metrics, llmErrors, executionTime, llmAccounting) {
+  const llmExtras = {};
+  if (llmAccounting.llmAttempted > 0) {
+    const ok = llmAccounting.llmAttempted - llmErrors;
+    llmExtras["LLM extraction"] = `${ok}/${llmAccounting.llmAttempted} succeeded`;
+    if (!llmAccounting.llmSucceeded) {
+      llmExtras["LLM credit"] = "0 charged (no extraction produced)";
+    }
+  } else if (llmErrors > 0) {
+    llmExtras["LLM extraction failures"] = llmErrors;
+  }
+  const batchHeader = formatBatchHeader({
+    title: `Scraped Content (${params.urls.length} URLs)`,
+    totalItems: params.urls.length,
+    successful: metrics.successful,
+    failed: metrics.failed,
+    extras: {
+      "Credits used": metrics.totalCredits,
+      ...llmExtras
+    }
+  });
+  const formattedContent = formatSuccess({
+    title: "Scraping Complete",
+    summary: batchHeader,
+    data: contents.join("\n\n---\n\n"),
+    metadata: {
+      "Execution time": formatDuration(executionTime)
+    }
+  });
+  return formattedContent;
+}
+async function handleScrapeLinksMode(params, reporter = NOOP_REPORTER) {
+  const startTime = Date.now();
+  if (!params.urls || params.urls.length === 0) {
+    return createScrapeErrorResponse("NO_URLS", "No URLs provided", startTime, params.toolName);
+  }
+  if (params.smart && !createLLMProcessor()) {
+    return toolFailure(getMissingEnvMessage("llmExtraction"));
+  }
+  const { webInputs, redditInputs, documentInputs, invalidEntries } = partitionUrls(params.urls);
+  const validCount = webInputs.length + redditInputs.length + documentInputs.length;
+  await reporter.log(
+    "info",
+    `Partitioned ${params.urls.length} URL(s): ${webInputs.length} web, ${redditInputs.length} reddit, ${documentInputs.length} document, ${invalidEntries.length} invalid`
+  );
+  if (validCount === 0) {
+    return createScrapeErrorResponse(
+      "INVALID_URLS",
+      `All ${params.urls.length} URLs are invalid`,
+      startTime,
+      params.toolName,
+      false,
+      [
+        "raw-web-search(keywords=[...]) \u2014 search for valid URLs first, then scrape the results"
+      ]
+    );
+  }
+  mcpLog(
+    "info",
+    `Starting ${params.toolName}: ${webInputs.length} web + ${redditInputs.length} reddit + ${documentInputs.length} document URL(s)`,
+    "scrape"
+  );
+  await reporter.progress(15, 100, "Preparing scrape clients");
+  let kernelEnabled;
+  let scrapeDoProxyUrl;
+  try {
+    const env = parseEnv();
+    kernelEnabled = getCapabilities().kernel;
+    scrapeDoProxyUrl = env.SCRAPER_API_KEY ? buildScrapeDoProxyUrl(env.SCRAPER_API_KEY) : void 0;
+  } catch (error2) {
+    const err = classifyError(error2);
+    return createScrapeErrorResponse(
+      "CLIENT_INIT_FAILED",
+      `Failed to initialize scrape providers: ${err.message}`,
+      startTime,
+      params.toolName,
+      false,
+      [
+        'raw-web-search(keywords=["topic key findings", "topic summary"]) \u2014 search instead of scraping'
+      ]
+    );
+  }
+  const enhancedInstruction = params.smart ? enhanceExtractionInstruction(params.extract) : void 0;
+  await reporter.progress(35, 100, "Fetching page content");
+  const jinaInputs = [...webInputs, ...documentInputs];
+  const [jinaPhase, redditPhase] = await Promise.all([
+    fetchJinaFirstBranch(jinaInputs, kernelEnabled, scrapeDoProxyUrl),
+    fetchRedditBranch(redditInputs)
+  ]);
+  const successItems = [
+    ...jinaPhase.successItems,
+    ...redditPhase.successItems
+  ];
+  const invalidFailed = invalidEntries.map(
+    ({ url, origIndex }) => ({ index: origIndex, content: `## ${url}
+
+\u274C Invalid URL format` })
+  );
+  const failedContents = [
+    ...invalidFailed,
+    ...jinaPhase.failedContents,
+    ...redditPhase.failedContents
+  ];
+  const metrics = {
+    successful: jinaPhase.metrics.successful + redditPhase.metrics.successful,
+    failed: invalidEntries.length + jinaPhase.metrics.failed + redditPhase.metrics.failed,
+    totalCredits: 0
+  };
+  await reporter.log("info", `Fetched ${metrics.successful} page(s), ${metrics.failed} failed`);
+  if (successItems.length > 0) {
+    await reporter.progress(80, 100, "Running LLM extraction over fetched pages");
+  }
+  const { items: processedItems, llmErrors, llmAttempted } = await processItemsWithLlm(
+    successItems,
+    enhancedInstruction,
+    createLLMProcessor(),
+    reporter
+  );
+  const contents = assembleContentEntries(processedItems, failedContents);
+  const executionTime = Date.now() - startTime;
+  mcpLog(
+    "info",
+    `Completed: ${metrics.successful} successful, ${metrics.failed} failed, ${metrics.totalCredits} credits used`,
+    "scrape"
+  );
+  const llmSucceeded = llmAttempted > 0 && llmErrors < llmAttempted;
+  const content = buildScrapeResponse(
+    params,
+    contents,
+    metrics,
+    llmErrors,
+    executionTime,
+    { llmAttempted, llmSucceeded }
+  );
+  if (metrics.successful === 0 && metrics.failed > 0) {
+    return toolFailure(content);
+  }
+  if (params.smart && llmAttempted > 0 && llmErrors === llmAttempted) {
+    return toolFailure(content);
+  }
+  return toolSuccess(content);
+}
+function handleRawScrapeLinks(params, reporter = NOOP_REPORTER) {
+  return handleScrapeLinksMode({ ...params, smart: false, toolName: "raw-scrape-links" }, reporter);
+}
+function handleSmartScrapeLinks(params, reporter = NOOP_REPORTER) {
+  return handleScrapeLinksMode({ ...params, smart: true, toolName: "smart-scrape-links" }, reporter);
+}
+function registerScrapeLinksTools(server) {
+  server.tool(
+    {
+      name: "raw-scrape-links",
+      title: "Raw Scrape Links",
+      description: "Fetch URLs in parallel and return full markdown directly. Input is only `urls` (1\u201350). Reddit post permalinks route through the Reddit API with threaded comments. Non-Reddit URLs use Jina Reader first, then Jina Reader with Scrape.do proxy mode when SCRAPEDO_API_KEY is configured, then optional Kernel browser rendering for web pages. Use this for full source capture, Reddit comment harvesting, and raw evidence before synthesis.",
+      schema: rawScrapeLinksParamsSchema,
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: true
+      }
+    },
+    async (args, ctx) => {
+      const parsed = rawScrapeLinksParamsSchema.safeParse(args);
+      if (!parsed.success) {
+        return toToolResponse(toolFailure(formatInputValidationError("raw-scrape-links", parsed.error.issues)));
+      }
+      const reporter = createToolReporter(ctx, "raw-scrape-links");
+      const result = await handleRawScrapeLinks(parsed.data, reporter);
+      await reporter.progress(100, 100, result.isError ? "Scrape failed" : "Scrape complete");
+      return toToolResponse(result);
+    }
+  );
+  server.tool(
+    {
+      name: "smart-scrape-links",
+      title: "Smart Scrape Links",
+      description: "Fetch URLs in parallel, then always run per-URL LLM extraction. Input is `urls` (1\u201350) plus required `extract`. Reddit post permalinks route through the Reddit API with threaded comments. Non-Reddit URLs use Jina Reader first, then Jina Reader with Scrape.do proxy mode when SCRAPEDO_API_KEY is configured, then optional Kernel browser rendering for web pages. Each extracted page returns markdown sections such as `## Source`, `## Matches`, `## Not found`, and `## Follow-up signals`.",
+      schema: smartScrapeLinksParamsSchema,
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: true
+      }
+    },
+    async (args, ctx) => {
+      const parsed = smartScrapeLinksParamsSchema.safeParse(args);
+      if (!parsed.success) {
+        return toToolResponse(toolFailure(formatInputValidationError("smart-scrape-links", parsed.error.issues)));
+      }
+      const reporter = createToolReporter(ctx, "smart-scrape-links");
+      const result = await handleSmartScrapeLinks(parsed.data, reporter);
+      await reporter.progress(100, 100, result.isError ? "Scrape failed" : "Scrape complete");
+      return toToolResponse(result);
+    }
+  );
+}
+
+// src/tools/search.ts
+import { Effect as Effect4 } from "effect";
+
+// src/utils/url-aggregator.ts
+var MIN_BEYOND_TOP10_WEIGHT = 0;
+var BEYOND_TOP10_DECAY = 0.5;
+var BEYOND_TOP10_BASE = 10;
+var DEFAULT_MIN_CONSENSUS_URLS = 5;
+var HIGH_CONSENSUS_THRESHOLD = 4;
+var MAX_ALT_SNIPPETS = 3;
+var MAX_CONSISTENCY_PENALTY = 0.15;
+var CONSISTENCY_STDDEV_SCALE = 5;
+function computePositionStats(positions) {
+  if (positions.length <= 1) {
+    return { mean: positions[0] ?? 0, stdDev: 0, consistencyMultiplier: 1 };
+  }
+  const mean = positions.reduce((a, b) => a + b, 0) / positions.length;
+  const variance = positions.reduce((sum, p) => sum + (p - mean) ** 2, 0) / (positions.length - 1);
+  const stdDev = Math.sqrt(variance);
+  const consistencyMultiplier = 1 - MAX_CONSISTENCY_PENALTY * Math.min(stdDev / CONSISTENCY_STDDEV_SCALE, 1);
+  return { mean, stdDev, consistencyMultiplier };
+}
+function getCtrWeight(position) {
+  if (position >= 1 && position <= 10) {
+    return CTR_WEIGHTS[position] ?? 0;
+  }
+  return Math.max(MIN_BEYOND_TOP10_WEIGHT, BEYOND_TOP10_BASE - (position - BEYOND_TOP10_BASE) * BEYOND_TOP10_DECAY);
+}
+function aggregateResults(searches) {
+  const urlMap = /* @__PURE__ */ new Map();
+  for (const search of searches) {
+    for (const result of search.results) {
+      const normalizedUrl = normalizeUrl(result.link);
+      const existing = urlMap.get(normalizedUrl);
+      if (existing) {
+        existing.frequency += 1;
+        existing.positions.push(result.position);
+        existing.queries.push(search.query);
+        const prevBest = existing.bestPosition;
+        existing.bestPosition = Math.min(existing.bestPosition, result.position);
+        existing.totalScore += getCtrWeight(result.position);
+        if (result.snippet && existing.allSnippets.length < MAX_ALT_SNIPPETS && !existing.allSnippets.some((s) => s === result.snippet)) {
+          existing.allSnippets.push(result.snippet);
+        }
+        if (result.position < prevBest) {
+          existing.title = result.title;
+          existing.snippet = result.snippet;
+        }
+      } else {
+        urlMap.set(normalizedUrl, {
+          url: result.link,
+          title: result.title,
+          snippet: result.snippet,
+          allSnippets: result.snippet ? [result.snippet] : [],
+          frequency: 1,
+          positions: [result.position],
+          queries: [search.query],
+          bestPosition: result.position,
+          totalScore: getCtrWeight(result.position)
+        });
+      }
+    }
+  }
+  return urlMap;
+}
+function normalizeUrl(url) {
+  try {
+    const parsed = new URL(url);
+    let host = parsed.hostname.replace(/^www\./, "");
+    let path = parsed.pathname.replace(/\/$/, "") || "/";
+    return `${host}${path}${parsed.search}`.toLowerCase();
+  } catch {
+    return url.toLowerCase().replace(/\/$/, "");
+  }
+}
+function countByFrequency(urlMap, minFrequency) {
+  let count = 0;
+  for (const url of urlMap.values()) {
+    if (url.frequency >= minFrequency) count++;
+  }
+  return count;
+}
+function calculateWeightedScores(urls, consensusThreshold, totalQueries) {
+  if (urls.length === 0) return [];
+  const scored = urls.map((url) => {
+    const stats = computePositionStats(url.positions);
+    const compositeScore = url.totalScore * stats.consistencyMultiplier;
+    return { url, compositeScore, stats };
+  });
+  scored.sort((a, b) => b.compositeScore - a.compositeScore);
+  const maxScore = scored[0].compositeScore;
+  return scored.map(({ url, compositeScore, stats }, index) => ({
+    url: url.url,
+    title: url.title,
+    snippet: url.snippet,
+    allSnippets: url.allSnippets,
+    rank: index + 1,
+    score: maxScore > 0 ? compositeScore / maxScore * 100 : 0,
+    frequency: url.frequency,
+    positions: url.positions,
+    queries: url.queries,
+    bestPosition: url.bestPosition,
+    isConsensus: url.frequency >= consensusThreshold,
+    coverageRatio: totalQueries > 0 ? url.frequency / totalQueries : 0,
+    positionStdDev: stats.stdDev,
+    consistencyMultiplier: stats.consistencyMultiplier
+  }));
+}
+var COVERAGE_TABLE_MAX_ROWS = 20;
+function consistencyLabel(stdDev, frequency) {
+  if (frequency <= 1) return "n/a";
+  if (stdDev < 1.5) return "high";
+  if (stdDev < 3.5) return "medium";
+  return "variable";
+}
+function generateUnifiedOutput(rankedUrls, allQueries, queryResults, totalUniqueUrls, frequencyThreshold, thresholdNote, verbose = false) {
+  const lines = [];
+  const consensusCount = rankedUrls.filter((u) => u.isConsensus).length;
+  lines.push(`## Web Search Results (${allQueries.length} queries, ${totalUniqueUrls} unique URLs)`);
+  lines.push("");
+  if (thresholdNote) {
+    lines.push(`> ${thresholdNote}`);
+    lines.push("");
+  }
+  const consensusActive = frequencyThreshold > 1;
+  for (const url of rankedUrls) {
+    const consensusTag = consensusActive && url.frequency >= HIGH_CONSENSUS_THRESHOLD ? " CONSENSUS+++" : consensusActive && url.isConsensus ? " CONSENSUS" : "";
+    const coveragePct = Math.round(url.coverageRatio * 100);
+    const consistency = consistencyLabel(url.positionStdDev, url.frequency);
+    lines.push(`**${url.rank}. [${url.title}](${url.url})**${consensusTag}`);
+    const showRowMetadata = verbose || allQueries.length > 1 && url.frequency > 1 || allQueries.length === 1;
+    if (showRowMetadata) {
+      const parts = [
+        `Score: ${url.score.toFixed(1)}`,
+        `Seen in: ${url.frequency}/${allQueries.length} queries (${coveragePct}%)`,
+        `Best pos: #${url.bestPosition}`
+      ];
+      if (url.frequency > 1) {
+        parts.push(`Consistency: ${consistency}`);
+      }
+      lines.push(parts.join(" | "));
+    }
+    if (url.queries.length > 1 || verbose) {
+      lines.push(`Queries: ${url.queries.map((q) => `"${q}"`).join(", ")}`);
+    }
+    lines.push(`> ${url.snippet}`);
+    if (url.allSnippets.length > 1) {
+      const alts = url.allSnippets.filter((s) => s !== url.snippet).slice(0, 3).map((s) => s.length > 100 ? s.slice(0, 97) + "..." : s);
+      if (alts.length > 0) {
+        lines.push(`Alt: ${alts.map((s) => `"${s}"`).join(" | ")}`);
+      }
+    }
+    lines.push("");
+  }
+  lines.push("---");
+  if (allQueries.length <= COVERAGE_TABLE_MAX_ROWS) {
+    lines.push("### Query Coverage");
+    lines.push("| Query | Results | Top URL | Top Pos |");
+    lines.push("|---------|---------|---------|---------|");
+    for (const search of queryResults) {
+      const topResult = search.results[0];
+      let topDomain = "";
+      if (topResult) {
+        try {
+          topDomain = new URL(topResult.link).hostname.replace(/^www\./, "");
+        } catch {
+          topDomain = topResult.link;
+        }
+      }
+      lines.push(`| "${search.query}" | ${search.results.length} | ${topDomain || "\u2014"} | ${topResult ? `#${topResult.position}` : "\u2014"} |`);
+    }
+    lines.push("");
+  } else {
+    const goodCount = queryResults.filter((s) => s.results.length >= 3).length;
+    lines.push(`### Query Coverage: ${goodCount}/${allQueries.length} queries returned 3+ results`);
+    lines.push("");
+  }
+  const lowYield = queryResults.filter((s) => s.results.length <= 1);
+  if (lowYield.length > 0) {
+    lines.push(`**Low-yield queries** (0-1 results): ${lowYield.map((s) => `\`${s.query}\``).join(", ")}`);
+    lines.push("");
+  }
+  const allRelated = /* @__PURE__ */ new Set();
+  for (const search of queryResults) {
+    if (search.related) {
+      for (const r of search.related) {
+        allRelated.add(r);
+      }
+    }
+  }
+  if (allRelated.size > 0) {
+    const related = [...allRelated].slice(0, 10);
+    lines.push(`**Related searches:** ${related.map((r) => `\`${r}\``).join(", ")}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function aggregateAndRank(searches, minConsensusUrls = DEFAULT_MIN_CONSENSUS_URLS) {
+  const urlMap = aggregateResults(searches);
+  const totalUniqueUrls = urlMap.size;
+  const totalQueries = searches.length;
+  const thresholds = [3, 2, 1];
+  let usedThreshold = 1;
+  let thresholdNote;
+  for (const threshold of thresholds) {
+    const count = countByFrequency(urlMap, threshold);
+    if (count >= minConsensusUrls || threshold === 1) {
+      usedThreshold = threshold;
+      if (threshold < 3) {
+        thresholdNote = `Note: Consensus threshold set to \u2265${threshold} due to result diversity.`;
+      }
+      break;
+    }
+  }
+  const allUrls = [...urlMap.values()];
+  const rankedUrls = calculateWeightedScores(allUrls, usedThreshold, totalQueries);
+  return {
+    rankedUrls,
+    totalUniqueUrls,
+    totalQueries,
+    frequencyThreshold: usedThreshold,
+    thresholdNote
+  };
+}
+
+// src/utils/sanitize.ts
+var CONTROL_CHARS = /[\x00-\x1f\x7f]/g;
+var URLS = /https?:\/\/\S+/gi;
+var MARKDOWN_LINKS = /\[([^\]]+)\]\([^)]+\)/g;
+function sanitizeSuggestion(input) {
+  return input.replace(CONTROL_CHARS, " ").replace(MARKDOWN_LINKS, "$1").replace(URLS, "").replace(/\s+/g, " ").trim();
+}
+
+// src/utils/query-relax.ts
+var QUOTED_PHRASE_RE = /"([^"]*)"/g;
+var HAS_BOOLEAN_GROUPING = /\b(?:OR|AND)\b|[()]/;
+var OPERATOR_CHAR_IN_PHRASE = /[():[\]]/;
+var OPERATOR_CHAR_GLOBAL = /[():[\]]/g;
+var PATH_LIKE_IN_PHRASE = /\/|~\/|^@|\.{3,}/;
+var URI_SCHEME_IN_PHRASE = /^[a-z][a-z0-9+.-]*:/i;
+var HAS_SITE_OPERATOR = /\bsite:\S+/i;
+var SITE_OPERATOR_GLOBAL = /\bsite:\S+/gi;
+function renderSeg(seg) {
+  return seg.type === "raw" ? seg.text : seg.quoted ? `"${seg.text}"` : seg.text;
+}
+function tokenize(query) {
+  const segs = [];
+  let last = 0;
+  for (const m of query.matchAll(QUOTED_PHRASE_RE)) {
+    const start = m.index ?? 0;
+    const end = start + m[0].length;
+    if (start > last) segs.push({ type: "raw", text: query.slice(last, start) });
+    segs.push({ type: "phrase", text: m[1] ?? "", quoted: true });
+    last = end;
+  }
+  if (last < query.length) segs.push({ type: "raw", text: query.slice(last) });
+  return segs;
+}
+function rebuild(segs) {
+  return segs.map(renderSeg).join("").replace(/\s+/g, " ").trim();
+}
+function onlyWhitespaceBetween(segs, fromIndex, toIndex) {
+  for (let i = fromIndex + 1; i < toIndex; i += 1) {
+    const seg = segs[i];
+    if (seg === void 0) continue;
+    if (seg.type !== "raw" || seg.text.trim() !== "") {
+      return false;
+    }
+  }
+  return true;
+}
+function buildAnchoredOrGroup(segs, quotedIndices) {
+  const groupStart = quotedIndices[1];
+  const groupEnd = quotedIndices[quotedIndices.length - 1];
+  if (groupStart === void 0 || groupEnd === void 0) {
+    return null;
+  }
+  for (let i = 2; i < quotedIndices.length; i += 1) {
+    const previous = quotedIndices[i - 1];
+    const current = quotedIndices[i];
+    if (previous === void 0 || current === void 0 || !onlyWhitespaceBetween(segs, previous, current)) {
+      return null;
+    }
+  }
+  const groupIndices = new Set(quotedIndices.slice(1));
+  const parts = [];
+  for (let i = 0; i < segs.length; i += 1) {
+    const seg = segs[i];
+    if (seg === void 0) continue;
+    if (seg.type === "raw") {
+      if (i > groupStart && i < groupEnd) {
+        continue;
+      }
+      parts.push(seg.text);
+      continue;
+    }
+    if (groupIndices.has(i)) {
+      parts.push(i === groupStart ? " (" : " OR ");
+      parts.push(renderSeg(seg));
+      if (i === groupEnd) {
+        parts.push(")");
+      }
+      continue;
+    }
+    parts.push(renderSeg(seg));
+  }
+  return parts.join("").replace(/\s+/g, " ").trim();
+}
+function normalizeQueryForDispatch(query) {
+  const original = query.trim().replace(/\s+/g, " ");
+  if (!original) {
+    return { rewritten: original, changed: false, rules: [] };
+  }
+  const segs = tokenize(query);
+  const rules = [];
+  for (const s of segs) {
+    if (s.type === "phrase" && s.quoted && OPERATOR_CHAR_IN_PHRASE.test(s.text) && !URI_SCHEME_IN_PHRASE.test(s.text)) {
+      s.quoted = false;
+      s.text = s.text.replace(OPERATOR_CHAR_GLOBAL, " ");
+      if (!rules.includes("A1")) rules.push("A1");
+    }
+  }
+  for (const s of segs) {
+    if (s.type === "phrase" && s.quoted && (URI_SCHEME_IN_PHRASE.test(s.text) || PATH_LIKE_IN_PHRASE.test(s.text))) {
+      s.quoted = false;
+      if (!rules.includes("A2")) rules.push("A2");
+    }
+  }
+  const stillQuotedIndices = [];
+  for (let i = 0; i < segs.length; i += 1) {
+    const seg = segs[i];
+    if (seg?.type === "phrase" && seg.quoted) {
+      stillQuotedIndices.push(i);
+    }
+  }
+  const rawJoined = segs.filter((s) => s.type === "raw").map((s) => s.text).join(" ");
+  if (stillQuotedIndices.length >= 3 && !HAS_BOOLEAN_GROUPING.test(rawJoined)) {
+    const grouped = buildAnchoredOrGroup(segs, stillQuotedIndices);
+    if (grouped !== null) {
+      rules.push("A3");
+      return { rewritten: grouped, changed: grouped !== original, rules };
+    }
+  }
+  const rewritten = rebuild(segs);
+  return { rewritten, changed: rewritten !== original, rules };
+}
+function relaxQueryForRetry(query, options = {}) {
+  const original = query.trim().replace(/\s+/g, " ");
+  if (!original) {
+    return { rewritten: original, changed: false, rules: [] };
+  }
+  const dropSite = options.dropSite ?? true;
+  const rules = [];
+  let result = query;
+  if (result.includes('"')) {
+    result = result.replace(/"/g, "");
+    rules.push("B1");
+  }
+  if (dropSite && HAS_SITE_OPERATOR.test(result)) {
+    result = result.replace(SITE_OPERATOR_GLOBAL, " ");
+    rules.push("B2");
+  }
+  result = result.replace(/\s+/g, " ").trim();
+  return { rewritten: result, changed: result !== original, rules };
+}
+
+// src/tools/search.ts
+function formatInputValidationError2(toolName, issues) {
+  const details = issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.map(String).join(".") : "<root>";
+    return `- ${path}: ${issue.message}`;
+  }).join("\n");
+  return `Invalid ${toolName} input.
+
+${details}`;
+}
+var REDDIT_POST_PERMALINK2 = /\/r\/[^/]+\/comments\/[a-z0-9]+\//i;
+var REDDIT_HOST2 = /(?:^|\.)reddit\.com$/i;
+function redditScopedQuery(query) {
+  return /\bsite:reddit\.com\b/i.test(query) ? query : `${query} site:reddit.com`;
+}
+function buildScopedQueries(queries, scope) {
+  if (scope === "web") {
+    return queries.map((query) => ({ query, resultScope: "web", dropSiteOnRetry: true }));
+  }
+  const reddited = queries.map(
+    (q) => ({ query: redditScopedQuery(q), resultScope: "reddit", dropSiteOnRetry: false })
+  );
+  if (scope === "reddit") return reddited;
+  return [
+    ...queries.map((query) => ({ query, resultScope: "web", dropSiteOnRetry: true })),
+    ...reddited
+  ];
+}
+async function executeSearches(queries) {
+  const env = parseEnv();
+  const hasSerper = Boolean(env.SEARCH_API_KEY);
+  const hasJina = Boolean(env.JINA_API_KEY);
+  if (!hasSerper && hasJina) {
+    mcpLog("info", "SERPER_API_KEY missing; using Jina Search fallback as primary search provider", "search");
+    return runExternalEffect(
+      Effect4.gen(function* () {
+        const search = yield* SearchService;
+        return yield* search.jinaSearchMultiple(queries);
+      }),
+      SearchServiceLive
+    );
+  }
+  if (!hasSerper) {
+    return {
+      searches: [],
+      totalQueries: queries.length,
+      executionTime: 0,
+      error: {
+        code: ErrorCode.AUTH_ERROR,
+        message: "No search provider configured. Set SERPER_API_KEY or JINA_API_KEY.",
+        retryable: false
+      }
+    };
+  }
+  const serperResponse = await runExternalEffect(
+    Effect4.gen(function* () {
+      const search = yield* SearchService;
+      return yield* search.serperSearchMultiple(queries);
+    }),
+    SearchServiceLive
+  );
+  if (!hasJina) return serperResponse;
+  if (serperResponse.error) {
+    mcpLog("warning", `Serper failed (${serperResponse.error.message}); trying Jina Search fallback`, "search");
+    const jinaResponse2 = await runExternalEffect(
+      Effect4.gen(function* () {
+        const search = yield* SearchService;
+        return yield* search.jinaSearchMultiple(queries);
+      }),
+      SearchServiceLive
+    );
+    return jinaResponse2.error ? serperResponse : jinaResponse2;
+  }
+  const emptyIndices = serperResponse.searches.map((search, index) => search.results.length === 0 ? index : -1).filter((index) => index !== -1);
+  if (emptyIndices.length === 0) return serperResponse;
+  const fallbackQueries = emptyIndices.map((index) => serperResponse.searches[index]?.query).filter((query) => typeof query === "string" && query.length > 0);
+  if (fallbackQueries.length === 0) return serperResponse;
+  mcpLog("info", `${fallbackQueries.length} zero-result Serper query/queries; trying Jina Search fallback`, "search");
+  const jinaResponse = await runExternalEffect(
+    Effect4.gen(function* () {
+      const search = yield* SearchService;
+      return yield* search.jinaSearchMultiple(fallbackQueries);
+    }),
+    SearchServiceLive
+  );
+  if (jinaResponse.error) return serperResponse;
+  const fallbackByQuery = new Map(jinaResponse.searches.map((search) => [search.query, search]));
+  const mergedSearches = serperResponse.searches.map((search) => {
+    if (search.results.length > 0) return search;
+    const fallback = fallbackByQuery.get(search.query);
+    if (!fallback || fallback.results.length === 0) return search;
+    return { ...fallback, query: search.query };
+  });
+  return {
+    ...serperResponse,
+    searches: mergedSearches,
+    executionTime: serperResponse.executionTime + jinaResponse.executionTime
+  };
+}
+async function executeWithRelaxRetry(dispatched, reporter, searchExecutor = executeSearches, retryOptions = {}) {
+  const initial = await searchExecutor(dispatched);
+  if (initial.error) {
+    return { response: initial, retried: [], failurePhase: "initial" };
+  }
+  const emptyIndices = initial.searches.map((s, i) => s.results.length === 0 ? i : -1).filter((i) => i !== -1);
+  if (emptyIndices.length === 0) {
+    return { response: initial, retried: [] };
+  }
+  const plans = [];
+  for (const idx of emptyIndices) {
+    const dq = dispatched[idx];
+    if (typeof dq !== "string") continue;
+    const r = relaxQueryForRetry(dq, { dropSite: retryOptions.dropSiteOnRetry?.[idx] ?? true });
+    if (r.changed && r.rewritten !== dq) {
+      plans.push({ index: idx, original: dq, relaxed: r.rewritten, rules: [...r.rules] });
+    }
+  }
+  if (plans.length === 0) {
+    return { response: initial, retried: [] };
+  }
+  mcpLog(
+    "info",
+    `${plans.length}/${emptyIndices.length} empty-result queries eligible for relaxation retry`,
+    "search"
+  );
+  await reporter.log(
+    "info",
+    `${plans.length} queries returned 0 results; retrying with relaxation`
+  );
+  const retryResp = await searchExecutor(plans.map((p) => p.relaxed));
+  const retried = [];
+  const retryByIndex = /* @__PURE__ */ new Map();
+  plans.forEach((plan, i) => {
+    const r = retryResp.searches[i];
+    if (r) retryByIndex.set(plan.index, r);
+    retried.push({
+      original: plan.original,
+      retried_with: plan.relaxed,
+      rules: plan.rules,
+      recovered_results: r?.results.length ?? 0
+    });
+  });
+  if (retryResp.error) {
+    mcpLog(
+      "warning",
+      `Relaxed retry batch failed; preserving initial search results: ${retryResp.error.message}`,
+      "search"
+    );
+    await reporter.log(
+      "warning",
+      `search_relax_retry_failed: ${retryResp.error.message}`
+    );
+    return {
+      response: initial,
+      retried,
+      retryError: retryResp.error
+    };
+  }
+  const mergedSearches = initial.searches.map((s, idx) => {
+    const r = retryByIndex.get(idx);
+    if (r && r.results.length > 0) {
+      return { ...r, query: s.query };
+    }
+    return s;
+  });
+  return {
+    response: { ...initial, searches: mergedSearches },
+    retried
+  };
+}
+function filterScopedSearches(response, scope, resultScopes = []) {
+  if (scope === "web") return response;
+  const filtered = response.searches.map((search, index) => {
+    const resultScope = resultScopes[index] ?? (scope === "reddit" ? "reddit" : "web");
+    return {
+      ...search,
+      results: search.results.filter((r) => {
+        let host;
+        try {
+          host = new URL(r.link).hostname;
+        } catch {
+          return true;
+        }
+        if (resultScope === "reddit") {
+          return REDDIT_HOST2.test(host) && REDDIT_POST_PERMALINK2.test(r.link);
+        }
+        if (!REDDIT_HOST2.test(host)) return true;
+        return REDDIT_POST_PERMALINK2.test(r.link);
+      })
+    };
+  });
+  return { ...response, searches: filtered };
+}
+function processResults(response) {
+  const aggregation = aggregateAndRank(response.searches, 5);
+  return { aggregation };
+}
+function buildRawOutput(queries, aggregation, searches, verbose = false) {
+  return generateUnifiedOutput(
+    aggregation.rankedUrls,
+    queries,
+    searches,
+    aggregation.totalUniqueUrls,
+    aggregation.frequencyThreshold,
+    aggregation.thresholdNote,
+    verbose
+  );
+}
+function buildSignalsSection(aggregation, searches, totalQueries) {
+  const coverageCount = searches.filter((search) => search.results.length >= 3).length;
+  const lowYield = searches.filter((search) => search.results.length <= 1).map((search) => `"${search.query}"`);
+  const consensusCount = aggregation.rankedUrls.filter((url) => url.isConsensus).length;
+  const lines = [
+    "**Signals**",
+    `- Coverage: ${coverageCount}/${totalQueries} queries returned \u22653 results`,
+    `- Consensus URLs: ${consensusCount}`
+  ];
+  if (lowYield.length > 0) {
+    lines.push(`- Low-yield: ${lowYield.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+function buildSuggestedFollowUpsSection(refineQueries) {
+  if (!refineQueries || refineQueries.length === 0) {
+    return "";
+  }
+  const lines = ["## Suggested follow-up searches", ""];
+  for (const item of refineQueries) {
+    const query = sanitizeSuggestion(item.query ?? "");
+    if (!query) continue;
+    const rationale = sanitizeSuggestion(item.rationale ?? "");
+    const gapTag = typeof item.gap_id === "number" ? ` _(closes gap [${item.gap_id}])_` : item.gap_description ? ` _(${sanitizeSuggestion(item.gap_description)})_` : "";
+    lines.push(
+      rationale ? `- ${query} \u2014 ${rationale}${gapTag}` : `- ${query}${gapTag}`
+    );
+  }
+  return lines.length === 2 ? "" : lines.join("\n");
+}
+function appendSignalsAndFollowUps(markdown2, signalsSection, refineQueries, options = {}) {
+  const includeSignals = options.includeSignals ?? false;
+  const sections = [markdown2];
+  if (includeSignals && signalsSection) {
+    sections.push("", "---", signalsSection);
+  }
+  const followUps = buildSuggestedFollowUpsSection(refineQueries);
+  if (followUps) {
+    sections.push("", followUps);
+  }
+  return sections.join("\n");
+}
+var MIN_START_HERE = 3;
+var MAX_START_HERE = 5;
+function buildStartHereSection(tiers, entryByRank, opts = {}) {
+  const min = opts.min ?? MIN_START_HERE;
+  const max = opts.max ?? MAX_START_HERE;
+  const picks = [];
+  for (const candidate of tiers.high) {
+    if (picks.length >= max) break;
+    picks.push({ candidate, tier: "HIGHLY_RELEVANT" });
+  }
+  if (picks.length < min) {
+    const target = Math.min(min, max);
+    for (const candidate of tiers.maybe) {
+      if (picks.length >= target) break;
+      picks.push({ candidate, tier: "MAYBE_RELEVANT" });
+    }
+  }
+  if (picks.length === 0) return "";
+  const lines = [];
+  lines.push("## Start here \u2014 best candidates for your extract");
+  picks.forEach((pick, i) => {
+    const entry = entryByRank.get(pick.candidate.rank);
+    const reason = entry?.reason && entry.reason.trim().length > 0 ? entry.reason : "\u2014";
+    let domain;
+    try {
+      domain = new URL(pick.candidate.url).hostname.replace(/^www\./, "");
+    } catch {
+      domain = pick.candidate.url;
+    }
+    lines.push(
+      `${i + 1}. **[${pick.candidate.title}](${pick.candidate.url})** \u2014 ${domain} \u2014 ${reason} *(${pick.tier}, rank ${pick.candidate.rank})*`
+    );
+  });
+  return lines.join("\n");
+}
+function buildClassifiedOutput(classification, aggregation, extract, searches, totalQueries, verbose = false) {
+  const rankedUrls = aggregation.rankedUrls;
+  const entryByRank = new Map(classification.results.map((r) => [r.rank, r]));
+  const tiers = {
+    high: [],
+    maybe: [],
+    other: []
+  };
+  for (const url of rankedUrls) {
+    const entry = entryByRank.get(url.rank);
+    const tier = entry?.tier;
+    if (tier === "HIGHLY_RELEVANT") {
+      tiers.high.push(url);
+    } else if (tier === "MAYBE_RELEVANT") {
+      tiers.maybe.push(url);
+    } else {
+      tiers.other.push(url);
+    }
+  }
+  const lines = [];
+  lines.push(`## ${classification.title}`);
+  lines.push(`> Looking for: ${extract}`);
+  lines.push(`> ${totalQueries} queries \u2192 ${rankedUrls.length} URLs \u2192 ${tiers.high.length} highly relevant, ${tiers.maybe.length} possibly relevant`);
+  if (classification.confidence) {
+    const confReason = classification.confidence_reason ? ` \u2014 ${classification.confidence_reason}` : "";
+    lines.push(`> Confidence: \`${classification.confidence}\`${confReason}`);
+  }
+  lines.push("");
+  const startHere = buildStartHereSection(
+    { high: tiers.high, maybe: tiers.maybe },
+    entryByRank
+  );
+  if (startHere) {
+    lines.push(startHere);
+    lines.push("");
+  }
+  lines.push(`**Summary:** ${classification.synthesis}`);
+  lines.push("");
+  const renderRichRow = (url) => {
+    const entry = entryByRank.get(url.rank);
+    const coveragePct = Math.round(url.coverageRatio * 100);
+    const seenIn = `${url.frequency}/${totalQueries} (${coveragePct}%)`;
+    const sourceType = entry?.source_type ? `\`${entry.source_type}\`` : "\u2014";
+    const reason = entry?.reason ? entry.reason.replace(/\|/g, "\\|") : "\u2014";
+    return `| ${url.rank} | [${url.title}](${url.url}) | ${sourceType} | ${seenIn} | ${reason} |`;
+  };
+  if (tiers.high.length > 0) {
+    lines.push(`### Highly Relevant (${tiers.high.length})`);
+    lines.push("| # | URL | Source | Seen in | Why |");
+    lines.push("|---|-----|--------|---------|-----|");
+    for (const url of tiers.high) lines.push(renderRichRow(url));
+    lines.push("");
+  }
+  if (tiers.maybe.length > 0) {
+    lines.push(`### Maybe Relevant (${tiers.maybe.length})`);
+    lines.push("| # | URL | Source | Seen in | Why |");
+    lines.push("|---|-----|--------|---------|-----|");
+    for (const url of tiers.maybe) lines.push(renderRichRow(url));
+    lines.push("");
+  }
+  if (tiers.other.length > 0) {
+    lines.push(`### Other Results (${tiers.other.length})`);
+    lines.push("| # | URL | Source | Score | Queries |");
+    lines.push("|---|-----|--------|-------|---------|");
+    for (const url of tiers.other) {
+      const entry = entryByRank.get(url.rank);
+      const queryList = url.queries.map((q) => `"${q}"`).join(", ");
+      const sourceType = entry?.source_type ? `\`${entry.source_type}\`` : "\u2014";
+      let domain;
+      try {
+        domain = new URL(url.url).hostname.replace(/^www\./, "");
+      } catch {
+        domain = url.url;
+      }
+      lines.push(`| ${url.rank} | ${domain} | ${sourceType} | ${url.score.toFixed(1)} | ${queryList} |`);
+    }
+    lines.push("");
+  }
+  if (verbose) {
+    lines.push(buildSignalsSection(aggregation, searches, totalQueries));
+  }
+  if (classification.gaps && classification.gaps.length > 0) {
+    lines.push("");
+    lines.push("## Gaps");
+    for (const gap of classification.gaps) {
+      lines.push(`- **[${gap.id}]** ${gap.description}`);
+    }
+  }
+  const followUps = buildSuggestedFollowUpsSection(classification.refine_queries);
+  if (followUps) {
+    lines.push("");
+    lines.push(followUps);
+  }
+  return lines.join("\n");
+}
+function formatSearchFailureMessage(error2, phase) {
+  if (phase === "initial") {
+    return `Search provider failed during initial batch: ${error2.message}`;
+  }
+  if (phase === "relax-retry") {
+    return `Search provider failed during relaxed retry batch: ${error2.message}`;
+  }
+  return error2.message;
+}
+function buildWebSearchError(error2, params, startTime, phase) {
+  const message = formatSearchFailureMessage(error2, phase);
+  const executionTime = Date.now() - startTime;
+  mcpLog("error", `${params.toolName}: ${message}`, "search");
+  const errorContent = formatError({
+    code: error2.code,
+    message,
+    retryable: error2.retryable,
+    toolName: params.toolName,
+    howToFix: ["Verify SERPER_API_KEY or JINA_API_KEY is set correctly"],
+    alternatives: [
+      'raw-web-search(keywords=["topic recommendations site:reddit.com"]) \u2014 unclassified search results',
+      "raw-scrape-links(urls=[...]) \u2014 if you already have URLs, fetch their markdown now"
+    ]
+  });
+  return toolFailure(
+    `${errorContent}
+
+Execution time: ${formatDuration(executionTime)}
+Keywords: ${params.keywords.length}`
+  );
+}
+async function handleSearch(params, reporter = NOOP_REPORTER, searchExecutor = executeSearches) {
+  const startTime = Date.now();
+  try {
+    if (params.smart && !createLLMProcessor()) {
+      return toolFailure(getMissingEnvMessage("llmExtraction"));
+    }
+    const scopedQueries = buildScopedQueries(params.keywords, params.scope);
+    const effectiveQueries = scopedQueries.map((entry) => entry.query);
+    if (params.scope !== "web") {
+      mcpLog("info", `Searching scope=${params.scope}: ${params.keywords.length} input keywords \u2192 ${effectiveQueries.length} dispatched`, "search");
+    } else {
+      mcpLog("info", `Searching for ${params.keywords.length} keyword(s)`, "search");
+    }
+    await reporter.log("info", `Searching for ${effectiveQueries.length} query/queries (scope=${params.scope})`);
+    await reporter.progress(15, 100, "Submitting search queries");
+    const dispatchPlan = effectiveQueries.map((q) => {
+      const r = normalizeQueryForDispatch(q);
+      return { original: q, dispatched: r.rewritten, rules: [...r.rules], changed: r.changed };
+    });
+    const dispatchedQueries = dispatchPlan.map((p) => p.dispatched);
+    const resultScopes = scopedQueries.map((entry) => entry.resultScope);
+    const dropSiteOnRetry = scopedQueries.map((entry) => entry.dropSiteOnRetry);
+    const queryRewrites = dispatchPlan.filter((p) => p.changed).map((p) => ({ original: p.original, rewritten: p.dispatched, rules: p.rules }));
+    if (queryRewrites.length > 0) {
+      mcpLog(
+        "info",
+        `Pre-dispatch normalized ${queryRewrites.length}/${effectiveQueries.length} queries`,
+        "search"
+      );
+      await reporter.log(
+        "info",
+        `Normalized ${queryRewrites.length} queries pre-dispatch`
+      );
+    }
+    const {
+      response: rawResponse,
+      retried: retriedQueries,
+      failurePhase,
+      retryError
+    } = await executeWithRelaxRetry(
+      dispatchedQueries,
+      reporter,
+      searchExecutor,
+      { dropSiteOnRetry }
+    );
+    if (rawResponse.error) {
+      await reporter.log("error", `search_provider_failed: ${rawResponse.error.message}`);
+      return buildWebSearchError(rawResponse.error, params, startTime, failurePhase);
+    }
+    const response = filterScopedSearches(rawResponse, params.scope, resultScopes);
+    await reporter.progress(50, 100, "Collected search results");
+    const { aggregation } = processResults(response);
+    await reporter.log(
+      "info",
+      `Collected ${aggregation.totalUniqueUrls} unique URLs across ${response.totalQueries} queries`
+    );
+    let markdown2;
+    if (!params.smart) {
+      markdown2 = appendSignalsAndFollowUps(
+        buildRawOutput(params.keywords, aggregation, response.searches, false),
+        buildSignalsSection(aggregation, response.searches, response.totalQueries),
+        void 0,
+        { includeSignals: false }
+      );
+      await reporter.progress(80, 100, "Ranking search results");
+    } else {
+      const llmProcessor = createLLMProcessor();
+      if (!llmProcessor) {
+        return toolFailure(getMissingEnvMessage("llmExtraction"));
+      }
+      await reporter.progress(65, 100, "Classifying results by relevance");
+      const classification = await runExternalEffect(
+        Effect4.gen(function* () {
+          const llm = yield* LlmService;
+          return yield* llm.classifySearchResults(
+            aggregation.rankedUrls,
+            params.extract ?? "",
+            response.totalQueries,
+            llmProcessor,
+            params.keywords
+          );
+        }),
+        LlmServiceLive
+      );
+      if (classification.result) {
+        markdown2 = buildClassifiedOutput(
+          classification.result,
+          aggregation,
+          params.extract ?? "",
+          response.searches,
+          response.totalQueries,
+          params.verbose
+        );
+        await reporter.progress(85, 100, "Formatted classified results");
+      } else {
+        const llmError = classification.error ?? "Unknown classification error";
+        mcpLog("warning", `Classification failed for smart-web-search: ${llmError}`, "search");
+        await reporter.log("warning", `llm_classifier_failed: ${llmError}`);
+        return toolFailure(
+          `${formatError({
+            code: ErrorCode.SERVICE_UNAVAILABLE,
+            message: `LLM classification failed: ${llmError}`,
+            retryable: true,
+            toolName: params.toolName,
+            alternatives: ["raw-web-search(keywords=[...]) \u2014 return unclassified search results"]
+          })}
+
+Execution time: ${formatDuration(Date.now() - startTime)}`
+        );
+      }
+    }
+    const executionTime = Date.now() - startTime;
+    mcpLog("info", `Search completed: ${aggregation.rankedUrls.length} URLs, smart=${params.smart}`, "search");
+    await reporter.log("info", `Search completed with ${aggregation.rankedUrls.length} URLs (smart: ${params.smart})`);
+    const footerParts = [
+      formatDuration(executionTime),
+      `${aggregation.totalUniqueUrls} unique URLs`,
+      params.smart ? "LLM classified" : "raw search"
+    ];
+    if (queryRewrites.length > 0) footerParts.push(`${queryRewrites.length} normalized`);
+    if (retriedQueries.length > 0) footerParts.push(`${retriedQueries.length} retried`);
+    if (retryError) footerParts.push(`retry warning: ${retryError.code}`);
+    const footer = `
+---
+*${footerParts.join(" | ")}*`;
+    const fullMarkdown = markdown2 + footer;
+    return toolSuccess(fullMarkdown);
+  } catch (error2) {
+    return buildWebSearchError(classifyError(error2), params, startTime);
+  }
+}
+function handleRawWebSearch(params, reporter = NOOP_REPORTER, searchExecutor = executeSearches) {
+  return handleSearch(
+    {
+      ...params,
+      scope: "web",
+      verbose: false,
+      smart: false,
+      toolName: "raw-web-search"
+    },
+    reporter,
+    searchExecutor
+  );
+}
+function handleSmartWebSearch(params, reporter = NOOP_REPORTER, searchExecutor = executeSearches) {
+  return handleSearch(
+    {
+      ...params,
+      smart: true,
+      toolName: "smart-web-search"
+    },
+    reporter,
+    searchExecutor
+  );
+}
+function registerWebSearchTools(server) {
+  server.tool(
+    {
+      name: "raw-web-search",
+      title: "Raw Web Search",
+      description: `Fan out raw search keywords in parallel and return the ranked markdown list directly. Serper is primary when configured; Jina Search is fallback when Serper is missing, fails, or yields empty query results. Input is only \`keywords\` (1\u201350 items). ${QUERY_REWRITE_PAIR_GUIDANCE_TEXT} Use this when you need unclassified result data, Reddit permalink discovery via explicit \`site:reddit.com/r/.../comments\` keywords, or broad reconnaissance before synthesis.`,
+      schema: rawWebSearchParamsSchema,
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: true
+      }
+    },
+    async (args, ctx) => {
+      const parsed = rawWebSearchParamsSchema.safeParse(args);
+      if (!parsed.success) {
+        return toToolResponse(toolFailure(formatInputValidationError2("raw-web-search", parsed.error.issues)));
+      }
+      if (!getCapabilities().search) {
+        return toToolResponse(toolFailure(getMissingEnvMessage("search")));
+      }
+      const reporter = createToolReporter(ctx, "raw-web-search");
+      const result = await handleRawWebSearch(parsed.data, reporter);
+      await reporter.progress(100, 100, result.isError ? "Search failed" : "Search complete");
+      return toToolResponse(result);
+    }
+  );
+  server.tool(
+    {
+      name: "smart-web-search",
+      title: "Smart Web Search",
+      description: `Fan out search keywords in parallel, then always run LLM classification and synthesis against \`extract\`. Serper is primary when configured; Jina Search is fallback when Serper is missing, fails, or yields empty query results. Input carries 1\u201350 \`keywords\`, required \`extract\`, optional \`scope: "web" | "reddit" | "both"\`, and optional \`verbose\`. ${QUERY_REWRITE_PAIR_GUIDANCE_TEXT} Use this for comprehensive research passes where you need HIGHLY_RELEVANT/MAYBE/OTHER tiers, a grounded synthesis with rank citations, gaps, and suggested follow-up searches.`,
+      schema: smartWebSearchParamsSchema,
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: true
+      }
+    },
+    async (args, ctx) => {
+      const parsed = smartWebSearchParamsSchema.safeParse(args);
+      if (!parsed.success) {
+        return toToolResponse(toolFailure(formatInputValidationError2("smart-web-search", parsed.error.issues)));
+      }
+      if (!getCapabilities().search) {
+        return toToolResponse(toolFailure(getMissingEnvMessage("search")));
+      }
+      const reporter = createToolReporter(ctx, "smart-web-search");
+      const result = await handleSmartWebSearch(parsed.data, reporter);
+      await reporter.progress(100, 100, result.isError ? "Search failed" : "Search complete");
+      return toToolResponse(result);
+    }
+  );
+}
+
+// src/tools/start-research.ts
+import { Effect as Effect5 } from "effect";
+
+// src/schemas/start-research.ts
+import { z as z3 } from "zod";
+var startResearchParamsSchema = z3.object({
+  goal: z3.string().min(1, { message: "start-research: goal cannot be empty" }).optional().describe(
+    'Research goal for this session. When provided AND the LLM planner is configured (LLM_API_KEY + LLM_BASE_URL + LLM_MODEL all set), the server returns a goal-tailored brief: classified goal type (spec | bug | migration | sentiment | pricing | security | synthesis | product_launch), a `primary_branch` recommendation (reddit for sentiment/migration; web for spec/bug/pricing; both when opinion-heavy AND needs official sources), the exact `first_call_sequence` of raw/smart search and scrape calls to fire, 25\u201350 keyword seeds for the first search call, iteration hints, gaps to watch, and stop criteria. The goal also sets the post-sort relevance target, so state the evidence you need and what "done" means. No goal \u2192 the generic 5-tool playbook (no tailored brief). Write the goal as you would to a human researcher \u2014 one or two sentences, specific about what "done" looks like.'
+  ),
+  include_playbook: z3.boolean().default(false).describe(
+    "Include the full 5-tool research playbook (toolbelt overview, the loop, output discipline). Default false \u2014 when the LLM planner is offline the server emits a compact stub that already names the tools and the loop. Pass true only if the agent needs the verbose tactic reference, or to override the degraded-mode shrink."
+  )
+}).strict();
+
+// src/tools/start-research.ts
+var SKILL_INSTALL_HINT = [
+  "> \u{1F4A1} **Pair this server with the `run-research` skill** for the full agentic playbook",
+  "> (single-agent loop, multi-agent orchestrator, mission-prompt templates, output discipline).",
+  "> Install once per machine \u2014 the skill is what teaches the agent how to spend these tools well:",
+  ">",
+  "> ```bash",
+  "> npx -y skills add -y -g https://github.com/yigitkonur/skills-by-yigitkonur --skill /run-research",
+  "> ```",
+  ">",
+  "> Already installed? Skip this \u2014 the skill auto-loads on relevant prompts. The full pack",
+  "> ships ~50 sibling skills: `npx -y skills add -y -g https://github.com/yigitkonur/skills-by-yigitkonur`."
+].join("\n");
+function buildStaticScaffolding(goal, opts = {}) {
+  const plannerAvailable = opts.plannerAvailable ?? true;
+  const focusLine = goal ? `> Focus for this session: ${goal}` : "> Focus for this session: not yet specified \u2014 set one on the next pass";
+  const classifierLoopStep = plannerAvailable ? "3. If you used `smart-web-search`, treat its output as a prioritization layer over your keyword fan-out: read `Start here`, HIGHLY/MAYBE tiers, `gaps[]`, and `refine_queries[]`, then decide what to scrape. Do not treat smart search as evidence; it only sees titles/snippets. If you used `raw-web-search`, use the ranked URLs/snippets as the candidate pool and do your own prioritization." : "3. Classifier output is NOT available (LLM planner offline). Use `raw-web-search` and synthesize the terrain yourself from titles + snippets; then scrape before making claims.";
+  return [
+    SKILL_INSTALL_HINT,
+    "",
+    "# Research session started",
+    "",
+    focusLine,
+    "",
+    "You are running a research LOOP, not answering from memory. Training data is stale; the web is authoritative for anything dated, versioned, priced, or contested. Every non-trivial claim in your final answer must be traceable to a raw or smart scrape excerpt you read. Never cite a URL from a search snippet alone.",
+    "",
+    "## The 5 tools",
+    "",
+    "**1. `start-research`** \u2014 you just called me. I plan this session and return the brief below. Call me again only if the goal materially shifts.",
+    "",
+    "**2. `raw-web-search`** \u2014 fan out search keywords in parallel and return the ranked markdown list directly. Serper is primary when configured; Jina Search is fallback when Serper is missing, fails, or yields empty query results. One call carries **up to 50 keywords** in a flat `keywords` array. Use raw search when recall matters more than interpretation: broad discovery, audit trails, exact candidate URLs, cheap second/third passes, and Reddit permalink discovery.",
+    "",
+    "**3. `smart-web-search`** \u2014 fan out search keywords, then always run LLM classification/synthesis with required `extract`. Its value is **prioritization, not evidence**: it ranks title/snippet results into HIGHLY_RELEVANT / MAYBE / OTHER, surfaces `## Gaps`, and suggests sharper follow-up keywords. Use smart search after you have a clear goal and a deliberately diverse keyword set; use raw search when you mainly need all candidate URLs or maximum distinct keyword coverage without classifier cost. Call search **aggressively** \u2014 2\u20134 rounds per session is normal, not 1. **Parallel-safe**: run multiple search calls in the same turn for orthogonal subtopics. `scope` values:",
+    '- `"reddit"` \u2192 server appends `site:reddit.com` and filters to post permalinks. Use for sentiment / migration / lived experience.',
+    '- `"web"` (default) \u2192 open web. Use for spec / bug / pricing / CVE / API / primary-source hunts.',
+    '- `"both"` \u2192 fans each query across both. Use when the topic is opinion-heavy AND needs official sources.',
+    "",
+    `**Query rewrite discipline** \u2014 ${QUERY_REWRITE_PAIR_GUIDANCE_TEXT}`,
+    "",
+    "## Raw vs smart choice",
+    "",
+    "- Prefer **raw search** for exploration and breadth: maximize distinct keywords, source classes, domains, and exact-result capture. Prefer **smart search** for triage: give it the same diverse keyword fan-out plus a precise `extract` goal so it can prioritize which URLs deserve scraping.",
+    "- Prefer **raw scrape** when the page/comments are the research object, when you need complete context, when extraction shape is unclear, or when preserving Reddit threads matters. Prefer **smart scrape** when you know the fields/facets you need and want compact evidence with `## Matches`, `## Not found`, and `## Follow-up signals`.",
+    "- Smart search is allowed to steer attention, but final claims must come from raw or smart scrape content. Smart scrape is usually the highest-value smart tool for answer construction because it reads the page body, not just snippets.",
+    "",
+    "**4. `raw-scrape-links`** \u2014 fetch URLs in parallel and return full markdown directly. **Auto-detects** `reddit.com/r/.../comments/` permalinks and routes them through the Reddit API (threaded post + comments). Non-Reddit URLs use Jina Reader first, then Jina Reader through Scrape.do proxy mode when configured, then optional Kernel browser rendering for web pages. Use raw scrape when you need complete markdown/comments, when the extraction shape is not yet known, or before narrowing a long/important source.",
+    "",
+    "**5. `smart-scrape-links`** \u2014 fetch URLs with the same provider stack, then always run per-URL LLM extraction with required `extract`. Use smart scrape for focused extraction, final evidence packs, long pages where only specific facts matter, and cross-source comparison. Describe extraction SHAPE in `extract`, facets separated by `|`: `root cause | affected versions | fix | workarounds | timeline`. It should preserve numbers/versions/errors/quotes and explicitly say what the source did not answer.",
+    "",
+    "## The loop",
+    "",
+    "1. Read the brief below (if present). Note `primary_branch`, `keyword_seeds`, `gaps_to_watch`, `stop_criteria`.",
+    '2. Fire `first_call_sequence` in order. For `primary_branch: reddit`, lead with `raw-web-search` using Reddit permalink probes, then `raw-scrape-links` on the best post permalinks for full comments. For `web`, use `raw-web-search` for maximum candidate breadth or `smart-web-search scope:"web"` to prioritize a strong keyword fan-out, then `smart-scrape-links` on selected URLs when the extraction shape is known. For `both`, issue parallel search calls split by source need.',
+    classifierLoopStep,
+    "4. Scrape every HIGHLY_RELEVANT plus the 2\u20133 best MAYBE_RELEVANT. Use `raw-scrape-links` first for full documents/comments and ambiguous sources; use `smart-scrape-links` when you can name the extraction facets precisely.",
+    "5. Harvest from smart scrape `## Follow-up signals` and from raw scrape full markdown/comments \u2014 new terms, version numbers, vendor names, failure modes, referenced URLs. These seed your next search round.",
+    "6. Fire the next search round with harvested terms plus any `refine_queries[]` the classifier suggested. Do NOT paraphrase queries already run \u2014 the classifier tracks them.",
+    "7. **Stop** when every `gaps_to_watch` item is closed AND the last search pass surfaced no new terms, OR when you have completed 4 full passes. State remaining gaps explicitly if you hit the cap.",
+    "",
+    "## Output discipline",
+    "",
+    "- Cite URL (or Reddit permalink) for every non-trivial claim \u2014 only from a raw or smart scrape excerpt you read.",
+    "- Quote verbatim: numbers, versions, API names, prices, error messages, stacktraces, people's words.",
+    "- Separate documented facts from inferred conclusions explicitly.",
+    "- Include the scrape date for time-sensitive claims.",
+    "- If you could not verify something, say so \u2014 do not paper over gaps.",
+    "- Never cite a URL from a search snippet alone.",
+    "",
+    "## Post-cutoff discipline",
+    "",
+    "For anything released / changed after your training cutoff \u2014 new products, versions, prices, benchmarks \u2014 treat your own query suggestions as hypotheses until a scraped first-party page confirms them. Include `site:<vendor-domain>` keywords in your first search call when the goal names a vendor or product."
+  ].join("\n");
+}
+function buildDegradedStub(goal) {
+  const focusLine = goal ? `> Focus for this session: ${goal}` : "> Focus for this session: not specified \u2014 set one on the next pass.";
+  return [
+    SKILL_INSTALL_HINT,
+    "",
+    "# Research session started (LLM planner offline \u2014 compact stub)",
+    "",
+    focusLine,
+    "",
+    "**5 tools**: `start-research` (plans), `raw-web-search` (keywords-only raw search), `smart-web-search` (search + required LLM prioritization over snippets, `scope: web|reddit|both`), `raw-scrape-links` (urls-only full markdown/comments), `smart-scrape-links` (scrape + required LLM extraction over page bodies). All are **parallel-callable** \u2014 fire multiple in the same turn when subtopics are orthogonal.",
+    "",
+    "**Loop**: search \u2192 scrape \u2192 harvest terms/signals \u2192 next search round \u2192 stop when gaps close OR after 4 passes. Use raw search for breadth, smart search for prioritization, raw scrape for full context, and smart scrape for focused extraction.",
+    "",
+    "**Reddit branch**: use `raw-web-search` with Reddit permalink probes for sentiment / migration / lived experience, then `raw-scrape-links` to capture full threaded comments. Use smart search only to prioritize many candidate posts; use smart scrape only after you know the extraction facets.",
+    "",
+    "**Cite**: every non-trivial claim must trace to a raw or smart scrape excerpt, never a search snippet. Quote verbatim for numbers, versions, stacktraces, people's words.",
+    "",
+    "Pass `include_playbook: true` to `start-research` for the full tactic reference."
+  ].join("\n");
+}
+var PLANNER_FAILURE_THRESHOLD = 2;
+var PLANNER_FAILURE_TTL_MS = 6e4;
+function isPlannerKnownOffline(health, nowMs = Date.now()) {
+  if (!health.plannerConfigured) {
+    return true;
+  }
+  if (health.consecutivePlannerFailures < PLANNER_FAILURE_THRESHOLD) {
+    return false;
+  }
+  if (health.lastPlannerCheckedAt === null) {
+    return false;
+  }
+  const lastMs = Date.parse(health.lastPlannerCheckedAt);
+  if (Number.isNaN(lastMs)) {
+    return false;
+  }
+  return nowMs - lastMs < PLANNER_FAILURE_TTL_MS;
+}
+async function buildGoalAwareBrief(goal, signal) {
+  const processor = createLLMProcessor();
+  if (!processor) {
+    mcpLog("info", "start-research: LLM unavailable, returning static orientation only", "start-research");
+    return "";
+  }
+  void signal;
+  const brief = await runExternalEffect(
+    Effect5.gen(function* () {
+      const llm = yield* LlmService;
+      return yield* llm.generateResearchBrief(goal, processor);
+    }),
+    LlmServiceLive
+  );
+  if (!brief) {
+    mcpLog("warning", "start-research: brief generation failed, returning static orientation only", "start-research");
+    return "";
+  }
+  return renderResearchBrief(brief);
+}
+async function handleStartResearch(params, signal) {
+  try {
+    const llmHealth2 = getLLMHealth();
+    const plannerKnownOffline = isPlannerKnownOffline(llmHealth2);
+    if (plannerKnownOffline && !params.include_playbook) {
+      const stub = buildDegradedStub(params.goal);
+      return toolSuccess(stub);
+    }
+    const scaffolding = buildStaticScaffolding(params.goal, {
+      plannerAvailable: !plannerKnownOffline
+    });
+    let brief = "";
+    if (params.goal) {
+      brief = await buildGoalAwareBrief(params.goal, signal);
+    }
+    const briefFallbackNote = params.goal && !brief ? "\n\n---\n\n> _Goal-tailored brief unavailable: LLM planner is not configured or failed this call. The static playbook above still applies; you can proceed with it, or retry `start-research` after verifying `LLM_API_KEY`._" : "";
+    const content = brief ? `${scaffolding}
+
+---
+
+${brief}` : `${scaffolding}${briefFallbackNote}`;
+    return toolSuccess(content);
+  } catch (err) {
+    const structuredError = classifyError(err);
+    mcpLog("error", `start-research: ${structuredError.message}`, "start-research");
+    return toolFailure(
+      formatError({
+        code: structuredError.code,
+        message: structuredError.message,
+        retryable: structuredError.retryable,
+        toolName: "start-research",
+        howToFix: ["Retry start-research. If the failure persists, verify LLM_API_KEY / LLM_BASE_URL / LLM_MODEL."]
+      })
+    );
+  }
+}
+function registerStartResearchTool(server) {
+  server.tool(
+    {
+      name: "start-research",
+      title: "Start Research Session",
+      description: `Call this FIRST every research session. Provide a \`goal\`; I return a goal-tailored brief naming (a) \`primary_branch\` (reddit for sentiment/migration, web for spec/bug/pricing, both when opinion-heavy AND needs official sources), (b) the exact \`first_call_sequence\` of raw/smart search and scrape calls to fire, (c) 25\u201350 keyword seeds for your first search call, (d) iteration hints, (e) gaps to watch, (f) stop criteria. ${QUERY_REWRITE_PAIR_GUIDANCE_TEXT} No goal? You still get the generic 5-tool playbook. Other tools work without calling this, but you will use them worse.`,
+      schema: startResearchParamsSchema,
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: false
+      }
+    },
+    async (args) => toToolResponse(await handleStartResearch(args))
+  );
+}
+
+// src/tools/registry.ts
+function registerAllTools(server) {
+  registerStartResearchTool(server);
+  registerWebSearchTools(server);
+  registerScrapeLinksTools(server);
+}
+
+// index.ts
+if (!process.env.UV_THREADPOOL_SIZE) {
+  process.env.UV_THREADPOOL_SIZE = "8";
+}
+var DEFAULT_PORT = 3e3;
+var SHUTDOWN_TIMEOUT_MS = 1e4;
+var WEBSITE_URL = "https://github.com/yigitkonur/mcp-researchpowerpack";
+var LOCAL_DEFAULT_HOST = "127.0.0.1";
+var startupLogger = Logger5.get("startup");
 function parseCsvEnv(value) {
   if (!value) return void 0;
   const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
@@ -66,15 +4707,15 @@ function buildCors(allowedOrigins) {
   };
 }
 function configureLogging() {
-  Logger.configure({
+  Logger5.configure({
     level: process.env.NODE_ENV === "production" ? "info" : "debug",
     format: "minimal"
   });
   const debug = process.env.DEBUG?.trim();
   if (debug === "2") {
-    Logger.setDebug(2);
+    Logger5.setDebug(2);
   } else if (debug) {
-    Logger.setDebug(1);
+    Logger5.setDebug(1);
   }
 }
 function normalizeOrigin(value, envName) {
@@ -227,9 +4868,9 @@ async function main() {
       }
       clearTimeout(forceExit);
       process.exit(exitCode);
-    } catch (error) {
+    } catch (error2) {
       clearTimeout(forceExit);
-      const message = error instanceof Error ? error.stack ?? error.message : String(error);
+      const message = error2 instanceof Error ? error2.stack ?? error2.message : String(error2);
       startupLogger.error(`Error while stopping server: ${message}`);
       process.exit(1);
     }
@@ -240,8 +4881,8 @@ async function main() {
   process.on("SIGINT", () => {
     void shutdown("SIGINT", 0);
   });
-  process.on("uncaughtException", (error) => {
-    startupLogger.error(`Uncaught exception: ${error.stack ?? error.message}`);
+  process.on("uncaughtException", (error2) => {
+    startupLogger.error(`Uncaught exception: ${error2.stack ?? error2.message}`);
     void shutdown("uncaughtException", 1);
   });
   process.on("unhandledRejection", (reason) => {
@@ -251,8 +4892,8 @@ async function main() {
   await server.listen(port);
   startupLogger.info(`${SERVER.NAME} v${SERVER.VERSION} listening on http://${host}:${port}/mcp`);
 }
-void main().catch((error) => {
-  const message = error instanceof Error ? error.stack ?? error.message : String(error);
+void main().catch((error2) => {
+  const message = error2 instanceof Error ? error2.stack ?? error2.message : String(error2);
   startupLogger.error(`Server failed to start: ${message}`);
   process.exit(1);
 });