[WIP] New Understudy v4 Page.* Routes

[pirate]

why

what changed

• /v4/browsersession (combination of Browser + Session)
• /v4/page/* new page routes
• /v4/stagehand/* act/observe/extract routes
• /v4/log for streaming SSE events in realtime WIP
• /v4/llm for configuring LLM options / retrieving token usage info + convo history

test plan

---

Summary by cubic

Introduces the v4 API with browsersession and page.* routes, standard response envelopes, action persistence, and an OpenAPI v4 spec. Splits the server into @browserbasehq/stagehand-server-v3 and @browserbasehq/stagehand-server-v4 with dedicated CI/release workflows and SEA builds.

• New Features

  • browsersession REST routes: create/get/end session, action list/detail, and one-file-per-route handlers for activePage, awaitActivePage, newPage, cookies/addCookies/clearCookies, addInitScript, configuredViewport, connectURL, browserbase* URLs/IDs, and getFullFrameTreeByMainFrameId.
  • page.* endpoints wired to @browserbasehq/stagehand (evaluate, sendCDP, screenshot, snapshot, waits, setViewportSize, close).
  • In-memory session store with LRU/TTL, action history, shared success/error responses, optional SSE streaming, and health/readiness endpoints with request logging.
  • OpenAPI v4 (packages/server-v4/openapi.v4.yaml) generated from Zod components; routes registered.

• Migration

  • Replace /v4/sessions/* with /v4/browsersession/*.
  • Server packages/binaries renamed: @browserbasehq/stagehand-server-v3 and @browserbasehq/stagehand-server-v4 with stagehand-server-v3-*/stagehand-server-v4-*; CI, release, and SEA build workflows updated (including SEA fuse handling).

^{Written for commit 276ddc3. Summary will update on new commits. Review in cubic}

todo:

• Client object should not have a default page. The user must call await something.pages()[0] to get the pages array. Each page in the array should have an id (or composite id baked into it). we will need custom code in stainless for this.
• neither client nor v4 server should pin an active page ID.
• instead, we should only expose page.* methods on the stainless page model (requires custom code)

>>> pages = await client.browsersession.pages()

>>> page[0].click('/some/xpath')
# internally gets mapped to this with custom code to sticky the page struct as an arg ->
#   client.page.click(page={url,frameId,tabindex,title}, '/some/xpath')

>>> print(page[0])
{
    url
    frameId
    tabindex
    title
}

• we also need to make sure that coordinate based actions ALL optionally return an array or object of selectors. currently, some return a single string, and others (like dragAndDrop) return multiple strings. we should standardize this so that the return type is something that may contain multiple selectors. eg, always return an array or object.
• ex, dragAndDrop returns this return [fromXpath ?? "", toXpath ?? ""];

[changeset-bot]

⚠️ No Changeset found

Latest commit: 276ddc3

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

[seanmcguire12]

we need a mask param here