@testdriverai/mcp 7.11.12-test → 7.11.13-test

package/agent/build-env.test.mjs

@@ -0,0 +1,146 @@
+/**
+ * Regression cover for the silent sandbox substitution in `buildEnv`.
+ *
+ * `connect({ sandboxId })` used to treat "attach to this sandbox" as a hint: if
+ * the reconnect threw, it swallowed the error and provisioned a brand-new
+ * sandbox in its place, then resolved as success. That is right for the CLI
+ * (`reconnect: true` means "reattach to my last sandbox, else make one") and
+ * catastrophic for a durable adapter.
+ *
+ * The eve agent parks between every tool call, which drops the realtime socket;
+ * on resume it reconnects by sandbox id. When that reconnect quietly forked a
+ * fresh sandbox, the replacement had never been through `provision.*` — those
+ * only run at session start, never on a reconnect — so the agent got a blank
+ * desktop reported as "reconnected, state preserved". It could not recover,
+ * either: the durable handle still held the dead id, so the next park forked
+ * another orphan, each one pinning a team concurrency slot until reaped.
+ *
+ * So: `requireSandbox` callers must see the failure, and the CLI's forgiving
+ * behavior must not change.
+ */
+
+import { describe, expect, it } from "vitest";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const TestDriverAgent = require("./index.js");
+
+const NEW_SANDBOX_ID = "sb-brand-new-blank";
+
+/**
+ * A minimal `this` for `buildEnv` — it only touches the collaborators stubbed
+ * here. Returns the fake plus a record of which provisioning path it took.
+ */
+function fakeAgent({ sandboxId, connectFails = false, CI = false }) {
+  const calls = { connectToSandboxDirect: 0, createNewSandbox: 0 };
+  const self = {
+    instance: null,
+    sandboxId,
+    newSandbox: false,
+    keepAlive: 900_000,
+    ip: null,
+    config: { CI, TD_RESOLUTION: [1366, 768] },
+    emitter: { emit() {} },
+    sandbox: { setConnectionParams() {}, async send() {} },
+    async newSession() {},
+    async connectToSandboxService() {},
+    async renderSandbox() {},
+    async runLifecycle() {},
+    async connectToSandboxDirect(id) {
+      calls.connectToSandboxDirect++;
+      if (connectFails) throw new Error("sandbox is gone (reaped)");
+      return { instanceId: id, sandboxId: id, url: "https://sandbox.example" };
+    },
+    async createNewSandbox() {
+      calls.createNewSandbox++;
+      return { sandbox: { sandboxId: NEW_SANDBOX_ID, url: "https://new.example" } };
+    },
+  };
+  return { self, calls };
+}
+
+const buildEnv = (self, options) =>
+  TestDriverAgent.prototype.buildEnv.call(self, options);
+
+describe("buildEnv({ requireSandbox: true })", () => {
+  it("throws instead of substituting a fresh sandbox when the target is gone", async () => {
+    const { self, calls } = fakeAgent({ sandboxId: "sb-dead", connectFails: true });
+
+    await expect(buildEnv(self, { requireSandbox: true })).rejects.toThrow(
+      /Failed to reconnect to sandbox sb-dead/,
+    );
+
+    // The whole point: no blank replacement was provisioned behind the caller's back.
+    expect(calls.createNewSandbox).toBe(0);
+    expect(self.instance).toBeNull();
+  });
+
+  it("preserves the underlying failure as the error cause", async () => {
+    const { self } = fakeAgent({ sandboxId: "sb-dead", connectFails: true });
+
+    const err = await buildEnv(self, { requireSandbox: true }).catch((e) => e);
+
+    expect(err.cause).toBeInstanceOf(Error);
+    expect(err.cause.message).toBe("sandbox is gone (reaped)");
+  });
+
+  it("attaches to the requested sandbox when it is alive", async () => {
+    const { self, calls } = fakeAgent({ sandboxId: "sb-live" });
+
+    await buildEnv(self, { requireSandbox: true });
+
+    expect(self.instance.sandboxId).toBe("sb-live");
+    expect(calls.createNewSandbox).toBe(0);
+  });
+
+  it("reconnects even under CI, which otherwise forces a new sandbox", async () => {
+    // CI normally sets createNew and nulls sandboxId, which would skip the
+    // reconnect entirely and hand back a blank sandbox — the same failure by a
+    // different route. An explicit reconnect request has to win.
+    const { self, calls } = fakeAgent({ sandboxId: "sb-live", CI: true });
+
+    await buildEnv(self, { requireSandbox: true });
+
+    expect(self.instance.sandboxId).toBe("sb-live");
+    expect(calls.createNewSandbox).toBe(0);
+  });
+
+  it("rejects a strict reconnect with no sandbox to reconnect to", async () => {
+    const { self, calls } = fakeAgent({ sandboxId: null });
+
+    await expect(buildEnv(self, { requireSandbox: true })).rejects.toThrow(
+      /requires a sandboxId/,
+    );
+    expect(calls.createNewSandbox).toBe(0);
+  });
+});
+
+describe("buildEnv default (CLI reconnect-or-create) is unchanged", () => {
+  it("falls through to a new sandbox when the last one is gone", async () => {
+    const { self, calls } = fakeAgent({ sandboxId: "sb-dead", connectFails: true });
+
+    await buildEnv(self, {});
+
+    expect(calls.connectToSandboxDirect).toBe(1);
+    expect(calls.createNewSandbox).toBe(1);
+    expect(self.instance.sandboxId).toBe(NEW_SANDBOX_ID);
+  });
+
+  it("reconnects when the last sandbox is alive", async () => {
+    const { self, calls } = fakeAgent({ sandboxId: "sb-live" });
+
+    await buildEnv(self, {});
+
+    expect(self.instance.sandboxId).toBe("sb-live");
+    expect(calls.createNewSandbox).toBe(0);
+  });
+
+  it("creates a new sandbox under CI", async () => {
+    const { self, calls } = fakeAgent({ sandboxId: "sb-live", CI: true });
+
+    await buildEnv(self, {});
+
+    expect(calls.connectToSandboxDirect).toBe(0);
+    expect(calls.createNewSandbox).toBe(1);
+  });
+});

