@swarmdo/cli 1.4.8

package/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 Swarmdo'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=swarm-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=swarm-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 swarm-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/dist/src/benchmarks/gaia-tools/grounded_query.js.map

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

package/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/dist/src/benchmarks/gaia-tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/benchmarks/gaia-tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AAKpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,IAAI,iBAAiB,CAE9D"}

package/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/dist/src/benchmarks/gaia-tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/benchmarks/gaia-tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AAEpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAG9D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO,CAAC,mBAAmB,EAAE,EAAE,kBAAkB,EAAE,EAAE,uBAAuB,EAAE,CAAC,CAAC;AAClF,CAAC"}

package/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/dist/src/benchmarks/gaia-tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/benchmarks/gaia-tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,eAAe,CAAC;CAC/B;AAMD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAMD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAMD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,eAAe,CAAC;AAMtE,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,OAAO,EAAE,YAAY,CAAC;IACtB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD,MAAM,WAAW,QAAQ;IACvB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1D;AAMD,MAAM,MAAM,iBAAiB,GAAG,QAAQ,EAAE,CAAC"}

package/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/dist/src/benchmarks/gaia-tools/types.js.map

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

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;AAmLD,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,218 @@
+/**
+ * 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) {
+    // Strip tags repeatedly — a single pass on '<<a>script>' would leave
+    // '<script>' (js/incomplete-multi-character-sanitization).
+    let text = html;
+    let prev;
+    do {
+        prev = text;
+        text = text.replace(/<[^>]+>/g, '');
+    } while (text !== prev);
+    return text
+        // Decode &amp; LAST so a decoded '&' can't re-form another entity (js/double-escaping).
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#x27;/g, "'")
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/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