@ryuu-reinzz/ryuu-cli 0.0.0-stage → 0.3.1

package/src/services/websearch/mcp.js

@@ -0,0 +1,233 @@
+/**
+ * Minimal MCP client wrapper.
+ *
+ * Remote providers use Streamable HTTP; the DuckDuckGo option uses stdio. The
+ * SDK handles protocol details, while this module adds the operational rules the
+ * agent needs: a hard timeout per operation, sanitized child-process
+ * environments, and typed errors that say whether a retry is worth it.
+ *
+ * Secrets never enter this module's logs: HTTP credentials travel in headers,
+ * and the stdio server receives a minimal environment (PATH/HOME only), not the
+ * agent's NVIDIA key or other credentials.
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { CancelledError, SearchError } from '../../utils/errors.js';
+import { readVersion } from '../../utils/version.js';
+
+const CLIENT_INFO = { name: 'ryuu-agent-cli', version: readVersion() };
+
+const SAFE_ENV_KEYS = [
+  'PATH',
+  'HOME',
+  'TMPDIR',
+  'TEMP',
+  'TMP',
+  'LANG',
+  'LC_ALL',
+  'SystemRoot',
+  'SYSTEMROOT',
+  'COMSPEC',
+  'PATHEXT',
+  'USERPROFILE',
+  'APPDATA',
+  'LOCALAPPDATA',
+];
+
+/** Environment for a third-party stdio server: no API keys, no session secrets. */
+export function safeChildEnv(extra = {}) {
+  const env = {};
+  for (const key of SAFE_ENV_KEYS) {
+    if (typeof process.env[key] === 'string') env[key] = process.env[key];
+  }
+  for (const [key, value] of Object.entries(extra || {})) {
+    if (/^(NVIDIA|TOKENHARBOR|RYUU|OPENAI|ANTHROPIC|TAVILY|FIRECRAWL|YDC|YOU|SERPER|SEARCH)_/i.test(key)) continue;
+    if (typeof value === 'string') env[key] = value;
+  }
+  return env;
+}
+
+function statusOf(error) {
+  const direct = Number(error?.status ?? error?.code);
+  if (Number.isInteger(direct) && direct >= 400 && direct <= 599) return direct;
+  const match = String(error?.message || '').match(/\b(4\d{2}|5\d{2})\b/);
+  return match ? Number(match[1]) : null;
+}
+
+/** Map an SDK/transport failure to a typed, actionable error. */
+export function mcpError(error, { provider, phase }) {
+  if (error?.code === 'CANCELLED' || error?.name === 'AbortError') {
+    return new CancelledError('Task cancelled by user.');
+  }
+  const status = statusOf(error);
+  const label = provider?.label || provider?.id || 'MCP provider';
+  const reason = String(error?.message || error).replace(/\s+/g, ' ').slice(0, 200);
+  if (status === 401 || status === 403) {
+    return new SearchError(`${label} rejected the credentials (HTTP ${status}).`, {
+      code: 'MCP_AUTH',
+      status,
+      details: { provider: provider?.id, phase },
+    });
+  }
+  if (status === 429) {
+    return new SearchError(`${label} is rate limited (HTTP 429).`, {
+      code: 'MCP_RATE_LIMIT',
+      status,
+      retryable: true,
+      details: { provider: provider?.id, phase },
+    });
+  }
+  if (status >= 500) {
+    return new SearchError(`${label} is unavailable (HTTP ${status}).`, {
+      code: 'MCP_UPSTREAM',
+      status,
+      retryable: true,
+      details: { provider: provider?.id, phase },
+    });
+  }
+  if (/timeout|timed out|aborted/i.test(reason)) {
+    return new SearchError(`${label} timed out during ${phase}.`, {
+      code: 'MCP_TIMEOUT',
+      retryable: true,
+      details: { provider: provider?.id, phase },
+    });
+  }
+  if (/fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ECONNRESET|socket/i.test(reason)) {
+    return new SearchError(`${label} cannot be reached: ${reason}`, {
+      code: 'MCP_NETWORK',
+      retryable: true,
+      details: { provider: provider?.id, phase },
+    });
+  }
+  if (/spawn|ENOENT/i.test(reason)) {
+    return new SearchError(`${label} could not start: ${reason}`, {
+      code: 'MCP_SPAWN',
+      details: { provider: provider?.id, phase },
+    });
+  }
+  if (phase === 'handshake') {
+    return new SearchError(`${label} MCP handshake failed: ${reason}`, {
+      code: 'MCP_HANDSHAKE',
+      details: { provider: provider?.id, phase },
+    });
+  }
+  if (phase === 'discovery') {
+    return new SearchError(`${label} tool discovery failed: ${reason}`, {
+      code: 'MCP_DISCOVERY',
+      details: { provider: provider?.id, phase },
+    });
+  }
+  return new SearchError(`${label} call failed: ${reason}`, {
+    code: 'MCP_CALL_FAILED',
+    details: { provider: provider?.id, phase },
+  });
+}
+
+/** Race a promise against a hard deadline and an optional abort signal. */
+export async function withTimeout(promise, { timeoutMs, signal = null, label = 'operation' }) {
+  if (signal?.aborted) throw new CancelledError('Task cancelled by user.');
+  let timer;
+  let onAbort;
+  const guard = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new SearchError(`${label} timed out after ${timeoutMs}ms.`, { code: 'MCP_TIMEOUT', retryable: true }));
+    }, timeoutMs);
+    if (timer.unref) timer.unref();
+    if (signal) {
+      onAbort = () => reject(new CancelledError('Task cancelled by user.'));
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+  try {
+    return await Promise.race([promise, guard]);
+  } finally {
+    clearTimeout(timer);
+    if (onAbort) signal.removeEventListener('abort', onAbort);
+  }
+}
+
+/**
+ * Open one MCP connection and discover its tools.
+ *
+ * @param {object} provider provider descriptor
+ * @param {object} options
+ * @param {number} options.timeoutMs
+ * @param {AbortSignal} [options.signal]
+ * @returns {Promise<{client: object, tools: object[]}>}
+ */
+export async function connectProvider(provider, { timeoutMs = 8000, signal = null, logger = null } = {}) {
+  const client = new Client(CLIENT_INFO, { capabilities: {} });
+  let transport;
+  try {
+    if (provider.transport === 'stdio') {
+      transport = new StdioClientTransport({
+        command: provider.command,
+        args: provider.args || [],
+        env: safeChildEnv(provider.env),
+        cwd: provider.cwd || process.cwd(),
+        stderr: 'pipe',
+      });
+    } else {
+      transport = new StreamableHTTPClientTransport(new URL(provider.url), {
+        requestInit: { headers: provider.headers || {} },
+      });
+    }
+    await withTimeout(client.connect(transport), {
+      timeoutMs,
+      signal,
+      label: `${provider.label} handshake`,
+    });
+  } catch (error) {
+    await closeQuietly(client, transport);
+    throw mcpError(error, { provider, phase: 'handshake' });
+  }
+
+  try {
+    const listed = await withTimeout(client.listTools(undefined, { timeout: timeoutMs }), {
+      timeoutMs,
+      signal,
+      label: `${provider.label} tool discovery`,
+    });
+    const tools = Array.isArray(listed?.tools) ? listed.tools : [];
+    logger?.debug('mcp provider discovered', {
+      provider: provider.id,
+      tools: tools.map((tool) => tool.name).slice(0, 20),
+    });
+    return { client, tools };
+  } catch (error) {
+    await closeQuietly(client, transport);
+    throw mcpError(error, { provider, phase: 'discovery' });
+  }
+}
+
+/**
+ * Call one discovered tool. The SDK validates the result envelope; the caller
+ * normalizes the payload.
+ */
+export async function callTool(connection, { name, args, timeoutMs = 8000, signal = null }) {
+  return withTimeout(
+    connection.client.callTool({ name, arguments: args }, undefined, { timeout: timeoutMs, signal }),
+    { timeoutMs, signal, label: `${name}` },
+  );
+}
+
+async function closeQuietly(client, transport) {
+  try {
+    if (typeof client?.close === 'function') await client.close();
+    else if (typeof transport?.close === 'function') await transport.close();
+  } catch {
+    // Closing a broken transport is best-effort.
+  }
+}
+
+export async function closeConnection(connection) {
+  if (!connection) return;
+  try {
+    if (typeof connection.client?.close === 'function') await connection.client.close();
+    else if (typeof connection.transport?.close === 'function') await connection.transport.close();
+  } catch {
+    // best-effort
+  }
+}