package/agent/index.js

@@ -1676,13 +1676,23 @@ ${regression}
 
     let { headless = false, heal, new: createNew = false } = options;
 
+    // The caller named a specific sandbox and cannot accept a substitute: attach
+    // to THAT sandbox or fail. Durable adapters (the eve agent) reconnect to a
+    // sandbox they already provisioned and whose state they depend on — the
+    // browser/app is only launched once, by `provision.*` at session_start, and
+    // is never re-run on a reconnect. Silently handing back a fresh sandbox
+    // therefore yields a blank desktop that no later step can repair, while the
+    // adapter reports "reconnected, state preserved". It must see the failure so
+    // it can drop the dead handle and provision properly.
+    const requireSandbox = options.requireSandbox === true;
+
     // Prioritize this.newSandbox flag if it's set
-    if (this.newSandbox) {
+    if (this.newSandbox && !requireSandbox) {
       createNew = true;
     }
 
     // If CI environment variable is true, always create a new sandbox
-    if (this.config.CI) {
+    if (this.config.CI && !requireSandbox) {
       createNew = true;
       this.emitter.emit(
         events.log.log,
@@ -1693,7 +1703,7 @@ ${regression}
     if (heal) this.healMode = heal;
 
     // If createNew flag is set, clear sandboxId to prevent reconnection attempts
-    if (createNew) {
+    if (createNew && !requireSandbox) {
       this.sandboxId = null;
       if (!this.config.CI && !this.newSandbox) {
         this.emitter.emit(events.log.log, theme.dim("Creating a new sandbox"));
@@ -1702,6 +1712,15 @@ ${regression}
       }
     }
 
+    // A strict reconnect with nothing to reconnect to is a caller bug, not a cue
+    // to provision: fail here rather than below, where the miss would look like a
+    // connect failure.
+    if (requireSandbox && !this.sandboxId) {
+      throw new Error(
+        "buildEnv({ requireSandbox: true }) requires a sandboxId to reconnect to, but none was set.",
+      );
+    }
+
     // Create session first so session ID is available for Sentry tracing in WebSocket connection
     await this.newSession();
 
@@ -1738,7 +1757,10 @@ ${regression}
       await this.runLifecycle("provision");
 
       return;
-    } else if (!createNew && this.sandboxId && !this.config.CI) {
+    } else if (
+      this.sandboxId &&
+      (requireSandbox || (!createNew && !this.config.CI))
+    ) {
       // Only attempt to connect to existing sandbox if not in CI mode and not creating new
       // Attempt to connect to known instance
       this.emitter.emit(
@@ -1758,6 +1780,15 @@ ${regression}
         await this.renderSandbox(instance, headless);
         return;
       } catch (error) {
+        // Strict callers get the truth. Falling through here would give them a
+        // brand-new sandbox that has never been through `provision.*` — a blank
+        // desktop reported as a successful reconnect (see `requireSandbox`).
+        if (requireSandbox) {
+          throw new Error(
+            `Failed to reconnect to sandbox ${this.sandboxId}: ${error?.message ?? error}`,
+            { cause: error },
+          );
+        }
         // If connection fails, fall through to creating a new sandbox
         this.emitter.emit(
           events.log.narration,

package/mcp-server/dist/core/actions.js

@@ -448,7 +448,14 @@ export async function sessionStart(params, resolved, hooks = {}) {
     // Debug mode — attach to an existing sandbox, skip provisioning.
     if (params.sandboxId) {
         progress(`Connecting to existing sandbox ${params.sandboxId}...`);
-        await sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
+        // Debug mode attaches to one specific sandbox in its current state, so a
+        // substitute is never acceptable here either — the whole point is to inspect
+        // THAT sandbox. Fail loudly if it's gone.
+        await sdk.connect({
+            sandboxId: params.sandboxId,
+            keepAlive: params.keepAlive,
+            requireSandbox: true,
+        });
         if (!(await publishSdk(c, sdk, generation)))
             return supersededResult();
         const instance = sdk.getInstance();
@@ -564,7 +571,18 @@ export async function reconnectSession(params) {
         ip: params.ip,
         e2bTemplateId: params.e2bTemplateId,
     });
-    await sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
+    // `requireSandbox` makes the SDK throw instead of quietly provisioning a
+    // replacement when this sandbox is gone. The replacement would never have been
+    // through `provision.*` (only `sessionStart` runs that, never this path), so a
+    // "successful" reconnect would hand the agent a blank desktop and durable
+    // callers would keep reconnecting to the same dead id, forking a new orphan —
+    // each one holding a concurrency slot — on every park. A throw here surfaces as
+    // SESSION_EXPIRED, which is what actually makes the agent re-provision.
+    await sdk.connect({
+        sandboxId: params.sandboxId,
+        keepAlive: params.keepAlive,
+        requireSandbox: true,
+    });
     // Superseded: a newer rebuild already published a live SDK. Release the sandbox
     // we just attached (`publishSdk` closes it) and hand back the winner's session
     // rather than clobbering it. The session is only created on the winning path, so

package/mcp-server/src/core/actions.ts

@@ -608,7 +608,14 @@ export async function sessionStart(
   // Debug mode — attach to an existing sandbox, skip provisioning.
   if (params.sandboxId) {
     progress(`Connecting to existing sandbox ${params.sandboxId}...`);
-    await sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
+    // Debug mode attaches to one specific sandbox in its current state, so a
+    // substitute is never acceptable here either — the whole point is to inspect
+    // THAT sandbox. Fail loudly if it's gone.
+    await sdk.connect({
+      sandboxId: params.sandboxId,
+      keepAlive: params.keepAlive,
+      requireSandbox: true,
+    });
     if (!(await publishSdk(c, sdk, generation))) return supersededResult();
 
     const instance = sdk.getInstance();
@@ -755,7 +762,18 @@ export async function reconnectSession(params: ReconnectParams): Promise<string>
     e2bTemplateId: params.e2bTemplateId,
   });
 
-  await sdk.connect({ sandboxId: params.sandboxId, keepAlive: params.keepAlive });
+  // `requireSandbox` makes the SDK throw instead of quietly provisioning a
+  // replacement when this sandbox is gone. The replacement would never have been
+  // through `provision.*` (only `sessionStart` runs that, never this path), so a
+  // "successful" reconnect would hand the agent a blank desktop and durable
+  // callers would keep reconnecting to the same dead id, forking a new orphan —
+  // each one holding a concurrency slot — on every park. A throw here surfaces as
+  // SESSION_EXPIRED, which is what actually makes the agent re-provision.
+  await sdk.connect({
+    sandboxId: params.sandboxId,
+    keepAlive: params.keepAlive,
+    requireSandbox: true,
+  });
 
   // Superseded: a newer rebuild already published a live SDK. Release the sandbox
   // we just attached (`publishSdk` closes it) and hand back the winner's session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testdriverai/mcp",
-  "version": "7.11.12-test",
+  "version": "7.11.13-test",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",
@@ -57,6 +57,7 @@
     "docs:extract-urls": "node docs/_scripts/extract-example-urls.js",
     "bundle": "node build.mjs",
     "test": "mocha test/*",
+    "test:unit": "vitest run --config vitest.unit.config.mjs",
     "test:sdk": "vitest run",
     "test:sdk:dev": "vitest run --project dev",
     "test:sdk:staging": "vitest run --project staging",

package/sdk.d.ts

@@ -321,6 +321,16 @@ export interface TestDriverOptions {
 export interface ConnectOptions {
   /** Existing sandbox ID to reconnect to */
   sandboxId?: string;
+  /**
+   * Require `sandboxId` to be attached exactly: throw if that sandbox is gone
+   * rather than silently provisioning a fresh one in its place (default: false).
+   *
+   * The replacement would be blank — provision methods (chrome, vscode, …) only
+   * run at session start and are never re-applied on a reconnect — so callers
+   * that depend on the sandbox's existing state should set this and handle the
+   * error by provisioning a new session explicitly.
+   */
+  requireSandbox?: boolean;
   /** Force creation of a new sandbox */
   newSandbox?: boolean;
   /** Reconnect to the last used sandbox instead of creating a new one. When true, provision methods (chrome, vscode, installer, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists. */

package/sdk.js

@@ -2090,6 +2090,10 @@ CAPTCHA_SOLVER_EOF`,
         connectOptions.newSandbox !== undefined
           ? connectOptions.newSandbox
           : this.newSandbox,
+      // Attach to `sandboxId` or throw — never silently substitute a fresh
+      // sandbox. Off by default so the CLI keeps its forgiving
+      // reconnect-or-create behavior; see buildEnv's `requireSandbox`.
+      requireSandbox: connectOptions.requireSandbox === true,
     };
 
     // Set agent properties for buildEnv to use

package/vitest.unit.config.mjs

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+
+// Unit tests for SDK internals — pure, no sandbox, no network.
+//
+// Kept separate from vitest.config.mjs, which drives the real end-to-end
+// examples: that config provisions live sandboxes, resolves per-channel API
+// keys, and runs with an 8-minute timeout, so it can't host fast unit tests.
+// Run with `npm run test:unit`.
+export default defineConfig({
+  test: {
+    include: ["agent/**/*.test.mjs", "lib/**/*.test.mjs"],
+    // Don't let the e2e suites' fixtures/setup leak in.
+    setupFiles: [],
+  },
+});