@nexus-cortex/executors 4.26.0

package/dist/implementations/web/WebSearchTool.js

@@ -0,0 +1,227 @@
+/**
+ * WebSearch Tool Executor — multi-provider.
+ *
+ * Backends (selected by WEB_TOOLS_MODEL env var):
+ *   - Anthropic Claude   → web_search_20250305 server tool
+ *   - XAI Grok           → Responses API web_search server tool
+ *   - Google Gemini      → googleSearch grounding (UTF-8 byte-accurate citations)
+ *   - DuckDuckGo HTML    → fallback when no provider key is available
+ *
+ * nexus-browser is intentionally not a backend here. It is exposed as a
+ * gated MCP server and reached only via the MCP transport.
+ */
+import { GoogleGenAI } from '@google/genai';
+import { BaseTool } from '../../base/index.js';
+import { SchemaValidator } from '../../utils/SchemaValidator.js';
+import { getWebToolsModel, resolveProvider, runWebSearch, } from './webBackends.js';
+import { buildBrowseSubagentDispatch } from './BrowseTool.js';
+export class WebSearchTool extends BaseTool {
+    config;
+    genAI = null;
+    constructor(config) {
+        super('WebSearch', 'WebSearch', `Performs a web search and returns results with citations.
+
+Backend is selected automatically based on the WEB_TOOLS_MODEL setting and available API keys:
+- Anthropic Claude models use the Claude web_search server tool
+- XAI Grok models use the XAI Responses API web_search server tool
+- OpenAI GPT/o-series models use the Responses API web_search_preview server tool
+- Google Gemini models use Google Search grounding via the Gemini API
+- A DuckDuckGo HTML fallback is used when no provider is configured
+
+Use this tool to find current information, facts, news, and data from the internet. Results include source attribution.`, {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'The search query to find information on the web. Can be a question or keywords.',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['fast', 'interactive'],
+                    description: "Default 'fast' uses the provider's native search. Set to 'interactive' to dispatch a nexus-browser subagent for JS-rendered SPAs, auth-gated pages, or anything that needs interaction.",
+                },
+            },
+            required: ['query'],
+        });
+        this.config = config;
+    }
+    getGeminiClient() {
+        if (!this.genAI) {
+            const apiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
+            if (!apiKey) {
+                throw new Error('Google API key not found. Please set GEMINI_API_KEY or GOOGLE_API_KEY environment variable.');
+            }
+            this.genAI = new GoogleGenAI({ apiKey });
+        }
+        return this.genAI;
+    }
+    validateToolParams(params) {
+        const schemaError = SchemaValidator.validate(this.parameterSchema, params);
+        if (schemaError)
+            return schemaError;
+        if (!params.query || params.query.trim() === '') {
+            return "The 'query' parameter cannot be empty.";
+        }
+        return null;
+    }
+    getDescription(params) {
+        return `Searching the web for: "${params.query}"`;
+    }
+    async execute(params, signal) {
+        const startTime = Date.now();
+        try {
+            const validationError = this.validateToolParams(params);
+            if (validationError) {
+                return {
+                    ...this.createErrorResult(validationError),
+                    metadata: { executionTime: Date.now() - startTime },
+                };
+            }
+            // Interactive mode: hand off to nexus-browser subagent. Same dispatch
+            // contract as the Browse tool — orchestrator handles the rest.
+            if (params.mode === 'interactive') {
+                // Recursion guard: inside a subagent, fall through to the fast path
+                // instead of trying to spawn another subagent.
+                if ((process.env.CORTEX_AGENT_MODE) === 'true') {
+                    console.warn('[WebSearch] mode=interactive ignored inside subagent (recursion guard) — using fast path');
+                }
+                else {
+                    return buildBrowseSubagentDispatch(`Search the web for: ${params.query}\n\n` +
+                        `Use the nexus-browser tools to navigate search engines if needed, click into results, ` +
+                        `and extract the most relevant content. Return a concise summary with sources.`, undefined, `Web search (interactive): ${params.query.slice(0, 80)}`, startTime);
+                }
+            }
+            const modelId = getWebToolsModel();
+            const provider = resolveProvider(modelId);
+            // Gemini path uses the @google/genai SDK directly for byte-accurate citation insertion.
+            const useGeminiSdk = provider === 'google' &&
+                !!(process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY);
+            if (useGeminiSdk) {
+                return await this.runGeminiSearch(params.query, modelId, startTime);
+            }
+            // Anthropic / XAI / DuckDuckGo fallback.
+            const result = await runWebSearch(params.query);
+            const formatted = this.formatBackendOutput(result.text, result.sources);
+            return {
+                ...this.createSuccessResult(formatted),
+                sources: result.sources.map((s) => ({ web: { title: s.title, uri: s.url } })),
+                metadata: {
+                    executionTime: Date.now() - startTime,
+                    query: params.query,
+                    sourceCount: result.sources.length,
+                    backend: result.backend,
+                },
+            };
+        }
+        catch (error) {
+            if (signal.aborted) {
+                return {
+                    ...this.createErrorResult('Search operation was cancelled'),
+                    metadata: { executionTime: Date.now() - startTime },
+                };
+            }
+            const errorMessage = error?.message ?? String(error);
+            return {
+                ...this.createErrorResult(`Error performing web search: ${errorMessage}`),
+                metadata: { executionTime: Date.now() - startTime, error: errorMessage },
+            };
+        }
+    }
+    formatBackendOutput(text, sources) {
+        if (sources.length === 0)
+            return text;
+        const list = sources
+            .map((s, i) => `[${i + 1}] ${s.title ?? 'Untitled'} (${s.url})`)
+            .join('\n');
+        return `${text}\n\nSources:\n${list}`;
+    }
+    async runGeminiSearch(query, modelId, startTime) {
+        const genAI = this.getGeminiClient();
+        const result = await genAI.models.generateContent({
+            model: modelId,
+            contents: query,
+            config: {
+                tools: [{ googleSearch: {} }],
+            },
+        });
+        let responseText = result.text || '';
+        const candidate = result.candidates?.[0];
+        const groundingMetadata = candidate?.groundingMetadata;
+        const sources = groundingMetadata?.groundingChunks;
+        const groundingSupports = groundingMetadata?.groundingSupports;
+        if (!responseText || !responseText.trim()) {
+            return {
+                ...this.createSuccessResult(`No search results or information found for query: "${query}"`),
+                sources: [],
+                metadata: {
+                    executionTime: Date.now() - startTime,
+                    query,
+                    sourceCount: 0,
+                    backend: 'gemini-googleSearch',
+                },
+            };
+        }
+        if (groundingSupports && groundingSupports.length > 0) {
+            responseText = this.insertCitationsUTF8(responseText, groundingSupports);
+        }
+        if (sources && sources.length > 0) {
+            const sourceList = sources
+                .map((source, index) => {
+                const title = source.web?.title || 'Untitled';
+                const uri = source.web?.uri || 'No URI';
+                return `[${index + 1}] ${title} (${uri})`;
+            })
+                .join('\n');
+            responseText += `\n\nSources:\n${sourceList}`;
+        }
+        return {
+            ...this.createSuccessResult(responseText),
+            sources,
+            metadata: {
+                executionTime: Date.now() - startTime,
+                query,
+                sourceCount: sources?.length ?? 0,
+                backend: 'gemini-googleSearch',
+            },
+        };
+    }
+    /**
+     * Insert citations at UTF-8 byte-accurate positions. Gemini grounding
+     * metadata uses byte offsets (not character indices), so multi-byte UTF-8
+     * characters must be handled via TextEncoder/TextDecoder.
+     */
+    insertCitationsUTF8(responseText, groundingSupports) {
+        if (!groundingSupports || groundingSupports.length === 0)
+            return responseText;
+        const insertions = [];
+        for (const support of groundingSupports) {
+            if (support.segment && support.groundingChunkIndices) {
+                const marker = support.groundingChunkIndices
+                    .map((i) => `[${i + 1}]`)
+                    .join('');
+                insertions.push({ index: support.segment.endIndex, marker });
+            }
+        }
+        insertions.sort((a, b) => b.index - a.index);
+        const encoder = new TextEncoder();
+        const responseBytes = encoder.encode(responseText);
+        const parts = [];
+        let lastIndex = responseBytes.length;
+        for (const ins of insertions) {
+            const pos = Math.min(ins.index, lastIndex);
+            parts.unshift(responseBytes.subarray(pos, lastIndex));
+            parts.unshift(encoder.encode(ins.marker));
+            lastIndex = pos;
+        }
+        parts.unshift(responseBytes.subarray(0, lastIndex));
+        const totalLength = parts.reduce((sum, p) => sum + p.length, 0);
+        const finalBytes = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const part of parts) {
+            finalBytes.set(part, offset);
+            offset += part.length;
+        }
+        return new TextDecoder().decode(finalBytes);
+    }
+}
+//# sourceMappingURL=WebSearchTool.js.map

