AGE-1957: Update PreparedTurn for create-turn JSON vs SSE split

[bhaveshpatel640]

AGE-1957: Update PreparedTurn for create-turn JSON vs SSE split

---

Note

Medium Risk
Changes how all prepared turns are started (streaming and non-streaming) in sync and async paths, which could affect runtime behavior if the JSON and SSE endpoints diverge.

Overview
PreparedTurn and AsyncPreparedTurn now match the gateway’s split between JSON turn creation and SSE streaming.

When execute(stream=True), turn start goes through create_turn_stream instead of treating create_turn as the SSE entrypoint. When execute(stream=False), the client calls create_turn once, builds the inner turn from the JSON response via _adopt_turn_from_api, then polls to completion—replacing the old behavior that opened SSE only until turn.created.

The SSE adoption path is renamed to _adopt_turn_from_created_event; _create_turn_if_not_exist is removed. Docs and docstrings are updated to describe the two APIs explicitly.

^{Reviewed by Cursor Bugbot for commit ae0a4c9. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Bug Fixes
  • Improved turn execution reliability for both streaming and non-streaming requests.
  • Non-streaming responses are now handled directly before status polling begins.
  • Streaming requests now correctly initialize from the first turn-created event.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3ae77c30-f8ab-4e96-8193-aaf060b63702

📥 Commits

Reviewing files that changed from the base of the PR and between 74a8e6b and ae0a4c9.

📒 Files selected for processing (1)

• src/truefoundry_gateway_sdk/agents/prepared_turn.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

PreparedTurn and AsyncPreparedTurn now use create_turn with polling for non-streaming execution and create_turn_stream for streaming execution. Separate helpers adopt turns from JSON responses and turn.created events.

Changes

Turn execution transport

Layer / File(s)	Summary
Synchronous execution and adoption src/truefoundry_gateway_sdk/agents/prepared_turn.py	Synchronous non-streaming execution adopts the create_turn response and polls it. Streaming execution consumes create_turn_stream SSE events and adopts the first turn.created event. Documentation reflects both transports.
Asynchronous execution and adoption src/truefoundry_gateway_sdk/agents/prepared_turn.py	Asynchronous execution mirrors the synchronous transport split. Separate helpers adopt JSON API responses and turn.created events. Documentation identifies create_turn_stream as the SSE source.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to ae0a4

This PR separates prepared-turn startup between JSON and SSE APIs for synchronous and asynchronous paths; no actionable merge-blocking risk remains beyond normal checks.

Sequence Diagram(s)

sequenceDiagram
  participant PreparedTurn
  participant AsyncPreparedTurn
  participant GatewayAPI
  participant TurnPolling
  alt Synchronous non-streaming
    PreparedTurn->>GatewayAPI: create_turn
    GatewayAPI-->>PreparedTurn: JSON turn
    PreparedTurn->>TurnPolling: poll adopted turn
  else Asynchronous non-streaming
    AsyncPreparedTurn->>GatewayAPI: await create_turn
    GatewayAPI-->>AsyncPreparedTurn: JSON turn
    AsyncPreparedTurn->>TurnPolling: poll adopted turn
  else Streaming
    PreparedTurn->>GatewayAPI: create_turn_stream
    GatewayAPI-->>PreparedTurn: turn.created SSE event
    PreparedTurn->>PreparedTurn: adopt event turn
  end

Loading

Suggested reviewers: chiragjn

Poem

A rabbit watched the turn begin,
JSON hopped where polls had been.
SSE streams flowed through moonlit air,
Created events settled there.
Sync and async now share the trail.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 64.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 1 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: updating PreparedTurn to support the JSON and SSE response split for create-turn.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch AGE-1957

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}