claude-flow 3.10.4 → 3.10.5

package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-tools/grounded_query.js

@@ -0,0 +1,225 @@
+/**
+ * GAIA Tool: grounded_query — ADR-135 / iter-33
+ *
+ * Calls Gemini 2.5 Flash with the google_search grounding tool and returns
+ * a synthesised factual answer plus source citations in a single API call.
+ *
+ * Architectural advantage over web_search (Google Custom Search):
+ *   - web_search: raw snippets → agent reads + parses → 2-3 extra turns
+ *   - grounded_query: Gemini synthesises an answer + cites sources in 1 call
+ *
+ * This is Ruflo's cross-provider stack in action:
+ *   Gemini grounds (google_search tool) → Sonnet/Haiku reasons → answer
+ *
+ * Credential resolution (mirrors performance-capability.ts / web_search.ts):
+ *   1. process.env.GOOGLE_AI_API_KEY
+ *   2. gcloud secrets versions access latest --secret=GOOGLE_AI_API_KEY --project=ruv-dev
+ *   3. Throws with clear instructions if neither is available
+ *
+ * Free tier: 1500 grounded queries/day on Gemini 2.5 Flash.
+ * Pricing: ~$0.075/M input tokens, ~$0.30/M output tokens, grounding free <1500/day.
+ *
+ * Regression note (iter-47): this file was absent from feat/adr-135-integrate-tracks
+ * because the grounded-query-gemini branch was not cherry-picked during Track integration.
+ * The omission caused a 36-question empty-answer failure in iter-42 (13.2% vs 49.1% baseline).
+ *
+ * Refs: ADR-133, ADR-135, iter-30 research, iter-33, iter-47, #2156
+ * Live-tested 2026-05-27: Mercedes Sosa GAIA L1 question → HTTP 200, 4 sources.
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const GEMINI_GENERATE_CONTENT_URL = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent';
+const DEFAULT_MAX_TOKENS = 1024;
+const REQUEST_TIMEOUT_MS = 30_000;
+// Gemini 2.5 Flash pricing (USD per 1M tokens, grounding free under 1500/day)
+const PRICE_INPUT_PER_M = 0.075;
+const PRICE_OUTPUT_PER_M = 0.30;
+export const groundedQueryTestHooks = {};
+// ---------------------------------------------------------------------------
+// Credential resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a Google AI API key.
+ *
+ * Order: env var → gcloud secret → throw.
+ * Never returns null — throws with actionable guidance if no key is found.
+ */
+export async function resolveGoogleAIApiKey() {
+    // 1. Environment variable (fastest path, used in test mocks and CI)
+    const envKey = process.env['GOOGLE_AI_API_KEY'];
+    if (envKey)
+        return envKey;
+    // 2. GCP Secrets Manager (matches resolveApiKey pattern in gaia-bench.ts)
+    try {
+        const { execSync } = await import('node:child_process');
+        const key = execSync('gcloud secrets versions access latest --secret=GOOGLE_AI_API_KEY --project=ruv-dev 2>/dev/null', { encoding: 'utf-8', timeout: 5_000 }).trim();
+        if (key)
+            return key;
+    }
+    catch {
+        // gcloud not installed, project unreachable, or secret not yet created
+    }
+    throw new Error('grounded_query: No Google AI API key found.\n' +
+        'Set GOOGLE_AI_API_KEY env var, or ensure `gcloud` is authenticated and\n' +
+        'the secret GOOGLE_AI_API_KEY exists in GCP project ruv-dev.\n' +
+        'Get a free key at: https://aistudio.google.com/apikey');
+}
+// ---------------------------------------------------------------------------
+// Gemini Grounding API call
+// ---------------------------------------------------------------------------
+/**
+ * Call Gemini 2.5 Flash with google_search grounding and parse the response.
+ *
+ * Exported so smoke tests can exercise the parser without live HTTP (via
+ * groundedQueryTestHooks.fetchResponse).
+ */
+export async function callGeminiGrounded(query, maxTokens, apiKey) {
+    const url = `${GEMINI_GENERATE_CONTENT_URL}?key=${encodeURIComponent(apiKey)}`;
+    const requestBody = {
+        contents: [{ parts: [{ text: query }] }],
+        tools: [{ google_search: {} }],
+        generationConfig: { maxOutputTokens: maxTokens },
+    };
+    let rawBody;
+    if (groundedQueryTestHooks.fetchResponse) {
+        rawBody = await groundedQueryTestHooks.fetchResponse(query, maxTokens, apiKey);
+    }
+    else {
+        const resp = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            body: JSON.stringify(requestBody),
+        });
+        if (!resp.ok) {
+            const errText = (await resp.text()).slice(0, 400);
+            throw new Error(`grounded_query: Gemini HTTP ${resp.status}: ${errText}`);
+        }
+        rawBody = (await resp.json());
+    }
+    return parseGeminiResponse(rawBody);
+}
+/**
+ * Parse a raw Gemini generateContent response into GroundedQueryResult.
+ * Exported for unit testing the parser independently.
+ */
+export function parseGeminiResponse(body) {
+    const candidate = body.candidates?.[0];
+    // Extract text answer
+    const answer = (candidate?.content?.parts ?? [])
+        .map((p) => p.text ?? '')
+        .join('');
+    // Extract grounding metadata
+    const meta = candidate?.groundingMetadata;
+    const chunks = meta?.groundingChunks ?? [];
+    const searchQueries = meta?.webSearchQueries ?? [];
+    // Build source list from grounding chunks (deduplicate by URI)
+    const seenUris = new Set();
+    const sources = [];
+    for (const chunk of chunks) {
+        const uri = chunk.web?.uri ?? '';
+        const title = chunk.web?.title ?? '';
+        if (uri && !seenUris.has(uri)) {
+            seenUris.add(uri);
+            sources.push({ title, uri });
+        }
+    }
+    // Estimate cost
+    const inputTokens = body.usageMetadata?.promptTokenCount ?? 0;
+    const outputTokens = body.usageMetadata?.candidatesTokenCount ?? 0;
+    const costUsd = (inputTokens / 1_000_000) * PRICE_INPUT_PER_M +
+        (outputTokens / 1_000_000) * PRICE_OUTPUT_PER_M;
+    return {
+        answer,
+        sources,
+        search_queries_used: searchQueries,
+        grounded: sources.length > 0 || searchQueries.length > 0,
+        model: 'gemini-2.5-flash',
+        cost_usd: costUsd,
+    };
+}
+// ---------------------------------------------------------------------------
+// Format output for Claude (mirrors web_search formatResults pattern)
+// ---------------------------------------------------------------------------
+function formatResult(result) {
+    const lines = [];
+    lines.push(`[grounded_query model: ${result.model}]`);
+    if (result.answer) {
+        lines.push('');
+        lines.push(result.answer.trim());
+    }
+    if (result.sources.length > 0) {
+        lines.push('');
+        lines.push('Sources:');
+        for (let i = 0; i < result.sources.length; i++) {
+            const s = result.sources[i];
+            lines.push(`[${i + 1}] ${s.title}`);
+            lines.push(`    ${s.uri}`);
+        }
+    }
+    if (result.search_queries_used.length > 0) {
+        lines.push('');
+        lines.push(`Search queries: ${result.search_queries_used.join('; ')}`);
+    }
+    if (!result.grounded) {
+        lines.push('');
+        lines.push('[Note: No grounding metadata returned — answer is unverified.]');
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// GaiaTool implementation
+// ---------------------------------------------------------------------------
+export class GroundedQueryTool {
+    name = 'grounded_query';
+    definition = {
+        name: 'grounded_query',
+        description: 'Query Google Search via Gemini 2.5 Flash grounding. ' +
+            'Returns a synthesised factual answer with source citations in a single call — ' +
+            'more efficient than web_search for factoid questions because Gemini pre-synthesises ' +
+            'the answer rather than returning raw snippets. ' +
+            'Use this for: factual lookups, "what year did X happen", "how many Y", ' +
+            '"who is Z", or any question requiring current web information with a clean answer. ' +
+            'Use web_search instead when you need to read a source page in full.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Question or factual lookup to ground via Google Search.',
+                },
+                max_tokens: {
+                    type: 'number',
+                    description: `Maximum response length in tokens (default: ${DEFAULT_MAX_TOKENS}).`,
+                },
+            },
+            required: ['query'],
+        },
+    };
+    apiKey;
+    constructor(opts) {
+        this.apiKey = opts?.apiKey;
+    }
+    async execute(input) {
+        const query = String(input['query'] ?? '').trim();
+        if (!query) {
+            throw new Error('grounded_query: `query` input is required and must be non-empty.');
+        }
+        const maxTokens = Math.min(Math.max(64, Number(input['max_tokens'] ?? DEFAULT_MAX_TOKENS)), 8192);
+        const resolveKeyFn = groundedQueryTestHooks.resolveKey ?? resolveGoogleAIApiKey;
+        const apiKey = this.apiKey ?? (await resolveKeyFn());
+        process.stderr.write(`[grounded_query] model=gemini-2.5-flash query=${JSON.stringify(query)}\n`);
+        const result = await callGeminiGrounded(query, maxTokens, apiKey);
+        process.stderr.write(`[grounded_query] grounded=${result.grounded} sources=${result.sources.length} ` +
+            `cost_usd=${result.cost_usd.toFixed(6)}\n`);
+        return formatResult(result);
+    }
+}
+// ---------------------------------------------------------------------------
+// Convenience factory
+// ---------------------------------------------------------------------------
+export function createGroundedQueryTool(opts) {
+    return new GroundedQueryTool(opts);
+}
+//# sourceMappingURL=grounded_query.js.map

