testdriverai 7.2.9 → 7.2.11

package/lib/vitest/hooks.mjs

@@ -154,9 +154,16 @@ export function TestDriver(context, options = {}) {
     throw new Error('TestDriver() requires Vitest context. Pass the context parameter from your test function: test("name", async (context) => { ... })');
   }
   
-  // Return existing instance if already created for this test
+  // Return existing instance if already created for this test AND it's still connected
+  // On retry, the previous instance will be disconnected, so we need to create a new one
   if (testDriverInstances.has(context.task)) {
-    return testDriverInstances.get(context.task);
+    const existingInstance = testDriverInstances.get(context.task);
+    if (existingInstance.connected) {
+      return existingInstance;
+    }
+    // Instance exists but is disconnected (likely a retry) - remove it and create fresh
+    testDriverInstances.delete(context.task);
+    lifecycleHandlers.delete(context.task);
   }
   
   // Get global plugin options if available
@@ -194,7 +201,6 @@ export function TestDriver(context, options = {}) {
   
   if (autoConnect) {
     testdriver.__connectionPromise = (async () => {
-        console.log('[testdriver] Connecting to sandbox...');
         if (debugConsoleSpy) {
           console.log('[DEBUG] Before auth - sandbox.instanceSocketConnected:', testdriver.sandbox?.instanceSocketConnected);
         }
@@ -231,74 +237,80 @@ export function TestDriver(context, options = {}) {
   }
   
   // Register cleanup handler with dashcam.stop()
-  if (!lifecycleHandlers.has(context.task)) {
-    const cleanup = async () => {
-      try {
-        // Stop dashcam if it was started - with timeout to prevent hanging
-        if (testdriver._dashcam && testdriver._dashcam.recording) {
-          try {
-            const dashcamUrl = await testdriver.dashcam.stop();
-            console.log('');
-            console.log('🎥' + chalk.yellow(` Dashcam URL`) + `: ${dashcamUrl}`);
-            console.log('');
-            
-            // Set test metadata directly on the Vitest task context
-            // This is the proper way to pass data from test to reporter
-            const platform = testdriver.os || 'linux';
-            const absolutePath = context.task.file?.filepath || context.task.file?.name || 'unknown';
-            const projectRoot = process.cwd();
-            const testFile = absolutePath !== 'unknown'
-              ? path.relative(projectRoot, absolutePath)
-              : absolutePath;
-            
-            // Set metadata on the task for the reporter to read
-            context.task.meta.dashcamUrl = dashcamUrl || null;
-            context.task.meta.platform = platform;
-            context.task.meta.testFile = testFile;
-            context.task.meta.testOrder = 0;
-            context.task.meta.sessionId = testdriver.getSessionId();
-            
-            // Also register in memory if plugin is available (for cross-process scenarios)
-            if (globalThis.__testdriverPlugin?.registerDashcamUrl) {
-              globalThis.__testdriverPlugin.registerDashcamUrl(context.task.id, dashcamUrl, platform);
-            }
-          } catch (error) {
-            // Log more detailed error information for debugging
-            console.error('❌ Failed to stop dashcam:', error.name || error.constructor?.name || 'Error');
-            if (error.message) console.error('   Message:', error.message);
-            // NotFoundError during cleanup is expected if sandbox already terminated
-            if (error.name === 'NotFoundError' || error.responseData?.error === 'NotFoundError') {
-              console.log('   ℹ️  Sandbox session already terminated - dashcam stop skipped');
-            }
-            // Mark as not recording to prevent retries
-            if (testdriver._dashcam) {
-              testdriver._dashcam.recording = false;
-            }
+  // We always register a new cleanup handler because on retry we need to clean up the new instance
+  const cleanup = async () => {
+    // Get the current instance from the WeakMap (not from closure)
+    // This ensures we clean up the correct instance on retries
+    const currentInstance = testDriverInstances.get(context.task);
+    if (!currentInstance) {
+      return; // Already cleaned up
+    }
+    
+    try {
+      // Stop dashcam if it was started - with timeout to prevent hanging
+      if (currentInstance._dashcam && currentInstance._dashcam.recording) {
+        try {
+          const dashcamUrl = await currentInstance.dashcam.stop();
+          console.log('');
+          console.log('🎥' + chalk.yellow(` Dashcam URL`) + `: ${dashcamUrl}`);
+          console.log('');
+          
+          // Set test metadata directly on the Vitest task context
+          // This is the proper way to pass data from test to reporter
+          const platform = currentInstance.os || 'linux';
+          const absolutePath = context.task.file?.filepath || context.task.file?.name || 'unknown';
+          const projectRoot = process.cwd();
+          const testFile = absolutePath !== 'unknown'
+            ? path.relative(projectRoot, absolutePath)
+            : absolutePath;
+          
+          // Set metadata on the task for the reporter to read
+          context.task.meta.dashcamUrl = dashcamUrl || null;
+          context.task.meta.platform = platform;
+          context.task.meta.testFile = testFile;
+          context.task.meta.testOrder = 0;
+          context.task.meta.sessionId = currentInstance.getSessionId();
+          
+          // Also register in memory if plugin is available (for cross-process scenarios)
+          if (globalThis.__testdriverPlugin?.registerDashcamUrl) {
+            globalThis.__testdriverPlugin.registerDashcamUrl(context.task.id, dashcamUrl, platform);
+          }
+        } catch (error) {
+          // Log more detailed error information for debugging
+          console.error('❌ Failed to stop dashcam:', error.name || error.constructor?.name || 'Error');
+          if (error.message) console.error('   Message:', error.message);
+          // NotFoundError during cleanup is expected if sandbox already terminated
+          if (error.name === 'NotFoundError' || error.responseData?.error === 'NotFoundError') {
+            console.log('   ℹ️  Sandbox session already terminated - dashcam stop skipped');
+          }
+          // Mark as not recording to prevent retries
+          if (currentInstance._dashcam) {
+            currentInstance._dashcam.recording = false;
           }
         }
-        
-        // Clean up console spies
-        cleanupConsoleSpy(testdriver);
-        
-        // Wait for connection to finish if it was initiated
-        if (testdriver.__connectionPromise) {
-          await testdriver.__connectionPromise.catch(() => {}); // Ignore connection errors during cleanup
-        }
-        
-        // Disconnect with timeout
-        await Promise.race([
-          testdriver.disconnect(),
-          new Promise((resolve) => setTimeout(resolve, 5000)) // 5s timeout for disconnect
-        ]);
-      } catch (error) {
-        console.error('Error disconnecting client:', error);
       }
-    };
-    lifecycleHandlers.set(context.task, cleanup);
-    
-    // Vitest will call this automatically after the test
-    context.onTestFinished?.(cleanup);
-  }
+      
+      // Clean up console spies
+      cleanupConsoleSpy(currentInstance);
+      
+      // Wait for connection to finish if it was initiated
+      if (currentInstance.__connectionPromise) {
+        await currentInstance.__connectionPromise.catch(() => {}); // Ignore connection errors during cleanup
+      }
+      
+      // Disconnect with timeout
+      await Promise.race([
+        currentInstance.disconnect(),
+        new Promise((resolve) => setTimeout(resolve, 5000)) // 5s timeout for disconnect
+      ]);
+    } catch (error) {
+      console.error('Error disconnecting client:', error);
+    }
+  };
+  lifecycleHandlers.set(context.task, cleanup);
+  
+  // Vitest will call this automatically after the test (each retry attempt)
+  context.onTestFinished?.(cleanup);
   
   return testdriver;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.2.9",
+  "version": "7.2.11",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "exports": {

package/sdk.d.ts

@@ -242,6 +242,8 @@ export interface TestDriverOptions {
   sandboxInstance?: string;
   /** Cache key for element finding operations. If provided, enables caching tied to this key */
   cacheKey?: string;
+  /** Reconnect to the last used sandbox (throws error if no last sandbox exists) */
+  reconnect?: boolean;
   /** Redraw configuration for screen change detection */
   redraw?: boolean | {
     /** Enable redraw detection (default: true) */
@@ -264,6 +266,8 @@ export interface ConnectOptions {
   sandboxId?: string;
   /** Force creation of a new sandbox */
   newSandbox?: boolean;
+  /** Reconnect to the last used sandbox (throws error if no last sandbox exists) */
+  reconnect?: boolean;
   /** Direct IP address to connect to a running sandbox instance */
   ip?: string;
   /** Custom AMI ID for sandbox instance (e.g., 'ami-1234') */
@@ -276,6 +280,8 @@ export interface ConnectOptions {
   headless?: boolean;
   /** Reuse recent connection if available (default: true) */
   reuseConnection?: boolean;
+  /** Keep sandbox alive for specified milliseconds after disconnect (default: 60000). Set to 0 to terminate immediately on disconnect. */
+  keepAlive?: number;
 }
 
 export interface SandboxInstance {
@@ -695,6 +701,18 @@ export default class TestDriverSDK {
    */
   disconnect(): Promise<void>;
 
+  /**
+   * Get the last sandbox info from the stored file
+   * @returns Last sandbox info or null if not found
+   */
+  getLastSandboxId(): {
+    sandboxId: string | null;
+    os: 'windows' | 'linux';
+    ami: string | null;
+    instanceType: string | null;
+    timestamp: string | null;
+  } | null;
+
   // Element Finding API
 
   /**
@@ -702,7 +720,7 @@ export default class TestDriverSDK {
    * Automatically locates the element and returns it
    *
    * @param description - Description of the element to find
-   * @param cacheThreshold - Cache threshold for this specific find (overrides global setting)
+   * @param options - Cache threshold (number) or options object
    * @returns Chainable promise that resolves to Element instance
    *
    * @example
@@ -719,17 +737,12 @@ export default class TestDriverSDK {
    * const element = await client.find('login button', 0.01);
    *
    * @example
-   * // Poll until element is found
-   * let element;
-   * while (!element?.found()) {
-   *   element = await client.find('login button');
-   *   if (!element.found()) {
-   *     await new Promise(resolve => setTimeout(resolve, 1000));
-   *   }
-   * }
+   * // Poll for element with timeout (retries every 5 seconds)
+   * const element = await client.find('loading complete indicator', { timeout: 30000 });
    * await element.click();
    */
   find(description: string, cacheThreshold?: number): ChainableElementPromise;
+  find(description: string, options?: { cacheThreshold?: number; cacheKey?: string; timeout?: number }): ChainableElementPromise;
 
   /**
    * Find all elements matching a description

package/sdk.js

@@ -372,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;
@@ -526,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
@@ -1183,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
@@ -1460,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 = {}) => {
@@ -1485,7 +1547,6 @@ class TestDriverSDK {
         const {
           extensionPath: providedExtensionPath,
           extensionId,
-          url = 'http://testdriver-sandbox.vercel.app/',
           maximized = true,
         } = options;
 
@@ -1603,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" 
@@ -1615,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");
         }
         
@@ -1695,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
           );
         }
@@ -1715,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');
       },
 
       /**
@@ -1900,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 /`;
           }
         }
 
@@ -1942,7 +2040,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           await this.focusApplication(appName);
         }
 
-        return filePath;
+        return actualFilePath;
       },
 
       /**
@@ -2039,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;
@@ -2068,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;
@@ -2150,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
   // ====================================

package/test/manual/reconnect-provision.test.mjs

@@ -0,0 +1,49 @@
+/**
+ * TestDriver SDK - Reconnect Test Part 1: Provision
+ * 
+ * This test provisions a new sandbox and navigates to the login page.
+ * The sandbox ID is saved to .testdriver/last-sandbox for the next test.
+ * 
+ * The sandbox has keepAlive: 120000 (2 minutes) after disconnect.
+ * Run reconnect-signin.test.mjs within 2 minutes of this test completing.
+ * 
+ * Usage:
+ *   1. npm test -- test/testdriver/reconnect-provision.test.mjs
+ *   2. (within 2 minutes) npm test -- test/testdriver/reconnect-signin.test.mjs
+ */
+
+import { afterAll, describe, expect, it } from "vitest";
+import { TestDriver } from "../../lib/vitest/hooks.mjs";
+
+describe("Reconnect Test - Part 1: Provision", () => {
+
+  afterAll(async () => {
+    // Explicitly DO NOT disconnect - we want the sandbox to stay alive
+    // for the reconnect test. The sandbox will auto-terminate after keepAlive TTL.
+    console.log("\n⚠️  NOT disconnecting - sandbox will stay alive for ~2 minutes (keepAlive: 120000)");
+    console.log("   Run reconnect-signin.test.mjs within 2 minutes to test reconnect\n");
+  });
+
+  it("should provision sandbox and navigate to login page", async (context) => {
+
+    const testdriver = TestDriver(context, { newSandbox: true, headless: false });
+    
+    // Provision Chrome and navigate to login page
+    await testdriver.provision.chrome({
+      url: 'http://testdriver-sandbox.vercel.app/login',
+    });
+
+
+    // Verify we're on the login page
+    const result = await testdriver.assert("I can see a Sign In button");
+    expect(result).toBeTruthy();
+
+    // Get the sandbox ID that was saved
+    const lastSandbox = testdriver.getLastSandboxId();
+    console.log("\n✅ Sandbox provisioned:", lastSandbox?.sandboxId);
+    console.log("   Sandbox info saved to .testdriver/last-sandbox");
+    
+    expect(lastSandbox).toBeTruthy();
+    expect(lastSandbox.sandboxId).toBeTruthy();
+  });
+});