Publish codex app-server Python SDK core and bundled packages

.github/workflows/rust-release-windows.yml

@@ -181,6 +181,41 @@ jobs:
           account-name: ${{ secrets.AZURE_TRUSTED_SIGNING_ACCOUNT_NAME }}
           certificate-profile-name: ${{ secrets.AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME }}
 
+      - name: Setup Python for runtime packaging
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Build Python runtime wheel
+        shell: bash
+        working-directory: ${{ github.workspace }}
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+          TARGET: ${{ matrix.target }}
+        run: |
+          set -euo pipefail
+
+          version="${RELEASE_TAG#rust-v}"
+          staging_dir="${RUNNER_TEMP}/codex-cli-bin-${TARGET}"
+          out_dir="${GITHUB_WORKSPACE}/dist-python/${TARGET}"
+
+          python -m pip install --upgrade pip
+          python -m pip install build hatchling
+
+          python sdk/python/scripts/update_sdk_artifacts.py \
+            stage-runtime \
+            "${staging_dir}" \
+            "codex-rs/target/${TARGET}/release/codex.exe" \
+            --runtime-version "${version}"
+
+          python -m build --wheel --outdir "${out_dir}" "${staging_dir}"
+
+      - name: Upload Python runtime wheel
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-runtime-${{ matrix.target }}
+          path: dist-python/${{ matrix.target }}/*
+
       - name: Stage artifacts
         shell: bash
         run: |

.github/workflows/rust-release.yml

@@ -302,6 +302,41 @@ jobs:
           apple-notarization-key-id: ${{ secrets.APPLE_NOTARIZATION_KEY_ID }}
           apple-notarization-issuer-id: ${{ secrets.APPLE_NOTARIZATION_ISSUER_ID }}
 
+      - name: Setup Python for runtime packaging
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Build Python runtime wheel
+        shell: bash
+        working-directory: ${{ github.workspace }}
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+          TARGET: ${{ matrix.target }}
+        run: |
+          set -euo pipefail
+
+          version="${RELEASE_TAG#rust-v}"
+          staging_dir="${RUNNER_TEMP}/codex-cli-bin-${TARGET}"
+          out_dir="${GITHUB_WORKSPACE}/dist-python/${TARGET}"
+
+          python -m pip install --upgrade pip
+          python -m pip install build hatchling
+
+          python sdk/python/scripts/update_sdk_artifacts.py \
+            stage-runtime \
+            "${staging_dir}" \
+            "codex-rs/target/${TARGET}/release/codex" \
+            --runtime-version "${version}"
+
+          python -m build --wheel --outdir "${out_dir}" "${staging_dir}"
+
+      - name: Upload Python runtime wheel
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-runtime-${{ matrix.target }}
+          path: dist-python/${{ matrix.target }}/*
+
       - name: Stage artifacts
         shell: bash
         run: |
@@ -384,6 +419,7 @@ jobs:
     needs:
       - build
       - build-windows
+      - build-python-sdk
       - shell-tool-mcp
     name: release
     runs-on: ubuntu-latest
@@ -533,6 +569,190 @@ jobs:
             exit 1
           fi
 
+  build-python-sdk:
+    name: build-python-sdk
+    needs:
+      - tag-check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Build Python SDK artifacts
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+
+          version="${RELEASE_TAG#rust-v}"
+          core_staging_dir="${RUNNER_TEMP}/codex-app-server-sdk-core"
+          core_out_dir="${GITHUB_WORKSPACE}/dist-python/sdk-core"
+          bundled_staging_dir="${RUNNER_TEMP}/codex-app-server-sdk"
+          bundled_out_dir="${GITHUB_WORKSPACE}/dist-python/sdk"
+
+          python -m pip install --upgrade pip
+          python -m pip install \
+            build \
+            hatchling \
+            "datamodel-code-generator==0.31.2" \
+            "ruff==0.11.13"
+
+          python sdk/python/scripts/update_sdk_artifacts.py generate-types
+
+          python sdk/python/scripts/update_sdk_artifacts.py \
+            stage-sdk-core \
+            "${core_staging_dir}" \
+            --sdk-version "${version}"
+
+          python -m build --outdir "${core_out_dir}" "${core_staging_dir}"
+
+          python sdk/python/scripts/update_sdk_artifacts.py \
+            stage-sdk \
+            "${bundled_staging_dir}" \
+            --sdk-version "${version}" \
+            --runtime-version "${version}"
+
+          python -m build --outdir "${bundled_out_dir}" "${bundled_staging_dir}"
+
+      - name: Upload Python core SDK artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-sdk-core
+          path: dist-python/sdk-core/*
+
+      - name: Upload Python SDK artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-sdk
+          path: dist-python/sdk/*
+
+  publish-pypi-runtime:
+    name: publish-pypi-runtime
+    needs:
+      - build
+      - build-windows
+      - release
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    environment:
+      name: pypi
+
+    steps:
+      # Do not publish musl runtime wheels to PyPI yet. GNU and musl builds for
+      # the same architecture currently infer the same wheel tag, which can make
+      # the published Linux runtime nondeterministic.
+      - name: Download macOS arm64 runtime wheel
+        uses: actions/download-artifact@v8
+        with:
+          name: python-runtime-aarch64-apple-darwin
+          path: dist-pypi/runtime
+
+      - name: Download macOS x64 runtime wheel
+        uses: actions/download-artifact@v8
+        with:
+          name: python-runtime-x86_64-apple-darwin
+          path: dist-pypi/runtime
+
+      - name: Download Linux GNU arm64 runtime wheel
+        uses: actions/download-artifact@v8
+        with:
+          name: python-runtime-aarch64-unknown-linux-gnu
+          path: dist-pypi/runtime
+
+      - name: Download Linux GNU x64 runtime wheel
+        uses: actions/download-artifact@v8
+        with:
+          name: python-runtime-x86_64-unknown-linux-gnu
+          path: dist-pypi/runtime
+
+      - name: Download Windows arm64 runtime wheel
+        uses: actions/download-artifact@v8
+        with:
+          name: python-runtime-aarch64-pc-windows-msvc
+          path: dist-pypi/runtime
+
+      - name: Download Windows x64 runtime wheel
+        uses: actions/download-artifact@v8
+        with:
+          name: python-runtime-x86_64-pc-windows-msvc
+          path: dist-pypi/runtime
+
+      - name: List runtime wheels
+        shell: bash
+        run: ls -R dist-pypi/runtime
+
+      - name: Publish Python runtime wheels to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist-pypi/runtime/
+
+  publish-pypi-sdk-core:
+    name: publish-pypi-sdk-core
+    needs:
+      - build-python-sdk
+      - publish-pypi-runtime
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    environment:
+      name: pypi
+
+    steps:
+      - name: Download Python core SDK artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: python-sdk-core
+          path: dist-pypi/sdk-core
+
+      - name: List core SDK artifacts
+        shell: bash
+        run: ls -R dist-pypi/sdk-core
+
+      - name: Publish Python core SDK to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist-pypi/sdk-core/
+
+  publish-pypi-sdk:
+    name: publish-pypi-sdk
+    needs:
+      - build-python-sdk
+      - publish-pypi-sdk-core
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    environment:
+      name: pypi
+
+    steps:
+      - name: Download bundled Python SDK artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: python-sdk
+          path: dist-pypi/sdk
+
+      - name: List bundled SDK artifacts
+        shell: bash
+        run: ls -R dist-pypi/sdk
+
+      - name: Publish bundled Python SDK to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist-pypi/sdk/
+
   # Publish to npm using OIDC authentication.
   # July 31, 2025: https://github.blog/changelog/2025-07-31-npm-trusted-publishing-with-oidc-is-generally-available/
   # npm docs: https://docs.npmjs.com/trusted-publishers

sdk/python/README.md

@@ -11,9 +11,16 @@ cd sdk/python
 python -m pip install -e .
 ```
 
-Published SDK builds pin an exact `codex-cli-bin` runtime dependency. For local
-repo development, pass `AppServerConfig(codex_bin=...)` to point at a local
-build explicitly.
+This checked-in package is the runtime-free core distribution:
+`codex-app-server-sdk-core`.
+
+Published releases expose two Python package names:
+
+- `codex-app-server-sdk-core`: the actual Python SDK code, without bundled binaries
+- `codex-app-server-sdk`: a bundled metapackage that depends on `codex-app-server-sdk-core` and `codex-cli-bin`
+
+For local repo development, pass `AppServerConfig(codex_bin=...)` to point at
+a local build explicitly.
 
 ## Quickstart
 
@@ -48,9 +55,9 @@ python examples/01_quickstart_constructor/async.py
 
 The repo no longer checks `codex` binaries into `sdk/python`.
 
-Published SDK builds are pinned to an exact `codex-cli-bin` package version,
-and that runtime package carries the platform-specific binary for the target
-wheel.
+Published `codex-app-server-sdk` builds depend on an exact
+`codex-app-server-sdk-core` version plus an exact `codex-cli-bin` version, and
+that runtime package carries the platform-specific binary for the target wheel.
 
 For local repo development, the checked-in `sdk/python-runtime` package is only
 a template for staged release artifacts. Editable installs should use an
@@ -61,9 +68,14 @@ explicit `codex_bin` override instead.
 ```bash
 cd sdk/python
 python scripts/update_sdk_artifacts.py generate-types
+python scripts/update_sdk_artifacts.py \
+  stage-sdk-core \
+  /tmp/codex-python-release/codex-app-server-sdk-core \
+  --sdk-version 1.2.3
 python scripts/update_sdk_artifacts.py \
   stage-sdk \
   /tmp/codex-python-release/codex-app-server-sdk \
+  --sdk-version 1.2.3 \
   --runtime-version 1.2.3
 python scripts/update_sdk_artifacts.py \
   stage-runtime \
@@ -75,17 +87,22 @@ python scripts/update_sdk_artifacts.py \
 This supports the CI release flow:
 
 - run `generate-types` before packaging
-- stage `codex-app-server-sdk` once with an exact `codex-cli-bin==...` dependency
+- stage `codex-app-server-sdk-core` with the release tag version as `--sdk-version`
+- stage `codex-app-server-sdk` as a bundled metapackage pinned to exact `codex-app-server-sdk-core==...` and `codex-cli-bin==...`
 - stage `codex-cli-bin` on each supported platform runner with the same pinned runtime version
 - build and publish `codex-cli-bin` as platform wheels only; do not publish an sdist
+- publish `codex-app-server-sdk-core` to PyPI after the runtime wheels land
+- publish `codex-app-server-sdk` to PyPI last, using the same release version
 
 ## Compatibility and versioning
 
-- Package: `codex-app-server-sdk`
+- Core package: `codex-app-server-sdk-core`
+- Bundled package: `codex-app-server-sdk`
 - Runtime package: `codex-cli-bin`
 - Current SDK version in this repo: `0.2.0`
 - Python: `>=3.10`
 - Target protocol: Codex `app-server` JSON-RPC v2
+- Release policy: published Python package versions should match the `rust-v...` release tag
 - Recommendation: keep SDK and `codex` CLI reasonably up to date together
 
 ## Notes

sdk/python/docs/faq.md

@@ -38,16 +38,23 @@ Common causes:
 - local auth/session is missing
 - incompatible/old app-server
 
-Maintainers stage releases by building the SDK once and the runtime once per
-platform with the same pinned runtime version. Publish `codex-cli-bin` as
-platform wheels only; do not publish an sdist:
+Maintainers stage releases by building the core SDK once, the bundled SDK
+metapackage once, and the runtime once per platform with the same pinned
+runtime version. Publish `codex-cli-bin` as platform wheels only; do not
+publish an sdist. Published Python package versions should match the
+`rust-v...` release tag:
 
 ```bash
 cd sdk/python
 python scripts/update_sdk_artifacts.py generate-types
+python scripts/update_sdk_artifacts.py \
+  stage-sdk-core \
+  /tmp/codex-python-release/codex-app-server-sdk-core \
+  --sdk-version 1.2.3
 python scripts/update_sdk_artifacts.py \
   stage-sdk \
   /tmp/codex-python-release/codex-app-server-sdk \
+  --sdk-version 1.2.3 \
   --runtime-version 1.2.3
 python scripts/update_sdk_artifacts.py \
   stage-runtime \

sdk/python/pyproject.toml

@@ -3,9 +3,9 @@ requires = ["hatchling>=1.24.0"]
 build-backend = "hatchling.build"
 
 [project]
-name = "codex-app-server-sdk"
+name = "codex-app-server-sdk-core"
 version = "0.2.0"
-description = "Python SDK for Codex app-server v2"
+description = "Core Python SDK for Codex app-server v2"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "Apache-2.0" }