STG-1784 Fix SSE docs examples

[monadoid]

Fix SSE streaming examples to prefer stream_response/streamResponse over the legacy header.

---

Summary by cubic

Fixes SSE streaming docs and API copy to use stream_response/streamResponse instead of legacy headers, and adds a changeset to publish patches for @browserbasehq/stagehand-server-v3 and @browserbasehq/stagehand-docs. Addresses Linear STG-1784 so users can stream events reliably.

• Bug Fixes
  • Python SDK docs now use stream_response=True only; removed x_stream_response="true" from examples and guidance.
  • OpenAPI and generator descriptions clarify SSE is enabled via streamResponse: true in the request body, and note legacy x-stream-response: true support for legacy/no-body clients.
  • stainless.yml overrides the sessions.act Python snippet to iterate over the SSE stream.

^{Written for commit ddf5930. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: ddf5930

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

This PR includes changesets to release 2 packages

Name	Type
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-docs	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 for stagehand

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

feat: STG-1784 Fix SSE docs examples

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ stagehand-ruby studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ⏭️ (prev: build ✅) → lint ✅ → test ✅

✅ stagehand-typescript studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ✅) → test ✅

✅ stagehand-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

✅ stagehand-csharp studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ✅) → test ✅

✅ stagehand-java studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

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

✅ stagehand-kotlin studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

✅ stagehand-python studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ✅) → test ✅

✅ stagehand-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ⏭️ (prev: build ✅) → lint ✅ → test ✅

go get github.com/stainless-sdks/stagehand-go@b73334eaedfb45250881ffbfad417e047e2f03f2

✅ stagehand-php studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → lint ✅ → test ✅

---

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-06-22 16:32:30 UTC

[cubic-dev-ai]

1 issue found across 4 files

Confidence score: 4/5

• In packages/server-v3/openapi.v3.yaml, the top-level SSE description currently suggests body-only streaming, which can mislead API consumers and generated clients for GET/header-only streaming endpoints; merging as-is risks integration mistakes rather than runtime breakage — update the SSE description to explicitly cover header-only streaming paths before merging.

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant SDK as Python SDK Client
    participant API as API Route (/v1/sessions/{id}/act)
    participant OpenAPI as OpenAPI Spec
    participant Docs as Documentation

    Note over Dev,Docs: SSE Streaming Configuration Flow

    Dev->>Docs: Read streaming docs
    Docs-->>Dev: NEW: stream_response=True usage only

    Dev->>SDK: Configure SSE stream
    SDK->>API: POST /v1/sessions/{id}/act
    Note over SDK,API: Body: { stream_response: true }

    API->>API: NEW: Detect streamResponse field in body
    alt streamResponse = true
        API->>API: Enable SSE streaming mode
        API-->>SDK: SSE event stream
        SDK-->>Dev: StreamEvent objects
    else streamResponse = false/missing
        API-->>SDK: Single response object
        SDK-->>Dev: Normal response
    end

    Note over Dev,OpenAPI: Documentation Consistency

    OpenAPI->>OpenAPI: Update description
    Note over OpenAPI: "x-stream-response header" → "streamResponse field"

    API->>Docs: Regenerate examples
    Docs->>Docs: Apply stainless.yml override
    Note over Docs: sessions.act Python snippet shows streaming iteration

    Dev->>SDK: Review example
    SDK-->>Dev: Stream iteration pattern with for loop

Loading

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
stagehand	🟢 Ready	View Preview	Jun 22, 2026, 4:29 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.