testdriverai 7.11.70-test → 7.11.71-test

package/agent/lib/http.js

@@ -27,13 +27,22 @@ const USER_AGENT = `TestDriverSDK/${version} (Node.js ${process.version})`;
  * @returns {object} Headers object (empty if no sessionId and no active span)
  */
 function getSentryTraceHeaders(sessionId) {
+  // Add a W3C traceparent for BetterStack/OTel continuity alongside Sentry's
+  // headers so the same distributed trace reaches both backends.
+  let traceparentHeaders = {};
+  try {
+    traceparentHeaders = require("../../lib/betterstack").getTraceparentHeaders(sessionId);
+  } catch (e) {
+    // BetterStack module not present — Sentry headers still propagate.
+  }
+
   // Prefer Sentry's own trace propagation when available
   try {
     const Sentry = require("@sentry/node");
     if (typeof Sentry.getTraceData === "function") {
       const traceData = Sentry.getTraceData();
       if (traceData && traceData["sentry-trace"]) {
-        return traceData;
+        return { ...traceData, ...traceparentHeaders };
       }
     }
   } catch (e) {
@@ -41,7 +50,7 @@ function getSentryTraceHeaders(sessionId) {
   }
 
   // Fallback: derive deterministic trace from session ID
-  if (!sessionId) return {};
+  if (!sessionId) return { ...traceparentHeaders };
   const traceId = crypto.createHash("md5").update(sessionId).digest("hex");
   const spanId = crypto.randomBytes(8).toString("hex");
   return {
@@ -50,6 +59,7 @@ function getSentryTraceHeaders(sessionId) {
       "sentry-trace_id=" +
       traceId +
       ",sentry-sample_rate=1.0,sentry-sampled=true",
+    ...traceparentHeaders,
   };
 }
 

package/agent/lib/provision-commands.js

@@ -41,12 +41,16 @@ function majorMinor(version) {
  * @param {string} [opts.sentryDsn]
  * @param {string} [opts.sentryEnvironment]
  * @param {string} [opts.sentryChannel]
+ * @param {string} [opts.betterstackSourceToken] - BetterStack OTLP source token
+ * @param {string} [opts.betterstackIngestUrl] - BetterStack OTLP ingest host/URL
+ * @param {string} [opts.betterstackErrorDsn] - BetterStack error-app Sentry DSN
+ * @param {boolean} [opts.betterstackForce] - Force BetterStack on dev/test channels
  * @param {Object} opts.ablyToken - Ably token object
  * @param {string} opts.channelName - Ably channel name
  * @param {string} [opts.sessionId] - Session ID for distributed tracing (traceId = MD5(sessionId))
  * @returns {Object} Agent config to serialize as JSON
  */
-function buildAgentConfig({ sandboxId, apiRoot, apiKey, sentryDsn, sentryEnvironment, sentryChannel, ablyToken, channelName, sessionId }) {
+function buildAgentConfig({ sandboxId, apiRoot, apiKey, sentryDsn, sentryEnvironment, sentryChannel, betterstackSourceToken, betterstackIngestUrl, betterstackErrorDsn, betterstackForce, ablyToken, channelName, sessionId }) {
   return {
     sandboxId,
     apiRoot,
@@ -54,6 +58,10 @@ function buildAgentConfig({ sandboxId, apiRoot, apiKey, sentryDsn, sentryEnviron
     sentryDsn: sentryDsn || undefined,
     sentryEnvironment: sentryEnvironment || 'production',
     sentryChannel: sentryChannel || undefined,
+    betterstackSourceToken: betterstackSourceToken || undefined,
+    betterstackIngestUrl: betterstackIngestUrl || undefined,
+    betterstackErrorDsn: betterstackErrorDsn || undefined,
+    betterstackForce: betterstackForce || undefined,
     sessionId: sessionId || undefined,
     ably: {
       token: ablyToken,

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/6a84f5551504d895610bbca1/6a84f56846eeed49c011dd38",
-      "lastUpdated": "2026-08-19T00:14:32.187Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798a278a75a86fc4b64f4",
+      "lastUpdated": "2026-08-21T00:15:30.566Z"
     },
     "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/6a84f5551504d895610bbca1/6a84f5581504d895610bbca4",
-      "lastUpdated": "2026-08-19T00:14:51.304Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a87989378a75a86fc4b64f1",
+      "lastUpdated": "2026-08-21T00:15:48.924Z"
     },
     "match-image.test.mjs": {
       "url": "https://console-test.testdriver.ai/runs/69c8738614b73310c7839412/69c8738c14b73310c783941d",
@@ -22,78 +22,78 @@
       "lastUpdated": "2026-03-03T00:32:25.282Z"
     },
     "hover-text-with-description.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f55c46eeed49c011dd35",
-      "lastUpdated": "2026-08-19T00:14:54.264Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a879896b7cddebeab9bfbee",
+      "lastUpdated": "2026-08-21T00:15:51.746Z"
     },
     "windows-installer.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f55d1504d895610bbca5",
-      "lastUpdated": "2026-08-19T00:20:18.039Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a879898b7cddebeab9bfbef",
+      "lastUpdated": "2026-08-21T00:20:29.119Z"
     },
     "exec-output.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f55e5834570b701a4866",
-      "lastUpdated": "2026-08-19T00:15:30.355Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798993062df0fb9b85595",
+      "lastUpdated": "2026-08-21T00:16:27.019Z"
     },
     "chrome-extension.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f5561504d895610bbca3",
-      "lastUpdated": "2026-08-19T00:14:49.438Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798913062df0fb9b85592",
+      "lastUpdated": "2026-08-21T00:15:47.131Z"
     },
     "launch-vscode-linux.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f55a5834570b701a4864",
-      "lastUpdated": "2026-08-19T00:15:25.390Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a87989441d49e9ea55bd199",
+      "lastUpdated": "2026-08-21T00:16:21.995Z"
     },
     "hover-image.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f5605834570b701a4867",
-      "lastUpdated": "2026-08-19T00:14:24.482Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a87989bb7cddebeab9bfbf0",
+      "lastUpdated": "2026-08-21T00:15:23.027Z"
     },
     "installer.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f56246eeed49c011dd36",
-      "lastUpdated": "2026-08-19T00:14:26.478Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a87989d78a75a86fc4b64f3",
+      "lastUpdated": "2026-08-21T00:15:24.990Z"
     },
     "type.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f5641504d895610bbca8",
