Recover bounded capture deadlines and preserve terminal session loss

.changeset/eval-capture-deadlines.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Bound experimental batch and RPC deadlines so callers can stop waiting without replaying actions or accepting late capture state.

packages/evals/core/contracts/tool.ts

@@ -140,6 +140,11 @@ export interface BrowserSessionLoss {
   cause: string;
   tool?: string;
   at?: string;
+  provider?: "local" | "browserbase";
+  sessionId?: string;
+  /** Elapsed time since the facade started browser launch, including initialization. */
+  sessionAgeMs?: number;
+  sessionTimeoutMs?: number;
 }
 
 /** MCP content returned unchanged by a runner call into its existing surface. */

packages/evals/core/tools/browserSessionLoss.ts

@@ -33,6 +33,22 @@ export function parseSessionLossTelemetry(line: string): BrowserSessionLoss | un
       cause: sanitizeErrorMessage(parsed.cause),
       ...(typeof parsed.tool === "string" && { tool: parsed.tool }),
       ...(typeof parsed.at === "string" && { at: parsed.at }),
+      ...((parsed.provider === "local" || parsed.provider === "browserbase") && {
+        provider: parsed.provider,
+      }),
+      ...(typeof parsed.sessionId === "string" && {
+        sessionId: sanitizeErrorMessage(parsed.sessionId),
+      }),
+      ...(typeof parsed.sessionAgeMs === "number" &&
+        Number.isFinite(parsed.sessionAgeMs) &&
+        parsed.sessionAgeMs >= 0 && {
+          sessionAgeMs: parsed.sessionAgeMs,
+        }),
+      ...(typeof parsed.sessionTimeoutMs === "number" &&
+        Number.isFinite(parsed.sessionTimeoutMs) &&
+        parsed.sessionTimeoutMs >= 0 && {
+          sessionTimeoutMs: parsed.sessionTimeoutMs,
+        }),
     };
   } catch {
     return undefined;

packages/evals/tests/core/browserSessionLossTelemetry.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseSessionLossTelemetry,
+  SESSION_LOST_TELEMETRY_PREFIX,
+} from "../../core/tools/browserSessionLoss.js";
+
+function line(fields: Record<string, unknown>) {
+  return (
+    SESSION_LOST_TELEMETRY_PREFIX + JSON.stringify({ cause: "CDP connection closed", ...fields })
+  );
+}
+
+describe("facade session loss diagnostics", () => {
+  it("retains browser identity, measured age and configured timeout", () => {
+    expect(
+      parseSessionLossTelemetry(
+        line({
+          tool: "snapshot",
+          at: "2026-09-08T00:00:00.000Z",
+          provider: "browserbase",
+          sessionId: "session-123",
+          sessionAgeMs: 12_500,
+          sessionTimeoutMs: 3_600_000,
+        }),
+      ),
+    ).toEqual({
+      cause: "CDP connection closed",
+      tool: "snapshot",
+      at: "2026-09-08T00:00:00.000Z",
+      provider: "browserbase",
+      sessionId: "session-123",
+      sessionAgeMs: 12_500,
+      sessionTimeoutMs: 3_600_000,
+    });
+  });
+
+  it.each([-1, "12000", null, {}, 1e309])("drops invalid diagnostic durations: %j", (value) => {
+    expect(
+      parseSessionLossTelemetry(line({ sessionAgeMs: value, sessionTimeoutMs: value })),
+    ).toEqual({ cause: "CDP connection closed" });
+  });
+
+  it("accepts zero age and omits invalid identity metadata", () => {
+    expect(
+      parseSessionLossTelemetry(line({ provider: "other", sessionId: 42, sessionAgeMs: 0 })),
+    ).toEqual({ cause: "CDP connection closed", sessionAgeMs: 0 });
+  });
+
+  it("drops JSON numeric overflow without losing the terminal cause", () => {
+    expect(
+      parseSessionLossTelemetry(
+        SESSION_LOST_TELEMETRY_PREFIX +
+          '{"cause":"CDP connection closed","sessionAgeMs":1e309,"sessionTimeoutMs":1e309}',
+      ),
+    ).toEqual({ cause: "CDP connection closed" });
+  });
+
+  it("sanitizes string diagnostics while retaining valid numeric metadata", () => {
+    const parsed = parseSessionLossTelemetry(
+      line({
+        provider: "local",
+        sessionId: "wss://example.test/?apiKey=synthetic-key",
+        sessionAgeMs: 1,
+      }),
+    );
+    expect(parsed?.provider).toBe("local");
+    expect(parsed?.sessionAgeMs).toBe(1);
+    expect(JSON.stringify(parsed)).not.toContain("synthetic-key");
+  });
+});

