Add context to browser handles

[miguelg719]

why

Browser context belongs to the factory-created browser handle and should only become available after Stagehand attaches.

what changed

Adds guarded context access plus internal attach/detach primitives across TypeScript, Python, and Go. Includes focused lifecycle tests.

No changeset: this targets the unreleased v4 API.

test plan

• TypeScript browser contract tests
• Python browser tests
• Go browser tests

---

Summary by cubic

Adds browser.context to Stagehand browser handles and makes it available only after Stagehand claims and attaches the browser. Aligns the v4 API with STG-2763 by preferring browser.context over stagehand.context.

• New Features
  • Exposes typed browser.context (BrowserContext) on handles in TypeScript, Python, and Go; available post-claim + attach; errors on early access or re-attach; cleared on detach.
  • Adds internal attach/detach helpers and lifecycle tests across SDKs; updates TypeScript contract tests to include context.
  • Updates v4 docs to accept DomainPolicyInput and ActionInput.

^{Written for commit 2ccb22b. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2ccb22b

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]

cubic analysis

4 issues found across 7 files

Confidence score: 2/5

• In packages/sdk-go/browser.go, Create still sets context on Stagehand and does not populate browser.context via the attach flow, so the documented post-attach access path can fail in Go clients — wire Create/initialization through attachBrowserContext so browser.context is reliably set.
• In packages/sdk-python/src/stagehand/browser.py, attach/detach primitives exist but are not connected to Stagehand runtime initialization, which can leave browser.context unavailable when users follow the new API pattern — hook attachment into the initialization lifecycle and validate with an integration test.
• In packages/sdk-ts/src/browser/index.ts, attachment is not integrated into the Stagehand lifecycle, so browser.context can remain unset in the canonical TypeScript path, creating cross-SDK behavior drift and user-facing regressions — invoke attach during Stagehand startup and assert browser.context after attach.
• In packages/sdk-go/browser_test.go, both Browser.Context() and Stagehand.Context() remain public/in use, so callers can keep depending on the old path and mask migration gaps — converge tests and public usage on browser.context (or explicitly deprecate the old accessor).

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/browser.py">

<violation number="1" location="packages/sdk-python/src/stagehand/browser.py:176">
P1: According to linked Linear issue STG-2763, `browser.context` should be the API access pattern after attachment, but this change adds attach/detach primitives without wiring them into runtime Stagehand initialization/teardown. As shipped, `browser.context` stays unavailable in real usage because the browser handle is never populated.</violation>
</file>

<file name="packages/sdk-go/browser_test.go">

<violation number="1" location="packages/sdk-go/browser_test.go:23">
P2: According to linked Linear issue STG-2763, the API should expose one access pattern (browser.context) rather than both. This change adds Browser.Context() but leaves Stagehand.Context() public and still in use, so both patterns remain exposed after this PR. Consider removing or deprecating Stagehand.Context() and migrating remaining callers (stagehand.go:355 and the live tests) to the browser handle so the access pattern is singular.</violation>
</file>

<file name="packages/sdk-go/browser.go">

<violation number="1" location="packages/sdk-go/browser.go:79">
P1: According to linked Linear issue STG-2763, `browser.context` should become available after attach, but this Go path is never populated. `Create` still writes the context to `Stagehand` and never calls `attachBrowserContext`, so `Browser.Context()` will keep returning `ErrNotInitialized` in normal use.</violation>
</file>

<file name="packages/sdk-ts/src/browser/index.ts">

<violation number="1" location="packages/sdk-ts/src/browser/index.ts:71">
P1: According to linked Linear issue STG-2763, `browser.context` should become the canonical attached context path, but this implementation never wires attachment into the Stagehand lifecycle. `browser.context` will always throw in real usage unless `attachStagehandBrowserContext` is called manually; consider attaching after successful `Stagehand.create` init and detaching during close.</violation>
</file>

Linked issue analysis

Linked issue: STG-2763: Change stagehand.context to browser.context

Status	Acceptance criteria	Notes
✅	Expose browser.context on browser handles (SDK surface)	Each SDK adds a context property to the browser handle/interface: TypeScript StagehandBrowser includes context and accessor; Python StagehandBrowser exposes .context; Go Browser.Context() method implemented.
✅	Block access until Stagehand claims and attaches the browser; error on early access	All SDKs throw or return an error when context is accessed before attach; the code enforces claimed check before attaching.
✅	Provide internal attach/detach primitives (TypeScript, Python, Go) and prevent double-attach	Each language adds attach/detach functions and checks for claimed state and existing context to prevent replacement.
✅	Add lifecycle tests for claim/attach/detach and error paths across SDKs	Tests were added/modified to cover unavailable-before-attach, attach success, reject second attach, and detachment behavior in each SDK test suite.

Architecture diagram

sequenceDiagram
    participant User
    participant SH as Stagehand (SDK)
    participant BH as Browser Handle (TS/Py/Go)
    participant BC as BrowserContext

    Note over User,BC: Initialization Phase

    User->>BH: GET browser.context
    alt NEW: Context not yet attached
        BH-->>User: Throw Error (Runtime/ErrNotInitialized)
    end

    User->>SH: Stagehand.create({ browser: handle })
    
    rect rgb(240, 240, 240)
        Note right of SH: NEW: Attachment Lifecycle
        SH->>BH: claimBrowser()
        SH->>BC: Create Context
        SH->>BH: NEW: attachBrowserContext(context)
        BH->>BH: Store context reference
    end

    SH-->>User: Stagehand Instance

    Note over User,BC: Usage Phase

    User->>BH: GET browser.context
    BH-->>User: Return context

    opt NEW: Attempt duplicate attachment
        SH->>BH: attachBrowserContext(new_context)
        BH-->>SH: Throw Error ("already has a context")
    end

    Note over User,BC: Cleanup Phase

    User->>SH: Close / De-init
    SH->>BH: NEW: detachBrowserContext()
    BH->>BH: context = nil / undefined
    SH->>BH: releaseBrowserClaim() (Existing)
    SH-->>User: Done

    User->>BH: GET browser.context
    BH-->>User: Throw Error (Context unavailable)

Loading

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

Re-trigger cubic</sub>