@nexus-cortex/executors 4.26.0

package/dist/implementations/addon/StopSandboxTool.js

@@ -0,0 +1,252 @@
+import { BaseTool } from '../../base/BaseTool.js';
+import { CreateArtifactToolExecutor } from './CreateArtifactTool.js';
+import { visualBridge } from './VisualFeedbackBridge.js';
+import { promises as fs } from 'fs';
+import { join } from 'path';
+/**
+ * StopSandboxTool - Stop a running sandbox and optionally cleanup
+ *
+ * This tool stops the sandbox process and cleans up resources:
+ * - Kills the running Node.js/Python process
+ * - Closes file watchers (hot reload)
+ * - Optionally captures final snapshot
+ * - Optionally deletes sandbox directory
+ * - Closes Playwright browser if no other sandboxes need it
+ *
+ * Use Cases:
+ * 1. Finished development - Stop sandbox when done
+ * 2. Free resources - Stop unused sandboxes
+ * 3. Clean slate - Stop and cleanup for fresh start
+ * 4. Error recovery - Stop crashed sandbox
+ *
+ * Example:
+ * ```typescript
+ * // Model finishes work
+ * await stopSandbox({
+ *   sandboxId: "abc-123",
+ *   cleanup: true,  // Delete sandbox directory
+ *   captureFinalSnapshot: true  // Save final state
+ * });
+ * ```
+ */
+export class StopSandboxExecutor extends BaseTool {
+    sandboxDir;
+    constructor(config) {
+        const schema = {
+            type: 'object',
+            properties: {
+                sandboxId: {
+                    type: 'string',
+                    description: 'Unique ID of the sandbox to stop'
+                },
+                cleanup: {
+                    type: 'boolean',
+                    description: 'Delete sandbox directory after stopping (default: false)'
+                },
+                captureFinalSnapshot: {
+                    type: 'boolean',
+                    description: 'Capture final visual snapshot before stopping (default: false)'
+                }
+            },
+            required: ['sandboxId']
+        };
+        super('StopSandbox', 'StopSandbox', 'Stop a running sandbox and optionally cleanup resources', schema);
+        this.sandboxDir = join(config.workingDirectory, '.addon-tools');
+    }
+    validateToolParams(params) {
+        if (!params.sandboxId || params.sandboxId.trim().length === 0) {
+            return 'sandboxId is required';
+        }
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(params.sandboxId)) {
+            return 'sandboxId must be a valid UUID';
+        }
+        return null;
+    }
+    async execute(params, signal) {
+        const startTime = Date.now();
+        const validationError = this.validateToolParams(params);
+        if (validationError) {
+            return this.createErrorResult(validationError);
+        }
+        try {
+            // Get sandbox session
+            const session = CreateArtifactToolExecutor.getActiveSandbox(params.sandboxId);
+            if (!session) {
+                return this.createErrorResult(`Sandbox not found: ${params.sandboxId}. It may already be stopped.`);
+            }
+            // Capture final snapshot if requested
+            let finalSnapshot = null;
+            if (params.captureFinalSnapshot && session.url) {
+                try {
+                    await visualBridge.initialize();
+                    finalSnapshot = await visualBridge.captureSnapshot(session.url);
+                }
+                catch (error) {
+                    console.warn('Could not capture final snapshot:', error);
+                }
+            }
+            // Collect session info before stopping
+            const sessionInfo = {
+                id: session.id,
+                name: session.name,
+                url: session.url,
+                port: session.port,
+                mode: session.mode,
+                uptime: Date.now() - session.startTime.getTime(),
+                startTime: session.startTime,
+                lastActivity: session.lastActivity
+            };
+            // Stop the sandbox (kills process, closes watchers)
+            const stopped = CreateArtifactToolExecutor.stopSandbox(params.sandboxId);
+            if (!stopped) {
+                return this.createErrorResult('Failed to stop sandbox (unknown reason)');
+            }
+            // Cleanup sandbox directory if requested
+            let cleanedUp = false;
+            let bytesFreed = 0;
+            if (params.cleanup) {
+                const sandboxPath = join(this.sandboxDir, params.sandboxId);
+                try {
+                    // Calculate size before deletion
+                    const files = await this.getDirectorySize(sandboxPath);
+                    bytesFreed = files.totalSize;
+                    // Delete directory
+                    await fs.rm(sandboxPath, { recursive: true, force: true });
+                    cleanedUp = true;
+                }
+                catch (error) {
+                    console.warn(`Could not cleanup sandbox directory: ${error}`);
+                    // Don't fail the whole operation if cleanup fails
+                }
+            }
+            // Check if we should close Playwright browser
+            const activeSandboxes = CreateArtifactToolExecutor.listActiveSandboxes();
+            if (activeSandboxes.length === 0) {
+                // No more sandboxes, close browser to free memory
+                try {
+                    await visualBridge.close();
+                }
+                catch (error) {
+                    console.warn('Could not close browser:', error);
+                }
+            }
+            // Format output
+            const output = this.formatStopOutput(sessionInfo, finalSnapshot, cleanedUp, bytesFreed);
+            return {
+                ...this.createSuccessResult(output),
+                metadata: {
+                    executionTime: Date.now() - startTime,
+                    sandboxId: params.sandboxId,
+                    sandboxName: sessionInfo.name,
+                    uptime: sessionInfo.uptime,
+                    stopped: true,
+                    cleanedUp,
+                    bytesFreed,
+                    hasFinalSnapshot: !!finalSnapshot
+                }
+            };
+        }
+        catch (error) {
+            return this.createErrorResult(`Failed to stop sandbox: ${error.message}`);
+        }
+    }
+    /**
+     * Calculate directory size recursively
+     */
+    async getDirectorySize(dirPath) {
+        let totalSize = 0;
+        let fileCount = 0;
+        try {
+            const entries = await fs.readdir(dirPath, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = join(dirPath, entry.name);
+                if (entry.isDirectory()) {
+                    const subDir = await this.getDirectorySize(fullPath);
+                    totalSize += subDir.totalSize;
+                    fileCount += subDir.fileCount;
+                }
+                else {
+                    const stats = await fs.stat(fullPath);
+                    totalSize += stats.size;
+                    fileCount++;
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`Error calculating directory size: ${error}`);
+        }
+        return { totalSize, fileCount };
+    }
+    /**
+     * Format human-readable file size
+     */
+    formatBytes(bytes) {
+        if (bytes === 0)
+            return '0 Bytes';
+        const k = 1024;
+        const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+        const i = Math.floor(Math.log(bytes) / Math.log(k));
+        return Math.round((bytes / Math.pow(k, i)) * 100) / 100 + ' ' + sizes[i];
+    }
+    /**
+     * Format uptime in human-readable format
+     */
+    formatUptime(ms) {
+        const seconds = Math.floor(ms / 1000);
+        const minutes = Math.floor(seconds / 60);
+        const hours = Math.floor(minutes / 60);
+        if (hours > 0) {
+            return `${hours}h ${minutes % 60}m ${seconds % 60}s`;
+        }
+        else if (minutes > 0) {
+            return `${minutes}m ${seconds % 60}s`;
+        }
+        else {
+            return `${seconds}s`;
+        }
+    }
+    /**
+     * Format stop output for model consumption
+     */
+    formatStopOutput(sessionInfo, finalSnapshot, cleanedUp, bytesFreed) {
+        const lines = [];
+        lines.push(`#  Sandbox Stopped: ${sessionInfo.name}`);
+        lines.push('');
+        lines.push(`**Sandbox ID**: ${sessionInfo.id}`);
+        lines.push(`**Status**: Stopped`);
+        lines.push(`**Total Uptime**: ${this.formatUptime(sessionInfo.uptime)}`);
+        lines.push(`**Started**: ${sessionInfo.startTime.toISOString()}`);
+        lines.push(`**Last Activity**: ${sessionInfo.lastActivity.toISOString()}`);
+        lines.push('');
+        if (finalSnapshot) {
+            lines.push('---');
+            lines.push('');
+            lines.push('##  Final Snapshot');
+            lines.push('');
+            lines.push(visualBridge.formatForModel(finalSnapshot));
+            lines.push('');
+        }
+        if (cleanedUp) {
+            lines.push('---');
+            lines.push('');
+            lines.push('##  Cleanup');
+            lines.push('');
+            lines.push(`[OK] Sandbox directory deleted`);
+            lines.push(`[OK] Disk space freed: ${this.formatBytes(bytesFreed)}`);
+            lines.push('');
+        }
+        lines.push('---');
+        lines.push('');
+        lines.push('**Summary**:');
+        lines.push('- [OK] Process terminated');
+        lines.push('- [OK] File watchers closed');
+        lines.push('- [OK] Resources freed');
+        if (cleanedUp) {
+            lines.push('- [OK] Files cleaned up');
+        }
+        lines.push('');
+        lines.push('The sandbox is now fully stopped and removed from active sessions.');
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=StopSandboxTool.js.map

package/dist/implementations/addon/StopSandboxTool.js.map

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

package/dist/implementations/addon/TerminalSandbox.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Terminal Sandbox
+ *
+ * Provides visual terminal emulation using xterm.js
+ * Allows model to see and interact with shell sessions
+ *
+ * Features:
+ * - Visual terminal display (xterm.js in browser)
+ * - Full PTY support (bash, zsh, etc.)
+ * - Screenshot capture of terminal output
+ * - Direct typing/command execution
+ * - WebSocket communication
+ */
+export interface TerminalConfig {
+    shell?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    headed?: boolean;
+    rows?: number;
+    cols?: number;
+    executablePath?: string;
+}
+export interface TerminalSnapshot {
+    screenshot: string;
+    output: string;
+    cwd: string;
+    timestamp: number;
+}
+/**
+ * TerminalSandbox - Visual terminal emulation
+ *
+ * Combines:
+ * - PTY process (actual shell)
+ * - xterm.js (visual display in browser)
+ * - Playwright (browser automation for screenshots)
+ * - WebSocket (real-time communication)
+ */
+export declare class TerminalSandbox {
+    private shell;
+    private browser;
+    private page;
+    private server;
+    private wss;
+    private terminalUrl;
+    private output;
+    private config;
+    private wsPort;
+    constructor(config?: TerminalConfig);
+    /**
+     * Initialize terminal sandbox
+     * 1. Start shell process (PTY)
+     * 2. Start WebSocket server for communication
+     * 3. Launch browser with xterm.js client
+     */
+    initialize(): Promise<void>;
+    /**
+     * Start shell process (PTY emulation)
+     */
+    private startShell;
+    /**
+     * Start WebSocket server for terminal I/O
+     */
+    private startWebSocketServer;
+    /**
+     * Broadcast output to all connected WebSocket clients
+     */
+    private broadcastToClients;
+    /**
+     * Start browser to display terminal
+     */
+    private startBrowser;
+    /**
+     * Type command into terminal
+     * @param text Text to type
+     */
+    type(text: string): Promise<void>;
+    /**
+     * Execute command in terminal
+     * @param command Command to execute
+     */
+    executeCommand(command: string): Promise<void>;
+    /**
+     * Get screenshot of terminal
+     */
+    getScreenshot(): Promise<Buffer>;
+    /**
+     * Capture current terminal state
+     */
+    captureSnapshot(): Promise<TerminalSnapshot>;
+    /**
+     * Clear terminal output
+     */
+    clear(): Promise<void>;
+    /**
+     * Get current output
+     */
+    getOutput(): string;
+    /**
+     * Cleanup resources
+     */
+    close(): Promise<void>;
+    /**
+     * Get inline terminal HTML client (fallback if file doesn't exist)
+     */
+    private getInlineTerminalHTML;
+}
+/**
+ * Singleton instance for convenience
+ */
+export declare const terminalSandbox: TerminalSandbox;
+//# sourceMappingURL=TerminalSandbox.d.ts.map

package/dist/implementations/addon/TerminalSandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TerminalSandbox.d.ts","sourceRoot":"","sources":["../../../src/implementations/addon/TerminalSandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAiB;IAG/B,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,GAAE,cAAmB;IAWvC;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAWjC;;OAEG;YACW,UAAU;IA2BxB;;OAEG;YACW,oBAAoB;IAmDlC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;YACW,YAAY;IAsB1B;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvC;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAQtC;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAWlD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+B5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;CAmF9B;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,iBAAwB,CAAC"}