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

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

@@ -5,21 +5,49 @@ import { installV3PiercerIntoSession } from "./piercer.js";
 import { v3ScriptContent } from "../dom/build/scriptV3Content.js";
 import { executionContexts } from "./executionContextRegistry.js";
 import { normalizeInitScriptSource } from "./initScripts.js";
-import { TimeoutError, PageNotFoundError } from "../types/public/sdkErrors.js";
+import { TimeoutError, CookieSetError, PageNotFoundError, StagehandSetExtraHTTPHeadersError, } from "../types/public/sdkErrors.js";
 import { getEnvTimeoutMs, withTimeout } from "../timeoutConfig.js";
+import { filterCookies, normalizeCookieParams, cookieMatchesFilter, toCdpCookieParam, } from "./cookies.js";
+/**
+ * Returns true when the target's URL points to a document with a real,
+ * pierceable HTML DOM.  We allowlist the small set of schemes that carry
+ * web content rather than trying to blacklist every internal browser scheme
+ * (chrome://, chrome-extension://, devtools://, brave://, edge://, …).
+ */
+function hasInjectableDOM(url) {
+    if (!url || url === "")
+        return true;
+    if (url === "about:blank" ||
+        url === "about:srcdoc" ||
+        url.startsWith("about:blank#"))
+        return true;
+    if (url.startsWith("http://") || url.startsWith("https://"))
+        return true;
+    if (url.startsWith("data:") ||
+        url.startsWith("blob:") ||
+        url.startsWith("file://") ||
+        url.startsWith("filesystem:"))
+        return true;
+    return false;
+}
+function isNonWebTarget(info) {
+    return ((info.type !== "page" && info.type !== "iframe") ||
+        !hasInjectableDOM(info.url));
+}
+function isTopLevelPage(info) {
+    const ti = info;
+    return info.type === "page" && ti.subtype !== "iframe";
+}
 const DEFAULT_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS = 5000;
 const CI_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS = 30000;
 const FIRST_TOP_LEVEL_PAGE_TIMEOUT_ENV = "STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS";
+const WAIT_FOR_FIRST_TOP_LEVEL_PAGE_OPERATION = "waitForFirstTopLevelPage (no top-level Page)";
 function getFirstTopLevelPageTimeoutMs() {
     return (getEnvTimeoutMs(FIRST_TOP_LEVEL_PAGE_TIMEOUT_ENV) ??
         (process.env.CI
             ? CI_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS
             : DEFAULT_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS));
 }
-function isTopLevelPage(info) {
-    const ti = info;
-    return info.type === "page" && ti.subtype !== "iframe";
-}
 /**
  * V3Context
  *
@@ -57,6 +85,7 @@ export class V3Context {
     _pageOrder = [];
     pendingCreatedTargetUrl = new Map();
     initScripts = [];
+    extraHttpHeaders = null;
     installTargetSessionListeners(session) {
         const sessionId = session.id;
         if (!sessionId)
@@ -79,10 +108,12 @@ export class V3Context {
      */
     static async create(wsUrl, opts) {
         const connectTask = async () => {
-            const conn = await CdpConnection.connect(wsUrl);
+            const conn = await CdpConnection.connect(wsUrl, {
+                headers: opts?.cdpHeaders,
+            });
             const ctx = new V3Context(conn, opts?.env ?? "LOCAL", opts?.apiClient ?? null, opts?.localBrowserLaunchOptions ?? null);
             await ctx.bootstrap();
-            await ctx.waitForFirstTopLevelPage(getFirstTopLevelPageTimeoutMs());
+            await ctx.ensureFirstTopLevelPage(getFirstTopLevelPageTimeoutMs());
             return ctx;
         };
         const cdpTimeoutMs = opts?.env === "BROWSERBASE"
@@ -105,6 +136,33 @@ export class V3Context {
         }
         return await connectTask();
     }
