31 Commits

• [codex] Stage Python SDK beta versions from release tags (#24872)

  ## Summary
  - Treat `sdk/python` as a development template with source version
  `0.0.0-dev`, matching the existing Python runtime packaging pattern.
  - Have `python-v*` tags supply the published SDK beta version through
  the existing `stage-sdk --sdk-version` path.
  - Remove the workflow check requiring a source version bump for each
  beta release and remove its now-unused host Python setup step.
  - Keep the reviewed runtime dependency pin at
  `openai-codex-cli-bin==0.132.0`.
  - Remove beta-number-specific documentation so it does not need editing
  for each publish.
  
  ## Why
  The package staging script already writes the release version into the
  artifact. Requiring the checked-in SDK template version to match every
  tag adds release-only source churn without changing the package users
  receive.
  
  ## Validation
  - Not run locally; relying on online CI for this workflow and metadata
  change.
  
  ## Release
  After this PR lands, publish the next beta by pushing tag
  `python-v0.1.0b2` from merged `main`.

  Ahmed Ibrahim · 2026-05-27 23:24:42 -07:00
  46946bb91c
• [codex] Prepare Python SDK beta documentation and package metadata (#24836)

  ## Why
  
  The initial public `openai-codex` beta should read and install like a
  normal published Python package before a release tag is created. This
  follows merged PR #24828, which establishes the independent SDK beta
  release plumbing and exact runtime dependency.
  
  ## What changed
  
  - Rewrote `sdk/python/README.md` as a compact PyPI-facing beta package
  page: published installation, one quickstart, short login examples,
  built-in help, and links to deeper guides.
  - Updated the getting-started guide, API reference, FAQ, and examples
  index to present the published beta consistently without repeating
  onboarding in the package landing page or reference page.
  - Made `pip install openai-codex` the primary install path while beta
  releases are the only published SDK releases, with `--pre` documented
  for opting into prereleases after a stable release exists.
  - Added curated `help()` / `pydoc` docstrings across the public API and
  generated public convenience methods through
  `scripts/update_sdk_artifacts.py`.
  - Declared the repository `Apache-2.0` license expression and
  Documentation URL in package metadata, without introducing a duplicated
  SDK-local license file.
  - Kept the source distribution focused on installable package material
  (`src/openai_codex`, `README.md`, and `pyproject.toml`); the repository
  docs and runnable examples remain linked from the PyPI README.
  - Built release artifacts in an Alpine container on the Ubuntu runner,
  matching Python SDK CI and allowing type generation to install the
  published `musllinux` runtime wheel.
  - Added `twine check --strict` to the release workflow so malformed PyPI
  metadata or rendered README content fails before publishing.
  - Added focused SDK assertions for beta metadata, the exact runtime pin,
  source distribution contents, and the built-in Python documentation
  surface.
  
  ## Validation
  
  - Ran `uv run --frozen --extra dev ruff check
  scripts/update_sdk_artifacts.py src/openai_codex
  tests/test_public_api_signatures.py
  tests/test_artifact_workflow_and_binaries.py` before the final
  README-only reductions and review-fix follow-ups.
  - Built `openai_codex-0.1.0b1-py3-none-any.whl` and
  `openai_codex-0.1.0b1.tar.gz` before the final README-only reductions
  and review-fix follow-ups.
  - Ran `python -m twine check --strict` on both built artifacts before
  the final README-only reductions and review-fix follow-ups.
  - Verified artifact metadata reports `Apache-2.0` without a duplicated
  SDK-local license file.
  - Verified `inspect.getdoc(...)` resolves documentation for the package,
  `Codex`, `CodexConfig`, and key generated thread methods.
  - Rebased the documentation/readiness change onto merged PR #24828
  without changing the intended SDK or workflow file contents.
  - Final verification is delegated to online CI for this PR.

  Ahmed Ibrahim · 2026-05-27 18:29:05 -07:00
  eb1cc3824c
• [codex] Add independent beta release for the Python SDK (#24828)

  ## Why
  
  `openai-codex` needs a beta release lifecycle without requiring beta
  releases of its pinned runtime package. Previously, SDK staging rewrote
  its runtime dependency to the SDK version, which made an SDK-only beta
  impossible.
  
  ## What changed
  
  - Set the initial SDK beta version to `0.1.0b1` and pin it to published
  stable `openai-codex-cli-bin==0.132.0`.
  - Decoupled SDK release staging from runtime versioning so it preserves
  the reviewed exact runtime pin.
  - Added a `python-v*` tag workflow that builds and publishes only
  `openai-codex` through PyPI trusted publishing.
  - Removed the Beta classifier from runtime package metadata for future
  runtime publications.
  - Regenerated protocol-derived SDK models from the selected stable
  runtime package.
  
  `0.132.0` is the newest stable runtime admitted by the checked-in
  dependency date fence and retains the Linux wheel family currently used
  by SDK CI.
  
  ## Release setup
  
  Before pushing `python-v0.1.0b1`, configure PyPI trusted publishing for
  the `openai-codex` project with workflow `python-sdk-release.yml`,
  environment `pypi`, and job `publish-python-sdk`.
  
  ## Validation
  
  - `uv run --frozen --extra dev ruff check src/openai_codex scripts
  examples tests`
  - Parsed `.github/workflows/python-sdk-release.yml` with PyYAML.
  - Built staged release artifacts locally:
  `openai_codex-0.1.0b1-py3-none-any.whl` and
  `openai_codex-0.1.0b1.tar.gz`.
  - Verified wheel metadata pins `openai-codex-cli-bin==0.132.0`.
  - Tests are deferred to online CI for this PR.

  Ahmed Ibrahim · 2026-05-27 17:57:51 -07:00
  4d0c4cd058
• [codex] Rename Python SDK AppServerConfig to CodexConfig (#24800)

  ## Why
  
  `AppServerConfig` is exported as part of the ergonomic Python SDK
  surface and passed to `Codex(...)` and `AsyncCodex(...)`. That name
  exposes the underlying app-server transport at the same layer where
  users are configuring the Codex client. `CodexConfig` makes the common
  callsite read naturally and names the object it configures.
  
  ## What changed
  
  - Renamed the public configuration dataclass from `AppServerConfig` to
  `CodexConfig`.
  - Updated `Codex`, `AsyncCodex`, and the transport clients to accept
  `CodexConfig`.
  - Updated binary-resolution messages, package exports, docs, examples,
  and related coverage to use the new public name.
  
  ## API impact
  
  ```python
  from openai_codex import Codex, CodexConfig
  
  with Codex(config=CodexConfig(codex_bin="/path/to/codex")) as codex:
      ...
  ```
  
  Callers should now import and construct `CodexConfig`; `AppServerConfig`
  is no longer part of the Python SDK surface.
  
  ## Validation
  
  - `uv run --frozen --extra dev ruff check src/openai_codex scripts
  examples tests`
  - Tests are deferred to online CI for this PR.

  Ahmed Ibrahim · 2026-05-27 16:10:15 -07:00
  0db49a7e6a
• [codex] Add friendly Python SDK sandbox presets (#24772)

  ## Why
  
  The Python SDK currently exposes sandbox selection differently depending
  on where it is used: thread lifecycle methods accept `SandboxMode`,
  while turns accept the lower-level `SandboxPolicy` shape. For the common
  case of choosing an access level, that leaks app-server wire details
  into otherwise straightforward SDK usage.
  
  This makes the common path explicit and discoverable: callers choose a
  named sandbox preset once, using the same keyword on threads and turns.
  The preset name `workspace_write` also makes the granted capability
  clear at the callsite.
  
  ## What changed
  
  - Added a root-level `Sandbox` enum with documented presets:
    - `Sandbox.read_only`: read files without allowing writes.
  - `Sandbox.workspace_write`: the normal default for projects with a
  recorded trust decision; read files and write inside the workspace and
  configured writable roots.
    - `Sandbox.full_access`: run without filesystem access restrictions.
  - Documented that omitting `sandbox=` delegates to app-server's
  configured default, while explicit turn overrides remain sticky for
  subsequent turns.
  - Updated sync and async thread lifecycle and turn APIs to consistently
  accept `sandbox=Sandbox...`, translating to the existing app-server
  thread and turn representations internally.
  - Updated the public API artifact generator so regenerated SDK wrappers
  retain the friendly enum shape.
  - Replaced low-level policy construction in Python docs, examples, and
  the walkthrough notebook with the preset API.
  - Added focused coverage for root exports, method signatures,
  preset-to-wire mapping, and rejection of raw string sandbox inputs.
  
  ## API impact
  
  High-level turn calls now use `sandbox=` instead of `sandbox_policy=`:
  
  ```python
  from openai_codex import Codex, Sandbox
  
  with Codex() as codex:
      thread = codex.thread_start(sandbox=Sandbox.workspace_write)
      result = thread.run("Review the diff only.", sandbox=Sandbox.read_only)
  ```
  
  `thread_start(...)` already defaults to `ApprovalMode.auto_review`, so
  normal writable usage is concise:
  
  ```python
  with Codex() as codex:
      thread = codex.thread_start(sandbox=Sandbox.workspace_write)
      thread.run("Update the files in this workspace.")
  ```
  
  With that combination, edits inside `cwd` and configured writable roots
  run within the workspace-write sandbox. Operations that require
  approval, such as edits outside those roots, are routed through auto
  review. When `sandbox=` is omitted, app-server resolves its configured
  default. A sandbox supplied to `run(...)` or `turn(...)` applies to that
  turn and subsequent turns.
  
  ## Test coverage
  
  - `sdk/python/tests/test_public_api_signatures.py` covers the public
  export and parameter names, including the default approval mode.
  - `sdk/python/tests/test_public_api_runtime_behavior.py` covers preset
  mappings to the existing wire types and raw string rejection.

  Ahmed Ibrahim · 2026-05-27 11:11:04 -07:00
  b1cbf622ad
• sdk: launch packaged Codex runtimes (#23786)

  ## Why
  
  The Python and TypeScript SDKs launch the native Codex runtime directly,
  so they need to consume the same package artifact shape that release
  jobs now produce. The runtime wheel should be built from the canonical
  Codex package archive rather than reconstructing a parallel layout from
  loose binaries.
  
  ## What Changed
  
  - Stage `openai-codex-cli-bin` by extracting
  `codex-package-<target>.tar.gz` into `src/codex_cli_bin` and validating
  the expected package layout.
  - Update release workflows to pass the generated package archive into
  `stage-runtime` instead of the temporary package directory.
  - Update Python runtime setup to download `codex-package-*.tar.gz`
  release assets directly.
  - Expose Python runtime helpers for the bundled package directory and
  `codex-path`, and prepend that path when `openai_codex` launches the
  installed runtime without duplicating Windows `Path`/`PATH` keys.
  - Teach the TypeScript SDK to resolve package-layout optional
  dependencies while keeping the existing npm fallback layout, and
  preserve the existing Windows path variable casing when prepending
  `codex-path`.
  
  ## Test Plan
  
  - `python3 -m py_compile sdk/python/scripts/update_sdk_artifacts.py
  sdk/python/_runtime_setup.py sdk/python/src/openai_codex/client.py
  sdk/python-runtime/src/codex_cli_bin/__init__.py`
  - `uv run --frozen --project sdk/python --extra dev ruff check
  sdk/python/scripts/update_sdk_artifacts.py sdk/python/_runtime_setup.py
  sdk/python/src/openai_codex/client.py
  sdk/python/tests/test_artifact_workflow_and_binaries.py
  sdk/python-runtime/src/codex_cli_bin/__init__.py`
  - `uv run --frozen --project sdk/python --extra dev pytest
  sdk/python/tests/test_artifact_workflow_and_binaries.py`
  - `pnpm eslint src/exec.ts tests/exec.test.ts`
  - `pnpm test --runInBand tests/exec.test.ts`

  Michael Bolin · 2026-05-20 18:01:22 -07:00
  0b4f86095c
• [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
• [codex] Refine Python SDK user-facing docs (#22941)

  ## Summary
  - Remove maintainer and release-process wording from the Python SDK
  README and docs.
  - Rewrite SDK-facing comments/docstrings so they read as standalone
  product documentation.
  - Add a real app-server integration smoke that follows the public
  quickstart-style `Codex() -> thread_start() -> run()` path.
  
  ## Integration coverage
  - Add `test_real_quickstart_style_flow_smoke` in the real app-server
  integration suite.
  
  ## Validation
  - Local tests were not run per repo guidance. CI should validate this
  branch once the PR is online.

  Ahmed Ibrahim · 2026-05-15 19:55:05 -07:00
  326e31ab65
• fix: prevent fmt from updating Python SDK lockfile (#22505)

  ## Why
  
  `just fmt` should align source formatting without resolving dependencies
  or rewriting lockfiles. The Python SDK formatting steps run through
  `uv`, so differing local `uv` versions could decide the SDK lock was
  stale and mutate `sdk/python/uv.lock` before Ruff ran.
  
  ## What
  
  - Add `--frozen` to both Python SDK `uv run ... ruff` commands in the
  root `fmt` recipe.
  - Update the existing Python SDK artifact workflow guard test so future
  changes keep the formatter recipe non-lock-mutating.
  
  ## Verification
  
  - `uv run --frozen --project ../sdk/python --extra dev pytest
  ../sdk/python/tests/test_artifact_workflow_and_binaries.py -q`

  jif-oai · 2026-05-13 17:58:08 +02:00
  382404db99
• [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
• [7/8] Add Python SDK app-server integration harness (#22014)

  ## Why
  
  The SDK had behavioral tests that replaced SDK client internals. Those
  tests could catch wrapper mistakes, but they did not prove the pinned
  app-server runtime, generated notification models, request routing, and
  sync/async public clients worked together.
  
  This PR adds deterministic integration coverage that starts the pinned
  `codex app-server` process and mocks only the upstream Responses HTTP
  boundary.
  
  ## What
  
  - Add `AppServerHarness` and `MockResponsesServer` helpers for isolated
  `CODEX_HOME`, mock-provider config, queued SSE responses, and captured
  `/v1/responses` requests.
  - Add shared helpers for SSE construction, stream assertions,
  approval-policy inspection, and image fixtures.
  - Split integration coverage into focused modules for run behavior,
  inputs, streaming, turn controls, approvals, and thread lifecycle.
  - Cover sync and async `Thread.run`, `TurnHandle.stream`, interleaved
  streams, approval-mode persistence, lifecycle helpers, final-answer
  phase handling, image inputs, loaded skill input injection, steering,
  interruption, listing, history reads, run overrides, and token usage
  mapping.
  - Replace public-wrapper tests that duplicated integration-test behavior
  with lower-level client tests only where direct client behavior is the
  thing under test.
  
  ## 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. This PR `[7/8]` Add Python SDK app-server integration harness
  8. #22021 `[8/8]` Add Python SDK Ruff formatting
  
  ## Verification
  
  - Added pinned app-server integration tests under
  `sdk/python/tests/test_app_server_*.py` and
  `test_real_app_server_integration.py`.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-05-12 01:06:41 +03:00
  3e10e09e24
• [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
• [1/8] Pin Python SDK runtime dependency (#21891)

  ## Why
  
  The Python SDK depends on the app-server runtime package for the bundled
  `codex` binary and schema source of truth. That relationship should be
  explicit in package metadata instead of inferred from matching version
  numbers, so installers, lockfiles, and reviewers can see exactly which
  runtime the SDK expects.
  
  ## What
  
  - Declare `openai-codex-cli-bin==0.131.0a4` as a Python SDK dependency.
  - Update runtime setup helpers to resolve the runtime version from the
  declared dependency pin.
  - Refresh the SDK lockfile for the pinned runtime wheel.
  - Update package/runtime tests and docs that describe where the runtime
  version comes from.
  
  ## Stack
  
  1. This PR `[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. #22021 `[8/8]` Add Python SDK Ruff formatting
  
  ## Verification
  
  - Added coverage for the SDK runtime dependency pin and runtime
  distribution naming.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-05-12 00:42:26 +03:00
  5fe33443b0
• Route Python SDK turn notifications by ID (#21778)

  ## Why
  
  The Python SDK previously protected the stdio transport with a single
  active turn-consumer guard. That avoided competing reads from stdout,
  but it also meant one `Codex`/`AsyncCodex` client could not stream
  multiple active turns at the same time. Notifications could also arrive
  before the caller received a `TurnHandle` and registered for streaming,
  so the SDK needed an explicit routing layer instead of letting
  individual API calls read directly from the shared transport.
  
  ## What Changed
  
  - Added a private `MessageRouter` that owns per-request response queues,
  per-turn notification queues, pending turn-notification replay, and
  global notification delivery behind a single stdout reader thread.
  - Generated typed notification routing metadata so turn IDs come from
  known payload shapes instead of router-side attribute guessing, with
  explicit fallback handling for unknown notification payloads.
  - Updated sync and async turn streaming so `TurnHandle.stream()`/`run()`
  and `stream_text()` consume only notifications for their own turn ID,
  while `AsyncAppServerClient` no longer serializes all transport calls
  behind one async lock.
  - Cleared pending turn-notification buffers when unregistered turns
  complete so never-consumed turn handles do not leave stale queues
  behind.
  - Removed the internal stream-until helper now that turn completion
  waiting can register directly with routed turn notifications.
  - Updated Python SDK docs and focused tests for concurrent transport
  calls, interleaved turn routing, buffered early notifications, unknown
  notification routing, async delegation, and routed turn completion
  behavior.
  
  ## Validation
  
  - `uv run --extra dev ruff format scripts/update_sdk_artifacts.py
  src/codex_app_server/_message_router.py src/codex_app_server/client.py
  src/codex_app_server/generated/notification_registry.py
  tests/test_client_rpc_methods.py
  tests/test_public_api_runtime_behavior.py
  tests/test_async_client_behavior.py`
  - `uv run --extra dev ruff check scripts/update_sdk_artifacts.py
  src/codex_app_server/_message_router.py src/codex_app_server/client.py
  src/codex_app_server/generated/notification_registry.py
  tests/test_client_rpc_methods.py
  tests/test_public_api_runtime_behavior.py
  tests/test_async_client_behavior.py`
  - `uv run --extra dev pytest tests/test_client_rpc_methods.py
  tests/test_public_api_runtime_behavior.py
  tests/test_async_client_behavior.py`
  - `git diff --check`
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-05-09 04:16:23 +00:00
  ebe75bb683
• Support resource binaries in Python runtime staging (#21787)

  ## Why
  
  Some Codex runtime distributions need helper executables beside the main
  bundled binary. Linux sandbox fallback needs a packaged `bwrap` when no
  suitable system `bwrap` is available, and Windows sandbox/elevation
  needs helper executables discoverable beside `codex.exe`. The checked-in
  `openai-codex-cli-bin` template already packages everything under
  `codex_cli_bin/bin/**`, but the staging script only copied the main
  Codex binary into that directory.
  
  This PR adds the generic staging primitive needed by release workflows
  to build complete platform runtime wheels without baking
  platform-specific helper names into the package template.
  
  ## What changed
  
  - Added repeatable `stage-runtime --resource-binary` support so release
  workflows can copy extra executables beside the bundled Codex binary.
  - Kept resource selection in workflow code, where the platform target is
  known.
  - Added tests that verify resource binaries are copied into the staged
  runtime package, that the wheel include config covers them, and that the
  CLI forwards repeated `--resource-binary` values.
  
  ## Testing
  
  - `uv run ruff check scripts/update_sdk_artifacts.py
  tests/test_artifact_workflow_and_binaries.py`
  - `uv run --extra dev pytest
  tests/test_artifact_workflow_and_binaries.py::test_stage_runtime_release_copies_resource_binaries
  tests/test_artifact_workflow_and_binaries.py::test_runtime_resource_binaries_are_included_by_wheel_config
  tests/test_artifact_workflow_and_binaries.py::test_stage_runtime_stages_binary_without_type_generation`
  
  Full `tests/test_artifact_workflow_and_binaries.py` still has unrelated
  schema-normalization drift in the local checkout.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-05-08 22:00:44 +03:00
  8956a928a1
• 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
• Fix auto-review config compatibility across protocol and SDK (#19113)

  ## Why
  
  This keeps the partial Guardian subagent -> Auto-review rename
  forward-compatible across mixed Codex installations. Newer binaries need
  to understand the new `auto_review` spelling, but they cannot write it
  to shared `~/.codex/config.toml` yet because older CLI/app-server
  bundles only know `user` and `guardian_subagent` and can fail during
  config load before recovering.
  
  The Python SDK had the opposite compatibility gap: app-server responses
  can contain `approvalsReviewer: "auto_review"`, but the checked-in
  generated SDK enum did not accept that value.
  
  ## What Changed
  
  - Keep `ApprovalsReviewer::AutoReview` readable from both
  `guardian_subagent` and `auto_review`, while serializing it as
  `guardian_subagent` in both protocol crates.
  - Update TUI Auto-review persistence tests so enabling Auto-review
  writes `approvals_reviewer = "guardian_subagent"` while UI copy still
  says Auto-review.
  - Map managed/cloud `feature_requirements.auto_review` to the existing
  `Feature::GuardianApproval` gate without adding a broad local
  `[features].auto_review` key or changing config writes.
  - Add `auto_review` to the Python SDK `ApprovalsReviewer` enum and cover
  `ThreadResumeResponse` validation.
  
  ## Testing
  
  - `cargo test -p codex-protocol approvals_reviewer`
  - `cargo test -p codex-app-server-protocol approvals_reviewer`
  - `cargo test -p codex-tui
  update_feature_flags_enabling_guardian_selects_auto_review`
  - `cargo test -p codex-tui
  update_feature_flags_enabling_guardian_in_profile_sets_profile_auto_review_policy`
  - `cargo test -p codex-core
  feature_requirements_auto_review_disables_guardian_approval`
  - `pytest
  sdk/python/tests/test_client_rpc_methods.py::test_thread_resume_response_accepts_auto_review_reviewer`
  - `git diff --check`

  Won Park · 2026-04-23 03:12:56 -07:00
  17ae906048
• Stage publishable Python runtime wheels (#18865)

  This is PR 2 of the Python SDK PyPI publishing split. [PR
  1](https://github.com/openai/codex/pull/18862) refreshed the generated
  SDK bindings; this PR makes the runtime package itself publishable, and
  PR 3 will wire the SDK package/version pinning to this runtime package.
  
  ## Summary
  - Rename the runtime distribution to `openai-codex-cli-bin` while
  keeping the import package as `codex_cli_bin`.
  - Make the runtime package wheel-only and build `py3-none-<platform>`
  wheels instead of interpreter-specific wheels.
  - Add `stage-runtime --codex-version` and `--platform-tag` so release
  staging can produce the platform wheel matrix from Codex release tags.
  - Add focused artifact workflow tests for version normalization,
  platform tag injection, and runtime wheel metadata.
  
  ## Why Rename
  There is already an unofficial PyPI package,
  [`codex-bin`](https://pypi.org/project/codex-bin/), distributing OpenAI
  Codex binaries. Publishing the official SDK runtime dependency as
  `openai-codex-cli-bin` makes the ownership clear, avoids confusing the
  SDK-pinned runtime wheel with that unowned wrapper, and keeps the import
  package unchanged as `codex_cli_bin`.
  
  ## Tests
  - `uv run --extra dev pytest
  tests/test_artifact_workflow_and_binaries.py` -> 21 passed
  - `uv run --extra dev python scripts/update_sdk_artifacts.py
  stage-runtime /tmp/codex-python-pr2-rebased/runtime-stage
  /tmp/codex-python-pr2-rebased/codex --codex-version
  rust-v0.116.0-alpha.1 --platform-tag macosx_11_0_arm64`
  - `uv run --with build --extra dev python -m build --wheel
  /tmp/codex-python-pr2-rebased/runtime-stage`
  - `uv run --with twine --extra dev twine check
  /tmp/codex-python-pr2-rebased/runtime-stage/dist/openai_codex_cli_bin-0.116.0a1-py3-none-macosx_11_0_arm64.whl`
  
  ## Note
  - Full `uv run --extra dev pytest` currently fails because regenerating
  from schemas already on `main` adds new DeviceKey Python types. I left
  that generated catch-up out of this runtime-only PR.

  Steve Coffey · 2026-04-22 08:14:48 -07:00
  0127cef5db
• 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
• Fix stale quickstart integration assertion (#15677)

  TL;DR: update the quickstart integration assertion to match the current
  example output.
  
  - replace the stale `Status:` expectation for
  `01_quickstart_constructor` with `Server:`, `Items:`, and `Text:`
  - keep the existing guard against `Server: unknown`

  Shaqayeq · 2026-03-24 20:12:52 -07:00
  fece9ce745
• 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
• Refresh Python SDK generated types (#14646)

  ## Summary
  - regenerate `sdk/python` protocol-derived artifacts on latest
  `origin/main`
  - update `notification_registry.py` to match the regenerated
  notification set
  - fix the stale SDK test expectation for `GranularAskForApproval`
  
  ## Validation
  - `cd sdk/python && python scripts/update_sdk_artifacts.py
  generate-types`
  - `cd sdk/python && python -m pytest`

  sayan-oai · 2026-03-14 05:50:33 +00:00
  8ca358a13c
• Add Python app-server SDK (#14435)

  ## TL;DR
  Bring the Python app-server SDK from `main-with-prs-13953-and-14232`
  onto current `main` as a standalone SDK-only PR.
  
  - adds the new `sdk/python` and `sdk/python-runtime` package trees
  - keeps the scope to the SDK payload only, without the unrelated
  branch-history or workflow changes from the source branch
  - regenerates `sdk/python/src/codex_app_server/generated/v2_all.py`
  against current `main` schema so the extracted SDK matches today's
  protocol definitions
  
  ## Validation
  - `PYTHONPATH=sdk/python/src python3 -m pytest sdk/python/tests`
  
  Co-authored-by: Codex <noreply@openai.com>

  Shaqayeq · 2026-03-12 09:22:01 -07:00
  ff6764e808