package/src/services/websearch/normalize.js

@@ -0,0 +1,284 @@
+/**
+ * Normalization for MCP tool results.
+ *
+ * Every provider speaks a different dialect: You.com nests results under
+ * `results.web`, Firecrawl under `data.web`, Tavily under `results`, and a
+ * community server may only return Markdown. The agent must never see those
+ * differences, so everything is reduced to:
+ *
+ *   { provider, query, results: [{ title, url, snippet, content?, date? }] }
+ *
+ * Rules: only http(s) URLs without credentials, dedupe by canonical URL, cap
+ * counts and text length, and never invent a title, snippet or source.
+ */
+
+import { SearchError } from '../../utils/errors.js';
+
+const MAX_TITLE = 200;
+const MAX_SNIPPET = 320;
+const MAX_URL = 500;
+const MAX_TEXT = 50000;
+
+const clean = (value, max) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+
+/** Canonical URL for dedupe: lowercased host, no fragment, no trailing slash. */
+export function canonicalUrl(value) {
+  try {
+    const url = new URL(String(value));
+    if (!['http:', 'https:'].includes(url.protocol)) return null;
+    if (url.username || url.password) return null;
+    url.hash = '';
+    if (url.pathname !== '/' && url.pathname.endsWith('/')) url.pathname = url.pathname.slice(0, -1);
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+/** Pull the structured payload out of an MCP call result (or null). */
+export function extractPayload(callResult) {
+  if (!callResult || typeof callResult !== 'object') return null;
+  if (callResult.structuredContent && typeof callResult.structuredContent === 'object') {
+    return callResult.structuredContent;
+  }
+  for (const item of Array.isArray(callResult.content) ? callResult.content : []) {
+    if (item?.type !== 'text' || typeof item.text !== 'string' || !item.text.trim()) continue;
+    const text = item.text.trim();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return null;
+}
+
+/** Collect candidate result arrays from the known provider dialects. */
+function candidateLists(payload) {
+  if (!payload) return [];
+  if (Array.isArray(payload)) return [payload];
+  if (typeof payload !== 'object') return [];
+  const lists = [];
+  const push = (value) => {
+    if (Array.isArray(value)) lists.push(value);
+  };
+  push(payload.results);
+  push(payload.results?.web);
+  push(payload.results?.news);
+  push(payload.web);
+  push(payload.data?.web);
+  push(payload.data?.results);
+  push(payload.data);
+  push(payload.organic);
+  push(payload.organic_results);
+  push(payload.items);
+  push(payload.pages);
+  return lists;
+}
+
+function snippetOf(item) {
+  const direct = item.snippet || item.description || item.summary || item.text || item.content;
+  if (typeof direct === 'string' && direct.trim()) return clean(direct, MAX_SNIPPET);
+  const highlights = item.contents?.highlights || item.highlights;
+  if (Array.isArray(highlights)) return clean(highlights.join(' '), MAX_SNIPPET);
+  if (typeof item.markdown === 'string') return clean(item.markdown, MAX_SNIPPET);
+  return null;
+}
+
+/**
+ * Normalize a search payload.
+ *
+ * @returns {{results: object[], answer_box: object|null, people_also_ask: object[], related_searches: string[], format: string}}
+ * @throws {SearchError} when the payload is not a recognizable shape
+ */
+export function normalizeSearchPayload(payload, { maxResults = 5 } = {}) {
+  const limit = Math.max(1, Math.min(Number(maxResults) || 5, 10));
+  let raw = payload;
+
+  // JSON encoded inside a text item was already parsed by extractPayload; a
+  // plain string here is either Markdown links or unusable prose.
+  if (typeof raw === 'string') {
+    const results = parseMarkdownLinks(raw, limit);
+    if (results.length === 0) {
+      throw new SearchError('The search provider returned text without any recognizable results.', {
+        code: 'MCP_BAD_RESPONSE',
+      });
+    }
+    return {
+      results,
+      answer_box: null,
+      people_also_ask: [],
+      related_searches: [],
+      format: 'markdown',
+    };
+  }
+  if (!raw || typeof raw !== 'object') {
+    throw new SearchError('The search provider returned an empty or invalid response.', {
+      code: 'MCP_BAD_RESPONSE',
+    });
+  }
+  if (raw.error && !raw.results) {
+    throw new SearchError(`The search provider returned an error: ${clean(raw.error, 300)}`, {
+      code: 'MCP_PROVIDER_ERROR',
+    });
+  }
+
+  const lists = candidateLists(raw);
+  const seen = new Set();
+  const results = [];
+  for (const list of lists) {
+    for (const item of list) {
+      if (!item || typeof item !== 'object') continue;
+      const rawUrl = item.url || item.link || item.href;
+      const identity = canonicalUrl(rawUrl);
+      if (!identity || seen.has(identity)) continue;
+      const title = clean(item.title || item.name || item.heading, MAX_TITLE);
+      if (!title) continue;
+      const snippet = snippetOf(item);
+      const date = clean(item.date || item.publishedDate || item.published_date || item.metadata?.publishedDate, 40);
+      seen.add(identity);
+      results.push({
+        rank: results.length + 1,
+        title,
+        // Keep the provider's URL (only normalized by the URL parser); the
+        // canonical form is used for dedupe, not for rewriting the source.
+        url: sourceUrl(rawUrl, identity),
+        snippet: snippet || null,
+        ...(date ? { date } : {}),
+      });
+      if (results.length >= limit) break;
+    }
+    if (results.length >= limit) break;
+  }
+
+  if (results.length === 0 && lists.length === 0 && !Array.isArray(raw)) {
+    // A structured response with no list at all is a schema mismatch, not a
+    // valid "no results" answer. Let the manager fall back to the next provider.
+    const keys = Object.keys(raw).slice(0, 8).join(', ');
+    throw new SearchError(`The search provider response has an unknown shape (keys: ${keys || 'none'}).`, {
+      code: 'MCP_BAD_RESPONSE',
+    });
+  }
+
+  return {
+    results,
+    answer_box: normalizeAnswerBox(raw),
+    people_also_ask: normalizePeopleAlsoAsk(raw),
+    related_searches: normalizeRelated(raw),
+    format: 'json',
+  };
+}
+
+function normalizeAnswerBox(payload) {
+  const box = payload.answer_box || payload.answerBox;
+  if (!box || typeof box !== 'object') return null;
+  const text = clean(box.answer || box.text || box.snippet || box.description, MAX_SNIPPET);
+  if (!text) return null;
+  return {
+    ...(box.title ? { title: clean(box.title, MAX_TITLE) } : {}),
+    text,
+    ...(canonicalUrl(box.url || box.link) ? { url: canonicalUrl(box.url || box.link) } : {}),
+  };
+}
+
+function normalizePeopleAlsoAsk(payload) {
+  const list = payload.people_also_ask || payload.peopleAlsoAsk || payload.related_questions;
+  if (!Array.isArray(list)) return [];
+  return list
+    .map((item) => ({
+      question: clean(item?.question || item?.title, MAX_TITLE),
+      snippet: clean(item?.snippet || item?.answer || item?.description, MAX_SNIPPET) || null,
+    }))
+    .filter((item) => item.question)
+    .slice(0, 4);
+}
+
+function normalizeRelated(payload) {
+  const list = payload.related_searches || payload.relatedSearches;
+  if (!Array.isArray(list)) return [];
+  return list
+    .map((item) => clean(typeof item === 'string' ? item : item?.query, 160))
+    .filter(Boolean)
+    .slice(0, 5);
+}
+
+/** Parse `[title](url)` lines from text-only MCP servers. */
+function parseMarkdownLinks(text, limit) {
+  const results = [];
+  const seen = new Set();
+  const pattern = /\[([^\]]{1,200})\]\((https?:\/\/[^\s)]{1,500})\)/g;
+  let match;
+  while ((match = pattern.exec(text)) && results.length < limit) {
+    const identity = canonicalUrl(match[2]);
+    if (!identity || seen.has(identity)) continue;
+    seen.add(identity);
+    const after = text.slice(pattern.lastIndex).split('\n')[0].replace(/^[\s:–—-]+/, '');
+    results.push({
+      rank: results.length + 1,
+      title: clean(match[1], MAX_TITLE),
+      url: sourceUrl(match[2], identity),
+      snippet: after ? clean(after, MAX_SNIPPET) : null,
+    });
+  }
+  return results;
+}
+
+/** Keep the provider's URL but reject anything the URL parser cannot read. */
+function sourceUrl(value, fallback) {
+  try {
+    const parsed = new URL(String(value));
+    if (!['http:', 'https:'].includes(parsed.protocol)) return fallback;
+    return parsed.toString();
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Normalize an extraction result to `{title, text, url}`.
+ * Missing text is a valid empty extraction, not an error.
+ */
+export function normalizeExtractPayload(payload, { url = null } = {}) {
+  const empty = { title: '', text: '', url };
+  if (typeof payload === 'string') {
+    return { ...empty, text: cleanText(payload) };
+  }
+  if (!payload || typeof payload !== 'object') return empty;
+  const data = payload.data && typeof payload.data === 'object' ? payload.data : payload;
+  const first = Array.isArray(data.results) ? data.results[0] : null;
+  const text =
+    firstString(
+      data.markdown,
+      data.content,
+      data.text,
+      data.rawContent,
+      data.raw_content,
+      payload.markdown,
+      payload.text,
+      first?.raw_content,
+      first?.rawContent,
+      first?.content,
+      first?.text,
+    ) || '';
+  const title = clean(data.title || data.metadata?.title || first?.title || payload.title, 300);
+  const finalUrl = canonicalUrl(data.url || data.metadata?.sourceURL || first?.url || url) || url;
+  return { title, text: cleanText(text), url: finalUrl };
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value;
+  }
+  return '';
+}
+
+function cleanText(text) {
+  return String(text ?? '')
+    .replace(/\r\n?/g, '\n')
+    .replace(/[ \t]+$/gm, '')
+    .replace(/\n{4,}/g, '\n\n\n')
+    .trim()
+    .slice(0, MAX_TEXT);
+}
+
+export const NORMALIZE_LIMITS = { MAX_TITLE, MAX_SNIPPET, MAX_URL, MAX_TEXT };

package/src/services/websearch/providers.js

@@ -0,0 +1,178 @@
+/**
+ * Provider presets for web search.
+ *
+ * Endpoints and tool names were checked against the live servers (You.com and
+ * Firecrawl answered MCP discovery on 2026-10-23). Capabilities are *declared*
+ * here only as hints; the manager maps the tools that discovery actually
+ * returns, so a provider that changes its tool set keeps working.
+ *
+ * API keys are optional where the service allows keyless use. They are read
+ * from config.json and placed in request headers, never in a URL or log.
+ */
+
+import { createSerperProvider } from './serper.js';
+
+export const PROVIDER_IDS = ['serper', 'you', 'firecrawl', 'duckduckgo', 'tavily'];
+
+export const DEFAULT_PROVIDER_ORDER = ['serper', 'you', 'firecrawl', 'duckduckgo', 'tavily'];
+
+export const PROVIDER_INFO = {
+  serper: {
+    label: 'Serper',
+    transport: 'https',
+    requiresKey: true,
+    keySetting: 'webSearch.serperApiKey',
+    docs: 'https://serper.dev',
+    note: 'Serper-compatible SERP REST API (pre-existing backend).',
+  },
+  you: {
+    label: 'You.com',
+    transport: 'streamable-http',
+    requiresKey: false,
+    keySetting: 'webSearch.youApiKey',
+    docs: 'https://you.com/docs/agents/mcp-server',
+    note: 'Free profile is keyless and search-only; a key adds contents/discovery tools.',
+  },
+  firecrawl: {
+    label: 'Firecrawl',
+    transport: 'streamable-http',
+    requiresKey: false,
+    keySetting: 'webSearch.firecrawlApiKey',
+    docs: 'https://docs.firecrawl.dev/mcp-server/keyless',
+    note: 'Keyless search + scrape with a daily credit cap; a key raises limits.',
+  },
+  duckduckgo: {
+    label: 'DuckDuckGo',
+    transport: 'stdio',
+    requiresKey: false,
+    keySetting: null,
+    docs: 'https://github.com/sweetcornna/free-search-mcp',
+    note: 'Local community server (MIT). Disabled by default: it runs third-party code and needs uv/uvx.',
+  },
+  tavily: {
+    label: 'Tavily',
+    transport: 'streamable-http',
+    requiresKey: true,
+    keySetting: 'webSearch.tavilyApiKey',
+    docs: 'https://docs.tavily.com/documentation/mcp',
+    note: 'Agent-oriented search and extraction; API key required by the remote MCP endpoint.',
+  },
+};
+
+const trim = (value) => String(value ?? '').trim();
+
+/** Build the provider descriptors in the configured order. */
+export function buildProviders(config = {}, { fetch = null } = {}) {
+  const order = Array.isArray(config.webSearchProviders) && config.webSearchProviders.length > 0
+    ? config.webSearchProviders
+    : DEFAULT_PROVIDER_ORDER;
+  const disabled = new Set(Array.isArray(config.webSearchDisabled) ? config.webSearchDisabled : []);
+  const providers = [];
+
+  for (const id of order) {
+    if (!PROVIDER_IDS.includes(id)) continue;
+    if (id === 'serper') {
+      const provider = createSerperProvider({ config, fetch });
+      provider.enabled = !disabled.has('serper');
+      providers.push(provider);
+      continue;
+    }
+
+    if (id === 'you') {
+      const apiKey = trim(config.youApiKey);
+      providers.push({
+        id: 'you',
+        label: 'You.com',
+        kind: 'mcp',
+        transport: 'streamable-http',
+        url: apiKey ? 'https://api.you.com/mcp' : 'https://api.you.com/mcp?profile=free',
+        headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+        requiresKey: false,
+        configured: true,
+        enabled: !disabled.has('you'),
+        authenticated: Boolean(apiKey),
+        // With a key the default tool allowlist includes you-contents; without
+        // one the free profile is search-only (confirmed by discovery).
+        capabilities: { search: true, extract: Boolean(apiKey) },
+        keySetting: 'webSearch.youApiKey',
+      });
+      continue;
+    }
+
+    if (id === 'firecrawl') {
+      const apiKey = trim(config.firecrawlApiKey);
+      providers.push({
+        id: 'firecrawl',
+        label: 'Firecrawl',
+        kind: 'mcp',
+        transport: 'streamable-http',
+        url: 'https://mcp.firecrawl.dev/v2/mcp',
+        headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+        requiresKey: false,
+        configured: true,
+        enabled: !disabled.has('firecrawl'),
+        authenticated: Boolean(apiKey),
+        capabilities: { search: true, extract: true },
+        keySetting: 'webSearch.firecrawlApiKey',
+      });
+      continue;
+    }
+
+    if (id === 'duckduckgo') {
+      const command = trim(config.duckduckgoMcpCommand) || 'uvx';
+      const args = Array.isArray(config.duckduckgoMcpArgs) && config.duckduckgoMcpArgs.length > 0
+        ? config.duckduckgoMcpArgs
+        : ['free-search-mcp'];
+      providers.push({
+        id: 'duckduckgo',
+        label: 'DuckDuckGo',
+        kind: 'mcp',
+        transport: 'stdio',
+        command,
+        args,
+        env: {},
+        requiresKey: false,
+        configured: Boolean(command),
+        enabled: Boolean(config.duckduckgoMcpEnabled) && !disabled.has('duckduckgo'),
+        capabilities: { search: true, extract: true },
+        keySetting: null,
+      });
+      continue;
+    }
+
+    if (id === 'tavily') {
+      const apiKey = trim(config.tavilyApiKey);
+      providers.push({
+        id: 'tavily',
+        label: 'Tavily',
+        kind: 'mcp',
+        transport: 'streamable-http',
+        url: 'https://mcp.tavily.com/mcp/',
+        headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+        requiresKey: true,
+        configured: Boolean(apiKey),
+        enabled: !disabled.has('tavily'),
+        authenticated: Boolean(apiKey),
+        capabilities: { search: true, extract: true },
+        keySetting: 'webSearch.tavilyApiKey',
+      });
+    }
+  }
+
+  return providers;
+}
+
+/** Public, secret-free view of a provider for `/web` and logs. */
+export function describeProvider(provider) {
+  return {
+    id: provider.id,
+    label: provider.label,
+    transport: provider.transport,
+    enabled: provider.enabled,
+    configured: provider.configured,
+    requiresKey: provider.requiresKey,
+    authenticated: Boolean(provider.authenticated),
+    capabilities: { ...provider.capabilities },
+    keySetting: provider.keySetting || null,
+  };
+}