packages/integrations/core/README.md

@@ -38,6 +38,26 @@ attachment has not returned a handle when the process exits, the host cannot
 explicitly release that session. A cancellable launch/early lease API is a separate
 follow-up; the configured remote session expiry remains the fallback.
 
+## Deadlines and disconnect diagnostics
+
+Facade `run` has a 60-second executor deadline and a 75-second client deadline.
+The SDK's `experimentalBatch` option `clientTimeoutMs` controls the entire round
+trip: by default it is the executor `timeout` plus 15000 ms, capped at 2147483647 ms.
+An explicit value must be an integer from `1` through `2147483647`. A client
+deadline raises `StagehandBatchTimeoutError`; it does not cancel or replay the
+callback. Executor-reported timeouts are ordinary tool errors.
+
+Snapshot and screenshot captures have a 120-second local deadline. The first two
+consecutive capture deadlines return tool errors; the third latches terminal loss.
+A successful tool resets the counter. A failed snapshot invalidates its previous
+IDs, and late completion cannot overwrite a newer snapshot. Terminal loss rejects
+queued calls before dispatch. There is no CDP reconnect or action replay.
+
+The optional stdio `--max-screenshot-base64-bytes=N` flag requires an integer of
+at least 1024. When enabled, compressed viewport fallbacks enforce both the byte
+budget and a 2000-pixel maximum side; without the flag this transport adjustment
+is not enabled.
+
 ## Local regression checks
 
 From the repository root, with workspace dependencies and the extension, SDK, and

packages/integrations/core/integration/facade-frames.test.ts

@@ -155,6 +155,7 @@ it("runs the shared facade against same-origin and out-of-process local frames",
       ),
     ).toBe(true);
     expect(generate).not.toHaveBeenCalled();
