[codex] Return TurnResult from Python turn handles (#23151)

## Why

`TurnHandle.run()` returned the raw app-server `Turn`, whose live
start/completed payloads do not include loaded `items`, so users saw
empty `items` after starting a turn. That made the handle-based path
behave differently from `Thread.run(...)`, and pushed examples toward
persisted-thread reads plus helper extraction.

This PR makes the run APIs standalone: starting a turn and running it
returns collected turn data directly, or fails visibly when required
stream events are missing.

## What Changed

- Replaces the public `RunResult` export with `TurnResult`.
- Adds turn metadata to `TurnResult`: `id`, `status`, `error`,
`started_at`, `completed_at`, and `duration_ms`, alongside
`final_response`, `items`, and `usage`.
- Changes `TurnHandle.run()` and `AsyncTurnHandle.run()` to consume
stream events with the same collector used by `Thread.run(...)`.
- Exports `TurnError` from `openai_codex.types` for the new result
shape.
- Updates tests, examples, docs, and the walkthrough notebook to use
`result.final_response` and `result.items` directly.
- Removes persisted-thread helper paths and placeholder/skipped control
flows from the public examples and notebook.

## Verification

- `python3 -m py_compile ...` over changed SDK, example, and test Python
files.
- `python3 -c "import json;
json.load(open('sdk/python/notebooks/sdk_walkthrough.ipynb'))"`
- `git diff --check`
- `PYTHONPATH=sdk/python/src python3 -c ...` import/signature smoke for
`TurnResult`, `TurnHandle.run`, and `AsyncTurnHandle.run`.

sdk/python/src/openai_codex/__init__.py

@@ -14,11 +14,11 @@ from .api import (
     InputItem,
     LocalImageInput,
     MentionInput,
-    RunResult,
     SkillInput,
     TextInput,
     Thread,
     TurnHandle,
+    TurnResult,
 )
 from .client import AppServerConfig
 from .errors import (
@@ -51,7 +51,7 @@ __all__ = [
     "AsyncThread",
     "TurnHandle",
     "AsyncTurnHandle",
-    "RunResult",
+    "TurnResult",
     "Input",
     "InputItem",
     "TextInput",

sdk/python/src/openai_codex/_run.py

@@ -12,13 +12,20 @@ from .generated.v2_all import (
     ThreadTokenUsageUpdatedNotification,
     Turn as AppServerTurn,
     TurnCompletedNotification,
+    TurnError,
     TurnStatus,
 )
 from .models import Notification
 
 
 @dataclass(slots=True)
-class RunResult:
+class TurnResult:
+    id: str
+    status: TurnStatus
+    error: TurnError | None
+    started_at: int | None
+    completed_at: int | None
+    duration_ms: int | None
     final_response: str | None
     items: list[ThreadItem]
     usage: ThreadTokenUsage | None
@@ -56,7 +63,7 @@ def _raise_for_failed_turn(turn: AppServerTurn) -> None:
     raise RuntimeError(f"turn failed with status {turn.status.value}")
 
 
-def _collect_run_result(stream: Iterator[Notification], *, turn_id: str) -> RunResult:
+def _collect_turn_result(stream: Iterator[Notification], *, turn_id: str) -> TurnResult:
     completed: TurnCompletedNotification | None = None
     items: list[ThreadItem] = []
     usage: ThreadTokenUsage | None = None
@@ -76,16 +83,23 @@ def _collect_run_result(stream: Iterator[Notification], *, turn_id: str) -> RunR
         raise RuntimeError("turn completed event not received")
 
     _raise_for_failed_turn(completed.turn)
-    return RunResult(
+    turn = completed.turn
+    return TurnResult(
+        id=turn.id,
+        status=turn.status,
+        error=turn.error,
+        started_at=turn.started_at,
+        completed_at=turn.completed_at,
+        duration_ms=turn.duration_ms,
         final_response=_final_assistant_response_from_items(items),
         items=items,
         usage=usage,
     )
 
 
-async def _collect_async_run_result(
+async def _collect_async_turn_result(
     stream: AsyncIterator[Notification], *, turn_id: str
-) -> RunResult:
+) -> TurnResult:
     completed: TurnCompletedNotification | None = None
     items: list[ThreadItem] = []
     usage: ThreadTokenUsage | None = None
@@ -105,7 +119,14 @@ async def _collect_async_run_result(
         raise RuntimeError("turn completed event not received")
 
     _raise_for_failed_turn(completed.turn)
-    return RunResult(
+    turn = completed.turn
+    return TurnResult(
+        id=turn.id,
+        status=turn.status,
+        error=turn.error,
+        started_at=turn.started_at,
+        completed_at=turn.completed_at,
+        duration_ms=turn.duration_ms,
         final_response=_final_assistant_response_from_items(items),
         items=items,
         usage=usage,

sdk/python/src/openai_codex/api.py

@@ -33,9 +33,9 @@ from ._login import (
     start_device_code_login,
 )
 from ._run import (
-    RunResult,
-    _collect_async_run_result,
-    _collect_run_result,
+    TurnResult,
+    _collect_async_turn_result,
+    _collect_turn_result,
 )
 from .async_client import AsyncAppServerClient
 from .client import AppServerClient, AppServerConfig
@@ -65,7 +65,6 @@ from .generated.v2_all import (
     ThreadSourceKind,
     ThreadStartParams,
     ThreadStartSource,
-    Turn as AppServerTurn,
     TurnCompletedNotification,
     TurnInterruptResponse,
     TurnStartParams,
@@ -533,7 +532,7 @@ class Thread:
         sandbox_policy: SandboxPolicy | None = None,
         service_tier: str | None = None,
         summary: ReasoningSummary | None = None,
-    ) -> RunResult:
+    ) -> TurnResult:
         turn = self.turn(
             _normalize_run_input(input),
             approval_mode=approval_mode,
@@ -548,7 +547,7 @@ class Thread:
         )
         stream = turn.stream()
         try:
-            return _collect_run_result(stream, turn_id=turn.id)
+            return _collect_turn_result(stream, turn_id=turn.id)
         finally:
             stream.close()
 
@@ -616,7 +615,7 @@ class AsyncThread:
         sandbox_policy: SandboxPolicy | None = None,
         service_tier: str | None = None,
         summary: ReasoningSummary | None = None,
-    ) -> RunResult:
+    ) -> TurnResult:
         turn = await self.turn(
             _normalize_run_input(input),
             approval_mode=approval_mode,
@@ -631,7 +630,7 @@ class AsyncThread:
         )
         stream = turn.stream()
         try:
-            return await _collect_async_run_result(stream, turn_id=turn.id)
+            return await _collect_async_turn_result(stream, turn_id=turn.id)
         finally:
             await stream.aclose()
 
@@ -717,21 +716,13 @@ class TurnHandle:
         finally:
             self._client.unregister_turn_notifications(self.id)
 
-    def run(self) -> AppServerTurn:
-        completed: TurnCompletedNotification | None = None
+    def run(self) -> TurnResult:
         stream = self.stream()
         try:
-            for event in stream:
-                payload = event.payload
-                if isinstance(payload, TurnCompletedNotification) and payload.turn.id == self.id:
-                    completed = payload
+            return _collect_turn_result(stream, turn_id=self.id)
         finally:
             stream.close()
 
-        if completed is None:
-            raise RuntimeError("turn completed event not received")
-        return completed.turn
-
 
 @dataclass(slots=True)
 class AsyncTurnHandle:
@@ -768,17 +759,9 @@ class AsyncTurnHandle:
         finally:
             self._codex._client.unregister_turn_notifications(self.id)
 
-    async def run(self) -> AppServerTurn:
-        completed: TurnCompletedNotification | None = None
+    async def run(self) -> TurnResult:
         stream = self.stream()
         try:
-            async for event in stream:
-                payload = event.payload
-                if isinstance(payload, TurnCompletedNotification) and payload.turn.id == self.id:
-                    completed = payload
+            return await _collect_async_turn_result(stream, turn_id=self.id)
         finally:
             await stream.aclose()
-
-        if completed is None:
-            raise RuntimeError("turn completed event not received")
-        return completed.turn

sdk/python/src/openai_codex/types.py

@@ -33,6 +33,7 @@ from .generated.v2_all import (
     ThreadTokenUsageUpdatedNotification,
     Turn,
     TurnCompletedNotification,
+    TurnError,
     TurnInterruptResponse,
     TurnStatus,
     TurnSteerResponse,
@@ -73,6 +74,7 @@ __all__ = [
     "ThreadTokenUsageUpdatedNotification",
     "Turn",
     "TurnCompletedNotification",
+    "TurnError",
     "TurnInterruptResponse",
     "TurnStatus",
     "TurnSteerResponse",