Replace the Python Stagehand lifecycle with Stagehand.create

[miguelg719]

Summary

Completes the Python port of the browser-lifecycle stack (#2517–#2523) by making await Stagehand.create(browser=..., ...) the sole construction path, mirroring the TypeScript end state.

• makes Stagehand() unconstructible directly (module-private token; TypeError points at Stagehand.create)
• removes init(), async-with, the flattened browser constructor kwargs, the BrowserSource union models, and browser_source.py
• exports local_browser, browserbase, and StagehandBrowser from the package root
• stagehand.browser returns the exact handle passed to create; a failed create releases the claim so the same handle can be retried
• stagehand.close() never touches the browser or CDP socket — browser/session lifetime is exclusively browser.close()
• worker init keeps the exact StagehandInitParams wire shape; handle metadata overrides caller api_key, and local handles omit browser entirely
• migrates all 7 examples, README, and the CI wheel-smoke script to launch → create → stagehand.close() → browser.close() (browser close in the outermost finally)
• updates the Python ast-grep example-parity patterns to the Stagehand.create shape

Reviewer focus

1. stagehand.close() stops the runtime; browser.close() owns browser cleanup — under no configuration does Stagehand close the transport or process.
2. Browser acquisition options stay client-side and never cross the RPC boundary.
3. One-shot asyncio semantics: memoized close(), claim release under failed create, concurrent-close safety.

Stack

• Add Python browser handle and factories #2544 — browser handle, factories, and transport detach (internal)
• this PR — replace the constructor/init() lifecycle with Stagehand.create
• Implement Browserbase sessions in the Python browser factories #2552 — implement Browserbase sessions

Verification

• full Python package gates green: generate.py --check, ruff format --check, ruff check, ty check, pytest (rewritten lifecycle suite incl. wire-shape, claim-retry, and concurrent-close tests)
• repo pnpm run test:unit green (ast-grep example-parity + sdk-parity against the migrated sources)
• changeset check passed; wheel smoke exercised by CI python-wheel-smoke

---

Summary by cubic

Make await Stagehand.create(browser=...) the only way to start the Python client. Adds local_browser and browserbase factories, moves browser lifetime to the browser handle, and hardens close/cancel and launch validation (incl. Python 3.12’s eager task factory).

• Refactors

  • Stagehand() is no longer constructible; use Stagehand.create.
  • Removed init(), async-with usage, and BrowserSource models; deleted browser_source.py. ResolvedBrowserSource now lives in browser.py with dead fields removed.
  • Exported local_browser, browserbase, and StagehandBrowser from stagehand.
  • stagehand.browser returns the exact handle passed to create. Failed or canceled create releases the claim and detaches the RPC client with close_transport=False.
  • stagehand.close() stops the runtime only, is safe under Python 3.12’s eager task factory, and never closes the browser or CDP socket.
  • Removed connect_rpc_client; updated README, examples (incl. model_gateway.py), tests, smoke script, and ast-grep rules (Python now requires Stagehand.create).
  • Hardened browser handle: stricter launch validation (viewport pairing, list arg types), preserves explicit viewport when default flags are ignored, and treats a vanished Chrome as exited on close.

• Migration

  • Launch a browser: browser = await local_browser.launch(...) or browser = await browserbase.launch(api_key=...).
  • Create the client: stagehand = await Stagehand.create(browser=browser, ...).
  • Close in order: await stagehand.close() then await browser.close() (put browser close in the outermost finally).
  • Remove any async with Stagehand(...) and calls to init().

^{Written for commit 9fdb16d. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9fdb16d

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

[cubic-dev-ai]

2 issues found across 22 files

Confidence score: 2/5

• In packages/sdk-python/src/stagehand/stagehand.py, the browserbase.launch()/browserbase.connect() path raises NotImplementedError before Stagehand.create() runs, which blocks Browserbase users from the required handle-based migration and causes immediate runtime failure — implement the Browserbase factory methods (or gate this path) before release.
• In packages/sdk-python/examples/caching.py, the first call to browserbase.launch(api_key=...) crashes because BrowserbaseBrowser is still a stub, so the example is currently broken and can mislead adopters validating caching flows — update the example to a working path or finish the Browserbase session implementation first.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


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

<violation number="1" location="packages/sdk-python/src/stagehand/stagehand.py:91">
P1: Browserbase users cannot migrate to this required handle-based path: both `browserbase.launch()` and `browserbase.connect()` always raise before `Stagehand.create()` can run. Implement the Browserbase factories before removing the prior Browserbase construction route, or retain a working migration path.</violation>
</file>

<file name="packages/sdk-python/examples/caching.py">

<violation number="1" location="packages/sdk-python/examples/caching.py:29">
P1: This example will crash on its first line. `browserbase.launch(api_key=...)` is a stub in `BrowserbaseBrowser` that unconditionally raises `NotImplementedError("Browserbase sessions are not implemented yet")`, so `await browserbase.launch(...)` in caching.py fails before any browser is created — no session, and the subsequent `Stagehand.create`, page navigation, and caching demo never run. Browserbase session acquisition is not yet implemented in this client: local handles work fine (`local_browser.launch`), but this example was migrated to a factory that doesn't exist yet. Consider keeping caching.py on the local path, or leave the example using the not-yet-available browserbase path out of the migrated set until Browserbase acquisition lands.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as User Code
    participant BrowserF as Browser Factory
    participant Stagehand as Stagehand
    participant RPC as RPC Client
    participant Worker as Stagehand Worker
    participant CDP as CDP/Transport

    Note over User,CDP: NEW: Exclusive Stagehand.create() lifecycle

    User->>BrowserF: await local_browser.launch() or browserbase.launch()
    BrowserF-->>User: StagehandBrowser handle

    User->>Stagehand: await Stagehand.create(browser=browser, ...)
    Stagehand->>Stagehand: Validate handle via _BROWSER_TOKEN
    alt Invalid handle
        Stagehand-->>User: TypeError
    end

    Stagehand->>Stagehand: Build StagehandClientCreateConfig
    Stagehand->>BrowserF: _claim_browser(handle)
    BrowserF-->>Stagehand: _ClaimedBrowser (cdp_client, worker_init_metadata)

    Stagehand->>CDP: Create CDPClient from claimed transport
    Stagehand->>RPC: Create RPCClient(cdp_client, timeout)
    Stagehand->>RPC: Send stagehand.init

    Note over RPC,Worker: NEW: Wire shape uses worker_init_metadata
    RPC->>Worker: stagehand.init(protocol_version, browser_cdp_url, api_key, model, log_level, browser_metadata)
    alt Worker metadata defined
        Note over Worker: Worker api_key overrides caller api_key
        Note over Worker: Local browser omits browser field entirely
    end
    Worker-->>RPC: StagehandInitResult
    RPC-->>Stagehand: Initialized

    alt Init fails or is cancelled
        Stagehand->>BrowserF: _release_browser(handle)
        Stagehand->>RPC: Close RPC (detaches, no transport close)
        Stagehand-->>User: Propagates error
    else Success
        Stagehand-->>User: Stagehand instance
    end

    Note over User,CDP: Runtime operations (unchanged)

    User->>Stagehand: stagehand.act/extract/observe()
    Stagehand->>RPC: stagehand.act/etc.
    RPC->>Worker: RPC method call
    Worker-->>RPC: Result
    RPC-->>Stagehand: Result
    Stagehand-->>User: Response

    Note over User,CDP: NEW: Clean shutdown (explicit ordering)

    User->>Stagehand: await stagehand.close()
    Stagehand->>Stagehand: Memoized close (one-shot)
    Stagehand->>RPC: stagehand.close
    RPC->>Worker: stagehand.close
    Worker-->>RPC: StagehandCloseResult
    Stagehand->>RPC: Close RPC client (no transport close)
    RPC->>CDP: close(close_transport=False)
    Stagehand-->>User: done

    User->>BrowserF: await browser.close()
    BrowserF->>CDP: close transport/process
    CDP-->>BrowserF: done
    BrowserF-->>User: done

    Note over User,CDP: NEW: stagehand.close() never touches browser or CDP socket

Loading

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

Re-trigger cubic</sub>