testdriverai 7.2.75 → 7.2.77

package/agent/lib/redraw.js

@@ -8,6 +8,7 @@ const DEFAULT_REDRAW_OPTIONS = {
   enabled: true,           // Master switch to enable/disable redraw detection
   screenRedraw: true,      // Enable screen redraw detection
   networkMonitor: true,    // Enable network activity monitoring
+  noChangeTimeoutMs: 1500, // Exit early if no screen change detected after this time
 };
 
 // Factory function that creates redraw functionality with the provided system instance
@@ -235,7 +236,7 @@ const createRedraw = (
   }
 
   async function checkCondition(resolve, startTime, timeoutMs, options) {
-    const { enabled, screenRedraw, networkMonitor } = options;
+    const { enabled, screenRedraw, networkMonitor, noChangeTimeoutMs = 1500 } = options;
     
     // If redraw is disabled, resolve immediately
     if (!enabled) {
@@ -248,6 +249,9 @@ const createRedraw = (
     let diffFromInitial = 0;
     let diffFromLast = 0;
     let isTimeout = timeElapsed > timeoutMs;
+    
+    // Early exit: if no screen change detected after noChangeTimeoutMs, assume action had no visual effect
+    const noChangeTimeout = screenRedraw && !hasChangedFromInitial && timeElapsed > noChangeTimeoutMs;
 
     // Screen stability detection:
     // 1. Check if screen has changed from initial (detect transition)
@@ -276,8 +280,14 @@ const createRedraw = (
       lastScreenImage = nowImage;
     }
     
-    // Screen is settled when: it has changed from initial AND consecutive frames are now stable
-    const screenSettled = hasChangedFromInitial && consecutiveFramesStable;
+    // Screen is settled when:
+    // 1. It has changed from initial AND consecutive frames are now stable, OR
+    // 2. No change was detected after noChangeTimeoutMs (action had no visual effect)
+    const screenSettled = (hasChangedFromInitial && consecutiveFramesStable) || noChangeTimeout;
+    
+    if (noChangeTimeout && !hasChangedFromInitial) {
+      emitter.emit(events.log.debug, `[redraw] No screen change detected after ${noChangeTimeoutMs}ms, settling early`);
+    }
     
     // If screen redraw is disabled, consider it as "settled"
     const effectiveScreenSettled = screenRedraw ? screenSettled : true;
@@ -334,12 +344,13 @@ const createRedraw = (
         networkSettled: effectiveNetworkSettled,
         isTimeout,
         timeElapsed,
+        noChangeTimeout,
       });
       resolve("true");
     } else {
       setTimeout(() => {
         checkCondition(resolve, startTime, timeoutMs, options);
-      }, 500);
+      }, 250);
     }
   }
 

package/ai/agents/testdriver.md

@@ -1,7 +1,7 @@
 ---
 name: testdriver
 description: An expert at creating and refining automated tests using TestDriver.ai
-tools:
+tools: ["*"]
 mcp-servers:
   testdriver:
     command: npx
@@ -11,6 +11,7 @@ mcp-servers:
       - testdriverai-mcp
     env:
       TD_API_KEY: ${TD_API_KEY}
+    tools: ["testdriverai"]
 ---
 
 # TestDriver Expert
@@ -43,7 +44,7 @@ Use this agent when the user asks to:
 4. **⚠️ WRITE CODE IMMEDIATELY**: After EVERY successful action, append the generated code to the test file RIGHT AWAY. Do NOT wait until the end.
 5. **Verify Actions**: Use `check` after actions to verify they succeeded (for YOUR understanding only).
 6. **Add Assertions**: Use `assert` for test conditions that should be in the final test file.
-7. **⚠️ RUN THE TEST YOURSELF**: Use `npx vitest run <testFile>` to run the test - do NOT tell the user to run it. Iterate until it passes.
+7. **⚠️ RUN THE TEST YOURSELF**: Use `npx vitest run <testFile> --reporter=dot` to run the test - do NOT tell the user to run it. Iterate until it passes.
 
 ## Prerequisites
 
@@ -293,11 +294,15 @@ assert({ assertion: "the dashboard is visible" })
 **⚠️ YOU must run the test - do NOT tell the user to run it:**
 
 ```bash
-npx vitest run tests/login.test.mjs
+npx vitest run tests/login.test.mjs --reporter=dot
 ```
 
