@wdio/mcp 3.1.0 → 3.2.0

package/README.md

@@ -353,23 +353,22 @@ All session types support `reporting` labels that appear in the BrowserStack Aut
 
 ### Session Management
 
-| Tool                | Description                                                                              |
-|---------------------|------------------------------------------------------------------------------------------|
-| `start_browser`     | Start a browser session (Chrome, Firefox, Edge, Safari; headless/headed, custom dimensions) |
-| `start_app_session` | Start an iOS or Android app session via Appium (supports state preservation via noReset) |
-| `close_session`     | Close or detach from the current browser or app session (supports detach mode)           |
-| `attach_browser`    | Attach to a running Chrome instance via `--remote-debugging-port` (CDP) |
-| `emulate_device`    | Emulate a mobile/tablet device preset (viewport, DPR, UA, touch); requires BiDi session |
+| Tool             | Description                                                                              |
+|------------------|------------------------------------------------------------------------------------------|
+| `start_session`  | Start a browser or app session. Use `platform: 'browser'` for web, `platform: 'ios'`/`'android'` for mobile, or `attach: true` to connect to a running Chrome instance |
+| `launch_chrome`  | Launch a new Chrome instance with remote debugging enabled (for use with `start_session({ attach: true })`) |
+| `close_session`  | Close or detach from the current session (supports `detach: true` to disconnect without terminating) |
+| `emulate_device` | Emulate a mobile/tablet device preset (viewport, DPR, UA, touch); requires BiDi session |
 
 ### Navigation & Page Interaction (Web & Mobile)
 
-| Tool                   | Description                                                                                                                                                                                            |
-|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `navigate`             | Navigate to a URL                                                                                                                                                                                      |
-| `get_visible_elements` | Get visible, interactable elements on the page. Supports `inViewportOnly` (default: true) to filter viewport elements, and `includeContainers` (default: false) to include layout containers on mobile |
-| `get_accessibility`    | Get accessibility tree with semantic element information                                                                                                                                               |
-| `scroll`               | Scroll in a direction (up/down) by specified pixels                                                                                                                                                    |
-| `take_screenshot`      | Capture a screenshot                                                                                                                                                                                   |
+| Tool            | Description                                                                                                                                                                                         |
+|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `navigate`      | Navigate to a URL                                                                                                                                                                                   |
+| `get_elements`  | Get visible, interactable elements on the page. Supports `inViewportOnly` (default: true) to filter viewport elements, and `includeContainers` (default: false) to include layout containers on mobile |
+| `scroll`        | Scroll in a direction (up/down) by specified pixels                                                                                                                                                 |
+| `execute_script` | Execute arbitrary JavaScript in the browser context                                                                                                                                                |
+| `switch_tab`    | Switch to a different browser tab by index or URL                                                                                                                                                   |
 
 ### Element Interaction (Web & Mobile)
 
@@ -382,7 +381,6 @@ All session types support `reporting` labels that appear in the BrowserStack Aut
 
 | Tool             | Description                                            |
 |------------------|--------------------------------------------------------|
-| `get_cookies`    | Get all cookies or a specific cookie by name           |
 | `set_cookie`     | Set a cookie with name, value, and optional attributes |
 | `delete_cookies` | Delete all cookies or a specific cookie                |
 
@@ -394,27 +392,40 @@ All session types support `reporting` labels that appear in the BrowserStack Aut
 | `swipe`         | Swipe in a direction (up/down/left/right) |
 | `drag_and_drop` | Drag from one location to another         |
 
-### App Lifecycle (iOS/Android)
-
-| Tool            | Description                                                  |
-|-----------------|--------------------------------------------------------------|
-| `get_app_state` | Check app state (installed, running, background, foreground) |
-
 ### Context Switching (Hybrid Apps)
 
-| Tool                  | Description                                     |
-|-----------------------|-------------------------------------------------|
-| `get_contexts`        | List available contexts (NATIVE_APP, WEBVIEW_*) |
-| `get_current_context` | Show the currently active context               |
-| `switch_context`      | Switch between native and webview contexts      |
+| Tool             | Description                                     |
+|------------------|-------------------------------------------------|
+| `switch_context` | Switch between native and webview contexts      |
 
 ### Device Control (iOS/Android)
 
