@claude-flow/cli 3.10.4 → 3.10.6

package/dist/src/benchmarks/gaia-tools/web_browse.js

@@ -0,0 +1,217 @@
+/**
+ * GAIA Tool: web_browse — ADR-133-PR5
+ *
+ * Opens a URL in a headless Chromium browser via Playwright and extracts
+ * page content (text, HTML, or screenshot).  Covers the ~10-15pp of GAIA
+ * Level-1 questions that require navigating dynamic JS pages, video pages
+ * (YouTube, Vimeo), and paywalled/login-required content.
+ *
+ * ============================================================
+ * PLAYWRIGHT DEPENDENCY — OPT-IN INSTALL
+ * ============================================================
+ * Playwright is NOT a hard runtime dep of @claude-flow/cli.  It is loaded
+ * lazily via a dynamic import so the package installs cleanly without it.
+ *
+ * To use web_browse, run once:
+ *   npm install playwright
+ *   npx playwright install chromium
+ *
+ * If Playwright is not installed, execute() returns a structured error
+ * message that Claude can relay to the user rather than crashing.
+ *
+ * Install size: ~80 MB for the Playwright package + Chromium binary.
+ * Add as a devDependency in benchmark-specific contexts to avoid bloating
+ * the production bundle.
+ *
+ * ============================================================
+ * RESOURCE CAPS
+ * ============================================================
+ * - Text/HTML extraction capped at 8 000 characters (prevents context-window
+ *   overflow; roughly 2 000 tokens).
+ * - Default timeout: 30 seconds.
+ * - Screenshots returned as base64-encoded PNG strings.
+ * - Browser instance is always closed in a `finally` block.
+ *
+ * Refs: ADR-133, #2156
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_CONTENT_CHARS = 8_000;
+/**
+ * Attempt to load Playwright's `chromium` launch function.
+ * Returns a missing-result (with install instructions) if Playwright is not
+ * installed rather than throwing — callers return the reason string to Claude.
+ */
+async function loadPlaywright() {
+    try {
+        // Dynamic import keeps Playwright out of the static dep graph.
+        // The string is built at runtime to prevent TS from statically resolving
+        // the module (which would fail with TS2307 when playwright is not installed).
+        const pwModuleName = 'play' + 'wright';
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const pw = await import(/* @vite-ignore */ pwModuleName);
+        return { ok: true, chromium: pw.chromium };
+    }
+    catch {
+        return {
+            ok: false,
+            reason: 'Playwright is not installed.  Install it with:\n' +
+                '  npm install playwright\n' +
+                '  npx playwright install chromium\n' +
+                'Then retry.  web_browse requires Playwright to navigate dynamic pages.',
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Core browse logic
+// ---------------------------------------------------------------------------
+async function browseUrl(input) {
+    const extract = input.extract ?? 'text';
+    const timeoutMs = Math.min(Math.max(1_000, Math.round((input.timeout_seconds ?? DEFAULT_TIMEOUT_MS / 1000) * 1000)), 120_000);
+    const pw = await loadPlaywright();
+    if (!pw.ok) {
+        // Return as a structured result so the agent loop can forward the error
+        // to Claude without crashing.
+        return {
+            content: `[web_browse error] ${pw.reason}`,
+            final_url: input.url,
+            status: 0,
+        };
+    }
+    const browser = await pw.chromium.launch({ headless: true });
+    try {
+        const page = await browser.newPage();
+        // Capture final HTTP status from the main-frame response.
+        let responseStatus = 200;
+        page.on('response', (resp) => {
+            if (resp.url() === page.url() || resp.url() === input.url) {
+                responseStatus = resp.status();
+            }
+        });
+        await page.goto(input.url, {
+            waitUntil: 'domcontentloaded',
+            timeout: timeoutMs,
+        });
+        if (input.wait_for_selector) {
+            await page.waitForSelector(input.wait_for_selector, { timeout: timeoutMs });
+        }
+        let rawContent;
+        if (extract === 'screenshot') {
+            const buf = await page.screenshot({ type: 'png', fullPage: false });
+            rawContent = buf.toString('base64');
+        }
+        else if (extract === 'html') {
+            rawContent = await page.content();
+        }
+        else {
+            // Default: extract visible text
+            // page.evaluate runs inside the browser context (Chromium's V8 runtime),
+            // so `document` / `window` are available there.  Cast to avoid the
+            // TypeScript "lib does not include dom" error from the Node.js tsconfig.
+            rawContent = await page.evaluate(() => {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const doc = globalThis.document;
+                if (!doc)
+                    return '';
+                doc
+                    .querySelectorAll('script, style, noscript, [hidden], [aria-hidden="true"]')
+                    .forEach((el) => el.remove());
+                return (doc.body?.innerText ?? doc.documentElement?.innerText ?? '').trim();
+            });
+        }
+        const finalUrl = page.url();
+        // Cap text/html at MAX_CONTENT_CHARS; screenshots are kept as-is (base64
+        // of a 1280×720 PNG ≈ 300–800 KB — large but necessary for vision pass).
+        let content = rawContent;
+        let truncated = false;
+        if (extract !== 'screenshot' && rawContent.length > MAX_CONTENT_CHARS) {
+            content = rawContent.slice(0, MAX_CONTENT_CHARS);
+            truncated = true;
+        }
+        return { content, final_url: finalUrl, status: responseStatus, truncated };
+    }
+    finally {
+        await browser.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Format output for Claude
+// ---------------------------------------------------------------------------
+function formatBrowseResult(result, extract) {
+    const lines = [];
+    lines.push(`final_url: ${result.final_url}`);
+    lines.push(`status: ${result.status}`);
+    if (extract === 'screenshot') {
+        lines.push(`extract: screenshot (base64 PNG)`);
+        lines.push(`content:\n${result.content}`);
+    }
+    else {
+        lines.push(`extract: ${extract}`);
+        if (result.truncated) {
+            lines.push(`[content truncated at ${MAX_CONTENT_CHARS} characters]`);
+        }
+        lines.push(`content:\n${result.content}`);
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// GaiaTool implementation
+// ---------------------------------------------------------------------------
+export class WebBrowseTool {
+    name = 'web_browse';
+    definition = {
+        name: 'web_browse',
+        description: 'Open a URL in a headless Chromium browser and extract page content. ' +
+            'Use this for dynamic JavaScript pages, video pages (YouTube, Vimeo), ' +
+            'or any URL that web_search cannot fetch directly.  ' +
+            'Returns page text by default; pass extract="html" for raw HTML or ' +
+            'extract="screenshot" for a base64 PNG screenshot.  ' +
+            'Requires Playwright to be installed (npm install playwright && ' +
+            'npx playwright install chromium).',
+        input_schema: {
+            type: 'object',
+            properties: {
+                url: {
+                    type: 'string',
+                    description: 'The URL to navigate to (http or https).',
+                },
+                wait_for_selector: {
+                    type: 'string',
+                    description: 'Optional CSS selector to wait for before extracting content. ' +
+                        'Useful for SPAs that render after the initial DOM load.',
+                },
+                extract: {
+                    type: 'string',
+                    description: 'What to extract: "text" (default, visible text), ' +
+                        '"html" (full page HTML), or "screenshot" (base64 PNG).',
+                },
+                timeout_seconds: {
+                    type: 'number',
+                    description: `Navigation timeout in seconds (default: ${DEFAULT_TIMEOUT_MS / 1000}, max: 120).`,
+                },
+            },
+            required: ['url'],
+        },
+    };
+    async execute(input) {
+        const url = String(input['url'] ?? '').trim();
+        if (!url)
+            throw new Error('web_browse: `url` input is required and must be non-empty.');
+        const rawExtract = String(input['extract'] ?? 'text').toLowerCase();
+        const extract = rawExtract === 'html' ? 'html' : rawExtract === 'screenshot' ? 'screenshot' : 'text';
+        const browseInput = {
+            url,
+            wait_for_selector: input['wait_for_selector'] != null ? String(input['wait_for_selector']) : undefined,
+            extract,
+            timeout_seconds: input['timeout_seconds'] != null ? Number(input['timeout_seconds']) : undefined,
+        };
+        const result = await browseUrl(browseInput);
+        return formatBrowseResult(result, extract);
+    }
+}
+export function createWebBrowseTool(_opts) {
+    return new WebBrowseTool();
+}
+//# sourceMappingURL=web_browse.js.map

package/dist/src/benchmarks/gaia-tools/web_browse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web_browse.js","sourceRoot":"","sources":["../../../../src/benchmarks/gaia-tools/web_browse.ts"],"names":[],"mappings":"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"}

package/dist/src/benchmarks/gaia-tools/web_browse.smoke.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Smoke tests for web_browse — ADR-133-PR5
+ *
+ * Run with:
+ *   cd v3/@claude-flow/cli
+ *   npx tsx src/benchmarks/gaia-tools/web_browse.smoke.ts
+ *
+ * Requires Playwright to be installed:
+ *   npm install playwright
+ *   npx playwright install chromium
+ *
+ * If Playwright is not installed, tests that require it are skipped with
+ * a SKIP result (not a failure) — the install instructions are printed.
+ *
+ * Tests:
+ *   1. Browse Wikipedia page — content contains 'Mercedes', status 200
+ *   2. Bad URL with short timeout — returns error message (no crash)
+ *   3. Screenshot mode — returns non-empty base64 string
+ *   4. HTML extract mode — content contains '<html' or '<HTML'
+ *
+ * Cost: $0 (all local Playwright calls — no LLM).
+ *
+ * Refs: ADR-133, #2156
+ */
+export {};
+//# sourceMappingURL=web_browse.smoke.d.ts.map

package/dist/src/benchmarks/gaia-tools/web_browse.smoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web_browse.smoke.d.ts","sourceRoot":"","sources":["../../../../src/benchmarks/gaia-tools/web_browse.smoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/dist/src/benchmarks/gaia-tools/web_browse.smoke.js

@@ -0,0 +1,152 @@
+/**
+ * Smoke tests for web_browse — ADR-133-PR5
+ *
+ * Run with:
+ *   cd v3/@claude-flow/cli
+ *   npx tsx src/benchmarks/gaia-tools/web_browse.smoke.ts
+ *
+ * Requires Playwright to be installed:
+ *   npm install playwright
+ *   npx playwright install chromium
+ *
+ * If Playwright is not installed, tests that require it are skipped with
+ * a SKIP result (not a failure) — the install instructions are printed.
+ *
+ * Tests:
+ *   1. Browse Wikipedia page — content contains 'Mercedes', status 200
+ *   2. Bad URL with short timeout — returns error message (no crash)
+ *   3. Screenshot mode — returns non-empty base64 string
+ *   4. HTML extract mode — content contains '<html' or '<HTML'
+ *
+ * Cost: $0 (all local Playwright calls — no LLM).
+ *
+ * Refs: ADR-133, #2156
+ */
+import { createWebBrowseTool } from './web_browse.js';
+async function runTest(name, fn) {
+    try {
+        await fn();
+        return { name, status: 'PASS', message: 'OK' };
+    }
+    catch (e) {
+        const msg = String(e);
+        // If Playwright isn't installed, mark as SKIP rather than FAIL.
+        if (msg.includes('Playwright is not installed') ||
+            msg.includes('Cannot find module') ||
+            msg.includes('playwright')) {
+            return { name, status: 'SKIP', message: `Playwright not installed — ${msg}` };
+        }
+        return { name, status: 'FAIL', message: msg };
+    }
+}
+function assert(condition, msg) {
+    if (!condition)
+        throw new Error(`Assertion failed: ${msg}`);
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+const tool = createWebBrowseTool();
+// Test 1: Wikipedia text extraction
+async function testWikipedia() {
+    const out = await tool.execute({
+        url: 'https://en.wikipedia.org/wiki/Mercedes_Sosa',
+        extract: 'text',
+        timeout_seconds: 30,
+    });
+    // If Playwright is missing, execute() returns a structured error string.
+    if (out.startsWith('[web_browse error]')) {
+        throw new Error(out);
+    }
+    assert(out.toLowerCase().includes('mercedes') || out.toLowerCase().includes('sosa'), `Expected page text to contain "Mercedes" or "Sosa", got:\n${out.slice(0, 500)}`);
+    assert(out.includes('final_url:'), `Expected final_url in output, got:\n${out.slice(0, 200)}`);
+}
+// Test 2: Bad URL with short timeout — should return gracefully, not throw
+async function testBadUrlTimeout() {
+    const out = await tool.execute({
+        url: 'https://this-domain-absolutely-does-not-exist-gaia-bench.example',
+        extract: 'text',
+        timeout_seconds: 5,
+    });
+    // Either a Playwright "not installed" error or a network error — both are
+    // acceptable.  The tool must NOT throw; it must return a string.
+    assert(typeof out === 'string', 'Expected string output from bad-URL test');
+}
+// Test 3: Screenshot mode — returns base64 PNG
+async function testScreenshotMode() {
+    const out = await tool.execute({
+        url: 'https://en.wikipedia.org/wiki/Main_Page',
+        extract: 'screenshot',
+        timeout_seconds: 30,
+    });
+    if (out.startsWith('[web_browse error]')) {
+        throw new Error(out);
+    }
+    assert(out.includes('content:'), `Expected "content:" in output, got:\n${out.slice(0, 200)}`);
+    // Extract the base64 portion after "content:\n"
+    const contentIdx = out.indexOf('content:\n');
+    if (contentIdx !== -1) {
+        const b64 = out.slice(contentIdx + 'content:\n'.length).trim();
+        assert(b64.length > 100, `Expected non-trivial base64 data, got length ${b64.length}`);
+        // Base64 charset only
+        assert(/^[A-Za-z0-9+/=]+$/.test(b64.slice(0, 100)), `Expected base64-encoded output, got:\n${b64.slice(0, 100)}`);
+    }
+}
+// Test 4: HTML extract mode
+async function testHtmlExtract() {
+    const out = await tool.execute({
+        url: 'https://en.wikipedia.org/wiki/Main_Page',
+        extract: 'html',
+        timeout_seconds: 30,
+    });
+    if (out.startsWith('[web_browse error]')) {
+        throw new Error(out);
+    }
+    assert(out.toLowerCase().includes('<html') || out.includes('<!DOCTYPE'), `Expected HTML markup in output, got:\n${out.slice(0, 300)}`);
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+async function main() {
+    console.log('web_browse smoke tests — ADR-133-PR5\n');
+    const tests = [
+        runTest('Test 1: Wikipedia text extraction (contains "Mercedes")', testWikipedia),
+        runTest('Test 2: Bad URL with 5s timeout — no crash', testBadUrlTimeout),
+        runTest('Test 3: Screenshot mode — non-empty base64', testScreenshotMode),
+        runTest('Test 4: HTML extract mode — markup present', testHtmlExtract),
+    ];
+    // Run sequentially to avoid spawning 4 browser instances simultaneously.
+    const results = [];
+    for (const t of tests) {
+        results.push(await t);
+    }
+    let passed = 0;
+    let failed = 0;
+    let skipped = 0;
+    for (const r of results) {
+        console.log(`[${r.status}] ${r.name}`);
+        if (r.status !== 'PASS') {
+            console.log(`       ${r.message.slice(0, 300)}`);
+        }
+        if (r.status === 'PASS')
+            passed++;
+        else if (r.status === 'FAIL')
+            failed++;
+        else
+            skipped++;
+    }
+    console.log(`\nResults: ${passed} passed, ${failed} failed, ${skipped} skipped`);
+    if (skipped > 0) {
+        console.log('\nInstall Playwright to run skipped tests:');
+        console.log('  npm install playwright');
+        console.log('  npx playwright install chromium');
+    }
+    if (failed > 0) {
+        process.exit(1);
+    }
+}
+main().catch((e) => {
+    console.error('Fatal:', e);
+    process.exit(1);
+});
+//# sourceMappingURL=web_browse.smoke.js.map

package/dist/src/benchmarks/gaia-tools/web_browse.smoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web_browse.smoke.js","sourceRoot":"","sources":["../../../../src/benchmarks/gaia-tools/web_browse.smoke.ts"],"names":[],"mappings":"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"}

package/dist/src/benchmarks/gaia-tools/web_search.d.ts

@@ -0,0 +1,30 @@
+/**
+ * GAIA Tool: web_search — ADR-133-PR2
+ *
+ * Scrapes DuckDuckGo HTML search results for a query string and returns
+ * the top-N snippet titles + URLs as a plain-text block.  No API key
+ * required; uses DDG's HTML endpoint which is publicly accessible.
+ *
+ * Design notes:
+ * - Uses native Node.js https/http (no external fetch polyfill).
+ * - Follows the DDG Lite HTML endpoint: https://html.duckduckgo.com/html/?q=…
+ * - Parses result titles + URLs via a simple regex (no DOM parser dependency).
+ * - Rate-limit aware: 1-second back-off between calls is the caller's
+ *   responsibility (the agent loop enforces this in PR-3).
+ * - PDF / binary detection is handled by file_read.ts, not here.
+ *
+ * Refs: ADR-133, #2156
+ */
+import { GaiaTool, ToolDefinition } from './types.js';
+export interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+export declare class WebSearchTool implements GaiaTool {
+    readonly name = "web_search";
+    readonly definition: ToolDefinition;
+    execute(input: Record<string, unknown>): Promise<string>;
+}
+export declare function createWebSearchTool(): WebSearchTool;
+//# sourceMappingURL=web_search.d.ts.map

package/dist/src/benchmarks/gaia-tools/web_search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web_search.d.ts","sourceRoot":"","sources":["../../../../src/benchmarks/gaia-tools/web_search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAkBtD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AA2KD,qBAAa,aAAc,YAAW,QAAQ;IAC5C,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAmBjC;IAEI,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;CAa/D;AAMD,wBAAgB,mBAAmB,IAAI,aAAa,CAEnD"}

package/dist/src/benchmarks/gaia-tools/web_search.js

@@ -0,0 +1,210 @@
+/**
+ * GAIA Tool: web_search — ADR-133-PR2
+ *
+ * Scrapes DuckDuckGo HTML search results for a query string and returns
+ * the top-N snippet titles + URLs as a plain-text block.  No API key
+ * required; uses DDG's HTML endpoint which is publicly accessible.
+ *
+ * Design notes:
+ * - Uses native Node.js https/http (no external fetch polyfill).
+ * - Follows the DDG Lite HTML endpoint: https://html.duckduckgo.com/html/?q=…
+ * - Parses result titles + URLs via a simple regex (no DOM parser dependency).
+ * - Rate-limit aware: 1-second back-off between calls is the caller's
+ *   responsibility (the agent loop enforces this in PR-3).
+ * - PDF / binary detection is handled by file_read.ts, not here.
+ *
+ * Refs: ADR-133, #2156
+ */
+import * as https from 'node:https';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DDG_HTML_URL = 'https://html.duckduckgo.com/html/';
+const DEFAULT_MAX_RESULTS = 5;
+const REQUEST_TIMEOUT_MS = 20_000;
+// User-Agent that DDG accepts (plain browser UA).
+const UA = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36';
+// ---------------------------------------------------------------------------
+// HTML fetch helper
+// ---------------------------------------------------------------------------
+/**
+ * POST to DuckDuckGo's HTML search endpoint and return the raw HTML string.
+ * DDG blocks GET for automated scrapers but accepts POST form submissions.
+ */
+async function fetchDdgHtml(query) {
+    const body = `q=${encodeURIComponent(query)}&b=&kl=&df=`;
+    const bodyBytes = Buffer.from(body, 'utf-8');
+    return new Promise((resolve, reject) => {
+        const options = {
+            hostname: 'html.duckduckgo.com',
+            path: '/html/',
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                'Content-Length': bodyBytes.length,
+                'User-Agent': UA,
+                Accept: 'text/html,application/xhtml+xml',
+                'Accept-Language': 'en-US,en;q=0.9',
+            },
+        };
+        const req = https.request(options, (res) => {
+            // Follow a single redirect if needed (DDG occasionally redirects to /html/)
+            if (res.statusCode !== undefined &&
+                res.statusCode >= 300 &&
+                res.statusCode < 400 &&
+                res.headers.location) {
+                const loc = res.headers.location;
+                res.resume();
+                // Simple follow — only handle absolute https redirects
+                if (loc.startsWith('https://')) {
+                    https
+                        .get(loc, { headers: { 'User-Agent': UA } }, (r2) => {
+                        const chunks = [];
+                        r2.on('data', (c) => chunks.push(c));
+                        r2.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+                        r2.on('error', reject);
+                    })
+                        .on('error', reject);
+                }
+                else {
+                    reject(new Error(`Unexpected redirect target: ${loc}`));
+                }
+                return;
+            }
+            if (res.statusCode !== 200) {
+                res.resume();
+                reject(new Error(`DDG returned HTTP ${res.statusCode ?? 'unknown'}`));
+                return;
+            }
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+            res.on('error', reject);
+        });
+        req.on('error', reject);
+        req.setTimeout(REQUEST_TIMEOUT_MS, () => {
+            req.destroy(new Error(`web_search timeout after ${REQUEST_TIMEOUT_MS}ms`));
+        });
+        req.write(bodyBytes);
+        req.end();
+    });
+}
+// ---------------------------------------------------------------------------
+// HTML parser (regex-based, no DOM)
+// ---------------------------------------------------------------------------
+/**
+ * Extract up to `maxResults` search results from DDG HTML.
+ *
+ * DDG's HTML result structure (stable as of 2026):
+ *   <a class="result__a" href="URL">TITLE</a>
+ *   <a class="result__snippet">SNIPPET</a>
+ *
+ * We parse with regex to avoid adding an htmlparser2 dependency.
+ */
+function parseDdgHtml(html, maxResults) {
+    const results = [];
+    // Match result blocks — DDG wraps each result in <div class="result …">
+    // We extract title+url from the result__a anchor, and snippet from result__snippet.
+    const resultBlockRe = /<a[^>]+class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?(?:<a[^>]+class="result__snippet"[^>]*>([\s\S]*?)<\/a>)?/g;
+    let match;
+    while ((match = resultBlockRe.exec(html)) !== null && results.length < maxResults) {
+        const rawUrl = match[1] ?? '';
+        const rawTitle = match[2] ?? '';
+        const rawSnippet = match[3] ?? '';
+        // DDG wraps URLs in //duckduckgo.com/l/?uddg=ENCODED_URL
+        const url = decodeRawUrl(rawUrl);
+        const title = stripHtml(rawTitle).trim();
+        const snippet = stripHtml(rawSnippet).trim();
+        if (url && title) {
+            results.push({ title, url, snippet });
+        }
+    }
+    return results;
+}
+/**
+ * Decode the DDG redirect URL back to the real URL.
+ * Input example: //duckduckgo.com/l/?uddg=https%3A%2F%2Fexample.com%2F&rut=…
+ */
+function decodeRawUrl(raw) {
+    if (raw.startsWith('//duckduckgo.com/l/')) {
+        const qIdx = raw.indexOf('uddg=');
+        if (qIdx !== -1) {
+            const encoded = raw.slice(qIdx + 5).split('&')[0];
+            try {
+                return decodeURIComponent(encoded);
+            }
+            catch {
+                return raw;
+            }
+        }
+    }
+    // Direct URL (some results skip the redirect)
+    if (raw.startsWith('http://') || raw.startsWith('https://'))
+        return raw;
+    return raw;
+}
+/** Strip HTML tags and decode common entities. */
+function stripHtml(html) {
+    return html
+        .replace(/<[^>]+>/g, '')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#x27;/g, "'")
+        .replace(/&nbsp;/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+// ---------------------------------------------------------------------------
+// Format output for Claude
+// ---------------------------------------------------------------------------
+function formatResults(results) {
+    if (results.length === 0) {
+        return 'No results found.';
+    }
+    return results
+        .map((r, i) => `[${i + 1}] ${r.title}\n    URL: ${r.url}${r.snippet ? '\n    ' + r.snippet : ''}`)
+        .join('\n\n');
+}
+// ---------------------------------------------------------------------------
+// GaiaTool implementation
+// ---------------------------------------------------------------------------
+export class WebSearchTool {
+    name = 'web_search';
+    definition = {
+        name: 'web_search',
+        description: 'Search the web using DuckDuckGo and return the top results (title, URL, snippet). ' +
+            'Use this when you need current information, external facts, or to verify claims.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'The search query string.',
+                },
+                max_results: {
+                    type: 'number',
+                    description: `Maximum number of results to return (default: ${DEFAULT_MAX_RESULTS}, max: 10).`,
+                },
+            },
+            required: ['query'],
+        },
+    };
+    async execute(input) {
+        const query = String(input['query'] ?? '').trim();
+        if (!query)
+            throw new Error('web_search: `query` input is required and must be non-empty.');
+        const maxResults = Math.min(Math.max(1, Number(input['max_results'] ?? DEFAULT_MAX_RESULTS)), 10);
+        const html = await fetchDdgHtml(query);
+        const results = parseDdgHtml(html, maxResults);
+        return formatResults(results);
+    }
+}
+// ---------------------------------------------------------------------------
+// Convenience factory
+// ---------------------------------------------------------------------------
+export function createWebSearchTool() {
+    return new WebSearchTool();
+}
+//# sourceMappingURL=web_search.js.map