testdriverai 7.8.0-test.71 → 7.8.0-test.73

package/agent/lib/provision-commands.js

@@ -0,0 +1,176 @@
+// sdk/agent/lib/provision-commands.js
+// Canonical source of truth for sandbox-agent provisioning commands.
+//
+// These pure functions generate platform-specific command arrays for
+// installing/updating the runner, writing agent config, and starting
+// the sandbox agent. They are used by:
+//   - API: _provisionAgentCredentials (Windows SSM)
+//   - API: _createLinuxSandbox (E2B bash)
+//   - API: direct connection handler (returns commands for SDK to execute)
+//   - SDK: _sendSSMCommands (direct connection, client-side SSM)
+//
+// Published as part of the testdriverai npm package.
+
+'use strict';
+
+/**
+ * Build the agent config object written to the sandbox.
+ *
+ * @param {Object} opts
+ * @param {string} opts.sandboxId
+ * @param {string} opts.apiRoot
+ * @param {string} [opts.apiKey]
+ * @param {string} [opts.sentryDsn]
+ * @param {string} [opts.sentryEnvironment]
+ * @param {string} [opts.sentryChannel]
+ * @param {Object} opts.ablyToken - Ably token object
+ * @param {string} opts.channelName - Ably channel name
+ * @returns {Object} Agent config to serialize as JSON
+ */
+function buildAgentConfig({ sandboxId, apiRoot, apiKey, sentryDsn, sentryEnvironment, sentryChannel, ablyToken, channelName }) {
+  return {
+    sandboxId,
+    apiRoot,
+    apiKey: apiKey || undefined,
+    sentryDsn: sentryDsn || undefined,
+    sentryEnvironment: sentryEnvironment || 'production',
+    sentryChannel: sentryChannel || undefined,
+    ably: {
+      token: ablyToken,
+      channel: channelName,
+      // Backward compat for old runners (<=7.5.x) that expect multi-channel format
+      channels: { commands: channelName, responses: channelName, control: channelName, files: channelName },
+    },
+  };
+}
+
+/**
+ * Generate PowerShell commands to provision the sandbox agent on Windows.
+ *
+ * The returned array is suitable for SSM AWS-RunPowerShellScript Parameters.commands.
+ *
+ * @param {Object} opts
+ * @param {string} opts.channel      - Release channel (dev|test|canary|stable)
+ * @param {string} opts.configJson   - JSON.stringify'd agent config
+ * @param {string} opts.sandboxId    - For logging
+ * @param {string} [opts.s3DownloadUrl] - S3 pre-signed URL for dev/test (omit for npm install)
+ * @returns {string[]} Array of PowerShell command strings
+ */
+function windowsProvisionCommands({ channel, configJson, sandboxId, s3DownloadUrl }) {
+  var useS3 = (channel === 'dev' || channel === 'test') && s3DownloadUrl;
+  var commands = [];
+
+  // ── 1. Stop old runner ────────────────────────────────────────────
+  commands.push(
+    "Write-Host 'Stopping old runner...'",
+    'Stop-ScheduledTask -TaskName RunTestDriverAgent -ErrorAction SilentlyContinue',
+    'Stop-Process -Name node -Force -ErrorAction SilentlyContinue',
+    "Remove-Item 'C:\\Windows\\Temp\\testdriver-agent.json' -Force -ErrorAction SilentlyContinue"
+  );
+
+  // ── 2. Install / update runner ────────────────────────────────────
+  commands.push("Set-Location 'C:\\testdriver\\sandbox-agent'");
+
+  var agentScript;
+
+  if (useS3) {
+    // Dev/test: download tarball from S3, extract, npm install deps
+    agentScript = 'sandbox-agent.js';
+    commands.push(
+      "Write-Host 'Downloading runner from S3 (" + channel + ")...'",
+      "$tarball = 'C:\\Windows\\Temp\\runner-dev.tgz'",
+      "Invoke-WebRequest -Uri '" + s3DownloadUrl + "' -OutFile $tarball",
+      "Write-Host 'Extracting runner...'",
+      "tar -xzf $tarball -C 'C:\\Windows\\Temp'",
+      "xcopy 'C:\\Windows\\Temp\\package\\*' 'C:\\testdriver\\sandbox-agent\\' /E /Y /I",
+      "Remove-Item 'C:\\Windows\\Temp\\package' -Recurse -Force -ErrorAction SilentlyContinue",
+      'Remove-Item $tarball -Force -ErrorAction SilentlyContinue',
+      'npm install --omit=dev 2>&1 | Write-Host',
+      "Write-Host 'Runner install complete (s3)'"
+    );
+  } else {
+    // Canary/stable (or dev/test without S3 URL): npm install by dist-tag
+    agentScript = 'node_modules/@testdriverai/runner/sandbox-agent.js';
+    var runnerTag = channel === 'stable' ? 'latest' : channel;
+    commands.push(
+      "Write-Host 'Installing @testdriverai/runner@" + runnerTag + "...'",
+      'npm install @testdriverai/runner@' + runnerTag + ' --omit=dev 2>&1 | Write-Host',
+      "Write-Host 'Runner install complete'"
+    );
+  }
+
+  // ── 3. Regenerate run_testdriver.ps1 ──────────────────────────────
+  // Overwrites the baked-in script so the entry point matches the install layout.
+  // Uses [IO.File]::WriteAllText to avoid PowerShell variable expansion issues.
+  var scriptContent = [
+    "Write-Output 'Starting sandbox agent...'",
+    "Set-Location 'C:\\testdriver\\sandbox-agent'",
+    'while ($true) {',
+    '    & node ' + agentScript + ' 2>&1 | Tee-Object -Append -FilePath C:\\testdriver\\logs\\sandbox-agent.log',
+    "    Write-Output 'Agent exited, restarting in 2 seconds...'",
+    '    Start-Sleep -Seconds 2',
+    '}',
+  ].join('\r\n');
+
+  commands.push(
+    "Write-Host 'Regenerating run_testdriver.ps1...'",
+    "[IO.File]::WriteAllText('C:\\testdriver\\run_testdriver.ps1', '" + scriptContent.replace(/'/g, "''") + "')"
+  );
+
+  // ── 4. Write agent config ─────────────────────────────────────────
+  commands.push(
+    "Write-Host '=== Writing config ==='",
+    "$config = '" + configJson.replace(/'/g, "''") + "'",
+    "[System.IO.File]::WriteAllText('C:\\Windows\\Temp\\testdriver-agent.json', $config)",
+    "Write-Host 'Config written for sandbox " + sandboxId + "'"
+  );
+
+  // ── 5. Start runner ───────────────────────────────────────────────
+  commands.push(
+    'Start-Sleep -Seconds 1',
+    'Start-ScheduledTask -TaskName RunTestDriverAgent',
+    "Write-Host 'Runner started'"
+  );
+
+  return commands;
+}
+
+/**
+ * Generate the bash command to install/update the runner on Linux (E2B).
+ *
+ * @param {Object} opts
+ * @param {string} opts.channel        - Release channel
+ * @param {string} [opts.s3DownloadUrl] - S3 pre-signed URL for dev/test
+ * @param {string} [opts.runnerPath]   - Default '/opt/testdriver-runner'
+ * @returns {string} Single bash command (steps joined with &&)
+ */
+function linuxRunnerInstallCommand({ channel, s3DownloadUrl, runnerPath }) {
+  var rp = runnerPath || '/opt/testdriver-runner';
+  var useS3 = (channel === 'dev' || channel === 'test') && s3DownloadUrl;
+  var runnerTag = channel === 'stable' ? 'latest' : channel;
+
+  if (useS3) {
+    return [
+      'sudo rm -rf ' + rp,
+      'sudo mkdir -p ' + rp,
+      'sudo chown -R user:user ' + rp,
+      "curl -sL '" + s3DownloadUrl + "' -o /tmp/runner.tgz",
+      'tar -xzf /tmp/runner.tgz -C /tmp',
+      'cp -r /tmp/package/* ' + rp + '/',
+      'rm -rf /tmp/runner.tgz /tmp/package',
+      'cd ' + rp + ' && npm install --omit=dev --no-audit --no-fund --loglevel=error',
+    ].join(' && ');
+  }
+
+  return [
+    'sudo npm install -g @testdriverai/runner@' + runnerTag + ' --omit=dev --no-audit --no-fund --loglevel=error',
+    'sudo rm -rf ' + rp,
+    'sudo ln -sf $(npm root -g)/@testdriverai/runner ' + rp,
+  ].join(' && ');
+}
+
+module.exports = {
+  buildAgentConfig,
+  windowsProvisionCommands,
+  linuxRunnerInstallCommand,
+};

package/agent/lib/sandbox.js

@@ -712,19 +712,25 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       }
 
       if (message.type === "direct") {
-        // If the API returned agent config and we have an instanceId,
-        // provision the config to the instance via SSM (client-side).
+        // If the API returned provisioning commands and we have an instanceId,
+        // send them to the instance via SSM (client-side).
         // This runs from the user's infrastructure where AWS permissions exist,
         // rather than from the API server.
         // NOTE: For direct connections, the user MUST provide the AWS instanceId
         // because the API only knows the sandboxId, not the actual EC2 instance ID.
         var instanceId = message.instanceId;
-        if (reply.agentConfig && instanceId) {
-          logger.log('Provisioning agent config to instance ' + instanceId + ' via SSM...');
+        if (instanceId && reply.provisionCommands) {
+          // New path: API generated full provisioning commands (runner install + config + start)
+          logger.log('Provisioning instance ' + instanceId + ' via SSM (API-generated commands)...');
+          await this._sendSSMCommands(instanceId, reply.provisionCommands);
+          logger.log('Instance provisioned successfully.');
+        } else if (reply.agentConfig && instanceId) {
+          // Fallback: older API that only returns agentConfig (config-only, no runner install)
+          logger.log('Provisioning agent config to instance ' + instanceId + ' via SSM (legacy)...');
           await this._provisionAgentConfig(instanceId, reply.agentConfig);
           logger.log('Agent config provisioned successfully.');
-        } else if (reply.agentConfig && !instanceId) {
-          logger.log('Warning: agentConfig returned but no instanceId provided - cannot provision via SSM');
+        } else if ((reply.agentConfig || reply.provisionCommands) && !instanceId) {
+          logger.log('Warning: agentConfig/provisionCommands returned but no instanceId provided - cannot provision via SSM');
         }
 
         // If the API returned agent credentials (reply.agent present),
@@ -1233,9 +1239,66 @@ const createSandbox = function (emitter, analytics, sessionInstance) {
       this.ps = {};
     }
 
+    /**
+     * Send pre-generated PowerShell commands to an EC2 instance via AWS SSM.
+     * The commands are generated by the API (sdk/agent/lib/provision-commands.js)
+     * so provisioning logic lives in one place.
+     */
+    async _sendSSMCommands(instanceId, commands) {
+      const { execSync } = require('child_process');
+      const { writeFileSync, unlinkSync } = require('fs');
+      const { join } = require('path');
+      const { tmpdir } = require('os');
+      const { randomUUID } = require('crypto');
+
+      const region = process.env.AWS_REGION || 'us-east-2';
+      const paramsJson = JSON.stringify({ commands: commands });
+      const tmpFile = join(tmpdir(), 'td-provision-' + randomUUID() + '.json');
+      writeFileSync(tmpFile, paramsJson);
+
+      try {
+        const output = execSync(
+          'aws ssm send-command --region "' + region + '" --instance-ids "' + instanceId + '" ' +
+          '--document-name "AWS-RunPowerShellScript" ' +
+          '--parameters file://' + tmpFile + ' --output json',
+          { encoding: 'utf-8', timeout: 30000 }
+        );
+        var cmdId = JSON.parse(output).Command.CommandId;
+        logger.log('SSM command sent: ' + cmdId);
+
+        // Wait for the command to complete
+        execSync(
+          'aws ssm wait command-executed --region "' + region + '" ' +
+          '--command-id "' + cmdId + '" --instance-id "' + instanceId + '"',
+          { encoding: 'utf-8', timeout: 300000 } // 5 min — runner install can take a while
+        );
+
+        // Get the command output for debugging
+        try {
+          var invocationOutput = execSync(
+            'aws ssm get-command-invocation --region "' + region + '" ' +
+            '--command-id "' + cmdId + '" --instance-id "' + instanceId + '" --output json',
+            { encoding: 'utf-8', timeout: 30000 }
+          );
+          var invocation = JSON.parse(invocationOutput);
+          if (invocation.StandardOutputContent) {
+            logger.log('SSM output:\n' + invocation.StandardOutputContent);
+          }
+          if (invocation.StandardErrorContent) {
+            logger.warn('SSM errors:\n' + invocation.StandardErrorContent);
+          }
+        } catch (e) {
+          logger.warn('Could not retrieve SSM command output: ' + e.message);
+        }
+      } finally {
+        try { unlinkSync(tmpFile); } catch (e) { /* ignore */ }
+      }
+    }
+
     /**
      * Write the agent config JSON to an EC2 instance via AWS SSM.
      * Runs client-side so the API doesn't need AWS permissions on user infra.
+     * LEGACY: Used when connecting to an API that doesn't return provisionCommands.
      */
     async _provisionAgentConfig(instanceId, agentConfig) {
       const { execSync } = require('child_process');

package/lib/core/Dashcam.js

@@ -31,8 +31,7 @@ class Dashcam {
     this.apiKey =
       options.apiKey ||
       client.apiKey ||
-      client.config?.TD_API_KEY ||
-      "4e93d8bf-3886-4d26-a144-116c4063522d";
+      client.config?.TD_API_KEY;
     this.autoStart = options.autoStart ?? false;
     this.logs = options.logs || [];
     this.recording = false;
@@ -132,21 +131,6 @@ class Dashcam {
       return `https://${prefix}-web.fly.dev`;
     }
 
-    // Render PR previews: map API service to Web service
-    // canary-api-pr-123.onrender.com -> canary-web-pr-123.onrender.com
-    // testdriver-api-i4m4-pr-123.onrender.com -> web-i4m4-pr-123.onrender.com
-    const renderPrMatch = apiRoot.match(/https:\/\/([\w-]+)-api(-[\w]+)?(-pr-\d+)?\.onrender\.com/);
-    if (renderPrMatch) {
-      const [, prefix, suffix, prSuffix] = renderPrMatch;
-      let webPrefix;
-      if (prefix === 'testdriver' && suffix) {
-        webPrefix = 'web' + suffix;
-      } else {
-        webPrefix = prefix + '-web';
-      }
-      return `https://${webPrefix}${prSuffix || ''}.onrender.com`;
-    }
-
     // Cloudflare tunnels, custom domains, etc.: the web console is served
     // from the same origin as the API, so return apiRoot as-is.
     return apiRoot;

package/lib/vitest/hooks.mjs

@@ -181,18 +181,33 @@ function setupConsoleSpy(client, taskId) {
 
 /**
  * Unregister a client so its sandbox no longer receives forwarded logs.
- * When the last client is removed we restore the original console methods so
- * the Vitest worker fork can exit cleanly (unreleased vi.spyOn mocks prevent
- * the worker from shutting down, producing "Worker exited unexpectedly").
- * If another test starts later (e.g. a retry), installConsoleSpy() will
- * re-install the spy on demand.
+ *
+ * Between sequential `it()` blocks we intentionally keep the spies installed.
+ * The `bufferConsoleToClients` function is a no-op when `activeClients` is
+ * empty, so leaving the spy in place is harmless and avoids a non-atomic
+ * restore/re-install race that can corrupt console method references.
+ *
+ * Spies are torn down once at process exit so the Vitest worker fork can
+ * shut down cleanly (unreleased vi.spyOn mocks prevent exit).
+ *
  * @param {import('../../sdk.js').default} client - TestDriver client instance
  */
 function cleanupConsoleSpy(client) {
   _consoleSpy.activeClients.delete(client);
 
-  // Restore spies when no tests need them — allows clean worker exit
-  if (_consoleSpy.activeClients.size === 0 && _consoleSpy.spies) {
+  if (debugConsoleSpy) {
+    process.stdout.write(
+      `[DEBUG cleanupConsoleSpy] clients remaining: ${_consoleSpy.activeClients.size}\n`,
+    );
+  }
+}
+
+/**
+ * Tear down the singleton console spy completely.
+ * Called once on process exit so the Vitest worker can shut down cleanly.
+ */
+function teardownConsoleSpy() {
+  if (_consoleSpy.spies) {
     _consoleSpy.spies.log.mockRestore();
     _consoleSpy.spies.error.mockRestore();
     _consoleSpy.spies.warn.mockRestore();
@@ -202,21 +217,26 @@ function cleanupConsoleSpy(client) {
     _consoleSpy.installed = false;
 
     if (debugConsoleSpy) {
-      process.stdout.write("[DEBUG cleanupConsoleSpy] All spies restored\n");
+      process.stdout.write("[DEBUG teardownConsoleSpy] All spies restored\n");
     }
   }
-
-  if (debugConsoleSpy) {
-    process.stdout.write(
-      `[DEBUG cleanupConsoleSpy] clients remaining: ${_consoleSpy.activeClients.size}\n`,
-    );
-  }
 }
 
+// Restore console spies on process exit so the Vitest worker can exit cleanly
+process.on("exit", teardownConsoleSpy);
+
 // Weak maps to store instances per test context
 const testDriverInstances = new WeakMap();
 const lifecycleHandlers = new WeakMap();
 
+/**
+ * Module-level promise tracking the most recent test's disconnect.
+ * When sequential `it()` blocks run, the next test awaits this promise
+ * before connecting — ensuring the previous sandbox is fully torn down
+ * even if the cleanup's disconnect timeout fired early.
+ */
+let _pendingDisconnect = null;
+
 /**
  * Upload buffered SDK + console logs directly to S3 via the existing Log system.
  * Extracts the replayId from the dashcam URL, calls POST /api/v1/logs to create
@@ -436,6 +456,14 @@ export function TestDriver(context, options = {}) {
   const debugConsoleSpy = process.env.TD_DEBUG_CONSOLE_SPY === "true";
 
   testdriver.__connectionPromise = (async () => {
+    // Wait for any previous test's disconnect to fully complete.
+    // This prevents the new sandbox connection from racing with a
+    // lingering disconnect when sequential `it()` blocks run.
+    if (_pendingDisconnect) {
+      await _pendingDisconnect.catch(() => {});
+      _pendingDisconnect = null;
+    }
+
     if (debugConsoleSpy) {
       console.log(
         "[DEBUG] Before auth - sandbox.instanceSocketConnected:",
@@ -709,10 +737,19 @@ export function TestDriver(context, options = {}) {
         await currentInstance.__connectionPromise.catch(() => { }); // Ignore connection errors during cleanup
       }
 
-      // Disconnect with timeout
+      // Disconnect — track the promise at module level so the *next* test
+      // can await it before connecting, even if the timeout fires first.
+      const disconnectPromise = currentInstance.disconnect().catch((err) => {
+        console.error("Error during disconnect:", err);
+      });
+      _pendingDisconnect = disconnectPromise;
+
+      // Allow up to 30 s for Ably presence leave / channel detach.
+      // If it takes longer, cleanup resolves but _pendingDisconnect
+      // keeps the reference so the next test still waits.
       await Promise.race([
-        currentInstance.disconnect(),
-        new Promise((resolve) => setTimeout(resolve, 5000)), // 5s timeout for disconnect
+        disconnectPromise,
+        new Promise((resolve) => setTimeout(resolve, 30000)),
       ]);
     } catch (error) {
       console.error("Error disconnecting client:", error);

package/package.json

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

package/vitest.config.mjs

@@ -19,6 +19,10 @@ const sharedTestConfig = {
   maxConcurrency: 100,
   disableConsoleIntercept: false,
   silent: false,
+  // Use child-process forks so each test FILE gets a completely clean
+  // Node.js process — no shared Ably connections, module-level singletons,
+  // or Sentry globals bleeding between files.
+  pool: "forks",
   reporters: [
     "verbose",
     TestDriver()

package/docs/v7/_drafts/core.mdx

@@ -1,458 +0,0 @@
-# Core Classes
-
-Direct access to TestDriver and Dashcam classes for full manual control.
-
-## Overview
-
-The core module provides the fundamental building blocks without any automatic lifecycle management. Use this when you need complete control or when working outside of Vitest.
-
-```javascript
-import { TestDriver, Dashcam } from 'testdriverai/core';
-
-const client = new TestDriver(apiKey, { os: 'linux' });
-await client.auth();
-await client.connect();
-
-const dashcam = new Dashcam(client);
-await dashcam.start();
-
-// Your test code
-
-await dashcam.stop();
-await client.disconnect();
-```
-
-## TestDriver Class
-
-### Constructor
-
-```javascript
-import { TestDriver } from 'testdriverai/core';
-
-const client = new TestDriver(apiKey, options);
-```
-
-**Parameters:**
-- `apiKey` - Your TestDriver API key (string)
-- `options` - Configuration object
-
-**Options:**
-```javascript
-{
-  os: 'linux',              // Target OS: 'linux', 'mac', 'windows'
-  apiRoot: 'https://...',   // API endpoint
-  resolution: '1366x768',   // Screen resolution
-  newSandbox: true,         // Create new sandbox
-  analytics: true,          // Enable analytics
-  cacheThresholds: {
-    find: 0.05,
-    findAll: 0.05
-  }
-}
-```
-
-### Methods
-
-#### auth()
-Authenticate with TestDriver API.
-
-```javascript
-await client.auth();
-```
-
-#### connect(options)
-Connect to a sandbox instance.
-
-```javascript
-await client.connect({
-  new: true  // Create new sandbox (default: true)
-});
-```
-
-#### disconnect()
-Disconnect from sandbox and clean up.
-
-```javascript
-await client.disconnect();
-```
-
-#### find(query)
-Find an element on screen.
-
-```javascript
-const element = await client.find('Login button');
-await element.click();
-
-// Or chain:
-await client.find('Login button').then(el => el.click());
-```
-
-#### findAll(query)
-Find all matching elements.
-
-```javascript
-const buttons = await client.findAll('button');
-console.log('Found', buttons.length, 'buttons');
-```
-
-#### click(target)
-Click an element.
-
-```javascript
-await client.click('Submit button');
-```
-
-#### type(text)
-Type text (at current cursor position).
-
-```javascript
-await client.type('username@example.com');
-```
-
-#### pressKeys(keys)
-Press keyboard keys or shortcuts.
-
-```javascript
-await client.pressKeys(['ctrl', 'a']);
-await client.pressKeys(['enter']);
-```
-
-#### exec(shell, command, timeout, ignoreError)
-Execute shell command.
-
-```javascript
-const output = await client.exec(
-  'sh',                              // Shell: 'sh' or 'pwsh'
-  'google-chrome "https://..." &',   // Command
-  30000,                             // Timeout (ms)
-  false                              // Ignore errors
-);
-```
-
-#### focusApplication(appName)
-Focus/activate an application window.
-
-```javascript
-await client.focusApplication('Google Chrome');
-await client.focusApplication('Visual Studio Code');
-```
-
-#### scroll(direction, amount)
-Scroll the page.
-
-```javascript
-await client.scroll('down', 500);
-await client.scroll('up', 200);
-```
-
-#### assert(query)
-Assert that something is true on screen.
-
-```javascript
-const result = await client.assert('Login successful message appears');
-// Returns boolean
-```
-
-## Dashcam Class
-
-### Constructor
-
-```javascript
-import { Dashcam } from 'testdriverai/core';
-
-const dashcam = new Dashcam(client, options);
-```
-
-**Parameters:**
-- `client` - TestDriver instance (required)
-- `options` - Configuration object (optional)
-
-**Options:**
-```javascript
-{
-  apiKey: process.env.TD_API_KEY  // API key (same as TestDriver)
-}
-```
-
-### Methods
-
-#### auth(apiKey)
-Authenticate with Dashcam CLI.
-
-```javascript
-await dashcam.auth();  // Uses TD_API_KEY env var (same as TestDriver)
-// Or:
-await dashcam.auth('your-api-key');
-```
-
-#### start()
-Start recording.
-
-```javascript
-await dashcam.start();
-```
-
-#### stop()
-Stop recording and get replay URL.
-
-```javascript
-const url = await dashcam.stop();
-console.log('Replay:', url);
-// Returns: https://app.dashcam.io/replay/...
-```
-
-#### isRecording()
-Check if currently recording.
-
-```javascript
-if (dashcam.isRecording()) {
-  console.log('Recording in progress');
-}
-```
-
-#### addFileLog(path, name)
-Add a file to Dashcam logs.
-
-```javascript
-await dashcam.addFileLog('/var/log/app.log', 'Application Log');
-```
-
-#### addApplicationLog(application, name)
-Track an application in Dashcam.
-
-```javascript
-await dashcam.addApplicationLog('Google Chrome', 'Browser');
-```
-
-## Complete Examples
-
-### Basic Test
-
-```javascript
-import { TestDriver } from 'testdriverai/core';
-
-async function runTest() {
-  const client = new TestDriver(process.env.TD_API_KEY, {
-    os: 'linux',
-    resolution: '1920x1080'
-  });
-  
-  try {
-    // Connect
-    await client.auth();
-    await client.connect({ new: true });
-    
-    // Focus browser
-    await client.focusApplication('Google Chrome');
-    
-    // Navigate
-    const urlBar = await client.find('URL bar');
-    await urlBar.click();
-    await client.type('https://example.com');
-    await client.pressKeys(['enter']);
-    
-    // Test
-    await client.find('heading').click();
-    const result = await client.assert('page loaded successfully');
-    
-    console.log('Test passed:', result);
-  } finally {
-    // Always disconnect
-    await client.disconnect();
-  }
-}
-
-runTest();
-```
-
-### With Dashcam
-
-```javascript
-import { TestDriver, Dashcam } from 'testdriverai/core';
-
-async function runRecordedTest() {
-  const client = new TestDriver(process.env.TD_API_KEY, { os: 'linux' });
-  const dashcam = new Dashcam(client);
-  
-  try {
-    // Setup
-    await client.auth();
-    await client.connect();
-    
-    // Start recording
-    await dashcam.auth();
-    await dashcam.start();
-    
-    // Run test
-    await client.focusApplication('Google Chrome');
-    await client.find('button').click();
-    
-    // Stop recording
-    const url = await dashcam.stop();
-    console.log('Replay URL:', url);
-    
-  } finally {
-    await client.disconnect();
-  }
-}
-
-runRecordedTest();
-```
-
-### Multiple Operations
-
-```javascript
-import { TestDriver } from 'testdriverai/core';
-
-async function complexTest() {
-  const client = new TestDriver(process.env.TD_API_KEY, { os: 'linux' });
-  
-  await client.auth();
-  await client.connect();
-  
-  try {
-    // Launch application
-    await client.exec(
-      'sh',
-      'google-chrome --start-maximized "https://example.com" &',
-      30000
-    );
-    
-    await client.focusApplication('Google Chrome');
-    
-    // Fill form
-    await client.find('username field').type('user@example.com');
-    await client.find('password field').type('password123');
-    await client.find('submit button').click();
-    
-    // Navigate
-    await client.find('dashboard link').click();
-    
-    // Scroll and interact
-    await client.scroll('down', 500);
-    await client.find('settings button').click();
-    
-    // Verify
-    const result = await client.assert('settings page is visible');
-    console.log('Test result:', result);
-    
-  } finally {
-    await client.disconnect();
-  }
-}
-
-complexTest();
-```
-
-### Error Handling
-
-```javascript
-import { TestDriver } from 'testdriverai/core';
-
-async function testWithErrorHandling() {
-  const client = new TestDriver(process.env.TD_API_KEY, { os: 'linux' });
-  
-  try {
-    await client.auth();
-    await client.connect();
-    
-    await client.focusApplication('Google Chrome');
-    
-    // Try to find element
-    const element = await client.find('optional button');
-    
-    if (element.found()) {
-      await element.click();
-    } else {
-      console.log('Button not found, continuing...');
-    }
-    
-  } catch (error) {
-    console.error('Test failed:', error);
-    throw error;
-  } finally {
-    // Always cleanup
-    try {
-      await client.disconnect();
-    } catch (cleanupError) {
-      console.error('Cleanup error:', cleanupError);
-    }
-  }
-}
-```
-
-## TypeScript Support
-
-```typescript
-import { TestDriver, Dashcam, TestDriverOptions, DashcamOptions } from 'testdriverai/core';
-
-const options: TestDriverOptions = {
-  os: 'linux',
-  resolution: '1366x768',
-  analytics: true
-};
-
-const client = new TestDriver(process.env.TD_API_KEY!, options);
-
-const dashcamOptions: DashcamOptions = {
-  apiKey: process.env.TD_API_KEY  // Same as TestDriver
-};
-
-const dashcam = new Dashcam(client, dashcamOptions);
-```
-
-## When to Use Core Classes
-
-**Use core classes when:**
-- You need full manual control
-- You're not using Vitest
-- You're integrating with another test framework
-- You're building custom abstractions
-- You're debugging lifecycle issues
-- You're writing scripts, not tests
-
-**Use hooks or provision() instead when:**
-- You're using Vitest
-- You want automatic cleanup
-- You prefer simpler APIs
-- You're testing common applications
-
-## Best Practices
-
-1. **Always disconnect** - Use try/finally to ensure cleanup
-2. **Check element.found()** - Before using optional elements
-3. **Handle errors gracefully** - Log and re-throw when appropriate
-4. **Use TypeScript** - Get type safety and autocomplete
-5. **Set reasonable timeouts** - Default is 30 seconds for exec()
-6. **Focus applications** - Before interacting with them
-
-## Platform Differences
-
-### Shell Commands
-
-**Linux/Mac:**
-```javascript
-await client.exec('sh', 'google-chrome "https://example.com" &', 30000);
-```
-
-**Windows:**
-```javascript
-await client.exec(
-  'pwsh',
-  'Start-Process "C:/Program Files/Google/Chrome/Application/chrome.exe" -ArgumentList "https://example.com"',
-  30000
-);
-```
-
-### Application Names
-
-- Linux: `'Google Chrome'`, `'Firefox'`, `'Visual Studio Code'`
-- Mac: `'Google Chrome'`, `'Firefox'`, `'Visual Studio Code'`  
-- Windows: `'Google Chrome'`, `'Firefox'`, `'Visual Studio Code'`
-
-## See Also
-
-- [Provision API](./PROVISION.md) - Simplified API for common apps
-- [Hooks API](./HOOKS.md) - Automatic lifecycle management
-- [Migration Guide](../MIGRATION.md) - Upgrading from v6
-- [API Reference](../../sdk.js) - Full source code