-      "lastUpdated": "2026-08-19T00:15:35.394Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a87989fb7cddebeab9bfbf2",
+      "lastUpdated": "2026-08-21T00:16:31.968Z"
     },
     "press-keys.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f5661504d895610bbca9",
-      "replayUrl": "https://console-test.testdriver.ai/replay/6a84f82c1504d895610bbd4f?share=gvyKbIHOKiMqcVLAXfPhpg",
-      "embedUrl": "https://console-test.testdriver.ai/replay/6a84f82c1504d895610bbd4f?share=gvyKbIHOKiMqcVLAXfPhpg&embed=true",
-      "lastUpdated": "2026-08-19T00:26:25.444Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798a13062df0fb9b85597",
+      "replayUrl": "https://console-test.testdriver.ai/replay/6a879adf3062df0fb9b855fc?share=FFAdwAvK0aNJAa3xPOtWA",
+      "embedUrl": "https://console-test.testdriver.ai/replay/6a879adf3062df0fb9b855fc?share=FFAdwAvK0aNJAa3xPOtWA&embed=true",
+      "lastUpdated": "2026-08-21T00:25:08.572Z"
     },
     "scroll-keyboard.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f56c5834570b701a4869",
-      "lastUpdated": "2026-08-19T00:15:42.176Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798a6b7cddebeab9bfbf4",
+      "lastUpdated": "2026-08-21T00:16:38.650Z"
     },
     "scroll.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f5721504d895610bbcac",
-      "lastUpdated": "2026-08-19T00:15:15.384Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798ac3062df0fb9b8559c",
+      "lastUpdated": "2026-08-21T00:16:12.199Z"
     },
     "scroll-until-image.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f56d1504d895610bbcaa",
-      "lastUpdated": "2026-08-19T00:14:37.902Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798a73062df0fb9b8559a",
+      "lastUpdated": "2026-08-21T00:15:35.988Z"
     },
     "prompt.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f56f46eeed49c011dd3a",
-      "lastUpdated": "2026-08-19T00:15:45.483Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798a93062df0fb9b8559b",
+      "lastUpdated": "2026-08-21T00:16:41.842Z"
     },
     "focus-window.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f5701504d895610bbcab",
-      "lastUpdated": "2026-08-19T00:15:46.880Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798aa78a75a86fc4b64f6",
+      "lastUpdated": "2026-08-21T00:16:43.205Z"
     },
     "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/6a84f5551504d895610bbca1/6a84f5745834570b701a486a",
-      "lastUpdated": "2026-08-19T00:15:17.069Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798ae3062df0fb9b8559d",
+      "lastUpdated": "2026-08-21T00:16:13.841Z"
     },
     "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/6a84f5551504d895610bbca1/6a84f5765834570b701a486b",
-      "lastUpdated": "2026-08-19T00:15:18.750Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798afb7cddebeab9bfbf5",
+      "lastUpdated": "2026-08-21T00:16:15.554Z"
     },
     "no-provision.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62b7706a177a05bccd1cf",
@@ -138,12 +138,12 @@
       "lastUpdated": "2026-02-13T19:55:05.953Z"
     },
     "findall-coffee-icons.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f56a46eeed49c011dd39",
-      "lastUpdated": "2026-08-19T00:14:33.969Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798a43062df0fb9b85599",
+      "lastUpdated": "2026-08-21T00:15:32.294Z"
     },
     "parse.test.mjs": {
-      "url": "https://console-test.testdriver.ai/runs/6a84f5551504d895610bbca1/6a84f57746eeed49c011dd3b",
-      "lastUpdated": "2026-08-19T00:15:20.419Z"
+      "url": "https://console-test.testdriver.ai/runs/6a87988fb7cddebeab9bfbea/6a8798b178a75a86fc4b64f7",
+      "lastUpdated": "2026-08-21T00:16:17.187Z"
     },
     "flake-diffthreshold-001.test.mjs": {
       "url": "https://console.testdriver.ai/runs/69a62b3aaa712ecd3dea730a/69a62bcafc0ac3cc632a91aa",

package/docs/docs.json

@@ -41,6 +41,7 @@
                 ]
               },
               "/v7/what-is-testdriver",
