stagehand 4.2.2a0.dev1606__tar.gz → 4.2.2a0.dev1615__tar.gz

{stagehand-4.2.2a0.dev1606 → stagehand-4.2.2a0.dev1615}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stagehand
-Version: 4.2.2a0.dev1606
+Version: 4.2.2a0.dev1615
 Summary: Browserbase's SDK for building browser agents
 Keywords: ai,agent,ai-agent,browser,browser-agent,browser-automation,computer-use,headless,playwright,cdp,llm,automation,web-scraping,testing
 Author: Browserbase

{stagehand-4.2.2a0.dev1606 → stagehand-4.2.2a0.dev1615}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stagehand"
-version = "4.2.2a0.dev1606"
+version = "4.2.2a0.dev1615"
 description = "Browserbase's SDK for building browser agents"
 readme = "README.md"
 requires-python = ">=3.11"

{stagehand-4.2.2a0.dev1606 → stagehand-4.2.2a0.dev1615}/src/stagehand/_extension/manifest.json

@@ -31,5 +31,5 @@
     }
   ],
   "options_page": "wake-service-worker.html",
-  "version": "1.1.1"
+  "version": "1.2.0"
 }

{stagehand-4.2.2a0.dev1606 → stagehand-4.2.2a0.dev1615}/src/stagehand/_extension/service-worker.js

