@yeaft/webchat-agent 1.0.638 → 1.0.640

package/yeaft/tools/view-image.js

@@ -29,6 +29,7 @@ import { stat, readFile } from 'fs/promises';
 import { existsSync } from 'fs';
 import { resolve, extname, isAbsolute } from 'path';
 import { checkPathAllowed } from './path-safety.js';
+import { readPersistedAttachmentFile, resolvePersistedAttachmentPath } from '../attachments.js';
 
 /** Default max image size in bytes (20 MiB). Override via ctx.maxImageBytes. */
 const DEFAULT_MAX_IMAGE_BYTES = 20 * 1024 * 1024;
@@ -149,7 +150,7 @@ Path examples:
 
 Supported formats: PNG, JPEG (.jpg/.jpeg/.jfif), GIF, WebP.
 Max size: 20 MiB by default (configurable via ctx.maxImageBytes).
-Path must live under the project directory or an explicit host allowlist.`,
+Path must live under the project directory, the current Session's attachments, or an explicit host allowlist. Attachments from other Sessions are not allowed.`,
     zh: `加载本地图片文件并附加到对话中，使 LLM 可以查看。
 
 返回 base64 data URI（image 字段）及元数据（格式、尺寸、大小）。引擎将图片作为原生多模态工具结果交给模型。
@@ -170,7 +171,7 @@ Path must live under the project directory or an explicit host allowlist.`,
 
 支持格式：PNG、JPEG（.jpg/.jpeg/.jfif）、GIF、WebP。
 最大文件：默认 20 MiB（可通过 ctx.maxImageBytes 配置）。
-路径必须在项目目录下或已加入宿主白名单。`
+路径必须在项目目录、当前 Session 的附件目录下或已加入宿主白名单；不允许读取其他 Session 的附件。`
   },
   parameters: {
     type: 'object',
@@ -216,8 +217,14 @@ Path must live under the project directory or an explicit host allowlist.`,
         : DEFAULT_MAX_IMAGE_BYTES;
     const absPath = resolve(cwd, file_path);
 
+    // Session uploads intentionally live outside workDir. Reuse the same
+    // owner + no-symlink resolver as history/preview, never allow the whole
+    // instance's sessions directory just to make an uploaded image readable.
+    const attachmentOptions = { yeaftDir: ctx?.yeaftDir, sessionId: ctx?.sessionId, cwd };
+    const sessionAttachment = Boolean(ctx?.yeaftDir && ctx?.sessionId
+      && resolvePersistedAttachmentPath(file_path, attachmentOptions));
     const pathErr = checkPathAllowed(absPath, cwd, allowlist);
-    if (pathErr) {
+    if (pathErr && !sessionAttachment) {
       // prev-3 P2: split "absolute outside project" from "relative ..".
       // The `..` case is already handled above, so anything reaching here
       // is either an absolute path outside cwd/allowlist or a relative
@@ -229,6 +236,9 @@ Path must live under the project directory or an explicit host allowlist.`,
         : 'Resolved path is outside the project directory. ';
       return JSON.stringify({
         error: hint + pathErr.message,
+        code: 'image_path_denied',
+        errorEffect: 'none',
+        hint: 'Use the current Session attachment path, a project image, or an explicitly allowlisted directory.',
         path: absPath,
       });
     }