+**Always use `--reporter=dot`** for cleaner, more concise output that's easier to parse.
+
 Analyze the output, fix any issues, and iterate until the test passes.
 
+**⚠️ ALWAYS share the test report link with the user.** After each test run, look for the "View Report" URL in the test output (e.g., `https://app.testdriver.ai/projects/.../reports/...`) and share it with the user so they can review the recording and results.
+
 ### MCP Tools Reference
 
 | Tool | Description |
@@ -462,16 +467,17 @@ const result = await testdriver.assert("dashboard is visible");
 ## Tips for Agents
 
 1. **⚠️ WRITE CODE IMMEDIATELY** - After EVERY successful MCP action, append the generated code to the test file RIGHT AWAY. Do NOT wait until the session ends.
-2. **⚠️ RUN TESTS YOURSELF** - Do NOT tell the user to run tests. YOU must run the tests using `npx vitest run <testFile>`. Analyze the output and iterate until the test passes.
+2. **⚠️ RUN TESTS YOURSELF** - Do NOT tell the user to run tests. YOU must run the tests using `npx vitest run <testFile> --reporter=dot`. Always use `--reporter=dot` for cleaner output. Analyze the output and iterate until the test passes. **Always share the test report link** (e.g., `https://app.testdriver.ai/projects/.../reports/...`) with the user after each run.
 3. **⚠️ ADD SCREENSHOTS LIBERALLY** - Include `await testdriver.screenshot()` throughout your tests: after provision, before/after clicks, after typing, and before assertions. This creates a visual trail that makes debugging failures much easier.
