@testdriverai/agent 7.8.0-canary.14 → 7.8.0-canary.16

package/agent/index.js

@@ -70,6 +70,7 @@ class TestDriverAgent extends EventEmitter2 {
     this.sandboxId = flags["sandbox-id"] || null;
     this.sandboxAmi = flags["sandbox-ami"] || null;
     this.sandboxInstance = flags["sandbox-instance"] || null;
+    this.e2bTemplateId = flags["e2b-template-id"] || null;
     this.sandboxOs = flags.os || "linux";
     this.ip = flags.ip || null;
     this.workingDir = flags.workingDir || process.cwd();
@@ -2188,6 +2189,9 @@ Please check your network connection, TD_API_KEY, or the service status.`,
     if (this.sandboxInstance) {
       sandboxConfig.instanceType = this.sandboxInstance;
     }
+    if (this.e2bTemplateId) {
+      sandboxConfig.e2bTemplateId = this.e2bTemplateId;
+    }
     // Add keepAlive TTL if specified
     if (this.keepAlive !== undefined && this.keepAlive !== null) {
       sandboxConfig.keepAlive = this.keepAlive;

package/agent/lib/logger.js

@@ -7,6 +7,7 @@
  */
 
 const useStderr = process.env.TD_STDIO === 'stderr';
+const isDebug = process.env.TD_DEBUG === 'true' || process.env.VERBOSE === 'true';
 
 /**
  * Log a message - uses stdout by default, stderr if TD_STDIO=stderr
@@ -40,6 +41,19 @@ function warn(...args) {
   }
 }
 
+/**
+ * Log a debug message - only outputs when DEBUG=true
+ * @param {...any} args - Arguments to log
+ */
+function debug(...args) {
+  if (!isDebug) return;
+  if (useStderr) {
+    console.error(...args);
+  } else {
+    console.log(...args);
+  }
+}
+
 /**
  * Check if logger is configured to use stderr
  * @returns {boolean}
@@ -50,6 +64,7 @@ function isStderrMode() {
 
 module.exports = {
   log,
+  debug,
   error,
   warn,
   isStderrMode,

package/agent/lib/sandbox.js

@@ -29,7 +29,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       this._lastConnectParams = null;
       this._teamId = null;
       this._sandboxId = null;
-      this._disconnectedAt = null; // tracks when Ably connection dropped (for timeout extension on reconnect)
+      this._disconnectedAt = null; // tracks when Realtime connection dropped (for timeout extension on reconnect)
 
       // Rate limiting state for Ably publishes (Ably limits to 50 msg/sec per connection)
       this._publishLastTime = 0;
@@ -49,6 +49,10 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       );
     }
 
+    getPublishCount() {
+      return this._publishCount;
+    }
+
     async _initAbly(ablyToken, channelName) {
       if (this._ably) {
         try {
@@ -61,8 +65,23 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       var self = this;
 
       this._ably = new Ably.Realtime({
-        authCallback: function (tokenParams, callback) {
-          callback(null, ablyToken);
+        authCallback: async function (tokenParams, callback) {
+          // On initial connect Ably may supply the token directly; on renewal
+          // we must fetch a fresh one from the API (the original token will
+          // have expired, causing 40143 token.unrecognized if reused).
+          try {
+            const response = await axios({
+              method: "post",
+              url: self.apiRoot + "/api/v7/sandbox/ably-token",
+              data: { apiKey: self.apiKey, sandboxId: self._sandboxId },
+              headers: { "Content-Type": "application/json" },
+              timeout: 15000,
+            });
+            callback(null, response.data.token);
+          } catch (err) {
+            logger.warn("[ably] Token renewal failed, falling back to original token: " + (err.message || err));
+            callback(null, ablyToken);
+          }
         },
         clientId: "sdk-" + this._sandboxId,
         echoMessages: false,              // don't receive our own published messages
@@ -70,21 +89,21 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
         suspendedRetryTimeout: 15000,     // retry from suspended every 15s (default 30s)
       });
 
-      logger.log(`[ably] Connecting as sdk-${this._sandboxId}...`);
+      logger.debug(`[realtime] Connecting as sdk-${this._sandboxId}...`);
 
       await new Promise(function (resolve, reject) {
         self._ably.connection.on("connected", resolve);
         self._ably.connection.on("failed", function () {
-          reject(new Error("Ably connection failed"));
+          reject(new Error("Realtime connection failed"));
         });
         setTimeout(function () {
-          reject(new Error("Ably connection timeout"));
+          reject(new Error("Realtime connection timeout"));
         }, 30000);
       });
 
       this._sessionChannel = this._ably.channels.get(channelName);
 
-      logger.log(`[ably] Channel initialized: ${channelName}`);
+      logger.debug(`[realtime] Channel initialized: ${channelName}`);
 
       // Enter presence on the session channel so the API can count connected SDK clients
       try {
@@ -92,7 +111,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
           sandboxId: this._sandboxId,
           connectedAt: Date.now(),
         });
-        logger.log(`[ably] Entered presence on session channel (sandbox=${this._sandboxId})`);
+        logger.debug(`[realtime] Entered presence on session channel (sandbox=${this._sandboxId})`);
       } catch (e) {
         // Non-fatal — presence is used for concurrency counting, not critical path
         logger.warn("Failed to enter presence on session channel: " + (e.message || e));
@@ -103,7 +122,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
         var message = msg.data;
         if (!message) return;
 
-        logger.log(`[ably] Received response: type=${message.type || 'unknown'} (requestId=${message.requestId || 'none'})`);
+        logger.debug(`[realtime] Received response: type=${message.type || 'unknown'} (requestId=${message.requestId || 'none'})`);
 
         if (message.type === "sandbox.progress") {
           emitter.emit(events.sandbox.progress, {
@@ -162,8 +181,8 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
               return rid + '(' + (e && e.message ? e.message.type : '?') + ')';
             }).join(', ')
             : 'none';
-          logger.warn(
-            '[ably] No pending promise for requestId=' + (message.requestId || 'null') +
+          logger.debug(
+            '[realtime] No pending promise for requestId=' + (message.requestId || 'null') +
             ' | response type=' + (message.type || 'unknown') +
             ' | error=' + (message.error ? (message.errorMessage || 'true') : 'false') +
             ' | currently pending: [' + pendingSummary + ']'
@@ -177,8 +196,8 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
           var pendingAge = pendingEntry && pendingEntry.startTime
             ? ((Date.now() - pendingEntry.startTime) / 1000).toFixed(1) + 's'
             : '?';
-          logger.warn(
-            '[ably] Promise REJECTED: requestId=' + message.requestId +
+          logger.debug(
+            '[realtime] Promise REJECTED: requestId=' + message.requestId +
             ' | type=' + (pendingMessage ? pendingMessage.type : 'unknown') +
             ' | age=' + pendingAge +
             ' | error=' + (message.errorMessage || 'Sandbox error')
@@ -197,8 +216,8 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
             var resolveAge = resolveEntry.startTime
               ? ((Date.now() - resolveEntry.startTime) / 1000).toFixed(1) + 's'
               : '?';
-            logger.log(
-              '[ably] Promise RESOLVED: requestId=' + message.requestId +
+            logger.debug(
+              '[realtime] Promise RESOLVED: requestId=' + message.requestId +
               ' | type=' + (resolveEntry.message ? resolveEntry.message.type : 'unknown') +
               ' | age=' + resolveAge
             );
@@ -226,7 +245,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       this._onFileMsg = function (msg) {
         var message = msg.data;
         if (!message) return;
-        logger.log(`[ably] Received file: type=${message.type || 'unknown'} (requestId=${message.requestId || 'none'})`);
+        logger.debug(`[realtime] Received file: type=${message.type || 'unknown'} (requestId=${message.requestId || 'none'})`);
         if (message.requestId && self.ps[message.requestId]) {
           emitter.emit(events.sandbox.received);
           self.ps[message.requestId].resolve(message);
@@ -245,7 +264,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
         const chState = this._sessionChannel ? this._sessionChannel.state : 'null';
         const pendingIds = Object.keys(this.ps);
         const pending = pendingIds.length;
-        logger.log(`[ably][stats] connection=${connState} | sandbox=${this._sandboxId} | pending=${pending} | channel=${chState}`);
+        logger.debug(`[realtime][stats] connection=${connState} | sandbox=${this._sandboxId} | pending=${pending} | channel=${chState}`);
         if (pending > 0) {
           const now = Date.now();
           for (const rid of pendingIds) {
@@ -253,20 +272,20 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
             if (!entry) continue;
             const type = entry.message ? entry.message.type : 'unknown';
             const ageSec = ((now - (entry.startTime || now)) / 1000).toFixed(1);
-            logger.log(`[ably][stats]   pending: requestId=${rid} | type=${type} | age=${ageSec}s`);
+            logger.debug(`[realtime][stats]   pending: requestId=${rid} | type=${type} | age=${ageSec}s`);
           }
         }
       }, 10000);
       if (this._statsInterval.unref) this._statsInterval.unref();
 
       this._ably.connection.on("disconnected", function () {
-        logger.log("[ably] Connection: disconnected - will auto-reconnect");
+        logger.debug("[realtime] Connection: disconnected - will auto-reconnect");
         self._disconnectedAt = Date.now();
       });
 
       this._ably.connection.on("connected", function () {
         // Log reconnection so the user knows the blip was recovered
-        logger.log("[ably] Connection: reconnected");
+        logger.debug("[realtime] Connection: reconnected");
         // Extend any pending command timeouts by the disconnection duration so
         // commands whose timer was counting down while the connection was down
         // don't get incorrectly timed out.
@@ -275,8 +294,8 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
           self._disconnectedAt = null;
           var pendingIds = Object.keys(self.ps);
           if (pendingIds.length > 0) {
-            logger.log(
-              '[ably] Extending ' + pendingIds.length + ' pending timeout(s) by ' +
+            logger.debug(
+              '[realtime] Extending ' + pendingIds.length + ' pending timeout(s) by ' +
               disconnectionDurationMs + 'ms after disconnection'
             );
             for (var i = 0; i < pendingIds.length; i++) {
@@ -290,14 +309,14 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       });
 
       this._ably.connection.on("suspended", function () {
-        logger.warn("[ably] Connection: suspended - connection lost for extended period, will keep retrying");
+        logger.debug("[realtime] Connection: suspended - connection lost for extended period, will keep retrying");
       });
 
       this._ably.connection.on("failed", function () {
-        logger.error("[ably] Connection: failed");
+        logger.debug("[realtime] Connection: failed");
         self.apiSocketConnected = false;
         self.instanceSocketConnected = false;
-        emitter.emit(events.error.sandbox, "Ably connection failed");
+        emitter.emit(events.error.sandbox, "Realtime connection failed");
       });
 
       // ─── Channel discontinuity detection ──────────────────────────────
@@ -310,8 +329,8 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
         var reason = stateChange.reason;
         var reasonMsg = reason ? (reason.message || reason.code || String(reason)) : '';
 
-        if (current === 'attached' && stateChange.resumed === false && previous) {
-          logger.warn('[ably] Channel DISCONTINUITY detected (resumed=false)' + (reasonMsg ? ' — ' + reasonMsg : ''));
+        if (current === 'attached' && stateChange.resumed === false && previous === 'attached') {
+          logger.debug('[realtime] Channel DISCONTINUITY detected (resumed=false)' + (reasonMsg ? ' — ' + reasonMsg : ''));
           emitter.emit(events.sandbox.progress, {
             step: 'discontinuity',
             message: 'Recovering missed messages after connection interruption...',
@@ -338,7 +357,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
         var entry = subs[i];
         if (!entry.sub) continue;
         try {
-          logger.log('[ably] Discontinuity recovery: fetching historyBeforeSubscribe for ' + entry.name + '...');
+          logger.debug('[realtime] Discontinuity recovery: fetching historyBeforeSubscribe for ' + entry.name + '...');
           var page = await entry.sub.historyBeforeSubscribe({ limit: 100 });
           var recovered = 0;
           while (page) {
@@ -348,25 +367,25 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
               recovered++;
               try {
                 if (entry.handler) {
-                  logger.log('[ably] Replaying recovered ' + entry.name + ' message (requestId=' + (page.items[j].data && page.items[j].data.requestId || 'none') + ')');
+                  logger.debug('[realtime] Replaying recovered ' + entry.name + ' message (requestId=' + (page.items[j].data && page.items[j].data.requestId || 'none') + ')');
                   entry.handler(page.items[j]);
                 }
               } catch (replayErr) {
-                logger.error('[ably] Error replaying recovered message: ' + (replayErr.message || replayErr));
+                logger.debug('[realtime] Error replaying recovered message: ' + (replayErr.message || replayErr));
               }
             }
             page = page.hasNext() ? await page.next() : null;
           }
           totalRecovered += recovered;
-          logger.log('[ably] Discontinuity recovery: replayed ' + recovered + ' ' + entry.name + ' message(s) from gap');
+          logger.debug('[realtime] Discontinuity recovery: replayed ' + recovered + ' ' + entry.name + ' message(s) from gap');
         } catch (err) {
-          logger.error('[ably] Discontinuity recovery failed for ' + entry.name + ': ' + (err.message || err));
+          logger.debug('[realtime] Discontinuity recovery failed for ' + entry.name + ': ' + (err.message || err));
         }
       }
       if (totalRecovered > 0) {
-        logger.warn('[ably] Recovered and replayed ' + totalRecovered + ' message(s) that were missed during connection interruption');
+        logger.debug('[realtime] Recovered and replayed ' + totalRecovered + ' message(s) that were missed during connection interruption');
       } else {
-        logger.log('[ably] Discontinuity recovery: no missed messages found');
+        logger.debug('[realtime] Discontinuity recovery: no missed messages found');
       }
     }
 
@@ -474,6 +493,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
         body.ci = message.ci;
         if (message.ami) body.ami = message.ami;
         if (message.instanceType) body.instanceType = message.instanceType;
+        if (message.e2bTemplateId) body.e2bTemplateId = message.e2bTemplateId;
         if (message.keepAlive !== undefined) body.keepAlive = message.keepAlive;
       }
 
@@ -517,34 +537,40 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       }
 
       if (message.type === "create") {
-        // E2B (Linux) sandboxes: the API proxies commands and returns a url directly.
-        // No runner agent involved — skip runner.ready wait.
-        if (reply.url) {
-          logger.log(`E2B sandbox ready — url=${reply.url}`);
-          return {
-            success: true,
-            sandbox: {
-              sandboxId: reply.sandboxId,
-              instanceId: reply.sandbox?.sandboxId || reply.sandboxId,
-              os: body.os || 'linux',
-              url: reply.url,
-            },
-          };
-        }
-
+        // E2B (Linux) sandboxes return a url directly.
+        // We still need to wait for runner.ready since sandbox-agent.js runs inside E2B.
+        const isE2B = !!reply.url;
+        
         const runnerIp = reply.runner && reply.runner.ip;
         const noVncPort = reply.runner && reply.runner.noVncPort;
         const runnerVncUrl = reply.runner && reply.runner.vncUrl;
 
-        logger.log(`Runner claimed — ip=${runnerIp || 'none'}, os=${reply.runner?.os || 'unknown'}, noVncPort=${noVncPort || 'not reported'}, vncUrl=${runnerVncUrl || 'not reported'}`);
+        // Log image version info (AMI for Windows, E2B template for Linux)
+        if (reply.imageVersion) {
+          if (isE2B) {
+            logger.log('E2B image version: v' + reply.imageVersion + (reply.e2bTemplateId ? ' (template: ' + reply.e2bTemplateId + ')' : ''));
+          } else {
+            logger.log('AMI image version: v' + reply.imageVersion + (reply.amiId ? ' (ami: ' + reply.amiId + ')' : ''));
+          }
+        }
+
+        if (!isE2B) {
+          logger.log(`Runner claimed — ip=${runnerIp || 'none'}, os=${reply.runner?.os || 'unknown'}, noVncPort=${noVncPort || 'not reported'}, vncUrl=${runnerVncUrl || 'not reported'}`);
+        }
 
-        // For cloud Windows sandboxes (no runner in reply), wait for the
-        // agent to signal readiness before sending commands.  Without this
-        // gate, commands published before the agent subscribes are lost.
+        // Wait for the runner agent to signal readiness before sending commands.
+        // Without this gate, commands published before the agent subscribes are lost.
+        // This applies to:
+        //   - E2B Linux sandboxes (native runner agent via sandbox-agent.js)
+        //   - Windows EC2 sandboxes without presence runners
+        // For presence-based Windows runners (reply.runner already set), the runner
+        // is already listening so we can skip the wait.
         var self = this;
-        if (!reply.runner && this._sessionChannel) {
+        const needsReadyWait = this._sessionChannel && (isE2B || !reply.runner);
+        if (needsReadyWait) {
           logger.log('Waiting for runner agent to signal readiness...');
-          var readyTimeout = 120000; // 120s — allows for EC2 boot + agent startup
+          // E2B (Linux) sandboxes need extra time: S3 upload + npm install can add 60-120s on top of sandbox boot
+          var readyTimeout = isE2B ? 300000 : 120000; // 5 min for E2B (S3+npm), 2 min for EC2
           await new Promise(function (resolve, reject) {
             var resolved = false;
             function finish(data) {
@@ -557,7 +583,18 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
               if (data && data.os && reply.runner) reply.runner.os = data.os;
               if (data && data.ip && reply.runner) reply.runner.ip = data.ip;
               if (data && data.runnerVersion && reply.runner) reply.runner.version = data.runnerVersion;
+              // Persist version metadata for test result reporting
+              self._runnerVersionBefore = reply.imageVersion || null;
+              self._runnerVersionAfter = (data && data.runnerVersion) || reply.imageVersion || null;
+              self._wasUpdated = !!(data && data.runnerVersion && reply.imageVersion && data.runnerVersion !== reply.imageVersion);
               logger.log('Runner agent ready (os=' + ((data && data.os) || 'unknown') + ', runner v' + ((data && data.runnerVersion) || 'unknown') + ')');
+              // Show upgrade info: if the runner's npm version differs from the baked image version,
+              // the runner was upgraded during provisioning.
+              var runnerVer = data && data.runnerVersion;
+              var imageVer = reply.imageVersion;
+              if (runnerVer && imageVer && runnerVer !== imageVer) {
+                logger.log('Runner upgraded during provisioning: v' + imageVer + ' \u2192 v' + runnerVer);
+              }
               if (data && data.update) {
                 var u = data.update;
                 if (u.status === 'up-to-date') {
@@ -622,9 +659,13 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
           });
         }
         // Prefer the full vncUrl reported by the runner (infrastructure-agnostic).
+        // For E2B sandboxes, use the url from the API reply.
         // Fall back to constructing from ip + noVncPort for older runners.
         let url;
-        if (runnerVncUrl) {
+        if (isE2B && reply.url) {
+          url = reply.url;
+          logger.log(`E2B sandbox ready — url=${url}`);
+        } else if (runnerVncUrl) {
           url = runnerVncUrl;
           logger.log(`Using runner-provided vncUrl: ${url}`);
         } else if (runnerIp && noVncPort) {
@@ -646,6 +687,15 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
             url: url,
             vncPort: noVncPort || undefined,
             runner: reply.runner,
+            // Extra metadata for test result reporting
+            amiId: reply.amiId || null,
+            e2bTemplateId: reply.e2bTemplateId || null,
+            imageVersion: reply.imageVersion || null,
+            runnerVersionBefore: this._runnerVersionBefore || reply.imageVersion || null,
+            runnerVersionAfter: this._runnerVersionAfter || reply.runner?.version || null,
+            wasUpdated: this._wasUpdated || false,
+            vncUrl: url || null,
+            channelName: this._channelName || null,
           },
         };
       }
@@ -793,7 +843,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
             function onFailed() {
               clearTimeout(timer);
               self._ably.connection.off("connected", onConnected);
-              reject(new Error("Ably connection failed while waiting to send"));
+              reject(new Error("Realtime connection failed while waiting to send"));
             }
             self._ably.connection.once("connected", onConnected);
             self._ably.connection.once("failed", onFailed);
@@ -865,7 +915,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
             return rid + '(' + (e && e.message ? e.message.type : '?') + ', ' + age + ')';
           }).join(', ');
           logger.error(
-            '[ably] Promise TIMEOUT: requestId=' + requestId +
+            '[realtime] Promise TIMEOUT: requestId=' + requestId +
             ' | type=' + message.type +
             ' | timeout=' + timeout + 'ms' +
             ' | all pending: [' + pendingSummary + ']'
@@ -914,7 +964,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
           timeoutId = setTimeout(timeoutFn, newRemaining);
           if (timeoutId.unref) timeoutId.unref();
           logger.log(
-            '[ably] Extended timeout for requestId=' + requestId +
+            '[realtime] Extended timeout for requestId=' + requestId +
             ' by ' + disconnectionDurationMs + 'ms (new remaining: ' + Math.round(newRemaining / 1000) + 's)'
           );
         },
@@ -986,7 +1036,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       }
 
       return channel.publish(eventName, message).then(function () {
-        logger.log(`[ably] Published: channel=${channel.name.split(':').pop()}, event=${eventName}, type=${message.type || 'unknown'} (requestId=${message.requestId || 'none'})`);
+        logger.debug(`[realtime] Published: channel=${channel.name.split(':').pop()}, event=${eventName}, type=${message.type || 'unknown'} (requestId=${message.requestId || 'none'})`);
       });
     }
 
@@ -1116,7 +1166,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       // Send end-session control message to runner before disconnecting
       if (this._sessionChannel && this._ably?.connection?.state === 'connected') {
         try {
-          logger.log('[ably] Publishing control: type=end-session');
+          logger.debug('[realtime] Publishing control: type=end-session');
           await this._sessionChannel.publish('control', { type: 'end-session' });
         } catch (e) {
           // Ignore - best effort
@@ -1126,7 +1176,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       // Leave presence on session channel
       if (this._sessionChannel) {
         try {
-          logger.log('[ably] Leaving presence on session channel');
+          logger.debug('[realtime] Leaving presence on session channel');
           await this._sessionChannel.presence.leave();
         } catch (e) {
           // ignore - best effort, Ably will auto-leave on disconnect
@@ -1134,7 +1184,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       }
 
       try {
-        logger.log('[ably] Detaching session channel');
+        logger.debug('[realtime] Detaching session channel');
         if (this._sessionChannel) {
           await this._sessionChannel.detach();
         }
@@ -1144,7 +1194,7 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
 
       if (this._ably) {
         try {
-          logger.log('[ably] Closing Ably connection');
+          logger.debug('[realtime] Closing Realtime connection');
           this._ably.close();
         } catch (e) {
           /* ignore */

package/ai/skills/testdriver-find/SKILL.md

@@ -49,8 +49,8 @@ const element = await testdriver.find(description, options)
       - `"any"` — No wrapping, uses the description as-is (default behavior)
     </ParamField>
     
-    <ParamField path="zoom" type="boolean" default={false}>
-      Enable two-phase zoom mode for better precision in crowded UIs with many similar elements.
+    <ParamField path="zoom" type="boolean" default={true}>
+      Two-phase zoom mode for better precision in crowded UIs with many similar elements. Enabled by default.
     </ParamField>
     
     <ParamField path="ai" type="object">
@@ -332,14 +332,19 @@ The `timeout` option:
 - Returns the element (check `element.found()` if not throwing on failure)
 - Set to `0` to disable polling and make a single attempt
 
-## Zoom Mode for Crowded UIs
+## Zoom Mode
 
-When dealing with many similar icons or elements clustered together (like browser toolbars), enable `zoom` mode for better precision:
+Zoom mode is **enabled by default**. It uses a two-phase approach for better precision when locating elements, especially in crowded UIs with many similar elements.
+
+To disable zoom for a specific find call, pass `zoom: false`:
 
 ```javascript
-// Enable zoom for better precision in crowded UIs
-const extensionsBtn = await testdriver.find('extensions puzzle icon in Chrome toolbar', { zoom: true });
+// Zoom is on by default — no option needed
+const extensionsBtn = await testdriver.find('extensions puzzle icon in Chrome toolbar');
 await extensionsBtn.click();
+
+// Disable zoom for a specific call if needed
+const largeButton = await testdriver.find('big hero button', { zoom: false });
 ```
 
 ### How Zoom Mode Works
@@ -352,22 +357,11 @@ await extensionsBtn.click();
 This two-phase approach gives the AI a higher-resolution view of the target area, improving accuracy when multiple similar elements are close together.
 
 <Tip>
-  Use `zoom: true` when:
-  - Clicking small icons in toolbars
-  - Selecting from a grid of similar items
-  - Targeting elements in dense UI areas
-  - The default locate is clicking the wrong similar element
-  - You get an AI verification rejection like "The crosshair is located in the empty space of the browser's tab bar/title bar area" — this means the initial locate was imprecise and zoom will help the AI pinpoint the correct element
+  You may want to disable zoom with `zoom: false` when:
+  - Targeting large, isolated elements where the extra precision isn't needed
+  - You want to speed up find calls in simple UIs
 </Tip>
 
-```javascript
-// Without zoom - may click wrong icon in toolbar
-const icon = await testdriver.find('settings icon');
-
-// With zoom - better precision for crowded areas
-const icon = await testdriver.find('settings icon', { zoom: true });
-```
-
 ## Cache Options
 
 Control caching behavior to optimize performance, especially when using dynamic variables in prompts.