sdk/python: split core and bundled packages

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,16 @@ 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 \
+  --skip-generate-types \
+  --sdk-version 1.2.3
 python scripts/update_sdk_artifacts.py \
   stage-sdk \
   /tmp/codex-python-release/codex-app-server-sdk \
+  --skip-generate-types \
+  --sdk-version 1.2.3 \
   --runtime-version 1.2.3
 python scripts/update_sdk_artifacts.py \
   stage-runtime \
@@ -75,17 +89,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