Using 'mode' enum instead of old 'cua' boolean#1611
Merged
Conversation
🦋 Changeset detectedLatest commit: 9efc0db The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
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 |
Contributor
✱ Stainless preview buildsThis PR will update the Edit this comment to update it. It will appear in the SDK's changelogs. ✅ stagehand-typescript studio · code · diff
✅ stagehand-go studio · code · diff
⏳ These are partial results; builds are still running. This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push. |
Contributor
Greptile OverviewGreptile SummaryThis PR updates the OpenAPI spec to replace the deprecated Key changes:
Backward compatibility: Confidence Score: 5/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant Client as SDK Client
participant APIClient as StagehandAPIClient
participant Server as Server API
participant Agent as Agent Instance
Client->>APIClient: agent({ mode: "cua" })
Note over Client,APIClient: AgentConfig with mode enum
APIClient->>APIClient: prepareModelConfig()
APIClient->>APIClient: Build wireAgentConfig
Note over APIClient: wireAgentConfig.mode = agentConfig.mode
APIClient->>Server: POST /sessions/:id/agentExecute
Note over APIClient,Server: AgentExecuteRequest with mode field
Server->>Server: Validate AgentExecuteRequestSchema
Note over Server: Schema expects mode: "dom" | "hybrid" | "cua"
Server->>Agent: stagehand.agent(normalizedAgentConfig)
Note over Agent: Agent created with mode field
Agent->>Agent: Determine isCuaMode
Note over Agent: mode === "cua" || cua === true
Agent-->>Server: AgentResult
Server-->>APIClient: AgentExecuteResponse
APIClient-->>Client: Result
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
shrey150
approved these changes
Jan 26, 2026
| @@ -0,0 +1,6 @@ | |||
| --- | |||
| "@browserbasehq/stagehand-server": minor | |||
Contributor
There was a problem hiding this comment.
Just confirming -- is this minor b/c we're updating the API contract? If so, makes sense to me
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
1 issue found across 4 files
Confidence score: 3/5
- There’s a concrete risk of user-facing regression:
packages/server/openapi.v3.yamlintroduces a breaking API change (replacingcuaboolean withmode) without the required integration test coverage. - Score reflects a medium risk change to the REST API surface; without tests, downstream clients could break unexpectedly.
- Pay close attention to
packages/server/openapi.v3.yaml- breaking API change needs integration test coverage underpackages/server/test.
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/server/openapi.v3.yaml">
<violation number="1" location="packages/server/openapi.v3.yaml:666">
P1: Rule violated: **Any breaking changes to Stagehand REST API client / server implementation must be covered by an integration test under packages/server/test**
Breaking API change (replacing `cua` boolean with `mode` enum) is not covered by an integration test under packages/server/test/**, violating the API test coverage rule.</violation>
</file>
Architecture diagram
sequenceDiagram
participant User as Client Code
participant SDK as StagehandAPIClient
participant Zod as AgentConfigSchema
participant Server as Stagehand API
Note over User,SDK: Flow: Agent Configuration & Execution
User->>SDK: execute({ ..., mode: "dom" | "hybrid" | "cua" })
SDK->>Zod: Validate Config
Note right of Zod: CHANGED: Validates 'mode' enum<br/>instead of 'cua' boolean
alt Invalid Configuration
Zod-->>SDK: Error
SDK-->>User: Throw Validation Error
else Valid Configuration
Zod-->>SDK: Validated Object
end
SDK->>SDK: NEW: Assign 'mode' to wireAgentConfig
SDK->>Server: POST /v1/agent/execute
Note right of SDK: Payload JSON:<br/>{ "mode": "cua", ... }
alt Success
Server-->>SDK: 200 OK (AgentAction)
SDK-->>User: Return Result
else Schema Mismatch
Server-->>SDK: 400 Bad Request
Note right of Server: Server OpenAPI spec<br/>now expects 'mode'
SDK-->>User: Throw API Error
end
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Contributor
There was a problem hiding this comment.
1 issue found across 7 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.
<file name="packages/core/lib/v3/api.ts">
<violation number="1" location="packages/core/lib/v3/api.ts:364">
P2: Legacy `cua` configs are forwarded without mapping to the new `mode` enum, so `agentConfig.cua = true` will send no `mode` and can silently fall back to the default mode on the updated API. Map the deprecated boolean to `mode: "cua"` when `mode` is undefined to preserve legacy behavior.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Contributor
Author
Contributor
|
@monadoid I have started the AI code review. It will take a few minutes to complete. |
Contributor
There was a problem hiding this comment.
1 issue found across 10 files
Confidence score: 3/5
- The main risk is an API schema change adding a new
modeenum inpackages/core/lib/v3/types/public/api.tswithout the required integration test, so regressions in client/server compatibility could slip through. - Given the medium severity (6/10) and high confidence, there’s some user-facing risk if consumers depend on the previous schema.
- Pay close attention to
packages/core/lib/v3/types/public/api.ts- ensure the new enum field is covered by an integration test underpackages/server/test.
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/types/public/api.ts">
<violation number="1" location="packages/core/lib/v3/types/public/api.ts:608">
P2: Rule violated: **Any breaking changes to Stagehand REST API client / server implementation must be covered by an integration test under packages/server/test**
This API schema change adds a new `mode` enum field but lacks integration test coverage in `packages/server/test/**`. The rule requires that changes to shared request/response shapes in `packages/core/**/types/public/api.ts` be covered by integration tests.
Consider adding tests that verify:
1. Server accepts valid `mode` values (`'dom'`, `'hybrid'`, `'cua'`)
2. Server rejects invalid `mode` values
3. `mode` correctly takes precedence over deprecated `cua` when both are set</violation>
</file>
Architecture diagram
sequenceDiagram
participant Client as User Code
participant SDK as StagehandAPIClient
participant Server as V3 Server/Agent
participant Utils as Validation & Cache
Note over Client,Utils: Runtime Config Resolution: 'mode' vs 'cua'
Client->>SDK: execute({ mode: "dom", cua: true })
Note right of Client: Mixed Config (Transition State)
SDK->>SDK: CHANGED: Normalization Logic
Note right of SDK: If mode is set, use it.<br/>If only cua=true, fill mode="cua".
SDK->>Server: POST /agentExecute
Note right of SDK: Payload includes updated 'mode'<br/>and deprecated 'cua'
Server->>Server: CHANGED: Resolve 'isCuaMode'
alt agentConfig.mode is defined
Server->>Server: Evaluate mode (e.g. "dom")
Note right of Server: PRECEDENCE: "dom" overrides<br/>cua=true. isCuaMode=false.
else mode undefined
Server->>Server: Fallback to agentConfig.cua
end
Server->>Utils: validateExperimentalFeatures(isCuaMode)
alt isCuaMode == true
Utils->>Utils: Enforce CUA strict validation
else isCuaMode == false (DOM/Hybrid)
Utils-->>Server: Validation OK
end
Server->>Utils: AgentCache.get(config)
Utils->>Utils: CHANGED: Generate key using resolved mode
Note right of Utils: Cache key now relies on<br/>enum value rather than boolean
Utils-->>Server: Cache result/miss
Server-->>Client: Agent Result
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
shrey150
approved these changes
Jan 26, 2026
shrey150
approved these changes
Jan 26, 2026
This was referenced Jan 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
why
Discord user reported that the
modeproperty isn't typed in the Python SDK, which was due to the OpenAPI spec being out of datewhat changed
Replaced
cuaboolean field withmodeenum in zod objects + regenerated openapi spec.test plan
Summary by cubic
Updated agent config to use a mode enum (dom, hybrid, cua) instead of the old cua boolean, and regenerated the OpenAPI spec. Kept cua for backward compatibility but deprecated; mode takes precedence if both are set.
Written for commit 9efc0db. Summary will update on new commits. Review in cubic