2026-01-05 20:45:33 -07:00
|
|
|
# yaml-language-server: $schema=https://app.stainless.com/config-internal.schema.json
|
|
|
|
|
|
2026-01-29 11:13:07 -08:00
|
|
|
##########################################################################
|
|
|
|
|
############ DO NOT EDIT THIS FILE IN THE STAINLESS STUDIO UI ############
|
|
|
|
|
############ !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ############
|
|
|
|
|
############ ONLY EDIT IN browserbase/stagehand/stainless.yml ############
|
|
|
|
|
##########################################################################
|
|
|
|
|
|
2026-01-05 20:45:33 -07:00
|
|
|
edition: 2025-10-10
|
|
|
|
|
|
|
|
|
|
organization:
|
|
|
|
|
name: stagehand
|
|
|
|
|
docs: https://docs.stagehand.dev
|
2026-01-20 12:14:41 -07:00
|
|
|
contact: ""
|
2026-01-05 20:45:33 -07:00
|
|
|
|
|
|
|
|
targets:
|
|
|
|
|
python:
|
|
|
|
|
edition: python.2025-11-20
|
|
|
|
|
package_name: stagehand
|
2026-01-29 11:13:07 -08:00
|
|
|
project_name: stagehand
|
|
|
|
|
production_repo: browserbase/stagehand-python
|
2026-01-05 20:45:33 -07:00
|
|
|
publish:
|
|
|
|
|
pypi: true
|
|
|
|
|
go:
|
|
|
|
|
edition: go.2025-10-08
|
|
|
|
|
package_name: stagehand
|
|
|
|
|
production_repo: browserbase/stagehand-go
|
|
|
|
|
options:
|
|
|
|
|
enable_v2: true
|
|
|
|
|
java:
|
|
|
|
|
edition: java.2025-10-08
|
|
|
|
|
reverse_domain: com.browserbase.api
|
|
|
|
|
package_name: stagehand
|
|
|
|
|
production_repo: browserbase/stagehand-java
|
|
|
|
|
publish:
|
2026-02-25 13:07:06 -07:00
|
|
|
maven:
|
|
|
|
|
sonatype_platform: portal
|
2026-01-05 20:45:33 -07:00
|
|
|
kotlin:
|
|
|
|
|
edition: kotlin.2025-10-08
|
|
|
|
|
reverse_domain: com.browserbase.api
|
|
|
|
|
package_name: stagehand
|
|
|
|
|
production_repo: browserbase/stagehand-kotlin
|
|
|
|
|
publish:
|
2026-02-25 13:07:06 -07:00
|
|
|
maven:
|
|
|
|
|
sonatype_platform: portal
|
2026-01-05 20:45:33 -07:00
|
|
|
ruby:
|
|
|
|
|
edition: ruby.2025-10-08
|
|
|
|
|
gem_name: stagehand
|
|
|
|
|
production_repo: browserbase/stagehand-ruby
|
|
|
|
|
publish:
|
|
|
|
|
rubygems: false
|
|
|
|
|
typescript:
|
|
|
|
|
edition: typescript.2025-10-10
|
|
|
|
|
package_name: stagehand-sdk
|
|
|
|
|
production_repo: null
|
|
|
|
|
publish:
|
|
|
|
|
npm: false
|
|
|
|
|
options:
|
2026-01-30 17:27:35 -07:00
|
|
|
mcp_server: false
|
2026-01-05 20:45:33 -07:00
|
|
|
php:
|
|
|
|
|
edition: php.2025-10-08
|
|
|
|
|
package_name: stagehand
|
|
|
|
|
production_repo: browserbase/stagehand-php
|
|
|
|
|
composer_package_name: browserbase/stagehand
|
2026-01-29 11:13:07 -08:00
|
|
|
publish:
|
|
|
|
|
packagist: true
|
2026-01-05 20:45:33 -07:00
|
|
|
csharp:
|
|
|
|
|
edition: csharp.2025-10-08
|
|
|
|
|
package_name: stagehand
|
|
|
|
|
production_repo: browserbase/stagehand-net
|
|
|
|
|
publish:
|
2026-01-29 11:13:07 -08:00
|
|
|
nuget: true
|
2026-01-20 19:03:12 -08:00
|
|
|
# cli:
|
|
|
|
|
# edition: cli.2025-10-08
|
|
|
|
|
# binary_name: stagehand
|
|
|
|
|
# production_repo: browserbase/stagehand-cli
|
2026-01-05 20:45:33 -07:00
|
|
|
|
|
|
|
|
# `environments` are a map of the name of the environment (e.g. "sandbox",
|
|
|
|
|
# "production") to the corresponding url to use.
|
|
|
|
|
environments:
|
|
|
|
|
production: https://api.stagehand.browserbase.com
|
|
|
|
|
# dev: https://api.stagehand.dev.browserbase.com
|
2026-01-29 11:13:07 -08:00
|
|
|
# local: http://stagehand-api.localhost
|
2026-01-05 20:45:33 -07:00
|
|
|
|
2026-01-20 12:14:41 -07:00
|
|
|
# OpenAPI transforms applied by Stainless during SDK generation.
|
[STG-1536] Split `packages/stagehand/server` into separate server-v3 and server-v4 dirs (#1796)
# Follow-up Tasks
- [ ] Update stainless SDK custom code for all languages to pull new
`stagehand-server-v3-darwin-x64` binary names (`-v3-` added)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Split the Stagehand API into `packages/server-v3` and
`packages/server-v4`, each with its own builds, tests, SEA binaries, and
release workflows. Delivers STG-1536 and lets us keep v3 stable while
iterating on v4; CI/test discovery and OpenAPI artifacts are versioned.
- **Refactors**
- Renamed the original server to `packages/server-v3`
(`@browserbasehq/stagehand-server-v3`); updated docs and runtime path
helpers (now synced across core/docs/evals and both servers), ESLint
globs/ignores, scripts/Turbo filters, tests, and Stainless to read
`packages/server-v3/openapi.v3.yaml`; v3 SEA binaries use
`stagehand-server-v3-*`.
- Added `packages/server-v4` (`@browserbasehq/stagehand-server-v4`) with
`/v4/**` routes, SSE streaming via `x-stream-response`, LRU/TTL
in-memory session store, health/readiness, logging/metrics,
`openapi.v4.yaml` + generator, SEA tooling, and v4 integration tests.
- CI: path filters, test discovery, and artifacts cover both versions;
added `stagehand-server-v4-release.yml` and
`stagehand-server-v4-sea-build.yml`; renamed v3 workflows; artifacts
include `packages/server-v3/**` and `packages/server-v4/**` dists and
OAS.
- **Migration**
- Replace `packages/server/**` refs with `packages/server-v3/**` or
`packages/server-v4/**`.
- Use new package filters and binary names:
`@browserbasehq/stagehand-server-v3` /
`@browserbasehq/stagehand-server-v4`; `stagehand-server-v3-*` /
`stagehand-server-v4-*`.
- Update OpenAPI consumers to `packages/server-v3/openapi.v3.yaml` or
`packages/server-v4/openapi.v4.yaml`.
<sup>Written for commit 2b9114ca8097d28ac1567fc67062b24f789a5c2e.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1796">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
2026-03-09 17:32:57 -07:00
|
|
|
# This keeps the generated `packages/server-v3/openapi.v3.yaml` faithful to the Fastify+Zod source,
|
2026-01-20 12:14:41 -07:00
|
|
|
# while still producing a Stainless-compatible spec for codegen.
|
|
|
|
|
openapi:
|
|
|
|
|
code_samples: mintlify
|
|
|
|
|
transforms:
|
|
|
|
|
# Stainless doesn't support `propertyNames` (emitted by some JSON Schema generators).
|
|
|
|
|
- command: remove
|
|
|
|
|
reason: Remove unsupported JSON Schema keyword
|
|
|
|
|
args:
|
|
|
|
|
target: "$..propertyNames"
|
|
|
|
|
|
|
|
|
|
# Empty-schema `additionalProperties: {}` is equivalent to `true`, and avoids Stainless issues.
|
|
|
|
|
- command: update
|
|
|
|
|
reason: Treat record value schema as any
|
|
|
|
|
args:
|
|
|
|
|
target: "$.components.schemas.BrowserbaseSessionCreateParams.properties.userMetadata.additionalProperties"
|
|
|
|
|
value: true
|
|
|
|
|
- command: update
|
|
|
|
|
reason: Treat record value schema as any
|
|
|
|
|
args:
|
|
|
|
|
target: "$.components.schemas.BrowserbaseSessionCreateParamsOutput.properties.userMetadata.additionalProperties"
|
|
|
|
|
value: true
|
|
|
|
|
- command: update
|
|
|
|
|
reason: Treat record value schema as any
|
|
|
|
|
args:
|
|
|
|
|
target: "$.components.schemas.ExtractRequest.properties.schema.additionalProperties"
|
|
|
|
|
value: true
|
|
|
|
|
- command: update
|
|
|
|
|
reason: Treat record value schema as any
|
|
|
|
|
args:
|
|
|
|
|
target: "$.components.schemas.AgentResultData.properties.metadata.additionalProperties"
|
|
|
|
|
value: true
|
|
|
|
|
- command: update
|
|
|
|
|
reason: Treat record value schema as any
|
|
|
|
|
args:
|
|
|
|
|
target: "$.components.schemas.AgentResultDataOutput.properties.metadata.additionalProperties"
|
|
|
|
|
value: true
|
|
|
|
|
- command: update
|
|
|
|
|
reason: Treat passthrough schema as any
|
|
|
|
|
args:
|
|
|
|
|
target: "$.components.schemas.AgentAction.additionalProperties"
|
|
|
|
|
value: true
|
|
|
|
|
|
|
|
|
|
# Add a stable title to help Stainless infer a consistent name for this anonymous array schema.
|
|
|
|
|
- command: merge
|
|
|
|
|
reason: Improve name inference for anonymous arrays
|
|
|
|
|
args:
|
|
|
|
|
target: '$.components.schemas.BrowserbaseSessionCreateParams.properties.proxies.anyOf[?(@.type == "array")]'
|
|
|
|
|
value:
|
|
|
|
|
title: ProxyConfigList
|
|
|
|
|
- command: merge
|
|
|
|
|
reason: Improve name inference for anonymous arrays
|
|
|
|
|
args:
|
|
|
|
|
target: '$.components.schemas.BrowserbaseSessionCreateParamsOutput.properties.proxies.anyOf[?(@.type == "array")]'
|
|
|
|
|
value:
|
|
|
|
|
title: ProxyConfigList
|
|
|
|
|
|
|
|
|
|
# `result` is intentionally untyped and should be treated as `any` in Stainless.
|
|
|
|
|
- command: merge
|
|
|
|
|
reason: Treat StreamEventSystemData.result as any
|
|
|
|
|
args:
|
|
|
|
|
target: "$.components.schemas.StreamEventSystemData.properties.result"
|
|
|
|
|
value:
|
|
|
|
|
x-stainless-any: true
|
|
|
|
|
- command: merge
|
|
|
|
|
reason: Treat StreamEventSystemDataOutput.result as any
|
|
|
|
|
args:
|
|
|
|
|
target: "$.components.schemas.StreamEventSystemDataOutput.properties.result"
|
|
|
|
|
value:
|
|
|
|
|
x-stainless-any: true
|
|
|
|
|
|
2026-01-05 20:45:33 -07:00
|
|
|
# `resources` define the structure and organization for your API, such as how
|
|
|
|
|
# methods and models are grouped together and accessed. See the [configuration
|
|
|
|
|
# guide] for more information.
|
|
|
|
|
#
|
|
|
|
|
# [configuration guide]: https://www.stainless.com/docs/guides/configure#resources
|
|
|
|
|
resources:
|
|
|
|
|
sessions:
|
|
|
|
|
models:
|
2026-01-20 12:14:41 -07:00
|
|
|
action: "#/components/schemas/Action"
|
|
|
|
|
model_config: "#/components/schemas/ModelConfig"
|
|
|
|
|
stream_event: "#/components/schemas/StreamEvent"
|
2026-01-05 20:45:33 -07:00
|
|
|
methods:
|
|
|
|
|
start: post /v1/sessions/start
|
|
|
|
|
act:
|
|
|
|
|
endpoint: post /v1/sessions/{id}/act
|
|
|
|
|
type: http
|
|
|
|
|
streaming:
|
|
|
|
|
param_discriminator: streamResponse
|
|
|
|
|
stream_event_model: sessions.stream_event
|
|
|
|
|
params_type_name: streamResponse
|
|
|
|
|
extract:
|
|
|
|
|
endpoint: post /v1/sessions/{id}/extract
|
|
|
|
|
type: http
|
|
|
|
|
streaming:
|
|
|
|
|
param_discriminator: streamResponse
|
|
|
|
|
stream_event_model: sessions.stream_event
|
|
|
|
|
params_type_name: streamResponse
|
|
|
|
|
observe:
|
|
|
|
|
endpoint: post /v1/sessions/{id}/observe
|
|
|
|
|
type: http
|
|
|
|
|
streaming:
|
|
|
|
|
param_discriminator: streamResponse
|
|
|
|
|
stream_event_model: sessions.stream_event
|
|
|
|
|
params_type_name: streamResponse
|
|
|
|
|
execute:
|
|
|
|
|
endpoint: post /v1/sessions/{id}/agentExecute
|
|
|
|
|
type: http
|
|
|
|
|
streaming:
|
|
|
|
|
param_discriminator: streamResponse
|
|
|
|
|
stream_event_model: sessions.stream_event
|
|
|
|
|
params_type_name: streamResponse
|
|
|
|
|
navigate: post /v1/sessions/{id}/navigate
|
2026-01-21 17:11:55 -08:00
|
|
|
replay: get /v1/sessions/{id}/replay
|
2026-01-05 20:45:33 -07:00
|
|
|
end: post /v1/sessions/{id}/end
|
|
|
|
|
|
|
|
|
|
streaming:
|
|
|
|
|
on_event:
|
Add explicit SSE event names for local v3 streaming (#1858)
## Why
The stainless sdks are dropping the final finished SSE event instead of
yielding it. This is due to the fact that we were not using `event`
fields (basically setting event types) as per the SSE spec.
The fix is to emit explicit SSE `event:` names and match them in
Stainless. But on the hosted API we cannot switch that on for everyone
at once, because older clients still expect the old `data:`-only SSE
framing. Thus, we will need to have branching logic in our hosted
server:
1. Legacy (old stainless sdks, stagehand-js): continue to not return
`event` field.
2. New Stainless SDKs on `>= 3.13.0`: use typed SSE framing with
`event:` + `data:`.
Once this and it's core counterpart PR are merged, then we will release
another version of all stainless sdks - `3.13`, which will be the first
typed-SSE release.
## What Changed
- emit explicit SSE `event:` names from the local v3 streaming helper
while keeping the JSON `data:` payload unchanged
- switch Stainless streaming matching to explicit `event_type` handlers
- update the documented stream shape, regenerated v3 OpenAPI, and a
focused integration assertion
## Testing
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av --filter
@browserbasehq/stagehand-server-v3 run gen:openapi`
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av exec prettier --check
stainless.yml`
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av --filter
@browserbasehq/stagehand lint`
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av --filter
@browserbasehq/stagehand-server-v3 lint`
A test run with the three different client types against the updated
server:
<img width="765" height="230" alt="Screenshot 2026-03-20 at 11 01 50 AM"
src="https://github.com/user-attachments/assets/af97c8ec-d7f9-4ae6-95a0-16a3c2906934"
/>
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Emit explicit SSE event names for v3 streaming (`starting`, `connected`,
`running`, `finished`, `error`) while keeping the JSON `data:` payload
unchanged. Updates the streaming helper, Stainless config, OpenAPI docs,
and tests to use and verify typed events.
- New Features
- Server now sends `event: <status>` with `data: { data, type, id }`.
- Switched `stainless.yml` streaming matching to `event_type` (yields on
starting/connected/running/finished; handles `error`).
- Added integration test asserting event names match payload status;
updated OpenAPI description and core type docs.
- Dependencies
- Added changeset to publish patch updates for
`@browserbasehq/stagehand` and `@browserbasehq/stagehand-server-v3`.
<sup>Written for commit 96cd0372df7cad7d1986de0f9405e5a4f7f0e781.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1858">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
2026-03-24 10:20:43 -07:00
|
|
|
- event_type: error
|
2026-01-05 20:45:33 -07:00
|
|
|
handle: error
|
Add explicit SSE event names for local v3 streaming (#1858)
## Why
The stainless sdks are dropping the final finished SSE event instead of
yielding it. This is due to the fact that we were not using `event`
fields (basically setting event types) as per the SSE spec.
The fix is to emit explicit SSE `event:` names and match them in
Stainless. But on the hosted API we cannot switch that on for everyone
at once, because older clients still expect the old `data:`-only SSE
framing. Thus, we will need to have branching logic in our hosted
server:
1. Legacy (old stainless sdks, stagehand-js): continue to not return
`event` field.
2. New Stainless SDKs on `>= 3.13.0`: use typed SSE framing with
`event:` + `data:`.
Once this and it's core counterpart PR are merged, then we will release
another version of all stainless sdks - `3.13`, which will be the first
typed-SSE release.
## What Changed
- emit explicit SSE `event:` names from the local v3 streaming helper
while keeping the JSON `data:` payload unchanged
- switch Stainless streaming matching to explicit `event_type` handlers
- update the documented stream shape, regenerated v3 OpenAPI, and a
focused integration assertion
## Testing
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av --filter
@browserbasehq/stagehand-server-v3 run gen:openapi`
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av exec prettier --check
stainless.yml`
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av --filter
@browserbasehq/stagehand lint`
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av --filter
@browserbasehq/stagehand-server-v3 lint`
A test run with the three different client types against the updated
server:
<img width="765" height="230" alt="Screenshot 2026-03-20 at 11 01 50 AM"
src="https://github.com/user-attachments/assets/af97c8ec-d7f9-4ae6-95a0-16a3c2906934"
/>
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Emit explicit SSE event names for v3 streaming (`starting`, `connected`,
`running`, `finished`, `error`) while keeping the JSON `data:` payload
unchanged. Updates the streaming helper, Stainless config, OpenAPI docs,
and tests to use and verify typed events.
- New Features
- Server now sends `event: <status>` with `data: { data, type, id }`.
- Switched `stainless.yml` streaming matching to `event_type` (yields on
starting/connected/running/finished; handles `error`).
- Added integration test asserting event names match payload status;
updated OpenAPI description and core type docs.
- Dependencies
- Added changeset to publish patch updates for
`@browserbasehq/stagehand` and `@browserbasehq/stagehand-server-v3`.
<sup>Written for commit 96cd0372df7cad7d1986de0f9405e5a4f7f0e781.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1858">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
2026-03-24 10:20:43 -07:00
|
|
|
- event_type: [starting, connected, running, finished]
|
2026-01-05 20:45:33 -07:00
|
|
|
handle: yield
|
|
|
|
|
|
|
|
|
|
settings:
|
|
|
|
|
# All generated integration tests that hit the prism mock http server are marked
|
|
|
|
|
# as skipped. Removing this setting or setting it to false enables tests, but
|
|
|
|
|
# doing so may result in test failures due to bugs in the test server.
|
|
|
|
|
#
|
|
|
|
|
# [prism mock http server]: https://stoplight.io/open-source/prism
|
|
|
|
|
disable_mock_tests: true
|
2026-01-27 09:40:41 -08:00
|
|
|
license: MIT
|
2026-01-05 20:45:33 -07:00
|
|
|
|
|
|
|
|
# `client_settings` define settings for the API client, such as extra constructor
|
|
|
|
|
# arguments (used for authentication), retry behavior, idempotency, etc.
|
|
|
|
|
client_settings:
|
|
|
|
|
opts:
|
|
|
|
|
BROWSERBASE_API_KEY:
|
|
|
|
|
type: string
|
|
|
|
|
read_env: BROWSERBASE_API_KEY
|
|
|
|
|
description: Your [Browserbase API Key](https://www.browserbase.com/settings)
|
|
|
|
|
nullable: false
|
|
|
|
|
auth:
|
|
|
|
|
security_scheme: BBApiKeyAuth
|
|
|
|
|
BROWSERBASE_PROJECT_ID:
|
|
|
|
|
type: string
|
|
|
|
|
read_env: BROWSERBASE_PROJECT_ID
|
|
|
|
|
description: Your [Browserbase Project ID](https://www.browserbase.com/settings)
|
|
|
|
|
nullable: false
|
|
|
|
|
auth:
|
|
|
|
|
security_scheme: BBProjectIdAuth
|
|
|
|
|
MODEL_API_KEY:
|
|
|
|
|
type: string
|
|
|
|
|
read_env: MODEL_API_KEY
|
|
|
|
|
description: Your LLM provider API key (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
|
|
|
|
|
nullable: false
|
|
|
|
|
auth:
|
|
|
|
|
security_scheme: LLMModelApiKeyAuth
|
|
|
|
|
|
|
|
|
|
security_schemes:
|
|
|
|
|
BBApiKeyAuth:
|
|
|
|
|
type: apiKey
|
|
|
|
|
in: header
|
|
|
|
|
name: x-bb-api-key
|
|
|
|
|
BBProjectIdAuth:
|
|
|
|
|
type: apiKey
|
|
|
|
|
in: header
|
|
|
|
|
name: x-bb-project-id
|
|
|
|
|
LLMModelApiKeyAuth:
|
|
|
|
|
type: apiKey
|
|
|
|
|
in: header
|
|
|
|
|
name: x-model-api-key
|
|
|
|
|
|
|
|
|
|
security:
|
|
|
|
|
- BBApiKeyAuth: []
|
|
|
|
|
BBProjectIdAuth: []
|
|
|
|
|
LLMModelApiKeyAuth: []
|
|
|
|
|
|
|
|
|
|
# `readme` is used to configure the code snippets that will be rendered in the
|
|
|
|
|
# README.md of various SDKs.
|
|
|
|
|
readme:
|
|
|
|
|
example_requests:
|
|
|
|
|
default:
|
|
|
|
|
type: request
|
|
|
|
|
endpoint: post /v1/sessions/start
|
|
|
|
|
params:
|
2026-01-20 12:14:41 -07:00
|
|
|
modelName: "openai/gpt-5-nano"
|
2026-01-05 20:45:33 -07:00
|
|
|
headline:
|
|
|
|
|
type: request
|
|
|
|
|
endpoint: post /v1/sessions/{id}/act
|
|
|
|
|
params:
|
2026-01-20 12:14:41 -07:00
|
|
|
input: "click the first link on the page"
|
|
|
|
|
id: "00000000-your-session-id-000000000000"
|
2026-01-05 20:45:33 -07:00
|
|
|
|
|
|
|
|
diagnostics:
|
|
|
|
|
ignored:
|
|
|
|
|
Ruby/NameNotAllowed: true
|
|
|
|
|
Ruby/NameShadowedBuiltin: true
|