@nexus-cortex/executors 4.26.0

package/dist/implementations/addon/KeyframeDetector.js

@@ -0,0 +1,390 @@
+/**
+ * Keyframe Detector
+ *
+ * Intelligently detects when screenshots should be sent to vision API
+ * Uses DOM analysis, perceptual hashing, and event monitoring
+ * to minimize unnecessary API calls while maintaining accuracy.
+ *
+ * Features:
+ * - Navigation change detection
+ * - DOM mutation monitoring
+ * - Modal/alert detection
+ * - Visual error detection
+ * - Perceptual hash-based change detection
+ * - Event-driven keyframe triggers
+ */
+import { EventEmitter } from 'events';
+import crypto from 'crypto';
+/**
+ * KeyframeDetector - Smart detection of when to send screenshots to vision API
+ *
+ * Monitors page state and triggers keyframe captures only when significant
+ * changes occur, dramatically reducing API costs while maintaining accuracy.
+ *
+ * @example
+ * const detector = new KeyframeDetector(page, {
+ *   domMutationThreshold: 50,
+ *   visualHashThreshold: 0.15
+ * });
+ *
+ * detector.on('keyframe', (trigger: KeyframeTrigger) => {
+ *   console.log(`Keyframe needed: ${trigger.reason}`);
+ *   // Send screenshot to vision API
+ * });
+ *
+ * await detector.start();
+ */
+export class KeyframeDetector extends EventEmitter {
+    page;
+    config;
+    isRunning = false;
+    lastSnapshot = null;
+    mutationCount = 0;
+    modalCheckInterval = null;
+    constructor(page, config = {}) {
+        super();
+        this.page = page;
+        this.config = {
+            domMutationThreshold: config.domMutationThreshold ?? 50,
+            visualHashThreshold: config.visualHashThreshold ?? 0.15,
+            modalCheckInterval: config.modalCheckInterval ?? 500,
+            detectNavigation: config.detectNavigation ?? true,
+            detectDOMMutations: config.detectDOMMutations ?? true,
+            detectModals: config.detectModals ?? true,
+            detectErrors: config.detectErrors ?? true
+        };
+    }
+    /**
+     * Start monitoring for keyframe triggers
+     */
+    async start() {
+        if (this.isRunning) {
+            console.warn('KeyframeDetector already running');
+            return;
+        }
+        this.isRunning = true;
+        // Take initial snapshot
+        this.lastSnapshot = await this.captureSnapshot();
+        // Set up detectors
+        if (this.config.detectNavigation) {
+            await this.setupNavigationDetector();
+        }
+        if (this.config.detectDOMMutations) {
+            await this.setupDOMMutationDetector();
+        }
+        if (this.config.detectModals) {
+            this.setupModalDetector();
+        }
+        if (this.config.detectErrors) {
+            await this.setupErrorDetector();
+        }
+        this.emit('start', { config: this.config });
+    }
+    /**
+     * Stop monitoring
+     */
+    stop() {
+        if (!this.isRunning) {
+            return;
+        }
+        this.isRunning = false;
+        if (this.modalCheckInterval) {
+            clearInterval(this.modalCheckInterval);
+            this.modalCheckInterval = null;
+        }
+        this.emit('stop');
+    }
+    /**
+     * Manually trigger keyframe (for user requests)
+     */
+    triggerKeyframe(reason, metadata) {
+        const trigger = {
+            type: 'user_request',
+            reason,
+            confidence: 1.0,
+            metadata,
+            timestamp: Date.now()
+        };
+        this.emit('keyframe', trigger);
+    }
+    /**
+     * Capture current page snapshot
+     */
+    async captureSnapshot() {
+        const url = this.page.url();
+        const title = await this.page.title();
+        // Compute DOM hash
+        const domContent = await this.page.evaluate(() => {
+            return document.body.innerHTML;
+        });
+        const domHash = this.computeHash(domContent);
+        // Get element count
+        const elementCount = await this.page.evaluate(() => {
+            return document.querySelectorAll('*').length;
+        });
+        // Check for modals
+        const hasModal = await this.detectModal();
+        // Check for errors
+        const hasError = await this.detectError();
+        // Compute visual hash (placeholder - would need actual perceptual hashing)
+        const visualHash = this.computeHash(url + title + elementCount);
+        return {
+            url,
+            title,
+            domHash,
+            visualHash,
+            elementCount,
+            hasModal,
+            hasError
+        };
+    }
+    /**
+     * Set up navigation change detector
+     */
+    async setupNavigationDetector() {
+        this.page.on('framenavigated', async (frame) => {
+            if (frame === this.page.mainFrame()) {
+                const newSnapshot = await this.captureSnapshot();
+                if (this.lastSnapshot && newSnapshot.url !== this.lastSnapshot.url) {
+                    const trigger = {
+                        type: 'navigation',
+                        reason: `Navigation from ${this.lastSnapshot.url} to ${newSnapshot.url}`,
+                        confidence: 1.0,
+                        metadata: {
+                            fromUrl: this.lastSnapshot.url,
+                            toUrl: newSnapshot.url
+                        },
+                        timestamp: Date.now()
+                    };
+                    this.emit('keyframe', trigger);
+                }
+                this.lastSnapshot = newSnapshot;
+            }
+        });
+    }
+    /**
+     * Set up DOM mutation detector
+     */
+    async setupDOMMutationDetector() {
+        await this.page.evaluate((threshold) => {
+            let mutationCount = 0;
+            const observer = new MutationObserver((mutations) => {
+                mutationCount += mutations.length;
+                if (mutationCount >= threshold) {
+                    // Emit custom event that we'll listen for
+                    window.dispatchEvent(new CustomEvent('significant-mutation', {
+                        detail: { count: mutationCount }
+                    }));
+                    mutationCount = 0;
+                }
+            });
+            observer.observe(document.body, {
+                childList: true,
+                subtree: true,
+                attributes: true,
+                characterData: true
+            });
+            // Store observer so we can disconnect later
+            window.__keyframeDetectorObserver = observer;
+        }, this.config.domMutationThreshold);
+        // Listen for custom event
+        await this.page.exposeFunction('__triggerDOMMutation', (count) => {
+            const trigger = {
+                type: 'dom_mutation',
+                reason: `Significant DOM changes detected (${count} mutations)`,
+                confidence: 0.8,
+                metadata: { mutationCount: count },
+                timestamp: Date.now()
+            };
+            this.emit('keyframe', trigger);
+        });
+        await this.page.evaluate(() => {
+            window.addEventListener('significant-mutation', (e) => {
+                window.__triggerDOMMutation(e.detail.count);
+            });
+        });
+    }
+    /**
+     * Set up modal detector (periodic check)
+     */
+    setupModalDetector() {
+        this.modalCheckInterval = setInterval(async () => {
+            if (!this.isRunning)
+                return;
+            try {
+                const hasModal = await this.detectModal();
+                if (hasModal && (!this.lastSnapshot || !this.lastSnapshot.hasModal)) {
+                    const trigger = {
+                        type: 'modal',
+                        reason: 'Modal or dialog detected on page',
+                        confidence: 0.9,
+                        timestamp: Date.now()
+                    };
+                    this.emit('keyframe', trigger);
+                    if (this.lastSnapshot) {
+                        this.lastSnapshot.hasModal = true;
+                    }
+                }
+            }
+            catch (error) {
+                // Ignore navigation errors - page context was destroyed during navigation
+                if (!error.message?.includes('Execution context was destroyed')) {
+                    // Re-throw other errors
+                    throw error;
+                }
+            }
+        }, this.config.modalCheckInterval);
+    }
+    /**
+     * Set up error detector
+     */
+    async setupErrorDetector() {
+        // Listen for console errors
+        this.page.on('console', (msg) => {
+            if (msg.type() === 'error') {
+                const trigger = {
+                    type: 'error',
+                    reason: `Console error: ${msg.text()}`,
+                    confidence: 0.7,
+                    metadata: { errorText: msg.text() },
+                    timestamp: Date.now()
+                };
+                this.emit('keyframe', trigger);
+            }
+        });
+        // Listen for page errors
+        this.page.on('pageerror', (error) => {
+            const trigger = {
+                type: 'error',
+                reason: `Page error: ${error.message}`,
+                confidence: 0.9,
+                metadata: { error: error.message },
+                timestamp: Date.now()
+            };
+            this.emit('keyframe', trigger);
+        });
+    }
+    /**
+     * Detect if modal/dialog is present
+     */
+    async detectModal() {
+        return await this.page.evaluate(() => {
+            // Common modal selectors
+            const modalSelectors = [
+                '[role="dialog"]',
+                '[role="alertdialog"]',
+                '.modal',
+                '.dialog',
+                '[aria-modal="true"]'
+            ];
+            for (const selector of modalSelectors) {
+                const element = document.querySelector(selector);
+                if (element && element.offsetParent !== null) {
+                    return true;
+                }
+            }
+            return false;
+        });
+    }
+    /**
+     * Detect if error is visible on page
+     */
+    async detectError() {
+        return await this.page.evaluate(() => {
+            const errorSelectors = [
+                '.error',
+                '.error-message',
+                '[role="alert"]',
+                '.alert-danger',
+                '.notification-error'
+            ];
+            for (const selector of errorSelectors) {
+                const element = document.querySelector(selector);
+                if (element && element.offsetParent !== null) {
+                    const text = element.textContent?.toLowerCase() || '';
+                    if (text.includes('error') || text.includes('failed') || text.includes('wrong')) {
+                        return true;
+                    }
+                }
+            }
+            return false;
+        });
+    }
+    /**
+     * Compute simple hash of content
+     */
+    computeHash(content) {
+        return crypto.createHash('md5').update(content).digest('hex');
+    }
+    /**
+     * Compute perceptual hash difference between two snapshots
+     * Returns 0-1, where 0 is identical and 1 is completely different
+     */
+    async computeVisualDifference() {
+        if (!this.lastSnapshot) {
+            return 1.0; // No baseline, assume different
+        }
+        const newSnapshot = await this.captureSnapshot();
+        // Simple comparison based on DOM hash and element count
+        if (newSnapshot.domHash === this.lastSnapshot.domHash) {
+            return 0.0; // Identical
+        }
+        // Calculate difference based on element count change
+        const elementDiff = Math.abs(newSnapshot.elementCount - this.lastSnapshot.elementCount) / Math.max(newSnapshot.elementCount, this.lastSnapshot.elementCount);
+        return Math.min(elementDiff, 1.0);
+    }
+    /**
+     * Check if visual change threshold is exceeded
+     */
+    async shouldSendToAPI() {
+        const visualDiff = await this.computeVisualDifference();
+        if (visualDiff >= this.config.visualHashThreshold) {
+            return {
+                should: true,
+                reason: `Visual difference ${(visualDiff * 100).toFixed(1)}% exceeds threshold`,
+                confidence: Math.min(visualDiff * 2, 1.0)
+            };
+        }
+        const newSnapshot = await this.captureSnapshot();
+        // Check for modals
+        if (newSnapshot.hasModal && (!this.lastSnapshot || !this.lastSnapshot.hasModal)) {
+            return {
+                should: true,
+                reason: 'Modal detected',
+                confidence: 0.9
+            };
+        }
+        // Check for errors
+        if (newSnapshot.hasError && (!this.lastSnapshot || !this.lastSnapshot.hasError)) {
+            return {
+                should: true,
+                reason: 'Error detected',
+                confidence: 0.9
+            };
+        }
+        return {
+            should: false,
+            reason: 'No significant changes detected',
+            confidence: 0.0
+        };
+    }
+    /**
+     * Get current detector state
+     */
+    getState() {
+        return {
+            isRunning: this.isRunning,
+            lastSnapshot: this.lastSnapshot,
+            config: this.config
+        };
+    }
+    /**
+     * Cleanup resources
+     */
+    destroy() {
+        this.stop();
+        this.removeAllListeners();
+        this.lastSnapshot = null;
+    }
+}
+//# sourceMappingURL=KeyframeDetector.js.map

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

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

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

