[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/examples/03_turn_stream_events/async.py

@@ -5,12 +5,7 @@ _EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
 if str(_EXAMPLES_ROOT) not in sys.path:
     sys.path.insert(0, str(_EXAMPLES_ROOT))
 
-from _bootstrap import (
-    assistant_text_from_turn,
-    ensure_local_sdk_src,
-    find_turn_by_id,
-    runtime_config,
-)
+from _bootstrap import ensure_local_sdk_src, runtime_config
 
 ensure_local_sdk_src()
 
@@ -29,7 +24,8 @@ async def main() -> None:
         event_count = 0
         saw_started = False
         saw_delta = False
-        completed_status = "unknown"
+        completed_status = None
+        completed_texts = []
 
         async for event in turn.stream():
             event_count += 1
@@ -38,24 +34,27 @@ async def main() -> None:
                 print("stream.started")
                 continue
             if event.method == "item/agentMessage/delta":
-                delta = getattr(event.payload, "delta", "")
+                delta = event.payload.delta
                 if delta:
                     if not saw_delta:
                         print("assistant> ", end="", flush=True)
                     print(delta, end="", flush=True)
                     saw_delta = True
                 continue
+            if event.method == "item/completed":
+                root = event.payload.item.root
+                if root.type == "agentMessage":
+                    completed_texts.append(root.text)
+                continue
             if event.method == "turn/completed":
-                completed_status = getattr(
-                    event.payload.turn.status, "value", str(event.payload.turn.status)
-                )
+                completed_status = event.payload.turn.status.value
 
+        if completed_status is None:
+            raise RuntimeError("stream ended without turn/completed")
         if saw_delta:
             print()
         else:
-            persisted = await thread.read(include_turns=True)
-            persisted_turn = find_turn_by_id(persisted.thread.turns, turn.id)
-            final_text = assistant_text_from_turn(persisted_turn).strip() or "[no assistant text]"
+            final_text = "".join(completed_texts).strip()
             print("assistant>", final_text)
 
         print("stream.started.seen:", saw_started)

sdk/python/examples/03_turn_stream_events/sync.py

@@ -5,12 +5,7 @@ _EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
 if str(_EXAMPLES_ROOT) not in sys.path:
     sys.path.insert(0, str(_EXAMPLES_ROOT))
 
-from _bootstrap import (
-    assistant_text_from_turn,
-    ensure_local_sdk_src,
-    find_turn_by_id,
-    runtime_config,
-)
+from _bootstrap import ensure_local_sdk_src, runtime_config
 
 ensure_local_sdk_src()
 
@@ -23,7 +18,8 @@ with Codex(config=runtime_config()) as codex:
     event_count = 0
     saw_started = False
     saw_delta = False
-    completed_status = "unknown"
+    completed_status = None
+    completed_texts = []
 
     for event in turn.stream():
         event_count += 1
@@ -32,24 +28,27 @@ with Codex(config=runtime_config()) as codex:
             print("stream.started")
             continue
         if event.method == "item/agentMessage/delta":
-            delta = getattr(event.payload, "delta", "")
+            delta = event.payload.delta
             if delta:
                 if not saw_delta:
                     print("assistant> ", end="", flush=True)
                 print(delta, end="", flush=True)
                 saw_delta = True
             continue
+        if event.method == "item/completed":
+            root = event.payload.item.root
+            if root.type == "agentMessage":
+                completed_texts.append(root.text)
+            continue
         if event.method == "turn/completed":
-            completed_status = getattr(
-                event.payload.turn.status, "value", str(event.payload.turn.status)
-            )
+            completed_status = event.payload.turn.status.value
 
+    if completed_status is None:
+        raise RuntimeError("stream ended without turn/completed")
     if saw_delta:
         print()
     else:
-        persisted = thread.read(include_turns=True)
-        persisted_turn = find_turn_by_id(persisted.thread.turns, turn.id)
-        final_text = assistant_text_from_turn(persisted_turn).strip() or "[no assistant text]"
+        final_text = "".join(completed_texts).strip()
         print("assistant>", final_text)
 
     print("stream.started.seen:", saw_started)