Skip to content

[codex] Return TurnResult from Python turn handles#23151

Merged
aibrahim-oai merged 3 commits into
mainfrom
codex/python-turn-result
May 17, 2026
Merged

[codex] Return TurnResult from Python turn handles#23151
aibrahim-oai merged 3 commits into
mainfrom
codex/python-turn-result

Conversation

@aibrahim-oai
Copy link
Copy Markdown
Collaborator

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.

@aibrahim-oai aibrahim-oai marked this pull request as ready for review May 17, 2026 13:17
@aibrahim-oai aibrahim-oai merged commit f0166ca into main May 17, 2026
29 of 30 checks passed
@aibrahim-oai aibrahim-oai deleted the codex/python-turn-result branch May 17, 2026 13:17
@github-actions github-actions Bot locked and limited conversation to collaborators May 17, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant