stagehand/stainless.yml
Sam F 8bf5db8eb8
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 18:20:43 +01:00

283 lines
9.0 KiB
YAML

# yaml-language-server: $schema=https://app.stainless.com/config-internal.schema.json
##########################################################################
############ DO NOT EDIT THIS FILE IN THE STAINLESS STUDIO UI ############
############ !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ############
############ ONLY EDIT IN browserbase/stagehand/stainless.yml ############
##########################################################################
edition: 2025-10-10
organization:
name: stagehand
docs: https://docs.stagehand.dev
contact: ""
targets:
python:
edition: python.2025-11-20
package_name: stagehand
project_name: stagehand
production_repo: browserbase/stagehand-python
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:
maven:
sonatype_platform: portal
kotlin:
edition: kotlin.2025-10-08
reverse_domain: com.browserbase.api
package_name: stagehand
production_repo: browserbase/stagehand-kotlin
publish:
maven:
sonatype_platform: portal
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:
mcp_server: false
php:
edition: php.2025-10-08
package_name: stagehand
production_repo: browserbase/stagehand-php
composer_package_name: browserbase/stagehand
publish:
packagist: true
csharp:
edition: csharp.2025-10-08
package_name: stagehand
production_repo: browserbase/stagehand-net
publish:
nuget: true
# cli:
# edition: cli.2025-10-08
# binary_name: stagehand
# production_repo: browserbase/stagehand-cli
# `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
# local: http://stagehand-api.localhost
# OpenAPI transforms applied by Stainless during SDK generation.
# This keeps the generated `packages/server-v3/openapi.v3.yaml` faithful to the Fastify+Zod source,
# 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
# `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:
action: "#/components/schemas/Action"
model_config: "#/components/schemas/ModelConfig"
stream_event: "#/components/schemas/StreamEvent"
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
replay: get /v1/sessions/{id}/replay
end: post /v1/sessions/{id}/end
streaming:
on_event:
- event_type: error
handle: error
- event_type: [starting, connected, running, finished]
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
license: MIT
# `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:
modelName: "openai/gpt-5-nano"
headline:
type: request
endpoint: post /v1/sessions/{id}/act
params:
input: "click the first link on the page"
id: "00000000-your-session-id-000000000000"
diagnostics:
ignored:
Ruby/NameNotAllowed: true
Ruby/NameShadowedBuiltin: true