testdriverai 7.0.0 → 7.1.1

package/sdk.js

@@ -1,10 +1,69 @@
-#!/usr/bin/env node
-
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const crypto = require("crypto");
 const { formatter } = require("./sdk-log-formatter");
 
+/**
+ * Get the file path of the caller (the file that called TestDriver)
+ * @returns {string|null} File path or null if not found
+ */
+function getCallerFilePath() {
+  const originalPrepareStackTrace = Error.prepareStackTrace;
+  try {
+    const err = new Error();
+    Error.prepareStackTrace = (_, stack) => stack;
+    const stack = err.stack;
+    Error.prepareStackTrace = originalPrepareStackTrace;
+
+    // Look for the first file that's not sdk.js, hooks.mjs, or node internals
+    for (const callSite of stack) {
+      const fileName = callSite.getFileName();
+      if (fileName && 
+          !fileName.includes('sdk.js') && 
+          !fileName.includes('hooks.mjs') &&
+          !fileName.includes('hooks.js') &&
+          !fileName.includes('node_modules') &&
+          !fileName.includes('node:internal') &&
+          fileName !== 'evalmachine.<anonymous>') {
+        return fileName;
+      }
+    }
+  } catch (error) {
+    // Silently fail and return null
+  } finally {
+    Error.prepareStackTrace = originalPrepareStackTrace;
+  }
+  return null;
+}
+
+/**
+ * Generate a hash of the caller file for use as a cache key
+ * @returns {string|null} Hash of the file or null if file not found
+ */
+function getCallerFileHash() {
+  const filePath = getCallerFilePath();
+  if (!filePath) {
+    return null;
+  }
+
+  try {
+    // Handle file:// URLs by converting to file system path
+    let fsPath = filePath;
+    if (filePath.startsWith('file://')) {
+      fsPath = filePath.replace('file://', '');
+    }
+    
+    const fileContent = fs.readFileSync(fsPath, 'utf-8');
+    const hash = crypto.createHash('sha256').update(fileContent).digest('hex');
+    // Return first 16 chars of hash for brevity
+    return hash.substring(0, 16);
+  } catch (error) {
+    // If we can't read the file, return null
+    return null;
+  }
+}
+
 /**
  * Custom error class for element operation failures
  * Includes debugging information like screenshots and AI responses
@@ -13,8 +72,8 @@ class ElementNotFoundError extends Error {
   constructor(message, debugInfo = {}) {
     super(message);
     this.name = "ElementNotFoundError";
-    this.screenshot = debugInfo.screenshot;
-    this.aiResponse = debugInfo.aiResponse;
+    // Sanitize aiResponse to remove base64 images before storing
+    this.aiResponse = this._sanitizeAiResponse(debugInfo.aiResponse);
     this.description = debugInfo.description;
     this.timestamp = new Date().toISOString();
     this.screenshotPath = null;
@@ -24,8 +83,9 @@ class ElementNotFoundError extends Error {
       Error.captureStackTrace(this, ElementNotFoundError);
     }
 
-    // Write screenshot to temp directory
-    if (this.screenshot) {
+    // Write screenshot to temp directory immediately (don't store on error object)
+    // This prevents vitest from serializing huge base64 strings
+    if (debugInfo.screenshot) {
       try {
         const tempDir = path.join(os.tmpdir(), "testdriver-debug");
         if (!fs.existsSync(tempDir)) {
@@ -36,7 +96,7 @@ class ElementNotFoundError extends Error {
         this.screenshotPath = path.join(tempDir, filename);
 
         // Remove data:image/png;base64, prefix if present
-        const base64Data = this.screenshot.replace(
+        const base64Data = debugInfo.screenshot.replace(
           /^data:image\/\w+;base64,/,
           "",
         );
@@ -182,6 +242,25 @@ class ElementNotFoundError extends Error {
       this.stack = filteredLines.join("\n");
     }
   }
+
+  /**
+   * Sanitize AI response by removing large base64 data to prevent serialization issues
+   * @private
+   * @param {Object} response - AI response
+   * @returns {Object} Sanitized response
+   */
+  _sanitizeAiResponse(response) {
+    if (!response) return null;
+
+    // Create shallow copy and remove large base64 fields
+    const sanitized = { ...response };
+    delete sanitized.croppedImage;
+    delete sanitized.screenshot;
+    delete sanitized.pixelDiffImage;
+    // Keep cachedImageUrl as it's just a URL string, not base64 data
+
+    return sanitized;
+  }
 }
 
 /**
@@ -213,16 +292,18 @@ class Element {
   /**
    * Find the element on screen
    * @param {string} [newDescription] - Optional new description to search for
-   * @param {number} [cacheThreshold] - Cache threshold for this specific find (overrides global setting)
+   * @param {Object} [options] - Optional options object with cacheThreshold and/or cacheKey
    * @returns {Promise<Element>} This element instance
    */
