testdriverai 7.2.3 → 7.2.10

package/sdk.js

@@ -263,6 +263,48 @@ class ElementNotFoundError extends Error {
   }
 }
 
+/**
+ * Custom error class for act() failures
+ * Includes task execution details and retry information
+ */
+class ActError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {Object} details - Additional details about the failure
+   * @param {string} details.task - The task that was attempted
+   * @param {number} details.tries - Number of check attempts made
+   * @param {number} details.maxTries - Maximum tries that were allowed
+   * @param {number} details.duration - Total execution time in milliseconds
+   * @param {Error} [details.cause] - The underlying error that caused the failure
+   */
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "ActError";
+    this.task = details.task;
+    this.tries = details.tries;
+    this.maxTries = details.maxTries;
+    this.duration = details.duration;
+    this.cause = details.cause;
+    this.timestamp = new Date().toISOString();
+
+    // Capture stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ActError);
+    }
+
+    // Enhance error message with execution details
+    this.message += `\n\n=== Act Execution Details ===`;
+    this.message += `\nTask: "${this.task}"`;
+    this.message += `\nTries: ${this.tries}/${this.maxTries}`;
+    this.message += `\nDuration: ${this.duration}ms`;
+    this.message += `\nTimestamp: ${this.timestamp}`;
+    
+    if (this.cause) {
+      this.message += `\nUnderlying error: ${this.cause.message}`;
+    }
+  }
+}
+
 /**
  * Element class representing a located or to-be-located element
  */