package/dist/implementations/web/WebSearchTool.js.map

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

package/dist/implementations/web/escalateDirective.d.ts

@@ -0,0 +1,11 @@
+/**
+ * In-band escalation directive appended to every WebFetch failure result.
+ *
+ * WebFetch routes through Gemini urlContext with a 10s plain-fetch fallback;
+ * both fail on blocked / JS-heavy / dynamic pages (county record sites, etc.).
+ * Weaker models then retry WebFetch in a loop instead of switching tools.
+ * This tells the model — at the moment of failure, where it cannot be missed
+ * — to stop retrying WebFetch and use the browser instead.
+ */
+export declare function browseEscalationDirective(url?: string): string;
+//# sourceMappingURL=escalateDirective.d.ts.map

package/dist/implementations/web/escalateDirective.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalateDirective.d.ts","sourceRoot":"","sources":["../../../src/implementations/web/escalateDirective.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAW9D"}

package/dist/implementations/web/escalateDirective.js

@@ -0,0 +1,20 @@
+/**
+ * In-band escalation directive appended to every WebFetch failure result.
+ *
+ * WebFetch routes through Gemini urlContext with a 10s plain-fetch fallback;
+ * both fail on blocked / JS-heavy / dynamic pages (county record sites, etc.).
+ * Weaker models then retry WebFetch in a loop instead of switching tools.
+ * This tells the model — at the moment of failure, where it cannot be missed
+ * — to stop retrying WebFetch and use the browser instead.
+ */
+export function browseEscalationDirective(url) {
+    const target = url ? ` "${url}"` : ' the same URL';
+    return (`<system-reminder>WebFetch could not retrieve${target} — the page is ` +
+        `blocked, dynamic, or JS-rendered. Do NOT retry WebFetch on this URL; it ` +
+        `will keep failing. Call the \`browse\` tool instead:\n` +
+        ` browse({ task: "Navigate to${target} and extract the page content", url: ${url ? `"${url}"` : 'the URL'} })\n` +
+        `The browse subagent renders JavaScript, handles CAPTCHAs/challenges ` +
+        `(detect_challenge + solve_challenge), and returns the result. Do not ` +
+        `attempt WebFetch again for this page.</system-reminder>`);
+}
+//# sourceMappingURL=escalateDirective.js.map

