[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/13_model_select_and_turn_params/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()
 
@@ -35,29 +30,27 @@ REASONING_RANK = {
     "high": 4,
     "xhigh": 5,
 }
-PREFERRED_MODEL = "gpt-5.4"
 
 
 def _pick_highest_model(models):
-    visible = [m for m in models if not m.hidden] or models
-    preferred = next(
-        (m for m in visible if m.model == PREFERRED_MODEL or m.id == PREFERRED_MODEL), None
-    )
-    if preferred is not None:
-        return preferred
+    visible = [m for m in models if not m.hidden]
+    if not visible:
+        raise RuntimeError("models response did not include visible models")
+
     known_names = {m.id for m in visible} | {m.model for m in visible}
     top_candidates = [m for m in visible if not (m.upgrade and m.upgrade in known_names)]
-    pool = top_candidates or visible
-    return max(pool, key=lambda m: (m.model, m.id))
+    if not top_candidates:
+        raise RuntimeError("models response did not include top-level visible models")
+    return max(top_candidates, key=lambda m: (m.model, m.id))
 
 
 def _pick_highest_turn_effort(model) -> ReasoningEffort:
     if not model.supported_reasoning_efforts:
-        return ReasoningEffort.medium
+        raise RuntimeError(f"{model.model} did not advertise supported reasoning efforts")
 
     best = max(
         model.supported_reasoning_efforts,
-        key=lambda option: REASONING_RANK.get(option.reasoning_effort.value, -1),
+        key=lambda option: REASONING_RANK[option.reasoning_effort.value],
     )
     return ReasoningEffort(best.reasoning_effort.value)
 
@@ -103,13 +96,9 @@ async def main() -> None:
             effort=selected_effort,
         )
         first = await first_turn.run()
-        persisted = await thread.read(include_turns=True)
-        first_persisted_turn = find_turn_by_id(persisted.thread.turns, first.id)
 
-        print("agent.message:", assistant_text_from_turn(first_persisted_turn))
-        print(
-            "items:", 0 if first_persisted_turn is None else len(first_persisted_turn.items or [])
-        )
+        print("agent.message:", first.final_response)
+        print("items:", len(first.items))
 
         second_turn = await thread.turn(
             TextInput("Return JSON for a safe feature-flag rollout plan."),
@@ -122,14 +111,9 @@ async def main() -> None:
             summary=ReasoningSummary.model_validate("concise"),
         )
         second = await second_turn.run()
-        persisted = await thread.read(include_turns=True)
-        second_persisted_turn = find_turn_by_id(persisted.thread.turns, second.id)
 
-        print("agent.message.params:", assistant_text_from_turn(second_persisted_turn))
-        print(
-            "items.params:",
-            0 if second_persisted_turn is None else len(second_persisted_turn.items or []),
-        )
+        print("agent.message.params:", second.final_response)
+        print("items.params:", len(second.items))
 
 
 if __name__ == "__main__":

sdk/python/examples/13_model_select_and_turn_params/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()
 
@@ -33,29 +28,27 @@ REASONING_RANK = {
     "high": 4,
     "xhigh": 5,
 }
-PREFERRED_MODEL = "gpt-5.4"
 
 
 def _pick_highest_model(models):
-    visible = [m for m in models if not m.hidden] or models
-    preferred = next(
-        (m for m in visible if m.model == PREFERRED_MODEL or m.id == PREFERRED_MODEL), None
-    )
-    if preferred is not None:
-        return preferred
+    visible = [m for m in models if not m.hidden]
+    if not visible:
+        raise RuntimeError("models response did not include visible models")
+
     known_names = {m.id for m in visible} | {m.model for m in visible}
     top_candidates = [m for m in visible if not (m.upgrade and m.upgrade in known_names)]
-    pool = top_candidates or visible
-    return max(pool, key=lambda m: (m.model, m.id))
+    if not top_candidates:
+        raise RuntimeError("models response did not include top-level visible models")
+    return max(top_candidates, key=lambda m: (m.model, m.id))
 
 
 def _pick_highest_turn_effort(model) -> ReasoningEffort:
     if not model.supported_reasoning_efforts:
-        return ReasoningEffort.medium
+        raise RuntimeError(f"{model.model} did not advertise supported reasoning efforts")
 
     best = max(
         model.supported_reasoning_efforts,
-        key=lambda option: REASONING_RANK.get(option.reasoning_effort.value, -1),
+        key=lambda option: REASONING_RANK[option.reasoning_effort.value],
     )
     return ReasoningEffort(best.reasoning_effort.value)
 
@@ -99,11 +92,9 @@ with Codex(config=runtime_config()) as codex:
         model=selected_model.model,
         effort=selected_effort,
     ).run()
-    persisted = thread.read(include_turns=True)
-    first_turn = find_turn_by_id(persisted.thread.turns, first.id)
 
-    print("agent.message:", assistant_text_from_turn(first_turn))
-    print("items:", 0 if first_turn is None else len(first_turn.items or []))
+    print("agent.message:", first.final_response)
+    print("items:", len(first.items))
 
     second = thread.turn(
         TextInput("Return JSON for a safe feature-flag rollout plan."),
@@ -115,8 +106,6 @@ with Codex(config=runtime_config()) as codex:
         sandbox_policy=SANDBOX_POLICY,
         summary=ReasoningSummary.model_validate("concise"),
     ).run()
-    persisted = thread.read(include_turns=True)
-    second_turn = find_turn_by_id(persisted.thread.turns, second.id)
 
-    print("agent.message.params:", assistant_text_from_turn(second_turn))
-    print("items.params:", 0 if second_turn is None else len(second_turn.items or []))
+    print("agent.message.params:", second.final_response)
+    print("items.params:", len(second.items))