+              "/v7/agent",
               {
                 "group": "Deployment",
                 "icon": "server",

package/docs/v7/agent.mdx

@@ -0,0 +1,100 @@
+---
+title: "The TestDriver Agent"
+sidebarTitle: "Agent"
+description: "How the TestDriver agent behaves on GitHub issues, pull requests, and @mentions"
+icon: "robot"
+---
+
+The TestDriver agent is an AI teammate that lives in your GitHub repository. It's
+**code review that runs your app** — instead of only reading a diff and guessing
+what might break, it starts a real sandbox, drives the real app, and reports what
+actually happens.
+
+## Scope: it only builds and maintains tests
+
+The agent is focused. The one thing it does is **write, debug, fix, and maintain
+automated tests** with TestDriver, and review pull requests by writing and running
+a test against the change. It will politely decline off-scope work — it won't edit
+your application code, fix product bugs, answer unrelated programming questions, or
+act as a general coding assistant.
+
+## How it behaves depends on the surface
+
+The agent reacts to three different GitHub surfaces, and its behavior is
+noticeably different on each.
+
+| Surface | Trigger | What it does |
+|---------|---------|--------------|
+| **Pull request opened** | Automatic (no mention) | Silent, evidence-based **code review** |
+| **Issue opened** | Automatic (no mention) | **Onboarding / test-building** |
+| **@mention** (issue or PR) | You mention the bot | Interactive, chatty conversation |
+
+## Pull requests — automatic code review
+
+When a pull request is **opened**, the agent reviews it automatically — nobody has
+to ask.
+
+- **The review is the deliverable, not chatter.** An automatic review is
+  unsolicited, so the agent stays quiet while it works and posts a **single review
+  comment** at the end rather than scattering inline threads across the diff or
+  narrating each step.
+- **It runs the change when it can.** Its default first move is to start a session,
+  work out what the PR changes from a user's point of view, and write and run a
+  TestDriver test that exercises exactly that. A bug it *watched happen* is far
+  more valuable than one it inferred.
+- **Findings are labeled by how they were found.** Each finding is marked
+  `observed` (proven by actually running the change) or `suspected` (reasoned out
+  from reading the diff). If the installation isn't signed in to TestDriver, the
+  agent can't run anything, so it reviews by reading and marks every finding
+  `suspected`.
+- **It focuses on real bugs.** Logic errors, regressions, broken edge cases,
+  mishandled errors — not style, naming, or "consider extracting this."
+- **Zero findings is a good review.** If the change looks correct, it says so in a
+  sentence. If there's nothing worth reviewing (only lockfiles, generated files, or
+  formatting), it posts nothing at all.
+- **It comments, it never blocks.** The review is always a `COMMENT` — it never
+  approves and never requests changes, so it can't gate a merge.
+
+It also fires a native GitHub **Check Run** for the PR's TestDriver suite, and
+re-runs that check on every push (not a full re-review — push more commits and
+@mention the agent if you want it to review again).
+
+<Note>
+  The agent never reviews its own pull requests. PRs opened by the bot are skipped,
+  so it won't wake itself up to review the tests it just committed.
+</Note>
+
+## Issues — onboarding and test building
+
+When an issue is **opened**, the agent treats it as a cue to help you build a test.
+
+- **If the issue describes a task**, it acts on the request — writing or debugging
+  the test you asked for.
+- **If the issue is empty**, it introduces itself, explains that it writes and
+  debugs computer-use tests, and walks you through signing in to TestDriver and
+  creating your first test.
+- **It finishes by opening a pull request** with the test it wrote.
+
+## @mentions — interactive conversation
+
+Mentioning the bot (on either an issue or a PR) starts a **solicited**, interactive
+turn. Because you asked directly, the agent is chatty: it posts progress updates,
+shows you screenshots of what's happening in the sandbox, and answers follow-ups in
+the thread.
+
+On a PR, an @mention overrides the silent auto-review behavior — you'll see the full
+play-by-play instead of just the final review comment.
+
+You can also manage the agent from a comment:
+
+- **`@bot logout`** (or "sign out") revokes the installation's shared TestDriver
+  sign-in and tears down the live sandbox, so the next mention will prompt whoever
+  responds to sign in again.
+
+## Signing in
+
+Reading a diff needs nothing, but **running** the app needs a TestDriver session,
+which requires the installation to be signed in. Sign-in state doesn't decide
+*whether* the agent reviews — it decides *how good* the review gets. A signed-out
+install still gets its bugs caught from reading the code; signing in upgrades
+findings from `suspected` to `observed`.

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/6a84f56846eeed49c011dd38/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a8798a278a75a86fc4b64f4/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/6a84f5561504d895610bbca3/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a8798913062df0fb9b85592/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/6a84f5745834570b701a486a/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a8798ae3062df0fb9b8559d/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/6a84f56a46eeed49c011dd39/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a8798a43062df0fb9b85599/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/6a84f5605834570b701a4867/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a87989bb7cddebeab9bfbf0/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/6a84f55c46eeed49c011dd35/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a879896b7cddebeab9bfbee/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/6a84f5765834570b701a486b/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a8798afb7cddebeab9bfbf5/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/6a84f56246eeed49c011dd36/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a87989d78a75a86fc4b64f3/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/6a84f55a5834570b701a4864/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a87989441d49e9ea55bd199/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/6a84f57746eeed49c011dd3b/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a8798b178a75a86fc4b64f7/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://console-test.testdriver.ai/replay/6a84f82c1504d895610bbd4f?share=gvyKbIHOKiMqcVLAXfPhpg&embed=true" 
+  src="https://console-test.testdriver.ai/replay/6a879adf3062df0fb9b855fc?share=FFAdwAvK0aNJAa3xPOtWA&embed=true" 
   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/6a84f56c5834570b701a4869/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a8798a6b7cddebeab9bfbf4/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/6a84f5721504d895610bbcac/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a8798ac3062df0fb9b8559c/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/6a84f5641504d895610bbca8/replay" 
+  src="https://api-test.testdriver.ai/api/v1/testdriver/testcase/6a87989fb7cddebeab9bfbf2/replay" 
   width="100%" 
   height="390" 
   style={{ border: "1px solid #333", borderRadius: "8px" }}

package/interfaces/vitest-plugin.mjs

@@ -16,6 +16,15 @@ const environments = require("../lib/environments.json");
 const Sentry = require("@sentry/node");
 const chalk = require("chalk");
 