@@ -0,0 +1,62 @@
+import { BaseTool } from '../../base/BaseTool.js';
+import type { ToolResult } from '../../base/ToolResult.js';
+/**
+ * Parameters for ModifySandbox tool
+ */
+export interface ModifySandboxParams {
+    sandboxId: string;
+    file: string;
+    content: string;
+    waitForReload?: boolean;
+    captureAfterReload?: boolean;
+    verifyChanges?: boolean;
+}
+/**
+ * ModifySandboxTool - Edit sandbox code with automatic hot reload and verification
+ *
+ * This tool provides a higher-level interface than raw Write tool:
+ * - Edits files within the sandbox directory
+ * - Waits for hot reload to complete
+ * - Captures visual snapshot after changes
+ * - Verifies changes took effect
+ *
+ * Advantages over Write tool:
+ * 1. Sandbox-aware - knows sandbox directory structure
+ * 2. Hot reload integration - waits for restart
+ * 3. Automatic verification - captures post-edit snapshot
+ * 4. Error detection - checks if reload succeeded
+ *
+ * Use Cases:
+ * 1. Iterative development - Edit → See → Edit again
+ * 2. Bug fixing - Modify code, verify fix visually
+ * 3. Feature addition - Add code, test immediately
+ * 4. Styling - Change CSS, see results instantly
+ *
+ * Example:
+ * ```
+ * await modifySandbox({
+ *   sandboxId: "abc-123",
+ *   file: "index.js",
+ *   content: "// fixed code",
+ *   waitForReload: true,
+ *   captureAfterReload: true
+ * });
+ * ```
+ */
+export declare class ModifySandboxExecutor extends BaseTool<ModifySandboxParams, ToolResult> {
+    private sandboxDir;
+    constructor(config: {
+        workingDirectory: string;
+    });
+    validateToolParams(params: ModifySandboxParams): string | null;
+    execute(params: ModifySandboxParams, signal: AbortSignal): Promise<ToolResult>;
+    /**
+     * Wait helper
+     */
+    private wait;
+    /**
+     * Format modification output for model consumption
+     */
+    private formatModificationOutput;
+}
+//# sourceMappingURL=ModifySandboxTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ModifySandboxTool.d.ts","sourceRoot":"","sources":["../../../src/implementations/addon/ModifySandboxTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAQ3D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ,CAAC,mBAAmB,EAAE,UAAU,CAAC;IAClF,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAA;KAAE;IA0ChD,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI;IAqBxD,OAAO,CAAC,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAiIpF;;OAEG;IACH,OAAO,CAAC,IAAI;IAIZ;;OAEG;IACH,OAAO,CAAC,wBAAwB;CAyEjC"}