-| Tool                                  | Description                     |
-|---------------------------------------|---------------------------------|
-| `rotate_device`                       | Rotate to portrait or landscape |
-| `hide_keyboard`                       | Hide on-screen keyboard         |
-| `get_geolocation` / `set_geolocation` | Get or set device GPS location  |
+| Tool              | Description                     |
+|-------------------|---------------------------------|
+| `rotate_device`   | Rotate to portrait or landscape |
+| `hide_keyboard`   | Hide on-screen keyboard         |
+| `set_geolocation` | Set device GPS location         |
+
+### MCP Resources (read-only, no tool call needed)
+
+| Resource                                  | Description                                            |
+|-------------------------------------------|--------------------------------------------------------|
+| `wdio://sessions`                         | Index of all recorded sessions                         |
+| `wdio://session/current/steps`            | Step log for the active session                        |
+| `wdio://session/current/code`             | Generated runnable WebdriverIO JS for the active session |
+| `wdio://session/{id}/steps`               | Step log for any past session by ID                    |
+| `wdio://session/{id}/code`                | Generated JS for any past session by ID                |
+| `wdio://session/current/elements`         | Interactable elements (viewport-only by default)       |
+| `wdio://session/current/accessibility`    | Accessibility tree                                     |
+| `wdio://session/current/screenshot`       | Screenshot (base64)                                    |
+| `wdio://session/current/cookies`          | Browser cookies                                        |
+| `wdio://session/current/tabs`             | Open browser tabs                                      |
+| `wdio://session/current/contexts`         | Native/webview contexts (mobile)                       |
+| `wdio://session/current/context`          | Currently active context (mobile)                      |
+| `wdio://session/current/app-state`        | Mobile app state                                       |
+| `wdio://session/current/geolocation`      | Device geolocation                                     |
+| `wdio://session/current/capabilities`     | Resolved WebDriver capabilities for the active session |
+| `wdio://browserstack/local-binary`        | BrowserStack Local binary download URL and start command |
 
 ## Usage Examples
 
@@ -458,28 +469,26 @@ You are a Testing expert, and want to assess the basic workflows of a web applic
 
 ```javascript
 // Default settings (headed mode, 1280x1080)
-start_browser()
+start_session({platform: 'browser'})
 
 // Firefox
-start_browser({browser: 'firefox'})
+start_session({platform: 'browser', browser: 'firefox'})
 
 // Edge
-start_browser({browser: 'edge'})
+start_session({platform: 'browser', browser: 'edge'})
 
 // Safari (headed only; requires macOS)
-start_browser({browser: 'safari'})
+start_session({platform: 'browser', browser: 'safari'})
 
 // Headless mode
-start_browser({headless: true})
+start_session({platform: 'browser', headless: true})
 
 // Custom dimensions
-start_browser({windowWidth: 1920, windowHeight: 1080})
-
-// Headless with custom dimensions
-start_browser({headless: true, windowWidth: 1920, windowHeight: 1080})
+start_session({platform: 'browser', windowWidth: 1920, windowHeight: 1080})
 
 // Pass custom capabilities (e.g. Chrome extensions, profile, prefs)
-start_browser({
+start_session({
+  platform: 'browser',
   headless: false,
   capabilities: {
     'goog:chromeOptions': {
@@ -504,9 +513,9 @@ start_browser({
 //     google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug &
 //
 //   Verify it's ready: curl http://localhost:9222/json/version
-attach_browser()
-attach_browser({port: 9333})
-attach_browser({port: 9222, navigationUrl: 'https://app.example.com'})
+start_session({attach: true})
+start_session({attach: true, port: 9333})
+start_session({attach: true, port: 9222, navigationUrl: 'https://app.example.com'})
 ```
 
 **Device emulation (requires BiDi session):**
@@ -647,8 +656,8 @@ Control app state when creating new sessions using the `noReset` and `fullReset`
 
 ```javascript
 // Preserve login state between test runs
-start_app_session({
-    platform: 'Android',
+start_session({
+    platform: 'android',
     appPath: '/path/to/app.apk',
     deviceName: 'emulator-5554',
     noReset: true,         // Don't reset app state
@@ -717,10 +726,12 @@ This eliminates the need to manually handle permission popups during automated t
 Every tool call is automatically recorded to a session history. You can inspect sessions and export runnable code via MCP resources — no extra tool calls needed:
 
 - `wdio://sessions` — lists all recorded sessions with type, timestamps, and step count