package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-tools/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * gaia-tools barrel — ADR-133-PR2
+ *
+ * Exports all tool implementations + shared types so that gaia-agent.ts
+ * (PR-3) and future tools (PR-4: python_exec, PR-5: web_browse) can import
+ * from a single entry point.
+ *
+ * iter-47 fix: re-added grounded_query which was absent from the integration
+ * branch because feat/adr-135-grounded-query-gemini was never cherry-picked
+ * during Track A/B/D/E/Q integration (iter-42 measured −36pp / 13.2%).
+ *
+ * Refs: ADR-133, ADR-135, #2156
+ */
+export * from './types.js';
+export * from './web_search.js';
+export * from './file_read.js';
+export * from './grounded_query.js';
+import type { GaiaToolCatalogue } from './types.js';
+/**
+ * Returns the default tool catalogue for a GAIA Level-1 run.
+ *
+ * PR-2 catalogue: web_search + file_read
+ * iter-33 adds:   grounded_query (Gemini 2.5 Flash grounding — pre-synthesised answer + citations)
+ * PR-4 will add:  python_exec (E2B sandbox)
+ * PR-5 will add:  web_browse, image_describe
+ *
+ * Both web_search and grounded_query are registered so the agent can choose:
+ *   - grounded_query: for factoid questions needing a clean answer with citations (1 call)
+ *   - web_search: for questions needing raw snippets or source page reading (multi-backend)
+ */
+export declare function createDefaultToolCatalogue(): GaiaToolCatalogue;
+//# sourceMappingURL=index.d.ts.map

