fix(core): honor maxImages in Anthropic CUA

[BABTUNA]

why

ClientOptions.maxImages was not honored by AnthropicCUAClient, so Anthropic CUA always kept the default image retention behavior instead of using caller-configured limits.

Closes #2043.

what changed

• Added maxImages handling in AnthropicCUAClient constructor
• Applied maxImages to compressConversationImages(...) in step processing
• Preserved existing default behavior (2) when option is unset
• Updated ClientOptions.maxImages comment to reflect CUA support beyond Microsoft
• Added unit tests for:
  • default keep-2 behavior
  • keep-1 override
  • maxImages=0 (no compression)

test plan

• node node_modules/vitest/vitest.mjs run --config .tmp-vitest-anthropic-max-images.mjs
  • tests/unit/anthropic-cua-max-images.test.ts
• npm.cmd exec prettier -- --write on touched files

---

Summary by cubic

Honors maxImages in AnthropicCUAClient so Anthropic CUA keeps the caller-configured number of screenshots (default 2). This fixes screenshot retention limits not being applied.

• Bug Fixes
  • Read maxImages from ClientOptions and pass it to compressConversationImages during step processing.
  • Keep default 2 when unset; maxImages=0 disables compression.
  • Update ClientOptions.maxImages docs for CUA support and add unit tests for default, 1, and 0 cases.

^{Written for commit fdc6133. Summary will update on new commits. Review in cubic}

[changeset-bot]

⚠️ No Changeset found

Latest commit: fdc6133

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[cubic-dev-ai]

No issues found across 3 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 Caller
    participant CUA as AnthropicCUAClient
    participant Utils as compressConversationImages()
    participant API as Anthropic API

    User->>CUA: constructor(clientOptions)
    Note over CUA: CHANGED: Store maxImages from options<br/>(Defaults to 2 if unset)

    User->>CUA: executeStep(inputItems)
    
    rect rgb(240, 240, 240)
        Note over CUA, Utils: Image Retention Logic
        alt NEW: maxImages > 0
            CUA->>Utils: CHANGED: Pass user-defined maxImages limit
            Utils-->>CUA: inputItems with images > limit converted to text
        else NEW: maxImages == 0
            Note over CUA: Skip compression (retain all images)
        end
    end

    CUA->>CUA: internal: getAction(nextInputItems)
    CUA->>API: POST /messages (with processed history)
    API-->>CUA: assistant response / tool_use
    
    CUA-->>User: StepResult (action + nextInputItems)

Loading