@nexus-cortex/executors 4.26.0

package/dist/implementations/web/SandboxTransferTool.js

@@ -0,0 +1,261 @@
+/**
+ * SandboxTransfer Tool Executor
+ *
+ * Runs a command in a remote sandbox (via MCP run_command), captures its
+ * stdout, and writes the output to the local filesystem.  Closes the loop
+ * between sandbox-generated artifacts (PDFs, images, data) and local files.
+ *
+ * Uses late-bound mcpManagerGetter injected into ExecutorConfig by
+ * OrchestratorFactory after MCP initialisation.
+ */
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { BaseTool } from '../../base/index.js';
+import { SchemaValidator } from '../../utils/SchemaValidator.js';
+import { makeRelative, shortenPath, resolveFilePath, } from '../../utils/FileUtils.js';
+const MIME_FROM_EXT = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf',
+    '.zip': 'application/zip',
+    '.wasm': 'application/wasm',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.json': 'application/json',
+    '.csv': 'text/csv',
+    '.txt': 'text/plain',
+    '.html': 'text/html',
+};
+export class SandboxTransferTool extends BaseTool {
+    config;
+    constructor(config) {
+        super('SandboxTransfer', 'SandboxTransfer', 'Run a command in the sandbox and save its stdout to a local file.', {
+            type: 'object',
+            properties: {
+                command: {
+                    type: 'string',
+                    description: 'Shell command to execute in the sandbox. Stdout is captured and written to local_path.',
+                },
+                local_path: {
+                    type: 'string',
+                    description: 'Local file path to write the captured output to. Parent directories are created automatically.',
+                },
+                encoding: {
+                    type: 'string',
+                    enum: ['base64', 'utf8'],
+                    description: 'How to interpret stdout. "base64" (default) decodes to binary. "utf8" writes raw text.',
+                },
+                mime_type: {
+                    type: 'string',
+                    description: 'MIME type for the output file. Auto-detected from extension if omitted.',
+                },
+                timeout: {
+                    type: 'number',
+                    description: 'Command timeout in milliseconds (default: 60000). Use higher values for PDF generation.',
+                },
+                server: {
+                    type: 'string',
+                    description: 'MCP server name to use (default: "nexus-browser"). Must expose a run_command tool.',
+                },
+            },
+            required: ['command', 'local_path'],
+        });
+        this.config = config;
+    }
+    validateToolParams(params) {
+        const schemaError = SchemaValidator.validate(this.parameterSchema, params);
+        if (schemaError)
+            return schemaError;
+        if (!params.command.trim()) {
+            return 'command must not be empty';
+        }
+        const filePath = resolveFilePath(params.local_path, this.config.workingDirectory);
+        if (!path.isAbsolute(filePath)) {
+            return `local_path must resolve to an absolute path: ${filePath}`;
+        }
+        params.local_path = filePath;
+        if (params.encoding && !['base64', 'utf8'].includes(params.encoding)) {
+            return `encoding must be "base64" or "utf8", got "${params.encoding}"`;
+        }
+        return null;
+    }
+    getDescription(params) {
+        if (!params?.local_path)
+            return 'Transfer file from sandbox';
+        const shortened = shortenPath(makeRelative(params.local_path, this.config.workingDirectory));
+        return `SandboxTransfer → ${shortened}`;
+    }
+    async execute(params, signal, updateOutput) {
+        const startTime = Date.now();
+        const serverName = params.server || 'nexus-browser';
+        const encoding = params.encoding || 'base64';
+        const timeout = params.timeout || 60000;
+        const validationError = this.validateToolParams(params);
+        if (validationError) {
+            return this.createErrorResult(validationError);
+        }
+        // Late-bound MCP manager access
+        const mcpManagerGetter = this.config.mcpManagerGetter;
+        if (!mcpManagerGetter || typeof mcpManagerGetter !== 'function') {
+            return this.createErrorResult('MCP manager not available. SandboxTransfer requires an active MCP connection. ' +
+                'Ensure MCP is enabled and a sandbox server (e.g., nexus-browser) is configured.');
+        }
+        const mcpManager = mcpManagerGetter();
+        if (!mcpManager) {
+            return this.createErrorResult('MCP manager not initialised. SandboxTransfer requires MCP to be enabled.');
+        }
+        if (!mcpManager.isServerConnected(serverName)) {
+            return this.createErrorResult(`MCP server "${serverName}" is not connected. ` +
+                `Available servers can be checked with /mcp list. ` +
+                `If using a different server, pass server: "your-server-name".`);
+        }
+        if (signal.aborted) {
+            return this.createErrorResult('Cancelled before execution');
+        }
+        // Run command in sandbox
+        let sandboxResult;
+        try {
+            if (updateOutput) {
+                updateOutput(`Running in ${serverName} sandbox: ${params.command.slice(0, 80)}...`);
+            }
+            sandboxResult = await Promise.race([
+                mcpManager.callTool(serverName, 'run_command', {
+                    command: params.command,
+                    timeout,
+                }),
+                new Promise((_, reject) => {
+                    const onAbort = () => reject(new Error('Cancelled'));
+                    signal.addEventListener('abort', onAbort, { once: true });
+                }),
+            ]);
+        }
+        catch (error) {
+            if (signal.aborted || error.message === 'Cancelled') {
+                return this.createErrorResult('Cancelled during sandbox execution');
+            }
+            return this.createErrorResult(`Sandbox command failed: ${error.message}`);
+        }
+        // Extract stdout from MCP result
+        const stdout = this.extractStdout(sandboxResult);
+        if (stdout === null || stdout.length === 0) {
+            const stderr = this.extractField(sandboxResult, 'stderr');
+            const exitCode = this.extractField(sandboxResult, 'exitCode');
+            let msg = 'Sandbox command produced no stdout.';
+            if (stderr)
+                msg += ` stderr: ${stderr.slice(0, 200)}`;
+            if (exitCode !== null)
+                msg += ` (exit code ${exitCode})`;
+            return this.createErrorResult(msg);
+        }
+        // Write to local filesystem
+        try {
+            const dirPath = path.dirname(params.local_path);
+            if (!fs.existsSync(dirPath)) {
+                fs.mkdirSync(dirPath, { recursive: true });
+            }
+            let buffer;
+            if (encoding === 'base64') {
+                const raw = stdout.replace(/\s/g, '');
+                buffer = Buffer.from(raw, 'base64');
+            }
+            else {
+                buffer = Buffer.from(stdout, 'utf8');
+            }
+            await fs.promises.writeFile(params.local_path, buffer);
+            const fileSize = buffer.length;
+            const ext = path.extname(params.local_path).toLowerCase();
+            const mimeType = params.mime_type || MIME_FROM_EXT[ext] || 'application/octet-stream';
+            const sha256 = crypto
+                .createHash('sha256')
+                .update(buffer)
+                .digest('hex')
+                .slice(0, 16);
+            const relativePath = makeRelative(params.local_path, this.config.workingDirectory);
+            const sizeLabel = fileSize < 1024
+                ? `${fileSize} B`
+                : fileSize < 1024 * 1024
+                    ? `${(fileSize / 1024).toFixed(1)} KB`
+                    : `${(fileSize / (1024 * 1024)).toFixed(1)} MB`;
+            const displayContent = `Transferred ${relativePath} (${sizeLabel}, ${mimeType}, sha256:${sha256})`;
+            if (updateOutput) {
+                updateOutput(displayContent);
+            }
+            return this.createSuccessResult(displayContent, {
+                executionTime: Date.now() - startTime,
+                resourcesUsed: { files: [params.local_path] },
+                sandboxServer: serverName,
+                encoding,
+                fileStats: {
+                    path: relativePath,
+                    size: fileSize,
+                    mimeType,
+                    sha256,
+                    operation: 'create',
+                },
+            });
+        }
+        catch (error) {
+            if (error.code === 'EACCES') {
+                return this.createErrorResult(`Permission denied: ${params.local_path}`);
+            }
+            if (error.code === 'ENOSPC') {
+                return this.createErrorResult('No space left on device');
+            }
+            return this.createErrorResult(`Failed to write local file: ${error.message}`);
+        }
+    }
+    extractStdout(result) {
+        if (!result)
+            return null;
+        // MCP content blocks format
+        if (Array.isArray(result.content)) {
+            for (const block of result.content) {
+                if (block?.type === 'text' && block.text) {
+                    try {
+                        const parsed = JSON.parse(block.text);
+                        if (typeof parsed.stdout === 'string')
+                            return parsed.stdout;
+                    }
+                    catch {
+                        // Not JSON — might be raw stdout
+                    }
+                    return block.text;
+                }
+            }
+        }
+        // Direct object with stdout
+        if (typeof result.stdout === 'string')
+            return result.stdout;
+        // Direct string
+        if (typeof result === 'string')
+            return result;
+        return null;
+    }
+    extractField(result, field) {
+        if (!result)
+            return null;
+        if (Array.isArray(result.content)) {
+            for (const block of result.content) {
+                if (block?.type === 'text' && block.text) {
+                    try {
+                        const parsed = JSON.parse(block.text);
+                        if (parsed[field] !== undefined)
+                            return String(parsed[field]);
+                    }
+                    catch { }
+                }
+            }
+        }
+        if (result[field] !== undefined)
+            return String(result[field]);
+        return null;
+    }
+}
+//# sourceMappingURL=SandboxTransferTool.js.map

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

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

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