@@ -254,37 +264,48 @@ Path must live under the project directory or an explicit host allowlist.`,
       });
     }
 
-    if (!existsSync(absPath)) {
-      return JSON.stringify({ error: `Image not found: ${absPath}` });
-    }
+    let buffer;
+    let modified;
+    if (sessionAttachment) {
+      try {
+        // Recheck ownership and symlinks at the actual bounded file read.
+        ({ buffer, modified } = readPersistedAttachmentFile(file_path, attachmentOptions, maxBytes));
+      } catch (err) {
+        return JSON.stringify({ error: `Failed to read Session image: ${err.message}`, code: 'image_attachment_unavailable', errorEffect: 'none' });
+      }
+    } else {
+      if (!existsSync(absPath)) {
+        return JSON.stringify({ error: `Image not found: ${absPath}`, code: 'image_not_found', errorEffect: 'none' });
+      }
 
-    let fileStat;
-    try {
-      fileStat = await stat(absPath);
-    } catch (err) {
-      return JSON.stringify({ error: `Failed to stat image: ${err.message}` });
-    }
+      let fileStat;
+      try {
+        fileStat = await stat(absPath);
+      } catch (err) {
+        return JSON.stringify({ error: `Failed to stat image: ${err.message}` });
+      }
 
-    if (!fileStat.isFile()) {
-      return JSON.stringify({ error: 'file_path does not point to a regular file' });
-    }
+      if (!fileStat.isFile()) {
+        return JSON.stringify({ error: 'file_path does not point to a regular file' });
+      }
 
-    if (fileStat.size > maxBytes) {
-      return JSON.stringify({
-        error:
-          `Image exceeds ${formatBytes(maxBytes)} (${formatBytes(fileStat.size)} actual). ` +
-          `Reduce image size (resize/crop), or set \`maxImageBytes\` in ` +
-          `~/.yeaft/config.json if your LLM supports more.`,
-        size: fileStat.size,
-        maxSize: maxBytes,
-      });
-    }
+      if (fileStat.size > maxBytes) {
+        return JSON.stringify({
+          error:
+            `Image exceeds ${formatBytes(maxBytes)} (${formatBytes(fileStat.size)} actual). ` +
+            `Reduce image size (resize/crop), or set \`maxImageBytes\` in ` +
+            `~/.yeaft/config.json if your LLM supports more.`,
+          size: fileStat.size,
+          maxSize: maxBytes,
+        });
+      }
 
-    let buffer;
-    try {
-      buffer = await readFile(absPath);
-    } catch (err) {
-      return JSON.stringify({ error: `Failed to read image: ${err.message}` });
+      try {
+        buffer = await readFile(absPath);
+      } catch (err) {
+        return JSON.stringify({ error: `Failed to read image: ${err.message}` });
+      }
+      modified = fileStat.mtime.toISOString();
     }
 
     const mediaType = EXT_TO_MIME[ext];