-4. **Use MCP tools for development** - Build tests interactively with visual feedback
-5. **Always check `sdk.d.ts`** for method signatures and types when debugging generated tests
-6. **Look at test samples** in `node_modules/testdriverai/test` for working examples
-7. **Use `check` to understand screen state** - This is how you verify what the sandbox shows during MCP development.
-8. **Use `check` after actions, `assert` for test files** - `check` gives detailed AI analysis (no code), `assert` gives boolean pass/fail (generates code)
-9. **Be specific with element descriptions** - "blue Sign In button in the header" > "button"
-10. **Start simple** - get one step working before adding more
-11. **Always `await` async methods** - TestDriver will warn if you forget, but for TypeScript projects, add `@typescript-eslint/no-floating-promises` to your ESLint config to catch missing `await` at compile time:
+4. **⚠️ NEVER USE `.wait()`** - Do NOT use any `.wait()` method. Instead, use `find()` with a `timeout` option to poll for elements, or use `assert()` / `check()` to verify state. Explicit waits are flaky and slow.
+5. **Use MCP tools for development** - Build tests interactively with visual feedback
+6. **Always check `sdk.d.ts`** for method signatures and types when debugging generated tests
+7. **Look at test samples** in `node_modules/testdriverai/test` for working examples
+8. **Use `check` to understand screen state** - This is how you verify what the sandbox shows during MCP development.
+9. **Use `check` after actions, `assert` for test files** - `check` gives detailed AI analysis (no code), `assert` gives boolean pass/fail (generates code)
+10. **Be specific with element descriptions** - "blue Sign In button in the header" > "button"
+11. **Start simple** - get one step working before adding more
+12. **Always `await` async methods** - TestDriver will warn if you forget, but for TypeScript projects, add `@typescript-eslint/no-floating-promises` to your ESLint config to catch missing `await` at compile time:
 
    ```json
    // eslint.config.js (for TypeScript projects)

package/interfaces/cli/commands/init.js

@@ -485,12 +485,20 @@ jobs:
 
     if (!fs.existsSync(mcpConfigFile)) {
       const mcpConfig = {
+        inputs: [
+          {
+            type: "promptString",
+            id: "testdriver-api-key",
+            description: "TestDriver API Key From https://console.testdriver.ai/team",
+            password: true,
+          },
+        ],
         servers: {
           testdriver: {
             command: "npx",
             args: ["-p", "testdriverai@beta", "testdriverai-mcp"],
             env: {
-              TD_API_KEY: "${TD_API_KEY}",
+              TD_API_KEY: "${input:testdriver-api-key}",
             },
           },
         },

package/mcp-server/dist/server.mjs

@@ -41,6 +41,7 @@ if (isSentryEnabled()) {
         release: `testdriverai-mcp@${version}`,
         sampleRate: 1.0,
         tracesSampleRate: 1.0,
+        sendDefaultPii: true,
         integrations: [Sentry.httpIntegration(), Sentry.nodeContextIntegration()],
         initialScope: {
             tags: {
@@ -265,11 +266,16 @@ function createToolResult(success, textContent, structuredData, generatedCode) {
         },
     };
 }
-// Create MCP server
-const server = new McpServer({
-    name: "testdriver",
-    version: "1.0.0",
-});
+// Create MCP server wrapped with Sentry for automatic tracing
+const server = isSentryEnabled()
+    ? Sentry.wrapMcpServerWithSentry(new McpServer({
+        name: "testdriver",
+        version: version,
+    }))
+    : new McpServer({
+        name: "testdriver",
+        version: version,
+    });
 // Element reference storage (for click/hover after find)
 // Stores actual Element instances - no raw coordinates as input
 const elementRefs = new Map();
@@ -1341,6 +1347,198 @@ server.registerTool("exec", {
         throw error;
     }
 });
+// List Local Screenshots - lists screenshots saved to .testdriver directory
+server.registerTool("list_local_screenshots", {
+    description: `List screenshots saved in the .testdriver directory.
+
+This tool helps you find screenshots that have been saved during test runs or via the screenshot tool.
+Screenshots are organized in subdirectories like 'mcp-screenshots' and 'screenshots'.
+
+Returns a list of screenshot paths that can be viewed with the 'view_local_screenshot' tool.`,
+    inputSchema: z.object({
+        directory: z.string().optional().describe("Subdirectory to list (e.g., 'mcp-screenshots', 'screenshots'). If not provided, lists all subdirectories."),
+    }),
+}, async (params) => {
+    const startTime = Date.now();
+    logger.info("list_local_screenshots: Starting", { directory: params.directory });
+    try {
+        // Find .testdriver directory - check current working directory and common locations
+        const possiblePaths = [
+            path.join(process.cwd(), ".testdriver"),
+            path.join(os.homedir(), ".testdriver"),
+        ];
+        let testdriverDir = null;
+        for (const p of possiblePaths) {
+            if (fs.existsSync(p)) {
+                testdriverDir = p;
+                break;
+            }
+        }
+        if (!testdriverDir) {
+            logger.warn("list_local_screenshots: .testdriver directory not found");
+            return createToolResult(false, "No .testdriver directory found. Screenshots are saved here during test runs.", { error: "Directory not found" });
+        }
+        const screenshots = [];
+        // Function to recursively find PNG files
+        const findPngFiles = (dir) => {
+            if (!fs.existsSync(dir))
+                return;
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    // If a specific directory was requested, only search that one
+                    if (!params.directory || entry.name === params.directory || dir !== testdriverDir) {
+                        findPngFiles(fullPath);
+                    }
+                }
+                else if (entry.isFile() && entry.name.toLowerCase().endsWith(".png")) {
+                    const stats = fs.statSync(fullPath);
+                    screenshots.push({
+                        path: fullPath,
+                        name: entry.name,
+                        modified: stats.mtime,
+                        size: stats.size,
+                    });
+                }
+            }
+        };
+        findPngFiles(testdriverDir);
+        // Sort by modification time (newest first)
+        screenshots.sort((a, b) => b.modified.getTime() - a.modified.getTime());
+        const duration = Date.now() - startTime;
+        logger.info("list_local_screenshots: Completed", { count: screenshots.length, duration });
+        if (screenshots.length === 0) {
+            return createToolResult(true, "No screenshots found in .testdriver directory.", {
+                action: "list_local_screenshots",
+                count: 0,
+                directory: testdriverDir,
+                duration
+            });
+        }
+        // Format the list for display
+        const screenshotList = screenshots.slice(0, 50).map((s, i) => {
+            const relativePath = path.relative(testdriverDir, s.path);
+            const sizeKB = Math.round(s.size / 1024);
+            const timeAgo = formatTimeAgo(s.modified);
+            return `${i + 1}. ${relativePath} (${sizeKB}KB, ${timeAgo})`;
+        }).join("\n");
+        const message = screenshots.length > 50
+            ? `Found ${screenshots.length} screenshots (showing 50 most recent):\n\n${screenshotList}`
+            : `Found ${screenshots.length} screenshot(s):\n\n${screenshotList}`;
+        return createToolResult(true, message, {
+            action: "list_local_screenshots",
+            count: screenshots.length,
+            directory: testdriverDir,
+            screenshots: screenshots.slice(0, 50).map(s => ({
+                path: s.path,
+                relativePath: path.relative(testdriverDir, s.path),
+                name: s.name,
+                modified: s.modified.toISOString(),
+                sizeBytes: s.size,
+            })),
+            duration
+        });
+    }
+    catch (error) {
+        logger.error("list_local_screenshots: Failed", { error: String(error) });
+        captureException(error, { tags: { tool: "list_local_screenshots" } });
+        throw error;
+    }
+});
+// Helper to format time ago
+function formatTimeAgo(date) {
+    const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
+// View Local Screenshot - view a screenshot from .testdriver directory
+// Returns the image so AI clients that support images can see it
+// Also displays to the user via MCP App
+registerAppTool(server, "view_local_screenshot", {
+    title: "View Local Screenshot",
+    description: `View a screenshot from the .testdriver directory.
+
+Use 'list_local_screenshots' first to see available screenshots, then use this tool to view one.
+
+This tool returns the image content so AI clients that support images can see it directly.
+The image is also displayed to the user via the MCP App UI.
+
+Useful for:
+- Reviewing screenshots from previous test runs
+- Debugging test failures by examining saved screenshots
+- Comparing current screen state to saved screenshots`,
+    inputSchema: z.object({
+        path: z.string().describe("Full path to the screenshot file (from list_local_screenshots)"),
+    }),
+    _meta: { ui: { resourceUri: RESOURCE_URI, expanded: true } },
+}, async (params) => {
+    const startTime = Date.now();
+    logger.info("view_local_screenshot: Starting", { path: params.path });
+    try {
+        // Validate the path exists and is a PNG
+        if (!fs.existsSync(params.path)) {
+            logger.warn("view_local_screenshot: File not found", { path: params.path });
+            return createToolResult(false, `Screenshot not found: ${params.path}`, { error: "File not found" });
+        }
+        if (!params.path.toLowerCase().endsWith(".png")) {
+            logger.warn("view_local_screenshot: Not a PNG file", { path: params.path });
+            return createToolResult(false, "Only PNG files are supported", { error: "Invalid file type" });
+        }
+        // Security check - only allow files from .testdriver directory
+        const normalizedPath = path.resolve(params.path);
+        if (!normalizedPath.includes(".testdriver")) {
+            logger.warn("view_local_screenshot: Path not in .testdriver", { path: normalizedPath });
+            return createToolResult(false, "Can only view screenshots from .testdriver directory", { error: "Security: path not allowed" });
+        }
+        // Read the file
+        const imageBuffer = fs.readFileSync(params.path);
+        const imageBase64 = imageBuffer.toString("base64");
+        // Store image for MCP App UI display
+        const screenshotResourceUri = storeImage(imageBase64, "screenshot");
+        const stats = fs.statSync(params.path);
+        const sizeKB = Math.round(stats.size / 1024);
+        const fileName = path.basename(params.path);
+        const duration = Date.now() - startTime;
+        logger.info("view_local_screenshot: Completed", { path: params.path, sizeKB, duration });
+        // Return the image content for AI clients that support images
+        // The content array includes both text and image for maximum compatibility
+        const content = [
+            { type: "text", text: `Screenshot: ${fileName} (${sizeKB}KB)` },
+            {
+                type: "image",
+                data: imageBase64,
+                mimeType: "image/png"
+            },
+        ];
+        return {
+            content,
+            structuredContent: {
+                action: "view_local_screenshot",
+                success: true,
+                path: params.path,
+                fileName,
+                sizeBytes: stats.size,
+                modified: stats.mtime.toISOString(),
+                screenshotResourceUri,
+                duration
+            },
+        };
+    }
+    catch (error) {
+        logger.error("view_local_screenshot: Failed", { error: String(error), path: params.path });
+        captureException(error, { tags: { tool: "view_local_screenshot" }, extra: { path: params.path } });
+        throw error;
+    }
+});
 // Screenshot - captures full screen to show user the current state
 // NOTE: This is for SHOWING the user the screen, not for AI understanding.
 // Use 'check' tool for AI to understand screen state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.2.75",
+  "version": "7.2.77",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",

package/sdk.d.ts

@@ -879,10 +879,14 @@ export default class TestDriverSDK {
    * const client = new TestDriver();
    * 
    * @example
+   * // Pass options only (API key from .env)
+   * const client = new TestDriver({ os: 'windows' });
+   * 
+   * @example
    * // Or pass API key explicitly
    * const client = new TestDriver('your-api-key');
    */
-  constructor(apiKey?: string, options?: TestDriverOptions);
+  constructor(apiKey?: string | TestDriverOptions, options?: TestDriverOptions);
 
   /**
    * Whether the SDK is currently connected to a sandbox

package/sdk.js

@@ -3,7 +3,6 @@ const path = require("path");
 const os = require("os");
 const crypto = require("crypto");
 const { formatter } = require("./sdk-log-formatter");
-const logger = require("./agent/lib/logger");
 
 // Load .env file into process.env by default
 require("dotenv").config();
@@ -1245,16 +1244,15 @@ function createChainablePromise(promise) {
  * const client = new TestDriver();
  * await client.connect();
  *
+ * // Pass options only (API key from .env)
+ * const client = new TestDriver({ os: 'windows' });
+ *
  * // Or pass API key explicitly
  * const client = new TestDriver('your-api-key');
  *
  * // New API
  * const element = await client.find('Submit button');
  * await element.click();
- *
- * // Legacy API (deprecated)
- * await client.hoverText('Submit');
- * await client.click();
  */
 
 /**
@@ -1524,7 +1522,64 @@ class TestDriverSDK {
           await this._dashcam.addWebLog("**", "Web Logs");
         }
 
+        // Set up Chrome profile with preferences
         const shell = this.os === "windows" ? "pwsh" : "sh";
+        const userDataDir =
+          this.os === "windows"
+            ? "C:\\Users\\testdriver\\AppData\\Local\\TestDriver\\Chrome"
+            : "/tmp/testdriver-chrome-profile";
+
+        // Create user data directory and Default profile directory
+        const defaultProfileDir =
+          this.os === "windows"
+            ? `${userDataDir}\\Default`
+            : `${userDataDir}/Default`;
+
+        const createDirCmd =
+          this.os === "windows"
+            ? `New-Item -ItemType Directory -Path "${defaultProfileDir}" -Force | Out-Null`
+            : `mkdir -p "${defaultProfileDir}"`;
+
+        await this.exec(shell, createDirCmd, 60000, true);
+
+        // Write Chrome preferences
+        const chromePrefs = {
+          credentials_enable_service: false,
+          profile: {
+            password_manager_enabled: false,
+            default_content_setting_values: {},
+          },
+          signin: {
+            allowed: false,
+          },
+          sync: {
+            requested: false,
+            first_setup_complete: true,
+            sync_all_os_types: false,
+          },
+          autofill: {
+            enabled: false,
+          },
+          local_state: {
+            browser: {
+              has_seen_welcome_page: true,
+            },
+          },
+        };
+
+        const prefsPath =
+          this.os === "windows"
+            ? `${defaultProfileDir}\\Preferences`
+            : `${defaultProfileDir}/Preferences`;
+
+        const prefsJson = JSON.stringify(chromePrefs, null, 2);
+        const writePrefCmd =
+          this.os === "windows"
+            ? // Use compact JSON and [System.IO.File]::WriteAllText to avoid Set-Content hanging issues
+              `[System.IO.File]::WriteAllText("${prefsPath}", '${JSON.stringify(chromePrefs).replace(/'/g, "''")}')`
+            : `cat > "${prefsPath}" << 'EOF'\n${prefsJson}\nEOF`;
+
+        await this.exec(shell, writePrefCmd, 60000, true);
 
         // Build Chrome launch command
         const chromeArgs = [];