-- `wdio://session/current/steps` — step log for the active session, plus a generated WebdriverIO JS script ready to run with `webdriverio`
-- `wdio://session/{sessionId}/steps` — same for any past session by ID
+- `wdio://session/current/steps` — step log for the active session
+- `wdio://session/current/code` — generated runnable WebdriverIO JS for the active session
+- `wdio://session/{sessionId}/steps` — step log for any past session by ID
+- `wdio://session/{sessionId}/code` — generated JS for any past session by ID
 
-The generated script reconstructs the full session — including capabilities, navigation, clicks, and inputs — as a standalone `import { remote } from 'webdriverio'` file.
+The generated script reconstructs the full session — including capabilities, navigation, clicks, and inputs — as a standalone `import { remote } from 'webdriverio'` file. For BrowserStack sessions it includes the full try/catch/finally with automatic session result marking.
 
 ## Troubleshooting
 

package/lib/server.js

@@ -46,7 +46,7 @@ var package_default = {
     type: "git",
     url: "git://github.com/webdriverio/mcp.git"
   },
-  version: "3.0.0",
+  version: "3.1.1",
   description: "MCP server with WebdriverIO for browser and mobile app automation (iOS/Android via Appium)",
   main: "./lib/server.js",
   module: "./lib/server.js",