@@ -296,9 +317,9 @@ Path must live under the project directory or an explicit host allowlist.`,
       path: absPath,
       format: ext.slice(1).toUpperCase() === 'JPG' ? 'JPEG' : ext.slice(1).toUpperCase(),
       media_type: mediaType,
-      size: fileStat.size,
-      sizeFormatted: formatBytes(fileStat.size),
-      modified: fileStat.mtime.toISOString(),
+      size: buffer.length,
+      sizeFormatted: formatBytes(buffer.length),
+      modified,
       image: dataUri,
     };
     // Normalise .jfif to JPEG in display format too, for consistency.

package/yeaft/tools/web-fetch.js

@@ -6,6 +6,10 @@
  */
 
 import { defineTool } from './types.js';
+import {
+  attachResearchGuidance, canonicalWebUrl, recordWebResearchCall, safeWebUrl, setBounded,
+  shareWebRequest, webFetchKey, webHttpFailure, webRequestFailure, withWebDeadline,
+} from '../web-research.js';
 
 /** Strip HTML tags and normalize whitespace for readability. */
 function htmlToText(html) {
@@ -98,69 +102,73 @@ Guidelines:
   },
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
-  // Live waiting is explicit; raw formatting alone never exempts static reads.
+  // Success-only reuse and active sharing belong to the query ledger, not Engine's cache.
   duplicateCallPolicy: (input) => input?.polling === true ? 'allow' : 'warn',
   async execute(input, ctx) {
-    const { url, max_length = 50000, raw = false } = input;
-    if (!url) return JSON.stringify({ error: 'url is required' });
-
+    const { url, max_length = 50000, raw = false, polling = false } = input;
+    const research = ctx?.webResearch;
+    const signal = ctx?.signal;
+    const visibleUrl = safeWebUrl(url);
+    let canonicalUrl;
     try {
-      // Validate URL
-      let parsedUrl;
-      try {
-        parsedUrl = new URL(url);
-      } catch {
-        return JSON.stringify({ error: `Invalid URL: ${url}` });
-      }
-
-      // Only allow http(s)
-      if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
-        return JSON.stringify({ error: `Unsupported protocol: ${parsedUrl.protocol}` });
-      }
+      canonicalUrl = canonicalWebUrl(url);
+      if (!['http:', 'https:'].includes(new URL(canonicalUrl).protocol)) throw new Error('Only HTTP(S) URLs are supported');
+      if (!Number.isInteger(max_length) || max_length < 1) throw new Error('max_length must be a positive integer');
+    } catch {
+      return JSON.stringify({ error: 'Invalid fetch input: a full HTTP(S) URL and positive integer max_length are required', code: 'invalid_arguments', errorEffect: 'none', hint: 'Provide a full HTTP(S) URL and a positive integer max_length.' });
+    }
 
-      const response = await fetch(url, {
-        signal: ctx?.signal,
-        headers: {
-          'User-Agent': 'Yeaft/1.0 (compatible; bot)',
-          'Accept': 'text/html, application/json, text/plain, */*',
-        },
-        redirect: 'follow',
+    try {
+      signal?.throwIfAborted();
+      const key = webFetchKey(canonicalUrl, { raw, maxLength: max_length });
+      const prior = !polling && research?.fetches.get(key);
+      if (prior) return attachResearchGuidance(prior, research, {
+        reused: true, reuseReason: 'This URL and response mode already succeeded in this query. Use polling:true only for requested live status checks.',
       });
-
-      if (!response.ok) {
-        return JSON.stringify({
-          error: `HTTP ${response.status}: ${response.statusText}`,
-          url,
-        });
-      }
-
-      const contentType = response.headers.get('content-type') || '';
-      const body = await response.text();
-
-      let content;
-      if (raw || contentType.includes('json') || contentType.includes('text/plain')) {
-        content = body;
-      } else {
-        content = htmlToText(body);
-      }
-
-      // Truncate if too long
-      const truncated = content.length > max_length;
-      if (truncated) {
-        content = content.slice(0, max_length);
-      }
-
-      return JSON.stringify({
-        url: response.url, // final URL after redirects
-        status: response.status,
-        contentType,
-        contentLength: content.length,
-        truncated,
-        content,
+      const output = await shareWebRequest(research, JSON.stringify(['fetch', key, polling]), signal, async () => {
+        let result;
+        try {
+          result = await withWebDeadline(signal, async bounded => {
+            const response = await fetch(canonicalUrl, {
+              signal: bounded,
+              headers: { 'User-Agent': 'Yeaft/1.0 (compatible; bot)', Accept: 'text/html, application/json, text/plain, */*' },
+              redirect: 'follow',
+            });
+            const finalUrl = safeWebUrl(response.url || canonicalUrl) || visibleUrl;
+            if (!response.ok) return { ...webHttpFailure(response.status), url: finalUrl };
+            const contentType = response.headers.get('content-type') || '';
+            const body = await response.text();
+            const content = raw || contentType.includes('json') || contentType.includes('text/plain') ? body : htmlToText(body);
+            return {
+              url: finalUrl, status: response.status, contentType,
+              contentLength: Math.min(content.length, max_length), truncated: content.length > max_length,
+              content: content.slice(0, max_length),
+            };
+          });
+          signal?.throwIfAborted();
+        } catch (error) {
+          result = { ...webRequestFailure(error, signal), url: visibleUrl };
+        }
+        recordWebResearchCall(research);
+        const previousAuth = research?.authorizationFailures.get(canonicalUrl);
+        if (previousAuth && result.error) {
+          result.priorAuthorizationFailure = previousAuth;
+          result.hint += ' This same URL previously denied access in this query; check public access before retrying.';
+        }
+        const output = JSON.stringify(result);
+        if (research) {
+          if (!result.error) {
+            setBounded(research.fetches, key, output);
+            research.authorizationFailures.delete(canonicalUrl);
+          } else if ([401, 403].includes(result.status)) {
+            setBounded(research.authorizationFailures, canonicalUrl, { status: result.status, url: result.url });
+          }
+        }
+        return output;
       });
-    } catch (err) {
-      if (err.name === 'AbortError') return JSON.stringify({ error: 'Fetch cancelled' });
-      return JSON.stringify({ error: `Fetch failed: ${err.message}`, url });
+      return attachResearchGuidance(output, research);
+    } catch (error) {
+      return attachResearchGuidance({ ...webRequestFailure(error, signal), url: visibleUrl }, research);
     }
   },
 });

package/yeaft/tools/web-search.js

@@ -22,6 +22,11 @@
  */
 
 import { defineTool } from './types.js';
+import {
+  attachResearchGuidance, findPriorSearch, findRelatedSearch, normalizeSearchQuery,
+  recordSearch, recordWebResearchCall, shareWebRequest, webHttpFailure,
+  webRequestFailure, withWebDeadline,
+} from '../web-research.js';
 
 export default defineTool({
   name: 'WebSearch',
@@ -66,147 +71,134 @@ Guidelines:
   },
   isConcurrencySafe: () => true,
   isReadOnly: () => true,
+  // The ledger caches successes only; Engine's general cache would freeze errors.
   async execute(input, ctx) {
-    const { query, limit = 5 } = input;
-    if (!query || typeof query !== 'string') {
-      return JSON.stringify({ error: 'query is required' });
+    const query = normalizeSearchQuery(input.query);
+    const limit = input.limit ?? 5;
+    if (typeof input.query !== 'string' || !query || !Number.isInteger(limit) || limit < 1) {
+      return JSON.stringify({ error: 'query must be non-empty text and limit a positive integer', code: 'invalid_arguments', errorEffect: 'none', hint: 'Supply a targeted query and a positive integer result limit.' });
     }
 
-    const search = ctx?.config?.search || {};
+    const research = ctx?.webResearch;
     const signal = ctx?.signal;
-    const errors = [];
-
-    // Backend preference set in YeaftSettings → Search tab. When the
-    // user picks `playwright` we'd normally call the playwright-service;
-    // that service is not yet shipped (next PR), so the preference is
-    // recorded for forward-compat and we transparently fall through to
-    // Tavily / HTML scrape. Once the service lands we'll insert a
-    // tryPlaywright backend here ahead of Tavily.
-    // Anything other than 'playwright' is treated as 'tavily'.
-
-    // 1. Tavily — default, fast, structured.
-    if (search.tavilyApiKey) {
-      const r = await tryTavily(query, limit, search.tavilyApiKey, signal);
-      if (r.ok) return JSON.stringify(r.data, null, 2);
-      errors.push(`tavily: ${r.error}`);
-    }
-
-    // 2. Generic JSON endpoint (legacy escape hatch — SearXNG, custom proxy, etc).
-    const genericUrl = search.searchApiUrl || ctx?.config?.searchApiUrl;
-    if (genericUrl) {
-      const r = await tryGenericApi(query, limit, genericUrl, signal);
-      if (r.ok) return JSON.stringify(r.data, null, 2);
-      errors.push(`searchApiUrl: ${r.error}`);
+    try {
+      signal?.throwIfAborted();
+      const prior = findPriorSearch(research, query, limit);
+      if (prior) {
+        const data = JSON.parse(prior.output);
+        return attachResearchGuidance({ ...data, results: data.results.slice(0, limit) }, research, {
+          reused: true, priorQuery: prior.query,
+          reuseReason: 'This exact trimmed query already succeeded with at least the requested limit in this query.',
+        });
+      }
+      const related = findRelatedSearch(research, query);
+      const output = await shareWebRequest(research, JSON.stringify(['search', query, limit]), signal, async () => {
+        const result = await searchWeb(query, limit, ctx);
+        recordWebResearchCall(research);
+        const output = JSON.stringify(result);
+        if (!result.error) recordSearch(research, query, limit, output);
+        return output;
+      });
+      return attachResearchGuidance(output, research, related ? {
+        relatedPriorQuery: related.query,
+        convergenceHint: 'A similar query already completed. Use this result for the specific unresolved fact; semantic variants are not interchangeable.',
+      } : {});
+    } catch (error) {
+      return attachResearchGuidance(webRequestFailure(error, signal), research);
     }
-
-    // 3. HTML-scrape fallback. Often blocked on cloud IPs; useful for
-    //    self-hosted / residential setups with no API key.
-    if (!search.disableHtmlFallback) {
-      const r = await tryHtmlScrape(query, limit, signal);
-      if (r.ok) return JSON.stringify(r.data, null, 2);
-      errors.push(`html: ${r.error}`);
-    }
-
-    return JSON.stringify({
-      error: 'No web search backend succeeded.',
-      attempted: errors,
-      hint: 'Set search.tavilyApiKey in ~/.yeaft/config.json (free tier: https://tavily.com).',
-    });
   },
 });
 
+async function searchWeb(query, limit, ctx) {
+  const search = ctx?.config?.search || {};
+  const signal = ctx?.signal;
+  const failures = [];
+  const backends = [];
+  if (search.tavilyApiKey) backends.push(['tavily', bounded => tryTavily(query, limit, search.tavilyApiKey, bounded)]);
+  const genericUrl = search.searchApiUrl || ctx?.config?.searchApiUrl;
+  if (genericUrl) backends.push(['generic', bounded => tryGenericApi(query, limit, genericUrl, bounded)]);
+  if (!search.disableHtmlFallback) {
+    backends.push(['duckduckgo-html', bounded => tryHtmlScrape(query, limit, 'duckduckgo-html', bounded)]);
+    backends.push(['bing-html', bounded => tryHtmlScrape(query, limit, 'bing-html', bounded)]);
+  }
+  for (const [provider, work] of backends) {
+    signal?.throwIfAborted();
+    try {
+      const result = await withWebDeadline(signal, work);
+      signal?.throwIfAborted();
+      if (!result.error) return result;
+      failures.push({ provider, ...result });
+    } catch (error) {
+      const failure = webRequestFailure(error, signal);
+      // Cancellation is terminal: never start the next backend.
+      if (failure.code === 'cancelled') return { ...failure, query, failures };
+      failures.push({ provider, ...failure });
+    }
+  }
+  const last = failures.at(-1);
+  return {
+    error: 'No web search backend succeeded.', code: 'search_unavailable', errorEffect: 'none', query,
+    ...(last?.status ? { status: last.status } : {}),
+    attempted: failures.map(failure => `${failure.provider}: ${failure.error}`), failures,
+    hint: 'Inspect backend failures: HTML search may be bot-blocked or its markup may have changed. Use a known official URL with WebFetch or another available source; verify an already configured search endpoint if applicable. Rephrasing alone will not fix access failures.',
+  };
+}
+
 // ─── Backend implementations ────────────────────────────────────────
 
 async function tryTavily(query, limit, apiKey, signal) {
-  try {
-    const res = await fetch('https://api.tavily.com/search', {
-      method: 'POST',
-      signal,
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        api_key: apiKey,
-        query,
-        max_results: Math.max(1, Math.min(limit, 10)),
-        include_answer: true,
-        search_depth: 'basic',
-      }),
-    });
-    if (!res.ok) {
-      const text = await res.text().catch(() => '');
-      return { ok: false, error: `${res.status} ${res.statusText} ${text.slice(0, 200)}` };
-    }
-    const data = await res.json();
-    return {
-      ok: true,
-      data: {
-        provider: 'tavily',
-        query,
-        answer: data.answer || null,
-        results: (data.results || []).slice(0, limit).map((r) => ({
-          title: r.title,
-          url: r.url,
-          snippet: r.content,
-          score: r.score,
-        })),
-      },
-    };
-  } catch (err) {
-    if (err?.name === 'AbortError') return { ok: false, error: 'cancelled' };
-    return { ok: false, error: err.message || String(err) };
-  }
+  const res = await fetch('https://api.tavily.com/search', {
+    method: 'POST', signal,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ api_key: apiKey, query, max_results: Math.min(limit, 10), include_answer: true, search_depth: 'basic' }),
+  });
+  if (!res.ok) return webHttpFailure(res.status);
+  const data = await res.json();
+  if (!Array.isArray(data?.results) || data.error) return invalidSearchResponse();
+  return {
+    provider: 'tavily', query, answer: data.answer || null,
+    results: data.results.slice(0, limit).map(r => ({ title: r.title, url: r.url, snippet: r.content, score: r.score })),
+  };
 }
 
 async function tryGenericApi(query, limit, urlStr, signal) {
-  try {
-    const url = new URL(urlStr);
-    url.searchParams.set('q', query);
-    url.searchParams.set('limit', String(limit));
-    const res = await fetch(url.toString(), {
-      signal,
-      headers: { 'User-Agent': 'Yeaft/1.0', Accept: 'application/json' },
-    });
-    if (!res.ok) return { ok: false, error: `${res.status} ${res.statusText}` };
-    const data = await res.json();
-    return { ok: true, data: { provider: 'generic', query, ...data } };
-  } catch (err) {
-    if (err?.name === 'AbortError') return { ok: false, error: 'cancelled' };
-    return { ok: false, error: err.message || String(err) };
-  }
+  const url = new URL(urlStr);
+  url.searchParams.set('q', query);
+  url.searchParams.set('limit', String(limit));
+  const res = await fetch(url.toString(), { signal, headers: { 'User-Agent': 'Yeaft/1.0', Accept: 'application/json' } });
+  if (!res.ok) return webHttpFailure(res.status);
+  const data = await res.json();
+  if (!Array.isArray(data?.results) || data.error) return invalidSearchResponse();
+  return { ...data, provider: 'generic', query, results: data.results.slice(0, limit) };
 }
 
-/**
- * HTML-scrape fallback. Tries DuckDuckGo's lite HTML endpoint first
- * (smaller markup, but more aggressive bot detection on cloud IPs),
- * then Bing. We intentionally keep the regex-based parsers minimal —
- * they break less than full DOM selectors when sites tweak markup.
- */
-async function tryHtmlScrape(query, limit, signal) {
-  const ua = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
-  const headers = { 'User-Agent': ua, 'Accept-Language': 'en-US,en;q=0.9' };
-
-  try {
-    const ddg = await fetch(`https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`, { signal, headers });
-    if (ddg.ok) {
-      const html = await ddg.text();
-      const results = parseDdgHtml(html, limit);
-      if (results.length) return { ok: true, data: { provider: 'duckduckgo-html', query, results } };
-    }
-  } catch (err) {
-    if (err?.name === 'AbortError') return { ok: false, error: 'cancelled' };
-  }
-
-  try {
-    const bing = await fetch(`https://www.bing.com/search?q=${encodeURIComponent(query)}`, { signal, headers });
-    if (bing.ok) {
-      const html = await bing.text();
-      const results = parseBingHtml(html, limit);
-      if (results.length) return { ok: true, data: { provider: 'bing-html', query, results } };
-    }
-  } catch (err) {
-    if (err?.name === 'AbortError') return { ok: false, error: 'cancelled' };
-  }
+function invalidSearchResponse() {
+  return { error: 'Search endpoint did not return a results array', code: 'invalid_response', errorEffect: 'none', hint: 'Verify the configured endpoint returns a JSON object with results: [], including for no matches.' };
+}
 
