feat(google-cua): add screenshot pruning to prevent memory growth

[pkiv]

Summary

• Add maxImages property to GoogleCUAClient (default: 3) to limit screenshots kept in history
• Add maybeRemoveOldScreenshots() method that prunes old screenshots after each step
• Match the behavior of MicrosoftCUAClient which already has this feature

Problem

The GoogleCUAClient accumulates screenshots in this.history without any pruning mechanism. On image-heavy websites like ncl.com, each screenshot is ~2-3 MB base64. During a 30-step session, this can cause memory growth from ~170 MB to ~400+ MB RSS, leading to OOM errors on memory-constrained environments like AWS Lambda.

Solution

After pushing function responses to history, call maybeRemoveOldScreenshots() which:

1. Traverses history from newest to oldest
2. Counts entries containing screenshots (inlineData)
3. For entries beyond the maxImages limit, removes the inlineData while preserving the rest of the history structure

This reduces memory delta by ~40% in testing (from 232 MB to 138 MB over a typical session).

Test plan

• Memory profiled locally with ncl.com (image-heavy site)
• Verify agent still functions correctly after pruning
• Verify configurable via clientOptions.maxImages

🤖 Generated with Claude Code

---

Summary by cubic

Adds screenshot pruning to GoogleCUAClient to cap screenshots in history and prevent memory growth during long sessions. Keeps only the most recent maxImages screenshots (default 3), removes inlineData from older entries, is configurable via clientOptions.maxImages, and matches MicrosoftCUAClient behavior.

^{Written for commit 3b6588b. Summary will update automatically on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 3b6588b

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	Patch
@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

[cubic-dev-ai]

No issues found across 2 files

[greptile-apps]

Greptile Summary

Adds screenshot pruning to GoogleCUAClient to prevent unbounded memory growth during long agent sessions. The implementation keeps only the most recent maxImages (default: 3) screenshots in conversation history by removing inlineData from older entries while preserving the history structure.

Key changes:

• Added maxImages property (default: 3) configurable via clientOptions.maxImages
• Implemented maybeRemoveOldScreenshots() method that traverses history from newest to oldest
• Prunes screenshots beyond the limit by filtering out inlineData from functionResponse.parts
• Matches the existing behavior in MicrosoftCUAClient

Impact:

• Reduces memory delta by ~40% in testing (from 232 MB to 138 MB over typical sessions)
• Particularly helpful on image-heavy websites where screenshots are 2-3 MB each
• Prevents OOM errors on memory-constrained environments like AWS Lambda

Confidence Score: 4/5

• This PR is safe to merge with low risk - addresses a real memory issue with a proven pattern
• The implementation follows the existing MicrosoftCUAClient pattern closely and solves a documented memory growth problem. The approach is conservative (only removes screenshot data, preserves history structure) and includes logging. Minor points: lacks tests and the pruning logic has a small inefficiency where it filters parts multiple times for entries with multiple function responses, but this won't cause correctness issues.
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/agent/GoogleCUAClient.ts	Added screenshot pruning to prevent memory growth - keeps maxImages (default 3) most recent screenshots, removes inlineData from older entries
.changeset/fix-google-cua-screenshot-pruning.md	Changeset documentation for screenshot pruning feature - clear description and user-facing details

Sequence Diagram

sequenceDiagram
    participant Agent as GoogleCUAClient
    participant API as Google GenAI API
    participant History as Conversation History
    
    Note over Agent: Step execution starts
    Agent->>API: generateContent(history)
    API-->>Agent: Response with function calls
    Agent->>Agent: Process response & execute actions
    Agent->>Agent: Capture screenshot
    Agent->>History: Push function response with inlineData (screenshot)
    
    Note over Agent,History: Screenshot pruning logic
    Agent->>Agent: maybeRemoveOldScreenshots()
    Agent->>History: Traverse from newest to oldest
    loop For each history entry
        Agent->>History: Check if entry has inlineData
        alt Screenshot count > maxImages
            Agent->>History: Filter out inlineData from entry.parts
            Note over Agent,History: Keep structure, remove only screenshot data
        else Screenshot count <= maxImages
            Note over Agent,History: Keep entry unchanged
        end
    end
    
    Note over Agent: Continue to next step with pruned history

Loading

[greptile-apps]

Greptile's behavior is changing!

From now on, if a review finishes with no comments, we will not post an additional "statistics" comment to confirm that our review found nothing to comment on. However, you can confirm that we reviewed your changes in the status check section.

_{This feature can be toggled off in your Code Review Settings by deselecting "Create a status check for each PR".}

[BABTUNA]

Hello ! Saw this was pretty close to being finished and wanted to revive it. Went ahead an open a fresh PR with the linter issues fixed

[pirate]

moved to #2009