testdriverai 7.9.56-canary → 7.9.57-test

package/docs/_data/examples-manifest.json

@@ -2,16 +2,16 @@
   "$schema": "./examples-manifest.schema.json",
   "examples": {
     "assert.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabcf808125e49dc731fec",
-      "lastUpdated": "2026-04-24T01:16:28.300Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a6d87a2d41022ee5b1e2",
+      "lastUpdated": "2026-04-30T01:19:25.897Z"
     },
     "drag-and-drop.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62b42fc0ac3cc632a918b",
       "lastUpdated": "2026-03-03T00:32:25.275Z"
     },
     "exec-pwsh.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabc1608125e49dc731fc2",
-      "lastUpdated": "2026-04-24T00:54:44.124Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a5ef7a2d41022ee5b1bc",
+      "lastUpdated": "2026-04-30T00:58:41.912Z"
     },
     "match-image.test.mjs": {
       "url": "https://console-test.testdriver.ai/runs/69c8738614b73310c7839412/69c8738c14b73310c783941d",
@@ -22,84 +22,84 @@
       "lastUpdated": "2026-03-03T00:32:25.282Z"
     },
     "hover-text-with-description.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabc2f08125e49dc731fc3",
-      "lastUpdated": "2026-04-24T00:41:19.064Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a6077a2d41022ee5b1c3",
+      "lastUpdated": "2026-04-30T00:44:55.391Z"
     },
     "windows-installer.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabc5f08125e49dc731fca",
-      "lastUpdated": "2026-04-24T00:55:52.184Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a6367a2d41022ee5b1d2",
+      "lastUpdated": "2026-04-30T00:59:51.732Z"
     },
     "exec-output.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabc6008125e49dc731fcb",
-      "lastUpdated": "2026-04-24T00:55:53.597Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a6377a2d41022ee5b1d3",
+      "lastUpdated": "2026-04-30T00:59:53.210Z"
     },
     "chrome-extension.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabc1508125e49dc731fc1",
-      "lastUpdated": "2026-04-24T00:47:44.523Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a5ed7a2d41022ee5b1ba",
+      "lastUpdated": "2026-04-30T00:51:39.144Z"
     },
     "launch-vscode-linux.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabc5108125e49dc731fc8",
-      "lastUpdated": "2026-04-24T01:06:32.713Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a62a7a2d41022ee5b1cb",
+      "lastUpdated": "2026-04-30T01:10:15.313Z"
     },
     "hover-image.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabc7708125e49dc731fd0",
-      "lastUpdated": "2026-04-24T00:49:18.676Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a6507a2d41022ee5b1d8",
+      "lastUpdated": "2026-04-30T00:53:17.284Z"
     },
     "installer.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabc8d08125e49dc731fd5",
-      "lastUpdated": "2026-04-24T00:42:53.690Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a6717a2d41022ee5b1dd",
+      "lastUpdated": "2026-04-30T00:46:31.574Z"
     },
     "type.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabccd08125e49dc731fe8",
-      "lastUpdated": "2026-04-24T00:50:48.194Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a6a77a2d41022ee5b1e0",
+      "lastUpdated": "2026-04-30T00:54:49.081Z"
     },
     "press-keys.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabce308125e49dc731feb",
-      "lastUpdated": "2026-04-24T01:15:07.328Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a6c07a2d41022ee5b1e1",
+      "lastUpdated": "2026-04-30T01:18:20.140Z"
     },
     "scroll-keyboard.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabd2408125e49dc731fee",
-      "lastUpdated": "2026-04-24T00:59:19.017Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a7097a2d41022ee5b1e4",
+      "lastUpdated": "2026-04-30T01:03:12.683Z"
     },
     "scroll.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabd3f08125e49dc731ff2",
-      "lastUpdated": "2026-04-24T01:21:40.363Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a7257a2d41022ee5b1e8",
+      "lastUpdated": "2026-04-30T01:24:19.091Z"
     },
     "scroll-until-image.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabd2508125e49dc731fef",
