14 Commits

• [codex] Accept string input for Python turns (#23162)

  ## Summary
  - Allow thread.turn and turn.steer, including async variants, to accept
  RunInput so plain strings work alongside typed input objects.
  - Export RunInput and update the SDK artifact generator so regenerated
  turn methods keep the same signature and normalization.
  - Update docs, examples, notebook cells, and tests to use string
  shorthand for text-only turns while keeping typed inputs for multimodal
  input.
  
  ## Validation
  - uv run --extra dev ruff format .
  - uv run --extra dev ruff check --output-format=github .
  - python3 -m py_compile sdk/python/src/openai_codex/__init__.py
  sdk/python/src/openai_codex/api.py
  sdk/python/src/openai_codex/_inputs.py
  sdk/python/scripts/update_sdk_artifacts.py
  sdk/python/tests/test_public_api_signatures.py
  sdk/python/tests/test_app_server_streaming.py
  sdk/python/tests/test_app_server_turn_controls.py
  sdk/python/tests/test_real_app_server_integration.py
  - python3 -c "import json;
  json.load(open('sdk/python/notebooks/sdk_walkthrough.ipynb'))"
  - sdk/python/.venv/bin/python -c "import inspect, openai_codex; from
  openai_codex import Thread, AsyncThread, TurnHandle, AsyncTurnHandle,
  RunInput; funcs=[Thread.run, Thread.turn, AsyncThread.run,
  AsyncThread.turn, TurnHandle.steer, AsyncTurnHandle.steer]; assert
  all(inspect.signature(fn).parameters['input'].annotation == 'RunInput'
  for fn in funcs); assert RunInput is openai_codex.RunInput"

  Ahmed Ibrahim · 2026-05-17 09:05:44 -07:00
  e7bffc5a20
• [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`.

  Ahmed Ibrahim · 2026-05-17 06:17:22 -07:00
  f0166cadbb
• sdk/python: add first-class login support (#23093)

  ## Why
  
  The Python SDK can already create threads and run turns, but
  authentication still has to be arranged outside the SDK. App-server
  already exposes account login, account inspection, logout, and
  `account/login/completed` notifications, so SDK users currently have to
  work around a missing public client layer for a core setup step.
  
  This change makes authentication a normal SDK workflow while preserving
  the backend flow shape: API-key login completes immediately, and
  interactive ChatGPT flows return live handles that complete later
  through app-server notifications.
  
  ## What changed
  
  - Added public sync and async auth methods on `Codex` / `AsyncCodex`:
    - `login_api_key(...)`
    - `login_chatgpt()`
    - `login_chatgpt_device_code()`
    - `account(...)`
    - `logout()`
  - Added public browser-login and device-code handle types with
  attempt-local `wait()` and `cancel()` helpers. Cancellation stays on the
  handle instead of a root-level SDK method.
  - Extended the Python app-server client and notification router so login
  completion events are routed by `login_id` without consuming unrelated
  global notifications.
  - Kept login request/handle logic in a focused internal `_login.py`
  module so `api.py` remains the public facade instead of absorbing more
  auth plumbing.
  - Exported the new handle types plus curated account/login response
  types from the SDK surfaces.
  - Updated SDK docs, added sync/async login walkthrough examples, and
  added a notebook login walkthrough cell.
  
  ## Verification
  
  Added SDK coverage for:
  
  - API-key login, account readback, and logout through the app-server
  harness in both sync and async clients.
  - Browser login cancellation plus `handle.wait()` completion through the
  real app-server boundary used by the Python SDK harness.
  - Waiter routing that stays scoped across replaced interactive login
  attempts, plus async handle cancellation coverage.
  - Login notification demuxing, replay of early completion events, and
  async client delegation.
  - Public export/signature assertions.
  - Real integration-suite smoke coverage for the new examples and
  notebook login cell.

  Ahmed Ibrahim · 2026-05-16 19:49:28 -07:00
  4c89772314
• [codex] Split Python SDK helper logic (#22939)

  ## Summary
  - Move approval-mode mapping into
  `sdk/python/src/openai_codex/_approval_mode.py`.
  - Move initialize metadata parsing and normalization into
  `sdk/python/src/openai_codex/_initialize_metadata.py`.
  - Keep the public `ApprovalMode` export stable and retarget direct
  metadata helper coverage.
  
  ## Integration coverage
  - Add an app-server harness smoke that exercises sync and async SDK
  initialization plus thread creation.
  
  ## Validation
  - Local tests were not run per repo guidance. CI should validate this
  branch once the PR is online.

  Ahmed Ibrahim · 2026-05-16 09:47:51 -07:00
  a280248021
• [8/8] Add Python SDK Ruff formatting (#22021)

  ## Why
  
  The Python SDK needs the same tight formatter/lint loop as the rest of
  the repo: a safe Ruff autofix pass, Ruff formatting, editor save
  behavior, and CI checks that catch drift. Without that loop, SDK changes
  can land with formatting or import ordering that differs from what
  reviewers and CI expect.
  
  ## What
  
  - Add Ruff configuration to `sdk/python/pyproject.toml`, excluding
  generated protocol code and notebooks from the normal lint/format pass.
  - Update `just fmt` so it still formats Rust and also runs Python SDK
  Ruff autofix and formatting.
  - Add Python SDK CI steps for `ruff check` and `ruff format --check`
  before pytest.
  - Recommend the Ruff VS Code extension and enable Python
  format/fix/organize-on-save so Cmd+S uses the same tooling.
  - Apply the resulting Ruff formatting to SDK Python files, examples, and
  the checked-in generated `v2_all.py` output emitted by the pinned
  generator.
  - Add a guard test for the `just fmt` recipe so it keeps working from
  both Rust and Python SDK working directories.
  
  ## Stack
  
  1. #21891 `[1/8]` Pin Python SDK runtime dependency
  2. #21893 `[2/8]` Generate Python SDK types from pinned runtime
  3. #21895 `[3/8]` Run Python SDK tests in CI
  4. #21896 `[4/8]` Define Python SDK public API surface
  5. #21905 `[5/8]` Rename Python SDK package to `openai-codex`
  6. #21910 `[6/8]` Add high-level Python SDK approval mode
  7. #22014 `[7/8]` Add Python SDK app-server integration harness
  8. This PR `[8/8]` Add Python SDK Ruff formatting
  
  ## Verification
  
  - Added `test_root_fmt_recipe_formats_rust_and_python_sdk` for the
  shared format recipe.
  - Ran `just fmt` after the recipe update.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-05-12 01:10:29 +03:00
  aa9e8f0262
• [6/8] Add high-level Python SDK approval mode (#21910)

  ## Why
  
  The high-level SDK should expose the approval behavior it actually
  supports instead of leaking generated app-server routing fields. New
  work should have two clear choices: default auto review, or explicitly
  deny escalated permission requests. Existing threads and subsequent
  turns should preserve their current approval behavior unless the caller
  passes an override.
  
  ## What
  
  - Add the public `ApprovalMode` enum with `auto_review` and `deny_all`.
  - Default new thread creation to `ApprovalMode.auto_review`.
  - Preserve existing approval settings by default for resume, fork, run,
  and turn helpers.
  - Remove raw `approval_policy` / `approvals_reviewer` kwargs from
  high-level SDK wrappers.
  - Update generated wrapper output, docs, examples, notebooks, and tests
  for the high-level approval mode API.
  
  ## Stack
  
  1. #21891 `[1/8]` Pin Python SDK runtime dependency
  2. #21893 `[2/8]` Generate Python SDK types from pinned runtime
  3. #21895 `[3/8]` Run Python SDK tests in CI
  4. #21896 `[4/8]` Define Python SDK public API surface
  5. #21905 `[5/8]` Rename Python SDK package to `openai-codex`
  6. This PR `[6/8]` Add high-level Python SDK approval mode
  7. #22014 `[7/8]` Add Python SDK app-server integration harness
  8. #22021 `[8/8]` Add Python SDK Ruff formatting
  
  ## Verification
  
  - Added approval-mode mapping/default tests for new threads, existing
  threads, forks, resumes, and subsequent turns.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-05-12 01:02:43 +03:00
  2b90c37069
• [5/8] Rename Python SDK package to openai-codex (#21905)

  ## Why
  
  The SDK should publish under the reserved public distribution name
  `openai-codex`, and its import module should match that name in the
  Python style. Since package names can contain hyphens but import modules
  cannot, the public import path becomes `openai_codex`.
  
  Keeping the rename separate from the public API surface change makes the
  naming change easy to review and avoids mixing it with API curation.
  
  ## What
  
  - Rename the SDK distribution from `openai-codex-app-server-sdk` to
  `openai-codex`.
  - Rename the import package from `codex_app_server` to `openai_codex`.
  - Keep the runtime wheel as the separate `openai-codex-cli-bin`
  dependency.
  - Update docs, examples, notebooks, artifact scripts, lockfile metadata,
  and tests for the new distribution/module names.
  
  ## Stack
  
  1. #21891 `[1/8]` Pin Python SDK runtime dependency
  2. #21893 `[2/8]` Generate Python SDK types from pinned runtime
  3. #21895 `[3/8]` Run Python SDK tests in CI
  4. #21896 `[4/8]` Define Python SDK public API surface
  5. This PR `[5/8]` Rename Python SDK package to `openai-codex`
  6. #21910 `[6/8]` Add high-level Python SDK approval mode
  7. #22014 `[7/8]` Add Python SDK app-server integration harness
  8. #22021 `[8/8]` Add Python SDK Ruff formatting
  
  ## Verification
  
  - Updated package metadata and public API tests to assert the
  distribution and import names.
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-05-12 00:59:25 +03:00
  f1b84fac63
• [4/8] Define Python SDK public API surface (#21896)

  ## Why
  
  The SDK package root should be the ergonomic public client API, not a
  dump of every generated app-server schema type. Generated models still
  need a supported import path, but callers should be able to tell which
  names are high-level SDK entrypoints and which names are protocol value
  models.
  
  ## What
  
  - Define a curated root `__all__` for clients, handles, input helpers,
  retry helpers, config, and public errors.
  - Add a `types` module as the supported home for generated app-server
  response, event, enum, and helper models.
  - Update docs and examples to import protocol/value models from the type
  module.
  - Add tests that lock root exports, type-module exports, star-import
  behavior, and example import hygiene.
  
  ## Stack
  
  1. #21891 `[1/8]` Pin Python SDK runtime dependency
  2. #21893 `[2/8]` Generate Python SDK types from pinned runtime
  3. #21895 `[3/8]` Run Python SDK tests in CI
  4. This PR `[4/8]` Define Python SDK public API surface
  5. #21905 `[5/8]` Rename Python SDK package to `openai-codex`
  6. #21910 `[6/8]` Add high-level Python SDK approval mode
  7. #22014 `[7/8]` Add Python SDK app-server integration harness
  8. #22021 `[8/8]` Add Python SDK Ruff formatting
  
  ## Verification
  
  - Added public API signature tests for root exports, `types` exports,
  and example imports.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-05-12 00:57:44 +03:00
  b4bc02439f
• [2/8] Generate Python SDK types from pinned runtime (#21893)

  ## Why
  
  Once the SDK declares its runtime package, generated Python artifacts
  should come from that pinned runtime rather than whatever app-server
  schema happens to be in the current checkout. That keeps the generated
  API and model surface aligned with the runtime users install.
  
  ## What
  
  - Teach `scripts/update_sdk_artifacts.py generate-types` to invoke the
  pinned runtime package for schema generation.
  - Regenerate `v2_all.py`, `notification_registry.py`, and generated
  public wrapper methods from that schema.
  - Add freshness coverage so regenerating from the pinned runtime must
  leave checked-in artifacts unchanged.
  
  ## Stack
  
  1. #21891 `[1/8]` Pin Python SDK runtime dependency
  2. This PR `[2/8]` Generate Python SDK types from pinned runtime
  3. #21895 `[3/8]` Run Python SDK tests in CI
  4. #21896 `[4/8]` Define Python SDK public API surface
  5. #21905 `[5/8]` Rename Python SDK package to `openai-codex`
  6. #21910 `[6/8]` Add high-level Python SDK approval mode
  7. #22014 `[7/8]` Add Python SDK app-server integration harness
  8. #22021 `[8/8]` Add Python SDK Ruff formatting
  
  ## Verification
  
  - Added `test_generated_files_are_up_to_date` for pinned-runtime
  generation drift.
  - Added generator-structure tests for schema annotation and notification
  metadata generation.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-05-12 00:53:21 +03:00
  6a4653efc8
• Add remote plugin skill read API (#20150)

  ## Summary
  
  Adds an app-server `plugin/skill/read` method for remote plugin skill
  markdown. The new method calls the plugin-service skill detail endpoint
  and returns `skill_md_contents`, so clients can preview skills for
  remote plugins before the bundle is installed locally.
  
  ## Why
  
  Uninstalled remote plugin skills do not have local `SKILL.md` files.
  Without an on-demand remote read, the desktop plugin details UI cannot
  render the skill details modal for those skills.
  
  ## Validation
  
  - `just write-app-server-schema`
  - `just fmt`
  - `cargo test -p codex-app-server-protocol`
  - `cargo test -p codex-app-server --test all --
  suite::v2::plugin_read::plugin_skill_read_reads_remote_skill_contents_when_remote_plugin_enabled
  --exact`
  - `just fix -p codex-app-server-protocol -p codex-core-plugins -p
  codex-app-server`

  xli-oai · 2026-05-01 00:16:25 -07:00
  96d2ea9058
• Publish Python SDK with Codex-pinned versioning (#18996)

  **note**: a large chunk of this diff comes from regenerating Python
  types after app-server schema changes on `main`.
  
  This is PR 3 of 3 for the Python SDK PyPI publishing split. PR #18862
  refreshed the generated SDK surface, and PR #18865 made the runtime
  package publishable as `openai-codex-cli-bin`; this final PR makes the
  SDK package publishable as `openai-codex-app-server-sdk` and pins both
  packages to the same Codex runtime version.
  
  The key idea is that the published SDK version is the Codex runtime
  version. That one version now drives the SDK package version, the exact
  runtime dependency, the client version reported by the SDK, and the
  bootstrap runtime pin. This keeps release-time versioning in one lane
  instead of scattering checked-in literals through the package.
  
  ## What changed
  
  - Rename the SDK distribution from `codex-app-server-sdk` to
  `openai-codex-app-server-sdk` for conflict-free PyPI publishing.
  - Use `stage-sdk --codex-version ...` with one Codex version for both
  the SDK package version and exact `openai-codex-cli-bin` dependency.
  - Preserve hidden legacy `--runtime-version` / `--sdk-version` args only
  to reject mismatched versions during staging.
  - Map PEP 440 package versions back to Codex release tags for runtime
  setup downloads, e.g. `0.116.0a1` -> `rust-v0.116.0-alpha.1`.
  - Derive `codex_app_server.__version__`, the default
  `AppServerConfig.client_version`, and
  `_runtime_setup.pinned_runtime_version()` from the SDK package/project
  version instead of hardcoding duplicate version strings.
  - Carry the current generated SDK refresh from `main` so
  `generate-types` stays clean after recent app-server schema changes.
  - Update `sdk/python/uv.lock` for the renamed editable package.
  
  ## Validation
  
  - `uv run --extra dev pytest` in `sdk/python` -> 59 passed, 37 skipped.
  - Targeted `uv run ruff check` for the touched SDK files.
  - `git diff --check`.
  - Staged runtime with `--codex-version rust-v0.116.0-alpha.1
  --platform-tag macosx_11_0_arm64`.
  - Staged SDK with `--codex-version rust-v0.116.0-alpha.1`.
  - Built runtime wheel, SDK wheel, and SDK sdist.
  - `twine check /tmp/codex-python-pr3-build/dist/*` -> passed.
  - Clean venv smoke installed `openai-codex-app-server-sdk==0.116.0a1`
  from local dist and pulled `openai-codex-cli-bin==0.116.0a1`.
  - Smoke imports passed for `Codex` and `bundled_codex_path()`.

  Steve Coffey · 2026-04-27 14:28:46 -07:00
  0f40261e86
• Refresh generated Python app-server SDK types (#18862)

  This is the first step in splitting the Python SDK PyPI publish work
  into reviewable layers: land the generated SDK refresh by itself before
  changing packaging mechanics. The next PRs will make the runtime wheel
  publishable, then wire the SDK package/version pinning to that runtime.
  
  ## Summary
  - Refresh generated Python app-server v2 models and notification
  registry from the current schema.
  - Update the public API signature expectations for the newly generated
  kwargs.
  
  ## Stack
  - PR 1 of 3 for the Python SDK PyPI publishing split.
  - Follow-up PRs will handle runtime wheel publishing mechanics, then
  SDK/package version pinning.
  
  ## Tests
  - `uv run --extra dev pytest` in `sdk/python` -> 51 passed, 37 skipped.

  Steve Coffey · 2026-04-21 10:23:27 -07:00
  38ba876ea9
• Add Python SDK thread.run convenience methods (#15088)

  ## TL;DR
  Add `thread.run(...)` / `async thread.run(...)` convenience methods to
  the Python SDK for the common case.
  
  - add `RunInput = Input | str` and `RunResult` with `final_response`,
  collected `items`, and optional `usage`
  - keep `thread.turn(...)` strict and lower-level for streaming,
  steering, interrupting, and raw generated `Turn` access
  - update Python SDK docs, quickstart examples, and tests for the sync
  and async convenience flows
  
  ## Validation
  - `python3 -m pytest sdk/python/tests/test_public_api_signatures.py
  sdk/python/tests/test_public_api_runtime_behavior.py`
  - `python3 -m pytest
  sdk/python/tests/test_real_app_server_integration.py -k
  'thread_run_convenience or async_thread_run_convenience'` (skipped in
  this environment)
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Shaqayeq · 2026-03-19 00:57:48 +00:00
  4fd2774614
• Add Python SDK public API and examples (#14446)

  ## TL;DR
  WIP esp the examples
  
  Thin the Python SDK public surface so the wrapper layer returns
  canonical app-server generated models directly.
  
  - keeps `Codex` / `AsyncCodex` / `Thread` / `Turn` and input helpers,
  but removes alias-only type layers and custom result models
  - `metadata` now returns `InitializeResponse` and `run()` returns the
  generated app-server `Turn`
  - updates docs, examples, notebook, and tests to use canonical generated
  types and regenerates `v2_all.py` against current schema
  - keeps the pinned runtime-package integration flow and real integration
  coverage
  
    ## Validation
    - `PYTHONPATH=sdk/python/src python3 -m pytest sdk/python/tests`
  - `GH_TOKEN="$(gh auth token)" RUN_REAL_CODEX_TESTS=1
  PYTHONPATH=sdk/python/src python3 -m pytest sdk/python/tests -rs`
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Shaqayeq · 2026-03-17 16:05:56 -07:00
  fc75d07504