package/dist/implementations/web/escalateDirective.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalateDirective.js","sourceRoot":"","sources":["../../../src/implementations/web/escalateDirective.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAY;IACpD,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC;IACnD,OAAO,CACL,+CAA+C,MAAM,iBAAiB;QACtE,0EAA0E;QAC1E,wDAAwD;QACxD,+BAA+B,MAAM,wCAAwC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,OAAO;QAChH,sEAAsE;QACtE,uEAAuE;QACvE,yDAAyD,CAC1D,CAAC;AACJ,CAAC"}

package/dist/implementations/web/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Web Tool Implementations
+ *
+ * Provides web search and fetch capabilities using Gemini API built-in tools
+ */
+export * from './WebSearchTool.js';
+export * from './WebFetchTool.js';
+export * from './BrowseTool.js';
+export * from './SandboxTransferTool.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/implementations/web/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/implementations/web/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}

package/dist/implementations/web/index.js

@@ -0,0 +1,10 @@
+/**
+ * Web Tool Implementations
+ *
+ * Provides web search and fetch capabilities using Gemini API built-in tools
+ */
+export * from './WebSearchTool.js';
+export * from './WebFetchTool.js';
+export * from './BrowseTool.js';
+export * from './SandboxTransferTool.js';
+//# sourceMappingURL=index.js.map

