[STG-1607] Yield finished SSE event instead of silently dropping it

[aq17]

why

Customer reported a bug in the Python SDK (stagehand-python v3.6.0).

In src/stagehand/_streaming.py, both the sync Stream.stream() (line 62-63) and async AsyncStream.stream() (line 147-148) have:

python
if sse.data.startswith('{"data":{"status":"finished"'):
    break  # ← drops the event without yielding it

When the server sends the finished SSE event (which contains success, message, actions, usage, and messages), the SDK immediately breaks out of the loop without yielding the event to the caller. This means the final result payload is silently dropped.

what changed

The streaming on_event config had handle: done for the {"data":{"status":"finished"...}} event. Stainless generates this as a bare break, which exits the SSE loop without yielding the event – silently dropping the final result payload (success status, message, actions, usage, and messages) from every streaming response.

Fix – Changed to handle: yield so the finished event is delivered to callers before the stream terminates. This is safe because the server explicitly calls reply.raw.end() immediately after sending the finished event (packages/server-v3/src/lib/stream.ts), so the SSE connection closes right after the yield and the loop exits naturally on EOF – no hang risk.

test plan

Regenerate SDKs and confirm fix

[changeset-bot]

🦋 Changeset detected

Latest commit: 066c4c5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/browse-cli	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-server-v4	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

✱ Stainless preview builds

This PR will update the stagehand SDKs with the following commit message.

feat: [STG-1607] Yield finished SSE event instead of silently dropping it

✅ stagehand-ruby studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ✅ → test ✅

✅ stagehand-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

✅ stagehand-php studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → lint ✅ → test ✅

✅ stagehand-go studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ✅ → test ✅

go get github.com/stainless-sdks/stagehand-go@0d81aaac2388be111da866e09feee7ffc12552d3

✅ stagehand-kotlin studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

⏳ stagehand-typescript studio · code

generate ✅ → build ⏳ → lint ✅ → test ⏳

✅ stagehand-python studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

pip install https://pkg.stainless.com/s/stagehand-python/0bba1e9c657cffbbe306a2bc6520ab2992295773/stagehand-3.6.0-py3-none-any.whl

✅ stagehand-java studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

Add the following URL as a Maven source: 'https://pkg.stainless.com/s/stagehand-java/72fa6531d9996c0653fa610b5b05e8027c3a450b/mvn'

⚠️ stagehand-csharp studio · code

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ → lint ❗ → test ✅

⏳ These are partial results; builds are still running.

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-03-18 18:36:28 UTC

[greptile-apps]

Greptile Summary

This PR fixes a bug where the terminal SSE event (status: "finished") — which carries the final result, actionId, and success metadata — was silently dropped by all Stainless-generated SDKs (Python, Go, Java, Kotlin, Ruby, TypeScript, PHP, C#) instead of being delivered to the caller.

Root cause: stainless.yml had handle: done for the finished event, which Stainless generates as a bare break that exits the SSE loop without yielding the event.

Fix: Changing to handle: yield makes Stainless generate code that yields the finished event to the caller before the loop exits. This is safe because packages/server-v3/src/lib/stream.ts (and server-v4) calls reply.raw.end() immediately after emitting the finished event, so the client loop terminates naturally on EOF with no hang risk.

Key changes:

• stainless.yml: One-line fix — handle: done → handle: yield for the {"data":{"status":"finished" SSE event pattern
• Applies globally to all SDK targets (Python, Go, Java, Kotlin, Ruby, TypeScript, PHP, C#) through the top-level streaming.on_event configuration

Confidence Score: 5/5

• This PR is safe to merge — it is a minimal, well-reasoned one-line config fix that restores correct SSE behavior across all generated SDKs.
• The change is a single-line fix in the Stainless code-generation config. The server-side code in both server-v3 and server-v4 confirms that reply.raw.end() is called immediately after the finished event is sent, making the handle: yield approach safe with no hang risk. The fix correctly addresses the root cause of the silent payload drop reported by Monarch Money.
• No files require special attention.

Important Files Changed

Filename	Overview
stainless.yml	Changes the streaming on_event handler for the finished SSE event from done (break without yielding) to yield (deliver event, then exit naturally on EOF), fixing the silent drop of the final result payload across all generated SDKs.

Sequence Diagram

sequenceDiagram
    participant C as SDK Client
    participant S as Server (stream.ts)

    Note over C,S: BEFORE (handle: done)
    S->>C: SSE: {"data":{"status":"starting",...}}
    S->>C: SSE: {"data":{"status":"connected",...}}
    S->>C: SSE: {"data":{"status":"running",...}} (0..n)
    S->>C: SSE: {"data":{"status":"finished", result, actionId}}
    Note over C: break — event silently dropped ❌
    S-->>C: EOF (reply.raw.end())
    Note over C: Caller never receives result

    Note over C,S: AFTER (handle: yield)
    S->>C: SSE: {"data":{"status":"starting",...}}
    S->>C: SSE: {"data":{"status":"connected",...}}
    S->>C: SSE: {"data":{"status":"running",...}} (0..n)
    S->>C: SSE: {"data":{"status":"finished", result, actionId}}
    Note over C: yield — event delivered to caller ✅
    S-->>C: EOF (reply.raw.end())
    Note over C: Loop exits naturally on EOF

Loading

_{Last reviewed commit: "fix: yield finished ..."}

[cubic-dev-ai]

cubic analysis

No issues found across 1 file

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Linked issue analysis

Linked issue: STG-1607: Fix bug in Python SDK to yield finished SSE events

Status	Acceptance criteria	Notes
✅	Change streaming handling so the finished SSE event is yielded instead of dropped	Updated stainless.yml to use handle: yield for finished event
❌	Apply the fix to both sync Stream.__stream__() and async AsyncStream.__stream__() in the Python SDK	No modifications to src/stagehand/_streaming.py shown in PR
⚠️	Ensure yielding the finished event does not hang the stream (stream terminates naturally on EOF)	PR rationale explains safety but no tests or server changes included
❌	Regenerate SDKs and confirm the Python fix (test plan: regenerated SDKs and confirm python fix)	No regenerated SDK files or test confirmations present in diffs

[shrey150]

Nice! As a sanity check, I'd have @monadoid take a look, but this fix makes sense to me. Can you add a changeset so a patch version is generated & reported in changelog?

[pirate]

great catch, thank you for debugging + fixing this @aq17!