+    expect(tools.sessionLoss).toBeUndefined();
   } finally {
     try {
       await stagehand?.close();

packages/integrations/core/src/facade/index.ts

@@ -37,6 +37,7 @@ export {
 } from "./contract.js";
 export {
   StagehandFacadeTools,
+  StagehandFacadeSessionLostError,
   type StagehandFacadeRunReport,
   type StagehandFacadeToolsOptions,
 } from "./tools.js";

packages/integrations/core/src/facade/screenshot-transport.ts

@@ -27,24 +27,65 @@ export function screenshotBase64BudgetFromArgs(args: string[]): number | undefin
   return budget;
 }
 
+/**
+ * Model APIs reject images with a side longer than this. Anthropic allows
+ * 8000 px for a lone image but only 2000 px once a request carries many
+ * images, which every multi-step agent conversation does. Full-page captures
+ * of long pages exceed both and killed whole runs with a 400, so oversized
+ * captures fall back to the viewport like over-budget ones do.
+ */
+export const MAX_SCREENSHOT_SIDE_PX = 2000;
+
 export async function captureScreenshotWithinBase64Budget(
   capture: CaptureScreenshot,
   requested: ScreenshotOptions,
   maxBase64Bytes: number,
+  maxSidePx = MAX_SCREENSHOT_SIDE_PX,
 ): Promise<TransportSafeScreenshot> {
   const attempts = screenshotAttempts(requested);
   for (const [index, options] of attempts.entries()) {
     const image = await capture(options);
-    if (Buffer.byteLength(image.data, "utf8") <= maxBase64Bytes) {
+    if (Buffer.byteLength(image.data, "utf8") > maxBase64Bytes) continue;
+    const size = imageDimensions(image);
+    const tooLarge = size !== undefined && Math.max(size.width, size.height) > maxSidePx;
+    if (!tooLarge) {
       return { image, options, adjusted: index > 0 || !sameOptions(options, requested) };
     }
   }
 
   throw new Error(
-    `Screenshot exceeds the ${maxBase64Bytes}-byte MCP transport budget after compressed viewport retries.`,
+    `Screenshot exceeds the ${maxBase64Bytes}-byte MCP transport budget or the ${maxSidePx}px side limit after compressed viewport retries.`,
   );
 }
 
+/** Reads width/height from a PNG or JPEG header; undefined when unparseable. */
+export function imageDimensions(
+  image: StagehandFacadeScreenshot,
+): { width: number; height: number } | undefined {
+  const bytes = Buffer.from(image.data, "base64");
+  if (image.mimeType === "image/png") {
+    if (bytes.length < 24 || bytes.toString("ascii", 1, 4) !== "PNG") return undefined;
+    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+  }
+  // JPEG: walk the marker segments to the first SOFn (C0–CF except C4, C8, CC).
+  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) return undefined;
+  let offset = 2;
+  while (offset + 9 <= bytes.length) {
+    if (bytes[offset] !== 0xff) return undefined;
+    const marker = bytes[offset + 1]!;
+    if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7) || marker === 0x01) {
+      offset += 2;
+      continue;
+    }
+    const length = bytes.readUInt16BE(offset + 2);
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      return { height: bytes.readUInt16BE(offset + 5), width: bytes.readUInt16BE(offset + 7) };
+    }
+    offset += 2 + length;
+  }
+  return undefined;
+}
+
 function screenshotAttempts(requested: ScreenshotOptions): ScreenshotOptions[] {
   const initial: ScreenshotOptions = {
     fullPage: requested.fullPage ?? false,

packages/integrations/core/src/facade/stdio-server.ts

@@ -17,6 +17,7 @@ import {
   facadeSurfaceFromArgs,
   facadeToolsFor,
   SESSION_INFO_TOOL_NAME,
+  SESSION_LOST_TELEMETRY_PREFIX,
   ScreenshotInputSchema,
   SnapshotInputSchema,
 } from "./contract.js";
@@ -132,6 +133,7 @@ async function ensureResources(): Promise<FacadeResources> {
 
 async function createResources(): Promise<FacadeResources> {
   const config = stagehandFacadeConfigFromEnv();
+  const launchedAt = Date.now();
   const browser =
     config.browser.type === "browserbase"
       ? await browserbase.launch(config.browser.launchOptions)
@@ -141,6 +143,25 @@ async function createResources(): Promise<FacadeResources> {
     const tools = new StagehandFacadeTools(stagehand, {
       onRunReport: (report) =>
         process.stderr.write(`stagehand_playwright_compat ${JSON.stringify(report)}\n`),
+      // The browser is not recreated on purpose: a fresh session would silently
+      // change the evidence trail mid-task. Tools keep answering with the
+      // terminal error and the host decides what to do with the run.
+      // Age includes launch and initialization time. Compare it with configured
+      // timeout and remote session status when diagnosing a disconnect.
+      onSessionLost: (loss) =>
+        process.stderr.write(
+          `${SESSION_LOST_TELEMETRY_PREFIX}${JSON.stringify({
+            ...loss,
+            cause: sanitizeErrorMessage(loss.cause),
+            provider: browser.provider,
+            ...(browser.sessionId && { sessionId: browser.sessionId }),
+            sessionAgeMs: Date.now() - launchedAt,
+            ...(config.browser.type === "browserbase" &&
+              typeof config.browser.launchOptions.timeout === "number" && {
+                sessionTimeoutMs: config.browser.launchOptions.timeout * 1000,
+              }),
+          })}\n`,
+        ),
     });
     return { browser, stagehand, tools };
   } catch (error) {