[feat]: add cookie related getters & setters

[tkattkat]

Why

Browser automation workflows frequently need to manage authentication state, persist sessions across runs, and handle cookie-based features. Currently, users have no direct API to read, write, or clear cookies in Stagehand, forcing workarounds through raw CDP commands or page-level JavaScript injection.

What Changed

Cookie Management APIs

Added cookie management methods that mirror the familiar Playwright BrowserContext API:

On context instance:

• context.cookies(urls?) — Get all browser cookies, optionally filtered by URL(s)
• context.addCookies(cookies) — Set one or more cookies in the browser context
• context.clearCookies(options?) — Clear all cookies or selectively by name/domain/path (supports RegExp)

Types Added

• Cookie — Cookie object returned by the browser
• CookieParam — Parameters for setting a cookie (supports url OR domain+path)
• ClearCookieOptions — Filter options for selective cookie clearing

Test Plan

Cookie Management

• context.cookies() returns all cookies when no URLs provided
• context.cookies(url) filters cookies by single URL
• context.cookies([url1, url2]) filters cookies by multiple URLs
• context.addCookies([...]) successfully sets cookies
• context.addCookies() validates cookie params (requires url OR domain+path)
• context.addCookies() rejects sameSite: "None" without secure: true
• context.addCookies() throws on browser rejection (checks CDP success flag)
• context.clearCookies() clears all cookies atomically via single CDP call
• context.clearCookies({ name: "session" }) clears by exact name
• context.clearCookies({ domain: /\.example\.com/ }) clears by regex
• Selective clear only deletes matching cookies, leaves others untouched

[changeset-bot]

🦋 Changeset detected

Latest commit: e6e3e6b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Minor
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Greptile Summary

Added native cookie management to Stagehand's V3 API with context.cookies(), context.addCookies(), and context.clearCookies() methods that mirror Playwright's familiar BrowserContext API. The implementation uses CDP's Storage domain for efficient cookie operations.

Key highlights:

• Comprehensive validation: Cookie parameters are validated upfront with clear error messages (e.g., sameSite: "None" requires secure: true)
• Batched operations: Multiple cookies are sent in a single CDP call for efficiency
• Selective clearing: clearCookies() supports RegExp filters on name/domain/path for fine-grained control
• URL filtering: cookies(urls) filters by domain, path, and secure attributes
• Extensive test coverage: 1100+ unit tests plus integration tests covering edge cases, validation, error handling, and CDP interactions
• Type safety: Full TypeScript types exported for Cookie, CookieParam, and ClearCookieOptions

The PR resolves the gap in Stagehand's API by providing direct cookie access without requiring raw CDP commands or page-level JavaScript injection.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is production-ready with comprehensive validation, extensive test coverage (1100+ unit tests plus integration tests), proper error handling, and follows Playwright's cookie API patterns. The code batches CDP operations efficiently and handles edge cases thoroughly.
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/understudy/cookies.ts	Adds cookie management helper functions with comprehensive validation and filtering logic, including URL filtering, cookie normalization, and filter matching for selective clearing
packages/core/lib/v3/understudy/context.ts	Adds cookies(), addCookies(), and clearCookies() methods to V3Context, with proper error handling and batched CDP operations
packages/core/lib/v3/types/public/context.ts	Defines Cookie, CookieParam, and ClearCookieOptions types with clear documentation
packages/core/lib/v3/tests/cookies.spec.ts	Comprehensive integration tests for cookie management API covering all use cases from test plan
packages/core/tests/cookies.test.ts	Extensive unit tests for cookie helper functions with 1100+ lines covering edge cases, validation, and error handling

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User calls context.addCookies] --> B[normalizeCookieParams validates input]
    B --> C{Valid?}
    C -->|No| D[Throw CookieValidationError]
    C -->|Yes| E[Convert to CDP format via toCdpCookieParam]
    E --> F[Batch send via Storage.setCookies]
    F --> G{CDP Success?}
    G -->|No| H[Throw CookieSetError]
    G -->|Yes| I[Cookies set successfully]
    
    J[User calls context.cookies] --> K[Fetch via Storage.getCookies]
    K --> L[Map CDP cookies to Cookie type]
    L --> M{URLs provided?}
    M -->|Yes| N[filterCookies by domain/path/secure]
    M -->|No| O[Return all cookies]
    N --> O
    
    P[User calls context.clearCookies] --> Q{Filter options?}
    Q -->|No| R[Atomic Storage.clearCookies]
    Q -->|Yes| S[Fetch all cookies via context.cookies]
    S --> T[Filter with cookieMatchesFilter]
    T --> U{Any to delete?}
    U -->|No| V[Skip operation]
    U -->|Yes| W[Storage.clearCookies wipes all]
    W --> X{Any to keep?}
    X -->|Yes| Y[Re-add kept cookies via Storage.setCookies]
    X -->|No| Z[Done]
    Y --> Z

