mirror of
https://github.com/openai/codex.git
synced 2026-05-04 19:36:45 +00:00
dee5f5ea38
## 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
105 lines
3.4 KiB
Markdown
105 lines
3.4 KiB
Markdown
# Codex App Server Python SDK (Experimental)
|
||
|
||
Experimental Python SDK for `codex app-server` JSON-RPC v2 over stdio, with a small default surface optimized for real scripts and apps.
|
||
|
||
The generated wire-model layer is currently sourced from the bundled v2 schema and exposed as Pydantic models with snake_case Python fields that serialize back to the app-server’s camelCase wire format.
|
||
|
||
## Install
|
||
|
||
```bash
|
||
cd sdk/python
|
||
uv sync
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
Published SDK builds pin an exact `openai-codex-cli-bin` runtime dependency. For local
|
||
repo development, either pass `AppServerConfig(codex_bin=...)` to point at a
|
||
local build explicitly, or use the repo examples/notebook bootstrap which
|
||
installs the pinned runtime package automatically.
|
||
|
||
## Quickstart
|
||
|
||
```python
|
||
from codex_app_server import Codex
|
||
|
||
with Codex() as codex:
|
||
thread = codex.thread_start(model="gpt-5")
|
||
result = thread.run("Say hello in one sentence.")
|
||
print(result.final_response)
|
||
print(len(result.items))
|
||
```
|
||
|
||
`result.final_response` is `None` when the turn completes without a final-answer
|
||
or phase-less assistant message item.
|
||
|
||
## Docs map
|
||
|
||
- Golden path tutorial: `docs/getting-started.md`
|
||
- API reference (signatures + behavior): `docs/api-reference.md`
|
||
- Common decisions and pitfalls: `docs/faq.md`
|
||
- Runnable examples index: `examples/README.md`
|
||
- Jupyter walkthrough notebook: `notebooks/sdk_walkthrough.ipynb`
|
||
|
||
## Examples
|
||
|
||
Start here:
|
||
|
||
```bash
|
||
cd sdk/python
|
||
python examples/01_quickstart_constructor/sync.py
|
||
python examples/01_quickstart_constructor/async.py
|
||
```
|
||
|
||
## Runtime packaging
|
||
|
||
The repo no longer checks `codex` binaries into `sdk/python`.
|
||
|
||
Published SDK builds are pinned to an exact `openai-codex-cli-bin` package 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
|
||
explicit `codex_bin` override for manual SDK usage; the repo examples and
|
||
notebook bootstrap the pinned runtime package automatically.
|
||
|
||
## Maintainer workflow
|
||
|
||
```bash
|
||
cd sdk/python
|
||
python scripts/update_sdk_artifacts.py generate-types
|
||
python scripts/update_sdk_artifacts.py \
|
||
stage-sdk \
|
||
/tmp/codex-python-release/codex-app-server-sdk \
|
||
--runtime-version 1.2.3
|
||
python scripts/update_sdk_artifacts.py \
|
||
stage-runtime \
|
||
/tmp/codex-python-release/openai-codex-cli-bin \
|
||
/path/to/codex \
|
||
--runtime-version 1.2.3
|
||
```
|
||
|
||
This supports the CI release flow:
|
||
|
||
- run `generate-types` before packaging
|
||
- stage `codex-app-server-sdk` once with an exact `openai-codex-cli-bin==...` dependency
|
||
- stage `openai-codex-cli-bin` on each supported platform runner with the same pinned runtime version
|
||
- build and publish `openai-codex-cli-bin` as platform wheels only; do not publish an sdist
|
||
|
||
## Compatibility and versioning
|
||
|
||
- Package: `codex-app-server-sdk`
|
||
- Runtime package: `openai-codex-cli-bin`
|
||
- Current SDK version in this repo: `0.2.0`
|
||
- Python: `>=3.10`
|
||
- Target protocol: Codex `app-server` JSON-RPC v2
|
||
- Recommendation: keep SDK and `codex` CLI reasonably up to date together
|
||
|
||
## Notes
|
||
|
||
- `Codex()` is eager and performs startup + `initialize` in the constructor.
|
||
- Use context managers (`with Codex() as codex:`) to ensure shutdown.
|
||
- Prefer `thread.run("...")` for the common case. Use `thread.turn(...)` when
|
||
you need streaming, steering, or interrupt control.
|
||
- For transient overload, use `codex_app_server.retry.retry_on_overload`.
|