[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_real_app_server_integration.py

@@ -135,7 +135,7 @@ def _run_python(
     )
 
 
-def _runtime_compatibility_hint(
+def _runtime_schema_hint(
     runtime_env: PreparedRuntimeEnv,
     *,
     stdout: str,
@@ -144,7 +144,7 @@ def _runtime_compatibility_hint(
     combined = f"{stdout}\n{stderr}"
     if "ThreadStartResponse" in combined and "approvalsReviewer" in combined:
         return (
-            "\nCompatibility hint:\n"
+            "\nSchema hint:\n"
             f"Pinned runtime {runtime_env.runtime_version} returned a thread/start payload "
             "that is older than the current SDK schema and is missing "
             "`approvalsReviewer`. Bump `sdk/python/_runtime_setup.py` to a matching "
@@ -165,7 +165,7 @@ def _run_json_python(
         "Python snippet failed.\n"
         f"STDOUT:\n{result.stdout}\n"
         f"STDERR:\n{result.stderr}"
-        f"{_runtime_compatibility_hint(runtime_env, stdout=result.stdout, stderr=result.stderr)}"
+        f"{_runtime_schema_hint(runtime_env, stdout=result.stdout, stderr=result.stderr)}"
     )
     return json.loads(result.stdout)
 
@@ -242,17 +242,12 @@ def test_real_thread_and_turn_start_smoke(runtime_env: PreparedRuntimeEnv) -> No
                     config={"model_reasoning_effort": "high"},
                 )
                 result = thread.turn(TextInput("hello")).run()
-                persisted = thread.read(include_turns=True)
-                persisted_turn = next(
-                    (turn for turn in persisted.thread.turns or [] if turn.id == result.id),
-                    None,
-                )
                 print(json.dumps({
                     "thread_id": thread.id,
                     "turn_id": result.id,
                     "status": result.status.value,
-                    "items_count": len(result.items or []),
-                    "persisted_items_count": 0 if persisted_turn is None else len(persisted_turn.items or []),
+                    "items_count": len(result.items),
+                    "final_response_is_text": isinstance(result.final_response, str) and bool(result.final_response.strip()),
                 }))
             """
         ),
@@ -261,8 +256,8 @@ def test_real_thread_and_turn_start_smoke(runtime_env: PreparedRuntimeEnv) -> No
     assert isinstance(data["thread_id"], str) and data["thread_id"].strip()
     assert isinstance(data["turn_id"], str) and data["turn_id"].strip()
     assert data["status"] == "completed"
-    assert isinstance(data["items_count"], int)
-    assert isinstance(data["persisted_items_count"], int)
+    assert data["items_count"] > 0
+    assert data["final_response_is_text"] is True
 
 
 def test_real_thread_run_convenience_smoke(runtime_env: PreparedRuntimeEnv) -> None:
@@ -345,17 +340,12 @@ def test_real_async_thread_turn_usage_and_ids_smoke(
                         config={"model_reasoning_effort": "high"},
                     )
                     result = await (await thread.turn(TextInput("say ok"))).run()
-                    persisted = await thread.read(include_turns=True)
-                    persisted_turn = next(
-                        (turn for turn in persisted.thread.turns or [] if turn.id == result.id),
-                        None,
-                    )
                     print(json.dumps({
                         "thread_id": thread.id,
                         "turn_id": result.id,
                         "status": result.status.value,
-                        "items_count": len(result.items or []),
-                        "persisted_items_count": 0 if persisted_turn is None else len(persisted_turn.items or []),
+                        "items_count": len(result.items),
+                        "final_response_is_text": isinstance(result.final_response, str) and bool(result.final_response.strip()),
                     }))
 
             asyncio.run(main())
@@ -366,8 +356,8 @@ def test_real_async_thread_turn_usage_and_ids_smoke(
     assert isinstance(data["thread_id"], str) and data["thread_id"].strip()
     assert isinstance(data["turn_id"], str) and data["turn_id"].strip()
     assert data["status"] == "completed"
-    assert isinstance(data["items_count"], int)
-    assert isinstance(data["persisted_items_count"], int)
+    assert data["items_count"] > 0
+    assert data["final_response_is_text"] is True
 
 
 def test_real_async_thread_run_convenience_smoke(
@@ -531,7 +521,7 @@ def test_real_examples_run_and_assert(
         f"Example failed: {folder}/{script}\n"
         f"STDOUT:\n{result.stdout}\n"
         f"STDERR:\n{result.stderr}"
-        f"{_runtime_compatibility_hint(runtime_env, stdout=result.stdout, stderr=result.stderr)}"
+        f"{_runtime_schema_hint(runtime_env, stdout=result.stdout, stderr=result.stderr)}"
     )
 
     out = result.stdout
@@ -541,7 +531,7 @@ def test_real_examples_run_and_assert(
         assert "Server: unknown" not in out
     elif folder == "02_turn_run":
         assert "thread_id:" in out and "turn_id:" in out and "status:" in out
-        assert "persisted.items.count:" in out
+        assert "items.count:" in out
     elif folder == "03_turn_stream_events":
         assert "stream.completed:" in out
         assert "assistant>" in out