package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-tools/index.js

@@ -0,0 +1,36 @@
+/**
+ * gaia-tools barrel — ADR-133-PR2
+ *
+ * Exports all tool implementations + shared types so that gaia-agent.ts
+ * (PR-3) and future tools (PR-4: python_exec, PR-5: web_browse) can import
+ * from a single entry point.
+ *
+ * iter-47 fix: re-added grounded_query which was absent from the integration
+ * branch because feat/adr-135-grounded-query-gemini was never cherry-picked
+ * during Track A/B/D/E/Q integration (iter-42 measured −36pp / 13.2%).
+ *
+ * Refs: ADR-133, ADR-135, #2156
+ */
+export * from './types.js';
+export * from './web_search.js';
+export * from './file_read.js';
+export * from './grounded_query.js';
+import { createWebSearchTool } from './web_search.js';
+import { createFileReadTool } from './file_read.js';
+import { createGroundedQueryTool } from './grounded_query.js';
+/**
+ * Returns the default tool catalogue for a GAIA Level-1 run.
+ *
+ * PR-2 catalogue: web_search + file_read
+ * iter-33 adds:   grounded_query (Gemini 2.5 Flash grounding — pre-synthesised answer + citations)
+ * PR-4 will add:  python_exec (E2B sandbox)
+ * PR-5 will add:  web_browse, image_describe
+ *
+ * Both web_search and grounded_query are registered so the agent can choose:
+ *   - grounded_query: for factoid questions needing a clean answer with citations (1 call)
+ *   - web_search: for questions needing raw snippets or source page reading (multi-backend)
+ */
+export function createDefaultToolCatalogue() {
+    return [createWebSearchTool(), createFileReadTool(), createGroundedQueryTool()];
+}
+//# sourceMappingURL=index.js.map

package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-tools/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared types for the GAIA agent tool-use subsystem — ADR-133-PR2
+ *
+ * These types mirror the Anthropic Messages API `tool_use` / `tool_result`
+ * content block spec so that `gaia-agent.ts` (PR-3) can call the Anthropic
+ * SDK without an extra type-mapping layer.
+ *
+ * Refs: ADR-133, #2156
+ * https://docs.anthropic.com/en/api/messages
+ */
+export interface ToolInputSchema {
+    type: 'object';
+    properties: Record<string, {
+        type: string;
+        description?: string;
+    }>;
+    required?: string[];
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    input_schema: ToolInputSchema;
+}
+export interface ToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    /** Optional — set to true when the tool fails so Claude can recover. */
+    is_error?: boolean;
+}
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+export type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock;
+export interface ToolCallResult {
+    /** The block that triggered this call. */
+    toolUse: ToolUseBlock;
+    /** String output to return to Claude (or error description). */
+    output: string;
+    /** True if the tool returned an error output. */
+    isError: boolean;
+}
+export interface GaiaTool {
+    /** Must match the `name` field in the ToolDefinition. */
+    readonly name: string;
+    /** The definition object passed to Anthropic in the `tools` array. */
+    readonly definition: ToolDefinition;
+    /**
+     * Execute the tool.  Returns a plain string (success) or throws (will be
+     * caught by the agent loop and wrapped in an `is_error: true` result).
+     */
+    execute(input: Record<string, unknown>): Promise<string>;
+}
+export type GaiaToolCatalogue = GaiaTool[];
+//# sourceMappingURL=types.d.ts.map

package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-tools/types.js

@@ -0,0 +1,12 @@
+/**
+ * Shared types for the GAIA agent tool-use subsystem — ADR-133-PR2
+ *
+ * These types mirror the Anthropic Messages API `tool_use` / `tool_result`
+ * content block spec so that `gaia-agent.ts` (PR-3) can call the Anthropic
+ * SDK without an extra type-mapping layer.
+ *
+ * Refs: ADR-133, #2156
+ * https://docs.anthropic.com/en/api/messages
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/v3/@claude-flow/cli/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/v3/@claude-flow/cli/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