@@ -0,0 +1,93 @@
+/**
+ * WebFetch Tool Executor
+ *
+ * Processes content from URLs embedded in a prompt using Gemini API's built-in urlContext tool.
+ * Includes fallback to local fetch + html-to-text for private IPs and failed requests.
+ *
+ * Based on Gemini CLI web-fetch.ts implementation
+ * Uses FREE Gemini API built-in tools with automatic fallback
+ */
+import { BaseTool, type ToolResult } from '../../base/index.js';
+import type { ExecutorConfig } from '../../base/ToolRegistry.js';
+/**
+ * Grounding metadata structures from Gemini API
+ */
+interface GroundingChunkItem {
+    web?: {
+        uri?: string;
+        title?: string;
+    };
+}
+/**
+ * Parameters for the WebFetch tool
+ */
+export interface WebFetchToolParams {
+    /**
+     * Comprehensive prompt with URL(s) and processing instructions
+     */
+    prompt: string;
+}
+/**
+ * Extended result with grounding metadata
+ */
+export interface WebFetchToolResult extends ToolResult {
+    sources?: GroundingChunkItem[];
+}
+/**
+ * WebFetch Tool Executor
+ *
+ * Features:
+ * - Uses Gemini API urlContext built-in tool (FREE)
+ * - Automatic grounding metadata with source attribution
+ * - UTF-8 byte-accurate citation insertion
+ * - Fallback to local fetch + html-to-text for:
+ *   - Private IPs (localhost, 192.168.x.x, etc.)
+ *   - Failed URL retrievals
+ * - GitHub blob URL → raw URL conversion
+ * - HTML to text conversion
+ */
+export declare class WebFetchTool extends BaseTool<WebFetchToolParams, WebFetchToolResult> {
+    private config;
+    private genAI;
+    constructor(config: ExecutorConfig);
+    /**
+     * Initialize Gemini API client
+     */
+    private getGeminiClient;
+    validateToolParams(params: WebFetchToolParams): string | null;
+    getDescription(params: WebFetchToolParams): string;
+    execute(params: WebFetchToolParams, signal: AbortSignal, updateOutput?: (output: string) => void): Promise<WebFetchToolResult>;
+    /**
+     * Format a provider-native backend result into the WebFetch tool result shape.
+     */
+    private formatBackendResult;
+    /**
+     * Primary execution using Gemini API urlContext
+     */
+    private executePrimary;
+    /**
+     * Fallback execution using local fetch + html-to-text
+     */
+    private executeFallback;
+    /**
+     * Parse URLs from prompt text
+     */
+    private parsePrompt;
+    /**
+     * Check if URL points to a private IP address
+     */
+    private isPrivateIp;
+    /**
+     * Insert citations at UTF-8 byte-accurate positions
+     *
+     * Gemini API returns byte positions (not character positions) for grounding metadata.
+     * This method handles multi-byte UTF-8 characters correctly.
+     *
+     * @param responseText The response text to insert citations into
+     * @param groundingSupports Array of grounding support items with byte positions
+     * @returns Text with citations inserted
+     */
+    private insertCitationsUTF8;
+}
+export {};
+//# sourceMappingURL=WebFetchTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebFetchTool.d.ts","sourceRoot":"","sources":["../../../src/implementations/web/WebFetchTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAmBjE;;GAEG;AACH,UAAU,kBAAkB;IAC1B,GAAG,CAAC,EAAE;QACJ,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AA0BD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAa,SAAQ,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;IAGpE,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,KAAK,CAA4B;gBAErB,MAAM,EAAE,cAAc;IAqB1C;;OAEG;IACH,OAAO,CAAC,eAAe;IAavB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI;IAqC7D,cAAc,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM;IAM5C,OAAO,CACX,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,WAAW,EACnB,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GACtC,OAAO,CAAC,kBAAkB,CAAC;IA4H9B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;OAEG;YACW,cAAc;IAmF5B;;OAEG;YACW,eAAe;IAiF7B;;OAEG;IACH,OAAO,CAAC,WAAW;IAiCnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAoCnB;;;;;;;;;OASG;IACH,OAAO,CAAC,mBAAmB;CAoD5B"}