-  async find(newDescription, cacheThreshold) {
+  async find(newDescription, options) {
     const description = newDescription || this.description;
     if (newDescription) {
       this.description = newDescription;
     }
 
     const startTime = Date.now();
+    let response = null;
+    let findError = null;
 
     const debugMode =
       process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
@@ -239,9 +320,38 @@ class Element {
         this._screenshot = screenshot;
       }
 
-      // Use per-command threshold if provided, otherwise fall back to global threshold
-      const threshold =
-        cacheThreshold ?? this.sdk.cacheThresholds?.find ?? 0.05;
+      // Handle options - can be a number (cacheThreshold) or object with cacheKey/cacheThreshold
+      let cacheKey = null;
+      let cacheThreshold = null;
+      
+      if (typeof options === 'number') {
+        // Legacy: options is just a number threshold
+        cacheThreshold = options;
+      } else if (typeof options === 'object' && options !== null) {
+        // New: options is an object with cacheKey and/or cacheThreshold
+        cacheKey = options.cacheKey || null;
+        cacheThreshold = options.cacheThreshold ?? null;
+      }
+
+      // Use default cacheKey from SDK constructor if not provided in find() options
+      if (!cacheKey && this.sdk.options?.cacheKey) {
+        cacheKey = this.sdk.options.cacheKey;
+      }
+
+      // Determine threshold: 
+      // - If cacheKey is provided, enable cache (threshold = 0.05 or custom)
+      // - If no cacheKey, disable cache (threshold = -1) unless explicitly overridden
+      let threshold;
+      if (cacheKey) {
+        // cacheKey provided - enable cache with threshold
+        threshold = cacheThreshold ?? 0.05;
+      } else if (cacheThreshold !== null) {
+        // Explicit threshold provided without cacheKey
+        threshold = cacheThreshold;
+      } else {
+        // No cacheKey, no explicit threshold - use global default (which is -1 now)
+        threshold = this.sdk.cacheThresholds?.find ?? -1;
+      }
 
       // Store the threshold for debugging
       this._threshold = threshold;
@@ -249,16 +359,21 @@ class Element {
       // Debug log threshold
       if (debugMode) {
         const { events } = require("./agent/events.js");
+        const autoGenMsg = (this.sdk._autoGeneratedCacheKey && cacheKey === this.sdk.options.cacheKey) 
+          ? ' (auto-generated from file hash)' 
+          : '';
         this.sdk.emitter.emit(
           events.log.debug,
-          `🔍 find() threshold: ${threshold} (cache ${threshold < 0 ? "DISABLED" : "ENABLED"})`,
+          `🔍 find() threshold: ${threshold} (cache ${threshold < 0 ? "DISABLED" : "ENABLED"}${cacheKey ? `, cacheKey: ${cacheKey}${autoGenMsg}` : ""})`,
         );
       }
 
-      const response = await this.sdk.apiClient.req("find", {
+      response = await this.sdk.apiClient.req("find", {
+        session: this.sdk.getSessionId(),
         element: description,
         image: screenshot,
         threshold: threshold,
+        cacheKey: cacheKey,
         os: this.sdk.os,
         resolution: this.sdk.resolution,
       });
@@ -278,12 +393,36 @@ class Element {
       } else {
         this._response = this._sanitizeResponse(response);
         this._found = false;
+        findError = "Element not found";
       }
     } catch (error) {
       this._response = error.response
         ? this._sanitizeResponse(error.response)
         : null;
       this._found = false;
+      findError = error.message;
+      response = error.response;
+    }
+
+    // Track find interaction once at the end
+    const sessionId = this.sdk.getSessionId();
+    if (sessionId && this.sdk.sandbox?.send) {
+      try {
+        await this.sdk.sandbox.send({
+          type: "trackInteraction",
+          interactionType: "find",
+          session: sessionId,
+          prompt: description,
+          timestamp: startTime,
+          success: this._found,
+          error: findError,
+          cacheHit: response?.cacheHit || response?.cache_hit || response?.cached || false,
+          selector: response?.selector,
+          selectorUsed: !!response?.selector,
+        });
+      } catch (err) {
+        console.warn("Failed to track find interaction:", err.message);
+      }
     }
 
     return this;
@@ -544,11 +683,8 @@ class Element {
         `Element "${this.description}" not found.`,
         {
           description: this.description,
-          screenshot: this._screenshot,
           aiResponse: this._response,
           threshold: this._threshold,
-          cachedImageUrl: this._response?.cachedImageUrl,
-          pixelDiffImage: this._response?.pixelDiffImage,
         },
       );
     }
@@ -562,10 +698,22 @@ class Element {
     );
     this.sdk.emitter.emit(events.log.log, formattedMessage);
 
+    // Prepare element metadata for interaction tracking
+    const elementData = {
+      prompt: this.description,
+      elementType: this._response?.elementType,
+      elementBounds: this._response?.elementBounds,
+      croppedImageUrl: this._response?.savedImagePath,
+      edgeDetectedImageUrl: this._response?.edgeSavedImagePath || null,
+      cacheHit: this._response?.cacheHit,
+      selectorUsed: !!this._response?.selector,
+      selector: this._response?.selector
+    };
+
     if (action === "hover") {
-      await this.commands.hover(this.coordinates.x, this.coordinates.y);
+      await this.commands.hover(this.coordinates.x, this.coordinates.y, elementData);
     } else {
-      await this.commands.click(this.coordinates.x, this.coordinates.y, action);
+      await this.commands.click(this.coordinates.x, this.coordinates.y, action, elementData);
     }
   }
 
@@ -579,11 +727,8 @@ class Element {
         `Element "${this.description}" not found.`,
         {
           description: this.description,
-          screenshot: this._screenshot,
           aiResponse: this._response,
           threshold: this._threshold,
-          cachedImageUrl: this._response?.cachedImageUrl,
-          pixelDiffImage: this._response?.pixelDiffImage,
         },
       );
     }
@@ -593,7 +738,19 @@ class Element {
     const formattedMessage = formatter.formatAction("hover", this.description);
     this.sdk.emitter.emit(events.log.log, formattedMessage);
 
-    await this.commands.hover(this.coordinates.x, this.coordinates.y);
+    // Prepare element metadata for interaction tracking
+    const elementData = {
+      prompt: this.description,
+      elementType: this._response?.elementType,
+      elementBounds: this._response?.elementBounds,
+      croppedImageUrl: this._response?.savedImagePath,
+      edgeDetectedImageUrl: this._response?.edgeSavedImagePath || null,
+      cacheHit: this._response?.cacheHit,
+      selectorUsed: !!this._response?.selector,
+      selector: this._response?.selector
+    };
+
+    await this.commands.hover(this.coordinates.x, this.coordinates.y, elementData);
   }
 
   /**
@@ -785,6 +942,60 @@ class Element {
   }
 }
 
+/**
+ * Creates a chainable promise that allows method chaining on find() results
+ * This enables syntax like: await testdriver.find("button").click()
+ * 
+ * @param {Promise<Element>} promise - The promise that resolves to an Element
+ * @returns {Promise<Element> & ChainableElement} A promise with chainable element methods
+ */
+function createChainablePromise(promise) {
+  // Define the chainable methods that should be available
+  const chainableMethods = ['click', 'hover', 'doubleClick', 'rightClick', 'mouseDown', 'mouseUp'];
+  
+  // Create a new promise that wraps the original
+  const chainablePromise = promise.then(element => element);
+  
+  // Add chainable methods to the promise
+  for (const method of chainableMethods) {
+    chainablePromise[method] = function(...args) {
+      // Return a promise that waits for the element, then calls the method
+      return promise.then(element => element[method](...args));
+    };
+  }
+  
+  // Add getters for element properties (these return promises)
+  Object.defineProperty(chainablePromise, 'x', {
+    get() { return promise.then(el => el.x); }
+  });
+  Object.defineProperty(chainablePromise, 'y', {
+    get() { return promise.then(el => el.y); }
+  });
+  Object.defineProperty(chainablePromise, 'centerX', {
+    get() { return promise.then(el => el.centerX); }
+  });
+  Object.defineProperty(chainablePromise, 'centerY', {
+    get() { return promise.then(el => el.centerY); }
+  });
+  
+  // Add found() method
+  chainablePromise.found = function() {
+    return promise.then(el => el.found());
+  };
+  
+  // Add getCoordinates() method
+  chainablePromise.getCoordinates = function() {
+    return promise.then(el => el.getCoordinates());
+  };
+  
+  // Add getResponse() method
+  chainablePromise.getResponse = function() {
+    return promise.then(el => el.getResponse());
+  };
+  
+  return chainablePromise;
+}
+
 /**
  * TestDriver SDK
  *
@@ -838,6 +1049,17 @@ class TestDriverSDK {
       },
     });
 
+    // Auto-generate cache key from caller file hash if not explicitly provided
+    // This allows caching to be tied to the specific test file
+    if (!options.cacheKey) {
+      const autoGeneratedKey = getCallerFileHash();
+      if (autoGeneratedKey) {
+        options.cacheKey = autoGeneratedKey;
+        // Store flag to indicate this was auto-generated
+        this._autoGeneratedCacheKey = true;
+      }
+    }
+
     // Store options for later use
     this.options = options;
 
@@ -847,7 +1069,7 @@ class TestDriverSDK {
 
     // Store newSandbox preference from options
     this.newSandbox =
-      options.newSandbox !== undefined ? options.newSandbox : false;
+      options.newSandbox !== undefined ? options.newSandbox : true;
 
     // Store headless preference from options
     this.headless = options.headless !== undefined ? options.headless : false;
@@ -862,31 +1084,48 @@ class TestDriverSDK {
 
     // Cache threshold configuration
     // threshold = pixel difference allowed (0.05 = 5% difference, 95% similarity)
-    // cache: false option disables cache completely by setting threshold to -1
-    // Also support TD_NO_CACHE environment variable
-    const useCache =
-      options.cache !== false && process.env.TD_NO_CACHE !== "true";
-
-    // Note: Cannot emit events here as emitter is not yet available
-    // Logging will be done after connection
-
-    if (!useCache) {
-      // If cache is disabled, use -1 to bypass cache entirely
+    // By default, cache is DISABLED (threshold = -1) to avoid unnecessary AI costs
+    // To enable cache, provide a cacheKey when calling find() or findAll()
+    // Also support TD_NO_CACHE environment variable and cache: false option for backwards compatibility
+    const cacheDisabled =
+      options.cache === false || process.env.TD_NO_CACHE === "true";
+
+    if (cacheDisabled) {
+      // Explicit cache disabled via option or env var
       this.cacheThresholds = {
         find: -1,
         findAll: -1,
       };
     } else {
-      // Use configured thresholds or defaults
+      // Cache disabled by default, enabled only when cacheKey is provided
+      // Note: The threshold value here is the fallback when cacheKey is NOT provided
       this.cacheThresholds = {
-        find: options.cacheThreshold?.find ?? 0.05,
-        findAll: options.cacheThreshold?.findAll ?? 0.05,
+        find: options.cacheThreshold?.find ?? -1,  // Default: cache disabled
+        findAll: options.cacheThreshold?.findAll ?? -1,  // Default: cache disabled
       };
     }
 
-    // Redraw threshold configuration
-    // threshold = percentage of pixels that must change to consider screen redrawn (0.1 = 0.1%)
-    this.redrawThreshold = options.redrawThreshold ?? 0.1;
+    // Redraw configuration
+    // Supports both:
+    //   - redraw: { enabled: true, diffThreshold: 0.1, screenRedraw: true, networkMonitor: true }
+    //   - redrawThreshold: 0.1 (legacy, sets diffThreshold)
+    // The `redraw` option takes precedence and matches the per-command API
+    if (options.redraw !== undefined) {
+      // New unified API: redraw object (matches per-command options)
+      this.redrawOptions = typeof options.redraw === 'object' 
+        ? options.redraw 
+        : { enabled: options.redraw }; // Support redraw: false as shorthand
+    } else if (options.redrawThreshold !== undefined) {
+      // Legacy API: redrawThreshold number or object
+      this.redrawOptions = typeof options.redrawThreshold === 'object'
+        ? options.redrawThreshold
+        : { diffThreshold: options.redrawThreshold };
+    } else {
+      // Default: enabled (as of v7.2)
+      this.redrawOptions = { enabled: true };
+    }
+    // Keep redrawThreshold for backwards compatibility in connect()
+    this.redrawThreshold = this.redrawOptions;
 
     // Track connection state
     this.connected = false;
@@ -910,6 +1149,258 @@ class TestDriverSDK {
 
     // Set up event listeners once (they live for the lifetime of the SDK instance)
     this._setupLogging();
+
+    // Set up provision API
+    this.provision = this._createProvisionAPI();
+
+    // Set up dashcam API lazily
+    this._dashcam = null;
+  }
+
+  /**
+   * Wait for the sandbox connection to complete
+   * @returns {Promise<void>}
+   */
+  async ready() {
+    if (this.__connectionPromise) {
+      await this.__connectionPromise;
+    }
+    if (!this.connected) {
+      throw new Error('Not connected to sandbox. Call connect() first or use autoConnect option.');
+    }
+  }
+
+  /**
+   * Get or create the Dashcam instance
+   * @returns {Dashcam} Dashcam instance
+   */
+  get dashcam() {
+    if (!this._dashcam) {
+      const { Dashcam } = require("./lib/core/index.js");
+      // Don't pass apiKey - let Dashcam use its default key
+      this._dashcam = new Dashcam(this);
+    }
+    return this._dashcam;
+  }
+
+  /**
+   * Get milliseconds elapsed since dashcam started recording
+   * @returns {number|null} Milliseconds since dashcam start, or null if not recording
+   */
+  getDashcamElapsedTime() {
+    if (this._dashcam) {
+      return this._dashcam.getElapsedTime();
+    }
+    return null;
+  }
+
+  /**
+   * Create the provision API with methods for launching applications
+   * @private
+   */
+  _createProvisionAPI() {
+    return {
+      /**
+       * Launch Chrome browser
+       * @param {Object} options - Chrome launch options
+       * @param {string} [options.url='http://testdriver-sandbox.vercel.app/'] - URL to navigate to
+       * @param {boolean} [options.maximized=true] - Start maximized
+       * @param {boolean} [options.guest=false] - Use guest mode
+       * @returns {Promise<void>}
+       */
+      chrome: async (options = {}) => {
+        // Automatically wait for connection to be ready
+        await this.ready();
+        
+        const {
+          url = 'http://testdriver-sandbox.vercel.app/',
+          maximized = true,
+          guest = false,
+        } = options;
+
+        // If dashcam is available and recording, add web logs for this domain
+        if (this._dashcam) {
+    
+            // Create the log file on the remote machine
+            const shell = this.os === "windows" ? "pwsh" : "sh";
+            const logPath = this.os === "windows" 
+            ? "C:\\Users\\testdriver\\Documents\\testdriver.log"
+            : "/tmp/testdriver.log";
+            
+            const createLogCmd = this.os === "windows"
+            ? `New-Item -ItemType File -Path "${logPath}" -Force | Out-Null`
+            : `touch ${logPath}`;
+            
+            await this.exec(shell, createLogCmd, 10000, true);
+          
+          console.log('[provision.chrome] Adding web logs to dashcam...');
+          try {
+            const urlObj = new URL(url);
+            const domain = urlObj.hostname;
+            const pattern = `*${domain}*`;
+            await this._dashcam.addWebLog(pattern, 'Web Logs');
+            console.log(`[provision.chrome] ✅ Web logs added to dashcam (pattern: ${pattern})`);
+
+            await this._dashcam.addFileLog(logPath, "TestDriver Log");
+
+          } catch (error) {
+            console.warn('[provision.chrome] ⚠️  Failed to add web logs:', error.message);
+          }
+        }
+        
+        // Automatically start dashcam if not already recording
+        if (!this._dashcam || !this._dashcam.recording) {
+          console.log('[provision.chrome] Starting dashcam...');
+          await this.dashcam.start();
+          console.log('[provision.chrome] ✅ Dashcam started');
+        }
+
+        // Build Chrome launch command
+        const chromeArgs = [];
+        if (maximized) chromeArgs.push('--start-maximized');
+        if (guest) chromeArgs.push('--guest');
+        chromeArgs.push('--disable-fre', '--no-default-browser-check', '--no-first-run');
+        
+        // Add dashcam-chrome extension on Linux
+        if (this.os === 'linux') {
+          chromeArgs.push('--load-extension=/usr/lib/node_modules/dashcam-chrome/build');
+        }
+
+        // Launch Chrome
+        const shell = this.os === 'windows' ? 'pwsh' : 'sh';
+        
+        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}"`,
+            30000
+          );
+        } else {
+          const argsString = chromeArgs.join(' ');
+          await this.exec(
+            shell,
+            `chrome-for-testing ${argsString} "${url}" >/dev/null 2>&1 &`,
+            30000
+          );
+        }
+
+        // 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;
+          
+          console.log(`[provision.chrome] Waiting for domain "${domain}" to appear in URL bar...`);
+          
+          for (let attempt = 0; attempt < 30; attempt++) {
+            try {
+              const result = await this.find(`${domain}`);
+              if (result.found()) {
+                console.log(`[provision.chrome] ✅ Chrome ready at ${url}`);
+                break;
+              }
+            } catch (e) {
+              // Not found yet, continue polling
+            }
+            await new Promise(resolve => setTimeout(resolve, 1000));
+          }
+          
+          await this.focusApplication('Google Chrome');
+        } catch (e) {
+          console.warn(`[provision.chrome] ⚠️  Could not parse URL "${url}":`, e.message);
+        }
+      },
+
+      /**
+       * Launch VS Code
+       * @param {Object} options - VS Code launch options
+       * @param {string} [options.workspace] - Workspace/folder to open
+       * @param {string[]} [options.extensions=[]] - Extensions to install
+       * @returns {Promise<void>}
+       */
+      vscode: async (options = {}) => {
+        this._ensureConnected();
+        
+        const {
+          workspace = null,
+          extensions = [],
+        } = options;
+
+        // Install extensions if provided
+        for (const extension of extensions) {
+          const shell = this.os === 'windows' ? 'pwsh' : 'sh';
+          await this.exec(
+            shell,
+            `code --install-extension ${extension}`,
+            60000,
+            true
+          );
+        }
+
+        // Launch VS Code
+        const shell = this.os === 'windows' ? 'pwsh' : 'sh';
+        const workspaceArg = workspace ? `"${workspace}"` : '';
+        
+        if (this.os === 'windows') {
+          await this.exec(
+            shell,
+            `Start-Process code -ArgumentList ${workspaceArg}`,
+            30000
+          );
+        } else {
+          await this.exec(
+            shell,
+            `code ${workspaceArg} >/dev/null 2>&1 &`,
+            30000
+          );
+        }
+
+        // Wait for VS Code to be ready
+        await this.focusApplication('Visual Studio Code');
+        console.log('[provision.vscode] ✅ VS Code ready');
+      },
+
+      /**
+       * Launch Electron app
+       * @param {Object} options - Electron launch options
+       * @param {string} options.appPath - Path to Electron app (required)
+       * @param {string[]} [options.args=[]] - Additional electron args
+       * @returns {Promise<void>}
+       */
+      electron: async (options = {}) => {
+        this._ensureConnected();
+        
+        const { appPath, args = [] } = options;
+        
+        if (!appPath) {
+          throw new Error('provision.electron requires appPath option');
+        }
+
+        const shell = this.os === 'windows' ? 'pwsh' : 'sh';
+        const argsString = args.join(' ');
+        
+        if (this.os === 'windows') {
+          await this.exec(
+            shell,
+            `Start-Process electron -ArgumentList "${appPath}", ${argsString}`,
+            30000
+          );
+        } else {
+          await this.exec(
+            shell,
+            `electron "${appPath}" ${argsString} >/dev/null 2>&1 &`,
+            30000
+          );
+        }
+
+        await this.focusApplication('Electron');
+        console.log('[provision.electron] ✅ Electron app ready');
+      },
+    };
   }
 
   /**
@@ -995,6 +1486,9 @@ class TestDriverSDK {
       this.agent.sandboxOs = connectOptions.os;
     } else if (this.sandboxOs) {
       this.agent.sandboxOs = this.sandboxOs;
+    } else {
+      // Fall back to this.os (which defaults to "linux")
+      this.agent.sandboxOs = this.os;
     }
 
     // Set redrawThreshold on agent's cliArgs.options
@@ -1009,6 +1503,22 @@ class TestDriverSDK {
     // Expose the agent's commands, parser, and commander
     this.commands = this.agent.commands;
 
+    // Recreate commands with dashcam elapsed time support
+    const { createCommands } = require("./agent/lib/commands.js");
+    const commandsResult = createCommands(
+      this.agent.emitter,
+      this.agent.system,
+      this.agent.sandbox,
+      this.agent.config,
+      this.agent.session,
+      () => this.agent.sourceMapper?.currentFilePath || this.agent.thisFile,
+      this.agent.cliArgs.options.redrawThreshold,
+      () => this.getDashcamElapsedTime(), // Pass dashcam elapsed time function
+    );
+    this.commands = commandsResult.commands;
+    this.agent.commands = commandsResult.commands;
+    this.agent.redraw = commandsResult.redraw;
+
     // Dynamically create command methods based on available commands
     this._setupCommandMethods();
 
@@ -1027,13 +1537,19 @@ class TestDriverSDK {
    * @returns {Promise<void>}
    */
   async disconnect() {
+    // Track disconnect event if we were connected
     if (this.connected && this.instance) {
-      // Track disconnect event
       this.analytics.track("sdk.disconnect");
+    }
 
-      this.connected = false;
-      this.instance = null;
+    // Always close the sandbox WebSocket connection to clean up resources
+    // This ensures we don't leave orphaned connections even if connect() failed
+    if (this.sandbox && typeof this.sandbox.close === 'function') {
+      this.sandbox.close();
     }
+
+    this.connected = false;
+    this.instance = null;
   }
 
   /**
@@ -1054,16 +1570,24 @@ class TestDriverSDK {
    * Automatically locates the element and returns it
    *
    * @param {string} description - Description of the element to find
-   * @param {number} [cacheThreshold] - Cache threshold for this specific find (overrides global setting)
-   * @returns {Promise<Element>} Element instance that has been located
+   * @param {number | Object} [options] - Cache options: number for threshold, or object with {cacheKey, cacheThreshold}
+   * @returns {Promise<Element> & ChainableElement} Element instance that has been located, with chainable methods
    *
    * @example
-   * // Find and click immediately
+   * // Find and click immediately (chainable)
+   * await client.find('the sign in button').click();
+   *
+   * @example
+   * // Find and click (traditional)
    * const element = await client.find('the sign in button');
    * await element.click();
    *
    * @example
-   * // Find with custom cache threshold
+   * // Find with cache key to enable caching
+   * const element = await client.find('login button', { cacheKey: 'my-test-run' });
+   *
+   * @example
+   * // Find with custom cache threshold (legacy)
    * const element = await client.find('login button', 0.01);
    *
    * @example
@@ -1077,10 +1601,14 @@ class TestDriverSDK {
    * }
    * await element.click();
    */