Loading

_{Last reviewed commit: 810b7c6}

[greptile-apps]

_{8 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

2 issues found across 8 files

Confidence score: 3/5

• The cookie validation in packages/core/lib/v3/understudy/cookies.ts misses the secure undefined case, which can allow sameSite: "None" cookies without secure to slip through and behave unexpectedly for users.
• The cookie clearing flow in packages/core/lib/v3/understudy/context.ts is O(N) roundtrips with a race window; this can leave cookies behind or impact performance when no filter is provided.
• These are medium-severity, user-impacting behaviors, so there’s some risk despite the changes being localized.
• Pay close attention to packages/core/lib/v3/understudy/cookies.ts and packages/core/lib/v3/understudy/context.ts - cookie validation and clearing behavior.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/core/lib/v3/understudy/cookies.ts">

<violation number="1" location="packages/core/lib/v3/understudy/cookies.ts:123">
P1: Bug: `copy.secure === false` misses the `undefined` case. When a user sets `sameSite: "None"` with `domain`+`path` but omits `secure`, this validation is skipped because `undefined === false` is `false`. Use `!copy.secure` to also catch `undefined`, matching the stated intent of preventing silent CDP failures.</violation>
</file>

<file name="packages/core/lib/v3/understudy/context.ts">

<violation number="1" location="packages/core/lib/v3/understudy/context.ts:892">
P2: When no filter is provided, use `Network.clearBrowserCookies` instead of fetching all cookies and deleting them one by one. The current approach makes O(N) CDP roundtrips and still has a race condition (cookies set between the fetch and the deletion loop will be missed). `Network.clearBrowserCookies` is a single atomic CDP call.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User
    participant V3 as Stagehand (V3)
    participant Ctx as V3Context
    participant Util as Cookie Utils
    participant Browser as Browser (CDP)

    Note over User, Browser: Cookie Management Flow

    User->>V3: NEW: addCookies(cookies)
    V3->>Ctx: addCookies(cookies)
    Ctx->>Util: NEW: normalizeCookieParams()
    Note right of Util: Validates url OR domain/path<br/>Enforces sameSite=None + secure
    Util-->>Ctx: Normalized CookieParams
    loop Each Cookie
        Ctx->>Browser: Network.setCookie
        Browser-->>Ctx: { success: boolean }
        alt NEW: Browser rejected cookie
            Ctx-->>User: Throw Error (Explicit failure)
        end
    end
    Ctx-->>User: Done

    User->>V3: NEW: cookies(urls?)
    V3->>Ctx: cookies(urls)
    Ctx->>Browser: Network.getAllCookies
    Browser-->>Ctx: Protocol.Network.Cookie[]
    Ctx->>Util: NEW: filterCookies(cookies, urls)
    Note right of Util: Matches domain, path, and<br/>secure protocol requirements
    Util-->>Ctx: Filtered Cookie[]
    Ctx-->>User: Cookie[]

    User->>V3: NEW: clearCookies(options?)
    V3->>Ctx: clearCookies(options)
    Ctx->>Ctx: cookies()
    alt Selective Clear (options provided)
        loop Each Cookie
            Ctx->>Util: NEW: cookieMatchesFilter(cookie, options)
            Util-->>Ctx: boolean
            opt Match Found
                Ctx->>Browser: CHANGED: Network.deleteCookies
            end
        end
    else Clear All
        Ctx->>Browser: Network.deleteCookies (All)
    end
    Ctx-->>User: Done

    Note over User, Browser: Storage Persistence Flow

    User->>Ctx: NEW: storageState()
    Ctx->>Ctx: cookies()
    Ctx-->>User: { cookies: Cookie[] }

    User->>Ctx: NEW: setStorageState(state)
    Ctx->>Ctx: clearCookies()
    Ctx->>Util: Filter expired cookies
    Ctx->>Ctx: addCookies(validCookies)
    Ctx-->>User: Context Restored

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[seanmcguire12]

@cubic-dev-ai

[cubic-dev-ai]

@cubic-dev-ai

@seanmcguire12 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 6 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User as User/Script
    participant SDK as V3Context
    participant Helpers as Cookie Helpers
    participant CDP as Browser (CDP)

    Note over User,CDP: NEW: Cookie Management Flow

    rect rgb(23, 37, 84)
    Note right of User: Get Cookies
    User->>SDK: cookies(urls?)
    SDK->>CDP: Network.getAllCookies
    CDP-->>SDK: List of Protocol.Network.Cookie
    SDK->>Helpers: filterCookies(mappedCookies, urlList)
    Helpers-->>SDK: Filtered Cookie[]
    SDK-->>User: Return cookies
    end

    rect rgb(5, 46, 22)
    Note right of User: Add Cookies
    User->>SDK: addCookies(CookieParam[])
    SDK->>Helpers: NEW: normalizeCookieParams()
    Note over Helpers: Validates url/domain pairs<br/>Enforce Secure for SameSite=None
    Helpers-->>SDK: Normalized Params
    loop For each cookie
        SDK->>CDP: Network.setCookie(params)
        CDP-->>SDK: { success: boolean }
        alt NEW: Browser Rejected (success: false)
            SDK-->>User: Throw Error (Validation/CDP failure)
        end
    end
    SDK-->>User: Success
    end

    rect rgb(69, 26, 3)
    Note right of User: Clear Cookies
    User->>SDK: clearCookies(options?)
    alt Options contains name/domain/path filter
        SDK->>SDK: internal: cookies()
        SDK->>Helpers: NEW: cookieMatchesFilter()
        loop For matching cookies
            SDK->>CDP: Network.deleteCookies({ name, domain, path })
        end
    else No filters (Clear All)
        SDK->>CDP: CHANGED: Network.clearBrowserCookies (Atomic wipe)
    end
    CDP-->>SDK: Done
    SDK-->>User: Success
    end

    classDef highlight fill:#172554,stroke:#333,stroke-width:2px;
    class SDK,Helpers highlight;

Loading

[cubic-dev-ai]

2 issues found across 2 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/understudy/context.ts">

<violation number="1" location="packages/core/lib/v3/understudy/context.ts:856">
P2: Stale JSDoc: the comment says "we check the CDP success flag" but the implementation now uses try/catch on `Storage.setCookies`, which doesn't return a success flag. Update the comment to reflect the actual error-handling mechanism (exception-based, not flag-based).</violation>

<violation number="2" location="packages/core/lib/v3/understudy/context.ts:900">
P2: Race condition: selective `clearCookies` now nukes all cookies then re-adds keepers, creating a window where all cookies (including ones to keep) are temporarily deleted. If the page sets cookies between the clear and re-add, those will be permanently lost. Consider documenting this limitation on the public API or exploring whether `Network.deleteCookies` can be used as a fallback for targeted deletes.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/tests/cookies.spec.ts">

<violation number="1" location="packages/core/lib/v3/tests/cookies.spec.ts:154">
P2: Test navigates to the same URL instead of a different path. The URL on line 157 is identical to `BASE_URL`, so this test doesn't verify what the description claims (cookie persistence across navigation to a *different* path). Consider navigating to a genuinely different path, e.g. the root of the domain.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[greptile-apps]

_{10 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

1 issue found across 10 files

Confidence score: 3/5

• There is a concrete risk of partial cookie persistence in packages/core/lib/v3/understudy/context.ts if one cookie fails mid-loop, which could leave inconsistent state for users.
• The same loop also performs O(N) CDP roundtrips, which could impact performance and makes the change less predictable under load.
• Pay close attention to packages/core/lib/v3/understudy/context.ts - cookie batching/rollback behavior and per-cookie CDP calls.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/understudy/context.ts">

<violation number="1" location="packages/core/lib/v3/understudy/context.ts:879">
P2: Partial application on error: cookies are sent one-at-a-time, so if cookie N fails, cookies 1…N-1 are already persisted with no rollback. This also causes O(N) CDP roundtrips. Consider batching all cookies in a single `Storage.setCookies` call (as `clearCookies` already does for re-adding kept cookies) for both atomicity and performance.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as User Code
    participant Context as V3Context
    participant Helper as Cookie Helper
    participant CDP as Browser (CDP)

    Note over User,CDP: NEW: Cookie Management Flow

    rect rgb(23, 37, 84)
    Note right of User: context.addCookies(cookies)
    User->>Context: addCookies(cookies)
    Context->>Helper: NEW: normalizeCookieParams()
    Helper->>Helper: Validate (URL vs Domain/Path)
    Helper->>Helper: NEW: Enforce sameSite:None + Secure
    alt Validation Failed
        Helper-->>Context: CookieValidationError
        Context-->>User: Error
    else Valid
        Helper-->>Context: Normalized Cookies
        loop for each cookie
            Context->>CDP: CHANGED: Storage.setCookies
            CDP-->>Context: Result
        end
        Context-->>User: void
    end
    end

    rect rgb(5, 46, 22)
    Note right of User: context.cookies(urls)
    User->>Context: cookies(urls)
    Context->>CDP: Storage.getCookies
    CDP-->>Context: raw cookies
    Context->>Helper: NEW: filterCookies(urlList)
    Helper-->>Context: matched cookies
    Context-->>User: Cookie[]
    end

    rect rgb(69, 26, 3)
    Note right of User: context.clearCookies(options)
    User->>Context: clearCookies(options)
    alt No filter (Selective clearing is false)
        Context->>CDP: Storage.clearCookies (Atomic)
        CDP-->>Context: ok
    else With filters (Selective clearing)
        Context->>Context: Fetch current cookies (see above)
        Context->>Helper: NEW: cookieMatchesFilter()
        Helper-->>Context: toKeep[]
        Context->>CDP: Storage.clearCookies (Wipe all)
        opt toKeep.length > 0
            Context->>CDP: Storage.setCookies(toKeep)
        end
    end
    Context-->>User: void
    end

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

2 issues found across 10 files

Confidence score: 3/5

• Potential user-impacting risk: in packages/core/lib/v3/understudy/context.ts, a failure in Storage.setCookies after Storage.clearCookies can permanently drop cookies meant to be retained.
• Overall risk is moderate because this is a concrete failure path in cookie handling, though it may be mitigated with error handling.
• Pay close attention to packages/core/lib/v3/understudy/context.ts - cookie clear/add sequence can lose data if re-add fails.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/understudy/context.ts">

<violation number="1" location="packages/core/lib/v3/understudy/context.ts:923">
P2: If `Storage.setCookies` fails after `Storage.clearCookies` succeeds, all cookies that should have been kept are permanently lost. Consider wrapping the re-add in a try/catch that logs a warning or rethrows with a clear message about the partial failure, so callers know the state is now inconsistent.</violation>

<violation number="2" location="packages/core/lib/v3/understudy/context.ts:936">
P2: The cookie-to-CDP-param mapping is duplicated between `addCookies` and `clearCookies`. Extract a shared helper (e.g., `toCdpCookieParam`) in `cookies.ts` to avoid divergence if the mapping logic changes.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as User / Automation
    participant Context as V3Context
    participant Utils as Cookie Helpers (Internal)
    participant CDP as Browser (CDP Session)

    Note over User,CDP: NEW: Cookie Management Flow

    rect rgb(23, 37, 84)
    Note right of User: context.cookies(urls?)
    User->>Context: cookies(urls)
    Context->>CDP: Storage.getCookies
    CDP-->>Context: Protocol.Network.Cookie[]
    Context->>Utils: filterCookies(mapped, urls)
    Note over Utils: Matches domain/path/secure<br/>attributes against URL(s)
    Utils-->>Context: Cookie[]
    Context-->>User: Cookie[]
    end

    rect rgb(69, 26, 3)
    Note right of User: context.addCookies(cookies)
    User->>Context: addCookies(CookieParam[])
    Context->>Utils: normalizeCookieParams()
    alt NEW: Invalid Configuration
        Note over Utils: e.g. sameSite="None" without secure: true
        Utils-->>Context: throw CookieValidationError
        Context-->>User: Error
    else Valid Configuration
        Utils-->>Context: Normalized CookieParam[]
        Context->>CDP: Storage.setCookies(cdpCookies)
        alt CDP Rejection
            CDP-->>Context: Error response
            Context-->>User: throw CookieSetError
        else Success
            CDP-->>Context: { success: true }
            Context-->>User: void
        end
    end
    end

    rect rgb(5, 46, 22)
    Note right of User: context.clearCookies(options?)
    User->>Context: clearCookies(options)
    alt NEW: Selective Clear (name/domain/path filters)
        Context->>Context: cookies() [Fetch current state]
        Context->>Utils: Filter cookies to keep (cookieMatchesFilter)
        Context->>CDP: Storage.clearCookies [Atomic Wipe]
        opt Has cookies to preserve
            Context->>CDP: Storage.setCookies [Re-add non-matching]
        end
    else NEW: Global Clear (no options)
        Context->>CDP: Storage.clearCookies [Atomic Wipe]
    end
    CDP-->>Context: OK
    Context-->>User: void
    end

    classDef highlight fill:#1e293b,stroke:#333,stroke-width:2px;
    class User,Context,Utils,CDP highlight;

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

@greptileai @cubic-dev-ai

@seanmcguire12 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

@greptileai @cubic-dev-ai

@seanmcguire12 I have started the AI code review. It will take a few minutes to complete.

[greptile-apps]

_{10 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

3 issues found across 10 files

Confidence score: 3/5

• Node ESM runtime risk: packages/core/tests/cookies.test.ts uses relative imports without .js, which can fail under strict ESM resolution.
• Behavioral inconsistency in packages/core/lib/v3/understudy/cookies.ts: malformed URLs throw a raw TypeError instead of CookieValidationError, which could leak unexpected errors.
• Some risk of data loss in packages/core/lib/v3/understudy/context.ts where clearCookies drops CDP-specific metadata during the clear/restore cycle.
• Pay close attention to packages/core/tests/cookies.test.ts, packages/core/lib/v3/understudy/cookies.ts, packages/core/lib/v3/understudy/context.ts - ESM import resolution, error handling consistency, and cookie metadata preservation.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/understudy/cookies.ts">

<violation number="1" location="packages/core/lib/v3/understudy/cookies.ts:79">
P2: Malformed URL strings passed to `new URL()` will throw a raw `TypeError` instead of the `CookieValidationError` used for all other validation failures. Wrap the `new URL(copy.url)` call in a try-catch to provide a consistent error type and a clear message (e.g., `Cookie "<name>" has an invalid url: "<url>"`).

The same concern applies to `filterCookies` where `new URL(u)` is also unguarded.</violation>
</file>

<file name="packages/core/tests/cookies.test.ts">

<violation number="1" location="packages/core/tests/cookies.test.ts:6">
P2: All four relative imports are missing the `.js` extension, breaking the codebase convention used by every other test file. This can cause runtime failures under Node ESM resolution (which requires explicit extensions).

(Based on your team's feedback about requiring explicit .js extensions on all relative ESM import specifiers.) [FEEDBACK_USED]</violation>
</file>

<file name="packages/core/lib/v3/understudy/context.ts">

<violation number="1" location="packages/core/lib/v3/understudy/context.ts:920">
P2: Filtered `clearCookies` silently strips CDP-specific cookie metadata (e.g., `priority`, `sourceScheme`, `sourcePort`, `partitionKey`) from non-matching cookies during the clear-and-restore cycle. Consider storing the raw CDP cookie objects for re-adding, or pass through the original `Protocol.Network.Cookie` shape to `Storage.setCookies` to preserve all attributes.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as User Script
    participant Context as V3Context
    participant Utils as Cookie Helpers (cookies.ts)
    participant Conn as CDP Connection
    participant Browser as Chrome/CDP

    Note over User,Browser: Cookie Management Flow

    rect rgb(23, 37, 84)
    Note right of User: NEW: context.cookies(urls?)
    User->>Context: cookies(["https://example.com"])
    Context->>Conn: send("Storage.getCookies")
    Conn->>Browser: Storage.getCookies
    Browser-->>Conn: Protocol.Network.Cookie[]
    Conn-->>Context: Raw CDP Cookies
    Context->>Utils: filterCookies(mapped, urls)
    Utils->>Utils: Match domain, path, & secure flag
    Context-->>User: Cookie[]
    end

    rect rgb(5, 46, 22)
    Note right of User: NEW: context.addCookies(cookies)
    User->>Context: addCookies(CookieParam[])
    Context->>Utils: normalizeCookieParams(cookies)
    alt Invalid: sameSite="None" AND secure=false
        Utils-->>Context: Throw CookieValidationError
        Context-->>User: Error: Browsers require secure for None
    else Valid
        Utils-->>Context: Normalized params (derived domain/path)
        Context->>Conn: send("Storage.setCookies", { cookies })
        Conn->>Browser: Storage.setCookies
        alt CDP Success
            Browser-->>Context: OK
            Context-->>User: void
        else CDP Reject
            Browser-->>Context: Error
            Context-->>User: Throw CookieSetError
        end
    end
    end

    rect rgb(69, 26, 3)
    Note right of User: NEW: context.clearCookies(options?)
    User->>Context: clearCookies(options)
    
    alt No filter (Clear All)
        Context->>Conn: send("Storage.clearCookies")
        Conn->>Browser: Storage.clearCookies
    else Selective Clear (With Filter)
        Context->>Context: cookies() [Internal Fetch]
        Context->>Utils: cookieMatchesFilter(current, options)
        Note over Context,Utils: Identify cookies to keep vs. remove
        Context->>Conn: send("Storage.clearCookies")
        Conn->>Browser: Storage.clearCookies
        opt Has cookies to keep
            Context->>Conn: send("Storage.setCookies", { toKeep })
            Conn-->>Browser: Re-insert non-matching cookies
        end
    end
    Context-->>User: void
    end

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Filtered clearCookies silently strips CDP-specific cookie metadata (e.g., priority, sourceScheme, sourcePort, partitionKey) from non-matching cookies during the clear-and-restore cycle. Consider storing the raw CDP cookie objects for re-adding, or pass through the original Protocol.Network.Cookie shape to Storage.setCookies to preserve all attributes.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/core/lib/v3/understudy/context.ts, line 920:

<comment>Filtered `clearCookies` silently strips CDP-specific cookie metadata (e.g., `priority`, `sourceScheme`, `sourcePort`, `partitionKey`) from non-matching cookies during the clear-and-restore cycle. Consider storing the raw CDP cookie objects for re-adding, or pass through the original `Protocol.Network.Cookie` shape to `Storage.setCookies` to preserve all attributes.</comment>

<file context>
@@ -823,4 +838,106 @@ export class V3Context {
+    }
+
+    const current = await this.cookies();
+    const toKeep = current.filter((c) => !cookieMatchesFilter(c, options!));
+
+    if (toKeep.length === current.length) return;
</file context>

[seanmcguire12]

this should be fine for now since none of these fields are settable by users. this can be fixed when we add support for partitionKey

[cubic-dev-ai]

Got it, thanks for the context.

[cubic-dev-ai]

@cubic-dev-ai

@seanmcguire12 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

1 issue found across 10 files

Confidence score: 3/5

• Potential user-visible cookie scoping bug in packages/core/lib/v3/understudy/cookies.ts: path matching uses startsWith without the RFC 6265 boundary check, so /foo may incorrectly match /foobar.
• Score reflects a concrete behavior deviation (severity 6/10) that could affect request routing/session handling, though limited in scope to cookie path matching.
• Pay close attention to packages/core/lib/v3/understudy/cookies.ts - cookie path matching needs an RFC 6265 boundary check.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/understudy/cookies.ts">

<violation number="1" location="packages/core/lib/v3/understudy/cookies.ts:35">
P2: Cookie path matching does not enforce path-boundary check per RFC 6265 §5.1.4. A cookie with `path: "/foo"` will incorrectly match URL `http://example.com/foobar` because `startsWith` doesn't verify the next character is `/` (or end-of-string). This causes `cookies(urls)` to return cookies that the browser would not actually send.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Client
    participant Context as V3Context
    participant Helper as Cookie Utils
    participant Browser as Browser (CDP)

    Note over Client, Browser: NEW: Cookie Management Flow

    rect rgb(23, 37, 84)
    Note right of Client: Get Cookies
    Client->>Context: cookies(urls?)
    Context->>Browser: NEW: Storage.getCookies
    Browser-->>Context: Protocol.Network.Cookie[]
    Context->>Helper: NEW: filterCookies(mapped, urls)
    Helper-->>Client: Cookie[]
    end

    rect rgb(5, 46, 22)
    Note right of Client: Add Cookies
    Client->>Context: addCookies(cookies)
    Context->>Helper: NEW: normalizeCookieParams()
    alt NEW: Invalid params (e.g. SameSite:None and Secure:false)
        Helper-->>Client: throw CookieValidationError
    else Valid params
        Helper-->>Context: Normalized CookieParam[]
        Context->>Browser: NEW: Storage.setCookies
        alt CDP Error
            Browser-->>Client: throw CookieSetError
        else Success
            Browser-->>Client: void
        end
    end
    end

    rect rgb(69, 26, 3)
    Note right of Client: Clear Cookies
    Client->>Context: clearCookies(options?)
    alt NEW: No options (Atomic Clear)
        Context->>Browser: Storage.clearCookies
    else NEW: Selective Clear (Filter provided)
        Context->>Context: cookies() [Internal Fetch]
        Context->>Helper: NEW: cookieMatchesFilter()
        Context->>Browser: Storage.clearCookies [Wipe context]
        opt Non-matching cookies exist
            Context->>Browser: Storage.setCookies [Re-add kept cookies]
        end
    end
    Context-->>Client: void
    end

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

@cubic-dev-ai

@seanmcguire12 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

1 issue found across 10 files

Confidence score: 4/5

• Potential user-facing gap in secure-cookie handling: packages/core/lib/v3/understudy/cookies.ts only treats localhost as secure and may incorrectly drop secure cookies for loopback IPs like 127.0.0.1 or ::1.
• Issue is moderate severity and localized, suggesting the PR is likely safe to merge with minor risk for local dev/testing scenarios.
• Pay close attention to packages/core/lib/v3/understudy/cookies.ts - secure-context detection for loopback IPs.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/understudy/cookies.ts">

<violation number="1" location="packages/core/lib/v3/understudy/cookies.ts:45">
P2: Secure-context check only handles `localhost`, missing loopback IPs (`127.0.0.1`, `::1`). Browsers treat all loopback addresses as secure contexts, so secure cookies should also be returned when filtering by `http://127.0.0.1/...` or `http://[::1]/...` URLs.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as User/Test
    participant Ctx as V3Context
    participant Util as Cookie Helpers
    participant CDP as CDPSession (conn)
    participant Browser as Browser Storage

    Note over User, Browser: NEW: Cookie Management Flow

    rect rgb(20, 30, 50)
    Note right of User: context.cookies(urls?)
    User->>Ctx: cookies(urls)
    Ctx->>CDP: Storage.getCookies
    CDP->>Browser: Request all cookies
    Browser-->>CDP: Network.Cookie[]
    CDP-->>Ctx: { cookies }
    Ctx->>Util: filterCookies(mapped, urls)
    Note over Util: Matches domain, path,<br/>and secure protocol
    Util-->>Ctx: Filtered Cookie[]
    Ctx-->>User: Cookie[]
    end

    rect rgb(30, 20, 50)
    Note right of User: context.addCookies(cookies)
    User->>Ctx: addCookies(CookieParam[])
    Ctx->>Util: normalizeCookieParams(cookies)
    alt Invalid Params
        Util-->>Ctx: throw CookieValidationError
        Ctx-->>User: throw error
    else Valid
        Util-->>Ctx: NormalizedParams[]
    end
    Ctx->>CDP: Storage.setCookies({ cookies: cdpParams })
    CDP->>Browser: Apply cookie batch
    alt CDP Rejection
        CDP-->>Ctx: error
        Ctx-->>User: throw CookieSetError
    else Success
        CDP-->>Ctx: ok
        Ctx-->>User: void
    end
    end

    rect rgb(20, 50, 30)
    Note right of User: context.clearCookies(options?)
    User->>Ctx: clearCookies(options)
    alt No Filter (options empty)
        Ctx->>CDP: Storage.clearCookies
        CDP->>Browser: Wipe all cookies
    else Selective Clear (options.name/domain/path)
        Ctx->>Ctx: cookies() [Fetch all current]
        Ctx->>Util: cookieMatchesFilter(cookie, options)
        Util-->>Ctx: cookiesToKeep[]
        Ctx->>CDP: Storage.clearCookies
        Note over Ctx, CDP: Necessary because CDP Storage domain<br/>lacks targeted delete support
        opt Has cookies to keep
            Ctx->>CDP: Storage.setCookies(cookiesToKeep)
        end
    end
    CDP-->>User: Success
    end

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[seanmcguire12]

@cubic-dev-ai

[cubic-dev-ai]

@cubic-dev-ai

@seanmcguire12 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

1 issue found across 10 files

Confidence score: 4/5

• This PR looks safe to merge, with only a release-metadata concern around semantic versioning rather than functional behavior.
• The changeset in .changeset/fast-buses-kneel.md marks new public API methods (cookies, addCookies, clearCookies) as a patch, but semver suggests a minor bump to avoid misleading consumers.
• Pay close attention to .changeset/fast-buses-kneel.md - ensure the version bump matches the new API surface.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".changeset/fast-buses-kneel.md">

<violation number="1" location=".changeset/fast-buses-kneel.md:2">
P2: Adding new public API methods (`cookies`, `addCookies`, `clearCookies`) is a new feature, not a bug fix. Per semver, this should be a `minor` bump rather than `patch`.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as User/Test
    participant Context as V3Context
    participant Utils as cookies.ts (Logic)
    participant CDP as Browser (CDP Storage)

    Note over User,CDP: NEW: Cookie Retrieval Flow
    User->>Context: cookies(urls?)
    Context->>CDP: Storage.getCookies
    CDP-->>Context: Protocol.Network.Cookie[]
    Context->>Utils: filterCookies(mapped, urlList)
    Utils-->>Context: Filtered Cookie[]
    Context-->>User: Cookie[]

    Note over User,CDP: NEW: Cookie Addition Flow
    User->>Context: addCookies(CookieParam[])
    Context->>Utils: normalizeCookieParams(cookies)
    alt Invalid (e.g. SameSite: None without Secure)
        Utils-->>Context: throw CookieValidationError
        Context-->>User: Error
    else Valid
        Utils-->>Context: Normalized params
        Context->>CDP: Storage.setCookies
        alt CDP Rejection
            CDP-->>Context: Error
            Context-->>User: throw CookieSetError
        else Success
            CDP-->>Context: void
            Context-->>User: void
        end
    end

    Note over User,CDP: NEW: Selective Cookie Clearing Flow
    User->>Context: clearCookies(options)
    alt No filters provided
        Context->>CDP: Storage.clearCookies (Atomic Wipe)
    else Selective delete (options.name/domain/path)
        Context->>Context: cookies() (Fetch current)
        Context->>Utils: cookieMatchesFilter()
        Note right of Utils: Identify cookies to KEEP
        Context->>CDP: Storage.clearCookies (Total Wipe)
        opt Has cookies to keep
            Context->>CDP: Storage.setCookies (Re-add non-matching)
        end
    end
    Context-->>User: void

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[pirate]

seems ok but we should really provide a unified API that sets all of these together, cookies alone are not enough for sites like banks/social media:

• cookies
• session storage
• local storage
• indexed db

This is why playwright pushes people towards storageState() and auth.json not cookieState() / cookies.txt:

• https://playwright.dev/docs/auth
• https://playwright.dev/docs/auth#session-storage

Created ticket here: https://linear.app/browserbase/issue/STG-1425