[supremeboxlogos]

why

Expose browser-side predicate waiting consistently across Stagehand SDKs, without transport polling.

This is PR2 of 2, stacked directly on #3179 (amel/wait-for-function-extension). Polling, navigation recovery, and cleanup live in the parent; merge it first using the repository’s stacked-PR handoff rules.

what changed

• Register page.wait_for_function and connect the extension controller/runtime to the internal implementation.
• Add TypeScript waitForFunction(expression, arg?, options?), Python wait_for_function(expression, *, arg, polling, timeout), and Go WaitForFunction. As in Playwright, an expression that evaluates to a function is invoked on each poll and receives the optional JSON arg.
• Preserve JSON result keys through opaque wire metadata, with roundtrip coverage for own toString, constructor, and hasOwnProperty keys in nested payloads. No browser-handle API is introduced.
• Provide RAF/interval polling and no deadline by default in all three SDKs; pass timeout to bound a wait. An omitted or zero timeout also drops the client response deadline.
• Derive internal wait options from the canonical protocol contract. Reuse the TypeScript argument serializer. Model Go’s string-or-number polling option through its existing typed-union generator extension point.
• Regenerate protocol/models/final ZIP and include docs plus minor release entries for all five packages.

Reviewed with the requested Thermo-Nuclear Code Quality Review skill, including an independent cross-review of SDK boundaries. No SDK polling loops, duplicated serializer, broad generator abstraction, or new 1,000-line file crossing.

test plan

• 9 real-Chrome tests passed, including main-world access, async predicates, custom intervals, error propagation, navigation recovery, concurrent waits, and timeout-zero closure.
• 79 extension/selector tests and 788 protocol/docs/SDK/architecture guards passed.
• 184 Python tests plus Ruff/type checks passed; Go SDK package tests passed.
• Follow-up review: 26 wire tests passed; canonical option types emit unchanged JavaScript, and the rebuilt extension ZIP remains identical.
• Extension/SDK/protocol typechecks, dependency-ordered build, generated-model/ZIP checks, formatting, lint, and git diff --check passed.

[changeset-bot]

🦋 Changeset detected

Latest commit: b545864

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

This PR includes changesets to release 25 packages

Name	Type
@browserbasehq/stagehand-go	Minor
@browserbasehq/stagehand-protocol	Minor
@browserbasehq/stagehand-extension	Minor
@browserbasehq/stagehand-python	Minor
@browserbasehq/stagehand	Minor
browse	Patch
@browserbasehq/stagehand-examples	Patch
@browserbasehq/stagehand-integrations-claude-cua-sdk	Patch
@browserbasehq/stagehand-integrations	Patch
@browserbasehq/eve	Patch
@browserbasehq/stagehand-integrations-gemini-cua-sdk	Patch
@browserbasehq/stagehand-integrations-example-pi-facade	Patch
@browserbasehq/stagehand-integrations-claude-agent-sdk	Patch
@browserbasehq/stagehand-integrations-example-claude-code-facade	Patch
@browserbasehq/stagehand-integrations-codex-sdk	Patch
@browserbasehq/stagehand-integrations-example-codex-facade	Patch
@browserbasehq/stagehand-integrations-cursor-sdk	Patch
@browserbasehq/stagehand-integrations-example-cursor-facade	Patch
@browserbasehq/stagehand-integrations-deepagents-sdk	Patch
@browserbasehq/stagehand-integrations-eve-sdk	Patch
@browserbasehq/stagehand-integrations-fx-sdk	Patch
@browserbasehq/stagehand-integrations-mastra-sdk	Patch
@browserbasehq/stagehand-integrations-example-mastra-facade	Patch
@browserbasehq/stagehand-integrations-pi-sdk	Patch
@browserbasehq/stagehand-integrations-example-vercel-ai-facade	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]

1 issue found and verified against the latest diff

Confidence score: 3/5

• models.py rejects integer polling intervals even though the protocol accepts them, so valid requests can fail model validation. Accept strict integers as well as floats while retaining the bounds.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/sdk-python/src/stagehand/_generated/models.py">

<violation number="1" location="packages/sdk-python/src/stagehand/_generated/models.py:2093">
P2: Integer-valued polling intervals fail model validation because `StrictFloat` rejects integers, although the protocol accepts any positive number. Accept strict integers as well as floats while retaining the bounds.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 12 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 9 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 8 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>