@testdriverai/runner 7.8.0-test.41 → 7.8.0-test.43

package/README.md

@@ -1 +1,187 @@
-# runner
+# @testdriverai/runner
+
+The TestDriver Runner is a desktop automation agent that connects to the TestDriver API via [Ably](https://ably.com/) realtime messaging. It receives commands from the SDK (click, type, find, screenshot, etc.) and executes them on a desktop environment using PyAutoGUI and Sharp.
+
+## Architecture
+
+The runner operates in two modes:
+
+| Mode | Binary | Use Case |
+|------|--------|----------|
+| **Presence Runner** | `testdriver-runner` | Self-registers with the API, enters Ably presence, and waits for SDK sessions to claim it. Used for persistent/pooled runners. |
+| **Sandbox Agent** | `testdriver-sandbox-agent` | Reads pre-provisioned credentials from a config file or environment variables. Used for ephemeral cloud sandboxes (E2B, AWS EC2). |
+
+## Prerequisites
+
+### System Requirements
+
+- **Node.js** >= 18
+- **Python 3** with `pyautogui` and `Pillow`
+- A desktop environment (physical display, VNC, or virtual framebuffer)
+
+### Desktop Environment (Linux)
+
+```bash
+# Virtual display + desktop
+apt-get install -y xvfb xfce4 xfce4-terminal dbus-x11 wmctrl
+
+# VNC access (optional, for debugging)
+apt-get install -y tigervnc-standalone-server novnc websockify
+
+# Python automation
+pip3 install pyautogui python-xlib Pillow
+```
+
+### Desktop Environment (Windows)
+
+- Standard Windows desktop (RDP or console session)
+- Python 3 with `pyautogui` and `Pillow`:
+  ```powershell
+  pip install pyautogui Pillow
+  ```
+
+### Chrome
+
+Google Chrome or Chrome for Testing must be installed and accessible on `PATH`.
+
+## Installation
+
+### From the TestDriver API (recommended)
+
+```bash
+curl -fSL -H "x-api-key: $TD_API_KEY" \
+  https://api.testdriver.ai/api/v7/runner/download \
+  -o /tmp/testdriverai-runner.tgz && \
+  npm install -g /tmp/testdriverai-runner.tgz && \
+  rm /tmp/testdriverai-runner.tgz
+```
+
+### From source (development)
+
+```bash
+cd runner
+npm install
+npm start
+```
+
+## Quick Start
+
+### Presence Runner
+
+```bash
+export TD_API_KEY="your-team-api-key"
+testdriver-runner
+```
+
+The runner will:
+1. Register with the API at `/api/v7/runner/register`
+2. Receive an Ably token and channel
+3. Enter presence on the runner channel
+4. Wait for SDK sessions to claim it
+
+### Sandbox Agent
+
+The sandbox agent reads credentials from a JSON config file that the API provisions (via SSM, cloud-init, etc.):
+
+**Linux:** `/tmp/testdriver-agent.json`
+**Windows:** `C:\Windows\Temp\testdriver-agent.json`
+
+```json
+{
+  "sandboxId": "sb-abc123",
+  "ably": {
+    "token": "ably-token-string",
+    "channel": "testdriver:env:team:sandbox"
+  },
+  "apiRoot": "https://api.testdriver.ai",
+  "apiKey": "team-api-key"
+}
+```
+
+Start the agent (it will wait up to 5 minutes for the config file to appear):
+
+```bash
+testdriver-sandbox-agent
+```
+
+Or pass credentials via environment variables instead:
+
+```bash
+export SANDBOX_ID="my-sandbox"
+export ABLY_TOKEN='{"token":"..."}'
+export ABLY_CHANNEL="testdriver:env:team:sandbox"
+testdriver-sandbox-agent
+```
+
+## Environment Variables
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `TD_API_KEY` | Team API key (presence runner mode) |
+
+### Optional
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TD_API_ROOT` | Per `TD_ENV` | API server URL |
+| `TD_ENV` | `stable` | Environment (`dev` / `test` / `canary` / `stable`) |
+| `TD_RUNNER_ID` | Auto-generated UUID | Fixed runner identifier |
+| `TD_RUNNER_SINGLE` | `false` | Exit after one session |
+| `TD_RUNNER_OS` | Auto-detected | OS capability advertised to API |
+| `TD_VNC_URL` | Auto-detected | Public VNC URL override |
+| `TD_NOVNC_PORT` | Auto-detected | noVNC WebSocket proxy port |
+| `SANDBOX_ID` | Auto-generated | Sandbox identifier (agent mode) |
+| `ABLY_TOKEN` | From config file | Ably auth token JSON (agent mode) |
+| `ABLY_CHANNEL` | From config file | Ably channel name (agent mode) |
+| `CONFIG_PATH` | `/tmp/testdriver-agent.json` | Config file path override (agent mode) |
+| `SCREEN_WIDTH` | `1366` | Virtual display width (Linux) |
+| `SCREEN_HEIGHT` | `768` | Virtual display height (Linux) |
+| `DISPLAY` | `:0` | X11 display (Linux) |
+
+## Logs
+
+| Platform | Runner Log | Agent Log |
+|----------|-----------|-----------|
+| Linux/macOS | `/tmp/testdriver-runner.log` | `/tmp/testdriver-agent.log` |
+| Windows | `C:\Windows\Temp\testdriver-runner.log` | `C:\Windows\Temp\testdriver-agent.log` |
+
+## Desktop Scripts
+
+Helper scripts in `scripts-desktop/` for managing the Linux desktop environment:
+
+| Script | Purpose |
+|--------|---------|
+| `start-desktop.sh` | Starts Xvfb, XFCE, D-Bus, disables screen blanking |
+| `launch_chrome.sh` | Launches Chrome with standard flags |
+| `launch_chrome_for_testing.sh` | Launches Chrome for Testing with remote debugging (port 9222) |
+| `control_window.sh` | Window management (minimize, restore, focus) via wmctrl |
+
+## Deployment
+
+### AWS AMI (Packer)
+
+See `packer/` for Packer templates that build AMIs with the runner pre-installed. The AMI includes the full desktop stack, Chrome, Python, and the runner.
+
+### E2B Sandboxes
+
+The E2B template installs the runner in a Dockerfile. See `sdk/setup/e2b/` for the recommended setup.
+
+### Docker
+
+```bash
+TD_API_KEY=your-key docker compose up --build
+```
+
+## Updating
+
+Re-download and reinstall:
+
+```bash
+curl -fSL -H "x-api-key: $TD_API_KEY" \
+  https://api.testdriver.ai/api/v7/runner/download \
+  -o /tmp/testdriverai-runner.tgz && \
+  npm install -g /tmp/testdriverai-runner.tgz && \
+  rm /tmp/testdriverai-runner.tgz
+```

package/lib/ably-service.js

@@ -266,7 +266,7 @@ class AblyService extends EventEmitter {
     });
 
     // Subscribe to commands — save subscription ref for historyBeforeSubscribe()
-    this._commandSubscription = await this._sessionChannel.subscribe('command', async (msg) => {
+    this._onCommandMsg = async (msg) => {
       const message = msg.data;
       if (!message) return;
 
@@ -328,7 +328,8 @@ class AblyService extends EventEmitter {
       } else {
         await executeCommand();
       }
-    });
+    };
+    this._commandSubscription = await this._sessionChannel.subscribe('command', this._onCommandMsg);
 
     // ─── Ably connection state monitoring → Sentry ─────────────────────────
     this._ably.connection.on((stateChange) => {
@@ -431,7 +432,7 @@ class AblyService extends EventEmitter {
     }
 
     // Subscribe to control messages — save subscription ref for historyBeforeSubscribe()
-    this._controlSubscription = await this._sessionChannel.subscribe('control', async (msg) => {
+    this._onControlMsg = async (msg) => {
       const message = msg.data;
       if (!message) return;
 
@@ -450,7 +451,8 @@ class AblyService extends EventEmitter {
         this._debugMode = !!message.enabled;
         this.emit('log', `Debug mode ${this._debugMode ? 'enabled' : 'disabled'}`);
       }
-    });
+    };
+    this._controlSubscription = await this._sessionChannel.subscribe('control', this._onControlMsg);
 
     this.emit('log', 'Listening for commands on Ably');
 
@@ -519,24 +521,37 @@ class AblyService extends EventEmitter {
   /**
    * Recover missed messages after a channel discontinuity.
    * Uses historyBeforeSubscribe() on each subscription, which guarantees
-   * no gap between historical and live messages.
+   * no gap between historical and live messages.  Each recovered message
+   * is dispatched through the same handler that processes live messages
+   * so that missed commands are actually executed.
    */
   async _recoverFromDiscontinuity() {
     const subs = [
-      { name: 'command', sub: this._commandSubscription },
-      { name: 'control', sub: this._controlSubscription },
+      { name: 'command', sub: this._commandSubscription, handler: this._onCommandMsg },
+      { name: 'control', sub: this._controlSubscription, handler: this._onControlMsg },
     ];
-    for (const { name, sub } of subs) {
+    for (const { name, sub, handler } of subs) {
       if (!sub) continue;
       try {
         this.emit('log', `Discontinuity recovery: fetching historyBeforeSubscribe for ${name}...`);
         let page = await sub.historyBeforeSubscribe({ limit: 100 });
         let recovered = 0;
         while (page) {
-          recovered += page.items.length;
+          for (const item of page.items) {
+            recovered++;
+            try {
+              if (handler) {
+                this.emit('log', `Replaying recovered ${name} message (requestId=${item.data && item.data.requestId || 'none'})`);
+                await handler(item);
+              }
+            } catch (replayErr) {
+              this.emit('log', `Error replaying recovered ${name} message: ${replayErr.message}`);
+              Sentry.captureException(replayErr);
+            }
+          }
           page = page.hasNext() ? await page.next() : null;
         }
-        this.emit('log', `Discontinuity recovery: found ${recovered} ${name} message(s) in gap`);
+        this.emit('log', `Discontinuity recovery: replayed ${recovered} ${name} message(s) from gap`);
       } catch (err) {
         this.emit('log', `Discontinuity recovery failed for ${name}: ${err.message}`);
         Sentry.captureException(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testdriverai/runner",
-  "version": "7.8.0-test.41",
+  "version": "7.8.0-test.43",
   "description": "TestDriver Runner - Ably-based remote automation agent with Node.js automation",
   "main": "index.js",
   "bin": {