+// BetterStack telemetry alongside Sentry. Loads from shared/ in the monorepo and
+// from the bundled copy when installed from npm (see lib/betterstack.js).
+let betterstack = null;
+try {
+  betterstack = require("../lib/betterstack.js");
+} catch {
+  betterstack = null;
+}
+
 // Track if Sentry has been initialized
 let sentryInitialized = false;
 
@@ -34,6 +43,12 @@ function initializeSentry() {
   try {
     const version = resolveTestDriverVersion() || "unknown";
 
+    // Build BetterStack's span processor first so it attaches to Sentry's OTel
+    // provider and mirrors 100% of spans (see betterstack-otel.js).
+    const betterstackSpanProcessor = betterstack
+      ? betterstack.createSpanProcessor({ service: "vitest", version })
+      : null;
+
     Sentry.init({
       dsn:
         process.env.SENTRY_DSN ||
@@ -41,7 +56,9 @@ function initializeSentry() {
       environment: channelConfig.sentryEnvironment,
       release: version,
       sampleRate: 0.01,
-      tracesSampleRate: 0.01,
+      tracesSampleRate: 1,
+      openTelemetrySpanProcessors: [betterstackSpanProcessor].filter(Boolean),
+      beforeSendTransaction: (event) => (Math.random() < 0.01 ? event : null),
       enableLogs: true,
       integrations: [Sentry.httpIntegration(), Sentry.nodeContextIntegration()],
       initialScope: {
@@ -98,6 +115,12 @@ function initializeSentry() {
 
     sentryInitialized = true;
     logger.debug("Sentry initialized for vitest");
+
+    if (betterstack) {
+      betterstack.init({ service: "vitest", version });
+      // Forward errors to BetterStack's error app so releases populate.
+      betterstack.initErrorReporting({ service: "vitest", version });
+    }
   } catch (err) {
     // Sentry init failed - continue without it
     logger.debug("Failed to initialize Sentry:", err.message);

package/lib/betterstack.js

@@ -0,0 +1,15 @@
+// Loads the shared BetterStack/OTel telemetry module so it's available both in
+// the monorepo (shared/ sibling) and when installed from npm (bundled copy at
+// vendor/betterstack-otel.js, created by the prepack script). BetterStack should
+// always work like Sentry — never silently disabled just because of packaging.
+
+let betterstack;
+try {
+  // Monorepo location (dev / running from source).
+  betterstack = require("../../shared/betterstack-otel");
+} catch (_) {
+  // Published package: shared/ is copied into the package by prepack.
+  betterstack = require("../vendor/betterstack-otel");
+}
+
+module.exports = betterstack;

package/lib/sentry.js

@@ -16,6 +16,7 @@ const os = require("os");
 const { version } = require("../package.json");
 const { active, sentryEnvironment } = require("./resolve-channel");
 const logger = require("../agent/lib/logger");
+const betterstack = require("./betterstack");
 
 // Store trace contexts per session so concurrent tests don't overwrite each other.
 // Keys are sessionIds, values are { traceId, sessionId }.
@@ -42,6 +43,9 @@ const isEnabled = () => {
 
 if (isEnabled()) {
   logger.log("Analytics enabled. Set TD_TELEMETRY=false to disable.");
+  // Build BetterStack's span processor first so it can attach to Sentry's own
+  // OpenTelemetry provider and mirror 100% of spans (see betterstack-otel.js).
+  const betterstackSpanProcessor = betterstack.createSpanProcessor({ service: "sdk", version });
   Sentry.init({
     dsn:
       process.env.SENTRY_DSN ||
@@ -49,7 +53,11 @@ if (isEnabled()) {
     environment: sentryEnvironment,
     release: version,
     sampleRate: 0.01,
-    tracesSampleRate: 0.01,
+    // Record 100% of spans so BetterStack gets them all; Sentry ingestion is
+    // throttled back to ~1% in beforeSendTransaction below.
+    tracesSampleRate: 1,
+    openTelemetrySpanProcessors: [betterstackSpanProcessor].filter(Boolean),
+    beforeSendTransaction: (event) => (Math.random() < 0.01 ? event : null),
     enableLogs: true,
     integrations: [Sentry.httpIntegration(), Sentry.nodeContextIntegration()],
     // Set initial context
@@ -99,6 +107,11 @@ if (isEnabled()) {
       return event;
     },
   });
+
+  // Attach BetterStack after Sentry so it shares the OTel provider and trace ids.
+  betterstack.init({ service: "sdk", version });
+  // Forward errors to BetterStack's error app so releases populate (release+environment).
+  betterstack.initErrorReporting({ service: "sdk", version });
 }
 
 /**
@@ -160,6 +173,14 @@ function captureException(error, context = {}) {
     }
     Sentry.captureException(error);
   });
+
+  betterstack.captureException(error, {
+    tags: {
+      ...(context.tags || {}),
+      ...(currentSessionId ? { session: currentSessionId } : {}),
+    },
+    extra: context.extra,
+  });
 }
 
 /**
@@ -432,6 +453,7 @@ async function withSpan(options, callback) {
  */
 async function flush(timeout = 2000) {
   if (!isEnabled()) return;
+  await betterstack.flush(timeout);
   await Sentry.flush(timeout);
 }
 

package/mcp-server/dist/server.mjs

@@ -20,6 +20,7 @@ import * as os from "os";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { z } from "zod";
+import { createRequire } from "module";
 import * as core from "./core/actions.js";
 import { NoActiveSessionError } from "./core/actions.js";
 import { resolveE2bTemplateId, resolveOs } from "./env-utils.js";
@@ -111,7 +112,23 @@ if (isSentryEnabled()) {
         },
     });
 }
+let betterstack = null;
+try {
+    const req = createRequire(import.meta.url);
+    // Monorepo location, falling back to the bundled copy in the published package.
+    try {
+        betterstack = req(path.join(sdkRoot, "..", "shared", "betterstack-otel.js"));
+    }
+    catch {
+        betterstack = req(path.join(sdkRoot, "vendor", "betterstack-otel.js"));
+    }
+    betterstack.init({ service: "mcp-server", version });
+}
+catch {
+    betterstack = null;
+}
 function captureException(error, context = {}) {
+    betterstack?.captureException(error, context);
     if (!isSentryEnabled())
         return;
     Sentry.withScope((scope) => {
@@ -141,6 +158,8 @@ function setSessionContext(sessionId, sandboxId) {
     });
 }
 async function flushSentry(timeout = 2000) {
+    if (betterstack)
+        await betterstack.flush(timeout);
     if (!isSentryEnabled())
         return;
     await Sentry.flush(timeout);

package/mcp-server/src/server.ts

@@ -26,6 +26,8 @@ import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { z } from "zod";
 
+import { createRequire } from "module";
+
 import * as core from "./core/actions.js";
 import { NoActiveSessionError, type ActionResult } from "./core/actions.js";
 import { resolveE2bTemplateId, resolveOs } from "./env-utils.js";
@@ -134,7 +136,30 @@ if (isSentryEnabled()) {
   });
 }
 
+// BetterStack telemetry alongside Sentry. Loaded from the shared module when
+// available (it lives outside the published SDK package, so guard the require).
+type BetterStack = {
+  init: (opts: { service: string; version?: string }) => boolean;
+  captureException: (error: unknown, ctx?: { tags?: Record<string, string>; extra?: Record<string, unknown> }) => void;
+  flush: (timeout?: number) => Promise<void>;
+};
+let betterstack: BetterStack | null = null;
+try {
+  const req = createRequire(import.meta.url);
+  // Monorepo location, falling back to the bundled copy in the published package.
+  try {
+    betterstack = req(path.join(sdkRoot, "..", "shared", "betterstack-otel.js")) as BetterStack;
+  } catch {
+    betterstack = req(path.join(sdkRoot, "vendor", "betterstack-otel.js")) as BetterStack;
+  }
+  betterstack.init({ service: "mcp-server", version });
+} catch {
+  betterstack = null;
+}
+
 function captureException(error: Error, context: { tags?: Record<string, string>; extra?: Record<string, unknown> } = {}) {
+  betterstack?.captureException(error, context);
+
   if (!isSentryEnabled()) return;
   
   Sentry.withScope((scope) => {
@@ -166,6 +191,7 @@ function setSessionContext(sessionId: string, sandboxId?: string) {
 }
 
 async function flushSentry(timeout = 2000) {
+  if (betterstack) await betterstack.flush(timeout);
   if (!isSentryEnabled()) return;
   await Sentry.flush(timeout);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdriverai",
-  "version": "7.11.70-test",
+  "version": "7.11.71-test",
   "description": "Next generation autonomous AI agent for end-to-end testing of web & desktop",
   "main": "sdk.js",
   "types": "sdk.d.ts",
@@ -82,12 +82,22 @@
     "report": "npm run generate-report && npm run serve-report",
     "generate:skills": "node scripts/generate-skills.js",
     "build:mcp": "cd mcp-server && npm ci && npm run build",
+    "bundle:shared": "node scripts/bundle-shared.js",
+    "prepack": "npm run bundle:shared",
     "prepublishOnly": "npm run build:mcp"
   },
   "author": "",
   "license": "ISC",
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.208.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.208.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@opentelemetry/sdk-logs": "^0.208.0",
+    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "@opentelemetry/sdk-trace-node": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.24.0",
     "@npmcli/redact": "^3.2.2",
     "@oclif/core": "^4.5.0",

package/scripts/bundle-shared.js

@@ -0,0 +1,28 @@
+// Copies shared/ modules that the SDK depends on into the package (vendor/) so
+// they ship in the npm tarball. Without this, requires like
+// ../../shared/betterstack-otel escape the package once installed and throw
+// MODULE_NOT_FOUND. Run from prepack so it happens before `npm pack`/publish.
+
+const fs = require("fs");
+const path = require("path");
+
+const sdkRoot = path.join(__dirname, "..");
+const sharedRoot = path.join(sdkRoot, "..", "shared");
+const vendorRoot = path.join(sdkRoot, "vendor");
+
+// Files copied from shared/ into vendor/. betterstack-otel.js tolerates a
+// missing resolve-channel (it falls back to env vars), so only it is required.
+const files = ["betterstack-otel.js"];
+
+fs.mkdirSync(vendorRoot, { recursive: true });
+
+for (const file of files) {
+  const src = path.join(sharedRoot, file);
+  const dest = path.join(vendorRoot, file);
+  if (!fs.existsSync(src)) {
+    console.error(`[bundle-shared] missing source: ${src}`);
+    process.exit(1);
+  }
+  fs.copyFileSync(src, dest);
+  console.log(`[bundle-shared] ${file} → vendor/${file}`);
+}

package/vendor/betterstack-otel.js

@@ -0,0 +1,470 @@
+// shared/betterstack-otel.js
+//
+// BetterStack (Telemetry) observability that runs ALONGSIDE Sentry.
+//
+// Sentry v10 already registers a global OpenTelemetry TracerProvider + span
+// processor. Rather than stand up a competing provider (which triggers the
+// "duplicate provider" errors noted in api/config/log.js), this module attaches
+// a BetterStack OTLP span processor to whatever TracerProvider is already
+// active — so every span Sentry sees is ALSO exported to BetterStack under the
+// same trace id. When Sentry is disabled we create our own NodeTracerProvider so
+// tracing still works standalone.
+//
+// Logs are exported via the OTel Logs SDK; console.* is bridged to log records
+// to match Sentry's consoleLoggingIntegration behavior (capture all logs).
+//
+// Gating mirrors Sentry exactly: disabled on dev/test channels, PR previews,
+// and when TD_TELEMETRY=false or no BetterStack token is configured.
+
+const crypto = require('crypto');
+const os = require('os');
+const path = require('path');
+const { createRequire } = require('module');
+
+// Resolve OTel deps from the caller's node_modules (api/, runner/, image-worker/,
+// …) rather than shared/, which has no node_modules of its own — same trick as
+// shared/load-env.js.
+let _callerRequire = require;
+try {
+  _callerRequire = createRequire(path.resolve(process.cwd(), 'package.json'));
+} catch (_) {
+  // fall back to this module's require
+}
+
+let _initialized = false;
+let _enabled = false;
+let _loggerProvider = null;
+let _otelLogger = null;
+let _tracerProvider = null;
+let _resourceAttrs = {};
+// BetterStack span processor, built once and shared between createSpanProcessor()
+// (passed into Sentry.init) and init() (fallback provider).
+let _spanProcessor = null;
+// Secondary Sentry client + scope pointed at BetterStack's error-tracking app.
+// Errors captured through it carry `release`/`environment`, which is what
+// populates the BetterStack Releases tab. Built once by initErrorReporting().
+let _errorClient = null;
+let _errorScope = null;
+
+/**
+ * Resolve the release channel using the shared helper, tolerating callers that
+ * have their own copy of resolve-channel.
+ */
+function resolveChannelSafe() {
+  try {
+    const { resolveChannel } = require('./resolve-channel');
+    return resolveChannel();
+  } catch (_) {
+    return process.env.TD_CHANNEL || process.env.TD_ENV || 'stable';
+  }
+}
+
+/**
+ * Should BetterStack be active? Same rules as Sentry so both backends stay in
+ * lockstep: opt-out via TD_TELEMETRY=false, off in dev/test and PR previews,
+ * and requires a source token.
+ *
+ * Escape hatch: TD_BETTERSTACK_FORCE=true enables it on dev/test too (for local
+ * verification), still honoring TD_TELEMETRY=false and the token requirement.
+ */
+function isEnabled(channel) {
+  if (process.env.TD_TELEMETRY === 'false') return false;
+  if (!process.env.BETTERSTACK_SOURCE_TOKEN) return false;
+  const forced = process.env.TD_BETTERSTACK_FORCE === 'true';
+  if (forced) return true;
+  if (process.env.IS_PULL_REQUEST === 'true') return false;
+  if (channel === 'dev' || channel === 'test') return false;
+  return true;
+}
+
+/**
+ * BetterStack ingest endpoint. Users get this from the Telemetry source page
+ * (e.g. https://s1234567.eu-nbg-2.betterstackdata.com). We append the standard
+ * OTLP/HTTP paths.
+ */
+function ingestBase() {
+  const raw = process.env.BETTERSTACK_INGEST_URL;
+  if (!raw) return null;
+  // Tolerate a bare host (no scheme) — BetterStack shows the ingesting host
+  // without https://, and the OTLP exporter requires an absolute URL.
+  const withScheme = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+  return withScheme.replace(/\/+$/, '');
+}
+
+function authHeaders() {
+  return { Authorization: `Bearer ${process.env.BETTERSTACK_SOURCE_TOKEN}` };
+}
+
+/**
+ * DSN for BetterStack's Sentry-compatible error-tracking app. Errors sent here
+ * (unlike OTLP traces/logs) populate the Errors + Releases tabs. Format matches
+ * a standard Sentry DSN: https://<token>@<ingest-host>/<application-id>.
+ */
+function errorDsn() {
+  return process.env.BETTERSTACK_ERROR_DSN || null;
+}
+
+/**
+ * Build (once) a BetterStack OTLP BatchSpanProcessor for traces.
+ *
+ * Pass the result into `Sentry.init({ openTelemetrySpanProcessors: [...] })` so
+ * it attaches to Sentry's own instrumented TracerProvider and receives every
+ * span Sentry's sampler records — the only reliable way to mirror spans on
+ * Sentry v10, whose provider has no public addSpanProcessor().
+ *
+ * Returns null when BetterStack is disabled or OTel trace packages are missing,
+ * so callers can spread it safely: `[bs.createSpanProcessor(...)].filter(Boolean)`.
+ *
+ * @param {object} opts - same shape as init(): { service, version, attributes }
+ * @returns {object|null} a BatchSpanProcessor, or null
+ */
+function createSpanProcessor(opts = {}) {
+  if (_spanProcessor) return _spanProcessor;
+
+  const channel = resolveChannelSafe();
+  if (!isEnabled(channel)) return null;
+
+  const base = ingestBase();
+  if (!base) return null;
+
+  let tracesModule;
+  let otlpTraceModule;
+  try {
+    tracesModule = _callerRequire('@opentelemetry/sdk-trace-base');
+    otlpTraceModule = _callerRequire('@opentelemetry/exporter-trace-otlp-http');
+  } catch (_) {
+    return null; // OTel trace packages not installed for this service
+  }
+
+  try {
+    const { BatchSpanProcessor } = tracesModule;
+    const { OTLPTraceExporter } = otlpTraceModule;
+    const traceExporter = new OTLPTraceExporter({
+      url: `${base}/v1/traces`,
+      headers: authHeaders(),
+    });
+    _spanProcessor = new BatchSpanProcessor(traceExporter);
+    return _spanProcessor;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Initialize BetterStack telemetry.
+ *
+ * @param {object} opts
+ * @param {string} opts.service      - logical service name (api, runner, sdk, …)
+ * @param {string} [opts.version]    - service version / release
+ * @param {object} [opts.attributes] - extra resource attributes
+ * @returns {boolean} whether BetterStack was enabled
+ */
+function init(opts = {}) {
+  if (_initialized) return _enabled;
+  _initialized = true;
+
+  const channel = resolveChannelSafe();
+  if (!isEnabled(channel)) {
+    _enabled = false;
+    return false;
+  }
+
+  const base = ingestBase();
+  if (!base) {
+    _enabled = false;
+    return false;
+  }
+
+  let resourceModule;
+  let tracesModule;
+  let logsSdkModule;
+  let logsApiModule;
+  let otlpTraceModule;
+  let otlpLogModule;
+  try {
+    resourceModule = _callerRequire('@opentelemetry/resources');
+    tracesModule = _callerRequire('@opentelemetry/sdk-trace-base');
+    logsSdkModule = _callerRequire('@opentelemetry/sdk-logs');
+    logsApiModule = _callerRequire('@opentelemetry/api-logs');
+    otlpTraceModule = _callerRequire('@opentelemetry/exporter-trace-otlp-http');
+    otlpLogModule = _callerRequire('@opentelemetry/exporter-logs-otlp-http');
+  } catch (err) {
+    // OTel packages not installed for this service — skip silently so the
+    // service still boots. Install the @opentelemetry/* deps to enable.
+    _enabled = false;
+    return false;
+  }
+
+  const { resourceFromAttributes } = resourceModule;
+  const { BatchSpanProcessor } = tracesModule;
+  const { LoggerProvider, BatchLogRecordProcessor } = logsSdkModule;
+  const { OTLPTraceExporter } = otlpTraceModule;
+  const { OTLPLogExporter } = otlpLogModule;
+
+  _resourceAttrs = {
+    'service.name': opts.service || 'unknown',
+    'service.version': opts.version || 'unknown',
+    'deployment.environment': channel,
+    'host.name': os.hostname(),
+    ...(opts.attributes || {}),
+  };
+
+  const resource = resourceFromAttributes(_resourceAttrs);
+
+  // ── Traces ────────────────────────────────────────────────────────────────
+  // Preferred path: the service already passed createSpanProcessor() into
+  // Sentry.init({ openTelemetrySpanProcessors }), so BetterStack rides Sentry's
+  // instrumented provider and gets every recorded span. Nothing to do here.
+  //
+  // Fallback: no processor handed to Sentry (e.g. Sentry disabled). Stand up our
+  // own provider so tracing still works standalone. NOTE: this provider has no
+  // auto-instrumentation, so it only exports spans created via the OTel API
+  // directly — not automatic HTTP/Express/Mongo spans.
+  if (!_spanProcessor) {
+    try {
+      const traceExporter = new OTLPTraceExporter({
+        url: `${base}/v1/traces`,
+        headers: authHeaders(),
+      });
+      _spanProcessor = new BatchSpanProcessor(traceExporter);
+
+      const { NodeTracerProvider } = _callerRequire('@opentelemetry/sdk-trace-node');
+      const provider = new NodeTracerProvider({
+        resource,
+        spanProcessors: [_spanProcessor],
+      });
+      provider.register();
+      _tracerProvider = provider;
+    } catch (_) {
+      // Tracing wiring failed — continue with logs only.
+    }
+  }
+
+  // ── Logs ────────────────────────────────────────────────────────────────
+  try {
+    const logExporter = new OTLPLogExporter({
+      url: `${base}/v1/logs`,
+      headers: authHeaders(),
+    });
+    _loggerProvider = new LoggerProvider({
+      resource,
+      processors: [new BatchLogRecordProcessor(logExporter)],
+    });
+    logsApiModule.logs.setGlobalLoggerProvider(_loggerProvider);
+    _otelLogger = _loggerProvider.getLogger(opts.service || 'unknown');
+    _bridgeConsole(logsApiModule.SeverityNumber);
+  } catch (_) {
+    // Logs wiring failed — continue with traces only.
+  }
+
+  _enabled = true;
+  return true;
+}
+
+/**
+ * Mirror console.log/info/warn/error to OTel log records (parity with Sentry's
+ * consoleLoggingIntegration). The original console methods still run.
+ */
+function _bridgeConsole(SeverityNumber) {
+  const levels = [
+    ['log', SeverityNumber.INFO, 'INFO'],
+    ['info', SeverityNumber.INFO, 'INFO'],
+    ['warn', SeverityNumber.WARN, 'WARN'],
+    ['error', SeverityNumber.ERROR, 'ERROR'],
+  ];
+  for (const [method, severityNumber, severityText] of levels) {
+    const original = console[method] ? console[method].bind(console) : null;
+    if (!original) continue;
+    console[method] = (...args) => {
+      original(...args);
+      try {
+        _otelLogger.emit({
+          severityNumber,
+          severityText,
+          body: args
+            .map((a) => (typeof a === 'string' ? a : safeStringify(a)))
+            .join(' '),
+        });
+      } catch (_) {
+        // Never let logging crash the caller.
+      }
+    };
+  }
+}
+
+function safeStringify(value) {
+  try {
+    if (value instanceof Error) return `${value.name}: ${value.message}`;
+    return JSON.stringify(value);
+  } catch (_) {
+    return String(value);
+  }
+}
+
+/**
+ * Stand up a secondary Sentry client aimed at BetterStack's error-tracking app
+ * so handled/unhandled errors land there tagged with `release` + `environment`.
+ * This is what fills BetterStack's Releases tab — OTLP traces/logs never do.
+ *
+ * Runs alongside the service's primary Sentry client (Sentry SaaS) without
+ * touching it: we build an isolated Client + Scope and only ever capture
+ * through that scope. Gating mirrors init(); no-op when disabled, when no
+ * BETTERSTACK_ERROR_DSN is set, or when @sentry/node isn't installed.
+ *
+ * @param {object} opts - { service, version, attributes } (same shape as init())
+ * @returns {boolean} whether error reporting was wired up
+ */
+function initErrorReporting(opts = {}) {
+  if (_errorClient) return true;
+
+  const channel = resolveChannelSafe();
+  if (!isEnabled(channel)) return false;
+
+  const dsn = errorDsn();
+  if (!dsn) return false;
+
+  let Sentry;
+  try {
+    Sentry = _callerRequire('@sentry/node');
+  } catch (_) {
+    // @sentry/node not installed for this service — skip silently.
+    return false;
+  }
+
+  try {
+    const client = new Sentry.NodeClient({
+      dsn,
+      environment: channel,
+      release: opts.version || 'unknown',
+      // This client only forwards errors; traces/logs already go via OTLP.
+      tracesSampleRate: 0,
+      defaultIntegrations: false,
+      integrations: [],
+      transport: Sentry.makeNodeTransport,
+      stackParser: Sentry.defaultStackParser,
+    });
+
+    const scope = new Sentry.Scope();
+    scope.setClient(client);
+    scope.setTag('service', opts.service || 'unknown');
+    if (opts.attributes) {
+      for (const [k, v] of Object.entries(opts.attributes)) scope.setTag(k, String(v));
+    }
+    client.init();
+
+    _errorClient = client;
+    _errorScope = scope;
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Record an exception to BetterStack as an ERROR log record (parity with
+ * Sentry.captureException). Traces are captured automatically via the shared
+ * span processor; this ensures crashes/handled errors are always searchable.
+ *
+ * Also forwards to BetterStack's error-tracking app (when initErrorReporting()
+ * wired up a client) so the error carries `release` + `environment`.
+ *
+ * @param {Error} error
+ * @param {object} [context] - { tags, extra } merged into log attributes
+ */
+function captureException(error, context = {}) {
+  if (_errorScope) {
+    try {
+      _errorScope.captureException(error, {
+        captureContext: { tags: context.tags, extra: context.extra },
+      });
+    } catch (_) {
+      // never let error reporting crash the caller
+    }
+  }
+  if (!_enabled || !_otelLogger) return;
+  try {
+    const { SeverityNumber } = _callerRequire('@opentelemetry/api-logs');
+    const attributes = { 'exception.type': error?.name, 'exception.message': error?.message };
+    if (error?.stack) attributes['exception.stacktrace'] = error.stack;
+    if (context.tags) {
+      for (const [k, v] of Object.entries(context.tags)) attributes[`tag.${k}`] = String(v);
+    }
+    if (context.extra) {
+      for (const [k, v] of Object.entries(context.extra)) attributes[`extra.${k}`] = safeStringify(v);
+    }
+    _otelLogger.emit({
+      severityNumber: SeverityNumber.ERROR,
+      severityText: 'ERROR',
+      body: error?.message || String(error),
+      attributes,
+    });
+  } catch (_) {
+    // swallow
+  }
+}
+
+/**
+ * W3C traceparent headers derived from a session id, mirroring the SDK's
+ * MD5(sessionId) scheme so BetterStack sees the same distributed trace that
+ * Sentry does across SDK → API → Runner → Worker.
+ *
+ * Prefer the active OTel span's real context; fall back to the deterministic
+ * session-derived id when no span is active.
+ *
+ * @param {string} sessionId
+ * @returns {object} { traceparent } (empty if nothing to propagate)
+ */
+function getTraceparentHeaders(sessionId) {
+  try {
+    const { trace, context } = _callerRequire('@opentelemetry/api');
+    const span = trace.getSpan(context.active());
+    const sc = span && span.spanContext();
+    if (sc && sc.traceId && sc.spanId) {
+      const flags = (sc.traceFlags & 1) ? '01' : '00';
+      return { traceparent: `00-${sc.traceId}-${sc.spanId}-${flags}` };
+    }
+  } catch (_) {
+    // fall through to deterministic derivation
+  }
+
+  if (!sessionId) return {};
+  const traceId = crypto.createHash('md5').update(sessionId).digest('hex');
+  const spanId = crypto.randomBytes(8).toString('hex');
+  return { traceparent: `00-${traceId}-${spanId}-01` };
+}
+
+/**
+ * Flush pending telemetry (call before process exit).
+ * @param {number} [timeout]
+ */
+async function flush(timeout = 2000) {
+  const jobs = [];
+  if (_errorClient?.flush) jobs.push(_errorClient.flush(timeout));
+  if (!_enabled && jobs.length === 0) return;
+  if (_loggerProvider?.forceFlush) jobs.push(_loggerProvider.forceFlush());
+  if (_tracerProvider?.forceFlush) jobs.push(_tracerProvider.forceFlush());
+  try {
+    await Promise.race([
+      Promise.all(jobs),
+      new Promise((r) => setTimeout(r, timeout)),
+    ]);
+  } catch (_) {
+    // ignore flush errors on shutdown
+  }
+}
+
+function enabled() {
+  return _enabled;
+}
+
+module.exports = {
+  init,
+  initErrorReporting,
+  createSpanProcessor,
+  captureException,
+  getTraceparentHeaders,
+  flush,
+  enabled,
+  isEnabled,
+  resolveChannelSafe,
+};