@@ -1536,6 +1591,7 @@ class TestDriverSDK {
           "--no-first-run",
           "--no-experiments",
           "--disable-infobars",
+          `--user-data-dir=${userDataDir}`,
         );
 
         // Add remote debugging port for captcha solving support
@@ -1748,6 +1804,64 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           await this._dashcam.addWebLog("**", "Web Logs");
         }
 
+        // Set up Chrome profile with preferences
+        const userDataDir =
+          this.os === "windows"
+            ? "C:\\Users\\testdriver\\AppData\\Local\\TestDriver\\Chrome"
+            : "/tmp/testdriver-chrome-profile";
+
+        // Create user data directory and Default profile directory
+        const defaultProfileDir =
+          this.os === "windows"
+            ? `${userDataDir}\\Default`
+            : `${userDataDir}/Default`;
+
+        const createDirCmd =
+          this.os === "windows"
+            ? `New-Item -ItemType Directory -Path "${defaultProfileDir}" -Force | Out-Null`
+            : `mkdir -p "${defaultProfileDir}"`;
+
+        await this.exec(shell, createDirCmd, 60000, true);
+
+        // Write Chrome preferences
+        const chromePrefs = {
+          credentials_enable_service: false,
+          profile: {
+            password_manager_enabled: false,
+            default_content_setting_values: {},
+          },
+          signin: {
+            allowed: false,
+          },
+          sync: {
+            requested: false,
+            first_setup_complete: true,
+            sync_all_os_types: false,
+          },
+          autofill: {
+            enabled: false,
+          },
+          local_state: {
+            browser: {
+              has_seen_welcome_page: true,
+            },
+          },
+        };
+
+        const prefsPath =
+          this.os === "windows"
+            ? `${defaultProfileDir}\\Preferences`
+            : `${defaultProfileDir}/Preferences`;
+
+        const prefsJson = JSON.stringify(chromePrefs, null, 2);
+        const writePrefCmd =
+          this.os === "windows"
+            ? // Use compact JSON and [System.IO.File]::WriteAllText to avoid Set-Content hanging issues
+              `[System.IO.File]::WriteAllText("${prefsPath}", '${JSON.stringify(chromePrefs).replace(/'/g, "''")}')`
+            : `cat > "${prefsPath}" << 'EOF'\n${prefsJson}\nEOF`;
+
+        await this.exec(shell, writePrefCmd, 60000, true);
+
         // Build Chrome launch command
         const chromeArgs = [];
         if (maximized) chromeArgs.push("--start-maximized");
