External SDKs
Overview
The sdk/** tree ships external SDK surfaces for Codex in TypeScript and Python, plus a Python runtime wheel that carries the pinned Codex CLI binary. The two SDKs expose different transport layers:
- sdk/…/index.ts exports the TypeScript public API:
Codex,Thread, event and item unions, and option types. sdk/…/codex.ts is a small facade that creates or resumesThreadinstances. - sdk/…/thread.ts implements
run()andrunStreamed(). It normalizes string or structured text/local-image input, writes turn output schemas through sdk/…/outputSchemaFile.ts, invokesCodexExec, parses JSONL events, stores the thread id fromthread.started, and collects final results fromitem.completedandturn.completedevents. - sdk/…/exec.ts is the TypeScript runtime bridge. It resolves the installed
@openai/codexplatform package, finds the nativecodexbinary under package-layout or legacy vendor paths, prepends bundledcodex-pathdirectories toPATH, then spawnscodex exec --experimental-jsonwith CLI flags derived fromCodexOptions,ThreadOptions, andTurnOptions. sdk/…/events.ts and sdk/…/items.ts are hand-written protocol types based on codex-rs/…/exec_events.rs, not generated files. - sdk/…/__init__.py exports the Python public API: sync/async high-level clients, thread and turn handles, input dataclasses, sandbox and approval enums, low-level config, errors, and retry helpers. sdk/…/api.py is the high-level sync/async facade over the app-server protocol, with generated public method blocks for thread lifecycle and turn options.
- sdk/…/client.py is the synchronous JSON-RPC transport for
codex app-server --listen stdio://. It resolves the binary either fromCodexConfig.codex_binor theopenai-codex-cli-binruntime package, starts the process, sends newline-delimited JSON-RPC requests, handles server-to-client approval requests, drains stderr for transport errors, and exposes typed methods such asthread/start,turn/start,account/login/start,model/list, and goal operations. - sdk/…/async_client.py wraps the synchronous client with
asyncio.to_thread, a bounded turn-start executor, and cancellation cleanup so async API users do not block the event loop while the single stdio transport remains owned by the sync client. - sdk/…/_message_router.py is the Python SDK's central demultiplexer. The reader thread is the only stdout consumer; it routes JSON-RPC responses by id, login notifications by login id, turn notifications by turn id, global notifications, and logical goal-operation notifications.
- sdk/…/v2_all.py and sdk/…/notification_registry.py are checked-in generated protocol artifacts for the Rust app-server protocol. sdk/…/pyproject.toml points codegen at
../../codex-rs/app-server-protocol/schema/json, and sdk/…/update_sdk_artifacts.py normalizes those schemas, runsdatamodel-code-generator, builds notification routing metadata, regenerates public API blocks in api.py, and stages release artifacts. - sdk/…/__init__.py exposes
bundled_codex_path(),bundled_package_dir(), andbundled_path_dir()for the runtime package. sdk/…/pyproject.toml includes the packagedbin/**,codex-resources/**, andcodex-path/**; sdk/…/hatch_build.py marks wheels as platform-specific and rejects source distributions.
Python input and behavior helpers sit beside the clients: sdk/…/_inputs.py maps public TextInput, ImageInput, LocalImageInput, SkillInput, MentionInput, and ExternalMessage into app-server wire input/tool-output payloads; _approval_mode.py and _sandbox.py translate public enums into generated protocol values; _login.py wraps browser and device-code login flows; _goal.py coalesces runtime-generated physical goal turns into one logical turn stream; _run.py collects streamed turn notifications into a TurnResult; _runtime_requirements.py gates newer SDK fields against a minimum CLI version or an unversioned checkout's generated schemas; errors.py maps JSON-RPC errors into typed SDK exceptions; models.py and types.py provide stable public model exports around generated protocol types.
Build and release tooling is split by package. sdk/…/package.json, sdk/…/tsup.config.ts, sdk/…/tsconfig.json, sdk/…/jest.config.cjs, sdk/…/eslint.config.js, .prettierrc, and .prettierignore define an ESM Node 18 package built by tsup, tested by Jest/ts-jest, and linted/formatted with ESLint and Prettier. sdk/…/pyproject.toml, sdk/…/uv.lock, sdk/python/BUILD.bazel, sdk/…/release_version.py, and sdk/…/_runtime_setup.py define the Python SDK package, pinned dependency on openai-codex-cli-bin, schema export integration, version normalization, and local runtime bootstrapping from GitHub release assets. sdk/…/pyproject.toml, sdk/…/uv.lock, sdk/…/hatch_build.py, and sdk/…/README.md define the wheel-only runtime package.
Tests and examples are part of the shipped SDK area. sdk/typescript/tests/** covers spawn argument construction, output schema forwarding, abort behavior, MCP conformance gates, and mock Responses API flows; sdk/typescript/samples/** and sdk/…/README.md demonstrate streaming and structured output. sdk/python/tests/** covers generated-contract drift, public signatures, runtime package staging, app-server integration, notification routing, async behavior, approvals, login, inputs, streaming, and goal operations; sdk/python/examples/**, sdk/python/docs/**, sdk/python/notebooks/sdk_walkthrough.ipynb, sdk/…/README.md, and sdk/…/RELEASING.md are user-facing examples, docs, walkthroughs, and release notes for the Python SDK.
Path routing under sdk/** should be assigned as follows: sdk/typescript/src/** is TypeScript SDK runtime and API code; sdk/typescript/tests/** is TypeScript SDK validation; sdk/typescript/samples/** plus TypeScript README/config files are TypeScript package docs and tooling; sdk/python/src/openai_codex/** is Python SDK runtime, generated protocol, and API code; sdk/python/scripts/**, sdk/python/BUILD.bazel, sdk/…/pyproject.toml, sdk/…/uv.lock, sdk/…/release_version.py, and sdk/…/_runtime_setup.py are Python SDK generation/build/release tooling; sdk/python/tests/** is Python SDK validation; sdk/python/examples/**, sdk/python/docs/**, sdk/python/notebooks/**, sdk/…/README.md, and sdk/…/RELEASING.md are Python SDK user docs/examples; sdk/python-runtime/** is the separate runtime-binary package consumed by the Python SDK.
Coupling
- If codex-rs/…/exec_events.rs changes, update sdk/…/events.ts, sdk/…/items.ts, and the JSONL parsing/collection assumptions in sdk/…/thread.ts; the TypeScript SDK types are hand-maintained and will not follow Rust event changes automatically.
- If Rust app-server protocol schemas change under
codex-rs/app-server-protocol/schema/json, regenerate and review sdk/…/v2_all.py, sdk/…/notification_registry.py, and the generated blocks in sdk/…/api.py through sdk/…/update_sdk_artifacts.py; sdk/…/test_contract_generation.py treats checked-in drift as a failure. - If new app-server notification payloads carry
turnId,turn,threadId, orloginIddifferently, verify sdk/…/update_sdk_artifacts.py emits correct registry metadata and update fallback extraction in sdk/…/_message_router.py; otherwise turn/login streams can block or receive unrelated events. - If a new public Python turn or thread option is added in sdk/…/update_sdk_artifacts.py, also check sdk/…/_runtime_requirements.py; sdk/…/client.py explicitly gates newer fields such as
toolOutput,turnTrigger,serviceTierForTurn, andexcludeTurnsagainst runtime support. - If the packaged CLI layout changes, update both runtime resolvers: TypeScript binary discovery in sdk/…/exec.ts and Python runtime packaging/resolution in sdk/…/__init__.py, sdk/…/update_sdk_artifacts.py, and sdk/…/client.py.
Risks
- sdk/…/_message_router.py, sdk/…/client.py, and sdk/…/async_client.py depend on one reader thread owning stdout and on per-turn subscriptions being closed on completion or cancellation. If another consumer reads stdout or a cancellation path fails to close its subscription, JSON-RPC calls can hang or future turn notifications can be misrouted.
- sdk/…/update_sdk_artifacts.py contains many schema normalization patches before generation. If a Rust schema shape changes in a way those patches do not recognize, the generated Python API may still build but lose public compatibility; sdk/…/test_contract_generation.py and sdk/…/test_public_api_signatures.py are the review gates for this.
- sdk/…/exec.ts serializes structured
CodexOptions.configby flattening dotted keys and appending raw and SDK-managed--configoverrides in order. If precedence changes, callers can silently run with the wrong approval, sandbox, web-search, or base-url settings; sdk/…/exec.test.ts and sdk/…/run.test.ts assert the current ordering.