min-agent 0.2.0 → 0.3.0

package/dist/tools/web_search.js

@@ -1,40 +1,718 @@
 import { tool, jsonSchema } from "ai";
 import { truncateToolOutput } from "../tool-output.js";
-const SEARXNG_BASE = "https://searxng.xc.lonae.com";
+import { readBodyLimited } from "../http.js";
+import { loadConfig } from "../config.js";
+import { configHint, describeFetchError, resolveBackendBase } from "./backend.js";
+/** Built-in Serper key; override via config or the env var below. */
+const DEFAULT_SERPER_API_KEY = "7913c19ae7a80320771b843ddffa152c9162c9f2";
+const SERPER_KEY_ENV = "MIN_AGENT_SERPER_API_KEY";
+const SERPER_API = "https://google.serper.dev/search";
+/** SearXNG is used when explicitly configured (webSearchURL / MIN_AGENT_SEARXNG_URL). */
+export const SEARXNG_BACKEND = {
+    envName: "MIN_AGENT_SEARXNG_URL",
+    configKey: "webSearchURL",
+    fallback: "https://searxng.xc.lonae.com",
+};
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+const SERPER_TIMEOUT_MS = 35000;
+const SEARCH_TIMEOUT_MS = 20000;
+const DEFAULT_MAX_RESULTS = 10;
+const MAX_RESULTS_LIMIT = 30;
+const SNIPPET_MAX_CHARS = 300;
+const DEFAULT_FALLBACK_ENGINES = "google,bing";
+/** SearXNG's built-in category names. */
+const VALID_CATEGORIES = new Set([
+    "general",
+    "images",
+    "videos",
+    "news",
+    "map",
+    "music",
+    "it",
+    "science",
+    "files",
+    "social media",
+]);
+/** Common near-misses models produce, mapped onto real category names. */
+const CATEGORY_ALIASES = {
+    web: "general",
+    text: "general",
+    default: "general",
+    image: "images",
+    picture: "images",
+    pictures: "images",
+    photo: "images",
+    photos: "images",
+    video: "videos",
+    movie: "videos",
+    movies: "videos",
+    maps: "map",
+    social: "social media",
+    socialmedia: "social media",
+    social_media: "social media",
+    "social-media": "social media",
+    tech: "it",
+    technology: "it",
+    code: "it",
+    programming: "it",
+    file: "files",
+    torrent: "files",
+    torrents: "files",
+    paper: "science",
+    papers: "science",
+    academic: "science",
+    scholar: "science",
+};
+const VALID_TIME_RANGES = new Set(["day", "week", "month", "year"]);
+/** Google's tbs time filter for each supported time_range value. */
+const TBS_BY_RANGE = {
+    day: "qdr:d",
+    week: "qdr:w",
+    month: "qdr:m",
+    year: "qdr:y",
+};
+/** ISO 639-1/2 with an optional region subtag, or SearXNG's "all". */
+const LANGUAGE_RE = /^(all|[a-z]{2,3}([-_][a-zA-Z]{2,4})?)$/;
+const EXACT_TRACKING_PARAMS = new Set([
+    "ref",
+    "ref_src",
+    "referrer",
+    "fbclid",
+    "gclid",
+    "msclkid",
+    "igshid",
+    "mc_cid",
+    "mc_eid",
+    "spm",
+    "source",
+]);
+const emptyResponse = () => ({
+    results: [],
+    answers: [],
+    suggestions: [],
+    corrections: [],
+    infoboxes: [],
+    unresponsive_engines: [],
+});
+function isString(v) {
+    return typeof v === "string";
+}
+function asResult(r) {
+    if (typeof r !== "object" || r === null)
+        return null;
+    const o = r;
+    if (!isString(o.url))
+        return null;
+    return {
+        title: isString(o.title) ? o.title : "",
+        url: o.url,
+        content: isString(o.content) ? o.content : "",
+        engine: isString(o.engine) ? o.engine : "",
+        score: typeof o.score === "number" ? o.score : 0,
+        publishedDate: isString(o.publishedDate) ? o.publishedDate : "",
+        imgSrc: isString(o.img_src) ? o.img_src : isString(o.thumbnail) ? o.thumbnail : "",
+    };
+}
+function parseResponse(data) {
+    if (typeof data !== "object" || data === null)
+        return emptyResponse();
+    const o = data;
+    const results = (Array.isArray(o.results) ? o.results : [])
+        .map(asResult)
+        .filter((r) => r !== null);
+    // Some engines return answers as objects ({ answer, url }) rather than plain strings.
+    const answers = (Array.isArray(o.answers) ? o.answers : [])
+        .map((a) => {
+        if (isString(a))
+            return a;
+        if (typeof a === "object" && a !== null) {
+            const rec = a;
+            if (isString(rec.answer))
+                return rec.answer;
+            if (isString(rec.content))
+                return rec.content;
+        }
+        return "";
+    })
+        .filter((a) => a !== "");
+    const suggestions = Array.isArray(o.suggestions) ? o.suggestions.filter(isString) : [];
+    const corrections = Array.isArray(o.corrections) ? o.corrections.filter(isString) : [];
+    const infoboxes = (Array.isArray(o.infoboxes) ? o.infoboxes : [])
+        .map((b) => {
+        if (typeof b !== "object" || b === null)
+            return null;
+        const box = b;
+        return {
+            infobox: isString(box.infobox) ? box.infobox : "",
+            content: isString(box.content) ? box.content : "",
+        };
+    })
+        .filter((b) => b !== null && (b.infobox !== "" || b.content !== ""));
+    const unresponsive = (Array.isArray(o.unresponsive_engines) ? o.unresponsive_engines : [])
+        .map((e) => {
+        if (!Array.isArray(e) || !isString(e[0]))
+            return null;
+        return [e[0], isString(e[1]) ? e[1] : ""];
+    })
+        .filter((e) => e !== null);
+    return { results, answers, suggestions, corrections, infoboxes, unresponsive_engines: unresponsive };
+}
+/** SearXNG reports parameter problems as {"error": "..."} — sometimes with HTTP 200. */
+function backendErrorMessage(data) {
+    if (typeof data !== "object" || data === null)
+        return "";
+    const o = data;
+    for (const key of ["error", "detail", "message"]) {
+        const v = o[key];
+        if (isString(v) && v.trim())
+            return collapse(v);
+        if (typeof v === "object" && v !== null) {
+            const nested = v.message;
+            if (isString(nested) && nested.trim())
+                return collapse(nested);
+        }
+    }
+    return "";
+}
+function serperKey() {
+    const env = process.env[SERPER_KEY_ENV];
+    if (env && env.trim())
+        return env.trim();
+    const configured = loadConfig().serperApiKey;
+    if (configured && configured.trim())
+        return configured.trim();
+    return DEFAULT_SERPER_API_KEY;
+}
+/** True when the built-in shared key is in use (no env var, no config key). */
+function usingBuiltInSerperKey() {
+    const env = process.env[SERPER_KEY_ENV];
+    if (env && env.trim())
+        return false;
+    const configured = loadConfig().serperApiKey;
+    return !(configured && configured.trim());
+}
+function serperHint() {
+    return `Override the built-in key via "serperApiKey" in ~/.min-agent/config.json or the ${SERPER_KEY_ENV} env var.`;
+}
+function asSerperResult(r) {
+    if (typeof r !== "object" || r === null)
+        return null;
+    const o = r;
+    if (!isString(o.link) || o.link.trim() === "")
+        return null;
+    return {
+        title: isString(o.title) ? o.title : "",
+        url: o.link,
+        content: isString(o.snippet) ? o.snippet : "",
+        engine: hostOf(o.link),
+        score: 0,
+        publishedDate: isString(o.date) ? o.date : "",
+        imgSrc: "",
+    };
+}
+function emptySerper() {
+    return { ...emptyResponse(), questions: [] };
+}
+function stringList(v, key) {
+    return (Array.isArray(v) ? v : [])
+        .map((item) => {
+        if (typeof item === "object" && item !== null) {
+            const rec = item;
+            if (isString(rec[key]))
+                return rec[key];
+        }
+        return "";
+    })
+        .filter((s) => s.trim() !== "");
+}
+function parseSerper(data) {
+    if (typeof data !== "object" || data === null)
+        return emptySerper();
+    const o = data;
+    const results = (Array.isArray(o.organic) ? o.organic : [])
+        .map(asSerperResult)
+        .filter((r) => r !== null);
+    const answers = [];
+    const ab = o.answerBox;
+    if (typeof ab === "object" && ab !== null) {
+        const rec = ab;
+        for (const key of ["answer", "snippet", "title"]) {
+            if (isString(rec[key]) && rec[key].trim()) {
+                answers.push(collapse(rec[key]));
+                break;
+            }
+        }
+    }
+    const suggestions = stringList(o.relatedSearches, "query");
+    const questions = stringList(o.peopleAlsoAsk, "question");
+    const infoboxes = [];
+    const kg = o.knowledgeGraph;
+    if (typeof kg === "object" && kg !== null) {
+        const rec = kg;
+        const title = isString(rec.title) ? rec.title : "";
+        const description = isString(rec.description) ? rec.description : "";
+        if (title || description)
+            infoboxes.push({ infobox: title, content: description });
+    }
+    return { results, answers, suggestions, corrections: [], infoboxes, unresponsive_engines: [], questions };
+}
+/** Serper reports problems as {"message": "...", "statusCode": N}. */
+function serperErrorMessage(data) {
+    return backendErrorMessage(data);
+}
+async function serperSearch(payload) {
+    let response;
+    try {
+        response = await fetch(SERPER_API, {
+            method: "POST",
+            headers: {
+                "X-API-KEY": serperKey(),
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(SERPER_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        return { kind: "network", message: describeFetchError(err) };
+    }
+    let text;
+    let bodyTooLarge;
+    try {
+        const body = await readBodyLimited(response, MAX_BODY_BYTES);
+        text = body.text;
+        bodyTooLarge = body.truncated;
+    }
+    catch (err) {
+        return { kind: "network", message: describeFetchError(err) };
+    }
+    let parsed;
+    let parseFailed = false;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        parseFailed = true;
+    }
+    const backendMessage = parseFailed ? "" : serperErrorMessage(parsed);
+    if (!response.ok)
+        return { kind: "http", status: response.status, backendMessage };
+    if (parseFailed) {
+        return { kind: "invalid-json", bodyTooLarge, sample: clamp(collapse(text), 100) };
+    }
+    if (bodyTooLarge)
+        return { kind: "invalid-json", bodyTooLarge: true, sample: "" };
+    if (backendMessage)
+        return { kind: "http", status: response.status, backendMessage };
+    return { kind: "ok", data: parseSerper(parsed) };
+}
+function renderSerperFailure(o) {
+    const hint = serperHint();
+    switch (o.kind) {
+        case "network":
+            return `Search error: could not reach the Serper search API (${o.message}). This is not a problem with the query.`;
+        case "invalid-json":
+            if (o.bodyTooLarge) {
+                return `Search error: the search API response exceeded ${MAX_BODY_BYTES / 1024 / 1024} MB and could not be parsed. Narrow the query or request fewer results.`;
+            }
+            return `Search error: the search API returned a non-JSON response${o.sample ? ` (starts with: ${o.sample})` : ""}.`;
+        case "http": {
+            const detail = o.backendMessage ? ` Backend message: ${o.backendMessage}.` : "";
+            if (o.status === 429) {
+                return `Search error: the search API is rate-limiting (HTTP 429).${detail} Wait a few seconds before retrying.`;
+            }
+            if (o.status === 401 || o.status === 403) {
+                if (usingBuiltInSerperKey()) {
+                    return `Search error: the built-in shared Serper key was rejected (HTTP ${o.status}).${detail} The shared key's quota is likely exhausted. Set your own key via "${SERPER_KEY_ENV}" or "serperApiKey" in ~/.min-agent/config.json, or configure your own SearXNG instance via "webSearchURL".`;
+                }
+                return `Search error: the search API rejected the API key (HTTP ${o.status}).${detail} ${hint}`;
+            }
+            if (o.status === 400 || o.status === 422) {
+                return `Search error: the search API rejected these parameters (HTTP ${o.status}).${detail} Fix the arguments and retry; retrying with the same values will fail again.`;
+            }
+            if (o.status >= 500) {
+                return `Search error: the search API failed with HTTP ${o.status}.${detail} It may be temporarily overloaded — retry once.`;
+            }
+            return `Search error: HTTP ${o.status} from the search API.${detail}`;
+        }
+    }
+}
+function buildSerperPayload(input, notes, maxResults) {
+    const payload = { q: input.query, num: maxResults };
+    const lang = (input.language ?? "").trim().toLowerCase();
+    if (lang) {
+        if (LANGUAGE_RE.test(lang) && lang !== "all") {
+            payload.hl = lang.replace("_", "-");
+        }
+        else {
+            notes.push(`ignored invalid language "${input.language}"; use a code like "zh", "en" or "zh-CN"`);
+        }
+    }
+    const range = (input.time_range ?? "").trim().toLowerCase();
+    if (range) {
+        if (VALID_TIME_RANGES.has(range))
+            payload.tbs = TBS_BY_RANGE[range];
+        else
+            notes.push(`ignored invalid time_range "${range}"; valid values: day, week, month, year`);
+    }
+    return payload;
+}
+function searxngConfigured() {
+    const env = process.env[SEARXNG_BACKEND.envName];
+    if (env && env.trim())
+        return true;
+    const configured = loadConfig().webSearchURL;
+    return !!(configured && configured.trim());
+}
+// --- SearXNG (legacy, only when explicitly configured) ---
+function collapse(s) {
+    return s.replace(/\s+/g, " ").trim();
+}
+function clamp(s, max) {
+    const chars = Array.from(s);
+    if (chars.length <= max)
+        return s;
+    return chars.slice(0, max - 1).join("") + "…";
+}
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./, "");
+    }
+    catch {
+        return url;
+    }
+}
+/** Normalize a published date to YYYY-MM-DD; pass unparseable values through. */
+function formatPublished(raw) {
+    if (!raw)
+        return "";
+    const ms = Date.parse(raw);
+    if (Number.isNaN(ms))
+        return collapse(raw);
+    return new Date(ms).toISOString().slice(0, 10);
+}
+/**
+ * Identity key for deduplication: scheme, "www.", trailing slash, fragment and
+ * tracking parameters all describe the same page.
+ */
+export function dedupeKey(raw) {
+    try {
+        const u = new URL(raw);
+        const host = u.hostname.toLowerCase().replace(/^www\./, "");
+        const path = u.pathname.replace(/\/+$/, "");
+        const params = [...u.searchParams].filter(([k]) => !k.toLowerCase().startsWith("utm_") && !EXACT_TRACKING_PARAMS.has(k.toLowerCase()));
+        params.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+        const query = params.map(([k, v]) => `${k}=${v}`).join("&");
+        return `${host}${path}${query ? `?${query}` : ""}`;
+    }
+    catch {
+        return raw.trim().toLowerCase();
+    }
+}
+function dedupeByUrl(results) {
+    const seen = new Set();
+    return results.filter((r) => {
+        const key = dedupeKey(r.url);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * One block per result:
+ *   1. Title
+ *      https://url
+ *      [2026-08-18 · google]
+ *      snippet on a single line
+ * Snippets are whitespace-collapsed and clamped so the indented block
+ * structure survives multi-line engine output.
+ */
+function formatResults(results, withImages) {
+    return results
+        .map((r, i) => {
+        const lines = [`${i + 1}. ${collapse(r.title) || hostOf(r.url)}`, `   ${r.url}`];
+        const meta = [];
+        const date = formatPublished(r.publishedDate);
+        if (date)
+            meta.push(date);
+        if (r.engine)
+            meta.push(r.engine);
+        if (meta.length > 0)
+            lines.push(`   [${meta.join(" · ")}]`);
+        const snippet = clamp(collapse(r.content), SNIPPET_MAX_CHARS);
+        if (snippet)
+            lines.push(`   ${snippet}`);
+        // Image results usually carry an empty title/content; the asset URL is
+        // the only useful payload, so surface it for image searches.
+        if (withImages && r.imgSrc)
+            lines.push(`   image: ${r.imgSrc}`);
+        return lines.join("\n");
+    })
+        .join("\n\n");
+}
+/**
+ * SearXNG reports the instance-wide unresponsive list regardless of which
+ * engines a request used, so narrow it to the requested set when there is one
+ * and say so otherwise.
+ */
+function unresponsiveHint(engines, requested) {
+    let relevant = engines;
+    if (requested && requested.length > 0) {
+        const wanted = new Set(requested.map((e) => e.toLowerCase()));
+        relevant = engines.filter(([name]) => wanted.has(name.toLowerCase()));
+    }
+    if (relevant.length === 0)
+        return "";
+    const detail = relevant.map(([name, reason]) => (reason ? `${name} (${reason})` : name)).join(", ");
+    const scope = requested
+        ? "The requested engines are unavailable"
+        : "The backend reports these engines as unavailable (instance-wide list, may include engines this query did not use)";
+    return `${scope}: ${detail}. Try a different query, or pass "engines" explicitly (e.g. "google,bing").`;
+}
+async function searchOnce(base, params) {
+    let response;
+    try {
+        response = await fetch(`${base}/search?${params}`, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(SEARCH_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        return { kind: "network", message: describeFetchError(err) };
+    }
+    let text;
+    let bodyTooLarge;
+    try {
+        const body = await readBodyLimited(response, MAX_BODY_BYTES);
+        text = body.text;
+        bodyTooLarge = body.truncated;
+    }
+    catch (err) {
+        return { kind: "network", message: describeFetchError(err) };
+    }
+    let parsed;
+    let parseFailed = false;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        parseFailed = true;
+    }
+    // Error bodies are valid JSON even on a 4xx, so parse before branching on the
+    // status; that way the backend's own message reaches the caller.
+    const backendMessage = parseFailed ? "" : backendErrorMessage(parsed);
+    if (!response.ok)
+        return { kind: "http", status: response.status, backendMessage };
+    if (parseFailed) {
+        return { kind: "invalid-json", bodyTooLarge, sample: clamp(collapse(text), 100) };
+    }
+    // A truncated body that still parsed would be missing results silently.
+    if (bodyTooLarge)
+        return { kind: "invalid-json", bodyTooLarge: true, sample: "" };
+    if (backendMessage)
+        return { kind: "http", status: response.status, backendMessage };
+    return { kind: "ok", data: parseResponse(parsed) };
+}
+function renderFailure(o) {
+    const hint = configHint(SEARXNG_BACKEND);
+    switch (o.kind) {
+        case "network":
+            return `Search error: could not reach the search backend (${o.message}). The instance may be down or the network may be unavailable — this is not a problem with the query. ${hint}`;
+        case "invalid-json":
+            if (o.bodyTooLarge) {
+                return `Search error: the search backend response exceeded ${MAX_BODY_BYTES / 1024 / 1024} MB and could not be parsed. Narrow the query or request fewer engines.`;
+            }
+            return `Search error: the search backend returned a non-JSON response${o.sample ? ` (starts with: ${o.sample})` : ""}. The instance most likely has the JSON output format disabled. ${hint}`;
+        case "http": {
+            const detail = o.backendMessage ? ` Backend message: ${o.backendMessage}.` : "";
+            if (o.status === 429) {
+                return `Search error: the search backend is rate-limiting (HTTP 429).${detail} Wait a few seconds before retrying, or use a different instance. ${hint}`;
+            }
+            if (o.status === 401 || o.status === 403) {
+                return `Search error: the search backend rejected the request (HTTP ${o.status}).${detail} The instance likely requires authentication or has the JSON output format disabled. ${hint}`;
+            }
+            if (o.status === 400 || o.status === 422) {
+                return `Search error: the search backend rejected these parameters (HTTP ${o.status}).${detail} Fix the arguments and retry; retrying with the same values will fail again.`;
+            }
+            if (o.status >= 500) {
+                return `Search error: the search backend failed with HTTP ${o.status}.${detail} It may be temporarily overloaded — retry once, then try a different instance. ${hint}`;
+            }
+            return `Search error: HTTP ${o.status} from the search backend.${detail} ${hint}`;
+        }
+    }
+}
+function fallbackEngines() {
+    const env = process.env.MIN_AGENT_SEARXNG_FALLBACK_ENGINES;
+    if (env !== undefined)
+        return env.trim();
+    const configured = loadConfig().webSearchFallbackEngines;
+    if (configured !== undefined)
+        return configured.trim();
+    return DEFAULT_FALLBACK_ENGINES;
+}
+/** Validate/normalize the model-supplied arguments, collecting notes for anything ignored. */
+function buildParams(input, notes) {
+    const params = new URLSearchParams({ q: input.query, format: "json", categories: "general" });
+    const lang = (input.language ?? "").trim();
+    if (lang) {
+        if (LANGUAGE_RE.test(lang))
+            params.set("language", lang.replace("_", "-"));
+        else
+            notes.push(`ignored invalid language "${lang}"; use a code like "zh", "en" or "zh-CN"`);
+    }
+    const range = (input.time_range ?? "").trim().toLowerCase();
+    if (range) {
+        if (VALID_TIME_RANGES.has(range))
+            params.set("time_range", range);
+        else
+            notes.push(`ignored invalid time_range "${range}"; valid values: day, week, month, year`);
+    }
+    return { params, requested: null, wantsImages: false };
+}
+function resolveMaxResults(raw, notes) {
+    if (raw === undefined)
+        return DEFAULT_MAX_RESULTS;
+    const n = Math.floor(Number(raw));
+    if (!Number.isFinite(n) || n < 1) {
+        notes.push(`ignored invalid max_results "${raw}"; using ${DEFAULT_MAX_RESULTS}`);
+        return DEFAULT_MAX_RESULTS;
+    }
+    if (n > MAX_RESULTS_LIMIT) {
+        notes.push(`max_results capped at ${MAX_RESULTS_LIMIT}`);
+        return MAX_RESULTS_LIMIT;
+    }
+    return n;
+}
+async function runSearxng(input, query, notes) {
+    const resolved = resolveBackendBase(SEARXNG_BACKEND, loadConfig().webSearchURL);
+    if (!resolved.ok)
+        return `Search error: ${resolved.error}. ${configHint(SEARXNG_BACKEND)}`;
+    const maxResults = resolveMaxResults(input.max_results, notes);
+    const { params, requested } = buildParams({ ...input, query }, notes);
+    let outcome = await searchOnce(resolved.base, params);
+    // The default engine set on a given instance can be entirely blocked
+    // (CAPTCHA / rate limits), which looks identical to "no such page exists".
+    // A single retry against known-good engines distinguishes the two. The
+    // unresponsive list is instance-wide and therefore not a reliable trigger.
+    let usedFallback = null;
+    if (outcome.kind === "ok" && outcome.data.results.length === 0 && !requested) {
+        const fallback = fallbackEngines();
+        if (fallback) {
+            const retryParams = new URLSearchParams(params);
+            retryParams.set("engines", fallback);
+            const retry = await searchOnce(resolved.base, retryParams);
+            if (retry.kind === "ok" && retry.data.results.length > 0) {
+                outcome = retry;
+                usedFallback = fallback;
+            }
+            else if (retry.kind !== "ok") {
+                notes.push(`the fallback engines (${fallback}) also failed: ${renderFailure(retry).replace(/^Search error: /, "")}`);
+            }
+        }
+    }
+    if (outcome.kind !== "ok")
+        return renderFailure(outcome);
+    const data = outcome.data;
+    const results = dedupeByUrl(data.results).slice(0, maxResults);
+    const noteBlock = notes.map((n) => `Note: ${n}`).join("\n");
+    if (results.length === 0) {
+        const parts = [`No search results found for "${query}".`];
+        if (noteBlock)
+            parts.push(noteBlock);
+        const hint = unresponsiveHint(data.unresponsive_engines, usedFallback ? usedFallback.split(",") : requested);
+        if (hint)
+            parts.push(hint);
+        if (data.corrections.length > 0)
+            parts.push(`Did you mean: ${data.corrections.join(", ")}`);
+        if (data.suggestions.length > 0)
+            parts.push(`Related queries: ${data.suggestions.slice(0, 8).join(", ")}`);
+        if (!hint && data.corrections.length === 0 && data.suggestions.length === 0) {
+            parts.push("Try a different query or a broader wording.");
+        }
+        return parts.join("\n\n");
+    }
+    // Direct answers and infoboxes carry the highest information density, so
+    // they precede the result list.
+    const sections = [];
+    if (noteBlock)
+        sections.push(noteBlock);
+    for (const a of data.answers)
+        sections.push(`Answer: ${collapse(a)}`);
+    for (const b of data.infoboxes) {
+        sections.push(`Infobox${b.infobox ? ` (${collapse(b.infobox)})` : ""}: ${clamp(collapse(b.content), 600)}`);
+    }
+    sections.push(`Found ${results.length} result${results.length === 1 ? "" : "s"} for "${query}"${usedFallback ? ` via fallback engines ${usedFallback}` : ""}:`);
+    sections.push(formatResults(results, false));
+    if (data.corrections.length > 0)
+        sections.push(`Did you mean: ${data.corrections.join(", ")}`);
+    if (data.suggestions.length > 0)
+        sections.push(`Related queries: ${data.suggestions.slice(0, 8).join(", ")}`);
+    return truncateToolOutput(sections.join("\n\n"), { direction: "head" }).content;
+}
+async function runSerper(input, query, notes) {
+    const maxResults = resolveMaxResults(input.max_results, notes);
+    const payload = buildSerperPayload(input, notes, maxResults);
+    const outcome = await serperSearch(payload);
+    if (outcome.kind !== "ok")
+        return renderSerperFailure(outcome);
+    const data = outcome.data;
+    const results = dedupeByUrl(data.results).slice(0, maxResults);
+    const noteBlock = notes.map((n) => `Note: ${n}`).join("\n");
+    if (results.length === 0) {
+        const parts = [`No search results found for "${query}".`];
+        if (noteBlock)
+            parts.push(noteBlock);
+        if (data.questions.length > 0)
+            parts.push(`Related questions: ${data.questions.slice(0, 5).join(" · ")}`);
+        if (data.suggestions.length > 0)
+            parts.push(`Related searches: ${data.suggestions.slice(0, 8).join(" · ")}`);
+        if (data.questions.length === 0 && data.suggestions.length === 0) {
+            parts.push("Try a different query or a broader wording.");
+        }
+        return parts.join("\n\n");
+    }
+    const sections = [];
+    if (noteBlock)
+        sections.push(noteBlock);
+    for (const a of data.answers)
+        sections.push(`Answer: ${collapse(a)}`);
+    for (const b of data.infoboxes) {
+        sections.push(`Infobox${b.infobox ? ` (${collapse(b.infobox)})` : ""}: ${clamp(collapse(b.content), 600)}`);
+    }
+    sections.push(`Found ${results.length} result${results.length === 1 ? "" : "s"} for "${query}":`);
+    sections.push(formatResults(results, false));
+    if (data.questions.length > 0)
+        sections.push(`Related questions: ${data.questions.slice(0, 5).join(" · ")}`);
+    if (data.suggestions.length > 0)
+        sections.push(`Related searches: ${data.suggestions.slice(0, 8).join(" · ")}`);
+    return truncateToolOutput(sections.join("\n\n"), { direction: "head" }).content;
+}
 export const webSearchTool = tool({
-    description: "Search the web for information. Returns search results with titles, URLs, and snippets. Use this when you need current information, news, documentation, or answers that require up-to-date knowledge.",
+    description: `Search the web via Google. Returns ranked results with title, URL, source and a snippet. Use this for current information, news, documentation, or anything needing up-to-date knowledge. Today's date: ${new Date().toISOString().slice(0, 10)}. When the user asks about the latest or newest state of something, use the current year in the query or set time_range (day, week, month, year) — do not append an older year from your training knowledge.`,
     inputSchema: jsonSchema({
         type: "object",
         properties: {
             query: { type: "string", description: "The search query" },
-            categories: { type: "string", description: "Search categories: general, news, images, science, it (default: general)" },
+            language: { type: "string", description: "Search language code, e.g. zh, en, zh-CN (default: en)" },
+            time_range: { type: "string", description: "Time range filter: day, week, month, year" },
+            max_results: {
+                type: "number",
+                description: `Maximum number of results to return (default ${DEFAULT_MAX_RESULTS}, max ${MAX_RESULTS_LIMIT})`,
+            },
         },
         required: ["query"],
     }),
-    execute: async ({ query, categories }) => {
-        try {
-            const params = new URLSearchParams({
-                q: query,
-                format: "json",
-                categories: categories ?? "general",
-            });
-            const response = await fetch(`${SEARXNG_BASE}/search?${params}`, {
-                headers: { "Accept": "application/json" },
-                signal: AbortSignal.timeout(15000),
-            });
-            if (!response.ok)
-                return `Search error: HTTP ${response.status}`;
-            const data = await response.json();
-            const results = (data.results ?? []).slice(0, 10);
-            if (results.length === 0)
-                return "No search results found. Try a different query.";
-            const text = results
-                .map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.content ?? ""}`)
-                .join("\n\n");
-            return truncateToolOutput(text, { direction: "head" }).content;
-        }
-        catch (err) {
-            return `Search error: ${err.message}`;
-        }
+    execute: async (input) => {
+        const query = (input.query ?? "").trim();
+        if (!query)
+            return 'Search error: "query" must be a non-empty string.';
+        const notes = [];
+        // SearXNG is only used when the user explicitly configures an instance;
+        // otherwise the built-in Serper key powers the default backend.
+        if (searxngConfigured())
+            return runSearxng(input, query, notes);
+        return runSerper(input, query, notes);
     },
 });