-      "lastUpdated": "2026-04-24T00:45:25.877Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a70a7a2d41022ee5b1e5",
+      "lastUpdated": "2026-04-30T00:49:14.652Z"
     },
     "prompt.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabd2708125e49dc731ff0",
-      "lastUpdated": "2026-04-24T00:59:22.066Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a70c7a2d41022ee5b1e6",
+      "lastUpdated": "2026-04-30T01:03:15.901Z"
     },
     "focus-window.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabd2808125e49dc731ff1",
-      "lastUpdated": "2026-04-24T00:45:28.741Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a70d7a2d41022ee5b1e7",
+      "lastUpdated": "2026-04-30T00:49:17.532Z"
     },
     "captcha-api.test.mjs": {
       "url": "https://console.testdriver.ai/runs/698f7df69e27ce1528d7d087/698f7fb0d3b320ad547d9d44",
       "lastUpdated": "2026-02-13T19:55:05.951Z"
     },
     "element-not-found.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabd5608125e49dc731ff3",
-      "lastUpdated": "2026-04-24T01:00:11.554Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a73d7a2d41022ee5b1e9",
+      "lastUpdated": "2026-04-30T01:04:02.664Z"
     },
     "formatted-logging.test.mjs": {
       "url": "https://console-test.testdriver.ai/runs/69c8738614b73310c7839412/69c873a714b73310c7839450",
       "lastUpdated": "2026-03-29T00:36:10.628Z"
     },
     "hover-text.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabd8408125e49dc731ff5",
-      "lastUpdated": "2026-04-24T00:46:59.941Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a76b7a2d41022ee5b1eb",
+      "lastUpdated": "2026-04-30T00:50:51.700Z"
     },
     "no-provision.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62b7706a177a05bccd1cf",
       "lastUpdated": "2026-03-03T00:32:25.279Z"
     },
     "ai.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabd6e08125e49dc731ff4",
-      "lastUpdated": "2026-04-24T01:24:56.138Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a7537a2d41022ee5b1ea",
+      "lastUpdated": "2026-04-30T01:27:43.771Z"
     },
     "popup-loading.test.mjs": {
       "url": "https://console.testdriver.ai/runs/698bc89f7140c3fa7daaca8d/698bca7f7140c3fa7daacbf7",
@@ -134,12 +134,12 @@
       "lastUpdated": "2026-02-13T19:55:05.953Z"
     },
     "findall-coffee-icons.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabd0e08125e49dc731fed",
-      "lastUpdated": "2026-04-24T00:51:56.440Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a6f07a2d41022ee5b1e3",
+      "lastUpdated": "2026-04-30T00:55:57.472Z"
     },
     "parse.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/69eabbfb08125e49dc731fc0/69eabd9a08125e49dc731ff6",
-      "lastUpdated": "2026-04-24T01:01:20.273Z"
+      "url": "https://console-test.testdriver.ai/runs/69f2a5d47a2d41022ee5b19e/69f2a7837a2d41022ee5b1ec",
+      "lastUpdated": "2026-04-30T01:05:14.790Z"
     },
     "flake-diffthreshold-001.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62bcafc0ac3cc632a91aa",

package/docs/v7/examples/ai.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* ai.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabd6e08125e49dc731ff4/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a7537a2d41022ee5b1ea/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/assert.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* assert.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabcf808125e49dc731fec/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a6d87a2d41022ee5b1e2/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/chrome-extension.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* chrome-extension.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabc1508125e49dc731fc1/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a5ed7a2d41022ee5b1ba/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/element-not-found.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* element-not-found.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabd5608125e49dc731ff3/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a73d7a2d41022ee5b1e9/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/findall-coffee-icons.mdx

@@ -18,7 +18,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* findall-coffee-icons.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabd0e08125e49dc731fed/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a6f07a2d41022ee5b1e3/replay" 
   width="100%" 
   height="600" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/hover-image.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* hover-image.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabc7708125e49dc731fd0/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a6507a2d41022ee5b1d8/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/hover-text-with-description.mdx

@@ -18,7 +18,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* hover-text-with-description.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabc2f08125e49dc731fc3/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a6077a2d41022ee5b1c3/replay" 
   width="100%" 
   height="600" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/hover-text.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* hover-text.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabd8408125e49dc731ff5/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a76b7a2d41022ee5b1eb/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/installer.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* installer.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabc8d08125e49dc731fd5/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a6717a2d41022ee5b1dd/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/launch-vscode-linux.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* launch-vscode-linux.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabc5108125e49dc731fc8/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a62a7a2d41022ee5b1cb/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/parse.mdx

@@ -18,7 +18,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* parse.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabd9a08125e49dc731ff6/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a7837a2d41022ee5b1ec/replay" 
   width="100%" 
   height="600" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/press-keys.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* press-keys.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabce308125e49dc731feb/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a6c07a2d41022ee5b1e1/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/scroll-keyboard.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* scroll-keyboard.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabd2408125e49dc731fee/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a7097a2d41022ee5b1e4/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/scroll.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* scroll.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabd3f08125e49dc731ff2/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a7257a2d41022ee5b1e8/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/docs/v7/examples/type.mdx

@@ -12,7 +12,7 @@ Watch this test execute in a real sandbox environment:
 
 {/* type.test.mjs output */}
 <iframe 
-  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69eabccd08125e49dc731fe8/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/69f2a6a77a2d41022ee5b1e0/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/interfaces/vitest-plugin.mjs

@@ -1187,7 +1187,13 @@ class TestDriverReporter {
       // Include per-attempt replay URLs for retry visibility
       if (dashcamUrls.length > 0) {
         const attemptUrls = dashcamUrls
-          .map(a => ({ attempt: a.attempt, url: a.url || null, sessionId: a.sessionId || null }));
+          .map(a => ({
+            attempt: a.attempt,
+            url: a.url || null,
+            sessionId: a.sessionId || null,
+            errorMessage: a.errorMessage || null,
+            errorStack: a.errorStack || null,
+          }));
         testCaseData.replayUrls = attemptUrls;
       }
 

package/lib/vitest/hooks.mjs

@@ -597,6 +597,11 @@ export function TestDriver(context, options = {}) {
       const isRetry = attemptNumber > 1;
       const attemptLabel = isRetry ? ` (attempt ${attemptNumber})` : "";
 
+      // Capture the current attempt's test error (before retry resets result)
+      const attemptResult = context.task.result?.errors?.[0];
+      const attemptErrorMessage = attemptResult?.message || null;
+      const attemptErrorStack = attemptResult?.stack || null;
+
       // Stop dashcam if it was started - with timeout to prevent hanging
       if (currentInstance._dashcam && currentInstance._dashcam.recording) {
         try {
@@ -607,6 +612,8 @@ export function TestDriver(context, options = {}) {
             attempt: attemptNumber,
             url: dashcamUrl || null,
             sessionId: currentInstance.getSessionId?.() || null,
+            errorMessage: attemptErrorMessage,
+            errorStack: attemptErrorStack,
           });
 
           // Keep backward compatibility - last attempt's URL
@@ -660,6 +667,8 @@ export function TestDriver(context, options = {}) {
             url: null,
             sessionId: currentInstance.getSessionId?.() || null,
             error: error.message,
+            errorMessage: attemptErrorMessage,
+            errorStack: attemptErrorStack,
           });
           // Ensure dashcamUrl is set to null if stop failed
           context.task.meta.dashcamUrl = null;
@@ -670,6 +679,8 @@ export function TestDriver(context, options = {}) {
           attempt: attemptNumber,
           url: null,
           sessionId: currentInstance.getSessionId?.() || null,
+          errorMessage: attemptErrorMessage,
+          errorStack: attemptErrorStack,
         });
         context.task.meta.dashcamUrl = null;
       }

