Add explicit SSE event names for local v3 streaming (browserbase#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 96cd037.
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. -->

Author: monadoid

.changeset/typed-sse-events.md

@@ -0,0 +1,6 @@
+---
+"@browserbasehq/stagehand": patch
+"@browserbasehq/stagehand-server-v3": patch
+---
+
+Add explicit SSE event names for local v3 streaming and update the generated SDK contract to match.

packages/core/lib/v3/types/public/api.ts

@@ -931,11 +931,9 @@ export const StreamEventLogDataSchema = z
 /**
  * SSE stream event sent during streaming responses.
  *
- * IMPORTANT: Key ordering matters for Stainless SDK generation.
- * The `data` field MUST be serialized first, with `status` as the first key within it.
- * This allows Stainless to use `data_starts_with: '{"data":{"status":"finished"'` for event handling.
- *
- * Expected serialization order: {"data":{"status":...},"type":...,"id":...}
+ * The SSE wire format includes an `event:` line that mirrors the stream status
+ * (`starting`, `connected`, `running`, `finished`, or `error`) followed by a
+ * JSON `data:` line containing the typed payload below.
  */
 export const StreamEventSchema = z
   .object({
@@ -949,7 +947,7 @@ export const StreamEventSchema = z
   .meta({
     id: "StreamEvent",
     description:
-      "Server-Sent Event emitted during streaming responses. Events are sent as `data: <JSON>\\n\\n`. Key order: data (with status first), type, id.",
+      "Server-Sent Event emitted during streaming responses. Events are sent as `event: <status>\\ndata: <JSON>\\n\\n`, where the JSON payload has the shape `{ data, type, id }`.",
   });
 
 // =============================================================================

packages/server-v3/openapi.v3.yaml

@@ -1910,8 +1910,8 @@ components:
       additionalProperties: false
     StreamEvent:
       description: "Server-Sent Event emitted during streaming responses. Events are
-        sent as `data: <JSON>\\n\\n`. Key order: data (with status first), type,
-        id."
+        sent as `event: <status>\\ndata: <JSON>\\n\\n`, where the JSON payload
+        has the shape `{ data, type, id }`."
       type: object
       properties:
         data:

packages/server-v3/src/lib/stream.ts

@@ -27,6 +27,14 @@ interface StreamingResponseOptions<TV3> {
   operation?: string;
 }
 
+type StreamEventName =
+  | "starting"
+  | "connected"
+  | "running"
+  | "finished"
+  | "error";
+type StreamPayloadType = "system" | "log";
+
 export async function createStreamingResponse<TV3>({
   sessionId,
   request,
@@ -104,23 +112,29 @@ export async function createStreamingResponse<TV3>({
     }
   }
 
-  const sendData = (type: string, data: object) => {
+  const sendData = (
+    event: StreamEventName,
+    type: StreamPayloadType,
+    data: object,
+  ) => {
     if (!shouldStreamResponse) {
       return;
     }
 
-    reply.raw.write(`data: ${JSON.stringify({ data, type, id: v4() })}\n\n`);
+    reply.raw.write(
+      `event: ${event}\ndata: ${JSON.stringify({ data, type, id: v4() })}\n\n`,
+    );
   };
 
   const actionId = v4();
 
-  sendData("system", { status: "starting" });
+  sendData("starting", "system", { status: "starting" });
 
   const requestContext: RequestContext = {
     modelApiKey,
     logger: shouldStreamResponse
       ? (message) => {
-          sendData("log", { status: "running", message });
+          sendData("running", "log", { status: "running", message });
         }
       : undefined,
   };
@@ -134,7 +148,7 @@ export async function createStreamingResponse<TV3>({
   } catch (err) {
     const loadError = err instanceof Error ? err : new Error(String(err));
 
-    sendData("system", { status: "error", error: loadError.message });
+    sendData("error", "system", { status: "error", error: loadError.message });
 
     if (shouldStreamResponse) {
       reply.raw.end();
@@ -150,7 +164,7 @@ export async function createStreamingResponse<TV3>({
     );
   }
 
-  sendData("system", { status: "connected" });
+  sendData("connected", "system", { status: "connected" });
 
   let result: Awaited<ReturnType<typeof handler>> | null = null;
   let handlerError: Error | null = null;
@@ -180,7 +194,7 @@ export async function createStreamingResponse<TV3>({
         ? handlerError.getClientMessage()
         : `${operation ?? "operation"} failed`;
 
-    sendData("system", { status: "error", error: clientMessage });
+    sendData("error", "system", { status: "error", error: clientMessage });
 
     if (shouldStreamResponse) {
       reply.raw.end();
@@ -194,7 +208,7 @@ export async function createStreamingResponse<TV3>({
     return error(reply, clientMessage, statusCode);
   }
 
-  sendData("system", {
+  sendData("finished", "system", {
     status: "finished",
     result: result?.result,
     actionId,

packages/server-v3/test/integration/utils.ts

@@ -359,7 +359,8 @@ export async function readSSEStream(response: Response): Promise<SSEEvent[]> {
 // =============================================================================
 
 // Actual SSE event format from backend (see stream.ts):
-// { data: { status: "starting" | "connected" | "finished", result?: ... }, type: "system" | "log", id: "<uuid>" }
+// event: <status>
+// data: { data: { status: "starting" | "connected" | "finished", result?: ... }, type: "system" | "log", id: "<uuid>" }
 export interface TypedSSEEvent<TResult = unknown> {
   data: {
     status: string;

packages/server-v3/test/integration/v3/act.test.ts

@@ -19,6 +19,7 @@ import {
   navigateSession,
   OPENAI_API_KEY,
   readTypedSSEStreamWithContext,
+  readSSEStream,
   requireEnv,
 } from "../utils.js";
 
@@ -401,6 +402,47 @@ describe("POST /v1/sessions/:id/act with SSE streaming (V3)", () => {
     );
   });
 
+  it("should include explicit SSE event names that match streamed statuses", async () => {
+    const url = getBaseUrl();
+
+    const response = await fetch(`${url}/v1/sessions/${sessionId}/act`, {
+      method: "POST",
+      headers: {
+        ...getHeaders("3.0.0"),
+      },
+      body: JSON.stringify({
+        input: "click the Learn more link",
+        streamResponse: true,
+      }),
+    });
+
+    const events = await readSSEStream(response);
+
+    assert.ok(events.length >= 2, "Should emit multiple SSE frames");
+    assert.ok(
+      events.every((event) => typeof event.event === "string" && event.event),
+      "Every streamed frame should include an SSE event name",
+    );
+
+    const startingEvent = events.find((event) => event.event === "starting");
+    assert.ok(startingEvent, "Should include a starting SSE event");
+    assert.equal(
+      (startingEvent.parsed as { data?: { status?: string } } | undefined)?.data
+        ?.status,
+      "starting",
+      "Starting SSE event should match the payload status",
+    );
+
+    const finishedEvent = events.find((event) => event.event === "finished");
+    assert.ok(finishedEvent, "Should include a finished SSE event");
+    assert.equal(
+      (finishedEvent.parsed as { data?: { status?: string } } | undefined)?.data
+        ?.status,
+      "finished",
+      "Finished SSE event should match the payload status",
+    );
+  });
+
   it("should stream SSE events with inline model config", async () => {
     const url = getBaseUrl();
     const openaiApiKey = requireEnv("OPENAI_API_KEY", OPENAI_API_KEY);

stainless.yml

@@ -201,11 +201,9 @@ resources:
 
 streaming:
   on_event:
-    - data_starts_with: '{"data":{"status":"finished"'
-      handle: done
-    - data_starts_with: error
+    - event_type: error
       handle: error
-    - event_type: null
+    - event_type: [starting, connected, running, finished]
       handle: yield
 
 settings: