@testdriverai/mcp 7.11.46 → 7.11.47-test

package/agent/lib/commands.js

@@ -156,6 +156,8 @@ const createCommands = (
    * @param {number} [data.similarity] - Cache similarity score
    * @param {string} [data.screenshotUrl] - S3 key for screenshot
    * @param {boolean} [data.isSecret] - Whether interaction contains sensitive data
+   * @param {number} [data.zoom] - Zoom factor used by the find (0 = disabled)
+   * @param {boolean} [data.verify] - Whether AI verification was enabled for the find
    */
   const trackInteraction = (data) => {
     const sessionId = sessionInstance?.get();
@@ -180,6 +182,8 @@ const createCommands = (
       reasoning: data.reasoning,
       similarity: data.similarity,
       screenshotUrl: data.screenshotUrl,
+      zoom: data.zoom,
+      verify: data.verify,
     }).catch((err) => {
       console.warn(`Failed to track ${data.interactionType} interaction:`, err.message);
     });
@@ -614,9 +618,11 @@ const createCommands = (
             reasoning: elementData.reasoning ?? null,
             similarity: elementData.similarity ?? null,
             screenshotUrl: elementData.screenshotUrl ?? null,
+            zoom: elementData.zoom ?? null,
+            verify: elementData.verify ?? null,
           });
         }
-        
+
         // Wait for redraw and track duration
         const redrawStartTime = Date.now();
         await redraw.wait(5000, redrawOptions);
@@ -662,6 +668,8 @@ const createCommands = (
           confidence: elementData.confidence ?? null,
           reasoning: elementData.reasoning ?? null,
           similarity: elementData.similarity ?? null,
+          zoom: elementData.zoom ?? null,
+          verify: elementData.verify ?? null,
         });
       }
       throw error;
@@ -730,6 +738,8 @@ const createCommands = (
           reasoning: elementData.reasoning ?? null,
           similarity: elementData.similarity ?? null,
           screenshotUrl: elementData.screenshotUrl ?? null,
+          zoom: elementData.zoom ?? null,
+          verify: elementData.verify ?? null,
         });
       }
 
@@ -767,6 +777,8 @@ const createCommands = (
           reasoning: elementData.reasoning ?? null,
           similarity: elementData.similarity ?? null,
           screenshotUrl: elementData.screenshotUrl ?? null,
+          zoom: elementData.zoom ?? null,
+          verify: elementData.verify ?? null,
         });
       }
       throw error;

package/agent/lib/openrouter-key-error.test.mjs

@@ -0,0 +1,146 @@
+import { describe, it, expect } from "vitest";
+import { createRequire } from "node:module";
+import http from "node:http";
+
+const require = createRequire(import.meta.url);
+const { createSDK, withRetry } = require("./sdk.js");
+
+/**
+ * A team's OpenRouter key can be revoked, run out of credit, or never be
+ * configured. The API reports that as a 400 carrying an OPENROUTER_* code.
+ * Two things have to hold for the user to ever see it: the request layer must
+ * not retry it into a two-minute stall, and it must arrive as a real error with
+ * `isConfigError` set — that flag is what stops find()/findAll() from folding it
+ * into "element not found" / an empty array.
+ */
+
+const axiosError = (status, data) =>
+  Object.assign(new Error(`Request failed with status code ${status}`), {
+    response: { status, data },
+  });
+
+const KEY_ERROR_BODY = {
+  error:
+    "Your team's OpenRouter API key has no credits remaining — HTTP 402. Add credits at https://openrouter.ai/credits.",
+  code: "OPENROUTER_KEY_ERROR",
+  details: { openrouterStatus: 402, source: "testdriver-locate" },
+};
+
+describe("OpenRouter key errors are not retried", () => {
+  it("fails a rejected key on the first attempt", async () => {
+    let attempts = 0;
+    await expect(
+      withRetry(async () => {
+        attempts++;
+        throw axiosError(400, KEY_ERROR_BODY);
+      }),
+    ).rejects.toThrow();
+    expect(attempts).toBe(1);
+  });
+
+  it("fails a missing key on the first attempt", async () => {
+    let attempts = 0;
+    await expect(
+      withRetry(async () => {
+        attempts++;
+        throw axiosError(400, {
+          error: "OpenRouter API key is required for self-hosted plans.",
+          code: "OPENROUTER_KEY_REQUIRED",
+        });
+      }),
+    ).rejects.toThrow();
+    expect(attempts).toBe(1);
+  });
+
+  it("still retries server errors and network failures", async () => {
+    let attempts = 0;
+    await expect(
+      withRetry(
+        async () => {
+          attempts++;
+          throw axiosError(500, {});
+        },
+        { retryConfig: { maxRetries: 2, baseDelayMs: 1 } },
+      ),
+    ).rejects.toThrow();
+    expect(attempts).toBe(3);
+
+    attempts = 0;
+    await expect(
+      withRetry(
+        async () => {
+          attempts++;
+          throw Object.assign(new Error("socket hang up"), {
+            code: "ECONNRESET",
+          });
+        },
+        { retryConfig: { maxRetries: 2, baseDelayMs: 1 } },
+      ),
+    ).rejects.toThrow();
+    expect(attempts).toBe(3);
+  });
+});
+
+describe("OpenRouter key errors reach the caller", () => {
+  /** Serve one 400 with the given body, then hand back its origin. */
+  const serve = async (body) => {
+    const server = http.createServer((req, res) => {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(body));
+    });
+    await new Promise((resolve) => server.listen(0, resolve));
+    return {
+      origin: `http://127.0.0.1:${server.address().port}`,
+      close: () => new Promise((resolve) => server.close(resolve)),
+    };
+  };
+
+  it("throws the API's message with isConfigError set", async () => {
+    const { origin, close } = await serve(KEY_ERROR_BODY);
+    const emitted = [];
+    const { req } = createSDK(
+      { emit: (event, payload) => emitted.push({ event, payload }) },
+      { TD_API_ROOT: origin },
+      { get: () => "session-1" },
+    );
+
+    try {
+      const error = await req("find", { element: "the login button" }).then(
+        () => null,
+        (e) => e,
+      );
+
+      expect(error).toBeTruthy();
+      expect(error.isConfigError).toBe(true);
+      expect(error.code).toBe("OPENROUTER_KEY_ERROR");
+      expect(error.message).toBe(KEY_ERROR_BODY.error);
+      expect(error.details).toEqual(KEY_ERROR_BODY.details);
+
+      // The message also has to reach whoever is listening to the emitter,
+      // not just the throw site.
+      expect(
+        emitted.some((e) => e.payload?.message === KEY_ERROR_BODY.error),
+      ).toBe(true);
+    } finally {
+      await close();
+    }
+  });
+
+  it("leaves other 400s on the existing path", async () => {
+    const { origin, close } = await serve({ error: "Invalid image data" });
+    const { req } = createSDK({ emit: () => {} }, { TD_API_ROOT: origin }, {
+      get: () => "session-1",
+    });
+
+    try {
+      const error = await req("find", { element: "x" }).then(
+        () => null,
+        (e) => e,
+      );
+      expect(error).toBeTruthy();
+      expect(error.isConfigError).toBeUndefined();
+    } finally {
+      await close();
+    }
+  });
+});

package/agent/lib/sdk.js

@@ -30,6 +30,27 @@ const DEFAULT_RETRY_CONFIG = {
   retryableStatusCodes: [429, 500, 502, 503, 504],
 };
 
+/**
+ * API error codes that mean "your configuration is wrong" rather than
+ * "something went wrong this time". These fail identically on every attempt, so
+ * retrying only delays the message the user needs to read.
+ */
+const CONFIG_ERROR_CODES = [
+  "OPENROUTER_KEY_ERROR",
+  "OPENROUTER_KEY_REQUIRED",
+];
+
+/**
+ * Read the API's error code out of a response body, whichever field it used.
+ * @param {Error} error - The axios error
+ * @returns {string|null}
+ */
+function apiErrorCode(error) {
+  const data = error.response?.data;
+  if (!data || typeof data !== "object") return null;
+  return data.code || (typeof data.error === "string" ? data.error : null);
+}
+
 /**
  * Determines if an error is retryable
  * @param {Error} error - The axios error
@@ -37,7 +58,24 @@ const DEFAULT_RETRY_CONFIG = {
  * @returns {boolean} Whether the request should be retried
  */
 function isRetryableError(error, config = DEFAULT_RETRY_CONFIG) {
-  return true;
+  // A rejected OpenRouter key (or a missing one) is not going to start working
+  // on attempt two — surface it now instead of after ten backoffs.
+  if (CONFIG_ERROR_CODES.includes(apiErrorCode(error))) {
+    return false;
+  }
+
+  // A request the API rejected as malformed won't fix itself either.
+  if (error.response?.status === 400) {
+    return false;
+  }
+
+  // Network errors (no HTTP response)
+  if (!error.response) {
+    return !!error.code && config.retryableNetworkCodes.includes(error.code);
+  }
+
+  // Retry only on explicitly retryable HTTP statuses.
+  return config.retryableStatusCodes.includes(error.response.status);
 }
 
 /**
@@ -566,8 +604,35 @@ const createSDK = (emitter, config, sessionInstance) => {
         throw detailedError;
       }
 
-      // Server errors (5xx) - API is down or having issues
       const status = error.response?.status;
+
+      // Configuration errors (400 + a known code) — the API rejected the call
+      // for a reason the user can fix, most often an OpenRouter key that was
+      // revoked, ran out of credit, or was never configured. These used to
+      // arrive as a bare "Request failed with status code 400" and get folded
+      // into "element not found", so the real cause never reached the user.
+      const code = apiErrorCode(error);
+      if (status === 400 && CONFIG_ERROR_CODES.includes(code)) {
+        const data = error.response.data;
+        const configError = new Error(
+          data.error || data.message || "TestDriver rejected the request",
+        );
+        configError.code = code;
+        configError.isConfigError = true;
+        configError.details = data.details;
+        configError.originalError = error;
+        configError.path = path;
+
+        emitter.emit(events.error.sdk, {
+          message: configError.message,
+          code: configError.code,
+          fullError: error,
+        });
+
+        throw configError;
+      }
+
+      // Server errors (5xx) - API is down or having issues
       if (status >= 500) {
         const serverError = new Error(
           error.response?.data?.message ||

package/package.json

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

package/sdk.js

@@ -462,6 +462,9 @@ class Element {
     const startTime = absoluteTimestamp;
     let response = null;
     let findError = null;
+    // Resolved find options, hoisted so they can be reported to interaction tracking
+    let resolvedZoom = 0;
+    let resolvedVerify = this.sdk.verifyDefault === true;
 
     const debugMode =
       process.env.VERBOSE || process.env.TD_DEBUG;
@@ -568,6 +571,14 @@ class Element {
         );
       }
 
+      // Remember the resolved options so click()/hover() and interaction
+      // tracking can report what this find actually ran with
+      const requestedZoom = typeof options === "object" && options !== null ? options.zoom : undefined;
+      resolvedZoom = requestedZoom === true ? 1 : requestedZoom === false ? 0 : typeof requestedZoom === "number" ? requestedZoom : 0;
+      resolvedVerify = verify;
+      this._zoom = resolvedZoom;
+      this._verify = resolvedVerify;
+
       response = await this.sdk.apiClient.req("find", {
         session: this.sdk.getSessionId(),
         element: description,
@@ -577,7 +588,7 @@ class Element {
         cacheKey: cacheKey,
         os: this.sdk.os,
         resolution: this.sdk.resolution,
-        zoom: zoom === true ? 1 : zoom === false ? 0 : zoom,
+        zoom: resolvedZoom,
         skipVerify: !verify,
         confidence: minConfidence,
         type: elementType,
@@ -612,6 +623,18 @@ class Element {
         this.sdk.emitter.emit(events.log.log, notFoundMessage);
       }
     } catch (error) {
+      // A rejected or missing OpenRouter key breaks every find the same way.
+      // Reporting it as "element not found" hides the one thing the user needs
+      // to know, so it escapes instead of being folded into the not-found path.
+      if (error.isConfigError) {
+        const { events } = require("./agent/events.js");
+        this.sdk.emitter.emit(
+          events.log.log,
+          formatter.formatError("Cannot run find()", error),
+        );
+        throw error;
+      }
+
       this._response = error.response
         ? this._sanitizeResponse(error.response)
         : null;
@@ -648,12 +671,15 @@ class Element {
           success: this._found,
           error: findError,
           cacheHit: findCacheHit,
+          coordinates: response?.coordinates ?? null,
           selector: response?.selector,
           selectorUsed: !!response?.selector,
           confidence: response?.confidence ?? null,
           reasoning: response?.reasoning ?? null,
           similarity: response?.similarity ?? null,
           screenshotUrl: response?.screenshotKey ?? null,
+          zoom: resolvedZoom,
+          verify: resolvedVerify,
         })
         .catch((err) => {
           console.warn("Failed to track find interaction:", err.message);
@@ -1027,6 +1053,8 @@ class Element {
       reasoning: this._response?.reasoning ?? null,
       similarity: this._response?.similarity ?? null,
       screenshotUrl: this._response?.screenshotKey ?? null,
+      zoom: this._zoom ?? null,
+      verify: this._verify ?? null,
     };
 
     if (action === "hover") {
@@ -1078,7 +1106,12 @@ class Element {
       cacheHit: this._response?.cacheHit,
       selectorUsed: !!this._response?.selector,
       selector: this._response?.selector,
+      confidence: this._response?.confidence ?? null,
+      reasoning: this._response?.reasoning ?? null,
+      similarity: this._response?.similarity ?? null,
       screenshotUrl: this._response?.screenshotKey ?? null,
+      zoom: this._zoom ?? null,
+      verify: this._verify ?? null,
     };
 
     await this.commands.hover(
@@ -2638,6 +2671,17 @@ CAPTCHA_SOLVER_EOF`,
     } catch (error) {
       const duration = Date.now() - startTime;
 
+      // A rejected or missing OpenRouter key isn't "zero elements matched" —
+      // returning [] here would hide the only thing the user can act on.
+      if (error.isConfigError) {
+        this._lastPromiseSettled = true;
+        this.emitter.emit(
+          events.log.log,
+          formatter.formatError("Cannot run findAll()", error),
+        );
+        throw error;
+      }
+
       // Single log at the end - error
       const formattedMessage = formatter.formatElementsFound(
         description,