@@ -88,6 +88,7 @@ var package_default = {
     "@toon-format/toon": "^2.1.0",
     "@wdio/protocols": "^9.27.0",
     "@xmldom/xmldom": "^0.8.12",
+    "browserstack-local": "^1.5.12",
     "puppeteer-core": "^24.40.0",
     sharp: "^0.34.5",
     webdriverio: "^9.27.0",
@@ -114,7 +115,7 @@ var package_default = {
 };
 
 // src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/tools/navigate.tool.ts
@@ -2152,7 +2153,7 @@ var browserstackLocalBinaryResource = {
 };
 
 // src/resources/sessions.resource.ts
-import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/recording/code-generator.ts
 function escapeStr(value) {
@@ -2176,6 +2177,23 @@ function generateStep(step, history) {
   switch (step.tool) {
     case "start_session": {
       const platform2 = p.platform;
+      const isBrowserStack = "bstack:options" in history.capabilities;
+      const capJson = indentJson(history.capabilities).split("\n").map((line, i) => i > 0 ? `  ${line}` : line).join("\n");
+      if (isBrowserStack) {
+        const nav = platform2 === "browser" && p.navigationUrl ? `
+await browser.url('${escapeStr(p.navigationUrl)}');` : "";
+        return [
+          "const browser = await remote({",
+          "  protocol: 'https',",
+          "  hostname: 'hub.browserstack.com',",
+          "  port: 443,",
+          "  path: '/wd/hub',",
+          "  user: process.env.BS_USER,",
+          "  key: process.env.BS_KEY,",
+          `  capabilities: ${capJson}`,
+          `});${nav}`
+        ].join("\n");
+      }
       if (platform2 === "browser") {
         const nav = p.navigationUrl ? `
 await browser.url('${escapeStr(p.navigationUrl)}');` : "";
@@ -2225,8 +2243,67 @@ await browser.url('${escapeStr(p.navigationUrl)}');` : "";
       return `// [unknown tool] ${step.tool}`;
   }
 }
+function bsStatusUpdateLines(sessionType) {
+  const apiUrl = sessionType === "browser" ? "https://api.browserstack.com/automate/sessions/" : "https://api-cloud.browserstack.com/app-automate/sessions/";
+  return [
+    "    const bsAuth = Buffer.from(`${process.env.BS_USER}:${process.env.BS_KEY}`).toString('base64');",
+    `    await fetch('${apiUrl}' + browser.sessionId + '.json', {`,
+    "      method: 'PUT',",
+    "      headers: { Authorization: 'Basic ' + bsAuth, 'Content-Type': 'application/json' },",
+    "      body: JSON.stringify({ status: bsStatus, ...(bsReason ? { reason: bsReason } : {}) })",
+    "    });"
+  ];
+}
 function generateCode(history) {
+  const bstackOptions = history.capabilities["bstack:options"];
+  const isBrowserStack = bstackOptions !== void 0;
+  const usesBrowserstackLocal = bstackOptions?.local === true;
   const steps = history.steps.map((step) => generateStep(step, history)).join("\n").split("\n").map((line) => `  ${line}`).join("\n");
+  if (isBrowserStack) {
+    const bsSteps = steps.replace(/const browser = await remote\(/g, "browser = await remote(");
+    const statusUpdate = bsStatusUpdateLines(history.type).join("\n");
+    const preamble = "let browser;\nlet bsStatus = 'passed';\nlet bsReason;";
+    const catchBlock = "} catch (e) {\n  bsStatus = 'failed';\n  bsReason = String(e);\n  throw e;";
+    const finallyBody = `  if (browser) {
+${statusUpdate}
+    await browser.deleteSession();
+  }`;
+    if (usesBrowserstackLocal) {
+      const tunnelSetup = [
+        "",
+        "const tunnel = new BrowserstackTunnel();",
+        "const startTunnel = promisify(tunnel.start.bind(tunnel));",
+        "const stopTunnel = promisify(tunnel.stop.bind(tunnel));",
+        "await startTunnel({ key: process.env.BROWSERSTACK_ACCESS_KEY });",
+        ""
+      ].join("\n");
+      return [
+        "import { remote } from 'webdriverio';",
+        "import { Local as BrowserstackTunnel } from 'browserstack-local';",
+        "import { promisify } from 'node:util';",
+        tunnelSetup,
+        preamble,
+        "try {",
+        bsSteps,
+        catchBlock,
+        "} finally {",
+        finallyBody,
+        "  await stopTunnel();",
+        "}"
+      ].join("\n");
+    }
+    return [
+      "import { remote } from 'webdriverio';",
+      "",
+      preamble,
+      "try {",
+      bsSteps,
+      catchBlock,
+      "} finally {",
+      finallyBody,
+      "}"
+    ].join("\n");
+  }
   return `import { remote } from 'webdriverio';
 
 try {
@@ -2786,7 +2863,7 @@ var cookiesResource = {
 
 // src/resources/app-state.resource.ts
 init_state();
-import { ResourceTemplate as ResourceTemplate2 } from "@modelcontextprotocol/sdk/server/mcp";
+import { ResourceTemplate as ResourceTemplate2 } from "@modelcontextprotocol/sdk/server/mcp.js";
 async function readAppState(bundleId) {
   try {
     const browser = getBrowser();
@@ -2917,60 +2994,6 @@ import { z as z14 } from "zod";
 
 // src/session/lifecycle.ts
 init_state();
-function handleSessionTransition(newSessionId) {
-  const state2 = getState();
-  if (state2.currentSession && state2.currentSession !== newSessionId) {
-    const outgoing = state2.sessionHistory.get(state2.currentSession);
-    if (outgoing) {
-      outgoing.steps.push({
-        index: outgoing.steps.length + 1,
-        tool: "__session_transition__",
-        params: { newSessionId },
-        status: "ok",
-        durationMs: 0,
-        timestamp: (/* @__PURE__ */ new Date()).toISOString()
-      });
-      outgoing.endedAt = (/* @__PURE__ */ new Date()).toISOString();
-    }
-  }
-}
-function registerSession(sessionId, browser, metadata, historyEntry) {
-  const state2 = getState();
-  const oldSessionId = state2.currentSession;
-  if (oldSessionId && oldSessionId !== sessionId) {
-    handleSessionTransition(sessionId);
-  }
-  state2.browsers.set(sessionId, browser);
-  state2.sessionMetadata.set(sessionId, metadata);
-  state2.sessionHistory.set(sessionId, historyEntry);
-  state2.currentSession = sessionId;
-  if (oldSessionId && oldSessionId !== sessionId) {
-    const oldBrowser = state2.browsers.get(oldSessionId);
-    if (oldBrowser) {
-      oldBrowser.deleteSession().catch(() => {
-      });
-      state2.browsers.delete(oldSessionId);
-      state2.sessionMetadata.delete(oldSessionId);
-    }
-  }
-}
-async function closeSession(sessionId, detach, isAttached, force) {
-  const state2 = getState();
-  const browser = state2.browsers.get(sessionId);
-  if (!browser) return;
-  const history = state2.sessionHistory.get(sessionId);
-  if (history) {
-    history.endedAt = (/* @__PURE__ */ new Date()).toISOString();
-  }
-  if (force || !detach && !isAttached) {
-    await browser.deleteSession();
-  }
-  state2.browsers.delete(sessionId);
-  state2.sessionMetadata.delete(sessionId);
-  if (state2.currentSession === sessionId) {
-    state2.currentSession = null;
-  }
-}
 
 // src/providers/local-browser.provider.ts
 var LocalBrowserProvider = class {
@@ -3220,6 +3243,8 @@ var LocalAppiumProvider = class {
 var localAppiumProvider = new LocalAppiumProvider();
 
 // src/providers/cloud/browserstack.provider.ts
+import { promisify } from "util";
+import { Local as BrowserstackTunnel } from "browserstack-local";
 var BrowserStackProvider = class {
   name = "browserstack";
   getConnectionConfig(_options) {
@@ -3286,6 +3311,40 @@ var BrowserStackProvider = class {
   shouldAutoDetach(_options) {
     return false;
   }
+  async startTunnel(_options) {
+    const key = process.env.BROWSERSTACK_ACCESS_KEY ?? "";
+    const tunnel = new BrowserstackTunnel();
+    const start = promisify(tunnel.start.bind(tunnel));
+    try {
+      await start({ key });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      if (msg.includes("another browserstack local client is running") || msg.includes("server is listening on port")) {
+        console.error("[BrowserStack] Tunnel already running \u2014 reusing existing tunnel");
+        return null;
+      }
+      throw e;
+    }
+    return tunnel;
+  }
+  async onSessionClose(sessionId, sessionType, result, tunnelHandle) {
+    if (tunnelHandle) {
+      const tunnel = tunnelHandle;
+      const stop = promisify(tunnel.stop.bind(tunnel));
+      await stop();
+    }
+    const user = process.env.BROWSERSTACK_USERNAME;
+    const key = process.env.BROWSERSTACK_ACCESS_KEY;
+    if (!user || !key) return;
+    const baseUrl = sessionType === "browser" ? "https://api.browserstack.com/automate/sessions" : "https://api-cloud.browserstack.com/app-automate/sessions";
+    const auth = Buffer.from(`${user}:${key}`).toString("base64");
+    const body = { status: result.status, ...result.reason ? { reason: result.reason } : {} };
+    await fetch(`${baseUrl}/${sessionId}.json`, {
+      method: "PUT",
+      headers: { Authorization: `Basic ${auth}`, "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+  }
 };
 var browserStackProvider = new BrowserStackProvider();
 
@@ -3295,6 +3354,84 @@ function getProvider(providerName, platform2) {
   return platform2 === "browser" ? localBrowserProvider : localAppiumProvider;
 }
 
+// src/session/lifecycle.ts
+function getSessionResult(history) {
+  const errorStep = history?.steps.find((s) => s.status === "error");
+  return errorStep ? { status: "failed", reason: errorStep.error } : { status: "passed" };
+}
+function handleSessionTransition(newSessionId) {
+  const state2 = getState();
+  if (state2.currentSession && state2.currentSession !== newSessionId) {
+    const outgoing = state2.sessionHistory.get(state2.currentSession);
+    if (outgoing) {
+      outgoing.steps.push({
+        index: outgoing.steps.length + 1,
+        tool: "__session_transition__",
+        params: { newSessionId },
+        status: "ok",
+        durationMs: 0,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      outgoing.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
+  }
+}
+function registerSession(sessionId, browser, metadata, historyEntry) {
+  const state2 = getState();
+  const oldSessionId = state2.currentSession;
+  if (oldSessionId && oldSessionId !== sessionId) {
+    handleSessionTransition(sessionId);
+  }
+  state2.browsers.set(sessionId, browser);
+  state2.sessionMetadata.set(sessionId, metadata);
+  state2.sessionHistory.set(sessionId, historyEntry);
+  state2.currentSession = sessionId;
+  if (oldSessionId && oldSessionId !== sessionId) {
+    const oldBrowser = state2.browsers.get(oldSessionId);
+    const oldMetadata = state2.sessionMetadata.get(oldSessionId);
+    if (oldBrowser) {
+      void (async () => {
+        if (oldMetadata?.provider) {
+          const oldHistory = state2.sessionHistory.get(oldSessionId);
+          const provider = getProvider(oldMetadata.provider, oldMetadata.type);
+          await provider.onSessionClose?.(oldSessionId, oldMetadata.type, getSessionResult(oldHistory), oldMetadata.tunnelHandle).catch(() => {
+          });
+        }
+        await oldBrowser.deleteSession().catch(() => {
+        });
+      })();
+      state2.browsers.delete(oldSessionId);
+      state2.sessionMetadata.delete(oldSessionId);
+    }
+  }
+}
+async function closeSession(sessionId, detach, isAttached, force) {
+  const state2 = getState();
+  const browser = state2.browsers.get(sessionId);
+  if (!browser) return;
+  const history = state2.sessionHistory.get(sessionId);
+  if (history) {
+    history.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+  }
+  const metadata = state2.sessionMetadata.get(sessionId);
+  if (force || !detach && !isAttached) {
+    if (metadata?.provider) {
+      try {
+        const provider = getProvider(metadata.provider, metadata.type);
+        await provider.onSessionClose?.(sessionId, metadata.type, getSessionResult(history), metadata.tunnelHandle);
+      } catch (e) {
+        console.error("[WARN] Failed to run provider onSessionClose:", e);
+      }
+    }
+    await browser.deleteSession();
+  }
+  state2.browsers.delete(sessionId);
+  state2.sessionMetadata.delete(sessionId);
+  if (state2.currentSession === sessionId) {
+    state2.currentSession = null;
+  }
+}
+
 // src/tools/session.tool.ts
 var platformEnum = z14.enum(["browser", "ios", "android"]);
 var browserEnum = z14.enum(["chrome", "firefox", "edge", "safari"]);
@@ -3340,7 +3477,7 @@ var startSessionToolDefinition = {
       port: z14.number().optional(),
       path: z14.string().optional()
     }).optional().describe("Appium server connection (local provider only)"),
-    browserstackLocal: coerceBoolean.optional().default(false).describe("Enable BrowserStack Local tunnel for testing against local/internal URLs (BrowserStack only, default: false). IMPORTANT: The BrowserStack Local binary daemon MUST already be running before calling start_session, otherwise all navigation to local/internal URLs will fail with ERR_TUNNEL_CONNECTION_FAILED. Read the wdio://browserstack/local-binary resource for the platform-specific download URL and the exact daemon start command. Do not set this to true without first confirming the daemon is running."),
+    browserstackLocal: coerceBoolean.optional().default(false).describe("Enable BrowserStack Local tunnel for testing against local/internal URLs (BrowserStack only, default: false). When true, the tunnel is started automatically before the session and stopped when the session is closed."),
     navigationUrl: z14.string().optional().describe("URL to navigate to after starting"),
     capabilities: z14.record(z14.string(), z14.unknown()).optional().describe("Additional capabilities to merge")
   }
@@ -3426,12 +3563,15 @@ async function startBrowserSession(args) {
     windowHeight,
     capabilities: userCapabilities
   });
+  const tunnelHandle = args.browserstackLocal ? await provider.startTunnel?.(args) : void 0;
   const wdioBrowser = await remote({ ...connectionConfig, capabilities: mergedCapabilities });
   const { sessionId } = wdioBrowser;
   const sessionMetadata = {
     type: "browser",
     capabilities: mergedCapabilities,
-    isAttached: false
+    isAttached: false,
+    provider: args.provider ?? "local",
+    tunnelHandle
   };
   registerSession(sessionId, wdioBrowser, sessionMetadata, {
     sessionId,
@@ -3473,6 +3613,7 @@ async function startMobileSession(args) {
   const provider = getProvider(args.provider ?? "local", args.platform);
   const serverConfig = provider.getConnectionConfig(args);
   const mergedCapabilities = provider.buildCapabilities(args);
+  const tunnelHandle = args.browserstackLocal ? await provider.startTunnel?.(args) : void 0;
   const browser = await remote({ ...serverConfig, capabilities: mergedCapabilities });
   const { sessionId } = browser;
   const shouldAutoDetach = provider.shouldAutoDetach(args);
@@ -3480,7 +3621,9 @@ async function startMobileSession(args) {
   const metadata = {
     type: sessionType,
     capabilities: mergedCapabilities,
-    isAttached: shouldAutoDetach
+    isAttached: shouldAutoDetach,
+    provider: args.provider ?? "local",
+    tunnelHandle
   };
   registerSession(sessionId, browser, metadata, {
     sessionId,
@@ -3526,7 +3669,8 @@ async function attachBrowserSession(args) {
   const sessionMetadata = {
     type: "browser",
     capabilities,
-    isAttached: true
+    isAttached: true,
+    provider: "local"
   };
   registerSession(sessionId, browser, sessionMetadata, {
     sessionId,