@@ -330,10 +372,17 @@ class Element {
   /**
    * Find the element on screen
    * @param {string} [newDescription] - Optional new description to search for
-   * @param {Object} [options] - Optional options object with cacheThreshold and/or cacheKey
+   * @param {Object} [options] - Optional options object with cacheThreshold, cacheKey, and/or timeout
+   * @param {number} [options.timeout] - Max time in ms to poll for element (polls every 5 seconds)
    * @returns {Promise<Element>} This element instance
    */
   async find(newDescription, options) {
+    // Handle timeout/polling option
+    const timeout = typeof options === 'object' ? options?.timeout : null;
+    if (timeout && timeout > 0) {
+      return this._findWithTimeout(newDescription, options, timeout);
+    }
+
     const description = newDescription || this.description;
     if (newDescription) {
       this.description = newDescription;
@@ -484,6 +533,61 @@ class Element {
     return this;
   }
 
+  /**
+   * Find element with polling/timeout support
+   * @private
+   * @param {string} [newDescription] - Optional new description to search for
+   * @param {Object} options - Options object
+   * @param {number} timeout - Max time in ms to poll for element
+   * @returns {Promise<Element>} This element instance
+   */
+  async _findWithTimeout(newDescription, options, timeout) {
+    const POLL_INTERVAL = 5000; // 5 seconds between attempts
+    const startTime = Date.now();
+    const description = newDescription || this.description;
+    
+    // Log that we're starting a polling find
+    const { events } = require("./agent/events.js");
+    this.sdk.emitter.emit(events.log.log, `🔄 Polling for "${description}" (timeout: ${timeout}ms)`);
+    
+    // Create options without timeout to avoid infinite recursion
+    const findOptions = typeof options === 'object' ? { ...options } : {};
+    delete findOptions.timeout;
+    
+    let attempts = 0;
+    while (Date.now() - startTime < timeout) {
+      attempts++;
+      
+      // Call the regular find (without timeout option)
+      await this.find(newDescription, findOptions);
+      
+      if (this._found) {
+        this.sdk.emitter.emit(events.log.log, `✅ Found "${description}" after ${attempts} attempt(s)`);
+        return this;
+      }
+      
+      const elapsed = Date.now() - startTime;
+      const remaining = timeout - elapsed;
+      
+      if (remaining > POLL_INTERVAL) {
+        this.sdk.emitter.emit(events.log.log, `⏳ Element not found, retrying in 5s... (${Math.round(remaining / 1000)}s remaining)`);
+        await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL));
+      } else if (remaining > 0) {
+        // Less than 5s remaining, wait the remaining time and try once more
+        await new Promise(resolve => setTimeout(resolve, remaining));
+      }
+    }
+    
+    // Final attempt after timeout
+    await this.find(newDescription, findOptions);
+    
+    if (!this._found) {
+      this.sdk.emitter.emit(events.log.log, `❌ Element "${description}" not found after ${timeout}ms (${attempts} attempts)`);
+    }
+    
+    return this;
+  }
+
   /**
    * Sanitize response by removing large base64 data to prevent memory leaks
    * @private
@@ -1141,6 +1245,9 @@ class TestDriverSDK {
     this.sandboxAmi = options.sandboxAmi || null;
     this.sandboxInstance = options.sandboxInstance || null;
 
+    // Store reconnect preference from options
+    this.reconnect = options.reconnect !== undefined ? options.reconnect : false;
+
     // Cache threshold configuration
     // threshold = pixel difference allowed (0.05 = 5% difference, 95% similarity)
     // By default, cache is DISABLED (threshold = -1) to avoid unnecessary AI costs
@@ -1418,22 +1525,19 @@ class TestDriverSDK {
        * @param {Object} options - Chrome extension launch options
        * @param {string} [options.extensionPath] - Local filesystem path to the unpacked extension directory
        * @param {string} [options.extensionId] - Chrome Web Store extension ID (e.g., "cjpalhdlnbpafiamejdnhcphjbkeiagm" for uBlock Origin)
-       * @param {string} [options.url='http://testdriver-sandbox.vercel.app/'] - URL to navigate to
        * @param {boolean} [options.maximized=true] - Start maximized
        * @returns {Promise<void>}
        * @example
        * // Load extension from local path
        * await testdriver.exec('sh', 'git clone https://github.com/user/extension.git /tmp/extension');
        * await testdriver.provision.chromeExtension({
-       *   extensionPath: '/tmp/extension',
-       *   url: 'https://example.com'
+       *   extensionPath: '/tmp/extension'
        * });
        * 
        * @example
        * // Load extension by Chrome Web Store ID
        * await testdriver.provision.chromeExtension({
-       *   extensionId: 'cjpalhdlnbpafiamejdnhcphjbkeiagm', // uBlock Origin
-       *   url: 'https://example.com'
+       *   extensionId: 'cjpalhdlnbpafiamejdnhcphjbkeiagm' // uBlock Origin
        * });
        */
       chromeExtension: async (options = {}) => {
@@ -1443,7 +1547,6 @@ class TestDriverSDK {
         const {
           extensionPath: providedExtensionPath,
           extensionId,
-          url = 'http://testdriver-sandbox.vercel.app/',
           maximized = true,
         } = options;
 
@@ -1561,7 +1664,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           console.log(`[provision.chromeExtension] Extension ${extensionId} extracted to ${extensionPath}`);
         }
 
-        // If dashcam is available and recording, add web logs for this domain
+        // If dashcam is available, set up file logging
         if (this._dashcam) {
           // Create the log file on the remote machine
           const logPath = this.os === "windows" 
@@ -1573,11 +1676,6 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
             : `touch ${logPath}`;
           
           await this.exec(shell, createLogCmd, 10000, true);
-        
-          const urlObj = new URL(url);
-          const domain = urlObj.hostname;
-          const pattern = `*${domain}*`;
-          await this._dashcam.addWebLog(pattern, 'Web Logs');
           await this._dashcam.addFileLog(logPath, "TestDriver Log");
         }
         
@@ -1653,19 +1751,19 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           chromeArgs.push(`--load-extension=${extensionPath}`);
         }
 
-        // Launch Chrome
+        // Launch Chrome (opens to New Tab by default)
         if (this.os === 'windows') {
           const argsString = chromeArgs.map(arg => `"${arg}"`).join(', ');
           await this.exec(
             shell,
-            `Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList ${argsString}, "${url}"`,
+            `Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList ${argsString}`,
             30000
           );
         } else {
           const argsString = chromeArgs.join(' ');
           await this.exec(
             shell,
-            `chrome-for-testing ${argsString} "${url}" >/dev/null 2>&1 &`,
+            `chrome-for-testing ${argsString} >/dev/null 2>&1 &`,
             30000
           );
         }
@@ -1673,25 +1771,18 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         // Wait for Chrome to be ready
         await this.focusApplication('Google Chrome');
 
-        // Wait for URL to load
-        try {
-          const urlObj = new URL(url);
-          const domain = urlObj.hostname;
-                    
-          for (let attempt = 0; attempt < 30; attempt++) {
-            const result = await this.find(`${domain}`);
+        // Wait for New Tab to appear
+        for (let attempt = 0; attempt < 30; attempt++) {
+          const result = await this.find('New Tab');
 
-            if (result.found()) {
-              break;
-            } else {
-              await new Promise(resolve => setTimeout(resolve, 1000));
-            }
+          if (result.found()) {
+            break;
+          } else {
+            await new Promise(resolve => setTimeout(resolve, 1000));
           }
-          
-          await this.focusApplication('Google Chrome');
-        } catch (e) {
-          console.warn(`[provision.chromeExtension] ⚠️  Could not parse URL "${url}":`, e.message);
         }
+        
+        await this.focusApplication('Google Chrome');
       },
 
       /**
@@ -1858,33 +1949,82 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           );
         }
 
-        console.log(`[provision.installer] ✅ Downloaded to ${filePath}`);
+        // Check if the downloaded file has a proper extension, if not scan the download directory
+        let actualFilePath = filePath;
+        const hasValidExtension = /\.(msi|exe|deb|rpm|appimage|sh|dmg|pkg)$/i.test(detectedFilename);
+        
+        if (!hasValidExtension && this.os === 'windows') {
+          // On Windows, scan the download directory for .msi or .exe files
+          console.log(`[provision.installer] Downloaded file has no extension, scanning for .msi or .exe files...`);
+          const scanResult = await this.exec(
+            shell,
+            `Get-ChildItem -Path "${downloadDir}" -File | Where-Object { $_.Extension -match '\\.(msi|exe)$' } | Sort-Object LastWriteTime -Descending | Select-Object -First 1 -ExpandProperty FullName`,
+            30000,
+            true
+          );
+          
+          if (scanResult && scanResult.trim()) {
+            actualFilePath = scanResult.trim();
+            console.log(`[provision.installer] Found installer: ${actualFilePath}`);
+          }
+        } else if (!hasValidExtension && this.os === 'linux') {
+          // On Linux, scan for common installer extensions
+          console.log(`[provision.installer] Downloaded file has no extension, scanning for installer files...`);
+          const scanResult = await this.exec(
+            shell,
+            `find "${downloadDir}" -maxdepth 1 -type f \\( -name "*.deb" -o -name "*.rpm" -o -name "*.AppImage" -o -name "*.sh" \\) -printf '%T@ %p\\n' | sort -rn | head -1 | cut -d' ' -f2-`,
+            30000,
+            true
+          );
+          
+          if (scanResult && scanResult.trim()) {
+            actualFilePath = scanResult.trim();
+            console.log(`[provision.installer] Found installer: ${actualFilePath}`);
+          }
+        } else if (!hasValidExtension && this.os === 'darwin') {
+          // On macOS, scan for common installer extensions
+          console.log(`[provision.installer] Downloaded file has no extension, scanning for installer files...`);
+          const scanResult = await this.exec(
+            shell,
+            `find "${downloadDir}" -maxdepth 1 -type f \\( -name "*.dmg" -o -name "*.pkg" \\) -print0 | xargs -0 ls -t | head -1`,
+            30000,
+            true
+          );
+          
+          if (scanResult && scanResult.trim()) {
+            actualFilePath = scanResult.trim();
+            console.log(`[provision.installer] Found installer: ${actualFilePath}`);
+          }
+        }
+
+        console.log(`[provision.installer] ✅ Downloaded to ${actualFilePath}`);
 
-        // Auto-detect install command based on file extension
-        const ext = detectedFilename.split('.').pop()?.toLowerCase();
+        // Auto-detect install command based on file extension (use actualFilePath for extension detection)
+        const actualFilename = actualFilePath.split(/[/\\]/).pop() || '';
+        const ext = actualFilename.split('.').pop()?.toLowerCase();
         let installCommand = null;
         
         if (this.os === 'windows') {
           if (ext === 'msi') {
-            installCommand = `Start-Process msiexec -ArgumentList '/i', '"${filePath}"', '/quiet', '/norestart' -Wait`;
+            installCommand = `Start-Process msiexec -ArgumentList '/i', '"${actualFilePath}"', '/quiet', '/norestart' -Wait`;
           } else if (ext === 'exe') {
-            installCommand = `Start-Process "${filePath}" -ArgumentList '/S' -Wait`;
+            installCommand = `Start-Process "${actualFilePath}" -ArgumentList '/S' -Wait`;
           }
         } else if (this.os === 'linux') {
           if (ext === 'deb') {
-            installCommand = `sudo dpkg -i "${filePath}" && sudo apt-get install -f -y`;
+            installCommand = `sudo dpkg -i "${actualFilePath}" && sudo apt-get install -f -y`;
           } else if (ext === 'rpm') {
-            installCommand = `sudo rpm -i "${filePath}"`;
+            installCommand = `sudo rpm -i "${actualFilePath}"`;
           } else if (ext === 'appimage') {
-            installCommand = `chmod +x "${filePath}"`;
+            installCommand = `chmod +x "${actualFilePath}"`;
           } else if (ext === 'sh') {
-            installCommand = `chmod +x "${filePath}" && "${filePath}"`;
+            installCommand = `chmod +x "${actualFilePath}" && "${actualFilePath}"`;
           }
         } else if (this.os === 'darwin') {
           if (ext === 'dmg') {
-            installCommand = `hdiutil attach "${filePath}" -mountpoint /Volumes/installer && cp -R /Volumes/installer/*.app /Applications/ && hdiutil detach /Volumes/installer`;
+            installCommand = `hdiutil attach "${actualFilePath}" -mountpoint /Volumes/installer && cp -R /Volumes/installer/*.app /Applications/ && hdiutil detach /Volumes/installer`;
           } else if (ext === 'pkg') {
-            installCommand = `sudo installer -pkg "${filePath}" -target /`;
+            installCommand = `sudo installer -pkg "${actualFilePath}" -target /`;
           }
         }
 
@@ -1900,7 +2040,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           await this.focusApplication(appName);
         }
 
-        return filePath;
+        return actualFilePath;
       },
 
       /**
@@ -1997,6 +2137,29 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           : this.newSandbox,
     };
 
+    // Handle reconnect option - use last sandbox file
+    // Check both connectOptions and constructor options
+    const shouldReconnect = connectOptions.reconnect !== undefined 
+      ? connectOptions.reconnect 
+      : this.reconnect;
+    
+    if (shouldReconnect) {
+      const lastSandbox = this.agent.getLastSandboxId();
+      if (!lastSandbox || !lastSandbox.sandboxId) {
+        throw new Error(
+          "Cannot reconnect: No previous sandbox found. Run a test first to create a sandbox, or remove the reconnect option."
+        );
+      }
+      this.agent.sandboxId = lastSandbox.sandboxId;
+      buildEnvOptions.new = false;
+      
+      // Use OS from last sandbox if not explicitly specified
+      if (!connectOptions.os && lastSandbox.os) {
+        this.agent.sandboxOs = lastSandbox.os;
+        this.os = lastSandbox.os;
+      }
+    }
+
     // Set agent properties for buildEnv to use
     if (connectOptions.sandboxId) {
       this.agent.sandboxId = connectOptions.sandboxId;
@@ -2026,6 +2189,10 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     } else {
       this.agent.sandboxOs = this.os;
     }
+    // Use keepAlive from connectOptions if provided
+    if (connectOptions.keepAlive !== undefined) {
+      this.agent.keepAlive = connectOptions.keepAlive;
+    }
 
     // Set redrawThreshold on agent's cliArgs.options
     this.agent.cliArgs.options.redrawThreshold = this.redrawThreshold;
@@ -2108,6 +2275,14 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     return this.session?.get() || null;
   }
 
+  /**
+   * Get the last sandbox info from the stored file
+   * @returns {Object|null} Last sandbox info including sandboxId, os, ami, instanceType, timestamp, or null if not found
+   */
+  getLastSandboxId() {
+    return this.agent.getLastSandboxId();
+  }
+
   // ====================================
   // Element Finding API
   // ====================================
@@ -2188,10 +2363,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     const absoluteTimestamp = Date.now();
     const startTime = absoluteTimestamp;
 
-    // Log finding all action
     const { events } = require("./agent/events.js");
-    const findingMessage = formatter.formatElementsFinding(description);
-    this.emitter.emit(events.log.log, findingMessage);
 
     try {
       const screenshot = await this.system.captureScreenBase64();
@@ -2257,16 +2429,16 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
       const duration = Date.now() - startTime;
 
       if (response && response.elements && response.elements.length > 0) {
-        // Log found elements
-        const foundMessage = formatter.formatElementsFound(
+        // Single log at the end - found elements
+        const formattedMessage = formatter.formatFindAllSingleLine(
           description,
           response.elements.length,
           {
-            duration: `${duration}ms`,
+            duration: duration,
             cacheHit: response.cached || false,
           },
         );
-        this.emitter.emit(events.log.log, foundMessage);
+        this.emitter.emit(events.log.narration, formattedMessage, true);
 
         // Create Element instances for each found element
         const elements = response.elements.map((elementData) => {
@@ -2316,7 +2488,6 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
         // Log debug information when elements are found
         if (process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG) {
-          const { events } = require("./agent/events.js");
           this.emitter.emit(
             events.log.debug,
             `✓ Found ${elements.length} element(s): "${description}"`,
@@ -2330,6 +2501,19 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
 
         return elements;
       } else {
+        const duration = Date.now() - startTime;
+        
+        // Single log at the end - no elements found
+        const formattedMessage = formatter.formatFindAllSingleLine(
+          description,
+          0,
+          {
+            duration: duration,
+            cacheHit: response?.cached || false,
+          },
+        );
+        this.emitter.emit(events.log.narration, formattedMessage, true);
+
         // No elements found - track interaction (fire-and-forget, don't block)
         const sessionId = this.getSessionId();
         if (sessionId && this.sandbox?.send) {
@@ -2354,6 +2538,18 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         return [];
       }
     } catch (error) {
+      const duration = Date.now() - startTime;
+      
+      // Single log at the end - error
+      const formattedMessage = formatter.formatFindAllSingleLine(
+        description,
+        0,
+        {
+          duration: duration,
+        },
+      );
+      this.emitter.emit(events.log.narration, formattedMessage, true);
+
       // Track findAll error interaction (fire-and-forget, don't block)
       const sessionId = this.getSessionId();
       if (sessionId && this.sandbox?.send) {
@@ -2371,8 +2567,6 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
         });
       }
 
-      const { events } = require("./agent/events.js");
-      this.emitter.emit(events.log.log, `Error in findAll: ${error.message}`);
       return [];
     }
   }
@@ -2771,6 +2965,11 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     // handles forwarding to sandbox. This prevents duplicate output to server.
     this.emitter.on("log:**", (message) => {
       const event = this.emitter.event;
+
+      if (event.includes("markdown")) {
+        return;
+      }
+
       if (event === events.log.debug && !debugMode) return;
       if (this.loggingEnabled && message) {
         const prefixedMessage = this.testContext
@@ -2920,39 +3119,11 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
     const platform = options.platform || this.config.TD_PLATFORM || "linux";
 
     // Auto-detect sandbox ID from the active sandbox if not provided
-    const sandboxId = options.sandboxId || this.agent?.sandbox?.id || null;
+    // For E2B (Linux), the instance has sandboxId; for AWS (Windows), it has instanceId
+    const sandboxId = options.sandboxId || this.instance?.sandboxId || this.instance?.instanceId || this.agent?.sandboxId || null;
 
     // Get or create session ID using the agent's newSession method
     let sessionId = this.agent?.sessionInstance?.get() || null;
-    
-    // If no session exists, create one using the agent's method
-    if (!sessionId && this.agent?.newSession) {
-      try {
-        await this.agent.newSession();
-        sessionId = this.agent.sessionInstance.get();
-        
-        // Save session ID to file for reuse across test runs
-        if (sessionId) {
-          const sessionFile = path.join(os.homedir(), '.testdriverai-session');
-          fs.writeFileSync(sessionFile, sessionId, { encoding: 'utf-8' });
-        }
-      } catch (error) {
-        // Log but don't fail - tests can run without a session
-        console.warn('Failed to create session:', error.message);
-      }
-    }
-    
-    // If still no session, try reading from file (for reporter/separate processes)
-    if (!sessionId) {
-      try {
-        const sessionFile = path.join(os.homedir(), '.testdriverai-session');
-        if (fs.existsSync(sessionFile)) {
-          sessionId = fs.readFileSync(sessionFile, 'utf-8').trim();
-        }
-      } catch (error) {
-        // Ignore file read errors
-      }
-    }
 
     const data = {
       runId: options.runId,
@@ -3076,26 +3247,98 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
    * This is the SDK equivalent of the CLI's exploratory loop
    *
    * @param {string} task - Natural language description of what to do
-   * @param {Object} options - Execution options
-   * @param {boolean} [options.validateAndLoop=false] - Whether to validate completion and retry if incomplete
-   * @returns {Promise<string|void>} Final AI response if validateAndLoop is true
+   * @param {Object} [options] - Execution options
+   * @param {number} [options.tries=7] - Maximum number of check/retry attempts before giving up
+   * @returns {Promise<ActResult>} Result object with success status and details
+   * @throws {ActError} When the task fails after all tries are exhausted
+   *
+   * @typedef {Object} ActResult
+   * @property {boolean} success - Whether the task completed successfully
+   * @property {string} task - The original task that was executed
+   * @property {number} tries - Number of check attempts made
+   * @property {number} maxTries - Maximum tries that were allowed
+   * @property {number} duration - Total execution time in milliseconds
+   * @property {string} [response] - AI's final response if available
    *
    * @example
    * // Simple execution
-   * await client.act('Click the submit button');
+   * const result = await client.act('Click the submit button');
+   * console.log(result.success); // true
    *
    * @example
-   * // With validation loop
-   * const result = await client.act('Fill out the contact form', { validateAndLoop: true });
-   * console.log(result); // AI's final assessment
+   * // With custom retry limit
+   * const result = await client.act('Fill out the contact form', { tries: 10 });
+   * console.log(`Completed in ${result.tries} tries`);
+   *
+   * @example
+   * // Handle failures
+   * try {
+   *   await client.act('Complete the checkout process', { tries: 3 });
+   * } catch (error) {
+   *   console.log(`Failed after ${error.tries} tries: ${error.message}`);
+   * }
    */
-  async act(task) {
+  async act(task, options = {}) {
     this._ensureConnected();
 
-    this.analytics.track("sdk.act", { task });
+    const { tries = 7 } = options;
+
+    this.analytics.track("sdk.act", { task, tries });
 
-    // Use the agent's exploratoryLoop method directly
-    return await this.agent.exploratoryLoop(task, false, true, false);
+    const { events } = require("./agent/events.js");
+    const startTime = Date.now();
+
+    // Store original checkLimit and set custom one if provided
+    const originalCheckLimit = this.agent.checkLimit;
+    this.agent.checkLimit = tries;
+    
+    // Reset check count for this act() call
+    const originalCheckCount = this.agent.checkCount;
+    this.agent.checkCount = 0;
+
+    // Emit scoped start marker for act()
+    this.emitter.emit(events.log.log, formatter.formatActStart(task));
+
+    try {
+      // Use the agent's exploratoryLoop method directly
+      const response = await this.agent.exploratoryLoop(task, false, true, false);
+      
+      const duration = Date.now() - startTime;
+      const triesUsed = this.agent.checkCount;
+      
+      this.emitter.emit(events.log.log, formatter.formatActComplete(duration, true));
+      
+      // Restore original checkLimit
+      this.agent.checkLimit = originalCheckLimit;
+      this.agent.checkCount = originalCheckCount;
+      
+      return {
+        success: true,
+        task,
+        tries: triesUsed,
+        maxTries: tries,
+        duration,
+        response: response || undefined,
+      };
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      const triesUsed = this.agent.checkCount;
+      
+      this.emitter.emit(events.log.log, formatter.formatActComplete(duration, false, error.message));
+      
+      // Restore original checkLimit
+      this.agent.checkLimit = originalCheckLimit;
+      this.agent.checkCount = originalCheckCount;
+      
+      // Create an enhanced error with additional context using ActError class
+      throw new ActError(`Act failed: ${error.message}`, {
+        task,
+        tries: triesUsed,
+        maxTries: tries,
+        duration,
+        cause: error,
+      });
+    }
   }
 
   /**
@@ -3103,15 +3346,16 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
    * Execute a natural language task using AI
    *
    * @param {string} task - Natural language description of what to do
-   * @param {Object} options - Execution options
-   * @param {boolean} [options.validateAndLoop=false] - Whether to validate completion and retry if incomplete
-   * @returns {Promise<string|void>} Final AI response if validateAndLoop is true
+   * @param {Object} [options] - Execution options
+   * @param {number} [options.tries=7] - Maximum number of check/retry attempts
+   * @returns {Promise<ActResult>} Result object with success status and details
    */
-  async ai(task) {
-    return await this.act(task);
+  async ai(task, options) {
+    return await this.act(task, options);
   }
 }
 
 module.exports = TestDriverSDK;
 module.exports.Element = Element;
 module.exports.ElementNotFoundError = ElementNotFoundError;
+module.exports.ActError = ActError;