-  return { ok: false, error: 'all HTML scrape backends returned 0 results (likely bot-blocked)' };
+/** Zero matches need an explicit no-results marker, not an empty parser output. */
+async function tryHtmlScrape(query, limit, provider, signal) {
+  const ddg = provider === 'duckduckgo-html';
+  const endpoint = ddg ? 'https://html.duckduckgo.com/html/?q=' : 'https://www.bing.com/search?q=';
+  const res = await fetch(endpoint + encodeURIComponent(query), {
+    signal,
+    headers: {
+      'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      'Accept-Language': 'en-US,en;q=0.9',
+    },
+  });
+  if (!res.ok) return webHttpFailure(res.status);
+  const html = await res.text();
+  const blocked = /anomaly\.js|anomaly-modal|challenge-form|verify (?:that )?you(?:'re| are) (?:a )?human|unusual traffic|<title[^>]*>[^<]*(?:captcha|access denied)/i.test(html);
+  const results = ddg ? parseDdgHtml(html, limit) : parseBingHtml(html, limit);
+  const noMatches = ddg ? /class=["'][^"']*\bno-results\b|No results found for/i.test(html)
+    : /class=["'][^"']*\bb_no\b|There are no results for|No results found for/i.test(html);
+  if (!blocked && (results.length || noMatches)) return { provider, query, results };
+  return {
+    error: blocked ? 'HTML search returned a bot challenge' : 'HTML search markup was not recognized; zero matches are not confirmed',
+    code: blocked ? 'bot_blocked' : 'unrecognized_response', status: res.status, errorEffect: 'none',
+    hint: 'Use a known official URL or another available source. Retrying a rephrased query will not fix a bot challenge or parser mismatch.',
+  };
 }
 
 /**