@@ -1758,6 +1872,7 @@ with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
           "--no-experiments",
           "--disable-infobars",
           "--disable-features=ChromeLabs",
+          `--user-data-dir=${userDataDir}`,
         );
 
         // Add remote debugging port for captcha solving support
@@ -3452,28 +3567,28 @@ CAPTCHA_SOLVER_EOF`,
    *
    * @example
    * // Simple execution
-   * const result = await client.ai('Click the submit button');
+   * const result = await client.act('Click the submit button');
    * console.log(result.success); // true
    *
    * @example
    * // With custom retry limit
-   * const result = await client.ai('Fill out the contact form', { tries: 10 });
+   * const result = await client.act('Fill out the contact form', { tries: 10 });
    * console.log(`Completed in ${result.tries} tries`);
    *
    * @example
    * // Handle failures
    * try {
-   *   await client.ai('Complete the checkout process', { tries: 3 });
+   *   await client.act('Complete the checkout process', { tries: 3 });
    * } catch (error) {
    *   console.log(`Failed after ${error.tries} tries: ${error.message}`);
    * }
    */
-  async ai(task, options = {}) {
+  async act(task, options = {}) {
     this._ensureConnected();
 
     const { tries = 7 } = options;
 
-    this.analytics.track("sdk.ai", { task, tries });
+    this.analytics.track("sdk.act", { task, tries });
 
     const { events } = require("./agent/events.js");
     const startTime = Date.now();
@@ -3482,7 +3597,7 @@ CAPTCHA_SOLVER_EOF`,
     const originalCheckLimit = this.agent.checkLimit;
     this.agent.checkLimit = tries;
 
-    // Reset check count for this ai() call
+    // Reset check count for this act() call
     const originalCheckCount = this.agent.checkCount;
     this.agent.checkCount = 0;
 
@@ -3549,7 +3664,7 @@ CAPTCHA_SOLVER_EOF`,
   }
 
   /**
-   * @deprecated Use ai() instead
+   * @deprecated Use act() instead
    * Execute a natural language task using AI
    *
    * @param {string} task - Natural language description of what to do
@@ -3557,8 +3672,8 @@ CAPTCHA_SOLVER_EOF`,
    * @param {number} [options.tries=7] - Maximum number of check/retry attempts
    * @returns {Promise<ActResult>} Result object with success status and details
    */
-  async act(task, options) {
-    return await this.ai(task, options);
+  async ai(task, options) {
+    return await this.act(task, options);
   }
 }