@browserbasehq/orca 3.1.0-patch.3 → 3.2.0-middleware.1

package/dist/esm/lib/v3/understudy/cdp.js

@@ -1,20 +1,21 @@
 // lib/v3/understudy/cdp.ts
 import WebSocket from "ws";
 import { STAGEHAND_VERSION } from "../../version.js";
+import { FlowLogger, } from "../flowlogger/FlowLogger.js";
+import { CdpConnectionClosedError, PageNotFoundError, } from "../types/public/sdkErrors.js";
 export class CdpConnection {
     ws;
     nextId = 1;
-    inflight = new Map();
+    inflight = new Map(); // Outstanding request records; `_sendViaSession()` inserts and `onMessage()` removes/resolves them.
+    latestCdpCallEvent = new Map();
     eventHandlers = new Map();
     sessions = new Map();
     /** Maps sessionId -> targetId (1:1 mapping) */
     sessionToTarget = new Map();
+    sessionDispatchWaiters = new Set();
     id = null; // root
     transportCloseHandlers = new Set();
-    /** Optional CDP logger - set this to receive all outgoing CDP method calls */
-    cdpLogger;
-    /** Optional CDP event logger - set this to receive all incoming CDP events */
-    cdpEventLogger;
+    flowLoggerContext; // Instance-owned fallback flow context; V3 sets this once and later sends/callbacks re-enter it when ALS is absent.
     onTransportClosed(handler) {
         this.transportCloseHandlers.add(handler);
     }
@@ -36,21 +37,24 @@ export class CdpConnection {
         this.ws.on("close", (code, reason) => {
             // Reason is a Buffer in ws; stringify defensively
             const why = `socket-close code=${code} reason=${String(reason || "")}`;
+            this.rejectAllInflight(why);
             this.emitTransportClosed(why);
         });
         this.ws.on("error", (err) => {
             const why = `socket-error ${err?.message ?? String(err)}`;
+            this.rejectAllInflight(why);
             this.emitTransportClosed(why);
         });
         this.ws.on("message", (data) => this.onMessage(data.toString()));
     }
-    static async connect(wsUrl) {
+    static async connect(wsUrl, options) {
         // Include User-Agent header for server-side observability and version tracking
-        const ws = new WebSocket(wsUrl, {
-            headers: {
-                "User-Agent": `Stagehand/${STAGEHAND_VERSION}`,
-            },
-        });
+        // Merge user-provided headers, letting them override defaults
+        const headers = {
+            "User-Agent": `Stagehand/${STAGEHAND_VERSION}`,
+            ...options?.headers,
+        };
+        const ws = new WebSocket(wsUrl, { headers });
         await new Promise((resolve, reject) => {
             ws.once("open", () => resolve());
             ws.once("error", (e) => reject(e));
@@ -69,6 +73,20 @@ export class CdpConnection {
         const id = this.nextId++;
         const payload = { id, method, params };
         const stack = new Error().stack?.split("\n").slice(1, 4).join("\n");
+        const flowLoggerContext = FlowLogger.resolveContext(this.flowLoggerContext);
+        const cdpCallEvent = flowLoggerContext
+            ? FlowLogger.logCdpCallEvent(flowLoggerContext, {
+                method,
+                params,
+                targetId: null,
+            })
+            : null;
+        if (flowLoggerContext && cdpCallEvent) {
+            this.latestCdpCallEvent.set(null, {
+                flowLoggerContext,
+                cdpCallEvent,
+            });
+        }
         const p = new Promise((resolve, reject) => {
             this.inflight.set(id, {
                 resolve,
@@ -78,11 +96,12 @@ export class CdpConnection {
                 params,
                 stack,
                 ts: Date.now(),
+                flowLoggerContext,
+                cdpCallEvent,
             });
         });
         // Prevent unhandledRejection if a session detaches before the caller awaits.
         void p.catch(() => { });
-        this.cdpLogger?.({ method, params, targetId: null });
         this.ws.send(JSON.stringify(payload));
         return p;
     }
@@ -97,14 +116,44 @@ export class CdpConnection {
             set.delete(handler);
     }
     async close() {
+        if (this.ws.readyState === WebSocket.CLOSED)
+            return;
         await new Promise((resolve) => {
             this.ws.once("close", () => resolve());
             this.ws.close();
         });
     }
+    rejectAllInflight(why) {
+        for (const [id, entry] of this.inflight.entries()) {
+            entry.reject(new CdpConnectionClosedError(why));
+            this.inflight.delete(id);
+        }
+        this.latestCdpCallEvent.clear();
+        for (const waiter of Array.from(this.sessionDispatchWaiters)) {
+            waiter.reject(new CdpConnectionClosedError(why));
+        }
+    }
     getSession(sessionId) {
         return this.sessions.get(sessionId);
     }
+    waitForSessionDispatch(sessionId, method, match) {
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                sessionId,
+                method,
+                match,
+                resolve: () => {
+                    this.sessionDispatchWaiters.delete(waiter);
+                    resolve();
+                },
+                reject: (error) => {
+                    this.sessionDispatchWaiters.delete(waiter);
+                    reject(error);
+                },
+            };
+            this.sessionDispatchWaiters.add(waiter);
+        });
+    }
     async attachToTarget(targetId) {
         const { sessionId } = (await this.send("Target.attachToTarget", { targetId, flatten: true }));
         let session = this.sessions.get(sessionId);
@@ -127,9 +176,54 @@ export class CdpConnection {
                 return;
             this.inflight.delete(msg.id);
             if ("error" in msg && msg.error) {
+                // Response/error events only make sense if the original send captured
+                // both a flow context to re-enter and the emitted CdpCallEvent to hang
+                // the terminal edge under.
+                if (rec.flowLoggerContext && rec.cdpCallEvent) {
+                    let targetId;
+                    if (rec.sessionId) {
+                        const mappedTargetId = this.sessionToTarget.get(rec.sessionId);
+                        if (mappedTargetId) {
+                            targetId = mappedTargetId;
+                        }
+                        else {
+                            targetId = rec.sessionId;
+                        }
+                    }
+                    else {
+                        targetId = null;
+                    }
+                    FlowLogger.logCdpResponseEvent(rec.flowLoggerContext, rec.cdpCallEvent, {
+                        method: rec.method,
+                        error: `${msg.error.code} ${msg.error.message}`,
+                        targetId,
+                    });
+                }
                 rec.reject(new Error(`${msg.error.code} ${msg.error.message}`));
             }
             else {
+                // Successful responses reuse the same cached call context so the
+                // response lands under the exact CdpCallEvent emitted at send time.
+                if (rec.flowLoggerContext && rec.cdpCallEvent) {
+                    let targetId;
+                    if (rec.sessionId) {
+                        const mappedTargetId = this.sessionToTarget.get(rec.sessionId);
+                        if (mappedTargetId) {
+                            targetId = mappedTargetId;
+                        }
+                        else {
+                            targetId = rec.sessionId;
+                        }
+                    }
+                    else {
+                        targetId = null;
+                    }
+                    FlowLogger.logCdpResponseEvent(rec.flowLoggerContext, rec.cdpCallEvent, {
+                        method: rec.method,
+                        result: msg.result,
+                        targetId,
+                    });
+                }
                 rec.resolve(msg.result);
             }
             return;
@@ -148,12 +242,18 @@ export class CdpConnection {
                     .params;
                 for (const [id, entry] of this.inflight.entries()) {
                     if (entry.sessionId === p.sessionId) {
-                        entry.reject(new Error("CDP session detached"));
+                        entry.reject(new PageNotFoundError(`target closed before CDP response (sessionId=${p.sessionId}, targetId=${p.targetId})`));
                         this.inflight.delete(id);
                     }
                 }
+                for (const waiter of Array.from(this.sessionDispatchWaiters)) {
+                    if (waiter.sessionId === p.sessionId) {
+                        waiter.reject(new PageNotFoundError(`target closed before CDP send (sessionId=${p.sessionId}, targetId=${p.targetId})`));
+                    }
+                }
                 this.sessions.delete(p.sessionId);
                 this.sessionToTarget.delete(p.sessionId);
+                this.latestCdpCallEvent.delete(p.sessionId);
             }
             else if (msg.method === "Target.targetDestroyed") {
                 const p = msg.params;
@@ -161,23 +261,62 @@ export class CdpConnection {
                 for (const [sessionId, targetId] of this.sessionToTarget.entries()) {
                     if (targetId === p.targetId) {
                         this.sessionToTarget.delete(sessionId);
+                        this.latestCdpCallEvent.delete(sessionId);
                         break;
                     }
                 }
             }
             const { method, params, sessionId } = msg;
-            // Log incoming CDP events
-            const targetId = this.sessionToTarget.get(sessionId) || sessionId;
-            this.cdpEventLogger?.({ method, params, targetId });
+            const latestCdpCallEvent = this.latestCdpCallEvent.get(sessionId ?? null) ??
+                (sessionId ? this.latestCdpCallEvent.get(null) : null);
+            let targetId;
             if (sessionId) {
-                const session = this.sessions.get(sessionId);
-                session?.dispatch(method, params);
+                const mappedTargetId = this.sessionToTarget.get(sessionId);
+                if (mappedTargetId) {
+                    targetId = mappedTargetId;
+                }
+                else {
+                    targetId = sessionId;
+                }
             }
             else {
+                targetId = null;
+            }
+            // Unsolicited protocol messages are attached under the most recent call on
+            // that session/root when one is known, so later callbacks still show up
+            // in the same flow subtree.
+            if (latestCdpCallEvent) {
+                FlowLogger.logCdpMessageEvent(latestCdpCallEvent.flowLoggerContext, latestCdpCallEvent.cdpCallEvent, {
+                    method,
+                    params,
+                    targetId,
+                });
+            }
+            const dispatch = () => {
+                if (sessionId) {
+                    const session = this.sessions.get(sessionId);
+                    session?.dispatch(method, params);
+                    // Forward target lifecycle events to root listeners as well.
+                    // Some browsers emit these via a parent session rather than the root
+                    // connection; fan-out keeps target tracking consistent.
+                    if (method.startsWith("Target.")) {
+                        const handlers = this.eventHandlers.get(method);
+                        if (handlers)
+                            for (const h of handlers)
+                                h(params);
+                    }
+                    return;
+                }
                 const handlers = this.eventHandlers.get(method);
                 if (handlers)
                     for (const h of handlers)
                         h(params);
+            };
+            if (latestCdpCallEvent) {
+                FlowLogger.withContext(latestCdpCallEvent.flowLoggerContext, dispatch);
+            }
+            else {
+                dispatch();
             }
         }
     }
@@ -185,6 +324,28 @@ export class CdpConnection {
         const id = this.nextId++;
         const payload = { id, method, params, sessionId };
         const stack = new Error().stack?.split("\n").slice(1, 4).join("\n");
+        const flowLoggerContext = FlowLogger.resolveContext(this.flowLoggerContext);
+        let targetId;
+        const mappedTargetId = this.sessionToTarget.get(sessionId);
+        if (mappedTargetId) {
+            targetId = mappedTargetId;
+        }
+        else {
+            targetId = null;
+        }
+        const cdpCallEvent = flowLoggerContext
+            ? FlowLogger.logCdpCallEvent(flowLoggerContext, {
+                method,
+                params,
+                targetId,
+            })
+            : null;
+        if (flowLoggerContext && cdpCallEvent) {
+            this.latestCdpCallEvent.set(sessionId, {
+                flowLoggerContext,
+                cdpCallEvent,
+            });
+        }
         const p = new Promise((resolve, reject) => {
             this.inflight.set(id, {
                 resolve,
@@ -194,12 +355,22 @@ export class CdpConnection {
                 params,
                 stack,
                 ts: Date.now(),
+                flowLoggerContext,
+                cdpCallEvent,
             });
         });
         // Prevent unhandledRejection if a session detaches before the caller awaits.
         void p.catch(() => { });
-        const targetId = this.sessionToTarget.get(sessionId) ?? null;
-        this.cdpLogger?.({ method, params, targetId });
+        for (const waiter of Array.from(this.sessionDispatchWaiters)) {
+            if (waiter.sessionId !== sessionId)
+                continue;
+            if (waiter.method !== method)
+                continue;
+            if (waiter.match && !waiter.match(params))
+                continue;
+            waiter.resolve();
+            break;
+        }
         this.ws.send(JSON.stringify(payload));
         return p;
     }

package/dist/esm/lib/v3/understudy/cdp.js.map

@@ -1 +1 @@
-{"version":3,"file":"cdp.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/cdp.ts"],"names":[],"mappings":"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","sourcesContent":["// lib/v3/understudy/cdp.ts\nimport WebSocket from \"ws\";\nimport type { Protocol } from \"devtools-protocol\";\nimport { STAGEHAND_VERSION } from \"../../version.js\";\n\n/**\n * CDP transport & session multiplexer\n *\n * Owns the browser WebSocket and multiplexes flattened Target sessions.\n * Tracks inflight CDP calls, routes responses to the right session, and forwards events.\n *\n * This does not interpret Page/DOM/Runtime semantics — callers own that logic.\n */\nexport interface CDPSessionLike {\n  send<R = unknown>(method: string, params?: object): Promise<R>;\n  on<P = unknown>(event: string, handler: (params: P) => void): void;\n  off<P = unknown>(event: string, handler: (params: P) => void): void;\n  close(): Promise<void>;\n  readonly id: string | null;\n}\n\ntype Inflight = {\n  resolve: (v: unknown) => void;\n  reject: (e: Error) => void;\n  sessionId?: string | null;\n  method: string;\n  params?: object;\n  stack?: string;\n  ts: number;\n};\n\ntype EventHandler = (params: unknown) => void;\n\ntype RawMessage =\n  | {\n      id: number;\n      result?: unknown;\n      error?: { code: number; message: string; data?: unknown };\n      sessionId?: string;\n    }\n  | { method: string; params?: unknown; sessionId?: string };\n\nexport class CdpConnection implements CDPSessionLike {\n  private ws: WebSocket;\n  private nextId = 1;\n  private inflight = new Map<number, Inflight>();\n  private eventHandlers = new Map<string, Set<EventHandler>>();\n  private sessions = new Map<string, CdpSession>();\n  /** Maps sessionId -> targetId (1:1 mapping) */\n  private sessionToTarget = new Map<string, string>();\n  public readonly id: string | null = null; // root\n  private transportCloseHandlers = new Set<(why: string) => void>();\n\n  /** Optional CDP logger - set this to receive all outgoing CDP method calls */\n  public cdpLogger?: (info: {\n    method: string;\n    params?: object;\n    targetId?: string | null;\n  }) => void;\n\n  /** Optional CDP event logger - set this to receive all incoming CDP events */\n  public cdpEventLogger?: (info: {\n    method: string;\n    params?: unknown;\n    targetId?: string | null;\n  }) => void;\n\n  public onTransportClosed(handler: (why: string) => void): void {\n    this.transportCloseHandlers.add(handler);\n  }\n  public offTransportClosed(handler: (why: string) => void): void {\n    this.transportCloseHandlers.delete(handler);\n  }\n\n  private emitTransportClosed(why: string) {\n    for (const h of this.transportCloseHandlers) {\n      try {\n        h(why);\n      } catch {\n        //\n      }\n    }\n  }\n\n  private constructor(ws: WebSocket) {\n    this.ws = ws;\n    this.ws.on(\"close\", (code, reason) => {\n      // Reason is a Buffer in ws; stringify defensively\n      const why = `socket-close code=${code} reason=${String(reason || \"\")}`;\n      this.emitTransportClosed(why);\n    });\n\n    this.ws.on(\"error\", (err) => {\n      const why = `socket-error ${err?.message ?? String(err)}`;\n      this.emitTransportClosed(why);\n    });\n    this.ws.on(\"message\", (data) => this.onMessage(data.toString()));\n  }\n\n  static async connect(wsUrl: string): Promise<CdpConnection> {\n    // Include User-Agent header for server-side observability and version tracking\n    const ws = new WebSocket(wsUrl, {\n      headers: {\n        \"User-Agent\": `Stagehand/${STAGEHAND_VERSION}`,\n      },\n    });\n    await new Promise<void>((resolve, reject) => {\n      ws.once(\"open\", () => resolve());\n      ws.once(\"error\", (e) => reject(e));\n    });\n    return new CdpConnection(ws);\n  }\n\n  async enableAutoAttach(): Promise<void> {\n    await this.send(\"Target.setAutoAttach\", {\n      autoAttach: true,\n      flatten: true,\n      waitForDebuggerOnStart: true,\n    });\n    await this.send(\"Target.setDiscoverTargets\", { discover: true });\n  }\n\n  async send<R = unknown>(method: string, params?: object): Promise<R> {\n    const id = this.nextId++;\n    const payload = { id, method, params };\n    const stack = new Error().stack?.split(\"\\n\").slice(1, 4).join(\"\\n\");\n    const p = new Promise<R>((resolve, reject) => {\n      this.inflight.set(id, {\n        resolve,\n        reject,\n        sessionId: null,\n        method,\n        params,\n        stack,\n        ts: Date.now(),\n      });\n    });\n    // Prevent unhandledRejection if a session detaches before the caller awaits.\n    void p.catch(() => {});\n    this.cdpLogger?.({ method, params, targetId: null });\n    this.ws.send(JSON.stringify(payload));\n    return p;\n  }\n\n  on<P = unknown>(event: string, handler: (params: P) => void): void {\n    const set = this.eventHandlers.get(event) ?? new Set<EventHandler>();\n    set.add(handler as EventHandler);\n    this.eventHandlers.set(event, set);\n  }\n\n  off<P = unknown>(event: string, handler: (params: P) => void): void {\n    const set = this.eventHandlers.get(event);\n    if (set) set.delete(handler as EventHandler);\n  }\n\n  async close(): Promise<void> {\n    await new Promise<void>((resolve) => {\n      this.ws.once(\"close\", () => resolve());\n      this.ws.close();\n    });\n  }\n\n  getSession(sessionId: string): CdpSession | undefined {\n    return this.sessions.get(sessionId);\n  }\n\n  async attachToTarget(targetId: string): Promise<CdpSession> {\n    const { sessionId } = (await this.send<{ sessionId: string }>(\n      \"Target.attachToTarget\",\n      { targetId, flatten: true },\n    )) as { sessionId: string };\n\n    let session = this.sessions.get(sessionId);\n    if (!session) {\n      session = new CdpSession(this, sessionId);\n      this.sessions.set(sessionId, session);\n    }\n    this.sessionToTarget.set(sessionId, targetId);\n    return session;\n  }\n\n  async getTargets(): Promise<Protocol.Target.TargetInfo[]> {\n    const res = await this.send<{\n      targetInfos: Protocol.Target.TargetInfo[];\n    }>(\"Target.getTargets\");\n    return res.targetInfos;\n  }\n\n  private onMessage(json: string): void {\n    const msg = JSON.parse(json) as RawMessage;\n\n    if (\"id\" in msg) {\n      const rec = this.inflight.get(msg.id);\n      if (!rec) return;\n\n      this.inflight.delete(msg.id);\n\n      if (\"error\" in msg && msg.error) {\n        rec.reject(new Error(`${msg.error.code} ${msg.error.message}`));\n      } else {\n        rec.resolve((msg as { result?: unknown }).result);\n      }\n      return;\n    }\n\n    if (\"method\" in msg) {\n      if (msg.method === \"Target.attachedToTarget\") {\n        const p = (msg as { params: Protocol.Target.AttachedToTargetEvent })\n          .params;\n        if (!this.sessions.has(p.sessionId)) {\n          this.sessions.set(p.sessionId, new CdpSession(this, p.sessionId));\n        }\n        this.sessionToTarget.set(p.sessionId, p.targetInfo.targetId);\n      } else if (msg.method === \"Target.detachedFromTarget\") {\n        const p = (msg as { params: Protocol.Target.DetachedFromTargetEvent })\n          .params;\n        for (const [id, entry] of this.inflight.entries()) {\n          if (entry.sessionId === p.sessionId) {\n            entry.reject(new Error(\"CDP session detached\"));\n            this.inflight.delete(id);\n          }\n        }\n        this.sessions.delete(p.sessionId);\n        this.sessionToTarget.delete(p.sessionId);\n      } else if (msg.method === \"Target.targetDestroyed\") {\n        const p = (msg as { params: { targetId: string } }).params;\n        // Remove any session mapping for this target\n        for (const [sessionId, targetId] of this.sessionToTarget.entries()) {\n          if (targetId === p.targetId) {\n            this.sessionToTarget.delete(sessionId);\n            break;\n          }\n        }\n      }\n\n      const { method, params, sessionId } = msg;\n\n      // Log incoming CDP events\n      const targetId = this.sessionToTarget.get(sessionId) || sessionId;\n      this.cdpEventLogger?.({ method, params, targetId });\n\n      if (sessionId) {\n        const session = this.sessions.get(sessionId);\n        session?.dispatch(method, params);\n      } else {\n        const handlers = this.eventHandlers.get(method);\n        if (handlers) for (const h of handlers) h(params);\n      }\n    }\n  }\n\n  _sendViaSession<R = unknown>(\n    sessionId: string,\n    method: string,\n    params?: object,\n  ): Promise<R> {\n    const id = this.nextId++;\n    const payload = { id, method, params, sessionId };\n    const stack = new Error().stack?.split(\"\\n\").slice(1, 4).join(\"\\n\");\n\n    const p = new Promise<R>((resolve, reject) => {\n      this.inflight.set(id, {\n        resolve,\n        reject,\n        sessionId,\n        method,\n        params,\n        stack,\n        ts: Date.now(),\n      });\n    });\n    // Prevent unhandledRejection if a session detaches before the caller awaits.\n    void p.catch(() => {});\n    const targetId = this.sessionToTarget.get(sessionId) ?? null;\n    this.cdpLogger?.({ method, params, targetId });\n    this.ws.send(JSON.stringify(payload));\n    return p;\n  }\n\n  _onSessionEvent(\n    sessionId: string,\n    event: string,\n    handler: EventHandler,\n  ): void {\n    const key = `${sessionId}:${event}`;\n    const set = this.eventHandlers.get(key) ?? new Set<EventHandler>();\n    set.add(handler);\n    this.eventHandlers.set(key, set);\n  }\n\n  _offSessionEvent(\n    sessionId: string,\n    event: string,\n    handler: EventHandler,\n  ): void {\n    const key = `${sessionId}:${event}`;\n    const set = this.eventHandlers.get(key);\n    if (set) set.delete(handler);\n  }\n\n  _dispatchToSession(sessionId: string, event: string, params: unknown): void {\n    const key = `${sessionId}:${event}`;\n    const handlers = this.eventHandlers.get(key);\n    if (handlers) for (const h of handlers) h(params);\n  }\n}\n\nexport class CdpSession implements CDPSessionLike {\n  constructor(\n    private readonly root: CdpConnection,\n    public readonly id: string,\n  ) {}\n\n  send<R = unknown>(method: string, params?: object): Promise<R> {\n    return this.root._sendViaSession<R>(this.id, method, params);\n  }\n\n  on<P = unknown>(event: string, handler: (params: P) => void): void {\n    this.root._onSessionEvent(this.id, event, handler as EventHandler);\n  }\n\n  off<P = unknown>(event: string, handler: (params: P) => void): void {\n    this.root._offSessionEvent(this.id, event, handler as EventHandler);\n  }\n\n  async close(): Promise<void> {\n    await this.root.send<void>(\"Target.detachFromTarget\", {\n      sessionId: this.id,\n    });\n  }\n\n  dispatch(event: string, params: unknown): void {\n    this.root._dispatchToSession(this.id, event, params);\n  }\n}\n"]}
+{"version":3,"file":"cdp.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/cdp.ts"],"names":[],"mappings":"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","sourcesContent":["// lib/v3/understudy/cdp.ts\nimport WebSocket from \"ws\";\nimport type { Protocol } from \"devtools-protocol\";\nimport { STAGEHAND_VERSION } from \"../../version.js\";\nimport {\n  FlowLogger,\n  type FlowEvent,\n  type FlowLoggerContext,\n} from \"../flowlogger/FlowLogger.js\";\nimport {\n  CdpConnectionClosedError,\n  PageNotFoundError,\n} from \"../types/public/sdkErrors.js\";\n\n/**\n * CDP transport & session multiplexer\n *\n * Owns the browser WebSocket and multiplexes flattened Target sessions.\n * Tracks inflight CDP calls, routes responses to the right session, and forwards events.\n *\n * This does not interpret Page/DOM/Runtime semantics — callers own that logic.\n */\nexport interface CDPSessionLike {\n  send<R = unknown>(method: string, params?: object): Promise<R>;\n  on<P = unknown>(event: string, handler: (params: P) => void): void;\n  off<P = unknown>(event: string, handler: (params: P) => void): void;\n  close(): Promise<void>;\n  readonly id: string | null;\n}\n\ntype Inflight = {\n  resolve: (v: unknown) => void;\n  reject: (e: Error) => void;\n  sessionId?: string | null;\n  method: string;\n  params?: object;\n  stack?: string;\n  ts: number;\n  flowLoggerContext?: FlowLoggerContext | null; // Snapshot of the flow context captured when the request was sent; response handling re-enters this if ALS is gone.\n  cdpCallEvent?: Pick<FlowEvent, \"eventId\" | \"eventParentIds\"> | null; // The emitted CdpCallEvent identity; later response/error events attach under this exact parent.\n};\n\ntype EventHandler = (params: unknown) => void;\ntype SessionDispatchWaiter = {\n  sessionId: string;\n  method: string;\n  match?: (params?: object) => boolean;\n  resolve: () => void;\n  reject: (error: Error) => void;\n};\n\ntype RawMessage =\n  | {\n      id: number;\n      result?: unknown;\n      error?: { code: number; message: string; data?: unknown };\n      sessionId?: string;\n    }\n  | { method: string; params?: unknown; sessionId?: string };\n\nexport class CdpConnection implements CDPSessionLike {\n  private ws: WebSocket;\n  private nextId = 1;\n  private inflight = new Map<number, Inflight>(); // Outstanding request records; `_sendViaSession()` inserts and `onMessage()` removes/resolves them.\n  private latestCdpCallEvent = new Map<\n    // Most recent CDP call per session/root; `_sendViaSession()` refreshes it and later unsolicited messages reuse it as their parent anchor.\n    string | null,\n    {\n      flowLoggerContext: FlowLoggerContext; // Flow context captured when the latest call on this session/root was emitted.\n      cdpCallEvent: Pick<FlowEvent, \"eventId\" | \"eventParentIds\">; // Identity of that latest call event; unsolicited messages reuse it as their parent.\n    }\n  >();\n  private eventHandlers = new Map<string, Set<EventHandler>>();\n  private sessions = new Map<string, CdpSession>();\n  /** Maps sessionId -> targetId (1:1 mapping) */\n  private sessionToTarget = new Map<string, string>();\n  private sessionDispatchWaiters = new Set<SessionDispatchWaiter>();\n  public readonly id: string | null = null; // root\n  private transportCloseHandlers = new Set<(why: string) => void>();\n\n  public flowLoggerContext?: FlowLoggerContext; // Instance-owned fallback flow context; V3 sets this once and later sends/callbacks re-enter it when ALS is absent.\n\n  public onTransportClosed(handler: (why: string) => void): void {\n    this.transportCloseHandlers.add(handler);\n  }\n  public offTransportClosed(handler: (why: string) => void): void {\n    this.transportCloseHandlers.delete(handler);\n  }\n\n  private emitTransportClosed(why: string) {\n    for (const h of this.transportCloseHandlers) {\n      try {\n        h(why);\n      } catch {\n        //\n      }\n    }\n  }\n\n  private constructor(ws: WebSocket) {\n    this.ws = ws;\n    this.ws.on(\"close\", (code, reason) => {\n      // Reason is a Buffer in ws; stringify defensively\n      const why = `socket-close code=${code} reason=${String(reason || \"\")}`;\n      this.rejectAllInflight(why);\n      this.emitTransportClosed(why);\n    });\n\n    this.ws.on(\"error\", (err) => {\n      const why = `socket-error ${err?.message ?? String(err)}`;\n      this.rejectAllInflight(why);\n      this.emitTransportClosed(why);\n    });\n    this.ws.on(\"message\", (data) => this.onMessage(data.toString()));\n  }\n\n  static async connect(\n    wsUrl: string,\n    options?: { headers?: Record<string, string> },\n  ): Promise<CdpConnection> {\n    // Include User-Agent header for server-side observability and version tracking\n    // Merge user-provided headers, letting them override defaults\n    const headers = {\n      \"User-Agent\": `Stagehand/${STAGEHAND_VERSION}`,\n      ...options?.headers,\n    };\n    const ws = new WebSocket(wsUrl, { headers });\n    await new Promise<void>((resolve, reject) => {\n      ws.once(\"open\", () => resolve());\n      ws.once(\"error\", (e) => reject(e));\n    });\n    return new CdpConnection(ws);\n  }\n\n  async enableAutoAttach(): Promise<void> {\n    await this.send(\"Target.setAutoAttach\", {\n      autoAttach: true,\n      flatten: true,\n      waitForDebuggerOnStart: true,\n    });\n    await this.send(\"Target.setDiscoverTargets\", { discover: true });\n  }\n\n  async send<R = unknown>(method: string, params?: object): Promise<R> {\n    const id = this.nextId++;\n    const payload = { id, method, params };\n    const stack = new Error().stack?.split(\"\\n\").slice(1, 4).join(\"\\n\");\n    const flowLoggerContext = FlowLogger.resolveContext(this.flowLoggerContext);\n    const cdpCallEvent = flowLoggerContext\n      ? FlowLogger.logCdpCallEvent(flowLoggerContext, {\n          method,\n          params,\n          targetId: null,\n        })\n      : null;\n    if (flowLoggerContext && cdpCallEvent) {\n      this.latestCdpCallEvent.set(null, {\n        flowLoggerContext,\n        cdpCallEvent,\n      });\n    }\n    const p = new Promise<R>((resolve, reject) => {\n      this.inflight.set(id, {\n        resolve,\n        reject,\n        sessionId: null,\n        method,\n        params,\n        stack,\n        ts: Date.now(),\n        flowLoggerContext,\n        cdpCallEvent,\n      });\n    });\n    // Prevent unhandledRejection if a session detaches before the caller awaits.\n    void p.catch(() => {});\n    this.ws.send(JSON.stringify(payload));\n    return p;\n  }\n\n  on<P = unknown>(event: string, handler: (params: P) => void): void {\n    const set = this.eventHandlers.get(event) ?? new Set<EventHandler>();\n    set.add(handler as EventHandler);\n    this.eventHandlers.set(event, set);\n  }\n\n  off<P = unknown>(event: string, handler: (params: P) => void): void {\n    const set = this.eventHandlers.get(event);\n    if (set) set.delete(handler as EventHandler);\n  }\n\n  async close(): Promise<void> {\n    if (this.ws.readyState === WebSocket.CLOSED) return;\n    await new Promise<void>((resolve) => {\n      this.ws.once(\"close\", () => resolve());\n      this.ws.close();\n    });\n  }\n\n  private rejectAllInflight(why: string): void {\n    for (const [id, entry] of this.inflight.entries()) {\n      entry.reject(new CdpConnectionClosedError(why));\n      this.inflight.delete(id);\n    }\n    this.latestCdpCallEvent.clear();\n    for (const waiter of Array.from(this.sessionDispatchWaiters)) {\n      waiter.reject(new CdpConnectionClosedError(why));\n    }\n  }\n\n  getSession(sessionId: string): CdpSession | undefined {\n    return this.sessions.get(sessionId);\n  }\n\n  waitForSessionDispatch(\n    sessionId: string,\n    method: string,\n    match?: (params?: object) => boolean,\n  ): Promise<void> {\n    return new Promise<void>((resolve, reject) => {\n      const waiter: SessionDispatchWaiter = {\n        sessionId,\n        method,\n        match,\n        resolve: () => {\n          this.sessionDispatchWaiters.delete(waiter);\n          resolve();\n        },\n        reject: (error: Error) => {\n          this.sessionDispatchWaiters.delete(waiter);\n          reject(error);\n        },\n      };\n      this.sessionDispatchWaiters.add(waiter);\n    });\n  }\n\n  async attachToTarget(targetId: string): Promise<CdpSession> {\n    const { sessionId } = (await this.send<{ sessionId: string }>(\n      \"Target.attachToTarget\",\n      { targetId, flatten: true },\n    )) as { sessionId: string };\n\n    let session = this.sessions.get(sessionId);\n    if (!session) {\n      session = new CdpSession(this, sessionId);\n      this.sessions.set(sessionId, session);\n    }\n    this.sessionToTarget.set(sessionId, targetId);\n    return session;\n  }\n\n  async getTargets(): Promise<Protocol.Target.TargetInfo[]> {\n    const res = await this.send<{\n      targetInfos: Protocol.Target.TargetInfo[];\n    }>(\"Target.getTargets\");\n    return res.targetInfos;\n  }\n\n  private onMessage(json: string): void {\n    const msg = JSON.parse(json) as RawMessage;\n\n    if (\"id\" in msg) {\n      const rec = this.inflight.get(msg.id);\n      if (!rec) return;\n\n      this.inflight.delete(msg.id);\n\n      if (\"error\" in msg && msg.error) {\n        // Response/error events only make sense if the original send captured\n        // both a flow context to re-enter and the emitted CdpCallEvent to hang\n        // the terminal edge under.\n        if (rec.flowLoggerContext && rec.cdpCallEvent) {\n          let targetId: string | null;\n          if (rec.sessionId) {\n            const mappedTargetId = this.sessionToTarget.get(rec.sessionId);\n            if (mappedTargetId) {\n              targetId = mappedTargetId;\n            } else {\n              targetId = rec.sessionId;\n            }\n          } else {\n            targetId = null;\n          }\n          FlowLogger.logCdpResponseEvent(\n            rec.flowLoggerContext,\n            rec.cdpCallEvent,\n            {\n              method: rec.method,\n              error: `${msg.error.code} ${msg.error.message}`,\n              targetId,\n            },\n          );\n        }\n        rec.reject(new Error(`${msg.error.code} ${msg.error.message}`));\n      } else {\n        // Successful responses reuse the same cached call context so the\n        // response lands under the exact CdpCallEvent emitted at send time.\n        if (rec.flowLoggerContext && rec.cdpCallEvent) {\n          let targetId: string | null;\n          if (rec.sessionId) {\n            const mappedTargetId = this.sessionToTarget.get(rec.sessionId);\n            if (mappedTargetId) {\n              targetId = mappedTargetId;\n            } else {\n              targetId = rec.sessionId;\n            }\n          } else {\n            targetId = null;\n          }\n          FlowLogger.logCdpResponseEvent(\n            rec.flowLoggerContext,\n            rec.cdpCallEvent,\n            {\n              method: rec.method,\n              result: (msg as { result?: unknown }).result,\n              targetId,\n            },\n          );\n        }\n        rec.resolve((msg as { result?: unknown }).result);\n      }\n      return;\n    }\n\n    if (\"method\" in msg) {\n      if (msg.method === \"Target.attachedToTarget\") {\n        const p = (msg as { params: Protocol.Target.AttachedToTargetEvent })\n          .params;\n        if (!this.sessions.has(p.sessionId)) {\n          this.sessions.set(p.sessionId, new CdpSession(this, p.sessionId));\n        }\n        this.sessionToTarget.set(p.sessionId, p.targetInfo.targetId);\n      } else if (msg.method === \"Target.detachedFromTarget\") {\n        const p = (msg as { params: Protocol.Target.DetachedFromTargetEvent })\n          .params;\n        for (const [id, entry] of this.inflight.entries()) {\n          if (entry.sessionId === p.sessionId) {\n            entry.reject(\n              new PageNotFoundError(\n                `target closed before CDP response (sessionId=${p.sessionId}, targetId=${p.targetId})`,\n              ),\n            );\n            this.inflight.delete(id);\n          }\n        }\n        for (const waiter of Array.from(this.sessionDispatchWaiters)) {\n          if (waiter.sessionId === p.sessionId) {\n            waiter.reject(\n              new PageNotFoundError(\n                `target closed before CDP send (sessionId=${p.sessionId}, targetId=${p.targetId})`,\n              ),\n            );\n          }\n        }\n        this.sessions.delete(p.sessionId);\n        this.sessionToTarget.delete(p.sessionId);\n        this.latestCdpCallEvent.delete(p.sessionId);\n      } else if (msg.method === \"Target.targetDestroyed\") {\n        const p = (msg as { params: { targetId: string } }).params;\n        // Remove any session mapping for this target\n        for (const [sessionId, targetId] of this.sessionToTarget.entries()) {\n          if (targetId === p.targetId) {\n            this.sessionToTarget.delete(sessionId);\n            this.latestCdpCallEvent.delete(sessionId);\n            break;\n          }\n        }\n      }\n\n      const { method, params, sessionId } = msg;\n      const latestCdpCallEvent =\n        this.latestCdpCallEvent.get(sessionId ?? null) ??\n        (sessionId ? this.latestCdpCallEvent.get(null) : null);\n      let targetId: string | null;\n      if (sessionId) {\n        const mappedTargetId = this.sessionToTarget.get(sessionId);\n        if (mappedTargetId) {\n          targetId = mappedTargetId;\n        } else {\n          targetId = sessionId;\n        }\n      } else {\n        targetId = null;\n      }\n\n      // Unsolicited protocol messages are attached under the most recent call on\n      // that session/root when one is known, so later callbacks still show up\n      // in the same flow subtree.\n      if (latestCdpCallEvent) {\n        FlowLogger.logCdpMessageEvent(\n          latestCdpCallEvent.flowLoggerContext,\n          latestCdpCallEvent.cdpCallEvent,\n          {\n            method,\n            params,\n            targetId,\n          },\n        );\n      }\n\n      const dispatch = () => {\n        if (sessionId) {\n          const session = this.sessions.get(sessionId);\n          session?.dispatch(method, params);\n\n          // Forward target lifecycle events to root listeners as well.\n          // Some browsers emit these via a parent session rather than the root\n          // connection; fan-out keeps target tracking consistent.\n          if (method.startsWith(\"Target.\")) {\n            const handlers = this.eventHandlers.get(method);\n            if (handlers) for (const h of handlers) h(params);\n          }\n          return;\n        }\n\n        const handlers = this.eventHandlers.get(method);\n        if (handlers) for (const h of handlers) h(params);\n      };\n\n      if (latestCdpCallEvent) {\n        FlowLogger.withContext(latestCdpCallEvent.flowLoggerContext, dispatch);\n      } else {\n        dispatch();\n      }\n    }\n  }\n\n  _sendViaSession<R = unknown>(\n    sessionId: string,\n    method: string,\n    params?: object,\n  ): Promise<R> {\n    const id = this.nextId++;\n    const payload = { id, method, params, sessionId };\n    const stack = new Error().stack?.split(\"\\n\").slice(1, 4).join(\"\\n\");\n    const flowLoggerContext = FlowLogger.resolveContext(this.flowLoggerContext);\n    let targetId: string | null;\n    const mappedTargetId = this.sessionToTarget.get(sessionId);\n    if (mappedTargetId) {\n      targetId = mappedTargetId;\n    } else {\n      targetId = null;\n    }\n    const cdpCallEvent = flowLoggerContext\n      ? FlowLogger.logCdpCallEvent(flowLoggerContext, {\n          method,\n          params,\n          targetId,\n        })\n      : null;\n    if (flowLoggerContext && cdpCallEvent) {\n      this.latestCdpCallEvent.set(sessionId, {\n        flowLoggerContext,\n        cdpCallEvent,\n      });\n    }\n\n    const p = new Promise<R>((resolve, reject) => {\n      this.inflight.set(id, {\n        resolve,\n        reject,\n        sessionId,\n        method,\n        params,\n        stack,\n        ts: Date.now(),\n        flowLoggerContext,\n        cdpCallEvent,\n      });\n    });\n    // Prevent unhandledRejection if a session detaches before the caller awaits.\n    void p.catch(() => {});\n    for (const waiter of Array.from(this.sessionDispatchWaiters)) {\n      if (waiter.sessionId !== sessionId) continue;\n      if (waiter.method !== method) continue;\n      if (waiter.match && !waiter.match(params)) continue;\n      waiter.resolve();\n      break;\n    }\n    this.ws.send(JSON.stringify(payload));\n    return p;\n  }\n\n  _onSessionEvent(\n    sessionId: string,\n    event: string,\n    handler: EventHandler,\n  ): void {\n    const key = `${sessionId}:${event}`;\n    const set = this.eventHandlers.get(key) ?? new Set<EventHandler>();\n    set.add(handler);\n    this.eventHandlers.set(key, set);\n  }\n\n  _offSessionEvent(\n    sessionId: string,\n    event: string,\n    handler: EventHandler,\n  ): void {\n    const key = `${sessionId}:${event}`;\n    const set = this.eventHandlers.get(key);\n    if (set) set.delete(handler);\n  }\n\n  _dispatchToSession(sessionId: string, event: string, params: unknown): void {\n    const key = `${sessionId}:${event}`;\n    const handlers = this.eventHandlers.get(key);\n    if (handlers) for (const h of handlers) h(params);\n  }\n}\n\nexport class CdpSession implements CDPSessionLike {\n  constructor(\n    private readonly root: CdpConnection,\n    public readonly id: string,\n  ) {}\n\n  send<R = unknown>(method: string, params?: object): Promise<R> {\n    return this.root._sendViaSession<R>(this.id, method, params);\n  }\n\n  on<P = unknown>(event: string, handler: (params: P) => void): void {\n    this.root._onSessionEvent(this.id, event, handler as EventHandler);\n  }\n\n  off<P = unknown>(event: string, handler: (params: P) => void): void {\n    this.root._offSessionEvent(this.id, event, handler as EventHandler);\n  }\n\n  async close(): Promise<void> {\n    await this.root.send<void>(\"Target.detachFromTarget\", {\n      sessionId: this.id,\n    });\n  }\n\n  dispatch(event: string, params: unknown): void {\n    this.root._dispatchToSession(this.id, event, params);\n  }\n}\n"]}

package/dist/esm/lib/v3/understudy/context.d.ts

@@ -4,6 +4,7 @@ import { Page } from "./page.js";
 import type { StagehandAPIClient } from "../api.js";
 import { LocalBrowserLaunchOptions } from "../types/public/index.js";
 import { InitScriptSource } from "../types/private/index.js";
+import { Cookie, ClearCookieOptions, CookieParam } from "../types/public/context.js";
 /**
  * V3Context
  *
@@ -35,6 +36,7 @@ export declare class V3Context {
     private _pageOrder;
     private pendingCreatedTargetUrl;
     private readonly initScripts;
+    private extraHttpHeaders;
     private installTargetSessionListeners;
     /**
      * Create a Context for a given CDP websocket URL and bootstrap target wiring.
@@ -43,7 +45,10 @@ export declare class V3Context {
         env?: "LOCAL" | "BROWSERBASE";
         apiClient?: StagehandAPIClient | null;
         localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null;
+        cdpHeaders?: Record<string, string>;
     }): Promise<V3Context>;
+    private hasTopLevelPage;
+    private ensureFirstTopLevelPage;
     /**
      * Wait until at least one top-level Page has been created and registered.
      * We poll internal maps that bootstrap/onAttachedToTarget populate.
@@ -60,6 +65,7 @@ export declare class V3Context {
     /** Explicitly mark a known Page as the most-recent active page (and focus it). */
     setActivePage(page: Page): void;
     addInitScript<Arg>(script: InitScriptSource<Arg>, arg?: Arg): Promise<void>;
+    setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
     /**
      * Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
      */
@@ -129,4 +135,32 @@ export declare class V3Context {
      * Normal path returns immediately; popup path waits up to timeoutMs for the new page.
      */
     awaitActivePage(timeoutMs?: number): Promise<Page>;
+    /**
+     * Get all browser cookies, optionally filtered by URL(s).
+     *
+     * When `urls` is omitted or empty every cookie in the browser context is
+     * returned. When one or more URLs are supplied only cookies whose
+     * domain/path/secure attributes match are included.
+     */
+    cookies(urls?: string | string[]): Promise<Cookie[]>;
+    /**
+     * Add one or more cookies to the browser context.
+     *
+     * Each cookie must specify either a `url` (from which domain/path/secure are
+     * derived) or an explicit `domain` + `path` pair.
+     *
+     * We surface CDP errors if the browser rejects a cookie.
+     */
+    addCookies(cookies: CookieParam[]): Promise<void>;
+    /**
+     * Clear cookies from the browser context.
+     *
+     * - Called with no arguments: clears **all** cookies atomically via
+     *   `Storage.clearCookies`.
+     * - Called with filter options: fetches all cookies, clears everything,
+     *   then re-adds only the cookies that do NOT match the filter via
+     *   `Storage.setCookies`. This is necessary on the browser endpoint because
+     *   the Storage domain does not support targeted deletes.
+     */
+    clearCookies(options?: ClearCookieOptions): Promise<void>;
 }