python-sdk: rename turn wrapper handles (2026-03-16)

Rename the public SDK wrapper objects from Turn/AsyncTurn to TurnHandle/AsyncTurnHandle so the wrapper control object is clearly distinct from the canonical generated app-server Turn model.

Update the top-level exports, public API docs, runtime behavior test coverage, and the Python SDK codegen helper so future generated method signatures preserve the new wrapper names.

Co-authored-by: Codex <noreply@openai.com>

sdk/python/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 Public surface of `codex_app_server` for app-server v2.
 
-This SDK surface is experimental. The current implementation intentionally allows only one active `Turn.stream()` or `Turn.run()` consumer per client instance at a time.
+This SDK surface is experimental. The current implementation intentionally allows only one active `TurnHandle.stream()` or `TurnHandle.run()` consumer per client instance at a time.
 
 ## Package Entry
 
@@ -12,8 +12,8 @@ from codex_app_server import (
     AsyncCodex,
     Thread,
     AsyncThread,
-    Turn,
-    AsyncTurn,
+    TurnHandle,
+    AsyncTurnHandle,
     InitializeResponse,
     Input,
     InputItem,
@@ -87,21 +87,21 @@ async with AsyncCodex() as codex:
 
 ### Thread
 
-- `turn(input: Input, *, approval_policy=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, summary=None) -> Turn`
+- `turn(input: Input, *, approval_policy=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, summary=None) -> TurnHandle`
 - `read(*, include_turns: bool = False) -> ThreadReadResponse`
 - `set_name(name: str) -> ThreadSetNameResponse`
 - `compact() -> ThreadCompactStartResponse`
 
 ### AsyncThread
 
-- `turn(input: Input, *, approval_policy=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, summary=None) -> Awaitable[AsyncTurn]`
+- `turn(input: Input, *, approval_policy=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, summary=None) -> Awaitable[AsyncTurnHandle]`
 - `read(*, include_turns: bool = False) -> Awaitable[ThreadReadResponse]`
 - `set_name(name: str) -> Awaitable[ThreadSetNameResponse]`
 - `compact() -> Awaitable[ThreadCompactStartResponse]`
 
-## Turn / AsyncTurn
+## TurnHandle / AsyncTurnHandle
 
-### Turn
+### TurnHandle
 
 - `steer(input: Input) -> TurnSteerResponse`
 - `interrupt() -> TurnInterruptResponse`
@@ -113,7 +113,7 @@ Behavior notes:
 - `stream()` and `run()` are exclusive per client instance in the current experimental build
 - starting a second turn consumer on the same `Codex` instance raises `RuntimeError`
 
-### AsyncTurn
+### AsyncTurnHandle
 
 - `steer(input: Input) -> Awaitable[TurnSteerResponse]`
 - `interrupt() -> Awaitable[TurnInterruptResponse]`

sdk/python/docs/faq.md

@@ -8,8 +8,8 @@
 
 ## `run()` vs `stream()`
 
-- `Turn.run()` / `AsyncTurn.run()` is the easiest path. It consumes events until completion and returns the canonical generated app-server `Turn` model.
-- `Turn.stream()` / `AsyncTurn.stream()` yields raw notifications (`Notification`) so you can react event-by-event.
+- `TurnHandle.run()` / `AsyncTurnHandle.run()` is the easiest path. It consumes events until completion and returns the canonical generated app-server `Turn` model.
+- `TurnHandle.stream()` / `AsyncTurnHandle.stream()` yields raw notifications (`Notification`) so you can react event-by-event.
 
 Choose `run()` for most apps. Choose `stream()` for progress UIs, custom timeout logic, or custom parsing.
 

sdk/python/docs/getting-started.md

@@ -42,7 +42,7 @@ What happened:
 - `Codex()` started and initialized `codex app-server`.
 - `thread_start(...)` created a thread.
 - `turn(...).run()` consumed events until `turn/completed` and returned the canonical generated app-server `Turn` model.
-- one client can have only one active `Turn.stream()` / `Turn.run()` consumer at a time in the current experimental build
+- one client can have only one active `TurnHandle.stream()` / `TurnHandle.run()` consumer at a time in the current experimental build
 
 ## 3) Continue the same thread (multi-turn)