package/dist/implementations/web/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/implementations/web/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}

package/dist/implementations/web/webBackends.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Web Tool Backends — Multi-provider implementations for WebSearch / WebFetch.
+ *
+ * Resolution order (per call):
+ *   1. Provider-native server-side web tool, selected by WEB_TOOLS_MODEL env var:
+ *        - Anthropic Claude → Messages API + `web_search_20250305` server tool
+ *        - XAI Grok        → Responses API + `web_search` server tool
+ *        - Google Gemini   → GenerateContent + `googleSearch` grounding (default)
+ *   2. DuckDuckGo HTML fallback (no API key required) — last resort when:
+ *        - WEB_TOOLS_MODEL is unset, OR
+ *        - the configured provider's API key is missing.
+ *
+ * Provider is inferred from the model ID prefix; this matches the
+ * AdapterRegistry's pattern detection. nexus-browser is intentionally NOT a
+ * backend here — it is exposed via MCP only, with auth gating at the protocol
+ * layer (see nexus-cortex OSS / nexus-browser monetization boundary).
+ */
+export type WebProvider = 'anthropic' | 'xai' | 'openai' | 'google' | 'fallback';
+export interface BackendResult {
+    /** Combined text body */
+    text: string;
+    /** Source links for citation */
+    sources: Array<{
+        title?: string;
+        url: string;
+    }>;
+    /** Which backend produced this */
+    backend: string;
+}
+/** Resolve which provider serves a given model ID. */
+export declare function resolveProvider(modelId: string | undefined): WebProvider;
+export declare function anthropicSearch(query: string, modelId: string): Promise<BackendResult>;
+export declare function anthropicFetch(prompt: string, modelId: string): Promise<BackendResult>;
+export declare function xaiSearch(query: string, modelId: string): Promise<BackendResult>;
+export declare function xaiFetch(prompt: string, modelId: string): Promise<BackendResult>;
+export declare function openaiSearch(query: string, modelId: string): Promise<BackendResult>;
+export declare function openaiFetch(prompt: string, modelId: string): Promise<BackendResult>;
+export declare function duckDuckGoSearch(query: string): Promise<BackendResult>;
+/** Direct HTTP fetch + html-to-text. URL must be public. */
+export declare function directFetch(url: string): Promise<BackendResult>;
+/**
+ * Selected web tools model ID. Reads `WEB_TOOLS_MODEL` and, if unset,
+ * picks a sensible default based on which provider key is present:
+ *   GEMINI/GOOGLE → gemini-2.5-flash (free tier-friendly)
+ *   ANTHROPIC     → claude-haiku-4-5
+ *   XAI           → grok-4-fast-non-reasoning
+ *   none          → '' (DuckDuckGo fallback for search, direct fetch for fetch)
+ *
+ * Verified Gemini models with googleSearch + urlContext (2026-05-27):
+ *   gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.5-pro,
+ *   gemini-3-flash-preview (= gemini-3.5-flash preview), gemini-3.5-flash, gemini-3.1-pro-preview
+ */
+export declare function getWebToolsModel(): string;
+/**
+ * Run a web search with provider-native backends, falling back to DuckDuckGo
+ * when no provider is configured or its API key is missing.
+ */
+export declare function runWebSearch(query: string): Promise<BackendResult>;
+/**
+ * Run a web fetch with provider-native backends, falling back to direct
+ * HTTP + html-to-text. The `prompt` parameter contains the URL(s) and
+ * processing instructions (matching the WebFetch tool schema).
+ */
+export declare function runWebFetch(prompt: string, urls: string[]): Promise<BackendResult>;
+//# sourceMappingURL=webBackends.d.ts.map

package/dist/implementations/web/webBackends.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webBackends.d.ts","sourceRoot":"","sources":["../../../src/implementations/web/webBackends.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEjF,MAAM,WAAW,aAAa;IAC5B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sDAAsD;AACtD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAexE;AAiED,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAW5F;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAW5F;AAiED,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAWtF;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAWtF;AAyDD,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAWzF;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAWzF;AAsBD,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAwC5E;AAeD,4DAA4D;AAC5D,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA4BrE;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAQzC;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAyBxE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CA4CxF"}