refactor(cli): port deterministic actions to V4

[shrey150]

Summary

• allow a supplied V4 Action to run deterministically without an LLM while preserving the existing model requirement for natural-language instructions
• route CLI selector click and fill commands through Stagehand.act(Action) so they exercise the V4 performUnderstudyMethod path
• preserve value-returning select, highlight, and coordinate click/hover/scroll/drag behavior through V4 locator and page APIs
• fail explicitly for file upload, cursor overlay, and network capture enablement, which are not exposed by the V4 client yet

This is the next draft in the CLI migration stack and is based on #2525.

CLI contract changes

Surface	Contract in this draft
click / fill syntax and success JSON	Unchanged
Failed deterministic click / fill	Now fails the command instead of returning a false success payload
Structured Stagehand.act(Action) without a model	Now supported; it executes once without model-backed self-healing
Natural-language Stagehand.act("instruction") without a model	Still returns the existing missing-LLM error
select	Keeps returning the selected values
Coordinate mouse commands	Keep their arguments and optional XPath result fields; omitted options are not serialized onto the V4 wire
upload, cursor, network on	Return explicit V4 capability-gap errors until public V4 APIs exist
network off, network path, network clear	Unchanged

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
pnpm exec turbo run build --filter=browse	Protocol, extension/server, SDK, and CLI builds completed; 4/4 tasks succeeded	Proves the exact stacked source compiles through the dependency graph
pnpm check	Formatting, lint, and typecheck completed; 9/9 tasks succeeded, including browse:typecheck	Proves repository checks now schedule and pass the CLI typecheck; lint emitted warnings but no errors
pnpm --filter @browserbasehq/stagehand-server test:unit	27 files passed; 201 tests passed; 13 existing todos	Proves deterministic action dispatch, model gating, self-heal behavior, and the synced initialization boundary
pnpm --filter @browserbasehq/stagehand test:unit	10 files passed; 128 tests passed	Proves the V4 SDK still initializes and maps browser sources after the upstream initialization-contract sync
BROWSE_DAEMON_DIR=<temp> pnpm --filter browse test:unit	24 files passed; 366 tests passed	Proves the built CLI contracts, including selector actions, coordinate click/hover/scroll/drag, and omission of undefined V4 wire options
go -C packages/sdk-go run ./internal/extensionpack --check	Completed successfully	Proves the checked-in Go extension bundle matches the exact server build
Local built CLI: open <local fixture> with --local --headless, then click, fill, drag, scroll, evaluate results, and stop	Chrome for Testing 151 initialized in managed-local mode; click changed the page to clicked, fill returned hello-v4, drag returned dragged, scroll reached 600, and stop succeeded	Exercises the real headless browser, launch-loaded extension, V4 runtime RPCs, and deterministic action surface end to end
Local built CLI: repeat the fixture flow with --local --headed	A visible Chrome for Testing 151 window initialized; click/fill/drag/scroll produced clicked, hello-v4-headed, dragged, and 600; stop succeeded	Exercises the real headed launch path and proves the extension loads before V4 initialization in a visible local browser

Browserbase remote smoke coverage and the eval adapter update are intentionally left for the next stacked draft.

[changeset-bot]

⚠️ No Changeset found

Latest commit: f61c704

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