[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/docs/api-reference.md

@@ -16,11 +16,11 @@ from openai_codex import (
     DeviceCodeLoginHandle,
     AsyncChatgptLoginHandle,
     AsyncDeviceCodeLoginHandle,
-    RunResult,
     Thread,
     AsyncThread,
     TurnHandle,
     AsyncTurnHandle,
+    TurnResult,
     Input,
     InputItem,
     TextInput,
@@ -38,6 +38,7 @@ from openai_codex.types import (
     InitializeResponse,
     ThreadItem,
     ThreadTokenUsage,
+    TurnError,
     TurnStatus,
 )
 ```
@@ -146,7 +147,7 @@ attempt. API-key login completes synchronously and does not return a handle.
 
 ### Thread
 
-- `run(input: str | Input, *, approval_mode=ApprovalMode.auto_review, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, service_tier=None, summary=None) -> RunResult`
+- `run(input: str | Input, *, approval_mode=ApprovalMode.auto_review, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, service_tier=None, summary=None) -> TurnResult`
 - `turn(input: Input, *, approval_mode=ApprovalMode.auto_review, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, summary=None) -> TurnHandle`
 - `read(*, include_turns: bool = False) -> ThreadReadResponse`
 - `set_name(name: str) -> ThreadSetNameResponse`
@@ -154,7 +155,7 @@ attempt. API-key login completes synchronously and does not return a handle.
 
 ### AsyncThread
 
-- `run(input: str | Input, *, approval_mode=ApprovalMode.auto_review, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, service_tier=None, summary=None) -> Awaitable[RunResult]`
+- `run(input: str | Input, *, approval_mode=ApprovalMode.auto_review, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, service_tier=None, summary=None) -> Awaitable[TurnResult]`
 - `turn(input: Input, *, approval_mode=ApprovalMode.auto_review, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, summary=None) -> Awaitable[AsyncTurnHandle]`
 - `read(*, include_turns: bool = False) -> Awaitable[ThreadReadResponse]`
 - `set_name(name: str) -> Awaitable[ThreadSetNameResponse]`
@@ -164,6 +165,12 @@ attempt. API-key login completes synchronously and does not return a handle.
 the turn, consumes notifications until completion, and returns a small result
 object with:
 
+- `id: str`
+- `status: TurnStatus`
+- `error: TurnError | None`
+- `started_at: int | None`
+- `completed_at: int | None`
+- `duration_ms: int | None`
 - `final_response: str | None`
 - `items: list[ThreadItem]`
 - `usage: ThreadTokenUsage | None`
@@ -172,7 +179,7 @@ object with:
 phase-less assistant message item.
 
 Use `turn(...)` when you need low-level turn control (`stream()`, `steer()`,
-`interrupt()`) or the public `Turn` model from `TurnHandle.run()`.
+`interrupt()`) before collecting the turn result.
 
 ## TurnHandle / AsyncTurnHandle
 
@@ -181,7 +188,7 @@ Use `turn(...)` when you need low-level turn control (`stream()`, `steer()`,
 - `steer(input: Input) -> TurnSteerResponse`
 - `interrupt() -> TurnInterruptResponse`
 - `stream() -> Iterator[Notification]`
-- `run() -> openai_codex.types.Turn`
+- `run() -> TurnResult`
 
 Behavior notes:
 
@@ -193,7 +200,7 @@ Behavior notes:
 - `steer(input: Input) -> Awaitable[TurnSteerResponse]`
 - `interrupt() -> Awaitable[TurnInterruptResponse]`
 - `stream() -> AsyncIterator[Notification]`
-- `run() -> Awaitable[openai_codex.types.Turn]`
+- `run() -> Awaitable[TurnResult]`
 
 Behavior notes:
 

sdk/python/docs/faq.md

@@ -8,7 +8,8 @@
 
 ## `run()` vs `stream()`
 
-- `TurnHandle.run()` / `AsyncTurnHandle.run()` is the easiest path. It consumes events until completion and returns the public app-server `Turn` model from `openai_codex.types`.
+- `Thread.run(...)` starts a turn and returns `TurnResult`.
+- `TurnHandle.run()` / `AsyncTurnHandle.run()` consumes events for an existing turn handle and returns the same `TurnResult` shape.
 - `TurnHandle.stream()` / `AsyncTurnHandle.stream()` yields raw notifications (`Notification`) so you can react event-by-event.
 
 Choose `run()` for most apps. Choose `stream()` for progress UIs, custom timeout logic, or custom parsing.
@@ -66,7 +67,7 @@ Common causes:
 
 - published runtime package (`openai-codex-cli-bin`) is not installed
 - local `codex_bin` override points to a missing file
-- incompatible/old app-server
+- app-server version older than the SDK schema
 
 ## Why does a turn "hang"?
 
@@ -79,11 +80,11 @@ A turn is complete only when `turn/completed` arrives for that turn ID.
 
 Use `retry_on_overload(...)` for transient overload failures (`ServerBusyError`).
 
-Do not blindly retry all errors. For `InvalidParamsError` or `MethodNotFoundError`, fix inputs/version compatibility instead.
+Do not blindly retry all errors. For `InvalidParamsError` or `MethodNotFoundError`, fix inputs or update the runtime/schema version instead.
 
 ## Common pitfalls
 
 - Starting a new thread for every prompt when you wanted continuity.
 - Forgetting to `close()` (or not using context managers).
-- Assuming `run()` returns extra SDK-only fields instead of the public `Turn` model.
+- Reading `Turn.items` from live start/completed payloads instead of using `TurnResult.items`.
 - Mixing SDK input classes with raw dicts incorrectly.

sdk/python/docs/getting-started.md

@@ -70,9 +70,9 @@ What happened:
 
 - `Codex()` started and initialized `codex app-server`.
 - `thread_start(...)` created a thread.
-- `thread.run("...")` started a turn, consumed events until completion, and returned the final assistant response plus collected items and usage.
+- `thread.run("...")` started a turn, consumed events until completion, and returned `TurnResult` with turn metadata, final assistant response, collected items, and usage.
 - `result.final_response` is `None` when no final-answer or phase-less assistant message item completes for the turn.
-- use `thread.turn(...)` when you need a `TurnHandle` for streaming, steering, interrupting, or turn IDs/status
+- use `thread.turn(...)` when you need a `TurnHandle` for streaming, steering, or interrupting before collecting `TurnResult`
 - one client can consume multiple active turns concurrently; turn streams are routed by turn ID
 
 ## 4) Continue the same thread (multi-turn)