58 Commits

• Make formatter output quiet on success (#29467)

  ## Why
  
  `just fmt` is quite noisy even on successful runs.
  
  ## What
  
  Only print output when a formatter fails.
  
  - Buffer output from each formatter and print only a failed command and
  its diagnostics.
  - Prefix the `justfile` driver invocations with `@` so Just does not
  echo the command itself.
  - Retain rustfmt stderr on failure and cover silent-success and
  failure-reporting behavior.
  
  ## Validation
  
  - Confirmed `just fmt` and `just fmt-check` both exit successfully with
  empty stdout and stderr.

  Adam Perry @ OpenAI · 2026-06-23 00:55:49 +00:00
  ff31ba8d0a
• Allow ChatGPT accounts without email (#28991)

  # Summary
  
  Codex required every ChatGPT account to have an email address. A
  service-account personal access token can return valid account metadata
  without one, so PAT login failed while decoding the metadata response.
  
  This change makes email optional in the account metadata type that owns
  it and preserves that absence through authentication, provider account
  state, the app-server API, generated clients, and TUI bootstrap.
  Existing accounts with email addresses keep the same behavior.
  
  ## Behavior-changing call sites
  
  | Call site | Behavior after this change |
  | --- | --- |
  | `login/src/auth/personal_access_token.rs` | PAT metadata accepts a
  missing or null email and retains `None`. |
  | `agent-identity/src/lib.rs` | Agent Identity JWT claims accept an
  omitted email. |
  | `login/src/auth/storage.rs` and `login/src/auth/agent_identity.rs` |
  Stored and managed Agent Identity records carry `Option<String>`.
  Deserialization maps the legacy empty-string sentinel to `None`. |
  | `login/src/auth/manager.rs` | `get_account_email` returns the stored
  option, and managed identity bootstrap no longer converts `None` to an
  empty string. |
  | `model-provider/src/provider.rs` and `protocol/src/account.rs` | A
  ChatGPT provider account requires a plan type but may carry no email. |
  | `app-server-protocol/src/protocol/v2/account.rs` | `account/read`
  keeps the `email` field on the wire and returns `null` when the account
  has no email. Generated TypeScript and JSON schemas describe a required,
  nullable field. |
  | `sdk/python/src/openai_codex/generated/v2_all.py` | The generated
  Python `ChatgptAccount` model accepts `None` for email. |
  | `tui/src/app_server_session.rs` | Email-less ChatGPT accounts
  bootstrap normally, keep external feedback routing, omit account-email
  telemetry, and display the plan in account status. |
  
  ## Design decisions
  
  - Missing email remains `None` at every layer. The code never uses an
  empty string as a substitute.
  - The app-server response includes `"email": null` instead of omitting
  the field. Clients retain a stable response shape.
  - Plan type remains required for provider account state. This change
  relaxes only the email assumption.
  
  ## Testing
  
  Tests: affected test targets compile, scoped Clippy and formatting pass,
  a focused TUI snapshot covers plan-only account status, real
  before/after PAT login smoke covers metadata without email, app-server
  smoke covers `account/read` with `email: null`, and a regression smoke
  covers an existing email-bearing PAT. Unit tests run in CI.
  
  ## Evidence
  
  Visual smoke evidence will be attached here.

  efrazer-oai · 2026-06-22 13:19:40 -07:00
  5a67d898a5
• [sdk/python] Stop advertising HTTP image URLs (#29464)

  ## Summary
  
  - use generated image data URLs in the Python SDK examples and notebook
  - document HTTP and HTTPS image URLs as deprecated and recommend
  `LocalImageInput`
  - replace the remote-URL integration test with data-URL coverage
  
  `ImageInput` remains available for data URLs. The SDK does not duplicate
  app-server URL validation.
  
  ## Testing
  
  - `uv run --frozen --no-sync ruff check --output-format=full .`
  - `uv run --frozen --no-sync ruff format --check .`
  - full Python SDK test suite with an isolated writable
  `CODEX_SQLITE_HOME` (119 passed, 38 skipped)

  rka-oai · 2026-06-22 11:34:14 -07:00
  20431d49a0
• build: run buildifier from just fmt (#28125)

  ## Intent
  
  Keep Bazel and Starlark files consistently formatted without requiring
  contributors to install or version buildifier themselves.
  
  ## Implementation
  
  - Add a SHA-256-pinned, cross-platform DotSlash manifest for buildifier
  v8.5.1.
  - Run buildifier from the shared `just fmt` and `just fmt-check` driver,
  with Windows-safe explicit DotSlash invocation.
  - Provision DotSlash in formatting CI and contributor devcontainers, and
  document the source-build prerequisite.
  - Apply the initial mechanical buildifier formatting baseline.

  Adam Perry @ OpenAI · 2026-06-13 21:43:39 -07:00
  740c4f269d
• Use uv as Python SDK build backend (#27901)

  ## Summary
  
  Replace Hatchling with uv's build backend for the Python SDK. The
  backend infers the `src/openai_codex` module from the normalized project
  name and standard source layout, so no uv-specific package configuration
  is required.
  
  This keeps Python packaging within the uv toolchain already used for
  dependency management and release builds. A controlled before-and-after
  PEP 517 comparison produced identical wheel package paths, bytes,
  permissions, and semantic metadata. The sdist retains the SDK package
  tree, root README, and project metadata while dropping the unrelated
  examples README that Hatch included through its broad include matching.

  Charlie Marsh · 2026-06-12 17:21:00 +00:00
  94427aaf46
• Use dependency groups for Python SDK tooling (#27538)

  ## Summary
  
  `just fmt` previously used `uv run --with ruff` to make Ruff available.
  Because `--with` creates an ephemeral overlay outside the project
  lockfile, uv periodically re-resolved Ruff (by default every 10 minutes)
  instead of using the version recorded in `uv.lock`.
  
  Move the Python SDK tooling dependencies from the published `dev` extra
  into `format`, `test`, and composed `dev` dependency groups. The
  formatter now selects only the locked `format` group, contributor and CI
  setup explicitly sync the `dev` group, and CI and release commands reuse
  that environment with `--frozen --no-sync`. The scripts formatter also
  uses its project's locked Ruff dependency instead of an ephemeral
  overlay.
  
  Validated the Python 3.12 SDK suite (119 passed, 38 skipped) and the
  repository formatter.

  Charlie Marsh · 2026-06-12 16:10:07 +00:00
  c375deaf66
• [2/4] Add private Python goal operations (#27111)

  ## Why
  
  The Python SDK must treat the runtime's initial goal turn and its
  continuations as one logical operation. That requires a private
  lifecycle engine before the public API can return the existing turn
  handle and result types.
  
  ## What
  
  - start goals by composing the existing clear/set goal RPCs
  - enforce persisted, idle threads and a bounded startup handshake
  - coalesce continuation notifications under a stable logical turn ID
  - aggregate items, usage, timing, and terminal status
  - support rollover-aware steering, interruption, cancellation, and
  cleanup
  - provide equivalent sync and async internals
  
  This is the second PR in the stack and intentionally adds no public API.
  
  ## Test plan
  
  - online CI, including the Python SDK suite
  - behavioral coverage is added in the following two stack PRs

  Ahmed Ibrahim · 2026-06-09 15:32:15 -07:00
  9316acf9b2
• [1/4] Add Python goal routing foundation (#27110)

  ## Why
  
  Goal continuation turns are emitted by the existing runtime as separate
  physical turns. The Python SDK needs private thread-scoped routing
  before it can present those notifications as one logical operation,
  without changing ordinary turn routing or the app-server protocol.
  
  ## What
  
  - add private goal operation state and thread-scoped notification
  routing
  - add internal wrappers for the existing `thread/goal/clear` and
  `thread/goal/set` RPCs
  - include existing goal notifications in the SDK notification union
  - preserve ordinary turn-ID routing unchanged
  - add focused routing coverage
  
  This PR does not expose a public goal API. It is the first PR in the
  Python goal operations stack.
  
  ## Test plan
  
  - online CI, including the Python SDK suite
  - focused typed-notification routing coverage

  Ahmed Ibrahim · 2026-06-09 13:35:29 -07:00
  5a0f913426
• [codex] Pin Python SDK to runtime 0.137.0a4 (#26216)

  ## Summary
  - pin the Python SDK runtime to `openai-codex-cli-bin==0.137.0a4`
  - refresh generated protocol artifacts from `rust-v0.137.0-alpha.4`
  - refresh `sdk/python/uv.lock` with all eight published runtime wheels
  
  ## Runtime publication
  - published `openai-codex-cli-bin==0.137.0a4` through the
  `python-sdk-release` workflow
  - includes macOS, manylinux, musllinux, and Windows wheels
  - publication run:
  https://github.com/openai/codex/actions/runs/26905608531
  
  ## Validation
  - ran `just fmt`
  - generated artifacts from the `rust-v0.137.0-alpha.4` release wheel
  - ran `uv lock --check --default-index https://pypi.org/simple`
  - did not run tests locally, per request; CI provides the test signal

  Ahmed Ibrahim · 2026-06-03 12:14:14 -07:00
  10b408080a
• [codex] Pin Python SDK to glibc-compatible runtime (#25907)

  ## Summary
  - pin the Python SDK runtime package to `openai-codex-cli-bin==0.136.0`
  so Ubuntu/glibc installs resolve a compatible wheel
  - refresh generated SDK artifacts and lock data for the runtime update
  - keep newly generated client-message-id wire models internal to the
  generated protocol layer
  
  ## Dependency
  - merge #25906 first so the Python SDK release publishes both manylinux
  and musllinux runtime wheels before publishing the package with this pin
  
  ## Validation
  - ran `just fmt`
  - regenerated the Python public API helpers
  - validated the edited workflow YAML
  - CI passed 29/29 checks

  Ahmed Ibrahim · 2026-06-02 12:27:01 -07:00
  bc49677ec8
• [codex] Add comprehensive root formatting check (#25683)

  ## Why
  
  The root formatting entrypoints could drift: `just fmt` did not format
  the Justfile itself, and the CI-facing check recipe only checked Python
  scripts instead of matching everything formatted by `just fmt`.
  
  ## What changed
  
  - Add a shared cross-platform Python formatter driver used by both `just
  fmt` and `just fmt-check`.
  - Run Justfile, Rust, Python SDK, and internal-script formatter groups
  concurrently while buffering each formatter group's output until it
  finishes.
  - Log formatter starts immediately, then print each formatter group's
  labeled output when it completes.
  - Keep the SDK lint-fix and Ruff formatting passes ordered, with source
  comments explaining their distinct roles and the check-mode equivalents.
  - Run Ruff through shared `uv run --no-sync --with ruff` overlays so
  formatting works on clean glibc Linux checkouts without installing the
  platform-specific SDK runtime wheel.
  - Show `fmt-check` help text in `just -l` and simplify CI to call the
  shared driver through `just fmt-check`.
  - Pin the general CI workflow to `just@1.51.0` so its formatter agrees
  with the checked-in Justfile.
  - Add regression coverage for the thin Just recipes and the driver's
  formatter graph.
  
  ## Validation
  
  - `just fmt`
  - `just fmt-check`
  - `python3 -m pytest
  sdk/python/tests/test_artifact_workflow_and_binaries.py -k 'root_fmt or
  root_format' -q`
  - `pnpm run format`
  - `git diff --check`
  - `just -l | rg -n '^    fmt|fmt-check'`
  - `uvx --from uv==0.7.22 uv run --frozen --project sdk/python --no-sync
  --with ruff ruff check --diff sdk/python`

  Adam Perry @ OpenAI · 2026-06-02 01:20:25 +00:00
  747f1003dd
• Check root Python script formatting in CI (#25165)

  ## Why
  
  Python files under `scripts/` were not covered by the repository
  formatting recipe or the CI formatting job, so formatting drift could
  merge unnoticed.
  
  ## What
  
  - Add a dedicated `scripts/pyproject.toml` and `scripts/uv.lock` so
  root-script formatting uses a locked Ruff version.
  - Extend `just fmt` to format root Python scripts and add
  `fmt-scripts-check` for CI.
  - Run `just fmt-scripts-check` from `.github/workflows/ci.yml`,
  installing `uv` through SHA-pinned `astral-sh/setup-uv` while retaining
  the `uv` `0.11.3` pin.
  - Apply Ruff formatting to the root Python scripts, including
  `scripts/just-shell.py`, and extend
  `sdk/python/tests/test_artifact_workflow_and_binaries.py` to cover the
  root formatting recipe.
  - Update `AGENTS.md` so agents run `just fmt` after code changes
  anywhere in the repository.
  
  ## Validation
  
  - Extended the existing Python SDK workflow test to assert that `just
  fmt` includes root Python scripts.

  Adam Perry @ OpenAI · 2026-06-01 18:50:23 +00:00
  281b416c44
• [codex] Make justfile recipes Windows-aware (#24983)

  ## Summary
  
  Make the root `justfile` usable from Windows without maintaining a
  separate Windows copy of most recipes.
  
  The repo recipes previously assumed POSIX shell behavior for things like
  variadic argument forwarding (`"$@"`) and stderr redirection
  (`2>/dev/null`). That made common workflows such as `just fmt`, `just
  test`, and `just log` unreliable from Windows. This PR introduces a
  small cross-platform shell adapter so recipes can stay mostly unified
  while still expanding the few shell-specific constructs correctly on
  macOS/Linux and Windows.
  
  ## What Changed
  
  - Add `scripts/just-shell.py` as the configured `just` shell adapter.
    - On Unix it invokes `sh -cu`.
  - On Windows it invokes `pwsh -CommandWithArgs` so arguments containing
  spaces are preserved.
  - Add portable recipe placeholders:
  - `{args}` expands to `"$@"` on Unix and the equivalent PowerShell
  forwarded-args expression on Windows.
  - `{stderr-null}` expands to the platform-specific stderr suppression
  used by `fmt`.
  - Convert most variadic one-line recipes to the unified `{args}` form,
  including `codex`, `exec`, `file-search`, `app-server-test-client`,
  `fix`, `clippy`, `bench`, `mcp-server-run`, `write-app-server-schema`,
  and `argument-comment-lint-from-source`.
  - Keep genuinely shell-specific recipes split or Unix-only for now,
  including recipes backed by `.sh` scripts or recipes whose bodies are
  more than simple command forwarding.
  - Add a Windows `just install` path that installs PowerShell via
  `winget` when `pwsh` is not available, then runs the same basic Rust
  setup steps.
  - Update the SDK test that validates the root `fmt` recipe so it
  recognizes the new portable stderr placeholder.
  
  ## Validation
  
  - `just --summary`
  - `just --dry-run fmt`
  - `just --dry-run bench-smoke`
  - `just --dry-run codex foo "bar binky" baz`
  - `just --dry-run write-hooks-schema`
  - `just --dry-run bazel-lock-update`
  - `just --dry-run argument-comment-lint-from-source -- "foo bar"`
  - `git diff --check -- justfile scripts/just-shell.py
  sdk/python/tests/test_artifact_workflow_and_binaries.py`
  - Verified Windows argv preservation through `scripts/just-shell.py`
  with arguments containing spaces.
  - `uv run --frozen --project sdk/python --extra dev pytest
  sdk/python/tests/test_artifact_workflow_and_binaries.py::test_root_fmt_recipe_formats_rust_and_python_sdk`

  iceweasel-oai · 2026-06-01 11:26:36 -07:00
  88c7a4ff07
• [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] Remove Python SDK beta warning note (#24870)

  ## Summary
  - Remove the beta warning callout from the PyPI-facing Python SDK
  README.
  - Keep the existing Beta title and install/usage guidance unchanged.
  
  ## Validation
  - Not run locally; relying on online CI for this documentation-only
  change.
  
  ## Release
  - Land this change before publishing the next Python SDK beta.

  Ahmed Ibrahim · 2026-05-27 23:13:48 -07:00
  3d9f58ace8
• [codex] Remove Python SDK language classifiers (#24868)

  ## Summary
  - Remove the Python language classifiers from the Python SDK package
  metadata.
  - Keep `requires-python = ">=3.10"` as the package's interpreter
  compatibility constraint.
  - Avoid presenting a curated version-support list in PyPI metadata.
  
  ## Validation
  - Not run locally; relying on online CI for this metadata-only change.
  
  ## Release
  - Land this change before publishing the next Python SDK beta.

  Ahmed Ibrahim · 2026-05-27 23:09:34 -07:00
  4a53b09eb7
• [codex] Simplify Python SDK install guidance (#24866)

  ## Summary
  - Remove the exact-version install snippet from the PyPI-facing Python
  SDK README.
  - Remove the release-selection explanation so the install section
  presents the standard `pip install openai-codex` path directly.
  
  ## Validation
  - Not run locally; relying on online CI for this documentation-only
  change.

  Ahmed Ibrahim · 2026-05-27 23:01:42 -07:00
  d0663f8004
• [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
• fix: uv lock (#22323)

  Update the lock of UV

  jif-oai · 2026-05-12 16:24:54 +02:00
  89c8e9a4db
• [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
• Revert "Publish Python runtime wheels on release" (#21810)

  Reverts openai/codex#21784

  Ahmed Ibrahim · 2026-05-08 22:37:10 +03:00
  cf941ede15
• Publish Python runtime wheels on release (#21784)

  ## Why
  
  Published Python SDK builds depend on an exact `openai-codex-cli-bin`
  runtime package, but the release workflow did not publish that runtime
  package to PyPI. That left the SDK packaging story incomplete: release
  artifacts could produce Codex binaries, but Python users still needed a
  matching wheel carrying the platform-specific runtime and helper
  executables.
  
  This PR is stacked on #21787 so release jobs can include helper binaries
  in runtime wheels: Linux wheels include `bwrap` for sandbox fallback,
  and Windows wheels include the signed sandbox/elevation helpers beside
  `codex.exe`.
  
  ## What changed
  
  - Builds platform-specific `openai-codex-cli-bin` wheels from signed
  release binaries on macOS, Linux, and Windows release runners.
  - Packages Linux `bwrap` into musllinux runtime wheels.
  - Packages Windows sandbox helper executables into Windows runtime
  wheels.
  - Uploads runtime wheels as GitHub release assets and publishes them to
  PyPI using trusted publishing from the `pypi` GitHub environment.
  - Keeps the new Python runtime publish job non-blocking so failures need
  follow-up but do not fail the Rust release workflow.
  - Pins the PyPA publish action to the `v1.13.0` commit SHA for
  reproducible release publishing.
  - Documents that runtime wheels are platform wheels published through
  PyPI trusted publishing.
  
  ## Testing
  
  - `ruby -e 'require "yaml"; ARGV.each { |f| YAML.load_file(f); puts "ok
  #{f}" }' .github/workflows/rust-release.yml
  .github/workflows/rust-release-windows.yml`
  - `git diff --check`
  
  CI is the real end-to-end verification for the release workflow path.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-05-08 22:00:58 +03:00
  9183503b97
• 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
• Harden package-manager install policy (#19163)

  ## Summary
  
  This PR hardens package-manager usage across the repo to reduce
  dependency supply-chain risk. It also removes the stale `codex-cli`
  Docker path, which was already broken on `main`, instead of keeping a
  bitrotted container workflow alive.
  
  ## What changed
  
  - Updated pnpm package manager pins and workspace install settings.
  - Removed stale `codex-cli` Docker assets instead of trying to keep a
  broken local container path alive.
  - Added uv settings and lockfiles for the Python SDK packages.
  - Updated Python SDK setup docs to use `uv sync`.
  
  ## Why
  
  This is primarily a security hardening change. It reduces
  package-install and supply-chain risk by ensuring dependency installs go
  through pinned package managers, committed lockfiles, release-age
  settings, and reviewed build-script controls.
  
  For `codex-cli`, the right follow-up was to remove the local Docker path
  rather than keep patching it:
  
  - `codex-cli/Dockerfile` installed `codex.tgz` with `npm install -g`,
  which bypassed the repo lockfile and age-gated pnpm settings.
  - The local `codex-cli/scripts/build_container.sh` helper was already
  broken on `main`: it called `pnpm run build`, but
  `codex-cli/package.json` does not define a `build` script.
  - The container path itself had bitrotted enough that keeping it would
  require extra packaging-specific behavior that was not otherwise needed
  by the repo.
  
  ## Gaps addressed
  
  - Global npm installs bypassed the repo lockfile in Docker and CLI
  reinstall paths, including `codex-cli/Dockerfile` and
  `codex-cli/bin/codex.js`.
  - CI and Docker pnpm installs used `--frozen-lockfile`, but the repo was
  missing stricter pnpm workspace settings for dependency build scripts.
  - Python SDK projects had `pyproject.toml` metadata but no committed
  `uv.lock` coverage or uv age/index settings in `sdk/python` and
  `sdk/python-runtime`.
  - The secure devcontainer install path used npm/global install behavior
  without a local locked package-manager boundary.
  - The local `codex-cli` Docker helper was already broken on `main`, so
  this PR removes that stale Docker path instead of preserving a broken
  surface.
  - pnpm was already pinned, but not to the current repo-wide pnpm version
  target.
  
  ## Verification
  
  - `pnpm install --frozen-lockfile`
  - `.devcontainer/codex-install`: `pnpm install --prod --frozen-lockfile`
  - `.devcontainer/codex-install`: `./node_modules/.bin/codex --version`
  - `sdk/python`: `uv lock --check`, `uv sync --locked --all-extras
  --dry-run`, `uv build`
  - `sdk/python-runtime`: `uv lock --check`, `uv sync --locked --dry-run`,
  `uv build --wheel`
  - `pnpm -r --filter ./sdk/typescript run build`
  - `pnpm -r --filter ./sdk/typescript run lint`
  - `pnpm -r --filter ./sdk/typescript run test`
  - `node --check codex-cli/bin/codex.js`
  - `docker build -f .devcontainer/Dockerfile.secure -t codex-secure-test
  .`
  - `cargo build -p codex-cli`
  - repo-wide package-manager audit

  mcgrew-oai · 2026-04-24 14:36:19 -04:00
  dee5f5ea38
• 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
• Add usage-based business plan types (#15934)

  ## Summary
  - add `self_serve_business_usage_based` and `enterprise_cbp_usage_based`
  to the public/internal plan enums and regenerate the app-server + Python
  SDK artifacts
  - map both plans through JWT login and backend rate-limit payloads, then
  bucket them with the existing Team/Business entitlement behavior in
  cloud requirements, usage-limit copy, tooltips, and status display
  - keep the earlier display-label remap commit on this branch so the new
  Team-like and Business-like plans render consistently in the UI
  
  ## Testing
  - `just write-app-server-schema`
  - `uv run --project sdk/python python
  sdk/python/scripts/update_sdk_artifacts.py generate-types`
  - `just fix -p codex-protocol -p codex-login -p codex-core -p
  codex-backend-client -p codex-cloud-requirements -p codex-tui -p
  codex-tui-app-server -p codex-backend-openapi-models`
  - `just fmt`
  - `just argument-comment-lint`
  - `cargo test -p codex-protocol
  usage_based_plan_types_use_expected_wire_names`
  - `cargo test -p codex-login usage_based`
  - `cargo test -p codex-backend-client usage_based`
  - `cargo test -p codex-cloud-requirements usage_based`
  - `cargo test -p codex-core usage_limit_reached_error_formats_`
  - `cargo test -p codex-tui plan_type_display_name_remaps_display_labels`
  - `cargo test -p codex-tui remapped`
  - `cargo test -p codex-tui-app-server
  plan_type_display_name_remaps_display_labels`
  - `cargo test -p codex-tui-app-server remapped`
  - `cargo test -p codex-tui-app-server
  preserves_usage_based_plan_type_wire_name`
  
  ## Notes
  - a broader multi-crate `cargo test` run still hits unrelated existing
  guardian-approval config failures in
  `codex-rs/core/src/config/config_tests.rs`

  bwanner-oai · 2026-03-27 14:25:13 -07:00
  82e8031338
• 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
• Pin Python SDK app-server stdio to UTF-8 on Windows (#15244)

  ## TL;DR
  Pin the Python app-server SDK subprocess pipes to UTF-8 so Windows users
  on non-UTF-8 locales do not hit `UnicodeDecodeError` when the `codex`
  child emits UTF-8 text.
  
  - add `encoding="utf-8"` to the `subprocess.Popen(...)` call in
  `AppServerClient.start()`
  - add a focused regression test that asserts the client launches the
  subprocess with UTF-8 text I/O
  - validates with `python -m pytest
  sdk/python/tests/test_client_rpc_methods.py
  sdk/python/tests/test_client_process_launch.py
  sdk/python/tests/test_public_api_runtime_behavior.py`
  
  Fixes #14311.

  Shaqayeq · 2026-03-20 18:26:24 +00:00
  9e31aeadce
• 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