Add explicit SSE event names for local v3 streaming

Merged
MO
8mo ago
+80-21

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:
Screenshot 2026-03-20 at 11 01 50 AM


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.