-  async find(description, cacheThreshold) {
+  find(description, options) {
     this._ensureConnected();
     const element = new Element(description, this, this.system, this.commands);
-    return await element.find(null, cacheThreshold);
+    const findPromise = element.find(null, options);
+    
+    // Create a chainable promise that allows direct method chaining
+    // e.g., await testdriver.find("button").click()
+    return createChainablePromise(findPromise);
   }
 
   /**
@@ -1088,7 +1616,7 @@ class TestDriverSDK {
    * Automatically locates all matching elements and returns them as an array
    *
    * @param {string} description - Description of the elements to find
-   * @param {number} [cacheThreshold] - Cache threshold for this specific findAll (overrides global setting)
+   * @param {number | Object} [options] - Cache options: number for threshold, or object with {cacheKey, cacheThreshold}
    * @returns {Promise<Element[]>} Array of Element instances that have been located
    *
    * @example
@@ -1099,13 +1627,13 @@ class TestDriverSDK {
    * }
    *
    * @example
-   * // Find all list items with custom cache threshold
-   * const items = await client.findAll('list item', 0.01);
+   * // Find all list items with cache key to enable caching
+   * const items = await client.findAll('list item', { cacheKey: 'my-test-run' });
    * for (const item of items) {
    *   console.log(`Found item at (${item.x}, ${item.y})`);
    * }
    */
-  async findAll(description, cacheThreshold) {
+  async findAll(description, options) {
     this._ensureConnected();
 
     const startTime = Date.now();
@@ -1118,15 +1646,59 @@ class TestDriverSDK {
     try {
       const screenshot = await this.system.captureScreenBase64();
 
-      // Use per-command threshold if provided, otherwise fall back to global threshold
-      const threshold = cacheThreshold ?? this.cacheThresholds?.findAll ?? 0.05;
+      // Handle options - can be a number (cacheThreshold) or object with cacheKey/cacheThreshold
+      let cacheKey = null;
+      let cacheThreshold = null;
+      
+      if (typeof options === 'number') {
+        // Legacy: options is just a number threshold
+        cacheThreshold = options;
+      } else if (typeof options === 'object' && options !== null) {
+        // New: options is an object with cacheKey and/or cacheThreshold
+        cacheKey = options.cacheKey || null;
+        cacheThreshold = options.cacheThreshold ?? null;
+      }
+
+      // Use default cacheKey from SDK constructor if not provided in findAll() options
+      if (!cacheKey && this.options?.cacheKey) {
+        cacheKey = this.options.cacheKey;
+      }
+
+      // Determine threshold: 
+      // - If cacheKey is provided, enable cache (threshold = 0.05 or custom)
+      // - If no cacheKey, disable cache (threshold = -1) unless explicitly overridden
+      let threshold;
+      if (cacheKey) {
+        // cacheKey provided - enable cache with threshold
+        threshold = cacheThreshold ?? 0.05;
+      } else if (cacheThreshold !== null) {
+        // Explicit threshold provided without cacheKey
+        threshold = cacheThreshold;
+      } else {
+        // No cacheKey, no explicit threshold - use global default (which is -1 now)
+        threshold = this.cacheThresholds?.findAll ?? -1;
+      }
+
+      // Debug log threshold
+      const debugMode = process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
+      if (debugMode) {
+        const autoGenMsg = (this._autoGeneratedCacheKey && cacheKey === this.options.cacheKey) 
+          ? ' (auto-generated from file hash)' 
+          : '';
+        this.emitter.emit(
+          events.log.debug,
+          `🔍 findAll() threshold: ${threshold} (cache ${threshold < 0 ? "DISABLED" : "ENABLED"}${cacheKey ? `, cacheKey: ${cacheKey}${autoGenMsg}` : ""})`,
+        );
+      }
 
       const response = await this.apiClient.req(
         "/api/v7.0.0/testdriver-agent/testdriver-find-all",
         {
+          session: this.getSessionId(),
           element: description,
           image: screenshot,
           threshold: threshold,
+          cacheKey: cacheKey,
           os: this.os,
           resolution: this.resolution,
         },
@@ -1173,6 +1745,27 @@ class TestDriverSDK {
           return element;
         });
 
+        // Track successful findAll interaction
+        const sessionId = this.getSessionId();
+        if (sessionId && this.sandbox?.send) {
+          try {
+            await this.sandbox.send({
+              type: "trackInteraction",
+              interactionType: "findAll",
+              session: sessionId,
+              prompt: description,
+              timestamp: startTime,
+              success: true,
+              input: { count: elements.length },
+              cacheHit: response.cached || false,
+              selector: response.selector,
+              selectorUsed: !!response.selector,
+            });
+          } catch (err) {
+            console.warn("Failed to track findAll interaction:", err.message);
+          }
+        }
+
         // Log debug information when elements are found
         if (process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG) {
           const { events } = require("./agent/events.js");
@@ -1189,10 +1782,51 @@ class TestDriverSDK {
 
         return elements;
       } else {
+        // No elements found - track interaction
+        const sessionId = this.getSessionId();
+        if (sessionId && this.sandbox?.send) {
+          try {
+            await this.sandbox.send({
+              type: "trackInteraction",
+              interactionType: "findAll",
+              session: sessionId,
+              prompt: description,
+              timestamp: startTime,
+              success: false,
+              error: "No elements found",
+              input: { count: 0 },
+              cacheHit: response?.cached || false,
+              selector: response?.selector,
+              selectorUsed: !!response?.selector,
+            });
+          } catch (err) {
+            console.warn("Failed to track findAll interaction:", err.message);
+          }
+        }
+
         // No elements found - return empty array
         return [];
       }
     } catch (error) {
+      // Track findAll error interaction
+      const sessionId = this.getSessionId();
+      if (sessionId && this.sandbox?.send) {
+        try {
+          await this.sandbox.send({
+            type: "trackInteraction",
+            interactionType: "findAll",
+            session: sessionId,
+            prompt: description,
+            timestamp: startTime,
+            success: false,
+            error: error.message,
+            input: { count: 0 },
+          });
+        } catch (err) {
+          console.warn("Failed to track findAll interaction:", err.message);
+        }
+      }
+
       const { events } = require("./agent/events.js");
       this.emitter.emit(events.log.log, `Error in findAll: ${error.message}`);
       return [];
@@ -1245,17 +1879,18 @@ class TestDriverSDK {
    */
   _setupCommandMethods() {
     // Mapping from command names to SDK method names with type definitions
+    // Each command supports both positional args (legacy) and object args (new)
     const commandMapping = {
       "hover-text": {
         name: "hoverText",
         /**
          * Hover over text on screen
          * @deprecated Use find() and element.click() instead
-         * @param {string} text - Text to find and hover over
-         * @param {string | null} [description] - Optional description of the element
-         * @param {ClickAction} [action='click'] - Action to perform
-         * @param {TextMatchMethod} [method='turbo'] - Text matching method
-         * @param {number} [timeout=5000] - Timeout in milliseconds
+         * @param {Object|string} options - Options object or text (legacy positional)
+         * @param {string} options.text - Text to find and hover over
+         * @param {string|null} [options.description] - Optional description of the element
+         * @param {ClickAction} [options.action='click'] - Action to perform
+         * @param {number} [options.timeout=5000] - Timeout in milliseconds
          * @returns {Promise<{x: number, y: number, centerX: number, centerY: number}>}
          */
         doc: "Hover over text on screen (deprecated - use find() instead)",
@@ -1265,8 +1900,9 @@ class TestDriverSDK {
         /**
          * Hover over an image on screen
          * @deprecated Use find() and element.click() instead
-         * @param {string} description - Description of the image to find
-         * @param {ClickAction} [action='click'] - Action to perform
+         * @param {Object|string} options - Options object or description (legacy positional)
+         * @param {string} options.description - Description of the image to find
+         * @param {ClickAction} [options.action='click'] - Action to perform
          * @returns {Promise<{x: number, y: number, centerX: number, centerY: number}>}
          */
         doc: "Hover over an image on screen (deprecated - use find() instead)",
@@ -1275,9 +1911,10 @@ class TestDriverSDK {
         name: "matchImage",
         /**
          * Match and interact with an image template
-         * @param {string} imagePath - Path to the image template
-         * @param {ClickAction} [action='click'] - Action to perform
-         * @param {boolean} [invert=false] - Invert the match
+         * @param {Object|string} options - Options object or path (legacy positional)
+         * @param {string} options.path - Path to the image template
+         * @param {ClickAction} [options.action='click'] - Action to perform
+         * @param {boolean} [options.invert=false] - Invert the match
          * @returns {Promise<boolean>}
          */
         doc: "Match and interact with an image template",
@@ -1286,17 +1923,20 @@ class TestDriverSDK {
         name: "type",
         /**
          * Type text
-         * @param {string | number} text - Text to type
-         * @param {number} [delay=250] - Delay between keystrokes in milliseconds
+         * @param {string|number} text - Text to type
+         * @param {Object} [options] - Additional options
+         * @param {number} [options.delay=250] - Delay between keystrokes in milliseconds
+         * @param {boolean} [options.secret=false] - If true, text is treated as sensitive (not logged or stored)
          * @returns {Promise<void>}
          */
-        doc: "Type text",
+        doc: "Type text (use { secret: true } for passwords)",
       },
       "press-keys": {
         name: "pressKeys",
         /**
          * Press keyboard keys
          * @param {KeyboardKey[]} keys - Array of keys to press
+         * @param {Object} [options] - Additional options (reserved for future use)
          * @returns {Promise<void>}
          */
         doc: "Press keyboard keys",
@@ -1305,9 +1945,10 @@ class TestDriverSDK {
         name: "click",
         /**
          * Click at coordinates
-         * @param {number} x - X coordinate
-         * @param {number} y - Y coordinate
-         * @param {ClickAction} [action='click'] - Type of click action
+         * @param {Object|number} options - Options object or x coordinate (legacy positional)
+         * @param {number} options.x - X coordinate
+         * @param {number} options.y - Y coordinate
+         * @param {ClickAction} [options.action='click'] - Type of click action
          * @returns {Promise<void>}
          */
         doc: "Click at coordinates",
@@ -1316,8 +1957,9 @@ class TestDriverSDK {
         name: "hover",
         /**
          * Hover at coordinates
-         * @param {number} x - X coordinate
-         * @param {number} y - Y coordinate
+         * @param {Object|number} options - Options object or x coordinate (legacy positional)
+         * @param {number} options.x - X coordinate
+         * @param {number} options.y - Y coordinate
          * @returns {Promise<void>}
          */
         doc: "Hover at coordinates",
@@ -1327,7 +1969,8 @@ class TestDriverSDK {
         /**
          * Scroll the page
          * @param {ScrollDirection} [direction='down'] - Direction to scroll
-         * @param {number} [amount=300] - Amount to scroll in pixels
+         * @param {Object} [options] - Additional options
+         * @param {number} [options.amount=300] - Amount to scroll in pixels
          * @returns {Promise<void>}
          */
         doc: "Scroll the page",
@@ -1338,6 +1981,7 @@ class TestDriverSDK {
          * Wait for specified time
          * @deprecated Consider using element polling with find() instead of arbitrary waits
          * @param {number} [timeout=3000] - Time to wait in milliseconds
+         * @param {Object} [options] - Additional options (reserved for future use)
          * @returns {Promise<void>}
          */
         doc: "Wait for specified time (deprecated - consider element polling instead)",
@@ -1347,10 +1991,9 @@ class TestDriverSDK {
         /**
          * Wait for text to appear on screen
          * @deprecated Use find() in a polling loop instead
-         * @param {string} text - Text to wait for
-         * @param {number} [timeout=5000] - Timeout in milliseconds
-         * @param {TextMatchMethod} [method='turbo'] - Text matching method
-         * @param {boolean} [invert=false] - Invert the match (wait for text to disappear)
+         * @param {Object|string} options - Options object or text (legacy positional)
+         * @param {string} options.text - Text to wait for
+         * @param {number} [options.timeout=5000] - Timeout in milliseconds
          * @returns {Promise<void>}
          */
         doc: "Wait for text to appear on screen (deprecated - use find() in a loop instead)",
@@ -1360,9 +2003,9 @@ class TestDriverSDK {
         /**
          * Wait for image to appear on screen
          * @deprecated Use find() in a polling loop instead
-         * @param {string} description - Description of the image
-         * @param {number} [timeout=10000] - Timeout in milliseconds
-         * @param {boolean} [invert=false] - Invert the match (wait for image to disappear)
+         * @param {Object|string} options - Options object or description (legacy positional)
+         * @param {string} options.description - Description of the image
+         * @param {number} [options.timeout=10000] - Timeout in milliseconds
          * @returns {Promise<void>}
          */
         doc: "Wait for image to appear on screen (deprecated - use find() in a loop instead)",
@@ -1371,12 +2014,11 @@ class TestDriverSDK {
         name: "scrollUntilText",
         /**
          * Scroll until text is found
-         * @param {string} text - Text to find
-         * @param {ScrollDirection} [direction='down'] - Scroll direction
-         * @param {number} [maxDistance=10000] - Maximum distance to scroll in pixels
-         * @param {TextMatchMethod} [textMatchMethod='turbo'] - Text matching method
-         * @param {ScrollMethod} [method='keyboard'] - Scroll method
-         * @param {boolean} [invert=false] - Invert the match
+         * @param {Object|string} options - Options object or text (legacy positional)
+         * @param {string} options.text - Text to find
+         * @param {ScrollDirection} [options.direction='down'] - Scroll direction
+         * @param {number} [options.maxDistance=10000] - Maximum distance to scroll in pixels
+         * @param {boolean} [options.invert=false] - Invert the match
          * @returns {Promise<void>}
          */
         doc: "Scroll until text is found",
@@ -1385,12 +2027,13 @@ class TestDriverSDK {
         name: "scrollUntilImage",
         /**
          * Scroll until image is found
-         * @param {string} description - Description of the image (or use path parameter)
-         * @param {ScrollDirection} [direction='down'] - Scroll direction
-         * @param {number} [maxDistance=10000] - Maximum distance to scroll in pixels
-         * @param {ScrollMethod} [method='keyboard'] - Scroll method
-         * @param {string | null} [path=null] - Path to image template
-         * @param {boolean} [invert=false] - Invert the match
+         * @param {Object|string} [options] - Options object or description (legacy positional)
+         * @param {string} [options.description] - Description of the image
+         * @param {ScrollDirection} [options.direction='down'] - Scroll direction
+         * @param {number} [options.maxDistance=10000] - Maximum distance to scroll in pixels
+         * @param {string} [options.method='mouse'] - Scroll method
+         * @param {string} [options.path] - Path to image template
+         * @param {boolean} [options.invert=false] - Invert the match
          * @returns {Promise<void>}
          */
         doc: "Scroll until image is found",
@@ -1400,6 +2043,7 @@ class TestDriverSDK {
         /**
          * Focus an application by name
          * @param {string} name - Application name
+         * @param {Object} [options] - Additional options (reserved for future use)
          * @returns {Promise<string>}
          */
         doc: "Focus an application by name",
@@ -1408,7 +2052,8 @@ class TestDriverSDK {
         name: "remember",
         /**
          * Extract and remember information from the screen using AI
-         * @param {string} description - What to remember
+         * @param {Object|string} options - Options object or description (legacy positional)
+         * @param {string} options.description - What to remember
          * @returns {Promise<string>}
          */
         doc: "Extract and remember information from the screen",
@@ -1418,6 +2063,7 @@ class TestDriverSDK {
         /**
          * Make an AI-powered assertion
          * @param {string} assertion - Assertion to check
+         * @param {Object} [options] - Additional options (reserved for future use)
          * @returns {Promise<boolean>}
          */
         doc: "Make an AI-powered assertion",
@@ -1426,10 +2072,11 @@ class TestDriverSDK {
         name: "exec",
         /**
          * Execute code in the sandbox
-         * @param {ExecLanguage} language - Language ('js' or 'pwsh')
-         * @param {string} code - Code to execute
-         * @param {number} timeout - Timeout in milliseconds
-         * @param {boolean} [silent=false] - Suppress output
+         * @param {Object|ExecLanguage} options - Options object or language (legacy positional)
+         * @param {ExecLanguage} [options.language='pwsh'] - Language ('js', 'pwsh', or 'sh')
+         * @param {string} options.code - Code to execute
+         * @param {number} [options.timeout] - Timeout in milliseconds
+         * @param {boolean} [options.silent=false] - Suppress output
          * @returns {Promise<string>}
          */
         doc: "Execute code in the sandbox",
@@ -1568,6 +2215,9 @@ class TestDriverSDK {
    * @private
    */
   _setupLogging() {
+    // Track the last fatal error message to throw on exit
+    let lastFatalError = null;
+
     // Set up markdown logger
     createMarkdownLogger(this.emitter);
 
@@ -1580,6 +2230,9 @@ class TestDriverSDK {
           ? `[${this.testContext}] ${message}`
           : message;
         console.log(prefixedMessage);
+        
+        // Also forward to sandbox for dashcam
+        this._forwardLogToSandbox(prefixedMessage);
       }
     });
 
@@ -1587,6 +2240,11 @@ class TestDriverSDK {
       if (this.loggingEnabled) {
         const event = this.emitter.event;
         console.error(event, ":", data);
+        
+        // Capture fatal errors
+        if (event === events.error.fatal) {
+          lastFatalError = data;
+        }
       }
     });
 
@@ -1613,6 +2271,19 @@ class TestDriverSDK {
       }
     });
 
+    // Handle exit events - throw error with meaningful message instead of calling process.exit
+    // This allows test frameworks like Vitest to properly catch and display the error
+    this.emitter.on(events.exit, (exitCode) => {
+      if (exitCode !== 0) {
+        // Create an error with the fatal error message if available
+        const errorMessage = lastFatalError || 'TestDriver fatal error';
+        const error = new Error(errorMessage);
+        error.name = 'TestDriverFatalError';
+        error.exitCode = exitCode;
+        throw error;
+      }
+    });
+
     // Handle show window events for sandbox visualization
     this.emitter.on("show-window", async (url) => {
       if (this.loggingEnabled) {
@@ -1748,13 +2419,42 @@ class TestDriverSDK {
     );
     await sdk.auth();
 
-    const platform = options.platform || this.config.TD_PLATFORM || "windows";
+    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;
 
-    // Get session ID from the agent's session instance
-    const sessionId = this.agent?.sessionInstance?.get() || 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,
@@ -1884,21 +2584,34 @@ class TestDriverSDK {
    *
    * @example
    * // Simple execution
-   * await client.ai('Click the submit button');
+   * await client.act('Click the submit button');
    *
    * @example
    * // With validation loop
-   * const result = await client.ai('Fill out the contact form', { validateAndLoop: true });
+   * const result = await client.act('Fill out the contact form', { validateAndLoop: true });
    * console.log(result); // AI's final assessment
    */
-  async ai(task) {
+  async act(task) {
     this._ensureConnected();
 
-    this.analytics.track("sdk.ai", { task });
+    this.analytics.track("sdk.act", { task });
 
     // Use the agent's exploratoryLoop method directly
     return await this.agent.exploratoryLoop(task, false, true, false);
   }
+
+  /**
+   * @deprecated Use act() instead
+   * 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
+   */
+  async ai(task) {
+    return await this.act(task);
+  }
 }
 
 module.exports = TestDriverSDK;