@@ -7363,7 +7363,7 @@ function isRecord$1(value) {
 }
 var package_default$1 = {
 	name: "@browserbasehq/stagehand-protocol",
-	version: "2.1.1",
+	version: "3.0.0-alpha-c6b6f278c880d2f8b770ac0c1ecc63f248515968",
 	"private": true,
 	type: "module",
 	exports: {
@@ -8039,7 +8039,7 @@ var CacheMetadataSchema = strictObject({
 	status: CacheStatusSchema.meta({ description: "Whether server-side caching served this result, computed it, or was not consulted" }),
 	count: number$1().int().nonnegative().optional().meta({ description: "Times this cache key has been seen, including this request; compare with threshold to see how close the key is to being served" }),
 	threshold: number$1().int().positive().optional().meta({ description: "Hit-count threshold in effect for this key" }),
-	missReason: string().optional().meta({ description: "Why the cache did not serve this request; misses only. Reported by the server: \"not_found\", \"threshold\", \"empty_array\", \"timeout\", \"error\", \"bypass\", \"screenshot\", \"not_enabled\", \"no_cache_key\". Reported locally: \"read_failed\" (the cache request itself failed) and \"replay_failed\" (a cached value was found but could not be applied)" }),
+	missReason: string().optional().meta({ description: "Why the cache did not serve this request; misses only. Reported by the server: \"not_found\", \"threshold\", \"empty_array\", \"timeout\", \"error\", \"bypass\", \"screenshot\", \"not_enabled\", \"no_cache_key\". Reported locally: \"timeout\" (the cache read exceeded its budget), \"read_failed\" (another cache read failure), \"payload_too_large\" (the serialized cache request exceeds 25,000,000 UTF-8 bytes), and \"replay_failed\" (a cached value was found but could not be applied)" }),
 	tokensSaved: CacheTokenSavingsSchema.optional().meta({ description: "LLM tokens avoided by serving this request from cache; hits only" })
 }).meta({ id: "CacheMetadata" });
 var StagehandResultMetadataSchema = strictObject({
@@ -8295,6 +8295,47 @@ var LocatorDescriptorSchema = strictObject({
 	pageId: string(),
 	...LocatorSchema.shape
 }).meta({ id: "LocatorDescriptor" });
+/** One HTTP attempt; the caller owns retries and response interpretation. */
+var BrowserbaseRequestParamsSchema = strictObject({
+	operation: _enum([
+		"gateway.responses",
+		"cache.get",
+		"cache.set"
+	]),
+	headers: record(string(), string()).meta({ description: "Application headers. SDKs validate names and values, omit caller-supplied Host, Content-Length, hop-by-hop and forwarding headers, and supply x-bb-api-key and, for gateway.responses, x-bb-session-id." }),
+	body: string().meta({ description: "JSON request body sent as UTF-8 text" }),
+	remainingTimeoutMs: number$1().nonnegative().optional().meta({ description: "Remaining caller budget in milliseconds, including response-body buffering; omission adds no transport deadline" })
+}).meta({ id: "BrowserbaseRequestParams" });
+var BrowserbaseRequestResultSchema = discriminatedUnion("type", [strictObject({
+	type: literal("response"),
+	status: int().min(200).max(599),
+	statusText: string(),
+	headers: record(string(), string()).meta({ description: "Lowercase names with one value per name after SDK HTTP normalization; repeated fields are collapsed. Header bytes use Latin-1 code points. content-encoding and content-length are omitted." }),
+	body: string().meta({ description: "Fully buffered response body decoded as UTF-8 text, with a leading BOM removed and invalid byte sequences replaced" })
+}).meta({
+	id: "BrowserbaseHttpResponse",
+	description: "Buffered HTTP response with SDK-normalized headers and text. Redirect responses are returned without following them."
+}), strictObject({
+	type: literal("error"),
+	reason: _enum([
+		"network",
+		"cancelled",
+		"timeout",
+		"unavailable",
+		"disconnected"
+	]),
+	message: string()
+}).meta({
+	id: "BrowserbaseTransportError",
+	description: "Transport failure without an HTTP response; disconnected is synthesized locally when RPC closes"
+})]).meta({ id: "BrowserbaseRequestResult" });
+var BrowserbaseCancelParamsSchema = strictObject({
+	requestId: JSONRPCRequestIdSchema,
+	reason: _enum(["cancelled", "timeout"])
+}).meta({
+	id: "BrowserbaseCancelParams",
+	description: "Cancel a browserbase.request by its JSON-RPC ID on the same connection; ignore completed or unknown IDs"
+});
 var ImplementationInfoSchema = strictObject({
 	name: string().min(1),
 	version: string().min(1)
@@ -8311,8 +8352,7 @@ var StagehandInitParamsSchema = strictObject({
 	protocolVersion: StagehandProtocolVersionSchema,
 	clientInfo: ImplementationInfoSchema,
 	browserCdpUrl: string().min(1).optional(),
-	apiKey: string().min(1).optional(),
-	apiUrl: url().refine((value) => !value.includes("?") && !value.includes("#"), "Stagehand apiUrl must not include a query string or fragment").refine((value) => !new URL(value).pathname.replace(/\/+$/, "").endsWith("/v1"), { message: "Stagehand apiUrl must be a service origin without /v1" }).optional().meta({ description: "Stagehand API base URL override for managed services such as Model Gateway and server-side caching" }),
+	browserbase: literal("client").optional(),
 	browser: BrowserSessionMetadataSchema.optional(),
 	model: union([ModelConfigSchema, ClientModelReferenceSchema]).optional().meta({ description: "Default model configuration; when omitted and a Browserbase Model Gateway session is available, Browserbase selects a model automatically for inference calls" }),
 	telemetry: TelemetryConfigSchema.optional(),
@@ -8326,8 +8366,14 @@ var StagehandInitParamsSchema = strictObject({
 	systemPrompt: string().optional(),
 	selfHeal: boolean().optional(),
 	domSettleTimeoutMs: number$1().int().positive().optional(),
-	cache: CachingSchema.optional().meta({ description: "Server-side caching of act/observe/extract results for this instance: a boolean toggle, or an object with an optional hit-count threshold. Requires a Browserbase apiKey and browser sessionId. Can be overridden per request via options.cache." })
-}).meta({ id: "StagehandInitParams" });
+	cache: CachingSchema.optional().meta({ description: "Server-side caching of act/observe/extract results for this instance: a boolean toggle, or an object with an optional hit-count threshold. Requires client Browserbase transport and a browser sessionId. Can be overridden per request via options.cache." })
+}).refine((params) => params.browserbase === void 0 || params.browser !== void 0, {
+	message: "Client Browserbase transport requires browser metadata",
+	path: ["browserbase"]
+}).meta({
+	id: "StagehandInitParams",
+	dependentRequired: { browserbase: ["browser"] }
+});
 var StagehandActParamsSchema = strictObject({
 	pageId: string().min(1),
 	instruction: union([string().min(1), ActionSchema]),
@@ -8658,6 +8704,11 @@ var StagehandMethods = {
 		paramsWire: { opaqueKeys: ["input"] },
 		resultWire: { opaqueKeys: ["value"] }
 	},
+	browserbaseRequest: {
+		name: "browserbase.request",
+		params: BrowserbaseRequestParamsSchema,
+		result: BrowserbaseRequestResultSchema
+	},
 	llmGenerate: {
 		name: "llm.generate",
 		params: LLMGenerateParamsSchema,
@@ -9036,6 +9087,11 @@ var StagehandRpcRequestSchema = union(Object.values(StagehandMethods).map((metho
 	params: wireSchema(method.params, "paramsWire" in method ? method.paramsWire : void 0)
 }))).meta({ id: "StagehandRpcRuntimeRequest" });
 var StagehandNotifications = {
+	browserbaseCancel: {
+		name: "browserbase.cancel",
+		params: BrowserbaseCancelParamsSchema,
+		paramsWire: void 0
+	},
 	log: {
 		name: "stagehand.log",
 		params: StagehandLogSchema,
@@ -9061,6 +9117,45 @@ function getStagehandMethod(name) {
 	return stagehandMethodsByName.get(name);
 }
 //#endregion
+//#region clients/browserbaseClient.ts
+/** Requests one buffered Browserbase HTTP attempt over the connected SDK. */
+async function requestBrowserbase(client, params, signal) {
+	let result;
+	try {
+		result = await client.send(StagehandMethods.browserbaseRequest, params, {
+			signal,
+			onAbort: (requestId, reason) => client.notify(StagehandNotifications.browserbaseCancel, {
+				requestId,
+				reason: isTimeout(reason) ? "timeout" : "cancelled"
+			})
+		});
+	} catch (error) {
+		if (signal?.aborted) throw new DOMException(isTimeout(signal.reason) ? "Browserbase request timed out" : "Browserbase request cancelled", isTimeout(signal.reason) ? "TimeoutError" : "AbortError");
+		throw new Error(client.closed ? "Browserbase connection is disconnected" : "Browserbase RPC request failed", { cause: { error } });
+	}
+	if (result.type === "error") switch (result.reason) {
+		case "network": throw new TypeError("fetch failed", { cause: result });
+		case "cancelled": throw new DOMException(result.message, "AbortError");
+		case "timeout": throw new DOMException(result.message, "TimeoutError");
+		case "unavailable":
+		case "disconnected": throw new Error(result.message, { cause: result });
+	}
+	const response = new Response([
+		204,
+		205,
+		304
+	].includes(result.status) ? null : result.body, {
+		status: result.status,
+		statusText: result.statusText,
+		headers: result.headers
+	});
+	if (!new Headers(result.headers).has("content-type")) response.headers.delete("content-type");
+	return response;
+}
+function isTimeout(reason) {
+	return reason instanceof Error && reason.name === "TimeoutError";
+}
+//#endregion
 //#region clients/chromeRuntimeClient.ts
 var ChromeBindingMessageSchema = string();
 var ChromeBindingSchema = custom((value) => typeof value === "function", "Chrome runtime binding is not installed");
@@ -11265,7 +11360,8 @@ var RPCClient = class {
 		this.runtime.onclose = (reason) => this.close(reason);
 		this.runtime.onerror = (error) => this.close(error);
 	}
-	async send(method, params) {
+	async send(method, params, options = {}) {
+		options.signal?.throwIfAborted();
 		if (this.closed) throw new Error("RPC client is closed");
 		const parentContext = context.active();
 		const span = this.router.runtime.tracing.tracer.startSpan(method.name, {
@@ -11288,10 +11384,32 @@ var RPCClient = class {
 					...getTraceContextFields(requestContext)
 				});
 				span.setAttribute("jsonrpc.request.id", String(request.id));
-				const response = this.waitForResponse(id, method);
-				const [, result] = await Promise.all([this.runtime.send(request).catch((error) => {
-					this.rejectPending(id, asError(error));
-				}), response]);
+				const { signal } = options;
+				let dispatched = false;
+				let aborted = false;
+				const notifyAbort = () => {
+					if (this.closed) return;
+					try {
+						Promise.resolve(options.onAbort?.(id, signal?.reason)).catch(() => {});
+					} catch {}
+				};
+				const abort = () => {
+					if (!this.pending.has(id)) return;
+					aborted = true;
+					this.rejectPending(id, asError(signal?.reason));
+					if (dispatched) notifyAbort();
+				};
+				const response = this.waitForResponse(id, method, () => signal?.removeEventListener("abort", abort));
+				signal?.addEventListener("abort", abort, { once: true });
+				if (signal?.aborted) {
+					abort();
+					return await response;
+				}
+				const dispatch = this.runtime.send(request).then(() => {
+					dispatched = true;
+					if (aborted) notifyAbort();
+				}, (error) => this.rejectPending(id, asError(error)));
+				const [, result] = await Promise.all([dispatch, response]);
 				return result;
 			});
 		} catch (error) {
@@ -11318,12 +11436,18 @@ var RPCClient = class {
 		this.runtime.onerror = void 0;
 		this.runtime.close();
 	}
-	waitForResponse(id, method) {
+	waitForResponse(id, method, cleanup = () => {}) {
 		return new Promise((resolve, reject) => {
 			this.pending.set(id, {
 				method,
-				resolve,
-				reject
+				resolve(value) {
+					cleanup();
+					resolve(value);
+				},
+				reject(error) {
+					cleanup();
+					reject(error);
+				}
 			});
 		});
 	}
@@ -11716,7 +11840,7 @@ async function normalizeFile(file) {
 	if (!file.name) throw new TypeError("setInputFiles(): file payload name cannot be empty");
 	if (typeof file.buffer === "string") {
 		const nodeBuffer = globalThis.Buffer;
-		if (nodeBuffer ? nodeBuffer.byteLength(file.buffer, "utf8") > MAX_INPUT_FILE_BYTES : utf8ByteLengthExceeds(file.buffer, MAX_INPUT_FILE_BYTES)) throw new RangeError(`setInputFiles(): file is larger than the 50 MiB upload limit`);
+		if (nodeBuffer ? nodeBuffer.byteLength(file.buffer, "utf8") > MAX_INPUT_FILE_BYTES : utf8ByteLengthExceeds$1(file.buffer, MAX_INPUT_FILE_BYTES)) throw new RangeError(`setInputFiles(): file is larger than the 50 MiB upload limit`);
 	}
 	const bytes = typeof file.buffer === "string" ? new TextEncoder().encode(file.buffer) : file.buffer instanceof ArrayBuffer ? new Uint8Array(file.buffer) : file.buffer;
 	if (bytes.byteLength > MAX_INPUT_FILE_BYTES) throw new RangeError(`setInputFiles(): file is larger than the 50 MiB upload limit`);
@@ -11728,7 +11852,7 @@ async function normalizeFile(file) {
 		...file.lastModified === void 0 ? {} : { lastModified: file.lastModified }
 	};
 }
-function utf8ByteLengthExceeds(value, limit) {
+function utf8ByteLengthExceeds$1(value, limit) {
 	let byteLength = 0;
 	for (let index = 0; index < value.length; index++) {
 		const codeUnit = value.charCodeAt(index);
@@ -12522,13 +12646,16 @@ var StagehandClientExtractOptionsSchema = ExtractOptionsSchema.extend({
 	ignoreLocators: array$1(_instanceof(Locator$1)).optional(),
 	page: _instanceof(Page$1).optional()
 }).meta({ id: "StagehandClientExtractOptions" });
-var StagehandClientCreateConfigSchema = StagehandInitParamsSchema.omit({
+var StagehandClientCreateConfigSchema = strictObject(StagehandInitParamsSchema.shape).omit({
+	browserbase: true,
 	protocolVersion: true,
 	clientInfo: true,
 	browserCdpUrl: true,
 	logLevel: true,
 	browser: true
 }).extend({
+	apiKey: string().min(1).optional().meta({ description: "Browserbase API key. A Browserbase browser uses the key supplied to its launch/connect factory; this option does not override that key." }),
+	apiUrl: url({ protocol: /^https?$/ }).refine((value) => !value.includes("?") && !value.includes("#"), "Stagehand apiUrl must not include a query string or fragment").refine((value) => !new URL(value).pathname.replace(/\/+$/, "").endsWith("/v1"), { message: "Stagehand apiUrl must be a service origin without /v1" }).optional().meta({ description: "Stagehand API base URL override for managed services such as Model Gateway and server-side caching" }),
 	model: union([ModelConfigSchema, ClientLLMSchema]).optional(),
 	logging: StagehandClientLoggingConfigSchema.default({
 		level: "info",
@@ -18248,10 +18375,10 @@ function mergeFramesIntoSnapshot(context, perFrameMaps, perFrameOutlines, absPre
 //#endregion
 //#region clients/cacheClient.ts
 /**
-* HTTP client for the Stagehand API's stateless cache routes (POST /cache/get
-* and POST /cache/set). Owns transport concerns only: endpoint resolution,
-* auth headers, timeouts, and schema validation of requests going out and
-* responses coming back. All caching decisions (when to read, what to write,
+* Client for the Stagehand API's stateless cache routes (POST /cache/get
+* and POST /cache/set). Sends requests through the connected SDK and owns
+* request size limits, timeouts, and response validation.
+* All caching decisions (when to read, what to write,
 * fallback behavior) live in services/cacheService.ts, this client's only
 * consumer. See stagehand-api-v3's lib/cache/statelessCache.ts for the
 * server-side contract.
@@ -18259,6 +18386,8 @@ function mergeFramesIntoSnapshot(context, perFrameMaps, perFrameOutlines, absPre
 /** Ceiling for a single cache HTTP round-trip so a slow cache can only ever
 * add a bounded delay to the action it fronts. */
 var CACHE_REQUEST_TIMEOUT_MS = 5e3;
+/** Maximum UTF-8 JSON body size for a cache read or write. */
+var CACHE_REQUEST_MAX_BYTES = 25e6;
 var AXNodeSchema = custom((value) => typeof value === "object" && value !== null);
 var CdpTreeSchema = object$1({
 	rootFrameId: string(),
@@ -18295,7 +18424,7 @@ object$1({
 	llmUsage: CacheLlmUsageSchema.optional()
 });
 var CacheGetResponseSchema = object$1({
-	/** Null only when the server could not build a key (empty tree / bad URL). */
+	/** Null when no cache key is available, including a locally skipped request. */
 	cacheKey: string().nullable(),
 	hit: boolean(),
 	/** Present only on a hit. */
@@ -18317,7 +18446,7 @@ var CacheGetResponseSchema = object$1({
 	}).optional()
 });
 var CacheSetResponseSchema = object$1({
-	/** Null only when the server could not build a key. */
+	/** Null when no cache key is available, including a locally skipped request. */
 	cacheKey: string().nullable(),
 	/** True when the write was issued to Redis. */
 	written: boolean(),
@@ -18332,9 +18461,8 @@ var ApiResponseEnvelopeSchema = discriminatedUnion("success", [object$1({
 	message: string().optional()
 })]);
 var CacheClient = class {
-	constructor(apiUrl, apiKey) {
-		this.apiUrl = apiUrl;
-		this.apiKey = apiKey;
+	constructor(transport) {
+		this.transport = transport;
 	}
 	async get(request) {
 		return await this.post("/cache/get", request, CacheGetResponseSchema);
@@ -18343,51 +18471,67 @@ var CacheClient = class {
 		return await this.post("/cache/set", request, CacheSetResponseSchema);
 	}
 	async post(path, request, responseSchema) {
-		const response = await fetch(`${this.apiUrl}${path}`, {
-			method: "POST",
-			headers: {
-				"content-type": "application/json",
-				"x-bb-api-key": this.apiKey
-			},
-			body: JSON.stringify(request),
-			signal: AbortSignal.timeout(CACHE_REQUEST_TIMEOUT_MS)
-		});
-		if (!response.ok) throw new Error(`Cache request ${path} failed with status ${response.status}`);
-		const envelope = ApiResponseEnvelopeSchema.safeParse(await response.json());
-		if (!envelope.success) throw new Error(`Cache request ${path} returned an unrecognized envelope`);
-		if (!envelope.data.success) throw new Error(`Cache request ${path} rejected: ${envelope.data.message ?? "unknown error"}`);
-		const parsed = responseSchema.safeParse(envelope.data.data);
-		if (!parsed.success) throw new Error(`Cache request ${path} returned an unexpected payload: ${parsed.error.message}`);
-		return parsed.data;
+		const deadline = performance.now() + CACHE_REQUEST_TIMEOUT_MS;
+		const controller = new AbortController();
+		const timeout = () => controller.abort(new DOMException("Cache request timed out", "TimeoutError"));
+		const timer = setTimeout(timeout, CACHE_REQUEST_TIMEOUT_MS);
+		try {
+			const body = JSON.stringify(request);
+			if (utf8ByteLengthExceeds(body, CACHE_REQUEST_MAX_BYTES)) return responseSchema.parse(path === "/cache/get" ? {
+				cacheKey: null,
+				hit: false,
+				missReason: "payload_too_large"
+			} : {
+				cacheKey: null,
+				written: false,
+				skippedReason: "payload_too_large"
+			});
+			const remainingTimeoutMs = Math.max(0, deadline - performance.now());
+			if (remainingTimeoutMs === 0) timeout();
+			controller.signal.throwIfAborted();
+			if (!this.transport.request) throw new Error("Client Browserbase transport is unavailable");
+			const response = await this.transport.request({
+				operation: path === "/cache/get" ? "cache.get" : "cache.set",
+				headers: { "content-type": "application/json" },
+				body,
+				remainingTimeoutMs
+			}, controller.signal);
+			if (!response.ok) throw new Error(`Cache request ${path} failed with status ${response.status}`);
+			const envelope = ApiResponseEnvelopeSchema.safeParse(await response.json());
+			if (!envelope.success) throw new Error(`Cache request ${path} returned an unrecognized envelope`);
+			if (!envelope.data.success) throw new Error(`Cache request ${path} rejected: ${envelope.data.message ?? "unknown error"}`);
+			const parsed = responseSchema.safeParse(envelope.data.data);
+			if (!parsed.success) throw new Error(`Cache request ${path} returned an unexpected payload: ${parsed.error.message}`);
+			return parsed.data;
+		} finally {
+			clearTimeout(timer);
+		}
 	}
 };
-//#endregion
-//#region clients/stagehandApi.ts
-var REGION_API_URLS = {
-	"us-west-2": "https://api.stagehand.browserbase.com",
-	"us-east-1": "https://api.use1.stagehand.browserbase.com",
-	"eu-central-1": "https://api.euc1.stagehand.browserbase.com",
-	"ap-southeast-1": "https://api.apse1.stagehand.browserbase.com"
-};
-var DEFAULT_REGION = "us-west-2";
-/** Resolves the regional Stagehand API endpoint for a Browserbase session. */
-function apiUrlForRegion(region, apiUrl) {
-	return `${(apiUrl ?? REGION_API_URLS[region ?? DEFAULT_REGION]).replace(/\/+$/, "")}/v1`;
+function utf8ByteLengthExceeds(value, limit) {
+	if (value.length > limit) return true;
+	let byteLength = 0;
+	for (let index = 0; index < value.length; index++) {
+		const codeUnit = value.charCodeAt(index);
+		if (codeUnit <= 127) byteLength += 1;
+		else if (codeUnit <= 2047) byteLength += 2;
+		else if (codeUnit >= 55296 && codeUnit <= 56319 && index + 1 < value.length && value.charCodeAt(index + 1) >= 56320 && value.charCodeAt(index + 1) <= 57343) {
+			byteLength += 4;
+			index += 1;
+		} else byteLength += 3;
+		if (byteLength > limit) return true;
+	}
+	return false;
 }
 //#endregion
 //#region services/cacheService.ts
-/**
-* Builds the per-instance cache context from init params. Returns undefined
-* when caching is impossible: the stateless routes authenticate with the
-* Browserbase API key and resolve the project from the session id, so both
-* are required.
-*/
-function buildCacheContext(initParams) {
+/** Builds a cache context when client Browserbase transport is configured. */
+function buildCacheContext(initParams, request) {
 	const sessionId = initParams.browser?.sessionId;
-	if (!initParams.apiKey || !sessionId) return void 0;
+	if (!sessionId || initParams.browserbase !== "client") return void 0;
 	return {
 		sessionId,
-		client: new CacheClient(apiUrlForRegion(initParams.browser?.region, initParams.apiUrl), initParams.apiKey),
+		client: new CacheClient({ request }),
 		defaultCaching: initParams.cache ?? true
 	};
 }
@@ -18508,10 +18652,12 @@ async function withCache({ method, page, data, caching, bypass, context, logger,
 		data: withCacheThreshold(data, resolvedCaching)
 	};
 	let getResponse = null;
+	let readFailureReason = "read_failed";
 	try {
 		getResponse = await runLocatorStep(progress, "reading cache", () => context.client.get(baseRequest));
 	} catch (error) {
 		progress?.throwIfStopped();
+		readFailureReason = error instanceof Error && error.name === "TimeoutError" ? "timeout" : "read_failed";
 		logger.warn("Cache read failed; executing without cache", {
 			category: "cache",
 			method,
@@ -18548,12 +18694,12 @@ async function withCache({ method, page, data, caching, bypass, context, logger,
 			cacheKey: getResponse.cacheKey ?? "",
 			missReason: cacheMetadata.missReason ?? "unknown"
 		});
-	} else cacheMetadata = missMetadata(null, "read_failed");
+	} else cacheMetadata = missMetadata(null, readFailureReason);
 	progress?.throwIfStopped();
 	const outcome = await execute();
 	progress?.throwIfStopped();
 	outcome.result.metadata.cache = cacheMetadata;
-	if (outcome.cacheValue !== void 0 && outcome.cacheValue !== null) try {
+	if (getResponse?.missReason !== "payload_too_large" && outcome.cacheValue !== void 0 && outcome.cacheValue !== null) try {
 		const setResponse = await runLocatorStep(progress, "writing cache", () => context.client.set({
 			...baseRequest,
 			value: outcome.cacheValue,
@@ -51076,43 +51222,53 @@ async function generateWithClientLlm(request, input) {
 }
 //#endregion
 //#region llm/gatewayClient.ts
-/** Builds the credentials needed for Browserbase Model Gateway inference. */
-function buildGatewayContext(initParams) {
-	const sessionId = initParams.browser?.sessionId;
-	if (!initParams.apiKey || !sessionId) return void 0;
-	return {
-		apiUrl: apiUrlForRegion(initParams.browser?.region, initParams.apiUrl),
-		apiKey: initParams.apiKey,
-		sessionId
+var CLIENT_GATEWAY_BASE_URL = "https://stagehand.invalid/llm";
+var CLIENT_GATEWAY_API_KEY = "stagehand-client-gateway";
+/** Selects the configured transport for Browserbase Model Gateway inference. */
+function buildGatewayContext(initParams, request) {
+	if (!initParams.browser?.sessionId || initParams.browserbase !== "client") return void 0;
+	return { request };
+}
+function withoutModel(fetch) {
+	return async (input, init) => {
+		if (typeof init?.body !== "string") return await fetch(input, init);
+		let body;
+		try {
+			body = JSON.parse(init.body);
+		} catch {
+			return await fetch(input, init);
+		}
+		if (!body || typeof body !== "object" || Array.isArray(body)) return await fetch(input, init);
+		const routedBody = { ...body };
+		delete routedBody.model;
+		return await fetch(input, {
+			...init,
+			body: JSON.stringify(routedBody)
+		});
+	};
+}
+function clientGatewayFetch(gateway, config) {
+	const hasAuthorization = Object.keys(config?.headers ?? {}).some((name) => name.toLowerCase() === "authorization");
+	return async (input, init) => {
+		if (input !== `${CLIENT_GATEWAY_BASE_URL}/responses` || init?.method !== "POST" || typeof init.body !== "string") throw new TypeError("Unexpected Model Gateway request");
+		if (!gateway.request) throw new Error("Client Browserbase transport is unavailable");
+		const headers = new Headers(init.headers);
+		if (!hasAuthorization) headers.delete("authorization");
+		return await gateway.request({
+			operation: "gateway.responses",
+			headers: Object.fromEntries(headers),
+			body: init.body
+		}, init.signal ?? void 0);
 	};
 }
-var fetchWithoutModel = async (input, init) => {
-	if (typeof init?.body !== "string") return await boundFetch(input, init);
-	let body;
-	try {
-		body = JSON.parse(init.body);
-	} catch {
-		return await boundFetch(input, init);
-	}
-	if (!body || typeof body !== "object" || Array.isArray(body)) return await boundFetch(input, init);
-	const routedBody = { ...body };
-	delete routedBody.model;
-	return await boundFetch(input, {
-		...init,
-		body: JSON.stringify(routedBody)
-	});
-};
 /** Creates an OpenAI Responses model backed by Browserbase Model Gateway. */
 function createGatewayLanguageModel(config, gateway) {
+	const fetch = clientGatewayFetch(gateway, config);
 	return createOpenAI({
-		apiKey: gateway.apiKey,
-		baseURL: `${gateway.apiUrl}/llm`,
-		headers: {
-			...config?.headers,
-			"x-bb-api-key": gateway.apiKey,
-			"x-bb-session-id": gateway.sessionId
-		},
-		fetch: config ? boundFetch : fetchWithoutModel
+		apiKey: CLIENT_GATEWAY_API_KEY,
+		baseURL: CLIENT_GATEWAY_BASE_URL,
+		headers: config?.headers,
+		fetch: config ? fetch : withoutModel(fetch)
 	}).responses(config?.modelName ?? "auto");
 }
 //#endregion
@@ -51726,7 +51882,7 @@ function createStagehandController(runtime, options = {}) {
 			const state = runtime.state.getState();
 			if (state.status !== "initialized") throw new Error("Stagehand must be initialized before acting");
 			const model = params.options?.model ?? state.initParams.model;
-			const gateway = buildGatewayContext(state.initParams);
+			const gateway = buildGatewayContext(state.initParams, runtime.adapters.clientBrowserbaseRequest);
 			if (!model && !gateway) throw new Error("An LLM was not configured during Stagehand initialization");
 			const result = await act({
 				params,
@@ -51737,7 +51893,7 @@ function createStagehandController(runtime, options = {}) {
 				systemPrompt: state.initParams.systemPrompt,
 				selfHeal: state.initParams.selfHeal,
 				domSettleTimeoutMs: state.initParams.domSettleTimeoutMs,
-				cache: buildCacheContext(state.initParams),
+				cache: buildCacheContext(state.initParams, runtime.adapters.clientBrowserbaseRequest),
 				gateway
 			});
 			runtime.metrics.record("act", result.metadata.usage);
@@ -51750,7 +51906,7 @@ function createStagehandController(runtime, options = {}) {
 			const state = runtime.state.getState();
 			if (state.status !== "initialized") throw new Error("Stagehand must be initialized before observing");
 			const model = params.options?.model ?? state.initParams.model;
-			const gateway = buildGatewayContext(state.initParams);
+			const gateway = buildGatewayContext(state.initParams, runtime.adapters.clientBrowserbaseRequest);
 			if (!model && !gateway) throw new Error("An LLM was not configured during Stagehand initialization");
 			const result = await observe({
 				params,
@@ -51759,7 +51915,7 @@ function createStagehandController(runtime, options = {}) {
 				clientLLMGenerate: runtime.adapters.clientLLMGenerate,
 				logger,
 				systemPrompt: state.initParams.systemPrompt,
-				cache: buildCacheContext(state.initParams),
+				cache: buildCacheContext(state.initParams, runtime.adapters.clientBrowserbaseRequest),
 				gateway
 			});
 			runtime.metrics.record("observe", result.metadata.usage);
@@ -51772,7 +51928,7 @@ function createStagehandController(runtime, options = {}) {
 			const state = runtime.state.getState();
 			if (state.status !== "initialized") throw new Error("Stagehand must be initialized before extracting");
 			const model = params.options?.model ?? state.initParams.model;
-			const gateway = buildGatewayContext(state.initParams);
+			const gateway = buildGatewayContext(state.initParams, runtime.adapters.clientBrowserbaseRequest);
 			if (!model && !gateway) throw new Error("An LLM was not configured during Stagehand initialization");
 			const result = await extract({
 				params,
@@ -51781,7 +51937,7 @@ function createStagehandController(runtime, options = {}) {
 				clientLLMGenerate: runtime.adapters.clientLLMGenerate,
 				logger,
 				systemPrompt: state.initParams.systemPrompt,
-				cache: buildCacheContext(state.initParams),
+				cache: buildCacheContext(state.initParams, runtime.adapters.clientBrowserbaseRequest),
 				gateway
 			});
 			runtime.metrics.record("extract", result.metadata.usage);
@@ -54300,7 +54456,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.1.1",
+	version: "1.2.0-alpha-c6b6f278c880d2f8b770ac0c1ecc63f248515968",
 	"private": true,
 	type: "module",
 	scripts: {
@@ -58185,6 +58341,9 @@ var defaultBrowserSessionFactory = async () => {
 };
 var discardLog = () => {};
 var discardPageCDPEvent = () => {};
+var unavailableClientBrowserbase = async () => {
+	throw new Error("The connected SDK did not register a Browserbase transport");
+};
 var unavailableClientLLM = async () => {
 	throw new Error("The connected SDK did not register a client-side LLM");
 };
@@ -58193,6 +58352,7 @@ function createStagehandRuntime(adapters = {}, tracing = createStagehandTracing(
 		browserSessionFactory: adapters.browserSessionFactory ?? defaultBrowserSessionFactory,
 		emitLog: adapters.emitLog ?? discardLog,
 		clientLLMGenerate: adapters.clientLLMGenerate ?? unavailableClientLLM,
+		clientBrowserbaseRequest: adapters.clientBrowserbaseRequest ?? unavailableClientBrowserbase,
 		emitPageCDPEvent: adapters.emitPageCDPEvent ?? discardPageCDPEvent,
 		emitPageEvent: adapters.emitPageEvent ?? discardPageCDPEvent
 	}, tracing);
@@ -58266,7 +58426,7 @@ var StagehandRuntime = class {
 	async generateLlm(input) {
 		const state = this.state.getState();
 		const model = state.status === "initialized" ? state.initParams.model : void 0;
-		const gateway = state.status === "initialized" ? buildGatewayContext(state.initParams) : void 0;
+		const gateway = state.status === "initialized" ? buildGatewayContext(state.initParams, this.adapters.clientBrowserbaseRequest) : void 0;
 		if (!model && !gateway) throw new Error("An LLM was not configured during Stagehand initialization");
 		return await generate(model, input, this.adapters.clientLLMGenerate, gateway);
 	}
@@ -60059,6 +60219,10 @@ function startStagehandServiceWorker(scope = globalThis, runtime) {
 				console.error("[stagehand] Failed to emit page event notification", error);
 			});
 		},
+		clientBrowserbaseRequest: async (params, signal) => {
+			if (!rpcClient) throw new Error("Stagehand RPC client is not connected");
+			return await requestBrowserbase(rpcClient, params, signal);
+		},
 		clientLLMGenerate: async (params) => {
 			if (!rpcClient) throw new Error("Stagehand RPC client is not connected");
 			return await rpcClient.send(StagehandMethods.llmGenerate, params);