[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/14_turn_controls/sync.py

@@ -5,11 +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,
-    runtime_config,
-)
+from _bootstrap import ensure_local_sdk_src, runtime_config
 
 ensure_local_sdk_src()
 
@@ -20,54 +16,48 @@ with Codex(config=runtime_config()) as codex:
     steer_turn = thread.turn(
         TextInput("Count from 1 to 40 with commas, then one summary sentence.")
     )
-    steer_result = "sent"
-    try:
-        _ = steer_turn.steer(TextInput("Keep it brief and stop after 10 numbers."))
-    except Exception as exc:
-        steer_result = f"skipped {type(exc).__name__}"
+    steer_result = steer_turn.steer(TextInput("Keep it brief and stop after 10 numbers."))
 
     steer_event_count = 0
-    steer_completed_status = "unknown"
-    steer_completed_turn = None
+    steer_completed_status = None
+    steer_deltas = []
     for event in steer_turn.stream():
         steer_event_count += 1
+        if event.method == "item/agentMessage/delta":
+            steer_deltas.append(event.payload.delta)
+            continue
         if event.method == "turn/completed":
-            steer_completed_turn = event.payload.turn
-            steer_completed_status = getattr(
-                event.payload.turn.status, "value", str(event.payload.turn.status)
-            )
+            steer_completed_status = event.payload.turn.status.value
 
-    steer_preview = assistant_text_from_turn(steer_completed_turn).strip() or "[no assistant text]"
+    if steer_completed_status is None:
+        raise RuntimeError("stream ended without turn/completed")
+    steer_preview = "".join(steer_deltas).strip()
 
     interrupt_turn = thread.turn(
         TextInput("Count from 1 to 200 with commas, then one summary sentence.")
     )
-    interrupt_result = "sent"
-    try:
-        _ = interrupt_turn.interrupt()
-    except Exception as exc:
-        interrupt_result = f"skipped {type(exc).__name__}"
+    interrupt_result = interrupt_turn.interrupt()
 
     interrupt_event_count = 0
-    interrupt_completed_status = "unknown"
-    interrupt_completed_turn = None
+    interrupt_completed_status = None
+    interrupt_deltas = []
     for event in interrupt_turn.stream():
         interrupt_event_count += 1
+        if event.method == "item/agentMessage/delta":
+            interrupt_deltas.append(event.payload.delta)
+            continue
         if event.method == "turn/completed":
-            interrupt_completed_turn = event.payload.turn
-            interrupt_completed_status = getattr(
-                event.payload.turn.status, "value", str(event.payload.turn.status)
-            )
+            interrupt_completed_status = event.payload.turn.status.value
 
-    interrupt_preview = (
-        assistant_text_from_turn(interrupt_completed_turn).strip() or "[no assistant text]"
-    )
+    if interrupt_completed_status is None:
+        raise RuntimeError("stream ended without turn/completed")
+    interrupt_preview = "".join(interrupt_deltas).strip()
 
-    print("steer.result:", steer_result)
+    print("steer.result:", steer_result.model_dump(mode="json", by_alias=True))
     print("steer.final.status:", steer_completed_status)
     print("steer.events.count:", steer_event_count)
     print("steer.assistant.preview:", steer_preview)
-    print("interrupt.result:", interrupt_result)
+    print("interrupt.result:", interrupt_result.model_dump(mode="json", by_alias=True))
     print("interrupt.final.status:", interrupt_completed_status)
     print("interrupt.events.count:", interrupt_event_count)
     print("interrupt.assistant.preview:", interrupt_preview)