[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/11_cli_mini_app/async.py

@@ -21,19 +21,9 @@ from openai_codex.types import (
 )
 
 
-def _status_value(status: object | None) -> str:
-    return str(getattr(status, "value", status))
-
-
-def _format_usage(usage: object | None) -> str:
-    if usage is None:
-        return "usage> (none)"
-
-    last = getattr(usage, "last", None)
-    total = getattr(usage, "total", None)
-    if last is None or total is None:
-        return f"usage> {usage}"
-
+def _format_usage(usage: object) -> str:
+    last = usage.last
+    total = usage.total
     return (
         "usage>\n"
         f"  last: input={last.input_tokens} output={last.output_tokens} reasoning={last.reasoning_output_tokens} total={last.total_tokens} cached={last.cached_input_tokens}\n"
@@ -65,16 +55,14 @@ async def main() -> None:
             usage = None
             status = None
             error = None
-            printed_delta = False
 
             print("assistant> ", end="", flush=True)
             async for event in turn.stream():
                 payload = event.payload
                 if event.method == "item/agentMessage/delta":
-                    delta = getattr(payload, "delta", "")
+                    delta = payload.delta
                     if delta:
                         print(delta, end="", flush=True)
-                        printed_delta = True
                     continue
                 if isinstance(payload, ThreadTokenUsageUpdatedNotification):
                     usage = payload.token_usage
@@ -83,12 +71,13 @@ async def main() -> None:
                     status = payload.turn.status
                     error = payload.turn.error
 
-            if printed_delta:
-                print()
-            else:
-                print("[no text]")
+            print()
+            if status is None:
+                raise RuntimeError("stream ended without turn/completed")
+            if usage is None:
+                raise RuntimeError("stream ended without token usage")
 
-            status_text = _status_value(status)
+            status_text = status.value
             print(f"assistant.status> {status_text}")
             if status_text == "failed":
                 print("assistant.error>", error)

sdk/python/examples/11_cli_mini_app/sync.py

@@ -21,19 +21,9 @@ from openai_codex.types import (
 print("Codex mini CLI. Type /exit to quit.")
 
 
-def _status_value(status: object | None) -> str:
-    return str(getattr(status, "value", status))
-
-
-def _format_usage(usage: object | None) -> str:
-    if usage is None:
-        return "usage> (none)"
-
-    last = getattr(usage, "last", None)
-    total = getattr(usage, "total", None)
-    if last is None or total is None:
-        return f"usage> {usage}"
-
+def _format_usage(usage: object) -> str:
+    last = usage.last
+    total = usage.total
     return (
         "usage>\n"
         f"  last: input={last.input_tokens} output={last.output_tokens} reasoning={last.reasoning_output_tokens} total={last.total_tokens} cached={last.cached_input_tokens}\n"
@@ -60,16 +50,14 @@ with Codex(config=runtime_config()) as codex:
         usage = None
         status = None
         error = None
-        printed_delta = False
 
         print("assistant> ", end="", flush=True)
         for event in turn.stream():
             payload = event.payload
             if event.method == "item/agentMessage/delta":
-                delta = getattr(payload, "delta", "")
+                delta = payload.delta
                 if delta:
                     print(delta, end="", flush=True)
-                    printed_delta = True
                 continue
             if isinstance(payload, ThreadTokenUsageUpdatedNotification):
                 usage = payload.token_usage
@@ -78,12 +66,13 @@ with Codex(config=runtime_config()) as codex:
                 status = payload.turn.status
                 error = payload.turn.error
 
-        if printed_delta:
-            print()
-        else:
-            print("[no text]")
+        print()
+        if status is None:
+            raise RuntimeError("stream ended without turn/completed")
+        if usage is None:
+            raise RuntimeError("stream ended without token usage")
 
-        status_text = _status_value(status)
+        status_text = status.value
         print(f"assistant.status> {status_text}")
         if status_text == "failed":
             print("assistant.error>", error)