package/mcp-server/dist/env-utils.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Utilities for resolving TestDriver environment variables.
+ *
+ * These helpers centralise the "param > env var > default" fallback logic
+ * so the server handler stays clean and the logic can be unit-tested
+ * independently.
+ */
+declare const VALID_OS_VALUES: readonly ["linux", "windows"];
+export type SandboxOs = (typeof VALID_OS_VALUES)[number];
+/**
+ * Resolve the sandbox OS with the following priority:
+ *   1. Explicit `os` parameter passed to session_start
+ *   2. `TD_OS` environment variable (validated against supported values)
+ *   3. `"linux"` default
+ *
+ * Mirrors the behaviour in `hooks.mjs` so the MCP server and the
+ * Vitest integration are consistent.
+ *
+ * @param explicitOs - The value passed explicitly by the caller (may be undefined)
+ * @param env        - The environment variables map (defaults to `process.env`)
+ * @returns          - The resolved OS and a warning message if TD_OS was invalid
+ */
+export declare function resolveOs(explicitOs: SandboxOs | undefined, env?: NodeJS.ProcessEnv): {
+    os: SandboxOs;
+    warning?: string;
+};
+/**
+ * Resolve the E2B template ID with the following priority:
+ *   1. Explicit `e2bTemplateId` parameter passed to session_start
+ *   2. `TD_E2B_TEMPLATE_ID` environment variable
+ *   3. `undefined` (let the SDK use its own default)
+ *
+ * Mirrors the behaviour in `hooks.mjs`:
+ *   ```js
+ *   if (!config.e2bTemplateId && process.env.TD_E2B_TEMPLATE_ID) {
+ *     config.e2bTemplateId = process.env.TD_E2B_TEMPLATE_ID;
+ *   }
+ *   ```
+ *
+ * @param explicitId - The value passed explicitly by the caller (may be undefined)
+ * @param env        - The environment variables map (defaults to `process.env`)
+ * @returns          - The resolved template ID, or undefined if none is set
+ */
+export declare function resolveE2bTemplateId(explicitId: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+export {};

package/mcp-server/dist/env-utils.js

@@ -0,0 +1,63 @@
+/**
+ * Utilities for resolving TestDriver environment variables.
+ *
+ * These helpers centralise the "param > env var > default" fallback logic
+ * so the server handler stays clean and the logic can be unit-tested
+ * independently.
+ */
+// ============================================================
+// OS resolution
+// ============================================================
+const VALID_OS_VALUES = ["linux", "windows"];
+/**
+ * Resolve the sandbox OS with the following priority:
+ *   1. Explicit `os` parameter passed to session_start
+ *   2. `TD_OS` environment variable (validated against supported values)
+ *   3. `"linux"` default
+ *
+ * Mirrors the behaviour in `hooks.mjs` so the MCP server and the
+ * Vitest integration are consistent.
+ *
+ * @param explicitOs - The value passed explicitly by the caller (may be undefined)
+ * @param env        - The environment variables map (defaults to `process.env`)
+ * @returns          - The resolved OS and a warning message if TD_OS was invalid
+ */
+export function resolveOs(explicitOs, env = process.env) {
+    if (explicitOs) {
+        return { os: explicitOs };
+    }
+    const envOs = env.TD_OS;
+    if (envOs) {
+        if (VALID_OS_VALUES.includes(envOs)) {
+            return { os: envOs };
+        }
+        return {
+            os: "linux",
+            warning: `TD_OS has unsupported value "${envOs}" (supported: ${VALID_OS_VALUES.join(", ")}), ignoring`,
+        };
+    }
+    return { os: "linux" };
+}
+// ============================================================
+// E2B template ID resolution
+// ============================================================
+/**
+ * Resolve the E2B template ID with the following priority:
+ *   1. Explicit `e2bTemplateId` parameter passed to session_start
+ *   2. `TD_E2B_TEMPLATE_ID` environment variable
+ *   3. `undefined` (let the SDK use its own default)
+ *
+ * Mirrors the behaviour in `hooks.mjs`:
+ *   ```js
+ *   if (!config.e2bTemplateId && process.env.TD_E2B_TEMPLATE_ID) {
+ *     config.e2bTemplateId = process.env.TD_E2B_TEMPLATE_ID;
+ *   }
+ *   ```
+ *
+ * @param explicitId - The value passed explicitly by the caller (may be undefined)
+ * @param env        - The environment variables map (defaults to `process.env`)
+ * @returns          - The resolved template ID, or undefined if none is set
+ */
+export function resolveE2bTemplateId(explicitId, env = process.env) {
+    return explicitId || env.TD_E2B_TEMPLATE_ID;
+}

package/mcp-server/dist/provision-types.d.ts

@@ -147,7 +147,7 @@ export declare const SessionStartInputSchema: z.ZodObject<{
     /** Electron args (for electron) */
     electronArgs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     /** Operating system for the sandbox */
-    os: z.ZodDefault<z.ZodEnum<["linux", "windows"]>>;
+    os: z.ZodOptional<z.ZodEnum<["linux", "windows"]>>;
     /** Keep sandbox alive duration in ms (default: 5 minutes) */
     keepAlive: z.ZodDefault<z.ZodNumber>;
     /** Path to test file - when provided, you MUST append generated code to this file after each action */
@@ -158,11 +158,12 @@ export declare const SessionStartInputSchema: z.ZodObject<{
     apiRoot: z.ZodOptional<z.ZodString>;
     /** Direct IP address of self-hosted instance (bypasses cloud provisioning) */
     ip: z.ZodOptional<z.ZodString>;
+    /** E2B sandbox template ID (overrides TD_E2B_TEMPLATE_ID env var) */
+    e2bTemplateId: z.ZodOptional<z.ZodString>;
     /** Sandbox ID to connect to (for debug-on-failure mode). When provided, connects to an existing sandbox instead of creating a new one. Skip provisioning. */
     sandboxId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "chrome" | "chromeExtension" | "vscode" | "installer" | "electron";
-    os: "linux" | "windows";
     keepAlive: number;
     reconnect: boolean;
     url?: string | undefined;
@@ -178,9 +179,11 @@ export declare const SessionStartInputSchema: z.ZodObject<{
     installerUrl?: string | undefined;
     installerFilename?: string | undefined;
     electronArgs?: string[] | undefined;
+    os?: "linux" | "windows" | undefined;
     testFile?: string | undefined;
     apiRoot?: string | undefined;
     ip?: string | undefined;
+    e2bTemplateId?: string | undefined;
     sandboxId?: string | undefined;
 }, {
     url?: string | undefined;
@@ -203,6 +206,7 @@ export declare const SessionStartInputSchema: z.ZodObject<{
     reconnect?: boolean | undefined;
     apiRoot?: string | undefined;
     ip?: string | undefined;
+    e2bTemplateId?: string | undefined;
     sandboxId?: string | undefined;
 }>;
 export type SessionStartInput = z.infer<typeof SessionStartInputSchema>;

package/mcp-server/dist/provision-types.js

@@ -118,7 +118,7 @@ export const SessionStartInputSchema = z.object({
     electronArgs: z.array(z.string()).optional().describe("Additional Electron arguments"),
     // Common session options
     /** Operating system for the sandbox */
-    os: z.enum(["linux", "windows"]).default("linux").describe("Sandbox OS"),
+    os: z.enum(["linux", "windows"]).optional().describe("Sandbox OS (default: 'linux', or TD_OS environment variable if set)"),
     /** Keep sandbox alive duration in ms (default: 5 minutes) */
     keepAlive: z.number().default(300000).describe("Keep sandbox alive for this many ms"),
     /** Path to test file - when provided, you MUST append generated code to this file after each action */
@@ -130,6 +130,8 @@ export const SessionStartInputSchema = z.object({
     // Self-hosted connection options
     /** Direct IP address of self-hosted instance (bypasses cloud provisioning) */
     ip: z.string().optional().describe("Direct IP address of self-hosted Windows instance (e.g., from AWS). When provided, connects directly to this IP instead of using cloud provisioning."),
+    /** E2B sandbox template ID (overrides TD_E2B_TEMPLATE_ID env var) */
+    e2bTemplateId: z.string().optional().describe("E2B sandbox template ID. Overrides the TD_E2B_TEMPLATE_ID environment variable when provided."),
     // Debug mode - connect to existing sandbox
     /** Sandbox ID to connect to (for debug-on-failure mode). When provided, connects to an existing sandbox instead of creating a new one. Skip provisioning. */
     sandboxId: z.string().optional().describe("Existing sandbox ID to connect to (from debug-on-failure mode). Skips provisioning."),

package/mcp-server/dist/server.mjs

@@ -17,6 +17,7 @@ import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { z } from "zod";
 import { generateActionCode } from "./codegen.js";
+import { resolveE2bTemplateId, resolveOs } from "./env-utils.js";
 import { getProvisionOptions, SessionStartInputSchema } from "./provision-types.js";
 import { sessionManager } from "./session.js";
 // =============================================================================
@@ -412,10 +413,25 @@ Debug mode (connect to existing sandbox):
     _meta: { ui: { resourceUri: RESOURCE_URI, expanded: true } },
 }, async (params) => {
     const startTime = Date.now();
+    // Resolve OS with priority: explicit param > TD_OS env var > "linux" default
+    // This mirrors the behavior of the Vitest hooks (hooks.mjs) which also reads TD_OS
+    const { os: resolvedOs, warning: osWarning } = resolveOs(params.os);
+    if (osWarning) {
+        logger.warn(`session_start: ${osWarning}`);
+    }
+    else if (!params.os && resolvedOs !== "linux") {
+        logger.info("session_start: Using TD_OS environment variable", { os: resolvedOs });
+    }
+    // Resolve E2B template ID with priority: explicit param > TD_E2B_TEMPLATE_ID env var
+    // This mirrors the behavior of the Vitest hooks (hooks.mjs) which also reads TD_E2B_TEMPLATE_ID
+    const resolvedE2bTemplateId = resolveE2bTemplateId(params.e2bTemplateId);
+    if (!params.e2bTemplateId && resolvedE2bTemplateId) {
+        logger.info("session_start: Using TD_E2B_TEMPLATE_ID environment variable", { e2bTemplateId: resolvedE2bTemplateId });
+    }
     logger.info("session_start: Starting", {
         type: params.type,
         url: params.url,
-        os: params.os,
+        os: resolvedOs,
         reconnect: params.reconnect,
         sandboxId: params.sandboxId,
     });
@@ -431,7 +447,7 @@ Debug mode (connect to existing sandbox):
         }
         // Create new session
         const newSession = sessionManager.createSession({
-            os: params.os,
+            os: resolvedOs,
             keepAlive: params.keepAlive,
             testFile: params.testFile,
         });
@@ -469,11 +485,12 @@ Debug mode (connect to existing sandbox):
             keyPrefix: apiKey.substring(0, 7) + "..."
         });
         sdk = new TestDriverSDK(apiKey, {
-            os: params.os,
+            os: resolvedOs,
             logging: false,
             apiRoot,
             preview: previewMode,
             ip: instanceIp,
+            e2bTemplateId: resolvedE2bTemplateId,
         });
         // Handle sandboxId mode - connect to existing sandbox (debug-on-failure mode)
         if (params.sandboxId) {