patch agent on api #1336

tkattkat · 2025-12-03T00:14:43Z

why

if no options are provided, we need to provide an empty object

what changed

when options is empty, we fallback to empty object

test plan

tested locally
tested on api

Summary by cubic

Default options to {} for agentExecute calls in V3 to prevent errors when no options are provided. This makes API agent execution more resilient.

Why:

agentExecute expects an object; undefined options caused failures.

What:

Use options ?? {} when calling apiClient.agentExecute in V3.

Test Plan:

Call agent without options; verify it executes without error.
Call agent with options; verify values are passed unchanged.
Smoke test on API with an active page; confirm normal behavior.

^{Written for commit 8980e9f. Summary will update automatically on new commits.}

changeset-bot · 2025-12-03T00:14:46Z

🦋 Changeset detected

Latest commit: 8980e9f

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

This PR includes changesets to release 2 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	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

cubic-dev-ai

No issues found across 1 file

greptile-apps · 2025-12-03T00:19:47Z

Greptile Overview

Greptile Summary

This PR fixes a defensive programming issue in the V3 agent execution path. When the agent method is called without options (a common and valid use case), the options parameter becomes undefined. The apiClient.agentExecute method expects an object, so passing undefined causes runtime errors. The fix adds a nullish coalescing operator (?? {}) to ensure an empty object is passed when options are undefined, making the API agent execution path consistent with the rest of the codebase that already handles optional options gracefully.

Important Files Changed

Filename	Score	Overview
packages/core/lib/v3/v3.ts	5/5	Added nullish coalescing operator to default `options` to empty object in `apiClient.agentExecute` call

Confidence score: 5/5

This PR is extremely safe to merge with minimal risk of causing any issues
Score reflects a simple, well-tested defensive programming fix that prevents runtime errors without changing any core functionality
No files require special attention as this is a single-line defensive fix that maintains API consistency

Sequence Diagram

sequenceDiagram
    participant User
    participant V3
    participant AgentCache
    participant StagehandAPIClient
    participant V3AgentHandler
    participant V3CuaAgentHandler

    User->>V3: "agent(options).execute(instructionOrOptions)"
    
    alt "CUA mode enabled (options?.cua)"
        V3->>V3: "validateCUARequirements()"
        V3->>AgentCache: "buildConfigSignature(options)"
        V3->>V3: "normalizeToV3Page(resolvedOptions.page)"
        V3->>AgentCache: "shouldAttemptCache(instruction)"
        
        alt "cache enabled"
            V3->>AgentCache: "prepareContext()"
            AgentCache->>AgentCache: "tryReplay(cacheContext)"
            alt "cache hit"
                AgentCache-->>V3: "cached result"
                V3-->>User: "AgentResult"
            end
        end
        
        alt "API client enabled and not experimental"
            V3->>StagehandAPIClient: "agentExecute(options ?? {}, resolvedOptions, frameId)"
            StagehandAPIClient-->>V3: "AgentResult"
        else "local execution"
            V3->>V3CuaAgentHandler: "new V3CuaAgentHandler()"
            V3->>V3CuaAgentHandler: "execute(instructionOrOptions)"
            V3CuaAgentHandler-->>V3: "AgentResult"
        end
        
        alt "recording enabled"
            V3->>AgentCache: "store(cacheContext, agentSteps, result)"
        end
        
        V3-->>User: "AgentResult"
    
    else "Standard mode with streaming (options?.stream)"
        V3->>V3: "prepareAgentExecution()"
        V3->>V3AgentHandler: "new V3AgentHandler()"
        
        alt "cache enabled"
            V3->>AgentCache: "tryReplayAsStream(cacheContext)"
            alt "cache hit"
                AgentCache-->>V3: "stream result"
                V3-->>User: "AgentStreamResult"
            end
        end
        
        V3->>V3AgentHandler: "stream(instructionOrOptions)"
        V3AgentHandler-->>V3: "AgentStreamResult"
        
        alt "caching enabled"
            V3->>AgentCache: "wrapStreamForCaching()"
        end
        
        V3-->>User: "AgentStreamResult"
    
    else "Standard mode without streaming"
        V3->>V3: "prepareAgentExecution()"
        V3->>V3AgentHandler: "new V3AgentHandler()"
        
        alt "cache enabled"
            V3->>AgentCache: "tryReplay(cacheContext)"
            alt "cache hit"
                AgentCache-->>V3: "cached result"
                V3-->>User: "AgentResult"
            end
        end
        
        alt "API client enabled and not experimental"
            V3->>StagehandAPIClient: "agentExecute(options ?? {}, resolvedOptions, frameId)"
            StagehandAPIClient-->>V3: "AgentResult"
        else "local execution"
            V3->>V3AgentHandler: "execute(instructionOrOptions)"
            V3AgentHandler-->>V3: "AgentResult"
        end
        
        alt "recording enabled"
            V3->>AgentCache: "store(cacheContext, agentSteps, result)"
        end
        
        V3-->>User: "AgentResult"
    end

greptile-apps

