Make browser session ownership and facade mounts explicit - #2892
Open
miguelg719 wants to merge 7 commits into
Open
Make browser session ownership and facade mounts explicit#2892miguelg719 wants to merge 7 commits into
miguelg719 wants to merge 7 commits into
Conversation
🦋 Changeset detectedLatest commit: ef260fa The changes in this PR will be included in the next version bump. This PR includes changesets to release 16 packages
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[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
All reported issues were addressed across 26 files
Architecture diagram
sequenceDiagram
participant Harness as Eval Harness
participant FacadeTool as StagehandFacadeTool
participant Bridge as Facade Bridge
participant FacadeProc as Facade Process
participant SDK as Stagehand SDK
participant BB as Browserbase
participant Mt as Agent MCP Client
Note over Harness,BB: Browser Session Ownership & Lifecycle
Harness->>FacadeTool: start(environment=BROWSERBASE)
alt Shared extension upload enabled
FacadeTool->>BB: acquireRunScopedStagehandExtension()
BB-->>FacadeTool: extensionId + release()
FacadeTool->>FacadeProc: STAGEHAND_BROWSERBASE_EXTENSION_ID env
end
FacadeTool->>Bridge: startStagehandFacadeBridge()
Bridge->>FacadeProc: spawn stdio server (--surface=playwright|legacy)
FacadeProc->>SDK: Stagehand.create()
SDK->>BB: connectBrowser(origin=launched, keepAlive=true)
BB-->>SDK: sessionId
alt CDP attach fails
SDK->>BB: closeSession() (NEW: release owned session)
BB-->>SDK: session closed
SDK-->>FacadeProc: startup error
FacadeProc-->>Bridge: exit
Bridge-->>FacadeTool: start error
FacadeTool->>BB: release() shared extension
else CDP attach succeeds
BB-->>SDK: CDP connected
SDK-->>FacadeProc: session ready
FacadeProc-->>Bridge: session_info tool result
Bridge-->>FacadeTool: { provider, sessionId }
FacadeTool-->>Harness: metadata.browserbaseSessionId/Url
end
Note over Harness,BB: Agent Tool Calls via MCP
Mt->>Bridge: MCP connect (agent mount)
Mt->>FacadeProc: tools/call "run" | "snapshot" | "screenshot"
FacadeProc->>SDK: activePage()
alt Page vanished or crashed
FacadeProc->>SDK: get fresh page (keeper tab survives)
SDK-->>FacadeProc: new page
end
SDK-->>FacadeProc: result
FacadeProc-->>Mt: tool result
Note over Harness,BB: Runner-Initiated Tool Calls (NEW)
Harness->>FacadeTool: callTool("screenshot")
FacadeTool->>Bridge: callTool()
Bridge->>FacadeProc: tools/call (same facade, no new browser)
FacadeProc-->>Bridge: content blocks + isError
alt Browser session lost
FacadeProc->>FacadeProc: detect CDP loss
FacadeProc-->>Bridge: stderr: stagehand_facade_session_lost {...}
Bridge->>Bridge: parseSessionLossTelemetry()
Bridge-->>FacadeTool: browserSessionLoss()
FacadeProc-->>Mt: "Browser session lost (...)" error
end
Note over Harness,BB: Cleanup & Session Release
Harness->>FacadeTool: cleanup()
FacadeTool->>Bridge: close()
Bridge->>FacadeProc: terminate stdio
FacadeProc->>SDK: browser.close()
SDK->>BB: closeSession() (explicit release)
BB-->>SDK: session ended
FacadeTool->>FacadeTool: session.close()
FacadeTool->>BB: release() shared extension
FacadeTool-->>Harness: cleanup complete
Note over Harness,BB: Session Loss During Transport Failure
opt CDP transport drops but session alive
SDK-->>SDK: keepAlive=true prevents auto-close
Mt->>FacadeProc: next tool call
FacadeProc->>SDK: reconnect CDP
SDK-->>FacadeProc: session still valid
end
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
…ion-02-session-ownership
…ion-02-session-ownership
…ion-02-session-ownership
…ion-02-session-ownership
akeimach
approved these changes
Sep 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Makes browser ownership explicit across the eval mount, facade process, and SDK. The tool-owned Browserbase lease stays alive across transport loss and is explicitly released on cleanup; a newly created session is also released when initial CDP attachment fails. Existing-session attachment retains caller ownership. Shared extension uploads retry explicit rate-limit rejections, avoid replaying ambiguous creates, and release their lease if bridge startup fails.
Closes the owned browser after a completed batch requests browser.close(), confines screenshot artifacts to the owned directory, and separates runner-only session metadata from the agent relay. Terminal loss is established by host telemetry, never by an agent-written error prefix. Validates provider settings before acquiring resources and keeps explicit environment inputs isolated.
Exposes typed tool invocation, browser-loss and evidence contracts for later adapters. The legacy prompt is available through direct stdio here; harness selection is added in the later adapter PRs. The inherited shutdown window before initialization returns a session handle remains documented; this change does not introduce a cancellation API.
Validation: 344 runtime/SDK tests and 60 focused eval tests, SDK/core/eval typechecks, core build, formatting, and built stdio dispatch coverage.
Stack position: 2/17. Base:
evals/consolidation-01-hardbench. Each PR contains the change relative to its immediate predecessor.Reviewer entry points:
packages/integrations/core/src/facade/runtime.tspackages/evals/core/tools/stagehandFacadeBridge.tspackages/sdk-ts/src/browser/factories.tsReadiness: local validation is described above; GitHub CI and automated review feedback are pending. This PR is open as non-draft so automated reviewers can run.