atom-agent 0.3.0 → 1.1.0

package/dist/tools/todo.js

@@ -0,0 +1,191 @@
+// Session checklist state + todowrite/todo_get/todo_update. Module-global
+// list (session-scoped, ephemeral); invariants refuse as invalid calls.
+import { err, invalidCall } from "./shared.js";
+export const TODO_STATUSES = new Set(["pending", "in_progress", "completed"]);
+export const TODO_PRIORITIES = new Set(["high", "medium", "low"]);
+// Session-scoped, ephemeral (resets with the process — same lifetime as
+// read fingerprints and background tasks). todowrite replaces the whole
+// list per call (Claude Code / opencode); todo_get reads it back;
+// todo_update patches one item by index (check/uncheck without rewrite).
+let todoItems = [];
+// Copy for UI/tests (the executor's echoed rendering is the model path).
+export function getTodos() {
+    return todoItems.map((t) => ({ ...t }));
+}
+// Reset for /new (a fresh conversation in the same process starts with a
+// fresh checklist; /clear keeps it — the session continues).
+export function clearTodos() {
+    todoItems = [];
+}
+function renderTodos(items) {
+    if (items.length === 0)
+        return "Todo list is empty.";
+    const mark = (s) => s === "completed" ? "✅" : s === "in_progress" ? "🔧" : "○";
+    return (`Todo list (${items.length}):\n` +
+        items
+            .map((t, i) => `${i + 1}. ${mark(t.status)} [${t.status}] ${t.content}${t.priority ? ` (${t.priority})` : ""}`)
+            .join("\n"));
+}
+// Replace the session checklist. Malformed items are model mistakes
+// (`invalid call`, never runs); runtime failures keep plain `Error: ...`.
+// Runtime invariants (harness-enforced, not just prompt discipline):
+// - at most ONE item may be in_progress (flip the current one to completed
+//   or back to pending first — parallel "current work" is impossible state);
+// - a completed item keeps its status across rewrites: only an explicit
+//   todo_update status patch reopens one (silent un-completion via a full
+//   rewrite is refused with a pointer to todo_update).
+// An empty array clears; all-completed clears.
+export async function todowriteTool(args) {
+    try {
+        const list = args?.todos;
+        if (!Array.isArray(list))
+            return err("todos must be an array");
+        const next = [];
+        for (let i = 0; i < list.length; i++) {
+            const item = list[i];
+            if (typeof item !== "object" || item === null || Array.isArray(item)) {
+                return invalidCall(`todo item ${i} must be an object. Expected {content: string, status: "pending" | "in_progress" | "completed", priority?: "high" | "medium" | "low", activeForm?: string}`);
+            }
+            if (typeof item["content"] !== "string" || item["content"].length === 0) {
+                return invalidCall(`todo item ${i} field "content" must be a non-empty string`);
+            }
+            if (typeof item["status"] !== "string" || !TODO_STATUSES.has(item["status"])) {
+                return invalidCall(`todo item ${i} field "status" must be one of "pending", "in_progress", "completed" (got ${JSON.stringify(item["status"])})`);
+            }
+            const clean = {
+                content: item["content"],
+                status: item["status"],
+            };
+            if (item["priority"] !== undefined) {
+                if (typeof item["priority"] !== "string" || !TODO_PRIORITIES.has(item["priority"])) {
+                    return invalidCall(`todo item ${i} field "priority" must be one of "high", "medium", "low" (got ${JSON.stringify(item["priority"])})`);
+                }
+                clean.priority = item["priority"];
+            }
+            if (item["activeForm"] !== undefined) {
+                if (typeof item["activeForm"] !== "string") {
+                    return invalidCall(`todo item ${i} field "activeForm" must be a string`);
+                }
+                if (item["activeForm"].length > 0)
+                    clean.activeForm = item["activeForm"];
+            }
+            next.push(clean);
+        }
+        // Invariant: at most one in_progress (parallel current work is impossible
+        // state — complete or pause the other one first).
+        const active = next
+            .map((t, i) => ({ t, i }))
+            .filter(({ t }) => t.status === "in_progress");
+        if (active.length > 1) {
+            const names = active.map(({ t, i }) => `${i + 1}. ${t.content}`).join("; ");
+            return invalidCall(`only one task may be in_progress at a time (got ${active.length}: ${names}). ` +
+                `Mark the finished one completed (or paused back to pending) first`);
+        }
+        // Invariant: completed stays completed across rewrites — a full-list
+        // rewrite may not silently reopen a content-identical completed item.
+        // Reopening is an explicit act: todo_update that item's status.
+        for (const prev of todoItems) {
+            if (prev.status !== "completed")
+                continue;
+            const reopened = next.find((t) => t.content === prev.content && t.status !== "completed");
+            if (reopened) {
+                return invalidCall(`task "${prev.content}" is already completed — a rewrite cannot reopen it. ` +
+                    `To reopen it explicitly, call todo_update on its index with a new status`);
+            }
+        }
+        const prevCount = todoItems.length;
+        todoItems = next;
+        if (next.length === 0) {
+            return prevCount === 0 ? "Todo list is empty." : `Todo list cleared (${prevCount} item(s) removed).`;
+        }
+        if (next.every((t) => t.status === "completed")) {
+            todoItems = [];
+            return `All ${next.length} task(s) completed — todo list cleared.\n${renderTodos(next)}`;
+        }
+        return ("Todos have been modified successfully. Ensure that you continue to use the todo list to track your progress. Please proceed with the current tasks if applicable.\n" +
+            renderTodos(next));
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}
+// Read the session checklist (pure read — the todowrite echo is the
+// write path). Never throws; unknown fields are ignored by the schema.
+export async function todoGetTool() {
+    return renderTodos(getTodos());
+}
+// Patch ONE item by 1-based index (the check/uncheck verb; Claude
+// TaskUpdate equivalent for a single item). Out-of-range indexes are
+// model mistakes (`invalid call` — the list changed, so re-read with
+// todo_get). Completing the last open item clears the list, like
+// todowrite. Never throws.
+export async function todoUpdateTool(args) {
+    try {
+        const a = (args ?? {});
+        const rawIndex = a["index"];
+        if (typeof rawIndex !== "number" || !Number.isFinite(rawIndex) || Math.floor(rawIndex) !== rawIndex) {
+            return invalidCall(`field "index" for tool "todo_update" must be an integer (got ${JSON.stringify(rawIndex)})`);
+        }
+        if (rawIndex < 1 || rawIndex > todoItems.length) {
+            return invalidCall(`todo_update index ${rawIndex} out of range (list has ${todoItems.length} item(s); call todo_get to refresh)`);
+        }
+        const hasPatch = a["status"] !== undefined ||
+            a["content"] !== undefined ||
+            a["priority"] !== undefined ||
+            a["activeForm"] !== undefined;
+        if (!hasPatch) {
+            return invalidCall(`tool "todo_update" needs at least one of "status", "content", "priority", "activeForm" to change`);
+        }
+        const next = { ...todoItems[rawIndex - 1] };
+        if (a["status"] !== undefined) {
+            if (typeof a["status"] !== "string" || !TODO_STATUSES.has(a["status"])) {
+                return invalidCall(`field "status" for tool "todo_update" must be one of "pending", "in_progress", "completed" (got ${JSON.stringify(a["status"])})`);
+            }
+            // Invariant: at most one in_progress — starting this one while another
+            // runs is impossible state (complete or pause the other first).
+            // Reopening a completed item here is the explicit reset the
+            // todowrite rewrite guard points to, so it stays allowed.
+            if (a["status"] === "in_progress") {
+                const other = todoItems.findIndex((t, i) => i !== rawIndex - 1 && t.status === "in_progress");
+                if (other !== -1) {
+                    return invalidCall(`only one task may be in_progress at a time (item ${other + 1} "${todoItems[other].content}" is already in_progress). Complete it or pause it back to pending first`);
+                }
+            }
+            next.status = a["status"];
+        }
+        if (a["content"] !== undefined) {
+            if (typeof a["content"] !== "string" || a["content"].length === 0) {
+                return invalidCall(`field "content" for tool "todo_update" must be a non-empty string`);
+            }
+            next.content = a["content"];
+        }
+        if (a["priority"] !== undefined) {
+            if (typeof a["priority"] !== "string" || !TODO_PRIORITIES.has(a["priority"])) {
+                return invalidCall(`field "priority" for tool "todo_update" must be one of "high", "medium", "low" (got ${JSON.stringify(a["priority"])})`);
+            }
+            next.priority = a["priority"];
+        }
+        if (a["activeForm"] !== undefined) {
+            if (typeof a["activeForm"] !== "string") {
+                return invalidCall(`field "activeForm" for tool "todo_update" must be a string`);
+            }
+            if (a["activeForm"].length > 0) {
+                next.activeForm = a["activeForm"];
+            }
+            else {
+                delete next.activeForm;
+            }
+        }
+        todoItems[rawIndex - 1] = next;
+        if (todoItems.length > 0 && todoItems.every((t) => t.status === "completed")) {
+            const snapshot = renderTodos(todoItems);
+            const done = todoItems.length;
+            todoItems = [];
+            return `All ${done} task(s) completed — todo list cleared.\n${snapshot}`;
+        }
+        return `Todo ${rawIndex} updated.\n${renderTodos(todoItems)}`;
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}

package/dist/tools/web.js

@@ -0,0 +1,454 @@
+// Web executors: webfetch retrieval (SSRF-gated per URL and redirect hop)
+// and websearch discovery. Node builtins + global fetch only.
+import { promises as dns } from "node:dns";
+import * as net from "node:net";
+import { loadAtomConfig } from "../config.js";
+import { classifyIp, defaultNetworkPolicy, isRedirectStatus, zoneAllows, zoneForAddresses, } from "../policy.js";
+import { appendOverflow } from "./overflow.js";
+import { err, READ_CHAR_CAP } from "./shared.js";
+// ---- Web tools (webfetch retrieval / websearch discovery) ----
+const WEB_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36";
+const WEBFETCH_DOWNLOAD_CAP = 1024 * 1024; // ~1MB download cap
+const WEBSEARCH_QUERY_CAP = 500;
+const WEBSEARCH_TIMEOUT_MS = 30000;
+// Decode common named entities plus decimal/hex numeric refs. Unknown
+// entities are left as-is.
+function decodeHtmlEntities(s) {
+    const numeric = s
+        .replace(/&#x([0-9a-fA-F]+);/g, (m, hex) => {
+        const cp = parseInt(hex, 16);
+        return cp >= 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
+    })
+        .replace(/&#([0-9]+);/g, (m, dec) => {
+        const cp = parseInt(dec, 10);
+        return cp >= 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
+    });
+    return numeric
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;|&apos;/g, "'")
+        .replace(/&nbsp;/g, " ");
+}
+// Minimal HTML -> text: drop comments and script/style/noscript/template
+// blocks, map block tags to line breaks, strip remaining tags to spaces,
+// decode entities, collapse whitespace. Paragraph breaks (~double newline)
+// are preserved.
+function htmlToText(html) {
+    let s = html.replace(/<!--[\s\S]*?-->/g, " ");
+    s = s.replace(/<(script|style|noscript|template)[\s>][\s\S]*?<\/\1\s*>/gi, " ");
+    s = s.replace(/<\/?(?:p|div|br|li|[ou]l|h[1-6]|tr|t[bdh]|table|section|article|header|footer|main|nav|aside|figure|figcaption|blockquote|pre|hr|dd|dt|dl)[^>]*>/gi, "\n");
+    s = s.replace(/<[^<>]*>/g, " ");
+    s = decodeHtmlEntities(s);
+    s = s.replace(/\r\n?/g, "\n");
+    s = s.replace(/[ \t\f\v ]+/g, " ");
+    s = s.replace(/ *\n */g, "\n");
+    s = s.replace(/\n{3,}/g, "\n\n");
+    return s.trim();
+}
+// Read a fetch Response body, aborting (cancelling the reader) once ~cap
+// bytes are buffered. Falls back to res.text() when the body is not a
+// stream (null-body responses, non-standard fetch mocks).
+async function readBodyCapped(res, capBytes) {
+    const body = res.body;
+    if (body != null && typeof body.getReader === "function") {
+        const reader = body.getReader();
+        const chunks = [];
+        let total = 0;
+        let truncated = false;
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (!value || value.byteLength === 0)
+                    continue;
+                if (total + value.byteLength > capBytes) {
+                    const keep = capBytes - total;
+                    if (keep > 0) {
+                        chunks.push(value.slice(0, keep));
+                        total += keep;
+                    }
+                    truncated = true;
+                    try {
+                        await reader.cancel?.();
+                    }
+                    catch {
+                        // ignore cancel errors
+                    }
+                    break;
+                }
+                chunks.push(value);
+                total += value.byteLength;
+            }
+        }
+        finally {
+            try {
+                reader.releaseLock?.();
+            }
+            catch {
+                // ignore
+            }
+        }
+        const buf = Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength)));
+        return { text: buf.toString("utf8"), truncated };
+    }
+    const text = await res.text();
+    if (text.length > capBytes)
+        return { text: text.slice(0, capBytes), truncated: true };
+    return { text, truncated: false };
+}
+const WEBFETCH_MAX_REDIRECTS = 5;
+// Default hostname resolver: literal IPs classify directly (no DNS);
+// "localhost" pins loopback without depending on resolver config; everything
+// else resolves via the system resolver (all addresses — a hostname
+// straddling zones is gated by its most sensitive one). Never throws: DNS
+// failure yields [] (the caller blocks unresolvable hosts fail-closed).
+async function defaultResolveHost(host) {
+    try {
+        if (host.toLowerCase() === "localhost")
+            return ["127.0.0.1"];
+        const records = await dns.lookup(host, { all: true });
+        return records.map((r) => r.address);
+    }
+    catch {
+        return [];
+    }
+}
+function loadNetworkPolicy() {
+    try {
+        const file = loadAtomConfig().config.network;
+        if (!file)
+            return defaultNetworkPolicy();
+        return { ...defaultNetworkPolicy(), ...file };
+    }
+    catch {
+        return defaultNetworkPolicy();
+    }
+}
+// Gate one URL against the network policy (initial URL and EVERY redirect
+// hop — redirects must never bypass it). Checks, in order: parseable,
+// http(s) scheme, no embedded credentials, resolvable/classifiable host,
+// zone allowed by policy. Known limitation (documented, not solved here):
+// DNS rebinding between this check and fetch (TOCTOU) — mitigating that
+// needs connection-level IP pinning, which global fetch does not offer.
+export async function checkUrlAgainstPolicy(rawUrl, policy, resolve = defaultResolveHost) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        return { ok: false, error: `Error: invalid URL: ${rawUrl}` };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { ok: false, error: `Error: unsupported URL scheme (only http/https allowed): ${parsed.protocol}` };
+    }
+    // Credential-bearing URLs are an exfiltration shape (model-generated URLs
+    // should never carry userinfo); reject before any DNS or fetch.
+    if (parsed.username || parsed.password) {
+        return { ok: false, error: `Error: URLs with credentials are not allowed` };
+    }
+    let host = parsed.hostname.toLowerCase();
+    if (host.endsWith("."))
+        host = host.slice(0, -1);
+    if (!host)
+        return { ok: false, error: `Error: invalid URL: ${rawUrl}` };
+    // Bracketed IPv6 literals as carried by URL.hostname.
+    const bare = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+    let zone;
+    if (net.isIP(bare) !== 0) {
+        const direct = classifyIp(bare);
+        zone = direct === "invalid" ? "blocked" : direct;
+    }
+    else {
+        let addresses;
+        try {
+            addresses = await resolve(host);
+        }
+        catch {
+            addresses = [];
+        }
+        if (addresses.length === 0) {
+            return { ok: false, error: `Error: cannot resolve host: ${host}` };
+        }
+        zone = zoneForAddresses(addresses);
+    }
+    if (zone === "blocked" || !zoneAllows(zone, policy)) {
+        const key = zone === "public"
+            ? "allowPublic"
+            : zone === "localhost"
+                ? "allowLocalhost"
+                : zone === "private"
+                    ? "allowPrivate"
+                    : "allowLinkLocal";
+        const reason = zone === "blocked"
+            ? "unresolvable address"
+            : `network policy blocks ${zone} URLs (atom.json network.${key})`;
+        return { ok: false, error: `Error: ${reason}: ${rawUrl}` };
+    }
+    return { ok: true, zone, url: parsed.toString() };
+}
+// Fetch a page (retrieval). http:// is auto-upgraded to https:// (noted);
+// only http/https schemes are allowed. Downloads are capped at ~1MB and
+// output at ~64KB (both noted when truncated). markdown/text return page
+// text (non-HTML content-types pass through as text); html returns the raw
+// body. Network policy (SSRF): the initial URL and EVERY redirect hop are
+// gated by zone (public/localhost/private/link-local/blocked) — redirects
+// are followed manually (cap 5, loop-detected) so a public URL can never
+// bounce to localhost/metadata unseen. Error strings, never throws.
+export async function webfetchTool(args, opts) {
+    try {
+        const rawUrl = typeof args?.url === "string" ? args.url.trim() : "";
+        if (!rawUrl)
+            return err("url must be a non-empty string");
+        let parsed;
+        try {
+            parsed = new URL(rawUrl);
+        }
+        catch {
+            return err(`invalid URL: ${rawUrl}`);
+        }
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return err(`unsupported URL scheme (only http/https allowed): ${parsed.protocol}`);
+        }
+        const format = args?.format ?? "markdown";
+        if (format !== "markdown" && format !== "text" && format !== "html") {
+            return err('format must be "markdown", "text", or "html"');
+        }
+        const t = args?.timeoutMs;
+        const timeoutMs = typeof t === "number" && Number.isFinite(t)
+            ? Math.min(Math.max(Math.floor(t), 1), 120000)
+            : 30000;
+        let target = parsed.toString();
+        let upgraded = false;
+        if (parsed.protocol === "http:") {
+            parsed.protocol = "https:";
+            target = parsed.toString();
+            upgraded = true;
+        }
+        const policy = opts?.policy ?? loadNetworkPolicy();
+        const resolve = opts?.resolveHost ?? defaultResolveHost;
+        const first = await checkUrlAgainstPolicy(target, policy, resolve);
+        if (!first.ok)
+            return first.error;
+        target = first.url;
+        const visited = new Set([target]);
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+        let res;
+        let hops = 0;
+        try {
+            for (;;) {
+                res = await fetch(target, {
+                    redirect: "manual",
+                    signal: ctrl.signal,
+                    headers: {
+                        "User-Agent": WEB_UA,
+                        Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+                    },
+                });
+                const status = typeof res.status === "number" ? res.status : 0;
+                if (!isRedirectStatus(status))
+                    break;
+                // Best-effort socket release before following (mocks may lack a body).
+                try {
+                    await res.body?.cancel?.();
+                }
+                catch {
+                    // ignore — the next fetch proceeds regardless
+                }
+                const loc = res.headers?.get?.("location") ?? null;
+                if (!loc)
+                    return err(`webfetch redirect without location: ${target}`);
+                let next;
+                try {
+                    next = new URL(loc, target);
+                }
+                catch {
+                    return err(`webfetch invalid redirect location from ${target}`);
+                }
+                if (next.protocol !== "http:" && next.protocol !== "https:") {
+                    return err(`webfetch redirect to unsupported scheme (${next.protocol}): ${target}`);
+                }
+                if (visited.has(next.toString())) {
+                    return err(`webfetch redirect loop detected: ${target}`);
+                }
+                visited.add(next.toString());
+                hops += 1;
+                if (hops > WEBFETCH_MAX_REDIRECTS) {
+                    return err(`webfetch too many redirects (>${WEBFETCH_MAX_REDIRECTS}): ${target}`);
+                }
+                const hop = await checkUrlAgainstPolicy(next.toString(), policy, resolve);
+                if (!hop.ok)
+                    return hop.error;
+                target = hop.url;
+            }
+        }
+        catch (e) {
+            if (e instanceof Error && e.name === "AbortError") {
+                return err(`webfetch timed out after ${timeoutMs}ms: ${target}`);
+            }
+            return err(`webfetch failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok)
+            return err(`webfetch HTTP ${res.status} for ${target}`);
+        let body;
+        let downloadTruncated = false;
+        try {
+            const capped = await readBodyCapped(res, WEBFETCH_DOWNLOAD_CAP);
+            body = capped.text;
+            downloadTruncated = capped.truncated;
+        }
+        catch (e) {
+            return err(`webfetch failed reading response: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const contentType = res.headers?.get?.("content-type") ?? "";
+        const isHtml = contentType.trim() === "" || /html|xhtml/i.test(contentType);
+        const out = format === "html" || !isHtml ? body : htmlToText(body);
+        const prefix = upgraded ? "[note: upgraded http:// to https://]\n" : "";
+        const notes = [];
+        if (hops > 0)
+            notes.push(`[note: followed ${hops} redirect(s) to ${target}]`);
+        let text = out;
+        if (downloadTruncated)
+            notes.push("[truncated: download exceeded ~1MB]");
+        if (text.length > READ_CHAR_CAP) {
+            const full = text;
+            const head = full.slice(0, READ_CHAR_CAP);
+            text = head;
+            notes.push("[truncated: output exceeded 64KB]");
+            // Single spill: recover the pointer line from the composed tail.
+            const tailed = appendOverflow(head, "\n[truncated: output exceeded 64KB]", "converted page text", full);
+            const overflowLine = tailed.slice((head + "\n[truncated: output exceeded 64KB]\n").length);
+            if (overflowLine.startsWith("[overflow:"))
+                notes.push(overflowLine);
+        }
+        return prefix + text + (notes.length > 0 ? "\n" + notes.join("\n") : "");
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}
+// Unwrap a DuckDuckGo /l/ redirect (?uddg=<encoded target>) to the real
+// target URL; pass direct http(s) hrefs through. Anything else is dropped.
+function cleanDdgUrl(href) {
+    const h = decodeHtmlEntities(href.trim());
+    if (!h)
+        return "";
+    const abs = h.startsWith("//") ? `https:${h}` : h;
+    try {
+        const u = new URL(abs, "https://html.duckduckgo.com");
+        const uddg = u.searchParams.get("uddg");
+        if (uddg)
+            return uddg;
+        if (u.protocol === "http:" || u.protocol === "https:")
+            return u.toString();
+        return "";
+    }
+    catch {
+        return "";
+    }
+}
+function oneLine(s) {
+    return s.replace(/\s+/g, " ").trim();
+}
+// Parse DuckDuckGo HTML endpoint results with regex: split on result
+// container divs, then take the first result__a anchor (title/url) and the
+// result__snippet (a or div) per block. Blocks without a usable title/url
+// are skipped.
+export function parseDdgResults(html) {
+    const out = [];
+    try {
+        const chunks = html.split(/<div\b[^>]*\bclass="result[\s"']/i);
+        for (let i = 1; i < chunks.length; i++) {
+            const chunk = chunks[i];
+            let title = "";
+            let url = "";
+            const anchors = chunk.matchAll(/<a\b([^>]*)>([\s\S]*?)<\/a>/gi);
+            for (const m of anchors) {
+                if (!/\bresult__a\b/.test(m[1]))
+                    continue;
+                const href = /href\s*=\s*"([^"]*)"/i.exec(m[1])?.[1] ?? "";
+                url = cleanDdgUrl(href);
+                title = oneLine(htmlToText(m[2] ?? ""));
+                break;
+            }
+            if (!title || !url)
+                continue;
+            const snip = /result__snippet"[^>]*>([\s\S]*?)<\/(?:a|div)>/i.exec(chunk);
+            const snippet = snip ? oneLine(htmlToText(snip[1] ?? "")) : "";
+            out.push({ title, url, snippet });
+        }
+    }
+    catch {
+        return out;
+    }
+    return out;
+}
+// Search the web (discovery) via the keyless DuckDuckGo HTML endpoint —
+// best-effort: DDG bot protection may answer 403, surfaced as an error
+// string. Returns numbered "title — url" + snippet blocks, or "No results.".
+// Error strings, never throws.
+export async function websearchTool(args) {
+    try {
+        const raw = typeof args?.query === "string" ? args.query.trim() : "";
+        if (!raw)
+            return err("query must be a non-empty string");
+        // Client-side domain scoping (no server-side filters on this backend):
+        // `site: "example.com"` appends a `site:` operator to the query.
+        const site = typeof args?.site === "string" ? args.site.trim() : "";
+        const scoped = site ? `${raw} site:${site}` : raw;
+        const query = scoped.length > WEBSEARCH_QUERY_CAP ? scoped.slice(0, WEBSEARCH_QUERY_CAP) : scoped;
+        const n = args?.numResults;
+        const numResults = typeof n === "number" && Number.isFinite(n)
+            ? Math.min(Math.max(Math.floor(n), 1), 20)
+            : 8;
+        const endpoint = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), WEBSEARCH_TIMEOUT_MS);
+        let res;
+        try {
+            res = await fetch(endpoint, {
+                signal: ctrl.signal,
+                headers: { "User-Agent": WEB_UA, Accept: "text/html,*/*;q=0.8" },
+            });
+        }
+        catch (e) {
+            if (e instanceof Error && e.name === "AbortError") {
+                return err(`websearch timed out after ${WEBSEARCH_TIMEOUT_MS}ms`);
+            }
+            return err(`websearch failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (res.status === 403) {
+            return err("websearch blocked by DuckDuckGo bot protection (HTTP 403; best-effort search — retry later)");
+        }
+        if (!res.ok)
+            return err(`websearch HTTP ${res.status}`);
+        let html;
+        try {
+            html = await res.text();
+        }
+        catch (e) {
+            return err(`websearch failed reading response: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const results = parseDdgResults(html).slice(0, numResults);
+        if (results.length === 0)
+            return "No results.";
+        return results
+            .map((r, i) => {
+            const head = `${i + 1}. ${r.title} — ${r.url}`;
+            return r.snippet ? `${head}\n   ${r.snippet}` : head;
+        })
+            .join("\n");
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}