_{1 file reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

@miguelg719

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## @browserbasehq/[email protected] ### Patch Changes - [#1388](#1388) [`605ed6b`](605ed6b) Thanks [@miguelg719](https://github.com/miguelg719)! - Fix multiple click event dispatches on CDP and Anthropic CUA handling (double clicks) - [#1400](#1400) [`34e7e5b`](34e7e5b) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - don't write base64 encoded screenshots to disk when caching agent actions - [#1345](#1345) [`943d2d7`](943d2d7) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for aborting / stopping an agent run & continuing an agent run using messages from prior runs - [#1334](#1334) [`0e95cd2`](0e95cd2) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for google vertex provider - [#1410](#1410) [`d4237e4`](d4237e4) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: include extract in stagehand.history() - [#1315](#1315) [`86975e7`](86975e7) Thanks [@tkattkat](https://github.com/tkattkat)! - Add streaming support to agent through stream:true in the agent config - [#1304](#1304) [`d5e119b`](d5e119b) Thanks [@miguelg719](https://github.com/miguelg719)! - Add support for Microsoft's Fara-7B - [#1346](#1346) [`4e051b2`](4e051b2) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: don't attach to targets twice - [#1327](#1327) [`6b5a3c9`](6b5a3c9) Thanks [@miguelg719](https://github.com/miguelg719)! - Informed error parsing from api - [#1335](#1335) [`bb85ad9`](bb85ad9) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - add support for page.addInitScript() - [#1331](#1331) [`88d28cc`](88d28cc) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: page.evaluate() now works with scripts injected via context.addInitScript() - [#1316](#1316) [`45bcef0`](45bcef0) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for callbacks in stagehand agent - [#1374](#1374) [`6aa9d45`](6aa9d45) Thanks [@miguelg719](https://github.com/miguelg719)! - Fix key action mapping in Anthropic CUA - [#1330](#1330) [`d382084`](d382084) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: make act, extract, and observe respect user defined timeout param - [#1336](#1336) [`1df08cc`](1df08cc) Thanks [@tkattkat](https://github.com/tkattkat)! - Patch agent on api - [#1358](#1358) [`2b56600`](2b56600) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for 4.5 opus in cua agent ## @browserbasehq/[email protected] ### Patch Changes - [#1364](#1364) [`ca0630e`](ca0630e) Thanks [@tkattkat](https://github.com/tkattkat)! - Update model handling in agent evals cli - Updated dependencies \[[`605ed6b`](605ed6b), [`34e7e5b`](34e7e5b), [`943d2d7`](943d2d7), [`0e95cd2`](0e95cd2), [`d4237e4`](d4237e4), [`86975e7`](86975e7), [`d5e119b`](d5e119b), [`4e051b2`](4e051b2), [`6b5a3c9`](6b5a3c9), [`bb85ad9`](bb85ad9), [`88d28cc`](88d28cc), [`45bcef0`](45bcef0), [`6aa9d45`](6aa9d45), [`d382084`](d382084), [`1df08cc`](1df08cc), [`2b56600`](2b56600)]: - @browserbasehq/[email protected] ## @browserbasehq/[email protected] ### Patch Changes - Updated dependencies \[[`605ed6b`](605ed6b), [`34e7e5b`](34e7e5b), [`943d2d7`](943d2d7), [`0e95cd2`](0e95cd2), [`d4237e4`](d4237e4), [`86975e7`](86975e7), [`d5e119b`](d5e119b), [`4e051b2`](4e051b2), [`6b5a3c9`](6b5a3c9), [`bb85ad9`](bb85ad9), [`88d28cc`](88d28cc), [`45bcef0`](45bcef0), [`6aa9d45`](6aa9d45), [`d382084`](d382084), [`1df08cc`](1df08cc), [`2b56600`](2b56600)]: - @browserbasehq/[email protected] Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

@miguelg719

patch agent on api

a1ab750

cubic-dev-ai bot reviewed Dec 3, 2025

View reviewed changes

greptile-apps bot reviewed Dec 3, 2025

View reviewed changes

miguelg719 approved these changes Dec 3, 2025

View reviewed changes

changeset

8980e9f

tkattkat merged commit 1df08cc into main Dec 3, 2025
16 checks passed

coderabbitai bot mentioned this pull request Dec 13, 2025

reverse merge TestsigmaInc/stagehand#12

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

patch agent on api #1336

patch agent on api #1336

Uh oh!

tkattkat commented Dec 3, 2025 •

edited by cubic-dev-ai bot

Loading

Uh oh!

changeset-bot bot commented Dec 3, 2025 •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

greptile-apps bot commented Dec 3, 2025

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

patch agent on api #1336

patch agent on api #1336

Uh oh!

Conversation

tkattkat commented Dec 3, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

why

what changed

test plan

Summary by cubic

Why:

What:

Test Plan:

Uh oh!

changeset-bot bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot commented Dec 3, 2025

Greptile Overview

Greptile Summary

Important Files Changed

Confidence score: 5/5

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tkattkat commented Dec 3, 2025 •

edited by cubic-dev-ai bot

Loading

changeset-bot bot commented Dec 3, 2025 •

edited

Loading