[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/tests/test_public_api_signatures.py

@@ -14,9 +14,11 @@ from openai_codex import (
     AppServerConfig,
     AsyncCodex,
     AsyncThread,
+    AsyncTurnHandle,
     Codex,
-    RunResult,
     Thread,
+    TurnHandle,
+    TurnResult,
 )
 from openai_codex._initialize_metadata import validate_initialize_metadata
 from openai_codex.types import InitializeResponse
@@ -35,7 +37,7 @@ EXPECTED_ROOT_EXPORTS = [
     "AsyncThread",
     "TurnHandle",
     "AsyncTurnHandle",
-    "RunResult",
+    "TurnResult",
     "Input",
     "InputItem",
     "TextInput",
@@ -92,6 +94,7 @@ EXPECTED_TYPES_EXPORTS = [
     "ThreadTokenUsageUpdatedNotification",
     "Turn",
     "TurnCompletedNotification",
+    "TurnError",
     "TurnInterruptResponse",
     "TurnStatus",
     "TurnSteerResponse",
@@ -128,9 +131,39 @@ def test_root_exports_app_server_config() -> None:
     assert AppServerConfig.__name__ == "AppServerConfig"
 
 
-def test_root_exports_run_result() -> None:
-    """The root package should expose the common-case run result wrapper."""
-    assert RunResult.__name__ == "RunResult"
+def test_root_exports_turn_result() -> None:
+    """The root package should expose the collected turn result wrapper."""
+    assert {
+        "name": TurnResult.__name__,
+        "fields": list(TurnResult.__dataclass_fields__),
+    } == {
+        "name": "TurnResult",
+        "fields": [
+            "id",
+            "status",
+            "error",
+            "started_at",
+            "completed_at",
+            "duration_ms",
+            "final_response",
+            "items",
+            "usage",
+        ],
+    }
+
+
+def test_turn_run_methods_return_turn_result() -> None:
+    """Both convenience and handle-based run APIs return the same result shape."""
+    funcs = [
+        Thread.run,
+        TurnHandle.run,
+        AsyncThread.run,
+        AsyncTurnHandle.run,
+    ]
+
+    assert {fn: inspect.signature(fn).return_annotation for fn in funcs} == dict.fromkeys(
+        funcs, "TurnResult"
+    )
 
 
 def test_root_exports_approval_mode() -> None: