fix(integrations): propagate facade close lifecycle

[shrey150]

why

Current main already recognizes browser.close() inside the Playwright-shaped worker runtime, thanks to #2769 / 544ec87f. The worker sets closeRequested, but the batch result drops that signal and the Node host never consumes it. A tool call can therefore report success without releasing the host-owned browser resources.

Cleanup must stay in the host: the Chrome extension worker should not receive Browserbase credentials or own session state. This PR establishes the shared facade contract and implements it for the core stdio host. Eve and Pi adoption are intentionally separated into stacked follow-ups so each host's ownership policy can be reviewed independently.

what changed

• The batch envelope carries closeRequested alongside the model value/error. JSON serialization is preflighted so a circular result cannot discard a prior close request.
• StagehandFacadeTools awaits a host lifecycle callback before returning. Execution and close failures are both preserved, and hydrated snapshots are cleared.
• Hosts that have not adopted lifecycle cleanup remain source-compatible, but browser.close() throws a typed StagehandFacadeLifecycleError instead of silently claiming cleanup.
• The stdio host serializes cleanup, tracks in-flight/failed release targets, retries them before replacement and during shutdown, and preserves cleanup errors.
• Browserbase release uses the official @browserbasehq/sdk with a 10-second per-attempt timeout and two transient retries. An ambiguous failed update is verified with sessions.retrieve; only COMPLETED is accepted.
• The canonical prompt and Eve's checked copy distinguish host-owned browser.close() from page-only page.close().
• Current main intentionally permits unlisted noindex: true docs pages; the navigation invariant now excludes those pages instead of failing every newly based PR.

This is PR 1 of a three-PR stack:

1. Shared facade and stdio lifecycle (this PR)
2. Eve host lifecycle (fix(eve): close facade browser resources #2793)
3. Pi host lifecycle (fix(pi): close facade browser resources #2794)

behavior before and after

Stage	Before	After this PR
Worker callback	Sets a local close flag.	Returns the flag in a serializable envelope.
Shared facade	Drops the close request and returns the model result.	Awaits host cleanup before returning.
Adopted host	Has no lifecycle boundary.	Owns and reports cleanup through the callback.
Legacy host	Can appear to close while retaining resources.	Fails explicitly until its adapter adopts lifecycle cleanup.
Stdio cleanup	Can lose failed/racing cleanup ownership.	Serializes cleanup and retains retryable release targets.
Browserbase fallback	Hand-written, unbounded request path.	Official SDK with bounded retries/timeouts and completion verification.

test plan

• Core integration tests: 37/37
• Docs SDK-reference/navigation tests: 27/27
• Existing Eve tests against the compatibility boundary: 5/5
• Existing Pi tests against the compatibility boundary: 3/3
• Core, Eve, and Pi typechecks
• Core build and Eve consumer build
• Focused oxfmt and oxlint checks
• Built-helper transport probe: two transient 500 responses produced SDK retry attempts 0/1/2 before success

The live Eve before/after and Online-Mind2Web-style evidence is reported in the stacked Eve PR, where the Eve-owned persistence and release behavior is introduced.

No changeset is included because the shared integration package and both examples are private.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8fd1c83

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]

All reported issues were addressed across 11 files

Architecture diagram

sequenceDiagram
    participant Model as AI Model (Agent)
    participant Facade as Facade Tools (tools.ts)
    participant Runtime as Playwright Compat Runtime
    participant Host as Eve/Pi/Stdio Host
    participant Browserbase as Browserbase API

    Note over Model,Facade: Tool Call: run("await browser.close()")
    Model->>Facade: run(code: "await browser.close()")
    Facade->>Runtime: experimentalBatch(code)
    Runtime->>Runtime: context.close() → closeRequested = true
    Runtime-->>Facade: { value, closeRequested: true }

    alt closeRequested is true
        Facade->>Facade: Clear hydrated snapshots
        Facade->>Host: lifecycle.close()
        Host->>Host: Detach facade, close Stagehand
        Host->>Host: Close local browser

        alt Eve host with Browserbase session
            Host->>Browserbase: POST /v1/sessions/{id} (REQUEST_RELEASE)
            Browserbase-->>Host: 200 OK
            Host->>Host: Clear persisted session ID
        else Release failed
            Browserbase-->>Host: Error / non-200
            Host->>Host: Mark session as suspect
            Host-->>Facade: throw Error("Failed to release...")
        end

        alt Browser code also threw error
            Facade-->>Model: AggregateError (execution + close)
        else Clean close
            Facade-->>Model: Return value
        end
    end

    Note over Host,Model: Next Tool Call (after close)
    Model->>Facade: run(...) or snapshot(...)
    alt Eve host
        Host->>Host: No existing resources
        Host->>Host: createResources() → new browser session
        Host-->>Facade: Fresh facade tools
    else Pi host
        Host->>Host: closeResources() replaced with new
        Host-->>Facade: Fresh facade tools
    end
    Facade-->>Model: Result from new session

Loading

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

Re-trigger cubic</sub>

[cubic-dev-ai]

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

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

Re-trigger cubic</sub>

[cubic-dev-ai]

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

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

Re-trigger cubic</sub>

[cubic-dev-ai]

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

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

Re-trigger cubic</sub>

[cubic-dev-ai]

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

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

Re-trigger cubic</sub>