+    hasTopLevelPage() {
+        for (const [targetId, targetType] of this.typeByTarget) {
+            if (targetType === "page" && this.pagesByTarget.has(targetId)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    async ensureFirstTopLevelPage(timeoutMs) {
+        if (this.hasTopLevelPage())
+            return;
+        try {
+            await this.waitForFirstTopLevelPage(timeoutMs);
+            return;
+        }
+        catch (err) {
+            if (!(err instanceof TimeoutError)) {
+                throw err;
+            }
+            v3Logger({
+                category: "ctx",
+                message: "No open browser pages found after connect; creating an initial about:blank page",
+                level: 1,
+            });
+        }
+        await this.newPage("about:blank");
+    }
     /**
      * Wait until at least one top-level Page has been created and registered.
      * We poll internal maps that bootstrap/onAttachedToTarget populate.
@@ -123,7 +181,7 @@ export class V3Context {
             }
             await new Promise((r) => setTimeout(r, 25));
         }
-        throw new TimeoutError("waitForFirstTopLevelPage (no top-level Page)", timeoutMs);
+        throw new TimeoutError(WAIT_FOR_FIRST_TOP_LEVEL_PAGE_OPERATION, timeoutMs);
     }
     async waitForInitialTopLevelTargets(targetIds, timeoutMs = 3000) {
         if (!targetIds.length)
@@ -231,6 +289,36 @@ export class V3Context {
         const pages = this.pages();
         await Promise.all(pages.map((page) => page.registerInitScript(source)));
     }
+    async setExtraHTTPHeaders(headers) {
+        const nextHeaders = { ...headers };
+        this.extraHttpHeaders = nextHeaders;
+        const sessions = [];
+        for (const sessionId of this._sessionInit) {
+            const session = this.conn.getSession(sessionId);
+            if (session)
+                sessions.push(session);
+        }
+        if (!sessions.length)
+            return;
+        const results = await Promise.allSettled(sessions.map(async (session) => {
+            await session.send("Network.enable");
+            await session.send("Network.setExtraHTTPHeaders", {
+                headers: nextHeaders,
+            });
+        }));
+        const failures = results
+            .map((result, index) => ({ result, session: sessions[index] }))
+            .filter((entry) => entry.result.status === "rejected")
+            .map((entry) => {
+            const reason = entry.result.reason;
+            const sid = entry.session.id ?? "unknown";
+            const message = reason?.message ?? String(reason);
+            return `session=${sid} error=${message}`;
+        });
+        if (failures.length) {
+            throw new StagehandSetExtraHTTPHeadersError(failures);
+        }
+    }
     /**
      * Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
      */
@@ -371,11 +459,11 @@ export class V3Context {
      * - Resume the target only after listeners are wired.
      */
     async onAttachedToTarget(info, sessionId) {
-        // Workers are ignored by Stagehand, but with waitForDebuggerOnStart enabled
-        // they still need to be resumed so we don't leave them paused.
-        if (info.type === "worker" ||
-            info.type === "service_worker" ||
-            info.type === "shared_worker") {
+        // Skip non-web targets (workers, chrome extensions, background pages, etc.).
+        // They still need to be resumed so we don't leave them paused by
+        // waitForDebuggerOnStart, but injecting the piercer into these targets
+        // can throw or corrupt their internal state (e.g. Chrome's PDF viewer).
+        if (isNonWebTarget(info)) {
             const session = this.conn.getSession(sessionId);
             if (session) {
                 await session.send("Runtime.runIfWaitingForDebugger").catch(() => { });
@@ -402,72 +490,148 @@ export class V3Context {
             // any "must happen before first document" work.
             await session.send("Runtime.runIfWaitingForDebugger").catch(() => { });
         };
-        // Install any context-level init scripts as early as possible on this session.
-        // If this throws, we still resume the target but avoid re-installing later.
-        let scriptsInstalled = true;
-        let piercerPreRegistered = false;
-        const installPromises = [];
-        try {
-            const send = (method, params) => session.send(method, params).catch(() => { });
-            // make sure init scripts land before any subframe work.
-            installPromises.push(send("Page.enable"));
-            installPromises.push(send("Runtime.enable"));
-            installPromises.push(session
-                .send("Target.setAutoAttach", {
+        // Attach lifecycle (per target session):
+        // 1) while paused, enable domains + child auto-attach and register init scripts;
+        // 2) resume target execution;
+        // 3) build/adopt Page ownership and frame bridges.
+        // Some CDP backends defer *.enable() responses until after resume, so we
+        // cannot await those responses before resuming. Instead we:
+        // - wait for transport-level dispatch of required pre-resume commands;
+        // - then dispatch resume;
+        // - then await responses.
+        const queuePreResume = (method, params, match) => {
+            const dispatched = this.conn
+                .waitForSessionDispatch(sessionId, method, match)
+                .then(() => true)
+                .catch(() => false);
+            const response = session
+                .send(method, params)
+                .then(() => true)
+                .catch(() => false);
+            return { dispatched, response };
+        };
+        const initScriptOps = [];
+        // Pre-resume ordering matters:
+        // - enable domains;
+        // - enable child auto-attach with waitForDebuggerOnStart;
+        // - register init scripts.
+        // Commands are sent in-order on the same session before resume.
+        const corePreResumeOps = [
+            queuePreResume("Page.enable"),
+            queuePreResume("Runtime.enable"),
+            queuePreResume("Target.setAutoAttach", {
                 autoAttach: true,
                 waitForDebuggerOnStart: true,
                 flatten: true,
-            })
-                .catch(() => { }));
-            // Send init scripts only after auto-attach has been issued.
-            if (this.initScripts.length) {
-                for (const source of this.initScripts) {
-                    installPromises.push(session.send("Page.addScriptToEvaluateOnNewDocument", {
-                        source,
-                        runImmediately: true,
-                    }));
-                }
-            }
-            // register piercer (shadow-DOM hook) before resume so it runs
-            // before page scripts
-            installPromises.push(session
-                .send("Page.addScriptToEvaluateOnNewDocument", {
-                source: v3ScriptContent,
-                runImmediately: true,
-            })
-                .then(() => {
-                piercerPreRegistered = true;
-            })
-                .catch(() => { }));
-            installPromises.push(resume());
+            }),
+        ];
+        const headerPreResumeOps = [];
+        if (this.extraHttpHeaders) {
+            const headers = { ...this.extraHttpHeaders };
+            headerPreResumeOps.push(queuePreResume("Network.enable"));
+            headerPreResumeOps.push(queuePreResume("Network.setExtraHTTPHeaders", { headers }));
         }
-        catch {
-            scriptsInstalled = false;
-        }
-        if (installPromises.length) {
-            const results = await Promise.allSettled(installPromises);
-            if (results.some((r) => r.status === "rejected")) {
-                scriptsInstalled = false;
+        // Send init scripts only after auto-attach has been queued.
+        if (this.initScripts.length) {
+            for (const source of this.initScripts) {
+                initScriptOps.push(queuePreResume("Page.addScriptToEvaluateOnNewDocument", {
+                    source,
+                    runImmediately: true,
+                }, (sentParams) => sentParams?.source ===
+                    source));
             }
         }
-        // Only mark the piercer as installed when the pre-registration actually
-        // succeeded.  This lets ensurePiercer() short-circuit (avoiding sequential
-        // CDP round-trips that delay Page.create / installFrameEventBridges and
-        // cause same-process iframe frame-events to be missed) while still falling
-        // back to the full install path when registration failed.
-        if (piercerPreRegistered) {
-            this._piercerInstalled.add(sessionId);
+        const piercerPreloadOp = queuePreResume("Page.addScriptToEvaluateOnNewDocument", {
+            source: v3ScriptContent,
+            runImmediately: true,
+        }, (sentParams) => sentParams?.source ===
+            v3ScriptContent);
+        const preResumeDispatched = (await Promise.all([
+            ...corePreResumeOps.map((op) => op.dispatched),
+            ...headerPreResumeOps.map((op) => op.dispatched),
+            ...initScriptOps.map((op) => op.dispatched),
+            piercerPreloadOp.dispatched,
+        ])).every(Boolean);
+        // Dispatch resume only after pre-resume setup has actually been sent.
+        const resumeOp = queuePreResume("Runtime.runIfWaitingForDebugger");
+        const [resumedDispatched, resumedOk] = await Promise.all([
+            resumeOp.dispatched,
+            resumeOp.response,
+        ]);
+        const [coreResults, headerResults, initScriptResults, piercerPreRegistered,] = await Promise.all([
+            Promise.all(corePreResumeOps.map((op) => op.response)),
+            Promise.all(headerPreResumeOps.map((op) => op.response)),
+            Promise.all(initScriptOps.map((op) => op.response)),
+            piercerPreloadOp.response,
+        ]);
+        // Header propagation is independent of init-script determinism but still
+        // part of pre-resume attach setup; awaited above for ordering/lifecycle.
+        void headerResults;
+        if (!preResumeDispatched || !resumedDispatched || !resumedOk) {
+            // Short-lived child targets can detach before resume is acknowledged.
+            // Keep this noisy only for top-level pages where missing attach is fatal.
+            if (isTopLevelPage(info)) {
+                v3Logger({
+                    category: "ctx",
+                    message: "Failed target pre-resume setup ordering",
+                    level: 2,
+                    auxiliary: {
+                        targetId: { value: String(info.targetId), type: "string" },
+                        targetType: { value: String(info.type), type: "string" },
+                        preResumeDispatched: {
+                            value: String(preResumeDispatched),
+                            type: "string",
+                        },
+                        resumedDispatched: {
+                            value: String(resumedDispatched),
+                            type: "string",
+                        },
+                        resumedOk: { value: String(resumedOk), type: "string" },
+                    },
+                });
+            }
+            return;
         }
+        resumed = true;
+        const scriptsInstalled = coreResults.every(Boolean) && initScriptResults.every(Boolean);
         try {
-            const piercerReady = await this.ensurePiercer(session);
-            if (!piercerReady)
-                return;
-            await session
+            // Best-effort lifecycle events; do not block top-level page registration
+            // on this optional signal stream.
+            void session
                 .send("Page.setLifecycleEventsEnabled", { enabled: true })
                 .catch(() => { });
             // Top-level handling
             if (isTopLevelPage(info)) {
-                const page = await Page.create(this.conn, session, info.targetId, this.apiClient, this.localBrowserLaunchOptions, this.env === "BROWSERBASE");
+                let page = null;
+                let createError;
+                // Deterministic contract: never drop a newly attached top-level target
+                // because an arbitrary local timeout fired. We wait for Page.create and
+                // let it finish regardless of CDP call latency.
+                try {
+                    page = await Page.create(this.conn, session, info.targetId, this.apiClient, this.localBrowserLaunchOptions, this.env === "BROWSERBASE");
+                }
+                catch (error) {
+                    createError = error;
+                }
+                if (!page) {
+                    v3Logger({
+                        category: "ctx",
+                        message: "Failed to create top-level Page",
+                        level: 2,
+                        auxiliary: {
+                            targetId: { value: String(info.targetId), type: "string" },
+                            targetType: { value: String(info.type), type: "string" },
+                            targetUrl: { value: String(info.url ?? ""), type: "string" },
+                            error: {
+                                value: String(createError instanceof Error
+                                    ? createError.message
+                                    : createError),
+                                type: "string",
+                            },
+                        },
+                    });
+                    return;
+                }
                 this.wireSessionToOwnerPage(sessionId, page);
                 this.pagesByTarget.set(info.targetId, page);
                 this.mainFrameToTarget.set(page.mainFrameId(), info.targetId);
@@ -482,13 +646,22 @@ export class V3Context {
                 page.seedCurrentUrl(pendingSeedUrl ?? info.url ?? "");
                 this._pushActive(info.targetId);
                 this.installFrameEventBridges(sessionId, page);
+                if (piercerPreRegistered) {
+                    this._piercerInstalled.add(sessionId);
+                }
                 // If we already installed scripts at the session level, only seed the
                 // Page's registry to avoid double-installing DOMContentLoaded handlers.
                 await this.applyInitScriptsToPage(page, {
                     seedOnly: scriptsInstalled,
                 });
+                if (!piercerPreRegistered) {
+                    void this.ensurePiercer(session).catch(() => { });
+                }
                 return;
             }
+            const piercerReady = await this.ensurePiercer(session).catch(() => false);
+            if (!piercerReady)
+                return;
             // Child (iframe / OOPIF)
             try {
                 const { frameTree } = await session.send("Page.getFrameTree");
@@ -692,5 +865,92 @@ export class V3Context {
             return immediate;
         throw new PageNotFoundError("awaitActivePage: no page available");
     }
+    /**
+     * 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.
+     */
+    async cookies(urls) {
+        const urlList = !urls ? [] : typeof urls === "string" ? [urls] : urls;
+        const { cookies } = await this.conn.send("Storage.getCookies");
+        const mapped = cookies.map((c) => ({
+            name: c.name,
+            value: c.value,
+            domain: c.domain,
+            path: c.path,
+            expires: c.expires,
+            httpOnly: c.httpOnly,
+            secure: c.secure,
+            sameSite: c.sameSite ?? "Lax",
+        }));
+        return filterCookies(mapped, urlList);
+    }
+    /**
+     * 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.
+     */
+    async addCookies(cookies) {
+        const normalized = normalizeCookieParams(cookies);
+        if (!normalized.length)
+            return;
+        const cdpCookies = normalized.map(toCdpCookieParam);
+        try {
+            await this.conn.send("Storage.setCookies", { cookies: cdpCookies });
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            const names = normalized.map((c) => `"${c.name}"`).join(", ");
+            throw new CookieSetError(`Failed to set cookies [${names}] — ` +
+                `the browser rejected the batch. Check that the domain, path, and secure/sameSite values are valid.` +
+                (detail ? ` (CDP error: ${detail})` : ""));
+        }
+    }
+    /**
+     * 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.
+     */
+    async clearCookies(options) {
+        const hasFilter = options?.name !== undefined ||
+            options?.domain !== undefined ||
+            options?.path !== undefined;
+        if (!hasFilter) {
+            // Atomic single-call wipe — no race condition, no O(N) roundtrips.
+            await this.conn.send("Storage.clearCookies");
+            return;
+        }
+        const current = await this.cookies();
+        const toKeep = current.filter((c) => !cookieMatchesFilter(c, options));
+        if (toKeep.length === current.length)
+            return;
+        // Storage domain doesn't support targeted deletes on the browser endpoint.
+        // Clear everything, then re-add only the cookies we're keeping.
+        await this.conn.send("Storage.clearCookies");
+        if (toKeep.length) {
+            try {
+                await this.conn.send("Storage.setCookies", {
+                    cookies: toKeep.map(toCdpCookieParam),
+                });
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                const names = toKeep.map((c) => `"${c.name}"`).join(", ");
+                throw new CookieSetError(`clearCookies: cookies were cleared but failed to re-add the ${toKeep.length} ` +
+                    `non-matching cookie(s) [${names}]. The browser cookie jar is now empty. ` +
+                    (detail ? `(CDP error: ${detail})` : ""));
+            }
+        }
+    }
 }
 //# sourceMappingURL=context.js.map