Introduce Page.onResponse

packages/extension/responseHandleTable.ts

@@ -25,6 +25,7 @@ export class ResponseHandleNotFoundError extends Error {
  * server-side Response object.
  */
 export class ResponseHandleTable {
+  private readonly handlesByResponse = new WeakMap<Response, string>();
   private readonly entries = new Map<string, ResponseHandleEntry>();
   private readonly maxHandles: number;
   private readonly createHandle: () => string;
@@ -43,13 +44,16 @@ export class ResponseHandleTable {
   }
 
   register(pageId: string, response: Response): string {
+    const existing = this.handlesByResponse.get(response);
+    if (existing && this.entries.get(existing)?.pageId === pageId) return existing;
     const responseId = this.nextHandle();
     while (this.entries.size >= this.maxHandles) {
       const oldestResponseId = this.entries.keys().next().value as string | undefined;
       if (oldestResponseId === undefined) break;
       this.delete(oldestResponseId);
     }
     this.entries.set(responseId, { pageId, response });
+    this.handlesByResponse.set(response, responseId);
     return responseId;
   }
 
@@ -73,6 +77,7 @@ export class ResponseHandleTable {
     const entry = this.entries.get(responseId);
     if (!entry) return;
     this.entries.delete(responseId);
+    this.handlesByResponse.delete(entry.response);
     entry.response.dispose(new ResponseHandleNotFoundError(responseId));
   }
 

packages/extension/runtime.ts

@@ -200,6 +200,10 @@ export type UnderstudyRuntimePage = {
     listener: (event: PageCDPEvent) => void,
     signal?: AbortSignal,
   ): Promise<() => void>;
+  subscribeResponse(
+    listener: (response: Response) => void,
+    signal?: AbortSignal,
+  ): Promise<() => void>;
   subscribeWebMCPToolsChanged(
     listener: (event: WebMCPToolsEvent) => void,
     signal?: AbortSignal,
@@ -866,6 +870,19 @@ export class StagehandRuntime {
             subscription.controller.signal,
           );
           break;
+        case "response":
+          subscription.dispose = await page.subscribeResponse((response) => {
+            if (!isActive()) return;
+            this.adapters.emitPageEvent({
+              subscriptionId: params.subscriptionId,
+              event: "response",
+              pageId: params.pageId,
+              sessionId: response.session.id ?? params.pageId,
+              targetId: response.page.conn.targetIdForSession(response.session.id) ?? params.pageId,
+              response: this.responseDescriptor(params.pageId, response),
+            });
+          }, subscription.controller.signal);
+          break;
         case "toolsadded":
         case "toolsremoved":
           subscription.dispose = await page.subscribeWebMCPToolsChanged((event) => {
@@ -1179,6 +1196,17 @@ export class StagehandRuntime {
     return pageId;
   }
 
+  private responseDescriptor(pageId: string, response: Response) {
+    return {
+      responseId: this.responseHandles.register(pageId, response),
+      url: response.url(),
+      status: response.status(),
+      statusText: response.statusText(),
+      headers: response.headers(),
+      fromServiceWorker: response.fromServiceWorker(),
+    };
+  }
+
   private pageNavigationResult(
     pageId: string,
     page: UnderstudyRuntimePage,
@@ -1187,18 +1215,7 @@ export class StagehandRuntime {
     const pageRef = pageRefFromUnderstudyPage(page);
     if (!(response instanceof Response)) return { page: pageRef, response: null };
 
-    const responseId = this.responseHandles.register(pageId, response);
-    return {
-      page: pageRef,
-      response: {
-        responseId,
-        url: response.url(),
-        status: response.status(),
-        statusText: response.statusText(),
-        headers: response.headers(),
-        fromServiceWorker: response.fromServiceWorker(),
-      },
-    };
+    return { page: pageRef, response: this.responseDescriptor(pageId, response) };
   }
 
   requireBrowserSession(): StagehandBrowserSession {

packages/extension/types/private/network.ts

@@ -1,4 +1,5 @@
 import { Protocol } from "devtools-protocol";
+import type { Response } from "../../understudy/response.js";
 
 /** Metadata tracked for each network request currently in-flight. */
 export type NetworkRequestInfo = {
@@ -15,9 +16,10 @@ export type NetworkRequestInfo = {
 
 /** Callback hooks consumers can implement to observe network transitions. */
 export interface NetworkObserver {
-  onRequestStarted(info: NetworkRequestInfo): void;
-  onRequestFinished(info: NetworkRequestInfo): void;
-  onRequestFailed(info: NetworkRequestInfo): void;
+  onRequestStarted?(info: NetworkRequestInfo): void;
+  onRequestFinished?(info: NetworkRequestInfo): void;
+  onRequestFailed?(info: NetworkRequestInfo): void;
+  onResponse?(response: Response): void;
 }
 
 /** Options for the idle waiter helper. */

packages/extension/understudy/networkManager.ts

@@ -1,5 +1,7 @@
 import type { Protocol } from "devtools-protocol";
 import type { CDPSessionLike } from "./cdp.js";
+import type { Page } from "./page.js";
+import { Response } from "./response.js";
 import {
   DEFAULT_IDLE_WAIT,
   IGNORED_RESOURCE_TYPES,
@@ -23,6 +25,10 @@ import {
  * Aggregates network information for all CDP sessions owned by a Page.
  */
 export class NetworkManager {
+  private readonly pendingResponses = new Set<Response>();
+
+  constructor(private readonly page: Page) {}
+
   readonly sessions = new Map<
     string,
     {
@@ -114,6 +120,7 @@ export class NetworkManager {
 
     const onResponse = (evt: Protocol.Network.ResponseReceivedEvent) => {
       if (!evt?.requestId) return;
+      this.emitResponse(evt, session);
       const url = evt.response?.url ?? "";
       if (url.startsWith("data:")) finish(evt.requestId);
     };
@@ -163,6 +170,7 @@ export class NetworkManager {
     const entry = this.sessions.get(sid);
     if (!entry) return;
     entry.detach();
+    this.disposeResponsesForSession(entry.session);
     this.sessions.delete(sid);
 
     for (const key of this.requests.keys()) {
@@ -302,30 +310,66 @@ export class NetworkManager {
     for (const { detach } of this.sessions.values()) {
       detach();
     }
+    for (const response of this.pendingResponses) response.dispose();
+    this.pendingResponses.clear();
     this.sessions.clear();
     this.observers.clear();
     this.requests.clear();
     this.documentRequestsByFrame.clear();
   }
 
+  public subscribeResponse(listener: (response: Response) => void): () => void {
+    return this.addObserver({ onResponse: listener });
+  }
+
+  /** Materialize one response for all interested observers; body retrieval stays lazy. */
+  private emitResponse(
+    event: Protocol.Network.ResponseReceivedEvent,
+    session: CDPSessionLike,
+  ): void {
+    if (![...this.observers].some((observer) => typeof observer.onResponse === "function")) return;
+    const response = new Response({
+      page: this.page,
+      session,
+      requestId: event.requestId,
+      frameId: event.frameId,
+      loaderId: event.loaderId,
+      response: event.response,
+      fromServiceWorker: Boolean(event.response.fromServiceWorker),
+    });
+    this.pendingResponses.add(response);
+    void response.finished().then(() => this.pendingResponses.delete(response));
+    for (const observer of this.observers) {
+      observer.onResponse?.(response);
+    }
+  }
+
+  private disposeResponsesForSession(session: CDPSessionLike): void {
+    for (const response of this.pendingResponses) {
+      if (response.session !== session) continue;
+      response.dispose(new Error("Response session was detached"));
+      this.pendingResponses.delete(response);
+    }
+  }
+
   /** Fan-out helper when a tracked request starts. */
   emitStart(info: NetworkRequestInfo): void {
     for (const obs of this.observers) {
-      obs.onRequestStarted(info);
+      obs.onRequestStarted?.(info);
     }
   }
 
   /** Fan-out helper when a tracked request completes successfully. */
   emitFinish(info: NetworkRequestInfo): void {
     for (const obs of this.observers) {
-      obs.onRequestFinished(info);
+      obs.onRequestFinished?.(info);
     }
   }
 
   /** Fan-out helper when a tracked request fails mid-flight. */
   emitFailure(info: NetworkRequestInfo): void {
     for (const obs of this.observers) {
-      obs.onRequestFailed(info);
+      obs.onRequestFailed?.(info);
     }
   }
 

packages/extension/understudy/page.ts

@@ -259,7 +259,7 @@ export class Page {
       this.logger,
     );
 
-    this.networkManager = new NetworkManager();
+    this.networkManager = new NetworkManager(this);
     this.networkManager.trackSession(this.mainSession);
   }
 
@@ -605,6 +605,17 @@ export class Page {
     );
   }
 
+  public async subscribeResponse(
+    listener: (response: Response) => void,
+    signal?: AbortSignal,
+  ): Promise<() => void> {
+    return this.subscribeWhenReady(
+      undefined,
+      () => this.networkManager.subscribeResponse(listener),
+      signal,
+    );
+  }
+
   /** Activate against future shared-state changes, without replaying initial tools. */
   public async subscribeWebMCPToolsChanged(
     listener: (event: WebMCPToolsEvent) => void,

packages/protocol/schemas.ts

@@ -1285,7 +1285,7 @@ export const ResponseFinishedResultSchema = z
 export const PageEventNameSchema = z.enum(["console"]).meta({ id: "PageEventName" });
 
 export const PageSubscriptionEventNameSchema = z
-  .enum(["console", "toolsadded", "toolsremoved"])
+  .enum(["console", "toolsadded", "toolsremoved", "response"])
   .meta({ id: "PageSubscriptionEventName" });
 
 export const PageCDPEventParamsSchema = z
@@ -1360,10 +1360,19 @@ export const PageToolsRemovedNotificationSchema = z
   })
   .meta({ id: "PageToolsRemovedNotification" });
 
+export const PageResponseNotificationSchema = z
+  .strictObject({
+    ...pageEventRoutingShape,
+    event: z.literal("response"),
+    response: NavigationResponseDescriptorSchema,
+  })
+  .meta({ id: "PageResponseNotification" });
+
 export const PageEventNotificationSchema = z
   .discriminatedUnion("event", [
     PageToolsAddedNotificationSchema,
     PageToolsRemovedNotificationSchema,
+    PageResponseNotificationSchema,
   ])
   .meta({ id: "PageEventNotification" });
 

packages/protocol/stagehand.v4.json

@@ -3774,7 +3774,7 @@
     },
     "PageSubscriptionEventName": {
       "type": "string",
-      "enum": ["console", "toolsadded", "toolsremoved"]
+      "enum": ["console", "toolsadded", "toolsremoved", "response"]
     },
     "PageOffParams": {
       "type": "object",
@@ -5352,6 +5352,9 @@
         },
         {
           "$ref": "#/$defs/PageToolsRemovedNotification"
+        },
+        {
+          "$ref": "#/$defs/PageResponseNotification"
         }
       ]
     },
@@ -5436,6 +5439,36 @@
       "required": ["frame_id", "name"],
       "additionalProperties": false
     },
+    "PageResponseNotification": {
+      "type": "object",
+      "properties": {
+        "subscription_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "page_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "session_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "target_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "event": {
+          "type": "string",
+          "const": "response"
+        },
+        "response": {
+          "$ref": "#/$defs/NavigationResponseDescriptor"
+        }
+      },
+      "required": ["subscription_id", "page_id", "session_id", "target_id", "event", "response"],
+      "additionalProperties": false
+    },
     "BrowserbaseSessionCreateParams": {
       "type": "object",
       "properties": {

packages/protocol/types.ts

@@ -172,6 +172,7 @@ import type {
   PageEventNotificationSchema,
   PageToolsAddedNotificationSchema,
   PageToolsRemovedNotificationSchema,
+  PageResponseNotificationSchema,
   WebMCPToolIdentitySchema,
   PageLocatorSchema,
   PageNavigationResultSchema,
@@ -327,6 +328,7 @@ export type PageEventName = z.infer<typeof PageEventNameSchema>;
 export type PageSubscriptionEventName = z.infer<typeof PageSubscriptionEventNameSchema>;
 export type PageEventNotification = z.infer<typeof PageEventNotificationSchema>;
 export type PageToolsAddedNotification = z.infer<typeof PageToolsAddedNotificationSchema>;
+export type PageResponseNotification = z.infer<typeof PageResponseNotificationSchema>;
 export type PageToolsRemovedNotification = z.infer<typeof PageToolsRemovedNotificationSchema>;
 export type WebMCPToolIdentity = z.infer<typeof WebMCPToolIdentitySchema>;
 export type PageCDPEventParams = z.infer<typeof PageCDPEventParamsSchema>;

packages/sdk-python/src/stagehand/__init__.py

@@ -82,6 +82,7 @@
     CDPSubscription,
     Page,
     PageEventListener,
+    ResponseListener,
     ToolsAddedListener,
     ToolsRemovedListener,
     WebMCPToolIdentity,
@@ -147,6 +148,7 @@
     "PageCDPEvent",
     "PageDragAndDropRoutePoint",
     "PageEventListener",
+    "ResponseListener",
     "ToolsAddedListener",
     "ToolsRemovedListener",
     "WebMCPToolIdentity",