Add Python SDK public API and examples

Co-authored-by: Codex <noreply@openai.com>

sdk/python-runtime/README.md

@@ -0,0 +1,9 @@
+# Codex CLI Runtime for Python SDK
+
+Platform-specific runtime package consumed by the published `codex-app-server-sdk`.
+
+This package is staged during release so the SDK can pin an exact Codex CLI
+version without checking platform binaries into the repo.
+
+`codex-cli-bin` is intentionally wheel-only. Do not build or publish an sdist
+for this package.

sdk/python-runtime/hatch_build.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class RuntimeBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict[str, object]) -> None:
+        del version
+        if self.target_name == "sdist":
+            raise RuntimeError(
+                "codex-cli-bin is wheel-only; build and publish platform wheels only."
+            )
+
+        build_data["pure_python"] = False
+        build_data["infer_tag"] = True

sdk/python-runtime/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codex-cli-bin"
+version = "0.0.0-dev"
+description = "Pinned Codex CLI runtime for the Python SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "OpenAI" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/openai/codex"
+Repository = "https://github.com/openai/codex"
+Issues = "https://github.com/openai/codex/issues"
+
+[tool.hatch.build]
+exclude = [
+  ".venv/**",
+  ".pytest_cache/**",
+  "dist/**",
+  "build/**",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codex_cli_bin"]
+include = ["src/codex_cli_bin/bin/**"]
+
+[tool.hatch.build.targets.wheel.hooks.custom]
+
+[tool.hatch.build.targets.sdist]
+
+[tool.hatch.build.targets.sdist.hooks.custom]

sdk/python-runtime/src/codex_cli_bin/__init__.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+PACKAGE_NAME = "codex-cli-bin"
+
+
+def bundled_codex_path() -> Path:
+    exe = "codex.exe" if os.name == "nt" else "codex"
+    path = Path(__file__).resolve().parent / "bin" / exe
+    if not path.is_file():
+        raise FileNotFoundError(
+            f"{PACKAGE_NAME} is installed but missing its packaged codex binary at {path}"
+        )
+    return path
+
+
+__all__ = ["PACKAGE_NAME", "bundled_codex_path"]

sdk/python/README.md

@@ -0,0 +1,95 @@
+# 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
+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.
+
+## Quickstart
+
+```python
+from codex_app_server import Codex, TextInput
+
+with Codex() as codex:
+    thread = codex.thread_start(model="gpt-5")
+    result = thread.turn(TextInput("Say hello in one sentence.")).run()
+    print(result.text)
+```
+
+## 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 `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 instead.
+
+## 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/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 `codex-cli-bin==...` dependency
+- 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
+
+## Compatibility and versioning
+
+- 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
+- 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.
+- For transient overload, use `codex_app_server.retry.retry_on_overload`.

sdk/python/docs/api-reference.md

@@ -0,0 +1,180 @@
+# Codex App Server SDK — API Reference
+
+Public surface of `codex_app_server` for app-server v2.
+
+This SDK surface is experimental. The current implementation intentionally allows only one active `Turn.stream()` or `Turn.run()` consumer per client instance at a time.
+
+## Package Entry
+
+```python
+from codex_app_server import (
+    Codex,
+    AsyncCodex,
+    Thread,
+    AsyncThread,
+    Turn,
+    AsyncTurn,
+    TurnResult,
+    InitializeResult,
+    Input,
+    InputItem,
+    TextInput,
+    ImageInput,
+    LocalImageInput,
+    SkillInput,
+    MentionInput,
+    ThreadItem,
+    TurnStatus,
+)
+```
+
+- Version: `codex_app_server.__version__`
+- Requires Python >= 3.10
+
+## Codex (sync)
+
+```python
+Codex(config: AppServerConfig | None = None)
+```
+
+Properties/methods:
+
+- `metadata -> InitializeResult`
+- `close() -> None`
+- `thread_start(*, approval_policy=None, base_instructions=None, config=None, cwd=None, developer_instructions=None, ephemeral=None, model=None, model_provider=None, personality=None, sandbox=None) -> Thread`
+- `thread_list(*, archived=None, cursor=None, cwd=None, limit=None, model_providers=None, sort_key=None, source_kinds=None) -> ThreadListResponse`
+- `thread_resume(thread_id: str, *, approval_policy=None, base_instructions=None, config=None, cwd=None, developer_instructions=None, model=None, model_provider=None, personality=None, sandbox=None) -> Thread`
+- `thread_fork(thread_id: str, *, approval_policy=None, base_instructions=None, config=None, cwd=None, developer_instructions=None, model=None, model_provider=None, sandbox=None) -> Thread`
+- `thread_archive(thread_id: str) -> ThreadArchiveResponse`
+- `thread_unarchive(thread_id: str) -> Thread`
+- `models(*, include_hidden: bool = False) -> ModelListResponse`
+
+Context manager:
+
+```python
+with Codex() as codex:
+    ...
+```
+
+## AsyncCodex (async parity)
+
+```python
+AsyncCodex(config: AppServerConfig | None = None)
+```
+
+Properties/methods:
+
+- `metadata -> InitializeResult`
+- `close() -> Awaitable[None]`
+- `thread_start(*, approval_policy=None, base_instructions=None, config=None, cwd=None, developer_instructions=None, ephemeral=None, model=None, model_provider=None, personality=None, sandbox=None) -> Awaitable[AsyncThread]`
+- `thread_list(*, archived=None, cursor=None, cwd=None, limit=None, model_providers=None, sort_key=None, source_kinds=None) -> Awaitable[ThreadListResponse]`
+- `thread_resume(thread_id: str, *, approval_policy=None, base_instructions=None, config=None, cwd=None, developer_instructions=None, model=None, model_provider=None, personality=None, sandbox=None) -> Awaitable[AsyncThread]`
+- `thread_fork(thread_id: str, *, approval_policy=None, base_instructions=None, config=None, cwd=None, developer_instructions=None, model=None, model_provider=None, sandbox=None) -> Awaitable[AsyncThread]`
+- `thread_archive(thread_id: str) -> Awaitable[ThreadArchiveResponse]`
+- `thread_unarchive(thread_id: str) -> Awaitable[AsyncThread]`
+- `models(*, include_hidden: bool = False) -> Awaitable[ModelListResponse]`
+
+Async context manager:
+
+```python
+async with AsyncCodex() as codex:
+    ...
+```
+
+## Thread / AsyncThread
+
+`Thread` and `AsyncThread` share the same shape and intent.
+
+### Thread
+
+- `turn(input: Input, *, approval_policy=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, summary=None) -> Turn`
+- `read(*, include_turns: bool = False) -> ThreadReadResponse`
+- `set_name(name: str) -> ThreadSetNameResponse`
+- `compact() -> ThreadCompactStartResponse`
+
+### AsyncThread
+
+- `turn(input: Input, *, approval_policy=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox_policy=None, summary=None) -> Awaitable[AsyncTurn]`
+- `read(*, include_turns: bool = False) -> Awaitable[ThreadReadResponse]`
+- `set_name(name: str) -> Awaitable[ThreadSetNameResponse]`
+- `compact() -> Awaitable[ThreadCompactStartResponse]`
+
+## Turn / AsyncTurn
+
+### Turn
+
+- `steer(input: Input) -> TurnSteerResponse`
+- `interrupt() -> TurnInterruptResponse`
+- `stream() -> Iterator[Notification]`
+- `run() -> TurnResult`
+
+Behavior notes:
+
+- `stream()` and `run()` are exclusive per client instance in the current experimental build
+- starting a second turn consumer on the same `Codex` instance raises `RuntimeError`
+
+### AsyncTurn
+
+- `steer(input: Input) -> Awaitable[TurnSteerResponse]`
+- `interrupt() -> Awaitable[TurnInterruptResponse]`
+- `stream() -> AsyncIterator[Notification]`
+- `run() -> Awaitable[TurnResult]`
+
+Behavior notes:
+
+- `stream()` and `run()` are exclusive per client instance in the current experimental build
+- starting a second turn consumer on the same `AsyncCodex` instance raises `RuntimeError`
+
+## TurnResult
+
+```python
+@dataclass
+class TurnResult:
+    thread_id: str
+    turn_id: str
+    status: TurnStatus
+    error: TurnError | None
+    text: str
+    items: list[ThreadItem]
+    usage: ThreadTokenUsageUpdatedNotification | None
+```
+
+## Inputs
+
+```python
+@dataclass class TextInput: text: str
+@dataclass class ImageInput: url: str
+@dataclass class LocalImageInput: path: str
+@dataclass class SkillInput: name: str; path: str
+@dataclass class MentionInput: name: str; path: str
+
+InputItem = TextInput | ImageInput | LocalImageInput | SkillInput | MentionInput
+Input = list[InputItem] | InputItem
+```
+
+## Retry + errors
+
+```python
+from codex_app_server import (
+    retry_on_overload,
+    JsonRpcError,
+    MethodNotFoundError,
+    InvalidParamsError,
+    ServerBusyError,
+    is_retryable_error,
+)
+```
+
+- `retry_on_overload(...)` retries transient overload errors with exponential backoff + jitter.
+- `is_retryable_error(exc)` checks if an exception is transient/overload-like.
+
+## Example
+
+```python
+from codex_app_server import Codex, TextInput
+
+with Codex() as codex:
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+    result = thread.turn(TextInput("Say hello in one sentence.")).run()
+    print(result.text)
+```

sdk/python/docs/faq.md

@@ -0,0 +1,95 @@
+# FAQ
+
+## Thread vs turn
+
+- A `Thread` is conversation state.
+- A `Turn` is one model execution inside that thread.
+- Multi-turn chat means multiple turns on the same `Thread`.
+
+## `run()` vs `stream()`
+
+- `Turn.run()` / `AsyncTurn.run()` is the easiest path. It consumes events until completion and returns `TurnResult`.
+- `Turn.stream()` / `AsyncTurn.stream()` yields raw notifications (`Notification`) so you can react event-by-event.
+
+Choose `run()` for most apps. Choose `stream()` for progress UIs, custom timeout logic, or custom parsing.
+
+## Sync vs async clients
+
+- `Codex` is the sync public API.
+- `AsyncCodex` is an async replica of the same public API shape.
+
+If your app is not already async, stay with `Codex`.
+
+## Public kwargs are snake_case
+
+Public API keyword names are snake_case. The SDK still maps them to wire camelCase under the hood.
+
+If you are migrating older code, update these names:
+
+- `approvalPolicy` -> `approval_policy`
+- `baseInstructions` -> `base_instructions`
+- `developerInstructions` -> `developer_instructions`
+- `modelProvider` -> `model_provider`
+- `modelProviders` -> `model_providers`
+- `sortKey` -> `sort_key`
+- `sourceKinds` -> `source_kinds`
+- `outputSchema` -> `output_schema`
+- `sandboxPolicy` -> `sandbox_policy`
+
+## Why only `thread_start(...)` and `thread_resume(...)`?
+
+The public API keeps only explicit lifecycle calls:
+
+- `thread_start(...)` to create new threads
+- `thread_resume(thread_id, ...)` to continue existing threads
+
+This avoids duplicate ways to do the same operation and keeps behavior explicit.
+
+## Why does constructor fail?
+
+`Codex()` is eager: it starts transport and calls `initialize` in `__init__`.
+
+Common causes:
+
+- published runtime package (`codex-cli-bin`) is not installed
+- local `codex_bin` override points to a missing file
+- 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:
+
+```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/codex-cli-bin \
+  /path/to/codex \
+  --runtime-version 1.2.3
+```
+
+## Why does a turn "hang"?
+
+A turn is complete only when `turn/completed` arrives for that turn ID.
+
+- `run()` waits for this automatically.
+- With `stream()`, keep consuming notifications until completion.
+
+## How do I retry safely?
+
+Use `retry_on_overload(...)` for transient overload failures (`ServerBusyError`).
+
+Do not blindly retry all errors. For `InvalidParamsError` or `MethodNotFoundError`, fix inputs/version compatibility instead.
+
+## Common pitfalls
+
+- Starting a new thread for every prompt when you wanted continuity.
+- Forgetting to `close()` (or not using context managers).
+- Ignoring `TurnResult.status` and `TurnResult.error`.
+- Mixing SDK input classes with raw dicts incorrectly.

sdk/python/docs/getting-started.md

@@ -0,0 +1,96 @@
+# Getting Started
+
+This is the fastest path from install to a multi-turn thread using the public SDK surface.
+
+The SDK is experimental. Treat the API, bundled runtime strategy, and packaging details as unstable until the first public release.
+
+## 1) Install
+
+From repo root:
+
+```bash
+cd sdk/python
+python -m pip install -e .
+```
+
+Requirements:
+
+- Python `>=3.10`
+- installed `codex-cli-bin` runtime package, or an explicit `codex_bin` override
+- local Codex auth/session configured
+
+## 2) Run your first turn (sync)
+
+```python
+from codex_app_server import Codex, TextInput
+
+with Codex() as codex:
+    print("Server:", codex.metadata.server_name, codex.metadata.server_version)
+
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+    result = thread.turn(TextInput("Say hello in one sentence.")).run()
+
+    print("Thread:", result.thread_id)
+    print("Turn:", result.turn_id)
+    print("Status:", result.status)
+    print("Text:", result.text)
+```
+
+What happened:
+
+- `Codex()` started and initialized `codex app-server`.
+- `thread_start(...)` created a thread.
+- `turn(...).run()` consumed events until `turn/completed` and returned a `TurnResult`.
+- one client can have only one active `Turn.stream()` / `Turn.run()` consumer at a time in the current experimental build
+
+## 3) Continue the same thread (multi-turn)
+
+```python
+from codex_app_server import Codex, TextInput
+
+with Codex() as codex:
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+
+    first = thread.turn(TextInput("Summarize Rust ownership in 2 bullets.")).run()
+    second = thread.turn(TextInput("Now explain it to a Python developer.")).run()
+
+    print("first:", first.text)
+    print("second:", second.text)
+```
+
+## 4) Async parity
+
+```python
+import asyncio
+from codex_app_server import AsyncCodex, TextInput
+
+
+async def main() -> None:
+    async with AsyncCodex() as codex:
+        thread = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+        turn = await thread.turn(TextInput("Continue where we left off."))
+        result = await turn.run()
+        print(result.text)
+
+
+asyncio.run(main())
+```
+
+## 5) Resume an existing thread
+
+```python
+from codex_app_server import Codex, TextInput
+
+THREAD_ID = "thr_123"  # replace with a real id
+
+with Codex() as codex:
+    thread = codex.thread_resume(THREAD_ID)
+    result = thread.turn(TextInput("Continue where we left off.")).run()
+    print(result.text)
+```
+
+## 6) Next stops
+
+- API surface and signatures: `docs/api-reference.md`
+- Common decisions/pitfalls: `docs/faq.md`
+- End-to-end runnable examples: `examples/README.md`

sdk/python/examples/01_quickstart_constructor/async.py

@@ -0,0 +1,30 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import AsyncCodex, TextInput
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        print("Server:", codex.metadata.server_name, codex.metadata.server_version)
+
+        thread = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+        turn = await thread.turn(TextInput("Say hello in one sentence."))
+        result = await turn.run()
+
+        print("Status:", result.status)
+        print("Text:", result.text)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/01_quickstart_constructor/sync.py

@@ -0,0 +1,20 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import Codex, TextInput
+
+with Codex(config=runtime_config()) as codex:
+    print("Server:", codex.metadata.server_name, codex.metadata.server_version)
+
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+    result = thread.turn(TextInput("Say hello in one sentence.")).run()
+    print("Status:", result.status)
+    print("Text:", result.text)

sdk/python/examples/02_turn_run/async.py

@@ -0,0 +1,37 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import AsyncCodex, TextInput
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        thread = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+        turn = await thread.turn(TextInput("Give 3 bullets about SIMD."))
+        result = await turn.run()
+
+        print("thread_id:", result.thread_id)
+        print("turn_id:", result.turn_id)
+        print("status:", result.status)
+        if result.error is not None:
+            print("error:", result.error)
+        print("text:", result.text)
+        print("items.count:", len(result.items))
+        if result.usage is None:
+            raise RuntimeError("missing usage for completed turn")
+        print("usage.thread_id:", result.usage.thread_id)
+        print("usage.turn_id:", result.usage.turn_id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/02_turn_run/sync.py

@@ -0,0 +1,28 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import Codex, TextInput
+
+with Codex(config=runtime_config()) as codex:
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+    result = thread.turn(TextInput("Give 3 bullets about SIMD.")).run()
+
+    print("thread_id:", result.thread_id)
+    print("turn_id:", result.turn_id)
+    print("status:", result.status)
+    if result.error is not None:
+        print("error:", result.error)
+    print("text:", result.text)
+    print("items.count:", len(result.items))
+    if result.usage is None:
+        raise RuntimeError("missing usage for completed turn")
+    print("usage.thread_id:", result.usage.thread_id)
+    print("usage.turn_id:", result.usage.turn_id)

sdk/python/examples/03_turn_stream_events/async.py

@@ -0,0 +1,44 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import AsyncCodex, TextInput
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        thread = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+        turn = await thread.turn(TextInput("Count from 1 to 200 with commas, then one summary sentence."))
+
+        # Best effort controls: models can finish quickly, so races are expected.
+        try:
+            _ = await turn.steer(TextInput("Keep it brief and stop after 20 numbers."))
+            print("steer: sent")
+        except Exception as exc:
+            print("steer: skipped", type(exc).__name__)
+
+        try:
+            _ = await turn.interrupt()
+            print("interrupt: sent")
+        except Exception as exc:
+            print("interrupt: skipped", type(exc).__name__)
+
+        event_count = 0
+        async for event in turn.stream():
+            event_count += 1
+            print(event.method, event.payload)
+
+        print("events.count:", event_count)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/03_turn_stream_events/sync.py

@@ -0,0 +1,36 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import Codex, TextInput
+
+with Codex(config=runtime_config()) as codex:
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+    turn = thread.turn(TextInput("Count from 1 to 200 with commas, then one summary sentence."))
+
+    # Best effort controls: models can finish quickly, so races are expected.
+    try:
+        _ = turn.steer(TextInput("Keep it brief and stop after 20 numbers."))
+        print("steer: sent")
+    except Exception as exc:
+        print("steer: skipped", type(exc).__name__)
+
+    try:
+        _ = turn.interrupt()
+        print("interrupt: sent")
+    except Exception as exc:
+        print("interrupt: skipped", type(exc).__name__)
+
+    event_count = 0
+    for event in turn.stream():
+        event_count += 1
+        print(event.method, event.payload)
+
+    print("events.count:", event_count)

sdk/python/examples/04_models_and_metadata/async.py

@@ -0,0 +1,28 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import AsyncCodex
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        print("metadata:", codex.metadata)
+
+        models = await codex.models(include_hidden=True)
+        print("models.count:", len(models.data))
+        if models.data:
+            print("first model id:", models.data[0].id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/04_models_and_metadata/sync.py

@@ -0,0 +1,20 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import Codex
+
+with Codex(config=runtime_config()) as codex:
+    print("metadata:", codex.metadata)
+
+    models = codex.models()
+    print("models.count:", len(models.data))
+    if models.data:
+        print("first model id:", models.data[0].id)

sdk/python/examples/05_existing_thread/async.py

@@ -0,0 +1,32 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import AsyncCodex, TextInput
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        original = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+
+        first_turn = await original.turn(TextInput("Tell me one fact about Saturn."))
+        first = await first_turn.run()
+        print("Created thread:", first.thread_id)
+
+        resumed = await codex.thread_resume(first.thread_id)
+        second_turn = await resumed.turn(TextInput("Continue with one more fact."))
+        second = await second_turn.run()
+        print(second.text)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/05_existing_thread/sync.py

@@ -0,0 +1,23 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import Codex, TextInput
+
+with Codex(config=runtime_config()) as codex:
+    # Create an initial thread and turn so we have a real thread to resume.
+    original = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+    first = original.turn(TextInput("Tell me one fact about Saturn.")).run()
+    print("Created thread:", first.thread_id)
+
+    # Resume the existing thread by ID.
+    resumed = codex.thread_resume(first.thread_id)
+    second = resumed.turn(TextInput("Continue with one more fact.")).run()
+    print(second.text)

sdk/python/examples/06_thread_lifecycle_and_controls/async.py

@@ -0,0 +1,70 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import AsyncCodex, TextInput
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        thread = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+        first = await (await thread.turn(TextInput("One sentence about structured planning."))).run()
+        second = await (await thread.turn(TextInput("Now restate it for a junior engineer."))).run()
+
+        reopened = await codex.thread_resume(thread.id)
+        listing_active = await codex.thread_list(limit=20, archived=False)
+        reading = await reopened.read(include_turns=True)
+
+        _ = await reopened.set_name("sdk-lifecycle-demo")
+        _ = await codex.thread_archive(reopened.id)
+        listing_archived = await codex.thread_list(limit=20, archived=True)
+        unarchived = await codex.thread_unarchive(reopened.id)
+
+        resumed_info = "n/a"
+        try:
+            resumed = await codex.thread_resume(
+                unarchived.id,
+                model="gpt-5",
+                config={"model_reasoning_effort": "high"},
+            )
+            resumed_result = await (await resumed.turn(TextInput("Continue in one short sentence."))).run()
+            resumed_info = f"{resumed_result.turn_id} {resumed_result.status}"
+        except Exception as exc:
+            resumed_info = f"skipped({type(exc).__name__})"
+
+        forked_info = "n/a"
+        try:
+            forked = await codex.thread_fork(unarchived.id, model="gpt-5")
+            forked_result = await (await forked.turn(TextInput("Take a different angle in one short sentence."))).run()
+            forked_info = f"{forked_result.turn_id} {forked_result.status}"
+        except Exception as exc:
+            forked_info = f"skipped({type(exc).__name__})"
+
+        compact_info = "sent"
+        try:
+            _ = await unarchived.compact()
+        except Exception as exc:
+            compact_info = f"skipped({type(exc).__name__})"
+
+        print("Lifecycle OK:", thread.id)
+        print("first:", first.turn_id, first.status)
+        print("second:", second.turn_id, second.status)
+        print("read.turns:", len(reading.thread.turns or []))
+        print("list.active:", len(listing_active.data))
+        print("list.archived:", len(listing_archived.data))
+        print("resumed:", resumed_info)
+        print("forked:", forked_info)
+        print("compact:", compact_info)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/06_thread_lifecycle_and_controls/sync.py

@@ -0,0 +1,63 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import Codex, TextInput
+
+
+with Codex(config=runtime_config()) as codex:
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+    first = thread.turn(TextInput("One sentence about structured planning.")).run()
+    second = thread.turn(TextInput("Now restate it for a junior engineer.")).run()
+
+    reopened = codex.thread_resume(thread.id)
+    listing_active = codex.thread_list(limit=20, archived=False)
+    reading = reopened.read(include_turns=True)
+
+    _ = reopened.set_name("sdk-lifecycle-demo")
+    _ = codex.thread_archive(reopened.id)
+    listing_archived = codex.thread_list(limit=20, archived=True)
+    unarchived = codex.thread_unarchive(reopened.id)
+
+    resumed_info = "n/a"
+    try:
+        resumed = codex.thread_resume(
+            unarchived.id,
+            model="gpt-5",
+            config={"model_reasoning_effort": "high"},
+        )
+        resumed_result = resumed.turn(TextInput("Continue in one short sentence.")).run()
+        resumed_info = f"{resumed_result.turn_id} {resumed_result.status}"
+    except Exception as exc:
+        resumed_info = f"skipped({type(exc).__name__})"
+
+    forked_info = "n/a"
+    try:
+        forked = codex.thread_fork(unarchived.id, model="gpt-5")
+        forked_result = forked.turn(TextInput("Take a different angle in one short sentence.")).run()
+        forked_info = f"{forked_result.turn_id} {forked_result.status}"
+    except Exception as exc:
+        forked_info = f"skipped({type(exc).__name__})"
+
+    compact_info = "sent"
+    try:
+        _ = unarchived.compact()
+    except Exception as exc:
+        compact_info = f"skipped({type(exc).__name__})"
+
+    print("Lifecycle OK:", thread.id)
+    print("first:", first.turn_id, first.status)
+    print("second:", second.turn_id, second.status)
+    print("read.turns:", len(reading.thread.turns or []))
+    print("list.active:", len(listing_active.data))
+    print("list.archived:", len(listing_archived.data))
+    print("resumed:", resumed_info)
+    print("forked:", forked_info)
+    print("compact:", compact_info)

sdk/python/examples/07_image_and_text/async.py

@@ -0,0 +1,35 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import AsyncCodex, ImageInput, TextInput
+
+REMOTE_IMAGE_URL = "https://raw.githubusercontent.com/github/explore/main/topics/python/python.png"
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        thread = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+        turn = await thread.turn(
+            [
+                TextInput("What is in this image? Give 3 bullets."),
+                ImageInput(REMOTE_IMAGE_URL),
+            ]
+        )
+        result = await turn.run()
+
+        print("Status:", result.status)
+        print(result.text)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/07_image_and_text/sync.py

@@ -0,0 +1,26 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import Codex, ImageInput, TextInput
+
+REMOTE_IMAGE_URL = "https://raw.githubusercontent.com/github/explore/main/topics/python/python.png"
+
+with Codex(config=runtime_config()) as codex:
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+    result = thread.turn(
+        [
+            TextInput("What is in this image? Give 3 bullets."),
+            ImageInput(REMOTE_IMAGE_URL),
+        ]
+    ).run()
+
+    print("Status:", result.status)
+    print(result.text)

sdk/python/examples/08_local_image_and_text/async.py

@@ -0,0 +1,38 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import AsyncCodex, LocalImageInput, TextInput
+
+IMAGE_PATH = Path(__file__).resolve().parents[1] / "assets" / "sample_scene.png"
+if not IMAGE_PATH.exists():
+    raise FileNotFoundError(f"Missing bundled image: {IMAGE_PATH}")
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        thread = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+
+        turn = await thread.turn(
+            [
+                TextInput("Read this local image and summarize what you see in 2 bullets."),
+                LocalImageInput(str(IMAGE_PATH.resolve())),
+            ]
+        )
+        result = await turn.run()
+
+        print("Status:", result.status)
+        print(result.text)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/08_local_image_and_text/sync.py

@@ -0,0 +1,29 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import Codex, LocalImageInput, TextInput
+
+IMAGE_PATH = Path(__file__).resolve().parents[1] / "assets" / "sample_scene.png"
+if not IMAGE_PATH.exists():
+    raise FileNotFoundError(f"Missing bundled image: {IMAGE_PATH}")
+
+with Codex(config=runtime_config()) as codex:
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+
+    result = thread.turn(
+        [
+            TextInput("Read this local image and summarize what you see in 2 bullets."),
+            LocalImageInput(str(IMAGE_PATH.resolve())),
+        ]
+    ).run()
+
+    print("Status:", result.status)
+    print(result.text)

sdk/python/examples/09_async_parity/sync.py

@@ -0,0 +1,23 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import Codex, TextInput
+
+with Codex(config=runtime_config()) as codex:
+    print("Server:", codex.metadata.server_name, codex.metadata.server_version)
+
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+    turn = thread.turn(TextInput("Say hello in one sentence."))
+    result = turn.run()
+
+    print("Thread:", result.thread_id)
+    print("Turn:", result.turn_id)
+    print("Text:", result.text.strip())

sdk/python/examples/10_error_handling_and_retry/async.py

@@ -0,0 +1,91 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+import random
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from codex_app_server import (
+    AsyncCodex,
+    JsonRpcError,
+    ServerBusyError,
+    TextInput,
+    TurnStatus,
+    is_retryable_error,
+)
+
+ResultT = TypeVar("ResultT")
+
+
+async def retry_on_overload_async(
+    op: Callable[[], Awaitable[ResultT]],
+    *,
+    max_attempts: int = 3,
+    initial_delay_s: float = 0.25,
+    max_delay_s: float = 2.0,
+    jitter_ratio: float = 0.2,
+) -> ResultT:
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be >= 1")
+
+    delay = initial_delay_s
+    attempt = 0
+    while True:
+        attempt += 1
+        try:
+            return await op()
+        except Exception as exc:  # noqa: BLE001
+            if attempt >= max_attempts or not is_retryable_error(exc):
+                raise
+            jitter = delay * jitter_ratio
+            sleep_for = min(max_delay_s, delay) + random.uniform(-jitter, jitter)
+            if sleep_for > 0:
+                await asyncio.sleep(sleep_for)
+            delay = min(max_delay_s, delay * 2)
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        thread = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+
+        try:
+            result = await retry_on_overload_async(
+                _run_turn(thread, "Summarize retry best practices in 3 bullets."),
+                max_attempts=3,
+                initial_delay_s=0.25,
+                max_delay_s=2.0,
+            )
+        except ServerBusyError as exc:
+            print("Server overloaded after retries:", exc.message)
+            print("Text:")
+            return
+        except JsonRpcError as exc:
+            print(f"JSON-RPC error {exc.code}: {exc.message}")
+            print("Text:")
+            return
+
+        if result.status == TurnStatus.failed:
+            print("Turn failed:", result.error)
+
+        print("Text:", result.text)
+
+
+def _run_turn(thread, prompt: str):
+    async def _inner():
+        turn = await thread.turn(TextInput(prompt))
+        return await turn.run()
+
+    return _inner
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/10_error_handling_and_retry/sync.py

@@ -0,0 +1,40 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import (
+    Codex,
+    JsonRpcError,
+    ServerBusyError,
+    TextInput,
+    TurnStatus,
+    retry_on_overload,
+)
+
+with Codex(config=runtime_config()) as codex:
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+
+    try:
+        result = retry_on_overload(
+            lambda: thread.turn(TextInput("Summarize retry best practices in 3 bullets.")).run(),
+            max_attempts=3,
+            initial_delay_s=0.25,
+            max_delay_s=2.0,
+        )
+    except ServerBusyError as exc:
+        print("Server overloaded after retries:", exc.message)
+        print("Text:")
+    except JsonRpcError as exc:
+        print(f"JSON-RPC error {exc.code}: {exc.message}")
+        print("Text:")
+    else:
+        if result.status == TurnStatus.failed:
+            print("Turn failed:", result.error)
+        print("Text:", result.text)

sdk/python/examples/11_cli_mini_app/async.py

@@ -0,0 +1,96 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import (
+    AsyncCodex,
+    TextInput,
+    ThreadTokenUsageUpdatedNotification,
+    TurnCompletedNotificationPayload,
+)
+
+
+def _status_value(status: object | None) -> str:
+    return str(getattr(status, "value", status))
+
+
+def _format_usage(usage: object | None) -> str:
+    if usage is None:
+        return "usage> (none)"
+
+    last = getattr(usage, "last", None)
+    total = getattr(usage, "total", None)
+    if last is None or total is None:
+        return f"usage> {usage}"
+
+    return (
+        "usage>\n"
+        f"  last: input={last.inputTokens} output={last.outputTokens} reasoning={last.reasoningOutputTokens} total={last.totalTokens} cached={last.cachedInputTokens}\n"
+        f"  total: input={total.inputTokens} output={total.outputTokens} reasoning={total.reasoningOutputTokens} total={total.totalTokens} cached={total.cachedInputTokens}"
+    )
+
+
+async def main() -> None:
+    print("Codex async mini CLI. Type /exit to quit.")
+
+    async with AsyncCodex(config=runtime_config()) as codex:
+        thread = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+        print("Thread:", thread.id)
+
+        while True:
+            try:
+                user_input = (await asyncio.to_thread(input, "you> ")).strip()
+            except EOFError:
+                break
+
+            if not user_input:
+                continue
+            if user_input in {"/exit", "/quit"}:
+                break
+
+            turn = await thread.turn(TextInput(user_input))
+            usage = None
+            status = None
+            error = None
+            printed_delta = False
+
+            print("assistant> ", end="", flush=True)
+            async for event in turn.stream():
+                payload = event.payload
+                if event.method == "item/agentMessage/delta":
+                    delta = getattr(payload, "delta", "")
+                    if delta:
+                        print(delta, end="", flush=True)
+                        printed_delta = True
+                    continue
+                if isinstance(payload, ThreadTokenUsageUpdatedNotification):
+                    usage = payload.token_usage
+                    continue
+                if isinstance(payload, TurnCompletedNotificationPayload):
+                    status = payload.turn.status
+                    error = payload.turn.error
+
+            if printed_delta:
+                print()
+            else:
+                print("[no text]")
+
+            status_text = _status_value(status)
+            print(f"assistant.status> {status_text}")
+            if status_text == "failed":
+                print("assistant.error>", error)
+
+            print(_format_usage(usage))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/11_cli_mini_app/sync.py

@@ -0,0 +1,89 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import (
+    Codex,
+    TextInput,
+    ThreadTokenUsageUpdatedNotification,
+    TurnCompletedNotificationPayload,
+)
+
+print("Codex mini CLI. Type /exit to quit.")
+
+
+def _status_value(status: object | None) -> str:
+    return str(getattr(status, "value", status))
+
+
+def _format_usage(usage: object | None) -> str:
+    if usage is None:
+        return "usage> (none)"
+
+    last = getattr(usage, "last", None)
+    total = getattr(usage, "total", None)
+    if last is None or total is None:
+        return f"usage> {usage}"
+
+    return (
+        "usage>\n"
+        f"  last: input={last.inputTokens} output={last.outputTokens} reasoning={last.reasoningOutputTokens} total={last.totalTokens} cached={last.cachedInputTokens}\n"
+        f"  total: input={total.inputTokens} output={total.outputTokens} reasoning={total.reasoningOutputTokens} total={total.totalTokens} cached={total.cachedInputTokens}"
+    )
+
+
+with Codex(config=runtime_config()) as codex:
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+    print("Thread:", thread.id)
+
+    while True:
+        try:
+            user_input = input("you> ").strip()
+        except EOFError:
+            break
+
+        if not user_input:
+            continue
+        if user_input in {"/exit", "/quit"}:
+            break
+
+        turn = thread.turn(TextInput(user_input))
+        usage = None
+        status = None
+        error = None
+        printed_delta = False
+
+        print("assistant> ", end="", flush=True)
+        for event in turn.stream():
+            payload = event.payload
+            if event.method == "item/agentMessage/delta":
+                delta = getattr(payload, "delta", "")
+                if delta:
+                    print(delta, end="", flush=True)
+                    printed_delta = True
+                continue
+            if isinstance(payload, ThreadTokenUsageUpdatedNotification):
+                usage = payload.token_usage
+                continue
+            if isinstance(payload, TurnCompletedNotificationPayload):
+                status = payload.turn.status
+                error = payload.turn.error
+
+        if printed_delta:
+            print()
+        else:
+            print("[no text]")
+
+        status_text = _status_value(status)
+        print(f"assistant.status> {status_text}")
+        if status_text == "failed":
+            print("assistant.error>", error)
+
+        print(_format_usage(usage))

sdk/python/examples/12_turn_params_kitchen_sink/async.py

@@ -0,0 +1,75 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import (
+    AskForApproval,
+    AsyncCodex,
+    Personality,
+    ReasoningEffort,
+    ReasoningSummary,
+    SandboxPolicy,
+    TextInput,
+)
+
+OUTPUT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "summary": {"type": "string"},
+        "actions": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+    },
+    "required": ["summary", "actions"],
+    "additionalProperties": False,
+}
+
+SANDBOX_POLICY = SandboxPolicy.model_validate(
+    {
+        "type": "readOnly",
+        "access": {"type": "fullAccess"},
+    }
+)
+SUMMARY = ReasoningSummary.model_validate("concise")
+
+PROMPT = (
+    "Analyze a safe rollout plan for enabling a feature flag in production. "
+    "Return JSON matching the requested schema."
+)
+APPROVAL_POLICY = AskForApproval.model_validate("never")
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        thread = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+
+        turn = await thread.turn(
+            TextInput(PROMPT),
+            approval_policy=APPROVAL_POLICY,
+            cwd=str(Path.cwd()),
+            effort=ReasoningEffort.medium,
+            model="gpt-5",
+            output_schema=OUTPUT_SCHEMA,
+            personality=Personality.pragmatic,
+            sandbox_policy=SANDBOX_POLICY,
+            summary=SUMMARY,
+        )
+        result = await turn.run()
+
+        print("Status:", result.status)
+        print("Text:", result.text)
+        print("Usage:", result.usage)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/12_turn_params_kitchen_sink/sync.py

@@ -0,0 +1,67 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import (
+    AskForApproval,
+    Codex,
+    Personality,
+    ReasoningEffort,
+    ReasoningSummary,
+    SandboxPolicy,
+    TextInput,
+)
+
+OUTPUT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "summary": {"type": "string"},
+        "actions": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+    },
+    "required": ["summary", "actions"],
+    "additionalProperties": False,
+}
+
+SANDBOX_POLICY = SandboxPolicy.model_validate(
+    {
+        "type": "readOnly",
+        "access": {"type": "fullAccess"},
+    }
+)
+SUMMARY = ReasoningSummary.model_validate("concise")
+
+PROMPT = (
+    "Analyze a safe rollout plan for enabling a feature flag in production. "
+    "Return JSON matching the requested schema."
+)
+APPROVAL_POLICY = AskForApproval.model_validate("never")
+
+with Codex(config=runtime_config()) as codex:
+    thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+
+    turn = thread.turn(
+        TextInput(PROMPT),
+        approval_policy=APPROVAL_POLICY,
+        cwd=str(Path.cwd()),
+        effort=ReasoningEffort.medium,
+        model="gpt-5",
+        output_schema=OUTPUT_SCHEMA,
+        personality=Personality.pragmatic,
+        sandbox_policy=SANDBOX_POLICY,
+        summary=SUMMARY,
+    )
+    result = turn.run()
+
+    print("Status:", result.status)
+    print("Text:", result.text)
+    print("Usage:", result.usage)

sdk/python/examples/13_model_select_and_turn_params/async.py

@@ -0,0 +1,117 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import (
+    AskForApproval,
+    AsyncCodex,
+    Personality,
+    ReasoningEffort,
+    ReasoningSummary,
+    SandboxPolicy,
+    TextInput,
+)
+
+REASONING_RANK = {
+    "none": 0,
+    "minimal": 1,
+    "low": 2,
+    "medium": 3,
+    "high": 4,
+    "xhigh": 5,
+}
+
+
+def _pick_highest_model(models):
+    visible = [m for m in models if not m.hidden] or models
+    known_names = {m.id for m in visible} | {m.model for m in visible}
+    top_candidates = [m for m in visible if not (m.upgrade and m.upgrade in known_names)]
+    pool = top_candidates or visible
+    return max(pool, key=lambda m: (m.model, m.id))
+
+
+def _pick_highest_turn_effort(model) -> ReasoningEffort:
+    if not model.supported_reasoning_efforts:
+        return ReasoningEffort.medium
+
+    best = max(
+        model.supported_reasoning_efforts,
+        key=lambda option: REASONING_RANK.get(option.reasoning_effort.value, -1),
+    )
+    return ReasoningEffort(best.reasoning_effort.value)
+
+
+OUTPUT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "summary": {"type": "string"},
+        "actions": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+    },
+    "required": ["summary", "actions"],
+    "additionalProperties": False,
+}
+
+SANDBOX_POLICY = SandboxPolicy.model_validate(
+    {
+        "type": "readOnly",
+        "access": {"type": "fullAccess"},
+    }
+)
+APPROVAL_POLICY = AskForApproval.model_validate("never")
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        models = await codex.models(include_hidden=True)
+        selected_model = _pick_highest_model(models.data)
+        selected_effort = _pick_highest_turn_effort(selected_model)
+
+        print("selected.model:", selected_model.model)
+        print("selected.effort:", selected_effort.value)
+
+        thread = await codex.thread_start(
+            model=selected_model.model,
+            config={"model_reasoning_effort": selected_effort.value},
+        )
+
+        first_turn = await thread.turn(
+            TextInput("Give one short sentence about reliable production releases."),
+            model=selected_model.model,
+            effort=selected_effort,
+        )
+        first = await first_turn.run()
+
+        print("agent.message:", first.text)
+        print("usage:", first.usage)
+
+        second_turn = await thread.turn(
+            TextInput("Return JSON for a safe feature-flag rollout plan."),
+            approval_policy=APPROVAL_POLICY,
+            cwd=str(Path.cwd()),
+            effort=selected_effort,
+            model=selected_model.model,
+            output_schema=OUTPUT_SCHEMA,
+            personality=Personality.pragmatic,
+            sandbox_policy=SANDBOX_POLICY,
+            summary=ReasoningSummary.model_validate("concise"),
+        )
+        second = await second_turn.run()
+
+        print("agent.message.params:", second.text)
+        print("usage.params:", second.usage)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/13_model_select_and_turn_params/sync.py

@@ -0,0 +1,108 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from codex_app_server import (
+    AskForApproval,
+    Codex,
+    Personality,
+    ReasoningEffort,
+    ReasoningSummary,
+    SandboxPolicy,
+    TextInput,
+)
+
+REASONING_RANK = {
+    "none": 0,
+    "minimal": 1,
+    "low": 2,
+    "medium": 3,
+    "high": 4,
+    "xhigh": 5,
+}
+
+
+def _pick_highest_model(models):
+    visible = [m for m in models if not m.hidden] or models
+    known_names = {m.id for m in visible} | {m.model for m in visible}
+    top_candidates = [m for m in visible if not (m.upgrade and m.upgrade in known_names)]
+    pool = top_candidates or visible
+    return max(pool, key=lambda m: (m.model, m.id))
+
+
+def _pick_highest_turn_effort(model) -> ReasoningEffort:
+    if not model.supported_reasoning_efforts:
+        return ReasoningEffort.medium
+
+    best = max(
+        model.supported_reasoning_efforts,
+        key=lambda option: REASONING_RANK.get(option.reasoning_effort.value, -1),
+    )
+    return ReasoningEffort(best.reasoning_effort.value)
+
+
+OUTPUT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "summary": {"type": "string"},
+        "actions": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+    },
+    "required": ["summary", "actions"],
+    "additionalProperties": False,
+}
+
+SANDBOX_POLICY = SandboxPolicy.model_validate(
+    {
+        "type": "readOnly",
+        "access": {"type": "fullAccess"},
+    }
+)
+APPROVAL_POLICY = AskForApproval.model_validate("never")
+
+
+with Codex(config=runtime_config()) as codex:
+    models = codex.models(include_hidden=True)
+    selected_model = _pick_highest_model(models.data)
+    selected_effort = _pick_highest_turn_effort(selected_model)
+
+    print("selected.model:", selected_model.model)
+    print("selected.effort:", selected_effort.value)
+
+    thread = codex.thread_start(
+        model=selected_model.model,
+        config={"model_reasoning_effort": selected_effort.value},
+    )
+
+    first = thread.turn(
+        TextInput("Give one short sentence about reliable production releases."),
+        model=selected_model.model,
+        effort=selected_effort,
+    ).run()
+
+    print("agent.message:", first.text)
+    print("usage:", first.usage)
+
+    second = thread.turn(
+        TextInput("Return JSON for a safe feature-flag rollout plan."),
+        approval_policy=APPROVAL_POLICY,
+        cwd=str(Path.cwd()),
+        effort=selected_effort,
+        model=selected_model.model,
+        output_schema=OUTPUT_SCHEMA,
+        personality=Personality.pragmatic,
+        sandbox_policy=SANDBOX_POLICY,
+        summary=ReasoningSummary.model_validate("concise"),
+    ).run()
+
+    print("agent.message.params:", second.text)
+    print("usage.params:", second.usage)

sdk/python/examples/README.md

@@ -0,0 +1,78 @@
+# Python SDK Examples
+
+Each example folder contains runnable versions:
+
+- `sync.py` (public sync surface: `Codex`)
+- `async.py` (public async surface: `AsyncCodex`)
+
+All examples intentionally use only public SDK exports from `codex_app_server`.
+
+## Prerequisites
+
+- Python `>=3.10`
+- Install SDK dependencies for the same Python interpreter you will use to run examples
+
+Recommended setup (from `sdk/python`):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e .
+```
+
+When running examples from this repo checkout, the SDK source uses the local
+tree and does not bundle a runtime binary. The helper in `examples/_bootstrap.py`
+therefore resolves `codex` from:
+
+- `CODEX_PYTHON_SDK_CODEX_BIN`, if set
+- otherwise `codex` on `PATH`
+
+## Run examples
+
+From `sdk/python`:
+
+```bash
+python examples/<example-folder>/sync.py
+python examples/<example-folder>/async.py
+```
+
+The examples bootstrap local imports from `sdk/python/src` automatically, so no
+extra package build step is required beyond installing dependencies for your
+active interpreter and making a `codex` binary available.
+
+## Recommended first run
+
+```bash
+python examples/01_quickstart_constructor/sync.py
+python examples/01_quickstart_constructor/async.py
+```
+
+## Index
+
+- `01_quickstart_constructor/`
+  - first run / sanity check
+- `02_turn_run/`
+  - inspect full turn output fields
+- `03_turn_stream_events/`
+  - stream and print raw notifications
+- `04_models_and_metadata/`
+  - read server metadata and model list
+- `05_existing_thread/`
+  - resume a real existing thread (created in-script)
+- `06_thread_lifecycle_and_controls/`
+  - thread lifecycle + control calls
+- `07_image_and_text/`
+  - remote image URL + text multimodal turn
+- `08_local_image_and_text/`
+  - local image + text multimodal turn using bundled sample image
+- `09_async_parity/`
+  - parity-style sync flow (see async parity in other examples)
+- `10_error_handling_and_retry/`
+  - overload retry pattern + typed error handling structure
+- `11_cli_mini_app/`
+  - interactive chat loop
+- `12_turn_params_kitchen_sink/`
+  - one turn using most optional `turn(...)` params (sync + async)
+- `13_model_select_and_turn_params/`
+  - list models, pick highest model + highest supported reasoning effort, run turns, print message and usage

sdk/python/examples/_bootstrap.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import sys
+from pathlib import Path
+
+
+def _ensure_runtime_dependencies(sdk_python_dir: Path) -> None:
+    if importlib.util.find_spec("pydantic") is not None:
+        return
+
+    python = sys.executable
+    raise RuntimeError(
+        "Missing required dependency: pydantic.\n"
+        f"Interpreter: {python}\n"
+        "Install dependencies with the same interpreter used to run this example:\n"
+        f"  {python} -m pip install -e {sdk_python_dir}\n"
+        "If you installed with `pip` from another Python, reinstall using the command above."
+    )
+
+
+def ensure_local_sdk_src() -> Path:
+    """Add sdk/python/src to sys.path so examples run without installing the package."""
+    sdk_python_dir = Path(__file__).resolve().parents[1]
+    src_dir = sdk_python_dir / "src"
+    package_dir = src_dir / "codex_app_server"
+    if not package_dir.exists():
+        raise RuntimeError(f"Could not locate local SDK package at {package_dir}")
+
+    _ensure_runtime_dependencies(sdk_python_dir)
+
+    src_str = str(src_dir)
+    if src_str not in sys.path:
+        sys.path.insert(0, src_str)
+    return src_dir
+
+
+def runtime_config():
+    """Return an example-friendly AppServerConfig for local repo usage."""
+    from codex_app_server import AppServerConfig
+
+    codex_bin = os.environ.get("CODEX_PYTHON_SDK_CODEX_BIN") or shutil.which("codex")
+    if codex_bin is None:
+        raise RuntimeError(
+            "Examples require a Codex CLI binary when run from this repo checkout.\n"
+            "Set CODEX_PYTHON_SDK_CODEX_BIN=/absolute/path/to/codex, or ensure `codex` is on PATH."
+        )
+    return AppServerConfig(codex_bin=codex_bin)

sdk/python/notebooks/sdk_walkthrough.ipynb

@@ -0,0 +1,535 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Codex Python SDK Walkthrough\n",
+    "\n",
+    "Public SDK surface only (`codex_app_server` root exports)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 1: bootstrap local SDK imports (no installation required)\n",
+    "import os\n",
+    "import sys\n",
+    "from pathlib import Path\n",
+    "\n",
+    "if sys.version_info < (3, 10):\n",
+    "    raise RuntimeError(\n",
+    "        f'Notebook requires Python 3.10+; current interpreter is {sys.version.split()[0]}.'\n",
+    "    )\n",
+    "\n",
+    "try:\n",
+    "    _ = os.getcwd()\n",
+    "except FileNotFoundError:\n",
+    "    os.chdir(str(Path.home()))\n",
+    "\n",
+    "\n",
+    "def _is_sdk_python_dir(path: Path) -> bool:\n",
+    "    return (path / 'pyproject.toml').exists() and (path / 'src' / 'codex_app_server').exists()\n",
+    "\n",
+    "\n",
+    "def _iter_home_fallback_candidates(home: Path):\n",
+    "    # bounded depth scan under home to support launching notebooks from unrelated cwd values\n",
+    "    patterns = ('sdk/python', '*/sdk/python', '*/*/sdk/python', '*/*/*/sdk/python')\n",
+    "    for pattern in patterns:\n",
+    "        yield from home.glob(pattern)\n",
+    "\n",
+    "\n",
+    "def _find_sdk_python_dir(start: Path) -> Path | None:\n",
+    "    checked = set()\n",
+    "\n",
+    "    def _consider(candidate: Path) -> Path | None:\n",
+    "        resolved = candidate.resolve()\n",
+    "        if resolved in checked:\n",
+    "            return None\n",
+    "        checked.add(resolved)\n",
+    "        if _is_sdk_python_dir(resolved):\n",
+    "            return resolved\n",
+    "        return None\n",
+    "\n",
+    "    for candidate in [start, *start.parents]:\n",
+    "        found = _consider(candidate)\n",
+    "        if found is not None:\n",
+    "            return found\n",
+    "\n",
+    "    for candidate in [start / 'sdk' / 'python', *(parent / 'sdk' / 'python' for parent in start.parents)]:\n",
+    "        found = _consider(candidate)\n",
+    "        if found is not None:\n",
+    "            return found\n",
+    "\n",
+    "    env_dir = os.environ.get('CODEX_PYTHON_SDK_DIR')\n",
+    "    if env_dir:\n",
+    "        found = _consider(Path(env_dir).expanduser())\n",
+    "        if found is not None:\n",
+    "            return found\n",
+    "\n",
+    "    for entry in sys.path:\n",
+    "        if not entry:\n",
+    "            continue\n",
+    "        entry_path = Path(entry).expanduser()\n",
+    "        for candidate in (entry_path, entry_path / 'sdk' / 'python'):\n",
+    "            found = _consider(candidate)\n",
+    "            if found is not None:\n",
+    "                return found\n",
+    "\n",
+    "    home = Path.home()\n",
+    "    for candidate in _iter_home_fallback_candidates(home):\n",
+    "        found = _consider(candidate)\n",
+    "        if found is not None:\n",
+    "            return found\n",
+    "\n",
+    "    return None\n",
+    "\n",
+    "\n",
+    "repo_python_dir = _find_sdk_python_dir(Path.cwd())\n",
+    "if repo_python_dir is None:\n",
+    "    raise RuntimeError('Could not locate sdk/python. Set CODEX_PYTHON_SDK_DIR to your sdk/python path.')\n",
+    "\n",
+    "src_dir = repo_python_dir / 'src'\n",
+    "if str(src_dir) not in sys.path:\n",
+    "    sys.path.insert(0, str(src_dir))\n",
+    "\n",
+    "# Force fresh imports after SDK upgrades in the same notebook kernel.\n",
+    "for module_name in list(sys.modules):\n",
+    "    if module_name == 'codex_app_server' or module_name.startswith('codex_app_server.'):\n",
+    "        sys.modules.pop(module_name, None)\n",
+    "\n",
+    "print('Kernel:', sys.executable)\n",
+    "print('SDK source:', src_dir)\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 2: imports (public only)\n",
+    "from codex_app_server import (\n",
+    "    AsyncCodex,\n",
+    "    Codex,\n",
+    "    ImageInput,\n",
+    "    LocalImageInput,\n",
+    "    TextInput,\n",
+    "    retry_on_overload,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 3: simple sync conversation\n",
+    "with Codex() as codex:\n",
+    "    thread = codex.thread_start(model='gpt-5', config={'model_reasoning_effort': 'high'})\n",
+    "    turn = thread.turn(TextInput('Explain gradient descent in 3 bullets.'))\n",
+    "    result = turn.run()\n",
+    "\n",
+    "    print('server:', codex.metadata)\n",
+    "    print('status:', result.status)\n",
+    "    print(result.text)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 4: multi-turn continuity in same thread\n",
+    "with Codex() as codex:\n",
+    "    thread = codex.thread_start(model='gpt-5', config={'model_reasoning_effort': 'high'})\n",
+    "\n",
+    "    first = thread.turn(TextInput('Give a short summary of transformers.')).run()\n",
+    "    second = thread.turn(TextInput('Now explain that to a high-school student.')).run()\n",
+    "\n",
+    "    print('first status:', first.status)\n",
+    "    print('second status:', second.status)\n",
+    "    print('second text:', second.text)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 5: full thread lifecycle and branching (sync)\n",
+    "with Codex() as codex:\n",
+    "    thread = codex.thread_start(model='gpt-5', config={'model_reasoning_effort': 'high'})\n",
+    "    first = thread.turn(TextInput('One sentence about structured planning.')).run()\n",
+    "    second = thread.turn(TextInput('Now restate it for a junior engineer.')).run()\n",
+    "\n",
+    "    reopened = codex.thread_resume(thread.id)\n",
+    "    listing_active = codex.thread_list(limit=20, archived=False)\n",
+    "    reading = reopened.read(include_turns=True)\n",
+    "\n",
+    "    _ = reopened.set_name('sdk-lifecycle-demo')\n",
+    "    _ = codex.thread_archive(reopened.id)\n",
+    "    listing_archived = codex.thread_list(limit=20, archived=True)\n",
+    "    unarchived = codex.thread_unarchive(reopened.id)\n",
+    "\n",
+    "    resumed_info = 'n/a'\n",
+    "    try:\n",
+    "        resumed = codex.thread_resume(\n",
+    "            unarchived.id,\n",
+    "            model='gpt-5',\n",
+    "            config={'model_reasoning_effort': 'high'},\n",
+    "        )\n",
+    "        resumed_result = resumed.turn(TextInput('Continue in one short sentence.')).run()\n",
+    "        resumed_info = f'{resumed_result.turn_id} {resumed_result.status}'\n",
+    "    except Exception as e:\n",
+    "        resumed_info = f'skipped({type(e).__name__})'\n",
+    "\n",
+    "    forked_info = 'n/a'\n",
+    "    try:\n",
+    "        forked = codex.thread_fork(unarchived.id, model='gpt-5')\n",
+    "        forked_result = forked.turn(TextInput('Take a different angle in one short sentence.')).run()\n",
+    "        forked_info = f'{forked_result.turn_id} {forked_result.status}'\n",
+    "    except Exception as e:\n",
+    "        forked_info = f'skipped({type(e).__name__})'\n",
+    "\n",
+    "    compact_info = 'sent'\n",
+    "    try:\n",
+    "        _ = unarchived.compact()\n",
+    "    except Exception as e:\n",
+    "        compact_info = f'skipped({type(e).__name__})'\n",
+    "\n",
+    "    print('Lifecycle OK:', thread.id)\n",
+    "    print('first:', first.turn_id, first.status)\n",
+    "    print('second:', second.turn_id, second.status)\n",
+    "    print('read.turns:', len(reading.thread.turns or []))\n",
+    "    print('list.active:', len(listing_active.data))\n",
+    "    print('list.archived:', len(listing_archived.data))\n",
+    "    print('resumed:', resumed_info)\n",
+    "    print('forked:', forked_info)\n",
+    "    print('compact:', compact_info)\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 5b: one turn with most optional turn params\n",
+    "from pathlib import Path\n",
+    "from codex_app_server import (\n",
+    "    AskForApproval,\n",
+    "    Personality,\n",
+    "    ReasoningEffort,\n",
+    "    ReasoningSummary,\n",
+    "    SandboxPolicy,\n",
+    ")\n",
+    "\n",
+    "output_schema = {\n",
+    "    'type': 'object',\n",
+    "    'properties': {\n",
+    "        'summary': {'type': 'string'},\n",
+    "        'actions': {'type': 'array', 'items': {'type': 'string'}},\n",
+    "    },\n",
+    "    'required': ['summary', 'actions'],\n",
+    "    'additionalProperties': False,\n",
+    "}\n",
+    "\n",
+    "sandbox_policy = SandboxPolicy.model_validate({'type': 'readOnly', 'access': {'type': 'fullAccess'}})\n",
+    "summary = ReasoningSummary.model_validate('concise')\n",
+    "\n",
+    "with Codex() as codex:\n",
+    "    thread = codex.thread_start(model='gpt-5', config={'model_reasoning_effort': 'high'})\n",
+    "    turn = thread.turn(\n",
+    "        TextInput('Propose a safe production feature-flag rollout. Return JSON matching the schema.'),\n",
+    "        approval_policy=AskForApproval.never,\n",
+    "        cwd=str(Path.cwd()),\n",
+    "        effort=ReasoningEffort.medium,\n",
+    "        model='gpt-5',\n",
+    "        output_schema=output_schema,\n",
+    "        personality=Personality.pragmatic,\n",
+    "        sandbox_policy=sandbox_policy,\n",
+    "        summary=summary,\n",
+    "    )\n",
+    "    result = turn.run()\n",
+    "\n",
+    "    print('status:', result.status)\n",
+    "    print(result.text)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 5c: choose highest model + highest supported reasoning, then run turns\n",
+    "from pathlib import Path\n",
+    "from codex_app_server import (\n",
+    "    AskForApproval,\n",
+    "    Personality,\n",
+    "    ReasoningEffort,\n",
+    "    ReasoningSummary,\n",
+    "    SandboxPolicy,\n",
+    ")\n",
+    "\n",
+    "reasoning_rank = {\n",
+    "    'none': 0,\n",
+    "    'minimal': 1,\n",
+    "    'low': 2,\n",
+    "    'medium': 3,\n",
+    "    'high': 4,\n",
+    "    'xhigh': 5,\n",
+    "}\n",
+    "\n",
+    "\n",
+    "def pick_highest_model(models):\n",
+    "    visible = [m for m in models if not m.hidden] or models\n",
+    "    known_names = {m.id for m in visible} | {m.model for m in visible}\n",
+    "    top_candidates = [m for m in visible if not (m.upgrade and m.upgrade in known_names)]\n",
+    "    pool = top_candidates or visible\n",
+    "    return max(pool, key=lambda m: (m.model, m.id))\n",
+    "\n",
+    "\n",
+    "def pick_highest_turn_effort(model) -> ReasoningEffort:\n",
+    "    if not model.supported_reasoning_efforts:\n",
+    "        return ReasoningEffort.medium\n",
+    "    best = max(model.supported_reasoning_efforts, key=lambda opt: reasoning_rank.get(opt.reasoning_effort.value, -1))\n",
+    "    return ReasoningEffort(best.reasoning_effort.value)\n",
+    "\n",
+    "\n",
+    "output_schema = {\n",
+    "    'type': 'object',\n",
+    "    'properties': {\n",
+    "        'summary': {'type': 'string'},\n",
+    "        'actions': {'type': 'array', 'items': {'type': 'string'}},\n",
+    "    },\n",
+    "    'required': ['summary', 'actions'],\n",
+    "    'additionalProperties': False,\n",
+    "}\n",
+    "sandbox_policy = SandboxPolicy.model_validate({'type': 'readOnly', 'access': {'type': 'fullAccess'}})\n",
+    "\n",
+    "with Codex() as codex:\n",
+    "    models = codex.models(include_hidden=True)\n",
+    "    selected_model = pick_highest_model(models.data)\n",
+    "    selected_effort = pick_highest_turn_effort(selected_model)\n",
+    "\n",
+    "    print('selected.model:', selected_model.model)\n",
+    "    print('selected.effort:', selected_effort.value)\n",
+    "\n",
+    "    thread = codex.thread_start(model=selected_model.model, config={'model_reasoning_effort': selected_effort.value})\n",
+    "\n",
+    "    first = thread.turn(\n",
+    "        TextInput('Give one short sentence about reliable production releases.'),\n",
+    "        model=selected_model.model,\n",
+    "        effort=selected_effort,\n",
+    "    ).run()\n",
+    "    print('agent.message:', first.text)\n",
+    "    print('usage:', first.usage)\n",
+    "\n",
+    "    second = thread.turn(\n",
+    "        TextInput('Return JSON for a safe feature-flag rollout plan.'),\n",
+    "        approval_policy=AskForApproval.never,\n",
+    "        cwd=str(Path.cwd()),\n",
+    "        effort=selected_effort,\n",
+    "        model=selected_model.model,\n",
+    "        output_schema=output_schema,\n",
+    "        personality=Personality.pragmatic,\n",
+    "        sandbox_policy=sandbox_policy,\n",
+    "        summary=ReasoningSummary.model_validate('concise'),\n",
+    "    ).run()\n",
+    "    print('agent.message.params:', second.text)\n",
+    "    print('usage.params:', second.usage)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 6: multimodal with remote image\n",
+    "remote_image_url = 'https://raw.githubusercontent.com/github/explore/main/topics/python/python.png'\n",
+    "\n",
+    "with Codex() as codex:\n",
+    "    thread = codex.thread_start(model='gpt-5', config={'model_reasoning_effort': 'high'})\n",
+    "    result = thread.turn([\n",
+    "        TextInput('What do you see in this image? 3 bullets.'),\n",
+    "        ImageInput(remote_image_url),\n",
+    "    ]).run()\n",
+    "\n",
+    "    print('status:', result.status)\n",
+    "    print(result.text)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 7: multimodal with local image (bundled asset)\n",
+    "local_image_path = repo_python_dir / 'examples' / 'assets' / 'sample_scene.png'\n",
+    "if not local_image_path.exists():\n",
+    "    raise FileNotFoundError(f'Missing bundled image: {local_image_path}')\n",
+    "\n",
+    "with Codex() as codex:\n",
+    "    thread = codex.thread_start(model='gpt-5', config={'model_reasoning_effort': 'high'})\n",
+    "    result = thread.turn([\n",
+    "        TextInput('Describe this local image in 2 bullets.'),\n",
+    "        LocalImageInput(str(local_image_path.resolve())),\n",
+    "    ]).run()\n",
+    "\n",
+    "    print('status:', result.status)\n",
+    "    print(result.text)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 8: retry-on-overload pattern\n",
+    "with Codex() as codex:\n",
+    "    thread = codex.thread_start(model='gpt-5', config={'model_reasoning_effort': 'high'})\n",
+    "\n",
+    "    result = retry_on_overload(\n",
+    "        lambda: thread.turn(TextInput('List 5 failure modes in distributed systems.')).run(),\n",
+    "        max_attempts=3,\n",
+    "        initial_delay_s=0.25,\n",
+    "        max_delay_s=2.0,\n",
+    "    )\n",
+    "\n",
+    "    print('status:', result.status)\n",
+    "    print(result.text)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 9: full thread lifecycle and branching (async)\n",
+    "import asyncio\n",
+    "\n",
+    "\n",
+    "async def async_lifecycle_demo():\n",
+    "    async with AsyncCodex() as codex:\n",
+    "        thread = await codex.thread_start(model='gpt-5', config={'model_reasoning_effort': 'high'})\n",
+    "        first = await (await thread.turn(TextInput('One sentence about structured planning.'))).run()\n",
+    "        second = await (await thread.turn(TextInput('Now restate it for a junior engineer.'))).run()\n",
+    "\n",
+    "        reopened = await codex.thread_resume(thread.id)\n",
+    "        listing_active = await codex.thread_list(limit=20, archived=False)\n",
+    "        reading = await reopened.read(include_turns=True)\n",
+    "\n",
+    "        _ = await reopened.set_name('sdk-lifecycle-demo')\n",
+    "        _ = await codex.thread_archive(reopened.id)\n",
+    "        listing_archived = await codex.thread_list(limit=20, archived=True)\n",
+    "        unarchived = await codex.thread_unarchive(reopened.id)\n",
+    "\n",
+    "        resumed_info = 'n/a'\n",
+    "        try:\n",
+    "            resumed = await codex.thread_resume(\n",
+    "                unarchived.id,\n",
+    "                model='gpt-5',\n",
+    "                config={'model_reasoning_effort': 'high'},\n",
+    "            )\n",
+    "            resumed_result = await (await resumed.turn(TextInput('Continue in one short sentence.'))).run()\n",
+    "            resumed_info = f'{resumed_result.turn_id} {resumed_result.status}'\n",
+    "        except Exception as e:\n",
+    "            resumed_info = f'skipped({type(e).__name__})'\n",
+    "\n",
+    "        forked_info = 'n/a'\n",
+    "        try:\n",
+    "            forked = await codex.thread_fork(unarchived.id, model='gpt-5')\n",
+    "            forked_result = await (await forked.turn(TextInput('Take a different angle in one short sentence.'))).run()\n",
+    "            forked_info = f'{forked_result.turn_id} {forked_result.status}'\n",
+    "        except Exception as e:\n",
+    "            forked_info = f'skipped({type(e).__name__})'\n",
+    "\n",
+    "        compact_info = 'sent'\n",
+    "        try:\n",
+    "            _ = await unarchived.compact()\n",
+    "        except Exception as e:\n",
+    "            compact_info = f'skipped({type(e).__name__})'\n",
+    "\n",
+    "        print('Lifecycle OK:', thread.id)\n",
+    "        print('first:', first.turn_id, first.status)\n",
+    "        print('second:', second.turn_id, second.status)\n",
+    "        print('read.turns:', len(reading.thread.turns or []))\n",
+    "        print('list.active:', len(listing_active.data))\n",
+    "        print('list.archived:', len(listing_archived.data))\n",
+    "        print('resumed:', resumed_info)\n",
+    "        print('forked:', forked_info)\n",
+    "        print('compact:', compact_info)\n",
+    "\n",
+    "\n",
+    "await async_lifecycle_demo()\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cell 10: async stream + steer + interrupt (best effort)\n",
+    "import asyncio\n",
+    "\n",
+    "\n",
+    "async def async_stream_demo():\n",
+    "    async with AsyncCodex() as codex:\n",
+    "        thread = await codex.thread_start(model='gpt-5', config={'model_reasoning_effort': 'high'})\n",
+    "        turn = await thread.turn(TextInput('Count from 1 to 200 with commas, then one summary sentence.'))\n",
+    "\n",
+    "        try:\n",
+    "            _ = await turn.steer(TextInput('Keep it brief and stop after 20 numbers.'))\n",
+    "            print('steer: sent')\n",
+    "        except Exception as e:\n",
+    "            print('steer: skipped', type(e).__name__)\n",
+    "\n",
+    "        try:\n",
+    "            _ = await turn.interrupt()\n",
+    "            print('interrupt: sent')\n",
+    "        except Exception as e:\n",
+    "            print('interrupt: skipped', type(e).__name__)\n",
+    "\n",
+    "        event_count = 0\n",
+    "        async for event in turn.stream():\n",
+    "            event_count += 1\n",
+    "            print(event.method, event.payload)\n",
+    "\n",
+    "        print('events.count:', event_count)\n",
+    "\n",
+    "\n",
+    "await async_stream_demo()\n",
+    "\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10+"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

sdk/python/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codex-app-server-sdk"
+version = "0.2.0"
+description = "Python SDK for Codex app-server v2"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "OpenClaw Assistant" }]
+keywords = ["codex", "json-rpc", "sdk", "llm", "app-server"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["pydantic>=2.12"]
+
+[project.urls]
+Homepage = "https://github.com/openai/codex"
+Repository = "https://github.com/openai/codex"
+Issues = "https://github.com/openai/codex/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "datamodel-code-generator==0.31.2", "ruff>=0.11"]
+
+[tool.hatch.build]
+exclude = [
+  ".venv/**",
+  ".venv2/**",
+  ".pytest_cache/**",
+  "dist/**",
+  "build/**",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codex_app_server"]
+include = [
+  "src/codex_app_server/py.typed",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/codex_app_server/**",
+  "README.md",
+  "CHANGELOG.md",
+  "CONTRIBUTING.md",
+  "RELEASE_CHECKLIST.md",
+  "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

sdk/python/scripts/update_sdk_artifacts.py

@@ -0,0 +1,998 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import platform
+import re
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import types
+import typing
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Sequence, get_args, get_origin
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[3]
+
+
+def sdk_root() -> Path:
+    return repo_root() / "sdk" / "python"
+
+
+def python_runtime_root() -> Path:
+    return repo_root() / "sdk" / "python-runtime"
+
+
+def schema_bundle_path() -> Path:
+    return (
+        repo_root()
+        / "codex-rs"
+        / "app-server-protocol"
+        / "schema"
+        / "json"
+        / "codex_app_server_protocol.v2.schemas.json"
+    )
+
+
+def schema_root_dir() -> Path:
+    return repo_root() / "codex-rs" / "app-server-protocol" / "schema" / "json"
+
+
+def _is_windows() -> bool:
+    return platform.system().lower().startswith("win")
+
+
+def runtime_binary_name() -> str:
+    return "codex.exe" if _is_windows() else "codex"
+
+
+def staged_runtime_bin_path(root: Path) -> Path:
+    return root / "src" / "codex_cli_bin" / "bin" / runtime_binary_name()
+
+
+def run(cmd: list[str], cwd: Path) -> None:
+    subprocess.run(cmd, cwd=str(cwd), check=True)
+
+
+def run_python_module(module: str, args: list[str], cwd: Path) -> None:
+    run([sys.executable, "-m", module, *args], cwd)
+
+
+def current_sdk_version() -> str:
+    match = re.search(
+        r'^version = "([^"]+)"$',
+        (sdk_root() / "pyproject.toml").read_text(),
+        flags=re.MULTILINE,
+    )
+    if match is None:
+        raise RuntimeError("Could not determine Python SDK version from pyproject.toml")
+    return match.group(1)
+
+
+def _copy_package_tree(src: Path, dst: Path) -> None:
+    if dst.exists():
+        if dst.is_dir():
+            shutil.rmtree(dst)
+        else:
+            dst.unlink()
+    shutil.copytree(
+        src,
+        dst,
+        ignore=shutil.ignore_patterns(
+            ".venv",
+            ".venv2",
+            ".pytest_cache",
+            "__pycache__",
+            "build",
+            "dist",
+            "*.pyc",
+        ),
+    )
+
+
+def _rewrite_project_version(pyproject_text: str, version: str) -> str:
+    updated, count = re.subn(
+        r'^version = "[^"]+"$',
+        f'version = "{version}"',
+        pyproject_text,
+        count=1,
+        flags=re.MULTILINE,
+    )
+    if count != 1:
+        raise RuntimeError("Could not rewrite project version in pyproject.toml")
+    return updated
+
+
+def _rewrite_sdk_runtime_dependency(pyproject_text: str, runtime_version: str) -> str:
+    match = re.search(r"^dependencies = \[(.*?)\]$", pyproject_text, flags=re.MULTILINE)
+    if match is None:
+        raise RuntimeError(
+            "Could not find dependencies array in sdk/python/pyproject.toml"
+        )
+
+    raw_items = [item.strip() for item in match.group(1).split(",") if item.strip()]
+    raw_items = [item for item in raw_items if "codex-cli-bin" not in item]
+    raw_items.append(f'"codex-cli-bin=={runtime_version}"')
+    replacement = "dependencies = [\n  " + ",\n  ".join(raw_items) + ",\n]"
+    return pyproject_text[: match.start()] + replacement + pyproject_text[match.end() :]
+
+
+def stage_python_sdk_package(
+    staging_dir: Path, sdk_version: str, runtime_version: str
+) -> Path:
+    _copy_package_tree(sdk_root(), staging_dir)
+    sdk_bin_dir = staging_dir / "src" / "codex_app_server" / "bin"
+    if sdk_bin_dir.exists():
+        shutil.rmtree(sdk_bin_dir)
+
+    pyproject_path = staging_dir / "pyproject.toml"
+    pyproject_text = pyproject_path.read_text()
+    pyproject_text = _rewrite_project_version(pyproject_text, sdk_version)
+    pyproject_text = _rewrite_sdk_runtime_dependency(pyproject_text, runtime_version)
+    pyproject_path.write_text(pyproject_text)
+    return staging_dir
+
+
+def stage_python_runtime_package(
+    staging_dir: Path, runtime_version: str, binary_path: Path
+) -> Path:
+    _copy_package_tree(python_runtime_root(), staging_dir)
+
+    pyproject_path = staging_dir / "pyproject.toml"
+    pyproject_path.write_text(
+        _rewrite_project_version(pyproject_path.read_text(), runtime_version)
+    )
+
+    out_bin = staged_runtime_bin_path(staging_dir)
+    out_bin.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(binary_path, out_bin)
+    if not _is_windows():
+        out_bin.chmod(
+            out_bin.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+        )
+    return staging_dir
+
+
+def _flatten_string_enum_one_of(definition: dict[str, Any]) -> bool:
+    branches = definition.get("oneOf")
+    if not isinstance(branches, list) or not branches:
+        return False
+
+    enum_values: list[str] = []
+    for branch in branches:
+        if not isinstance(branch, dict):
+            return False
+        if branch.get("type") != "string":
+            return False
+
+        enum = branch.get("enum")
+        if not isinstance(enum, list) or len(enum) != 1 or not isinstance(enum[0], str):
+            return False
+
+        extra_keys = set(branch) - {"type", "enum", "description", "title"}
+        if extra_keys:
+            return False
+
+        enum_values.append(enum[0])
+
+    description = definition.get("description")
+    title = definition.get("title")
+    definition.clear()
+    definition["type"] = "string"
+    definition["enum"] = enum_values
+    if isinstance(description, str):
+        definition["description"] = description
+    if isinstance(title, str):
+        definition["title"] = title
+    return True
+
+
+DISCRIMINATOR_KEYS = ("type", "method", "mode", "state", "status", "role", "reason")
+
+
+def _to_pascal_case(value: str) -> str:
+    parts = re.split(r"[^0-9A-Za-z]+", value)
+    compact = "".join(part[:1].upper() + part[1:] for part in parts if part)
+    return compact or "Value"
+
+
+def _string_literal(value: Any) -> str | None:
+    if not isinstance(value, dict):
+        return None
+    const = value.get("const")
+    if isinstance(const, str):
+        return const
+
+    enum = value.get("enum")
+    if isinstance(enum, list) and enum and len(enum) == 1 and isinstance(enum[0], str):
+        return enum[0]
+    return None
+
+
+def _enum_literals(value: Any) -> list[str] | None:
+    if not isinstance(value, dict):
+        return None
+    enum = value.get("enum")
+    if (
+        not isinstance(enum, list)
+        or not enum
+        or not all(isinstance(item, str) for item in enum)
+    ):
+        return None
+    return list(enum)
+
+
+def _literal_from_property(props: dict[str, Any], key: str) -> str | None:
+    return _string_literal(props.get(key))
+
+
+def _variant_definition_name(base: str, variant: dict[str, Any]) -> str | None:
+    # datamodel-code-generator invents numbered helper names for inline union
+    # branches unless they carry a stable, unique title up front. We derive
+    # those titles from the branch discriminator or other identifying shape.
+    props = variant.get("properties")
+    if isinstance(props, dict):
+        for key in DISCRIMINATOR_KEYS:
+            literal = _literal_from_property(props, key)
+            if literal is None:
+                continue
+            pascal = _to_pascal_case(literal)
+            if base == "ClientRequest":
+                return f"{pascal}Request"
+            if base == "ServerRequest":
+                return f"{pascal}ServerRequest"
+            if base == "ClientNotification":
+                return f"{pascal}ClientNotification"
+            if base == "ServerNotification":
+                return f"{pascal}ServerNotification"
+            if base == "EventMsg":
+                return f"{pascal}EventMsg"
+            return f"{pascal}{base}"
+
+        if len(props) == 1:
+            key = next(iter(props))
+            pascal = _string_literal(props[key])
+            return f"{_to_pascal_case(pascal or key)}{base}"
+
+    required = variant.get("required")
+    if (
+        isinstance(required, list)
+        and len(required) == 1
+        and isinstance(required[0], str)
+    ):
+        return f"{_to_pascal_case(required[0])}{base}"
+
+    enum_literals = _enum_literals(variant)
+    if enum_literals is not None:
+        if len(enum_literals) == 1:
+            return f"{_to_pascal_case(enum_literals[0])}{base}"
+        return f"{base}Value"
+
+    return None
+
+
+def _variant_collision_key(
+    base: str, variant: dict[str, Any], generated_name: str
+) -> str:
+    parts = [f"base={base}", f"generated={generated_name}"]
+    props = variant.get("properties")
+    if isinstance(props, dict):
+        for key in DISCRIMINATOR_KEYS:
+            literal = _literal_from_property(props, key)
+            if literal is not None:
+                parts.append(f"{key}={literal}")
+        if len(props) == 1:
+            parts.append(f"only_property={next(iter(props))}")
+
+    required = variant.get("required")
+    if (
+        isinstance(required, list)
+        and len(required) == 1
+        and isinstance(required[0], str)
+    ):
+        parts.append(f"required_only={required[0]}")
+
+    enum_literals = _enum_literals(variant)
+    if enum_literals is not None:
+        parts.append(f"enum={'|'.join(enum_literals)}")
+
+    return "|".join(parts)
+
+
+def _set_discriminator_titles(props: dict[str, Any], owner: str) -> None:
+    for key in DISCRIMINATOR_KEYS:
+        prop = props.get(key)
+        if not isinstance(prop, dict):
+            continue
+        if _string_literal(prop) is None or "title" in prop:
+            continue
+        prop["title"] = f"{owner}{_to_pascal_case(key)}"
+
+
+def _annotate_variant_list(variants: list[Any], base: str | None) -> None:
+    seen = {
+        variant["title"]
+        for variant in variants
+        if isinstance(variant, dict) and isinstance(variant.get("title"), str)
+    }
+
+    for variant in variants:
+        if not isinstance(variant, dict):
+            continue
+
+        variant_name = variant.get("title")
+        generated_name = _variant_definition_name(base, variant) if base else None
+        if generated_name is not None and (
+            not isinstance(variant_name, str)
+            or "/" in variant_name
+            or variant_name != generated_name
+        ):
+            # Titles like `Thread/startedNotification` sanitize poorly in
+            # Python, and envelope titles like `ErrorNotification` collide
+            # with their payload model names. Rewrite them before codegen so
+            # we get `ThreadStartedServerNotification` instead of `...1`.
+            if generated_name in seen and variant_name != generated_name:
+                raise RuntimeError(
+                    "Variant title naming collision detected: "
+                    f"{_variant_collision_key(base or '<root>', variant, generated_name)}"
+                )
+            variant["title"] = generated_name
+            seen.add(generated_name)
+            variant_name = generated_name
+
+        if isinstance(variant_name, str):
+            props = variant.get("properties")
+            if isinstance(props, dict):
+                _set_discriminator_titles(props, variant_name)
+
+        _annotate_schema(variant, base)
+
+
+def _annotate_schema(value: Any, base: str | None = None) -> None:
+    if isinstance(value, list):
+        for item in value:
+            _annotate_schema(item, base)
+        return
+
+    if not isinstance(value, dict):
+        return
+
+    owner = value.get("title")
+    props = value.get("properties")
+    if isinstance(owner, str) and isinstance(props, dict):
+        _set_discriminator_titles(props, owner)
+
+    one_of = value.get("oneOf")
+    if isinstance(one_of, list):
+        # Walk nested unions recursively so every inline branch gets the same
+        # title normalization treatment before we hand the bundle to Python
+        # codegen.
+        _annotate_variant_list(one_of, base)
+
+    any_of = value.get("anyOf")
+    if isinstance(any_of, list):
+        _annotate_variant_list(any_of, base)
+
+    definitions = value.get("definitions")
+    if isinstance(definitions, dict):
+        for name, schema in definitions.items():
+            _annotate_schema(schema, name if isinstance(name, str) else base)
+
+    defs = value.get("$defs")
+    if isinstance(defs, dict):
+        for name, schema in defs.items():
+            _annotate_schema(schema, name if isinstance(name, str) else base)
+
+    for key, child in value.items():
+        if key in {"oneOf", "anyOf", "definitions", "$defs"}:
+            continue
+        _annotate_schema(child, base)
+
+
+def _normalized_schema_bundle_text() -> str:
+    schema = json.loads(schema_bundle_path().read_text())
+    definitions = schema.get("definitions", {})
+    if isinstance(definitions, dict):
+        for definition in definitions.values():
+            if isinstance(definition, dict):
+                _flatten_string_enum_one_of(definition)
+    # Normalize the schema into something datamodel-code-generator can map to
+    # stable class names instead of anonymous numbered helpers.
+    _annotate_schema(schema)
+    return json.dumps(schema, indent=2, sort_keys=True) + "\n"
+
+
+def generate_v2_all() -> None:
+    out_path = sdk_root() / "src" / "codex_app_server" / "generated" / "v2_all.py"
+    out_dir = out_path.parent
+    old_package_dir = out_dir / "v2_all"
+    if old_package_dir.exists():
+        shutil.rmtree(old_package_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory() as td:
+        normalized_bundle = Path(td) / schema_bundle_path().name
+        normalized_bundle.write_text(_normalized_schema_bundle_text())
+        run_python_module(
+            "datamodel_code_generator",
+            [
+                "--input",
+                str(normalized_bundle),
+                "--input-file-type",
+                "jsonschema",
+                "--output",
+                str(out_path),
+                "--output-model-type",
+                "pydantic_v2.BaseModel",
+                "--target-python-version",
+                "3.11",
+                "--use-standard-collections",
+                "--enum-field-as-literal",
+                "one",
+                "--field-constraints",
+                "--use-default-kwarg",
+                "--snake-case-field",
+                "--allow-population-by-field-name",
+                # Once the schema prepass has assigned stable titles, tell the
+                # generator to prefer those titles as the emitted class names.
+                "--use-title-as-name",
+                "--use-annotated",
+                "--use-union-operator",
+                "--disable-timestamp",
+                # Keep the generated file formatted deterministically so the
+                # checked-in artifact only changes when the schema does.
+                "--formatters",
+                "ruff-format",
+            ],
+            cwd=sdk_root(),
+        )
+    _normalize_generated_timestamps(out_path)
+
+
+def _notification_specs() -> list[tuple[str, str]]:
+    server_notifications = json.loads(
+        (schema_root_dir() / "ServerNotification.json").read_text()
+    )
+    one_of = server_notifications.get("oneOf", [])
+    generated_source = (
+        sdk_root() / "src" / "codex_app_server" / "generated" / "v2_all.py"
+    ).read_text()
+
+    specs: list[tuple[str, str]] = []
+
+    for variant in one_of:
+        props = variant.get("properties", {})
+        method_meta = props.get("method", {})
+        params_meta = props.get("params", {})
+
+        methods = method_meta.get("enum", [])
+        if len(methods) != 1:
+            continue
+        method = methods[0]
+        if not isinstance(method, str):
+            continue
+
+        ref = params_meta.get("$ref")
+        if not isinstance(ref, str) or not ref.startswith("#/definitions/"):
+            continue
+        class_name = ref.split("/")[-1]
+        if (
+            f"class {class_name}(" not in generated_source
+            and f"{class_name} =" not in generated_source
+        ):
+            # Skip schema variants that are not emitted into the generated v2 surface.
+            continue
+        specs.append((method, class_name))
+
+    specs.sort()
+    return specs
+
+
+def generate_notification_registry() -> None:
+    out = (
+        sdk_root()
+        / "src"
+        / "codex_app_server"
+        / "generated"
+        / "notification_registry.py"
+    )
+    specs = _notification_specs()
+    class_names = sorted({class_name for _, class_name in specs})
+
+    lines = [
+        "# Auto-generated by scripts/update_sdk_artifacts.py",
+        "# DO NOT EDIT MANUALLY.",
+        "",
+        "from __future__ import annotations",
+        "",
+        "from pydantic import BaseModel",
+        "",
+    ]
+
+    for class_name in class_names:
+        lines.append(f"from .v2_all import {class_name}")
+    lines.extend(
+        [
+            "",
+            "NOTIFICATION_MODELS: dict[str, type[BaseModel]] = {",
+        ]
+    )
+    for method, class_name in specs:
+        lines.append(f'    "{method}": {class_name},')
+    lines.extend(["}", ""])
+
+    out.write_text("\n".join(lines))
+
+
+def _normalize_generated_timestamps(root: Path) -> None:
+    timestamp_re = re.compile(r"^#\s+timestamp:\s+.+$", flags=re.MULTILINE)
+    py_files = [root] if root.is_file() else sorted(root.rglob("*.py"))
+    for py_file in py_files:
+        content = py_file.read_text()
+        normalized = timestamp_re.sub("#   timestamp: <normalized>", content)
+        if normalized != content:
+            py_file.write_text(normalized)
+
+
+FIELD_ANNOTATION_OVERRIDES: dict[str, str] = {
+    # Keep public API typed without falling back to `Any`.
+    "config": "JsonObject",
+    "output_schema": "JsonObject",
+}
+
+
+@dataclass(slots=True)
+class PublicFieldSpec:
+    wire_name: str
+    py_name: str
+    annotation: str
+    required: bool
+
+
+@dataclass(frozen=True)
+class CliOps:
+    generate_types: Callable[[], None]
+    stage_python_sdk_package: Callable[[Path, str, str], Path]
+    stage_python_runtime_package: Callable[[Path, str, Path], Path]
+    current_sdk_version: Callable[[], str]
+
+
+def _annotation_to_source(annotation: Any) -> str:
+    origin = get_origin(annotation)
+    if origin is typing.Annotated:
+        return _annotation_to_source(get_args(annotation)[0])
+    if origin in (typing.Union, types.UnionType):
+        parts: list[str] = []
+        for arg in get_args(annotation):
+            rendered = _annotation_to_source(arg)
+            if rendered not in parts:
+                parts.append(rendered)
+        return " | ".join(parts)
+    if origin is list:
+        args = get_args(annotation)
+        item = _annotation_to_source(args[0]) if args else "Any"
+        return f"list[{item}]"
+    if origin is dict:
+        args = get_args(annotation)
+        key = _annotation_to_source(args[0]) if args else "str"
+        val = _annotation_to_source(args[1]) if len(args) > 1 else "Any"
+        return f"dict[{key}, {val}]"
+    if annotation is Any or annotation is typing.Any:
+        return "Any"
+    if annotation is None or annotation is type(None):
+        return "None"
+    if isinstance(annotation, type):
+        if annotation.__module__ == "builtins":
+            return annotation.__name__
+        return annotation.__name__
+    return repr(annotation)
+
+
+def _camel_to_snake(name: str) -> str:
+    head = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", name)
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", head).lower()
+
+
+def _load_public_fields(
+    module_name: str, class_name: str, *, exclude: set[str] | None = None
+) -> list[PublicFieldSpec]:
+    exclude = exclude or set()
+    module = importlib.import_module(module_name)
+    model = getattr(module, class_name)
+    fields: list[PublicFieldSpec] = []
+    for name, field in model.model_fields.items():
+        if name in exclude:
+            continue
+        required = field.is_required()
+        annotation = _annotation_to_source(field.annotation)
+        override = FIELD_ANNOTATION_OVERRIDES.get(name)
+        if override is not None:
+            annotation = override if required else f"{override} | None"
+        fields.append(
+            PublicFieldSpec(
+                wire_name=name,
+                py_name=name,
+                annotation=annotation,
+                required=required,
+            )
+        )
+    return fields
+
+
+def _kw_signature_lines(fields: list[PublicFieldSpec]) -> list[str]:
+    lines: list[str] = []
+    for field in fields:
+        default = "" if field.required else " = None"
+        lines.append(f"        {field.py_name}: {field.annotation}{default},")
+    return lines
+
+
+def _model_arg_lines(
+    fields: list[PublicFieldSpec], *, indent: str = "            "
+) -> list[str]:
+    return [f"{indent}{field.wire_name}={field.py_name}," for field in fields]
+
+
+def _replace_generated_block(source: str, block_name: str, body: str) -> str:
+    start_tag = f"    # BEGIN GENERATED: {block_name}"
+    end_tag = f"    # END GENERATED: {block_name}"
+    pattern = re.compile(rf"(?s){re.escape(start_tag)}\n.*?\n{re.escape(end_tag)}")
+    replacement = f"{start_tag}\n{body.rstrip()}\n{end_tag}"
+    updated, count = pattern.subn(replacement, source, count=1)
+    if count != 1:
+        raise RuntimeError(f"Could not update generated block: {block_name}")
+    return updated
+
+
+def _render_codex_block(
+    thread_start_fields: list[PublicFieldSpec],
+    thread_list_fields: list[PublicFieldSpec],
+    resume_fields: list[PublicFieldSpec],
+    fork_fields: list[PublicFieldSpec],
+) -> str:
+    lines = [
+        "    def thread_start(",
+        "        self,",
+        "        *,",
+        *_kw_signature_lines(thread_start_fields),
+        "    ) -> Thread:",
+        "        params = ThreadStartParams(",
+        *_model_arg_lines(thread_start_fields),
+        "        )",
+        "        started = self._client.thread_start(params)",
+        "        return Thread(self._client, started.thread.id)",
+        "",
+        "    def thread_list(",
+        "        self,",
+        "        *,",
+        *_kw_signature_lines(thread_list_fields),
+        "    ) -> ThreadListResponse:",
+        "        params = ThreadListParams(",
+        *_model_arg_lines(thread_list_fields),
+        "        )",
+        "        return self._client.thread_list(params)",
+        "",
+        "    def thread_resume(",
+        "        self,",
+        "        thread_id: str,",
+        "        *,",
+        *_kw_signature_lines(resume_fields),
+        "    ) -> Thread:",
+        "        params = ThreadResumeParams(",
+        "            thread_id=thread_id,",
+        *_model_arg_lines(resume_fields),
+        "        )",
+        "        resumed = self._client.thread_resume(thread_id, params)",
+        "        return Thread(self._client, resumed.thread.id)",
+        "",
+        "    def thread_fork(",
+        "        self,",
+        "        thread_id: str,",
+        "        *,",
+        *_kw_signature_lines(fork_fields),
+        "    ) -> Thread:",
+        "        params = ThreadForkParams(",
+        "            thread_id=thread_id,",
+        *_model_arg_lines(fork_fields),
+        "        )",
+        "        forked = self._client.thread_fork(thread_id, params)",
+        "        return Thread(self._client, forked.thread.id)",
+        "",
+        "    def thread_archive(self, thread_id: str) -> ThreadArchiveResponse:",
+        "        return self._client.thread_archive(thread_id)",
+        "",
+        "    def thread_unarchive(self, thread_id: str) -> Thread:",
+        "        unarchived = self._client.thread_unarchive(thread_id)",
+        "        return Thread(self._client, unarchived.thread.id)",
+    ]
+    return "\n".join(lines)
+
+
+def _render_async_codex_block(
+    thread_start_fields: list[PublicFieldSpec],
+    thread_list_fields: list[PublicFieldSpec],
+    resume_fields: list[PublicFieldSpec],
+    fork_fields: list[PublicFieldSpec],
+) -> str:
+    lines = [
+        "    async def thread_start(",
+        "        self,",
+        "        *,",
+        *_kw_signature_lines(thread_start_fields),
+        "    ) -> AsyncThread:",
+        "        await self._ensure_initialized()",
+        "        params = ThreadStartParams(",
+        *_model_arg_lines(thread_start_fields),
+        "        )",
+        "        started = await self._client.thread_start(params)",
+        "        return AsyncThread(self, started.thread.id)",
+        "",
+        "    async def thread_list(",
+        "        self,",
+        "        *,",
+        *_kw_signature_lines(thread_list_fields),
+        "    ) -> ThreadListResponse:",
+        "        await self._ensure_initialized()",
+        "        params = ThreadListParams(",
+        *_model_arg_lines(thread_list_fields),
+        "        )",
+        "        return await self._client.thread_list(params)",
+        "",
+        "    async def thread_resume(",
+        "        self,",
+        "        thread_id: str,",
+        "        *,",
+        *_kw_signature_lines(resume_fields),
+        "    ) -> AsyncThread:",
+        "        await self._ensure_initialized()",
+        "        params = ThreadResumeParams(",
+        "            thread_id=thread_id,",
+        *_model_arg_lines(resume_fields),
+        "        )",
+        "        resumed = await self._client.thread_resume(thread_id, params)",
+        "        return AsyncThread(self, resumed.thread.id)",
+        "",
+        "    async def thread_fork(",
+        "        self,",
+        "        thread_id: str,",
+        "        *,",
+        *_kw_signature_lines(fork_fields),
+        "    ) -> AsyncThread:",
+        "        await self._ensure_initialized()",
+        "        params = ThreadForkParams(",
+        "            thread_id=thread_id,",
+        *_model_arg_lines(fork_fields),
+        "        )",
+        "        forked = await self._client.thread_fork(thread_id, params)",
+        "        return AsyncThread(self, forked.thread.id)",
+        "",
+        "    async def thread_archive(self, thread_id: str) -> ThreadArchiveResponse:",
+        "        await self._ensure_initialized()",
+        "        return await self._client.thread_archive(thread_id)",
+        "",
+        "    async def thread_unarchive(self, thread_id: str) -> AsyncThread:",
+        "        await self._ensure_initialized()",
+        "        unarchived = await self._client.thread_unarchive(thread_id)",
+        "        return AsyncThread(self, unarchived.thread.id)",
+    ]
+    return "\n".join(lines)
+
+
+def _render_thread_block(
+    turn_fields: list[PublicFieldSpec],
+) -> str:
+    lines = [
+        "    def turn(",
+        "        self,",
+        "        input: Input,",
+        "        *,",
+        *_kw_signature_lines(turn_fields),
+        "    ) -> Turn:",
+        "        wire_input = _to_wire_input(input)",
+        "        params = TurnStartParams(",
+        "            thread_id=self.id,",
+        "            input=wire_input,",
+        *_model_arg_lines(turn_fields),
+        "        )",
+        "        turn = self._client.turn_start(self.id, wire_input, params=params)",
+        "        return Turn(self._client, self.id, turn.turn.id)",
+    ]
+    return "\n".join(lines)
+
+
+def _render_async_thread_block(
+    turn_fields: list[PublicFieldSpec],
+) -> str:
+    lines = [
+        "    async def turn(",
+        "        self,",
+        "        input: Input,",
+        "        *,",
+        *_kw_signature_lines(turn_fields),
+        "    ) -> AsyncTurn:",
+        "        await self._codex._ensure_initialized()",
+        "        wire_input = _to_wire_input(input)",
+        "        params = TurnStartParams(",
+        "            thread_id=self.id,",
+        "            input=wire_input,",
+        *_model_arg_lines(turn_fields),
+        "        )",
+        "        turn = await self._codex._client.turn_start(",
+        "            self.id,",
+        "            wire_input,",
+        "            params=params,",
+        "        )",
+        "        return AsyncTurn(self._codex, self.id, turn.turn.id)",
+    ]
+    return "\n".join(lines)
+
+
+def generate_public_api_flat_methods() -> None:
+    src_dir = sdk_root() / "src"
+    public_api_path = src_dir / "codex_app_server" / "public_api.py"
+    if not public_api_path.exists():
+        # PR2 can run codegen before the ergonomic public API layer is added.
+        return
+    src_dir_str = str(src_dir)
+    if src_dir_str not in sys.path:
+        sys.path.insert(0, src_dir_str)
+
+    thread_start_fields = _load_public_fields(
+        "codex_app_server.generated.v2_all",
+        "ThreadStartParams",
+    )
+    thread_list_fields = _load_public_fields(
+        "codex_app_server.generated.v2_all",
+        "ThreadListParams",
+    )
+    thread_resume_fields = _load_public_fields(
+        "codex_app_server.generated.v2_all",
+        "ThreadResumeParams",
+        exclude={"thread_id"},
+    )
+    thread_fork_fields = _load_public_fields(
+        "codex_app_server.generated.v2_all",
+        "ThreadForkParams",
+        exclude={"thread_id"},
+    )
+    turn_start_fields = _load_public_fields(
+        "codex_app_server.generated.v2_all",
+        "TurnStartParams",
+        exclude={"thread_id", "input"},
+    )
+
+    source = public_api_path.read_text()
+    source = _replace_generated_block(
+        source,
+        "Codex.flat_methods",
+        _render_codex_block(
+            thread_start_fields,
+            thread_list_fields,
+            thread_resume_fields,
+            thread_fork_fields,
+        ),
+    )
+    source = _replace_generated_block(
+        source,
+        "AsyncCodex.flat_methods",
+        _render_async_codex_block(
+            thread_start_fields,
+            thread_list_fields,
+            thread_resume_fields,
+            thread_fork_fields,
+        ),
+    )
+    source = _replace_generated_block(
+        source,
+        "Thread.flat_methods",
+        _render_thread_block(turn_start_fields),
+    )
+    source = _replace_generated_block(
+        source,
+        "AsyncThread.flat_methods",
+        _render_async_thread_block(turn_start_fields),
+    )
+    public_api_path.write_text(source)
+
+
+def generate_types() -> None:
+    # v2_all is the authoritative generated surface.
+    generate_v2_all()
+    generate_notification_registry()
+    generate_public_api_flat_methods()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Single SDK maintenance entrypoint")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser(
+        "generate-types", help="Regenerate Python protocol-derived types"
+    )
+
+    stage_sdk_parser = subparsers.add_parser(
+        "stage-sdk",
+        help="Stage a releasable SDK package pinned to a runtime version",
+    )
+    stage_sdk_parser.add_argument(
+        "staging_dir",
+        type=Path,
+        help="Output directory for the staged SDK package",
+    )
+    stage_sdk_parser.add_argument(
+        "--runtime-version",
+        required=True,
+        help="Pinned codex-cli-bin version for the staged SDK package",
+    )
+    stage_sdk_parser.add_argument(
+        "--sdk-version",
+        help="Version to write into the staged SDK package (defaults to sdk/python current version)",
+    )
+
+    stage_runtime_parser = subparsers.add_parser(
+        "stage-runtime",
+        help="Stage a releasable runtime package for the current platform",
+    )
+    stage_runtime_parser.add_argument(
+        "staging_dir",
+        type=Path,
+        help="Output directory for the staged runtime package",
+    )
+    stage_runtime_parser.add_argument(
+        "runtime_binary",
+        type=Path,
+        help="Path to the codex binary to package for this platform",
+    )
+    stage_runtime_parser.add_argument(
+        "--runtime-version",
+        required=True,
+        help="Version to write into the staged runtime package",
+    )
+    return parser
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    return build_parser().parse_args(list(argv) if argv is not None else None)
+
+
+def default_cli_ops() -> CliOps:
+    return CliOps(
+        generate_types=generate_types,
+        stage_python_sdk_package=stage_python_sdk_package,
+        stage_python_runtime_package=stage_python_runtime_package,
+        current_sdk_version=current_sdk_version,
+    )
+
+
+def run_command(args: argparse.Namespace, ops: CliOps) -> None:
+    if args.command == "generate-types":
+        ops.generate_types()
+    elif args.command == "stage-sdk":
+        ops.generate_types()
+        ops.stage_python_sdk_package(
+            args.staging_dir,
+            args.sdk_version or ops.current_sdk_version(),
+            args.runtime_version,
+        )
+    elif args.command == "stage-runtime":
+        ops.stage_python_runtime_package(
+            args.staging_dir,
+            args.runtime_version,
+            args.runtime_binary.resolve(),
+        )
+
+
+def main(argv: Sequence[str] | None = None, ops: CliOps | None = None) -> None:
+    args = parse_args(argv)
+    run_command(args, ops or default_cli_ops())
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

sdk/python/src/codex_app_server/__init__.py

@@ -0,0 +1,115 @@
+from .async_client import AsyncAppServerClient
+from .client import AppServerClient, AppServerConfig
+from .errors import (
+    AppServerError,
+    AppServerRpcError,
+    InternalRpcError,
+    InvalidParamsError,
+    InvalidRequestError,
+    JsonRpcError,
+    MethodNotFoundError,
+    ParseError,
+    RetryLimitExceededError,
+    ServerBusyError,
+    TransportClosedError,
+    is_retryable_error,
+)
+from .generated.v2_types import (
+    ThreadItem,
+    ThreadTokenUsageUpdatedNotification,
+    TurnCompletedNotificationPayload,
+)
+from .public_api import (
+    AsyncCodex,
+    AsyncThread,
+    AsyncTurn,
+    Codex,
+    ImageInput,
+    InitializeResult,
+    Input,
+    InputItem,
+    LocalImageInput,
+    MentionInput,
+    SkillInput,
+    TextInput,
+    Thread,
+    Turn,
+    TurnResult,
+)
+from .public_types import (
+    AskForApproval,
+    Personality,
+    PlanType,
+    ReasoningEffort,
+    ReasoningSummary,
+    SandboxMode,
+    SandboxPolicy,
+    ServiceTier,
+    ThreadForkParams,
+    ThreadListParams,
+    ThreadResumeParams,
+    ThreadSortKey,
+    ThreadSourceKind,
+    ThreadStartParams,
+    TurnStartParams,
+    TurnStatus,
+    TurnSteerParams,
+)
+from .retry import retry_on_overload
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    "AppServerClient",
+    "AsyncAppServerClient",
+    "AppServerConfig",
+    "Codex",
+    "AsyncCodex",
+    "Thread",
+    "AsyncThread",
+    "Turn",
+    "AsyncTurn",
+    "TurnResult",
+    "InitializeResult",
+    "Input",
+    "InputItem",
+    "TextInput",
+    "ImageInput",
+    "LocalImageInput",
+    "SkillInput",
+    "MentionInput",
+    "ThreadItem",
+    "ThreadTokenUsageUpdatedNotification",
+    "TurnCompletedNotificationPayload",
+    "AskForApproval",
+    "Personality",
+    "PlanType",
+    "ReasoningEffort",
+    "ReasoningSummary",
+    "SandboxMode",
+    "SandboxPolicy",
+    "ServiceTier",
+    "ThreadStartParams",
+    "ThreadResumeParams",
+    "ThreadListParams",
+    "ThreadSortKey",
+    "ThreadSourceKind",
+    "ThreadForkParams",
+    "TurnStatus",
+    "TurnStartParams",
+    "TurnSteerParams",
+    "retry_on_overload",
+    "AppServerError",
+    "TransportClosedError",
+    "JsonRpcError",
+    "AppServerRpcError",
+    "ParseError",
+    "InvalidRequestError",
+    "MethodNotFoundError",
+    "InvalidParamsError",
+    "InternalRpcError",
+    "ServerBusyError",
+    "RetryLimitExceededError",
+    "is_retryable_error",
+]

sdk/python/src/codex_app_server/async_client.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterator
+from typing import AsyncIterator, Callable, Iterable, ParamSpec, TypeVar
+
+from pydantic import BaseModel
+
+from .client import AppServerClient, AppServerConfig
+from .generated.v2_all import (
+    AgentMessageDeltaNotification,
+    ModelListResponse,
+    ThreadArchiveResponse,
+    ThreadCompactStartResponse,
+    ThreadForkParams as V2ThreadForkParams,
+    ThreadForkResponse,
+    ThreadListParams as V2ThreadListParams,
+    ThreadListResponse,
+    ThreadReadResponse,
+    ThreadResumeParams as V2ThreadResumeParams,
+    ThreadResumeResponse,
+    ThreadSetNameResponse,
+    ThreadStartParams as V2ThreadStartParams,
+    ThreadStartResponse,
+    ThreadUnarchiveResponse,
+    TurnCompletedNotification,
+    TurnInterruptResponse,
+    TurnStartParams as V2TurnStartParams,
+    TurnStartResponse,
+    TurnSteerResponse,
+)
+from .models import InitializeResponse, JsonObject, Notification
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+ParamsT = ParamSpec("ParamsT")
+ReturnT = TypeVar("ReturnT")
+
+
+class AsyncAppServerClient:
+    """Async wrapper around AppServerClient using thread offloading."""
+
+    def __init__(self, config: AppServerConfig | None = None) -> None:
+        self._sync = AppServerClient(config=config)
+        # Single stdio transport cannot be read safely from multiple threads.
+        self._transport_lock = asyncio.Lock()
+
+    async def __aenter__(self) -> "AsyncAppServerClient":
+        await self.start()
+        return self
+
+    async def __aexit__(self, _exc_type, _exc, _tb) -> None:
+        await self.close()
+
+    async def _call_sync(
+        self,
+        fn: Callable[ParamsT, ReturnT],
+        /,
+        *args: ParamsT.args,
+        **kwargs: ParamsT.kwargs,
+    ) -> ReturnT:
+        async with self._transport_lock:
+            return await asyncio.to_thread(fn, *args, **kwargs)
+
+    @staticmethod
+    def _next_from_iterator(
+        iterator: Iterator[AgentMessageDeltaNotification],
+    ) -> tuple[bool, AgentMessageDeltaNotification | None]:
+        try:
+            return True, next(iterator)
+        except StopIteration:
+            return False, None
+
+    async def start(self) -> None:
+        await self._call_sync(self._sync.start)
+
+    async def close(self) -> None:
+        await self._call_sync(self._sync.close)
+
+    async def initialize(self) -> InitializeResponse:
+        return await self._call_sync(self._sync.initialize)
+
+    def acquire_turn_consumer(self, turn_id: str) -> None:
+        self._sync.acquire_turn_consumer(turn_id)
+
+    def release_turn_consumer(self, turn_id: str) -> None:
+        self._sync.release_turn_consumer(turn_id)
+
+    async def request(
+        self,
+        method: str,
+        params: JsonObject | None,
+        *,
+        response_model: type[ModelT],
+    ) -> ModelT:
+        return await self._call_sync(
+            self._sync.request,
+            method,
+            params,
+            response_model=response_model,
+        )
+
+    async def thread_start(self, params: V2ThreadStartParams | JsonObject | None = None) -> ThreadStartResponse:
+        return await self._call_sync(self._sync.thread_start, params)
+
+    async def thread_resume(
+        self,
+        thread_id: str,
+        params: V2ThreadResumeParams | JsonObject | None = None,
+    ) -> ThreadResumeResponse:
+        return await self._call_sync(self._sync.thread_resume, thread_id, params)
+
+    async def thread_list(self, params: V2ThreadListParams | JsonObject | None = None) -> ThreadListResponse:
+        return await self._call_sync(self._sync.thread_list, params)
+
+    async def thread_read(self, thread_id: str, include_turns: bool = False) -> ThreadReadResponse:
+        return await self._call_sync(self._sync.thread_read, thread_id, include_turns)
+
+    async def thread_fork(
+        self,
+        thread_id: str,
+        params: V2ThreadForkParams | JsonObject | None = None,
+    ) -> ThreadForkResponse:
+        return await self._call_sync(self._sync.thread_fork, thread_id, params)
+
+    async def thread_archive(self, thread_id: str) -> ThreadArchiveResponse:
+        return await self._call_sync(self._sync.thread_archive, thread_id)
+
+    async def thread_unarchive(self, thread_id: str) -> ThreadUnarchiveResponse:
+        return await self._call_sync(self._sync.thread_unarchive, thread_id)
+
+    async def thread_set_name(self, thread_id: str, name: str) -> ThreadSetNameResponse:
+        return await self._call_sync(self._sync.thread_set_name, thread_id, name)
+
+    async def thread_compact(self, thread_id: str) -> ThreadCompactStartResponse:
+        return await self._call_sync(self._sync.thread_compact, thread_id)
+
+    async def turn_start(
+        self,
+        thread_id: str,
+        input_items: list[JsonObject] | JsonObject | str,
+        params: V2TurnStartParams | JsonObject | None = None,
+    ) -> TurnStartResponse:
+        return await self._call_sync(self._sync.turn_start, thread_id, input_items, params)
+
+    async def turn_interrupt(self, thread_id: str, turn_id: str) -> TurnInterruptResponse:
+        return await self._call_sync(self._sync.turn_interrupt, thread_id, turn_id)
+
+    async def turn_steer(
+        self,
+        thread_id: str,
+        expected_turn_id: str,
+        input_items: list[JsonObject] | JsonObject | str,
+    ) -> TurnSteerResponse:
+        return await self._call_sync(
+            self._sync.turn_steer,
+            thread_id,
+            expected_turn_id,
+            input_items,
+        )
+
+    async def model_list(self, include_hidden: bool = False) -> ModelListResponse:
+        return await self._call_sync(self._sync.model_list, include_hidden)
+
+    async def request_with_retry_on_overload(
+        self,
+        method: str,
+        params: JsonObject | None,
+        *,
+        response_model: type[ModelT],
+        max_attempts: int = 3,
+        initial_delay_s: float = 0.25,
+        max_delay_s: float = 2.0,
+    ) -> ModelT:
+        return await self._call_sync(
+            self._sync.request_with_retry_on_overload,
+            method,
+            params,
+            response_model=response_model,
+            max_attempts=max_attempts,
+            initial_delay_s=initial_delay_s,
+            max_delay_s=max_delay_s,
+        )
+
+    async def next_notification(self) -> Notification:
+        return await self._call_sync(self._sync.next_notification)
+
+    async def wait_for_turn_completed(self, turn_id: str) -> TurnCompletedNotification:
+        return await self._call_sync(self._sync.wait_for_turn_completed, turn_id)
+
+    async def stream_until_methods(self, methods: Iterable[str] | str) -> list[Notification]:
+        return await self._call_sync(self._sync.stream_until_methods, methods)
+
+    async def stream_text(
+        self,
+        thread_id: str,
+        text: str,
+        params: V2TurnStartParams | JsonObject | None = None,
+    ) -> AsyncIterator[AgentMessageDeltaNotification]:
+        async with self._transport_lock:
+            iterator = self._sync.stream_text(thread_id, text, params)
+            while True:
+                has_value, chunk = await asyncio.to_thread(
+                    self._next_from_iterator,
+                    iterator,
+                )
+                if not has_value:
+                    break
+                yield chunk

sdk/python/src/codex_app_server/client.py

@@ -0,0 +1,540 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import threading
+import uuid
+from collections import deque
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Iterable, Iterator, TypeVar
+
+from pydantic import BaseModel
+
+from .errors import AppServerError, TransportClosedError, map_jsonrpc_error
+from .generated.notification_registry import NOTIFICATION_MODELS
+from .generated.v2_all import (
+    AgentMessageDeltaNotification,
+    ModelListResponse,
+    ThreadArchiveResponse,
+    ThreadCompactStartResponse,
+    ThreadForkParams as V2ThreadForkParams,
+    ThreadForkResponse,
+    ThreadListParams as V2ThreadListParams,
+    ThreadListResponse,
+    ThreadReadResponse,
+    ThreadResumeParams as V2ThreadResumeParams,
+    ThreadResumeResponse,
+    ThreadSetNameResponse,
+    ThreadStartParams as V2ThreadStartParams,
+    ThreadStartResponse,
+    ThreadUnarchiveResponse,
+    TurnCompletedNotification,
+    TurnInterruptResponse,
+    TurnStartParams as V2TurnStartParams,
+    TurnStartResponse,
+    TurnSteerResponse,
+)
+from .models import (
+    InitializeResponse,
+    JsonObject,
+    JsonValue,
+    Notification,
+    UnknownNotification,
+)
+from .retry import retry_on_overload
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+ApprovalHandler = Callable[[str, JsonObject | None], JsonObject]
+RUNTIME_PKG_NAME = "codex-cli-bin"
+
+
+def _params_dict(
+    params: (
+        V2ThreadStartParams
+        | V2ThreadResumeParams
+        | V2ThreadListParams
+        | V2ThreadForkParams
+        | V2TurnStartParams
+        | JsonObject
+        | None
+    ),
+) -> JsonObject:
+    if params is None:
+        return {}
+    if hasattr(params, "model_dump"):
+        dumped = params.model_dump(
+            by_alias=True,
+            exclude_none=True,
+            mode="json",
+        )
+        if not isinstance(dumped, dict):
+            raise TypeError("Expected model_dump() to return dict")
+        return dumped
+    if isinstance(params, dict):
+        return params
+    raise TypeError(f"Expected generated params model or dict, got {type(params).__name__}")
+
+
+def _installed_codex_path() -> Path:
+    try:
+        from codex_cli_bin import bundled_codex_path
+    except ImportError as exc:
+        raise FileNotFoundError(
+            "Unable to locate the pinned Codex runtime. Install the published SDK build "
+            f"with its {RUNTIME_PKG_NAME} dependency, or set AppServerConfig.codex_bin "
+            "explicitly."
+        ) from exc
+
+    return bundled_codex_path()
+
+
+@dataclass(frozen=True)
+class CodexBinResolverOps:
+    installed_codex_path: Callable[[], Path]
+    path_exists: Callable[[Path], bool]
+
+
+def _default_codex_bin_resolver_ops() -> CodexBinResolverOps:
+    return CodexBinResolverOps(
+        installed_codex_path=_installed_codex_path,
+        path_exists=lambda path: path.exists(),
+    )
+
+
+def resolve_codex_bin(config: "AppServerConfig", ops: CodexBinResolverOps) -> Path:
+    if config.codex_bin is not None:
+        codex_bin = Path(config.codex_bin)
+        if not ops.path_exists(codex_bin):
+            raise FileNotFoundError(
+                f"Codex binary not found at {codex_bin}. Set AppServerConfig.codex_bin "
+                "to a valid binary path."
+            )
+        return codex_bin
+
+    return ops.installed_codex_path()
+
+
+def _resolve_codex_bin(config: "AppServerConfig") -> Path:
+    return resolve_codex_bin(config, _default_codex_bin_resolver_ops())
+
+
+@dataclass(slots=True)
+class AppServerConfig:
+    codex_bin: str | None = None
+    launch_args_override: tuple[str, ...] | None = None
+    config_overrides: tuple[str, ...] = ()
+    cwd: str | None = None
+    env: dict[str, str] | None = None
+    client_name: str = "codex_python_sdk"
+    client_title: str = "Codex Python SDK"
+    client_version: str = "0.2.0"
+    experimental_api: bool = True
+
+
+class AppServerClient:
+    """Synchronous typed JSON-RPC client for `codex app-server` over stdio."""
+
+    def __init__(
+        self,
+        config: AppServerConfig | None = None,
+        approval_handler: ApprovalHandler | None = None,
+    ) -> None:
+        self.config = config or AppServerConfig()
+        self._approval_handler = approval_handler or self._default_approval_handler
+        self._proc: subprocess.Popen[str] | None = None
+        self._lock = threading.Lock()
+        self._turn_consumer_lock = threading.Lock()
+        self._active_turn_consumer: str | None = None
+        self._pending_notifications: deque[Notification] = deque()
+        self._stderr_lines: deque[str] = deque(maxlen=400)
+        self._stderr_thread: threading.Thread | None = None
+
+    def __enter__(self) -> "AppServerClient":
+        self.start()
+        return self
+
+    def __exit__(self, _exc_type, _exc, _tb) -> None:
+        self.close()
+
+    def start(self) -> None:
+        if self._proc is not None:
+            return
+
+        if self.config.launch_args_override is not None:
+            args = list(self.config.launch_args_override)
+        else:
+            codex_bin = _resolve_codex_bin(self.config)
+            args = [str(codex_bin)]
+            for kv in self.config.config_overrides:
+                args.extend(["--config", kv])
+            args.extend(["app-server", "--listen", "stdio://"])
+
+        env = os.environ.copy()
+        if self.config.env:
+            env.update(self.config.env)
+
+        self._proc = subprocess.Popen(
+            args,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            cwd=self.config.cwd,
+            env=env,
+            bufsize=1,
+        )
+
+        self._start_stderr_drain_thread()
+
+    def close(self) -> None:
+        if self._proc is None:
+            return
+        proc = self._proc
+        self._proc = None
+        self._active_turn_consumer = None
+
+        if proc.stdin:
+            proc.stdin.close()
+        try:
+            proc.terminate()
+            proc.wait(timeout=2)
+        except Exception:
+            proc.kill()
+
+        if self._stderr_thread and self._stderr_thread.is_alive():
+            self._stderr_thread.join(timeout=0.5)
+
+    def initialize(self) -> InitializeResponse:
+        result = self.request(
+            "initialize",
+            {
+                "clientInfo": {
+                    "name": self.config.client_name,
+                    "title": self.config.client_title,
+                    "version": self.config.client_version,
+                },
+                "capabilities": {
+                    "experimentalApi": self.config.experimental_api,
+                },
+            },
+            response_model=InitializeResponse,
+        )
+        self.notify("initialized", None)
+        return result
+
+    def request(
+        self,
+        method: str,
+        params: JsonObject | None,
+        *,
+        response_model: type[ModelT],
+    ) -> ModelT:
+        result = self._request_raw(method, params)
+        if not isinstance(result, dict):
+            raise AppServerError(f"{method} response must be a JSON object")
+        return response_model.model_validate(result)
+
+    def _request_raw(self, method: str, params: JsonObject | None = None) -> JsonValue:
+        request_id = str(uuid.uuid4())
+        self._write_message({"id": request_id, "method": method, "params": params or {}})
+
+        while True:
+            msg = self._read_message()
+
+            if "method" in msg and "id" in msg:
+                response = self._handle_server_request(msg)
+                self._write_message({"id": msg["id"], "result": response})
+                continue
+
+            if "method" in msg and "id" not in msg:
+                self._pending_notifications.append(
+                    self._coerce_notification(msg["method"], msg.get("params"))
+                )
+                continue
+
+            if msg.get("id") != request_id:
+                continue
+
+            if "error" in msg:
+                err = msg["error"]
+                if isinstance(err, dict):
+                    raise map_jsonrpc_error(
+                        int(err.get("code", -32000)),
+                        str(err.get("message", "unknown")),
+                        err.get("data"),
+                    )
+                raise AppServerError("Malformed JSON-RPC error response")
+
+            return msg.get("result")
+
+    def notify(self, method: str, params: JsonObject | None = None) -> None:
+        self._write_message({"method": method, "params": params or {}})
+
+    def next_notification(self) -> Notification:
+        if self._pending_notifications:
+            return self._pending_notifications.popleft()
+
+        while True:
+            msg = self._read_message()
+            if "method" in msg and "id" in msg:
+                response = self._handle_server_request(msg)
+                self._write_message({"id": msg["id"], "result": response})
+                continue
+            if "method" in msg and "id" not in msg:
+                return self._coerce_notification(msg["method"], msg.get("params"))
+
+    def acquire_turn_consumer(self, turn_id: str) -> None:
+        with self._turn_consumer_lock:
+            if self._active_turn_consumer is not None:
+                raise RuntimeError(
+                    "Concurrent turn consumers are not yet supported in the experimental SDK. "
+                    f"Client is already streaming turn {self._active_turn_consumer!r}; "
+                    f"cannot start turn {turn_id!r} until the active consumer finishes."
+                )
+            self._active_turn_consumer = turn_id
+
+    def release_turn_consumer(self, turn_id: str) -> None:
+        with self._turn_consumer_lock:
+            if self._active_turn_consumer == turn_id:
+                self._active_turn_consumer = None
+
+    def thread_start(self, params: V2ThreadStartParams | JsonObject | None = None) -> ThreadStartResponse:
+        return self.request("thread/start", _params_dict(params), response_model=ThreadStartResponse)
+
+    def thread_resume(
+        self,
+        thread_id: str,
+        params: V2ThreadResumeParams | JsonObject | None = None,
+    ) -> ThreadResumeResponse:
+        payload = {"threadId": thread_id, **_params_dict(params)}
+        return self.request("thread/resume", payload, response_model=ThreadResumeResponse)
+
+    def thread_list(self, params: V2ThreadListParams | JsonObject | None = None) -> ThreadListResponse:
+        return self.request("thread/list", _params_dict(params), response_model=ThreadListResponse)
+
+    def thread_read(self, thread_id: str, include_turns: bool = False) -> ThreadReadResponse:
+        return self.request(
+            "thread/read",
+            {"threadId": thread_id, "includeTurns": include_turns},
+            response_model=ThreadReadResponse,
+        )
+
+    def thread_fork(
+        self,
+        thread_id: str,
+        params: V2ThreadForkParams | JsonObject | None = None,
+    ) -> ThreadForkResponse:
+        payload = {"threadId": thread_id, **_params_dict(params)}
+        return self.request("thread/fork", payload, response_model=ThreadForkResponse)
+
+    def thread_archive(self, thread_id: str) -> ThreadArchiveResponse:
+        return self.request("thread/archive", {"threadId": thread_id}, response_model=ThreadArchiveResponse)
+
+    def thread_unarchive(self, thread_id: str) -> ThreadUnarchiveResponse:
+        return self.request("thread/unarchive", {"threadId": thread_id}, response_model=ThreadUnarchiveResponse)
+
+    def thread_set_name(self, thread_id: str, name: str) -> ThreadSetNameResponse:
+        return self.request(
+            "thread/name/set",
+            {"threadId": thread_id, "name": name},
+            response_model=ThreadSetNameResponse,
+        )
+
+    def thread_compact(self, thread_id: str) -> ThreadCompactStartResponse:
+        return self.request(
+            "thread/compact/start",
+            {"threadId": thread_id},
+            response_model=ThreadCompactStartResponse,
+        )
+
+    def turn_start(
+        self,
+        thread_id: str,
+        input_items: list[JsonObject] | JsonObject | str,
+        params: V2TurnStartParams | JsonObject | None = None,
+    ) -> TurnStartResponse:
+        payload = {
+            **_params_dict(params),
+            "threadId": thread_id,
+            "input": self._normalize_input_items(input_items),
+        }
+        return self.request("turn/start", payload, response_model=TurnStartResponse)
+
+    def turn_interrupt(self, thread_id: str, turn_id: str) -> TurnInterruptResponse:
+        return self.request(
+            "turn/interrupt",
+            {"threadId": thread_id, "turnId": turn_id},
+            response_model=TurnInterruptResponse,
+        )
+
+    def turn_steer(
+        self,
+        thread_id: str,
+        expected_turn_id: str,
+        input_items: list[JsonObject] | JsonObject | str,
+    ) -> TurnSteerResponse:
+        return self.request(
+            "turn/steer",
+            {
+                "threadId": thread_id,
+                "expectedTurnId": expected_turn_id,
+                "input": self._normalize_input_items(input_items),
+            },
+            response_model=TurnSteerResponse,
+        )
+
+    def model_list(self, include_hidden: bool = False) -> ModelListResponse:
+        return self.request(
+            "model/list",
+            {"includeHidden": include_hidden},
+            response_model=ModelListResponse,
+        )
+
+    def request_with_retry_on_overload(
+        self,
+        method: str,
+        params: JsonObject | None,
+        *,
+        response_model: type[ModelT],
+        max_attempts: int = 3,
+        initial_delay_s: float = 0.25,
+        max_delay_s: float = 2.0,
+    ) -> ModelT:
+        return retry_on_overload(
+            lambda: self.request(method, params, response_model=response_model),
+            max_attempts=max_attempts,
+            initial_delay_s=initial_delay_s,
+            max_delay_s=max_delay_s,
+        )
+
+    def wait_for_turn_completed(self, turn_id: str) -> TurnCompletedNotification:
+        while True:
+            notification = self.next_notification()
+            if (
+                notification.method == "turn/completed"
+                and isinstance(notification.payload, TurnCompletedNotification)
+                and notification.payload.turn.id == turn_id
+            ):
+                return notification.payload
+
+    def stream_until_methods(self, methods: Iterable[str] | str) -> list[Notification]:
+        target_methods = {methods} if isinstance(methods, str) else set(methods)
+        out: list[Notification] = []
+        while True:
+            notification = self.next_notification()
+            out.append(notification)
+            if notification.method in target_methods:
+                return out
+
+    def stream_text(
+        self,
+        thread_id: str,
+        text: str,
+        params: V2TurnStartParams | JsonObject | None = None,
+    ) -> Iterator[AgentMessageDeltaNotification]:
+        started = self.turn_start(thread_id, text, params=params)
+        turn_id = started.turn.id
+        while True:
+            notification = self.next_notification()
+            if (
+                notification.method == "item/agentMessage/delta"
+                and isinstance(notification.payload, AgentMessageDeltaNotification)
+                and notification.payload.turn_id == turn_id
+            ):
+                yield notification.payload
+                continue
+            if (
+                notification.method == "turn/completed"
+                and isinstance(notification.payload, TurnCompletedNotification)
+                and notification.payload.turn.id == turn_id
+            ):
+                break
+
+    def _coerce_notification(self, method: str, params: object) -> Notification:
+        params_dict = params if isinstance(params, dict) else {}
+
+        model = NOTIFICATION_MODELS.get(method)
+        if model is None:
+            return Notification(method=method, payload=UnknownNotification(params=params_dict))
+
+        try:
+            payload = model.model_validate(params_dict)
+        except Exception:  # noqa: BLE001
+            return Notification(method=method, payload=UnknownNotification(params=params_dict))
+        return Notification(method=method, payload=payload)
+
+    def _normalize_input_items(
+        self,
+        input_items: list[JsonObject] | JsonObject | str,
+    ) -> list[JsonObject]:
+        if isinstance(input_items, str):
+            return [{"type": "text", "text": input_items}]
+        if isinstance(input_items, dict):
+            return [input_items]
+        return input_items
+
+    def _default_approval_handler(self, method: str, params: JsonObject | None) -> JsonObject:
+        if method == "item/commandExecution/requestApproval":
+            return {"decision": "accept"}
+        if method == "item/fileChange/requestApproval":
+            return {"decision": "accept"}
+        return {}
+
+    def _start_stderr_drain_thread(self) -> None:
+        if self._proc is None or self._proc.stderr is None:
+            return
+
+        def _drain() -> None:
+            stderr = self._proc.stderr
+            if stderr is None:
+                return
+            for line in stderr:
+                self._stderr_lines.append(line.rstrip("\n"))
+
+        self._stderr_thread = threading.Thread(target=_drain, daemon=True)
+        self._stderr_thread.start()
+
+    def _stderr_tail(self, limit: int = 40) -> str:
+        return "\n".join(list(self._stderr_lines)[-limit:])
+
+    def _handle_server_request(self, msg: dict[str, JsonValue]) -> JsonObject:
+        method = msg["method"]
+        params = msg.get("params")
+        if not isinstance(method, str):
+            return {}
+        return self._approval_handler(
+            method,
+            params if isinstance(params, dict) else None,
+        )
+
+    def _write_message(self, payload: JsonObject) -> None:
+        if self._proc is None or self._proc.stdin is None:
+            raise TransportClosedError("app-server is not running")
+        with self._lock:
+            self._proc.stdin.write(json.dumps(payload) + "\n")
+            self._proc.stdin.flush()
+
+    def _read_message(self) -> dict[str, JsonValue]:
+        if self._proc is None or self._proc.stdout is None:
+            raise TransportClosedError("app-server is not running")
+
+        line = self._proc.stdout.readline()
+        if not line:
+            raise TransportClosedError(
+                f"app-server closed stdout. stderr_tail={self._stderr_tail()[:2000]}"
+            )
+
+        try:
+            message = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise AppServerError(f"Invalid JSON-RPC line: {line!r}") from exc
+
+        if not isinstance(message, dict):
+            raise AppServerError(f"Invalid JSON-RPC payload: {message!r}")
+        return message
+
+
+def default_codex_home() -> str:
+    return str(Path.home() / ".codex")

sdk/python/src/codex_app_server/errors.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class AppServerError(Exception):
+    """Base exception for SDK errors."""
+
+
+class JsonRpcError(AppServerError):
+    """Raw JSON-RPC error wrapper from the server."""
+
+    def __init__(self, code: int, message: str, data: Any = None):
+        super().__init__(f"JSON-RPC error {code}: {message}")
+        self.code = code
+        self.message = message
+        self.data = data
+
+
+class TransportClosedError(AppServerError):
+    """Raised when the app-server transport closes unexpectedly."""
+
+
+class AppServerRpcError(JsonRpcError):
+    """Base typed error for JSON-RPC failures."""
+
+
+class ParseError(AppServerRpcError):
+    pass
+
+
+class InvalidRequestError(AppServerRpcError):
+    pass
+
+
+class MethodNotFoundError(AppServerRpcError):
+    pass
+
+
+class InvalidParamsError(AppServerRpcError):
+    pass
+
+
+class InternalRpcError(AppServerRpcError):
+    pass
+
+
+class ServerBusyError(AppServerRpcError):
+    """Server is overloaded / unavailable and caller should retry."""
+
+
+class RetryLimitExceededError(ServerBusyError):
+    """Server exhausted internal retry budget for a retryable operation."""
+
+
+def _contains_retry_limit_text(message: str) -> bool:
+    lowered = message.lower()
+    return "retry limit" in lowered or "too many failed attempts" in lowered
+
+
+def _is_server_overloaded(data: Any) -> bool:
+    if data is None:
+        return False
+
+    if isinstance(data, str):
+        return data.lower() == "server_overloaded"
+
+    if isinstance(data, dict):
+        direct = (
+            data.get("codex_error_info")
+            or data.get("codexErrorInfo")
+            or data.get("errorInfo")
+        )
+        if isinstance(direct, str) and direct.lower() == "server_overloaded":
+            return True
+        if isinstance(direct, dict):
+            for value in direct.values():
+                if isinstance(value, str) and value.lower() == "server_overloaded":
+                    return True
+        for value in data.values():
+            if _is_server_overloaded(value):
+                return True
+
+    if isinstance(data, list):
+        return any(_is_server_overloaded(value) for value in data)
+
+    return False
+
+
+def map_jsonrpc_error(code: int, message: str, data: Any = None) -> JsonRpcError:
+    """Map a raw JSON-RPC error into a richer SDK exception class."""
+
+    if code == -32700:
+        return ParseError(code, message, data)
+    if code == -32600:
+        return InvalidRequestError(code, message, data)
+    if code == -32601:
+        return MethodNotFoundError(code, message, data)
+    if code == -32602:
+        return InvalidParamsError(code, message, data)
+    if code == -32603:
+        return InternalRpcError(code, message, data)
+
+    if -32099 <= code <= -32000:
+        if _is_server_overloaded(data):
+            if _contains_retry_limit_text(message):
+                return RetryLimitExceededError(code, message, data)
+            return ServerBusyError(code, message, data)
+        if _contains_retry_limit_text(message):
+            return RetryLimitExceededError(code, message, data)
+        return AppServerRpcError(code, message, data)
+
+    return JsonRpcError(code, message, data)
+
+
+def is_retryable_error(exc: BaseException) -> bool:
+    """True if the exception is a transient overload-style error."""
+
+    if isinstance(exc, ServerBusyError):
+        return True
+
+    if isinstance(exc, JsonRpcError):
+        return _is_server_overloaded(exc.data)
+
+    return False

sdk/python/src/codex_app_server/generated/__init__.py

@@ -0,0 +1 @@
+"""Auto-generated Python types derived from the app-server schemas."""

sdk/python/src/codex_app_server/generated/notification_registry.py

@@ -0,0 +1,102 @@
+# Auto-generated by scripts/update_sdk_artifacts.py
+# DO NOT EDIT MANUALLY.
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from .v2_all import AccountLoginCompletedNotification
+from .v2_all import AccountRateLimitsUpdatedNotification
+from .v2_all import AccountUpdatedNotification
+from .v2_all import AgentMessageDeltaNotification
+from .v2_all import AppListUpdatedNotification
+from .v2_all import CommandExecOutputDeltaNotification
+from .v2_all import CommandExecutionOutputDeltaNotification
+from .v2_all import ConfigWarningNotification
+from .v2_all import ContextCompactedNotification
+from .v2_all import DeprecationNoticeNotification
+from .v2_all import ErrorNotification
+from .v2_all import FileChangeOutputDeltaNotification
+from .v2_all import FuzzyFileSearchSessionCompletedNotification
+from .v2_all import FuzzyFileSearchSessionUpdatedNotification
+from .v2_all import HookCompletedNotification
+from .v2_all import HookStartedNotification
+from .v2_all import ItemCompletedNotification
+from .v2_all import ItemStartedNotification
+from .v2_all import McpServerOauthLoginCompletedNotification
+from .v2_all import McpToolCallProgressNotification
+from .v2_all import ModelReroutedNotification
+from .v2_all import PlanDeltaNotification
+from .v2_all import ReasoningSummaryPartAddedNotification
+from .v2_all import ReasoningSummaryTextDeltaNotification
+from .v2_all import ReasoningTextDeltaNotification
+from .v2_all import ServerRequestResolvedNotification
+from .v2_all import SkillsChangedNotification
+from .v2_all import TerminalInteractionNotification
+from .v2_all import ThreadArchivedNotification
+from .v2_all import ThreadClosedNotification
+from .v2_all import ThreadNameUpdatedNotification
+from .v2_all import ThreadRealtimeClosedNotification
+from .v2_all import ThreadRealtimeErrorNotification
+from .v2_all import ThreadRealtimeItemAddedNotification
+from .v2_all import ThreadRealtimeOutputAudioDeltaNotification
+from .v2_all import ThreadRealtimeStartedNotification
+from .v2_all import ThreadStartedNotification
+from .v2_all import ThreadStatusChangedNotification
+from .v2_all import ThreadTokenUsageUpdatedNotification
+from .v2_all import ThreadUnarchivedNotification
+from .v2_all import TurnCompletedNotification
+from .v2_all import TurnDiffUpdatedNotification
+from .v2_all import TurnPlanUpdatedNotification
+from .v2_all import TurnStartedNotification
+from .v2_all import WindowsSandboxSetupCompletedNotification
+from .v2_all import WindowsWorldWritableWarningNotification
+
+NOTIFICATION_MODELS: dict[str, type[BaseModel]] = {
+    "account/login/completed": AccountLoginCompletedNotification,
+    "account/rateLimits/updated": AccountRateLimitsUpdatedNotification,
+    "account/updated": AccountUpdatedNotification,
+    "app/list/updated": AppListUpdatedNotification,
+    "command/exec/outputDelta": CommandExecOutputDeltaNotification,
+    "configWarning": ConfigWarningNotification,
+    "deprecationNotice": DeprecationNoticeNotification,
+    "error": ErrorNotification,
+    "fuzzyFileSearch/sessionCompleted": FuzzyFileSearchSessionCompletedNotification,
+    "fuzzyFileSearch/sessionUpdated": FuzzyFileSearchSessionUpdatedNotification,
+    "hook/completed": HookCompletedNotification,
+    "hook/started": HookStartedNotification,
+    "item/agentMessage/delta": AgentMessageDeltaNotification,
+    "item/commandExecution/outputDelta": CommandExecutionOutputDeltaNotification,
+    "item/commandExecution/terminalInteraction": TerminalInteractionNotification,
+    "item/completed": ItemCompletedNotification,
+    "item/fileChange/outputDelta": FileChangeOutputDeltaNotification,
+    "item/mcpToolCall/progress": McpToolCallProgressNotification,
+    "item/plan/delta": PlanDeltaNotification,
+    "item/reasoning/summaryPartAdded": ReasoningSummaryPartAddedNotification,
+    "item/reasoning/summaryTextDelta": ReasoningSummaryTextDeltaNotification,
+    "item/reasoning/textDelta": ReasoningTextDeltaNotification,
+    "item/started": ItemStartedNotification,
+    "mcpServer/oauthLogin/completed": McpServerOauthLoginCompletedNotification,
+    "model/rerouted": ModelReroutedNotification,
+    "serverRequest/resolved": ServerRequestResolvedNotification,
+    "skills/changed": SkillsChangedNotification,
+    "thread/archived": ThreadArchivedNotification,
+    "thread/closed": ThreadClosedNotification,
+    "thread/compacted": ContextCompactedNotification,
+    "thread/name/updated": ThreadNameUpdatedNotification,
+    "thread/realtime/closed": ThreadRealtimeClosedNotification,
+    "thread/realtime/error": ThreadRealtimeErrorNotification,
+    "thread/realtime/itemAdded": ThreadRealtimeItemAddedNotification,
+    "thread/realtime/outputAudio/delta": ThreadRealtimeOutputAudioDeltaNotification,
+    "thread/realtime/started": ThreadRealtimeStartedNotification,
+    "thread/started": ThreadStartedNotification,
+    "thread/status/changed": ThreadStatusChangedNotification,
+    "thread/tokenUsage/updated": ThreadTokenUsageUpdatedNotification,
+    "thread/unarchived": ThreadUnarchivedNotification,
+    "turn/completed": TurnCompletedNotification,
+    "turn/diff/updated": TurnDiffUpdatedNotification,
+    "turn/plan/updated": TurnPlanUpdatedNotification,
+    "turn/started": TurnStartedNotification,
+    "windows/worldWritableWarning": WindowsWorldWritableWarningNotification,
+    "windowsSandbox/setupCompleted": WindowsSandboxSetupCompletedNotification,
+}

sdk/python/src/codex_app_server/generated/v2_types.py

@@ -0,0 +1,23 @@
+"""Stable aliases over the canonical generated v2 models."""
+
+from .v2_all import (
+    ModelListResponse,
+    ThreadCompactStartResponse,
+    ThreadItem,
+    ThreadListResponse,
+    ThreadReadResponse,
+    ThreadTokenUsageUpdatedNotification,
+    TurnCompletedNotification as TurnCompletedNotificationPayload,
+    TurnSteerResponse,
+)
+
+__all__ = [
+    "ModelListResponse",
+    "ThreadCompactStartResponse",
+    "ThreadItem",
+    "ThreadListResponse",
+    "ThreadReadResponse",
+    "ThreadTokenUsageUpdatedNotification",
+    "TurnCompletedNotificationPayload",
+    "TurnSteerResponse",
+]

sdk/python/src/codex_app_server/models.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from pydantic import BaseModel
+
+from .generated.v2_all import (
+    AccountLoginCompletedNotification,
+    AccountRateLimitsUpdatedNotification,
+    AccountUpdatedNotification,
+    AgentMessageDeltaNotification,
+    AppListUpdatedNotification,
+    CommandExecutionOutputDeltaNotification,
+    ConfigWarningNotification,
+    ContextCompactedNotification,
+    DeprecationNoticeNotification,
+    ErrorNotification,
+    FileChangeOutputDeltaNotification,
+    ItemCompletedNotification,
+    ItemStartedNotification,
+    McpServerOauthLoginCompletedNotification,
+    McpToolCallProgressNotification,
+    PlanDeltaNotification,
+    RawResponseItemCompletedNotification,
+    ReasoningSummaryPartAddedNotification,
+    ReasoningSummaryTextDeltaNotification,
+    ReasoningTextDeltaNotification,
+    TerminalInteractionNotification,
+    ThreadNameUpdatedNotification,
+    ThreadStartedNotification,
+    ThreadTokenUsageUpdatedNotification,
+    TurnCompletedNotification,
+    TurnDiffUpdatedNotification,
+    TurnPlanUpdatedNotification,
+    TurnStartedNotification,
+    WindowsWorldWritableWarningNotification,
+)
+
+JsonScalar: TypeAlias = str | int | float | bool | None
+JsonValue: TypeAlias = JsonScalar | dict[str, "JsonValue"] | list["JsonValue"]
+JsonObject: TypeAlias = dict[str, JsonValue]
+
+
+@dataclass(slots=True)
+class UnknownNotification:
+    params: JsonObject
+
+
+NotificationPayload: TypeAlias = (
+    AccountLoginCompletedNotification
+    | AccountRateLimitsUpdatedNotification
+    | AccountUpdatedNotification
+    | AgentMessageDeltaNotification
+    | AppListUpdatedNotification
+    | CommandExecutionOutputDeltaNotification
+    | ConfigWarningNotification
+    | ContextCompactedNotification
+    | DeprecationNoticeNotification
+    | ErrorNotification
+    | FileChangeOutputDeltaNotification
+    | ItemCompletedNotification
+    | ItemStartedNotification
+    | McpServerOauthLoginCompletedNotification
+    | McpToolCallProgressNotification
+    | PlanDeltaNotification
+    | RawResponseItemCompletedNotification
+    | ReasoningSummaryPartAddedNotification
+    | ReasoningSummaryTextDeltaNotification
+    | ReasoningTextDeltaNotification
+    | TerminalInteractionNotification
+    | ThreadNameUpdatedNotification
+    | ThreadStartedNotification
+    | ThreadTokenUsageUpdatedNotification
+    | TurnCompletedNotification
+    | TurnDiffUpdatedNotification
+    | TurnPlanUpdatedNotification
+    | TurnStartedNotification
+    | WindowsWorldWritableWarningNotification
+    | UnknownNotification
+)
+
+
+@dataclass(slots=True)
+class Notification:
+    method: str
+    payload: NotificationPayload
+
+
+class ServerInfo(BaseModel):
+    name: str | None = None
+    version: str | None = None
+
+
+class InitializeResponse(BaseModel):
+    serverInfo: ServerInfo | None = None
+    userAgent: str | None = None

sdk/python/src/codex_app_server/public_api.py

@@ -0,0 +1,795 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import AsyncIterator, Iterator
+
+from .async_client import AsyncAppServerClient
+from .client import AppServerClient, AppServerConfig
+from .generated.v2_all import (
+    AgentMessageDeltaNotification,
+    RawResponseItemCompletedNotification,
+    ThreadArchiveResponse,
+    ThreadSetNameResponse,
+    TurnError,
+    TurnInterruptResponse,
+)
+from .generated.v2_types import (
+    ModelListResponse,
+    ThreadCompactStartResponse,
+    ThreadItem,
+    ThreadListResponse,
+    ThreadReadResponse,
+    ThreadTokenUsageUpdatedNotification,
+    TurnCompletedNotificationPayload,
+    TurnSteerResponse,
+)
+from .models import InitializeResponse, JsonObject, Notification
+from .public_types import (
+    AskForApproval,
+    Personality,
+    ReasoningEffort,
+    ReasoningSummary,
+    SandboxMode,
+    SandboxPolicy,
+    ServiceTier,
+    ThreadForkParams,
+    ThreadListParams,
+    ThreadResumeParams,
+    ThreadSortKey,
+    ThreadSourceKind,
+    ThreadStartParams,
+    TurnStartParams,
+    TurnStatus,
+)
+
+
+@dataclass(slots=True)
+class TurnResult:
+    thread_id: str
+    turn_id: str
+    status: TurnStatus
+    error: TurnError | None
+    text: str
+    items: list[ThreadItem]
+    usage: ThreadTokenUsageUpdatedNotification | None = None
+
+
+@dataclass(slots=True)
+class TextInput:
+    text: str
+
+
+@dataclass(slots=True)
+class ImageInput:
+    url: str
+
+
+@dataclass(slots=True)
+class LocalImageInput:
+    path: str
+
+
+@dataclass(slots=True)
+class SkillInput:
+    name: str
+    path: str
+
+
+@dataclass(slots=True)
+class MentionInput:
+    name: str
+    path: str
+
+
+InputItem = TextInput | ImageInput | LocalImageInput | SkillInput | MentionInput
+Input = list[InputItem] | InputItem
+
+
+@dataclass(slots=True)
+class InitializeResult:
+    server_name: str
+    server_version: str
+    user_agent: str
+
+
+def _to_wire_item(item: InputItem) -> JsonObject:
+    if isinstance(item, TextInput):
+        return {"type": "text", "text": item.text}
+    if isinstance(item, ImageInput):
+        return {"type": "image", "url": item.url}
+    if isinstance(item, LocalImageInput):
+        return {"type": "localImage", "path": item.path}
+    if isinstance(item, SkillInput):
+        return {"type": "skill", "name": item.name, "path": item.path}
+    if isinstance(item, MentionInput):
+        return {"type": "mention", "name": item.name, "path": item.path}
+    raise TypeError(f"unsupported input item: {type(item)!r}")
+
+
+def _to_wire_input(input: Input) -> list[JsonObject]:
+    if isinstance(input, list):
+        return [_to_wire_item(i) for i in input]
+    return [_to_wire_item(input)]
+
+
+def _split_user_agent(user_agent: str) -> tuple[str | None, str | None]:
+    raw = user_agent.strip()
+    if not raw:
+        return None, None
+    if "/" in raw:
+        name, version = raw.split("/", 1)
+        return (name or None), (version or None)
+    parts = raw.split(maxsplit=1)
+    if len(parts) == 2:
+        return parts[0], parts[1]
+    return raw, None
+
+
+def _enum_value(value: object) -> object:
+    return getattr(value, "value", value)
+
+
+def _assistant_output_text_chunks(
+    notification: RawResponseItemCompletedNotification,
+) -> list[str]:
+    item = notification.item.root
+    if _enum_value(getattr(item, "type", None)) != "message":
+        return []
+    if getattr(item, "role", None) != "assistant":
+        return []
+
+    chunks: list[str] = []
+    for content in getattr(item, "content", []) or []:
+        content_item = getattr(content, "root", content)
+        if _enum_value(getattr(content_item, "type", None)) != "output_text":
+            continue
+        text = getattr(content_item, "text", None)
+        if isinstance(text, str) and text:
+            chunks.append(text)
+    return chunks
+
+
+def _build_turn_result(
+    completed: TurnCompletedNotificationPayload | None,
+    usage: ThreadTokenUsageUpdatedNotification | None,
+    delta_chunks: list[str],
+    raw_text_chunks: list[str],
+) -> TurnResult:
+    if completed is None:
+        raise RuntimeError("turn completed event not received")
+    if completed.turn.status == TurnStatus.completed and usage is None:
+        raise RuntimeError(
+            "thread/tokenUsage/updated notification not received for completed turn"
+        )
+
+    text = "".join(delta_chunks) if delta_chunks else "".join(raw_text_chunks)
+    return TurnResult(
+        thread_id=completed.thread_id,
+        turn_id=completed.turn.id,
+        status=completed.turn.status,
+        error=completed.turn.error,
+        text=text,
+        items=list(completed.turn.items or []),
+        usage=usage,
+    )
+
+
+class Codex:
+    """Minimal typed SDK surface for app-server v2."""
+
+    def __init__(self, config: AppServerConfig | None = None) -> None:
+        self._client = AppServerClient(config=config)
+        try:
+            self._client.start()
+            self._init = self._parse_initialize(self._client.initialize())
+        except Exception:
+            self._client.close()
+            raise
+
+    def __enter__(self) -> "Codex":
+        return self
+
+    def __exit__(self, _exc_type, _exc, _tb) -> None:
+        self.close()
+
+    @staticmethod
+    def _parse_initialize(payload: InitializeResponse) -> InitializeResult:
+        user_agent = (payload.userAgent or "").strip()
+        server = payload.serverInfo
+
+        server_name: str | None = None
+        server_version: str | None = None
+
+        if server is not None:
+            server_name = (server.name or "").strip() or None
+            server_version = (server.version or "").strip() or None
+
+        if (server_name is None or server_version is None) and user_agent:
+            parsed_name, parsed_version = _split_user_agent(user_agent)
+            if server_name is None:
+                server_name = parsed_name
+            if server_version is None:
+                server_version = parsed_version
+
+        normalized_server_name = (server_name or "").strip()
+        normalized_server_version = (server_version or "").strip()
+        if not user_agent or not normalized_server_name or not normalized_server_version:
+            raise RuntimeError(
+                "initialize response missing required metadata "
+                f"(user_agent={user_agent!r}, server_name={normalized_server_name!r}, server_version={normalized_server_version!r})"
+            )
+
+        return InitializeResult(
+            server_name=normalized_server_name,
+            server_version=normalized_server_version,
+            user_agent=user_agent,
+        )
+
+    @property
+    def metadata(self) -> InitializeResult:
+        return self._init
+
+    def close(self) -> None:
+        self._client.close()
+
+    # BEGIN GENERATED: Codex.flat_methods
+    def thread_start(
+        self,
+        *,
+        approval_policy: AskForApproval | None = None,
+        base_instructions: str | None = None,
+        config: JsonObject | None = None,
+        cwd: str | None = None,
+        developer_instructions: str | None = None,
+        ephemeral: bool | None = None,
+        model: str | None = None,
+        model_provider: str | None = None,
+        personality: Personality | None = None,
+        sandbox: SandboxMode | None = None,
+        service_name: str | None = None,
+        service_tier: ServiceTier | None = None,
+    ) -> Thread:
+        params = ThreadStartParams(
+            approval_policy=approval_policy,
+            base_instructions=base_instructions,
+            config=config,
+            cwd=cwd,
+            developer_instructions=developer_instructions,
+            ephemeral=ephemeral,
+            model=model,
+            model_provider=model_provider,
+            personality=personality,
+            sandbox=sandbox,
+            service_name=service_name,
+            service_tier=service_tier,
+        )
+        started = self._client.thread_start(params)
+        return Thread(self._client, started.thread.id)
+
+    def thread_list(
+        self,
+        *,
+        archived: bool | None = None,
+        cursor: str | None = None,
+        cwd: str | None = None,
+        limit: int | None = None,
+        model_providers: list[str] | None = None,
+        search_term: str | None = None,
+        sort_key: ThreadSortKey | None = None,
+        source_kinds: list[ThreadSourceKind] | None = None,
+    ) -> ThreadListResponse:
+        params = ThreadListParams(
+            archived=archived,
+            cursor=cursor,
+            cwd=cwd,
+            limit=limit,
+            model_providers=model_providers,
+            search_term=search_term,
+            sort_key=sort_key,
+            source_kinds=source_kinds,
+        )
+        return self._client.thread_list(params)
+
+    def thread_resume(
+        self,
+        thread_id: str,
+        *,
+        approval_policy: AskForApproval | None = None,
+        base_instructions: str | None = None,
+        config: JsonObject | None = None,
+        cwd: str | None = None,
+        developer_instructions: str | None = None,
+        model: str | None = None,
+        model_provider: str | None = None,
+        personality: Personality | None = None,
+        sandbox: SandboxMode | None = None,
+        service_tier: ServiceTier | None = None,
+    ) -> Thread:
+        params = ThreadResumeParams(
+            thread_id=thread_id,
+            approval_policy=approval_policy,
+            base_instructions=base_instructions,
+            config=config,
+            cwd=cwd,
+            developer_instructions=developer_instructions,
+            model=model,
+            model_provider=model_provider,
+            personality=personality,
+            sandbox=sandbox,
+            service_tier=service_tier,
+        )
+        resumed = self._client.thread_resume(thread_id, params)
+        return Thread(self._client, resumed.thread.id)
+
+    def thread_fork(
+        self,
+        thread_id: str,
+        *,
+        approval_policy: AskForApproval | None = None,
+        base_instructions: str | None = None,
+        config: JsonObject | None = None,
+        cwd: str | None = None,
+        developer_instructions: str | None = None,
+        ephemeral: bool | None = None,
+        model: str | None = None,
+        model_provider: str | None = None,
+        sandbox: SandboxMode | None = None,
+        service_tier: ServiceTier | None = None,
+    ) -> Thread:
+        params = ThreadForkParams(
+            thread_id=thread_id,
+            approval_policy=approval_policy,
+            base_instructions=base_instructions,
+            config=config,
+            cwd=cwd,
+            developer_instructions=developer_instructions,
+            ephemeral=ephemeral,
+            model=model,
+            model_provider=model_provider,
+            sandbox=sandbox,
+            service_tier=service_tier,
+        )
+        forked = self._client.thread_fork(thread_id, params)
+        return Thread(self._client, forked.thread.id)
+
+    def thread_archive(self, thread_id: str) -> ThreadArchiveResponse:
+        return self._client.thread_archive(thread_id)
+
+    def thread_unarchive(self, thread_id: str) -> Thread:
+        unarchived = self._client.thread_unarchive(thread_id)
+        return Thread(self._client, unarchived.thread.id)
+    # END GENERATED: Codex.flat_methods
+
+    def models(self, *, include_hidden: bool = False) -> ModelListResponse:
+        return self._client.model_list(include_hidden=include_hidden)
+
+
+class AsyncCodex:
+    """Async mirror of :class:`Codex` with matching method shapes."""
+
+    def __init__(self, config: AppServerConfig | None = None) -> None:
+        self._client = AsyncAppServerClient(config=config)
+        self._init: InitializeResult | None = None
+        self._initialized = False
+        self._init_lock = asyncio.Lock()
+
+    async def __aenter__(self) -> "AsyncCodex":
+        await self._ensure_initialized()
+        return self
+
+    async def __aexit__(self, _exc_type, _exc, _tb) -> None:
+        await self.close()
+
+    async def _ensure_initialized(self) -> None:
+        if self._initialized:
+            return
+        async with self._init_lock:
+            if self._initialized:
+                return
+            try:
+                await self._client.start()
+                payload = await self._client.initialize()
+                self._init = Codex._parse_initialize(payload)
+                self._initialized = True
+            except Exception:
+                await self._client.close()
+                self._init = None
+                self._initialized = False
+                raise
+
+    @property
+    def metadata(self) -> InitializeResult:
+        if self._init is None:
+            raise RuntimeError(
+                "AsyncCodex is not initialized yet. Use `async with AsyncCodex()` or call an async API first."
+            )
+        return self._init
+
+    async def close(self) -> None:
+        await self._client.close()
+        self._init = None
+        self._initialized = False
+
+    # BEGIN GENERATED: AsyncCodex.flat_methods
+    async def thread_start(
+        self,
+        *,
+        approval_policy: AskForApproval | None = None,
+        base_instructions: str | None = None,
+        config: JsonObject | None = None,
+        cwd: str | None = None,
+        developer_instructions: str | None = None,
+        ephemeral: bool | None = None,
+        model: str | None = None,
+        model_provider: str | None = None,
+        personality: Personality | None = None,
+        sandbox: SandboxMode | None = None,
+        service_name: str | None = None,
+        service_tier: ServiceTier | None = None,
+    ) -> AsyncThread:
+        await self._ensure_initialized()
+        params = ThreadStartParams(
+            approval_policy=approval_policy,
+            base_instructions=base_instructions,
+            config=config,
+            cwd=cwd,
+            developer_instructions=developer_instructions,
+            ephemeral=ephemeral,
+            model=model,
+            model_provider=model_provider,
+            personality=personality,
+            sandbox=sandbox,
+            service_name=service_name,
+            service_tier=service_tier,
+        )
+        started = await self._client.thread_start(params)
+        return AsyncThread(self, started.thread.id)
+
+    async def thread_list(
+        self,
+        *,
+        archived: bool | None = None,
+        cursor: str | None = None,
+        cwd: str | None = None,
+        limit: int | None = None,
+        model_providers: list[str] | None = None,
+        search_term: str | None = None,
+        sort_key: ThreadSortKey | None = None,
+        source_kinds: list[ThreadSourceKind] | None = None,
+    ) -> ThreadListResponse:
+        await self._ensure_initialized()
+        params = ThreadListParams(
+            archived=archived,
+            cursor=cursor,
+            cwd=cwd,
+            limit=limit,
+            model_providers=model_providers,
+            search_term=search_term,
+            sort_key=sort_key,
+            source_kinds=source_kinds,
+        )
+        return await self._client.thread_list(params)
+
+    async def thread_resume(
+        self,
+        thread_id: str,
+        *,
+        approval_policy: AskForApproval | None = None,
+        base_instructions: str | None = None,
+        config: JsonObject | None = None,
+        cwd: str | None = None,
+        developer_instructions: str | None = None,
+        model: str | None = None,
+        model_provider: str | None = None,
+        personality: Personality | None = None,
+        sandbox: SandboxMode | None = None,
+        service_tier: ServiceTier | None = None,
+    ) -> AsyncThread:
+        await self._ensure_initialized()
+        params = ThreadResumeParams(
+            thread_id=thread_id,
+            approval_policy=approval_policy,
+            base_instructions=base_instructions,
+            config=config,
+            cwd=cwd,
+            developer_instructions=developer_instructions,
+            model=model,
+            model_provider=model_provider,
+            personality=personality,
+            sandbox=sandbox,
+            service_tier=service_tier,
+        )
+        resumed = await self._client.thread_resume(thread_id, params)
+        return AsyncThread(self, resumed.thread.id)
+
+    async def thread_fork(
+        self,
+        thread_id: str,
+        *,
+        approval_policy: AskForApproval | None = None,
+        base_instructions: str | None = None,
+        config: JsonObject | None = None,
+        cwd: str | None = None,
+        developer_instructions: str | None = None,
+        ephemeral: bool | None = None,
+        model: str | None = None,
+        model_provider: str | None = None,
+        sandbox: SandboxMode | None = None,
+        service_tier: ServiceTier | None = None,
+    ) -> AsyncThread:
+        await self._ensure_initialized()
+        params = ThreadForkParams(
+            thread_id=thread_id,
+            approval_policy=approval_policy,
+            base_instructions=base_instructions,
+            config=config,
+            cwd=cwd,
+            developer_instructions=developer_instructions,
+            ephemeral=ephemeral,
+            model=model,
+            model_provider=model_provider,
+            sandbox=sandbox,
+            service_tier=service_tier,
+        )
+        forked = await self._client.thread_fork(thread_id, params)
+        return AsyncThread(self, forked.thread.id)
+
+    async def thread_archive(self, thread_id: str) -> ThreadArchiveResponse:
+        await self._ensure_initialized()
+        return await self._client.thread_archive(thread_id)
+
+    async def thread_unarchive(self, thread_id: str) -> AsyncThread:
+        await self._ensure_initialized()
+        unarchived = await self._client.thread_unarchive(thread_id)
+        return AsyncThread(self, unarchived.thread.id)
+    # END GENERATED: AsyncCodex.flat_methods
+
+    async def models(self, *, include_hidden: bool = False) -> ModelListResponse:
+        await self._ensure_initialized()
+        return await self._client.model_list(include_hidden=include_hidden)
+
+
+@dataclass(slots=True)
+class Thread:
+    _client: AppServerClient
+    id: str
+
+    # BEGIN GENERATED: Thread.flat_methods
+    def turn(
+        self,
+        input: Input,
+        *,
+        approval_policy: AskForApproval | None = None,
+        cwd: str | None = None,
+        effort: ReasoningEffort | None = None,
+        model: str | None = None,
+        output_schema: JsonObject | None = None,
+        personality: Personality | None = None,
+        sandbox_policy: SandboxPolicy | None = None,
+        service_tier: ServiceTier | None = None,
+        summary: ReasoningSummary | None = None,
+    ) -> Turn:
+        wire_input = _to_wire_input(input)
+        params = TurnStartParams(
+            thread_id=self.id,
+            input=wire_input,
+            approval_policy=approval_policy,
+            cwd=cwd,
+            effort=effort,
+            model=model,
+            output_schema=output_schema,
+            personality=personality,
+            sandbox_policy=sandbox_policy,
+            service_tier=service_tier,
+            summary=summary,
+        )
+        turn = self._client.turn_start(self.id, wire_input, params=params)
+        return Turn(self._client, self.id, turn.turn.id)
+    # END GENERATED: Thread.flat_methods
+
+    def read(self, *, include_turns: bool = False) -> ThreadReadResponse:
+        return self._client.thread_read(self.id, include_turns=include_turns)
+
+    def set_name(self, name: str) -> ThreadSetNameResponse:
+        return self._client.thread_set_name(self.id, name)
+
+    def compact(self) -> ThreadCompactStartResponse:
+        return self._client.thread_compact(self.id)
+
+
+@dataclass(slots=True)
+class AsyncThread:
+    _codex: AsyncCodex
+    id: str
+
+    # BEGIN GENERATED: AsyncThread.flat_methods
+    async def turn(
+        self,
+        input: Input,
+        *,
+        approval_policy: AskForApproval | None = None,
+        cwd: str | None = None,
+        effort: ReasoningEffort | None = None,
+        model: str | None = None,
+        output_schema: JsonObject | None = None,
+        personality: Personality | None = None,
+        sandbox_policy: SandboxPolicy | None = None,
+        service_tier: ServiceTier | None = None,
+        summary: ReasoningSummary | None = None,
+    ) -> AsyncTurn:
+        await self._codex._ensure_initialized()
+        wire_input = _to_wire_input(input)
+        params = TurnStartParams(
+            thread_id=self.id,
+            input=wire_input,
+            approval_policy=approval_policy,
+            cwd=cwd,
+            effort=effort,
+            model=model,
+            output_schema=output_schema,
+            personality=personality,
+            sandbox_policy=sandbox_policy,
+            service_tier=service_tier,
+            summary=summary,
+        )
+        turn = await self._codex._client.turn_start(
+            self.id,
+            wire_input,
+            params=params,
+        )
+        return AsyncTurn(self._codex, self.id, turn.turn.id)
+    # END GENERATED: AsyncThread.flat_methods
+
+    async def read(self, *, include_turns: bool = False) -> ThreadReadResponse:
+        await self._codex._ensure_initialized()
+        return await self._codex._client.thread_read(self.id, include_turns=include_turns)
+
+    async def set_name(self, name: str) -> ThreadSetNameResponse:
+        await self._codex._ensure_initialized()
+        return await self._codex._client.thread_set_name(self.id, name)
+
+    async def compact(self) -> ThreadCompactStartResponse:
+        await self._codex._ensure_initialized()
+        return await self._codex._client.thread_compact(self.id)
+
+
+@dataclass(slots=True)
+class Turn:
+    _client: AppServerClient
+    thread_id: str
+    id: str
+
+    def steer(self, input: Input) -> TurnSteerResponse:
+        return self._client.turn_steer(self.thread_id, self.id, _to_wire_input(input))
+
+    def interrupt(self) -> TurnInterruptResponse:
+        return self._client.turn_interrupt(self.thread_id, self.id)
+
+    def stream(self) -> Iterator[Notification]:
+        # TODO: replace this client-wide experimental guard with per-turn event demux.
+        self._client.acquire_turn_consumer(self.id)
+        try:
+            while True:
+                event = self._client.next_notification()
+                yield event
+                if (
+                    event.method == "turn/completed"
+                    and isinstance(event.payload, TurnCompletedNotificationPayload)
+                    and event.payload.turn.id == self.id
+                ):
+                    break
+        finally:
+            self._client.release_turn_consumer(self.id)
+
+    def run(self) -> TurnResult:
+        completed: TurnCompletedNotificationPayload | None = None
+        usage: ThreadTokenUsageUpdatedNotification | None = None
+        delta_chunks: list[str] = []
+        raw_text_chunks: list[str] = []
+
+        stream = self.stream()
+        try:
+            for event in stream:
+                payload = event.payload
+                if (
+                    isinstance(payload, AgentMessageDeltaNotification)
+                    and payload.turn_id == self.id
+                ):
+                    delta_chunks.append(payload.delta)
+                    continue
+                if (
+                    isinstance(payload, RawResponseItemCompletedNotification)
+                    and payload.turn_id == self.id
+                ):
+                    raw_text_chunks.extend(_assistant_output_text_chunks(payload))
+                    continue
+                if (
+                    isinstance(payload, ThreadTokenUsageUpdatedNotification)
+                    and payload.turn_id == self.id
+                ):
+                    usage = payload
+                    continue
+                if (
+                    isinstance(payload, TurnCompletedNotificationPayload)
+                    and payload.turn.id == self.id
+                ):
+                    completed = payload
+        finally:
+            stream.close()
+
+        return _build_turn_result(completed, usage, delta_chunks, raw_text_chunks)
+
+
+@dataclass(slots=True)
+class AsyncTurn:
+    _codex: AsyncCodex
+    thread_id: str
+    id: str
+
+    async def steer(self, input: Input) -> TurnSteerResponse:
+        await self._codex._ensure_initialized()
+        return await self._codex._client.turn_steer(
+            self.thread_id,
+            self.id,
+            _to_wire_input(input),
+        )
+
+    async def interrupt(self) -> TurnInterruptResponse:
+        await self._codex._ensure_initialized()
+        return await self._codex._client.turn_interrupt(self.thread_id, self.id)
+
+    async def stream(self) -> AsyncIterator[Notification]:
+        await self._codex._ensure_initialized()
+        # TODO: replace this client-wide experimental guard with per-turn event demux.
+        self._codex._client.acquire_turn_consumer(self.id)
+        try:
+            while True:
+                event = await self._codex._client.next_notification()
+                yield event
+                if (
+                    event.method == "turn/completed"
+                    and isinstance(event.payload, TurnCompletedNotificationPayload)
+                    and event.payload.turn.id == self.id
+                ):
+                    break
+        finally:
+            self._codex._client.release_turn_consumer(self.id)
+
+    async def run(self) -> TurnResult:
+        completed: TurnCompletedNotificationPayload | None = None
+        usage: ThreadTokenUsageUpdatedNotification | None = None
+        delta_chunks: list[str] = []
+        raw_text_chunks: list[str] = []
+
+        stream = self.stream()
+        try:
+            async for event in stream:
+                payload = event.payload
+                if (
+                    isinstance(payload, AgentMessageDeltaNotification)
+                    and payload.turn_id == self.id
+                ):
+                    delta_chunks.append(payload.delta)
+                    continue
+                if (
+                    isinstance(payload, RawResponseItemCompletedNotification)
+                    and payload.turn_id == self.id
+                ):
+                    raw_text_chunks.extend(_assistant_output_text_chunks(payload))
+                    continue
+                if (
+                    isinstance(payload, ThreadTokenUsageUpdatedNotification)
+                    and payload.turn_id == self.id
+                ):
+                    usage = payload
+                    continue
+                if (
+                    isinstance(payload, TurnCompletedNotificationPayload)
+                    and payload.turn.id == self.id
+                ):
+                    completed = payload
+        finally:
+            await stream.aclose()
+
+        return _build_turn_result(completed, usage, delta_chunks, raw_text_chunks)

sdk/python/src/codex_app_server/public_types.py

@@ -0,0 +1,41 @@
+"""Shallow public aliases over the generated v2 wire models."""
+
+from .generated.v2_all import (
+    AskForApproval,
+    Personality,
+    PlanType,
+    ReasoningEffort,
+    ReasoningSummary,
+    SandboxMode,
+    SandboxPolicy,
+    ServiceTier,
+    ThreadForkParams,
+    ThreadListParams,
+    ThreadResumeParams,
+    ThreadSortKey,
+    ThreadSourceKind,
+    ThreadStartParams,
+    TurnStartParams,
+    TurnStatus,
+    TurnSteerParams,
+)
+
+__all__ = [
+    "AskForApproval",
+    "Personality",
+    "PlanType",
+    "ReasoningEffort",
+    "ReasoningSummary",
+    "SandboxMode",
+    "SandboxPolicy",
+    "ServiceTier",
+    "ThreadForkParams",
+    "ThreadListParams",
+    "ThreadResumeParams",
+    "ThreadSortKey",
+    "ThreadSourceKind",
+    "ThreadStartParams",
+    "TurnStartParams",
+    "TurnStatus",
+    "TurnSteerParams",
+]

sdk/python/src/codex_app_server/retry.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import random
+import time
+from typing import Callable, TypeVar
+
+from .errors import is_retryable_error
+
+T = TypeVar("T")
+
+
+def retry_on_overload(
+    op: Callable[[], T],
+    *,
+    max_attempts: int = 3,
+    initial_delay_s: float = 0.25,
+    max_delay_s: float = 2.0,
+    jitter_ratio: float = 0.2,
+) -> T:
+    """Retry helper for transient server-overload errors."""
+
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be >= 1")
+
+    delay = initial_delay_s
+    attempt = 0
+    while True:
+        attempt += 1
+        try:
+            return op()
+        except Exception as exc:
+            if attempt >= max_attempts:
+                raise
+            if not is_retryable_error(exc):
+                raise
+
+            jitter = delay * jitter_ratio
+            sleep_for = min(max_delay_s, delay) + random.uniform(-jitter, jitter)
+            if sleep_for > 0:
+                time.sleep(sleep_for)
+            delay = min(max_delay_s, delay * 2)

sdk/python/tests/conftest.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+
+src_str = str(SRC)
+if src_str in sys.path:
+    sys.path.remove(src_str)
+sys.path.insert(0, src_str)
+
+for module_name in list(sys.modules):
+    if module_name == "codex_app_server" or module_name.startswith("codex_app_server."):
+        sys.modules.pop(module_name)

sdk/python/tests/test_artifact_workflow_and_binaries.py

@@ -0,0 +1,411 @@
+from __future__ import annotations
+
+import ast
+import importlib.util
+import json
+import sys
+import tomllib
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _load_update_script_module():
+    script_path = ROOT / "scripts" / "update_sdk_artifacts.py"
+    spec = importlib.util.spec_from_file_location("update_sdk_artifacts", script_path)
+    if spec is None or spec.loader is None:
+        raise AssertionError(f"Failed to load script module: {script_path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_generation_has_single_maintenance_entrypoint_script() -> None:
+    scripts = sorted(p.name for p in (ROOT / "scripts").glob("*.py"))
+    assert scripts == ["update_sdk_artifacts.py"]
+
+
+def test_generate_types_wires_all_generation_steps() -> None:
+    source = (ROOT / "scripts" / "update_sdk_artifacts.py").read_text()
+    tree = ast.parse(source)
+
+    generate_types_fn = next(
+        (
+            node
+            for node in tree.body
+            if isinstance(node, ast.FunctionDef) and node.name == "generate_types"
+        ),
+        None,
+    )
+    assert generate_types_fn is not None
+
+    calls: list[str] = []
+    for node in generate_types_fn.body:
+        if isinstance(node, ast.Expr) and isinstance(node.value, ast.Call):
+            fn = node.value.func
+            if isinstance(fn, ast.Name):
+                calls.append(fn.id)
+
+    assert calls == [
+        "generate_v2_all",
+        "generate_notification_registry",
+        "generate_public_api_flat_methods",
+    ]
+
+
+def test_schema_normalization_only_flattens_string_literal_oneofs() -> None:
+    script = _load_update_script_module()
+    schema = json.loads(
+        (
+            ROOT.parent.parent
+            / "codex-rs"
+            / "app-server-protocol"
+            / "schema"
+            / "json"
+            / "codex_app_server_protocol.v2.schemas.json"
+        ).read_text()
+    )
+
+    definitions = schema["definitions"]
+    flattened = [
+        name
+        for name, definition in definitions.items()
+        if isinstance(definition, dict)
+        and script._flatten_string_enum_one_of(definition.copy())
+    ]
+
+    assert flattened == [
+        "AuthMode",
+        "CommandExecOutputStream",
+        "ExperimentalFeatureStage",
+        "InputModality",
+        "MessagePhase",
+    ]
+
+
+def test_python_codegen_schema_annotation_adds_stable_variant_titles() -> None:
+    script = _load_update_script_module()
+    schema = json.loads(
+        (
+            ROOT.parent.parent
+            / "codex-rs"
+            / "app-server-protocol"
+            / "schema"
+            / "json"
+            / "codex_app_server_protocol.v2.schemas.json"
+        ).read_text()
+    )
+
+    script._annotate_schema(schema)
+    definitions = schema["definitions"]
+
+    server_notification_titles = {
+        variant.get("title")
+        for variant in definitions["ServerNotification"]["oneOf"]
+        if isinstance(variant, dict)
+    }
+    assert "ErrorServerNotification" in server_notification_titles
+    assert "ThreadStartedServerNotification" in server_notification_titles
+    assert "ErrorNotification" not in server_notification_titles
+    assert "Thread/startedNotification" not in server_notification_titles
+
+    ask_for_approval_titles = [
+        variant.get("title") for variant in definitions["AskForApproval"]["oneOf"]
+    ]
+    assert ask_for_approval_titles == [
+        "AskForApprovalValue",
+        "RejectAskForApproval",
+    ]
+
+    reasoning_summary_titles = [
+        variant.get("title") for variant in definitions["ReasoningSummary"]["oneOf"]
+    ]
+    assert reasoning_summary_titles == [
+        "ReasoningSummaryValue",
+        "NoneReasoningSummary",
+    ]
+
+
+def test_generate_v2_all_uses_titles_for_generated_names() -> None:
+    source = (ROOT / "scripts" / "update_sdk_artifacts.py").read_text()
+    assert "--use-title-as-name" in source
+    assert "--use-annotated" in source
+    assert "--formatters" in source
+    assert "ruff-format" in source
+
+
+def test_runtime_package_template_has_no_checked_in_binaries() -> None:
+    runtime_root = ROOT.parent / "python-runtime" / "src" / "codex_cli_bin"
+    assert sorted(
+        path.name
+        for path in runtime_root.rglob("*")
+        if path.is_file() and "__pycache__" not in path.parts
+    ) == ["__init__.py"]
+
+
+def test_runtime_package_is_wheel_only_and_builds_platform_specific_wheels() -> None:
+    pyproject = tomllib.loads(
+        (ROOT.parent / "python-runtime" / "pyproject.toml").read_text()
+    )
+    hook_source = (ROOT.parent / "python-runtime" / "hatch_build.py").read_text()
+    hook_tree = ast.parse(hook_source)
+    initialize_fn = next(
+        node
+        for node in ast.walk(hook_tree)
+        if isinstance(node, ast.FunctionDef) and node.name == "initialize"
+    )
+
+    sdist_guard = next(
+        (
+            node
+            for node in initialize_fn.body
+            if isinstance(node, ast.If)
+            and isinstance(node.test, ast.Compare)
+            and isinstance(node.test.left, ast.Attribute)
+            and isinstance(node.test.left.value, ast.Name)
+            and node.test.left.value.id == "self"
+            and node.test.left.attr == "target_name"
+            and len(node.test.ops) == 1
+            and isinstance(node.test.ops[0], ast.Eq)
+            and len(node.test.comparators) == 1
+            and isinstance(node.test.comparators[0], ast.Constant)
+            and node.test.comparators[0].value == "sdist"
+        ),
+        None,
+    )
+    build_data_assignments = {
+        node.targets[0].slice.value: node.value.value
+        for node in initialize_fn.body
+        if isinstance(node, ast.Assign)
+        and len(node.targets) == 1
+        and isinstance(node.targets[0], ast.Subscript)
+        and isinstance(node.targets[0].value, ast.Name)
+        and node.targets[0].value.id == "build_data"
+        and isinstance(node.targets[0].slice, ast.Constant)
+        and isinstance(node.targets[0].slice.value, str)
+        and isinstance(node.value, ast.Constant)
+    }
+
+    assert pyproject["tool"]["hatch"]["build"]["targets"]["wheel"] == {
+        "packages": ["src/codex_cli_bin"],
+        "include": ["src/codex_cli_bin/bin/**"],
+        "hooks": {"custom": {}},
+    }
+    assert pyproject["tool"]["hatch"]["build"]["targets"]["sdist"] == {
+        "hooks": {"custom": {}},
+    }
+    assert sdist_guard is not None
+    assert build_data_assignments == {"pure_python": False, "infer_tag": True}
+
+
+def test_stage_runtime_release_copies_binary_and_sets_version(tmp_path: Path) -> None:
+    script = _load_update_script_module()
+    fake_binary = tmp_path / script.runtime_binary_name()
+    fake_binary.write_text("fake codex\n")
+
+    staged = script.stage_python_runtime_package(
+        tmp_path / "runtime-stage",
+        "1.2.3",
+        fake_binary,
+    )
+
+    assert staged == tmp_path / "runtime-stage"
+    assert script.staged_runtime_bin_path(staged).read_text() == "fake codex\n"
+    assert 'version = "1.2.3"' in (staged / "pyproject.toml").read_text()
+
+
+def test_stage_runtime_release_replaces_existing_staging_dir(tmp_path: Path) -> None:
+    script = _load_update_script_module()
+    staging_dir = tmp_path / "runtime-stage"
+    old_file = staging_dir / "stale.txt"
+    old_file.parent.mkdir(parents=True)
+    old_file.write_text("stale")
+
+    fake_binary = tmp_path / script.runtime_binary_name()
+    fake_binary.write_text("fake codex\n")
+
+    staged = script.stage_python_runtime_package(
+        staging_dir,
+        "1.2.3",
+        fake_binary,
+    )
+
+    assert staged == staging_dir
+    assert not old_file.exists()
+    assert script.staged_runtime_bin_path(staged).read_text() == "fake codex\n"
+
+
+def test_stage_sdk_release_injects_exact_runtime_pin(tmp_path: Path) -> None:
+    script = _load_update_script_module()
+    staged = script.stage_python_sdk_package(tmp_path / "sdk-stage", "0.2.1", "1.2.3")
+
+    pyproject = (staged / "pyproject.toml").read_text()
+    assert 'version = "0.2.1"' in pyproject
+    assert '"codex-cli-bin==1.2.3"' in pyproject
+    assert not any((staged / "src" / "codex_app_server").glob("bin/**"))
+
+
+def test_stage_sdk_release_replaces_existing_staging_dir(tmp_path: Path) -> None:
+    script = _load_update_script_module()
+    staging_dir = tmp_path / "sdk-stage"
+    old_file = staging_dir / "stale.txt"
+    old_file.parent.mkdir(parents=True)
+    old_file.write_text("stale")
+
+    staged = script.stage_python_sdk_package(staging_dir, "0.2.1", "1.2.3")
+
+    assert staged == staging_dir
+    assert not old_file.exists()
+
+
+def test_stage_sdk_runs_type_generation_before_staging(tmp_path: Path) -> None:
+    script = _load_update_script_module()
+    calls: list[str] = []
+    args = script.parse_args(
+        [
+            "stage-sdk",
+            str(tmp_path / "sdk-stage"),
+            "--runtime-version",
+            "1.2.3",
+        ]
+    )
+
+    def fake_generate_types() -> None:
+        calls.append("generate_types")
+
+    def fake_stage_sdk_package(
+        _staging_dir: Path, _sdk_version: str, _runtime_version: str
+    ) -> Path:
+        calls.append("stage_sdk")
+        return tmp_path / "sdk-stage"
+
+    def fake_stage_runtime_package(
+        _staging_dir: Path, _runtime_version: str, _runtime_binary: Path
+    ) -> Path:
+        raise AssertionError("runtime staging should not run for stage-sdk")
+
+    def fake_current_sdk_version() -> str:
+        return "0.2.0"
+
+    ops = script.CliOps(
+        generate_types=fake_generate_types,
+        stage_python_sdk_package=fake_stage_sdk_package,
+        stage_python_runtime_package=fake_stage_runtime_package,
+        current_sdk_version=fake_current_sdk_version,
+    )
+
+    script.run_command(args, ops)
+
+    assert calls == ["generate_types", "stage_sdk"]
+
+
+def test_stage_runtime_stages_binary_without_type_generation(tmp_path: Path) -> None:
+    script = _load_update_script_module()
+    fake_binary = tmp_path / script.runtime_binary_name()
+    fake_binary.write_text("fake codex\n")
+    calls: list[str] = []
+    args = script.parse_args(
+        [
+            "stage-runtime",
+            str(tmp_path / "runtime-stage"),
+            str(fake_binary),
+            "--runtime-version",
+            "1.2.3",
+        ]
+    )
+
+    def fake_generate_types() -> None:
+        calls.append("generate_types")
+
+    def fake_stage_sdk_package(
+        _staging_dir: Path, _sdk_version: str, _runtime_version: str
+    ) -> Path:
+        raise AssertionError("sdk staging should not run for stage-runtime")
+
+    def fake_stage_runtime_package(
+        _staging_dir: Path, _runtime_version: str, _runtime_binary: Path
+    ) -> Path:
+        calls.append("stage_runtime")
+        return tmp_path / "runtime-stage"
+
+    def fake_current_sdk_version() -> str:
+        return "0.2.0"
+
+    ops = script.CliOps(
+        generate_types=fake_generate_types,
+        stage_python_sdk_package=fake_stage_sdk_package,
+        stage_python_runtime_package=fake_stage_runtime_package,
+        current_sdk_version=fake_current_sdk_version,
+    )
+
+    script.run_command(args, ops)
+
+    assert calls == ["stage_runtime"]
+
+
+def test_default_runtime_is_resolved_from_installed_runtime_package(
+    tmp_path: Path,
+) -> None:
+    from codex_app_server import client as client_module
+
+    fake_binary = tmp_path / ("codex.exe" if client_module.os.name == "nt" else "codex")
+    fake_binary.write_text("")
+    ops = client_module.CodexBinResolverOps(
+        installed_codex_path=lambda: fake_binary,
+        path_exists=lambda path: path == fake_binary,
+    )
+
+    config = client_module.AppServerConfig()
+    assert config.codex_bin is None
+    assert client_module.resolve_codex_bin(config, ops) == fake_binary
+
+
+def test_explicit_codex_bin_override_takes_priority(tmp_path: Path) -> None:
+    from codex_app_server import client as client_module
+
+    explicit_binary = tmp_path / (
+        "custom-codex.exe" if client_module.os.name == "nt" else "custom-codex"
+    )
+    explicit_binary.write_text("")
+    ops = client_module.CodexBinResolverOps(
+        installed_codex_path=lambda: (_ for _ in ()).throw(
+            AssertionError("packaged runtime should not be used")
+        ),
+        path_exists=lambda path: path == explicit_binary,
+    )
+
+    config = client_module.AppServerConfig(codex_bin=str(explicit_binary))
+    assert client_module.resolve_codex_bin(config, ops) == explicit_binary
+
+
+def test_missing_runtime_package_requires_explicit_codex_bin() -> None:
+    from codex_app_server import client as client_module
+
+    ops = client_module.CodexBinResolverOps(
+        installed_codex_path=lambda: (_ for _ in ()).throw(
+            FileNotFoundError("missing packaged runtime")
+        ),
+        path_exists=lambda _path: False,
+    )
+
+    with pytest.raises(FileNotFoundError, match="missing packaged runtime"):
+        client_module.resolve_codex_bin(client_module.AppServerConfig(), ops)
+
+
+def test_broken_runtime_package_does_not_fall_back() -> None:
+    from codex_app_server import client as client_module
+
+    ops = client_module.CodexBinResolverOps(
+        installed_codex_path=lambda: (_ for _ in ()).throw(
+            FileNotFoundError("missing packaged binary")
+        ),
+        path_exists=lambda _path: False,
+    )
+
+    with pytest.raises(FileNotFoundError) as exc_info:
+        client_module.resolve_codex_bin(client_module.AppServerConfig(), ops)
+
+    assert str(exc_info.value) == ("missing packaged binary")

sdk/python/tests/test_async_client_behavior.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import asyncio
+import time
+
+from codex_app_server.async_client import AsyncAppServerClient
+
+
+def test_async_client_serializes_transport_calls() -> None:
+    async def scenario() -> int:
+        client = AsyncAppServerClient()
+        active = 0
+        max_active = 0
+
+        def fake_model_list(include_hidden: bool = False) -> bool:
+            nonlocal active, max_active
+            active += 1
+            max_active = max(max_active, active)
+            time.sleep(0.05)
+            active -= 1
+            return include_hidden
+
+        client._sync.model_list = fake_model_list  # type: ignore[method-assign]
+        await asyncio.gather(client.model_list(), client.model_list())
+        return max_active
+
+    assert asyncio.run(scenario()) == 1
+
+
+def test_async_stream_text_is_incremental_and_blocks_parallel_calls() -> None:
+    async def scenario() -> tuple[str, list[str], bool]:
+        client = AsyncAppServerClient()
+
+        def fake_stream_text(thread_id: str, text: str, params=None):  # type: ignore[no-untyped-def]
+            yield "first"
+            time.sleep(0.03)
+            yield "second"
+            yield "third"
+
+        def fake_model_list(include_hidden: bool = False) -> str:
+            return "done"
+
+        client._sync.stream_text = fake_stream_text  # type: ignore[method-assign]
+        client._sync.model_list = fake_model_list  # type: ignore[method-assign]
+
+        stream = client.stream_text("thread-1", "hello")
+        first = await anext(stream)
+
+        blocked_before_stream_done = False
+        competing_call = asyncio.create_task(client.model_list())
+        await asyncio.sleep(0.01)
+        blocked_before_stream_done = not competing_call.done()
+
+        remaining: list[str] = []
+        async for item in stream:
+            remaining.append(item)
+
+        await competing_call
+        return first, remaining, blocked_before_stream_done
+
+    first, remaining, blocked = asyncio.run(scenario())
+    assert first == "first"
+    assert remaining == ["second", "third"]
+    assert blocked

sdk/python/tests/test_client_rpc_methods.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from codex_app_server.client import AppServerClient, _params_dict
+from codex_app_server.generated.v2_all import ThreadListParams, ThreadTokenUsageUpdatedNotification
+from codex_app_server.models import UnknownNotification
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_thread_set_name_and_compact_use_current_rpc_methods() -> None:
+    client = AppServerClient()
+    calls: list[tuple[str, dict[str, Any] | None]] = []
+
+    def fake_request(method: str, params, *, response_model):  # type: ignore[no-untyped-def]
+        calls.append((method, params))
+        return response_model.model_validate({})
+
+    client.request = fake_request  # type: ignore[method-assign]
+
+    client.thread_set_name("thread-1", "sdk-name")
+    client.thread_compact("thread-1")
+
+    assert calls[0][0] == "thread/name/set"
+    assert calls[1][0] == "thread/compact/start"
+
+
+def test_generated_params_models_are_snake_case_and_dump_by_alias() -> None:
+    params = ThreadListParams(search_term="needle", limit=5)
+
+    assert "search_term" in ThreadListParams.model_fields
+    dumped = _params_dict(params)
+    assert dumped == {"searchTerm": "needle", "limit": 5}
+
+
+def test_generated_v2_bundle_has_single_shared_plan_type_definition() -> None:
+    source = (ROOT / "src" / "codex_app_server" / "generated" / "v2_all.py").read_text()
+    assert source.count("class PlanType(") == 1
+
+
+def test_notifications_are_typed_with_canonical_v2_methods() -> None:
+    client = AppServerClient()
+    event = client._coerce_notification(
+        "thread/tokenUsage/updated",
+        {
+            "threadId": "thread-1",
+            "turnId": "turn-1",
+            "tokenUsage": {
+                "last": {
+                    "cachedInputTokens": 0,
+                    "inputTokens": 1,
+                    "outputTokens": 2,
+                    "reasoningOutputTokens": 0,
+                    "totalTokens": 3,
+                },
+                "total": {
+                    "cachedInputTokens": 0,
+                    "inputTokens": 1,
+                    "outputTokens": 2,
+                    "reasoningOutputTokens": 0,
+                    "totalTokens": 3,
+                },
+            },
+        },
+    )
+
+    assert event.method == "thread/tokenUsage/updated"
+    assert isinstance(event.payload, ThreadTokenUsageUpdatedNotification)
+    assert event.payload.turn_id == "turn-1"
+
+
+def test_unknown_notifications_fall_back_to_unknown_payloads() -> None:
+    client = AppServerClient()
+    event = client._coerce_notification(
+        "unknown/notification",
+        {
+            "id": "evt-1",
+            "conversationId": "thread-1",
+            "msg": {"type": "turn_aborted"},
+        },
+    )
+
+    assert event.method == "unknown/notification"
+    assert isinstance(event.payload, UnknownNotification)
+    assert event.payload.params["msg"] == {"type": "turn_aborted"}
+
+
+def test_invalid_notification_payload_falls_back_to_unknown() -> None:
+    client = AppServerClient()
+    event = client._coerce_notification("thread/tokenUsage/updated", {"threadId": "missing"})
+
+    assert event.method == "thread/tokenUsage/updated"
+    assert isinstance(event.payload, UnknownNotification)

sdk/python/tests/test_contract_generation.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+GENERATED_TARGETS = [
+    Path("src/codex_app_server/generated/notification_registry.py"),
+    Path("src/codex_app_server/generated/v2_all.py"),
+    Path("src/codex_app_server/public_api.py"),
+]
+
+
+def _snapshot_target(root: Path, rel_path: Path) -> dict[str, bytes] | bytes | None:
+    target = root / rel_path
+    if not target.exists():
+        return None
+    if target.is_file():
+        return target.read_bytes()
+
+    snapshot: dict[str, bytes] = {}
+    for path in sorted(target.rglob("*")):
+        if path.is_file() and "__pycache__" not in path.parts:
+            snapshot[str(path.relative_to(target))] = path.read_bytes()
+    return snapshot
+
+
+def _snapshot_targets(root: Path) -> dict[str, dict[str, bytes] | bytes | None]:
+    return {
+        str(rel_path): _snapshot_target(root, rel_path) for rel_path in GENERATED_TARGETS
+    }
+
+
+def test_generated_files_are_up_to_date():
+    before = _snapshot_targets(ROOT)
+
+    # Regenerate contract artifacts via single maintenance entrypoint.
+    env = os.environ.copy()
+    python_bin = str(Path(sys.executable).parent)
+    env["PATH"] = f"{python_bin}{os.pathsep}{env.get('PATH', '')}"
+
+    subprocess.run(
+        [sys.executable, "scripts/update_sdk_artifacts.py", "generate-types"],
+        cwd=ROOT,
+        check=True,
+        env=env,
+    )
+
+    after = _snapshot_targets(ROOT)
+    assert before == after, "Generated files drifted after regeneration"

sdk/python/tests/test_public_api_runtime_behavior.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+from pathlib import Path
+
+import pytest
+
+import codex_app_server.public_api as public_api_module
+from codex_app_server.client import AppServerClient
+from codex_app_server.generated.v2_all import (
+    AgentMessageDeltaNotification,
+    RawResponseItemCompletedNotification,
+    ThreadTokenUsageUpdatedNotification,
+)
+from codex_app_server.models import InitializeResponse, Notification
+from codex_app_server.public_api import AsyncCodex, AsyncTurn, Codex, Turn
+from codex_app_server.public_types import TurnStatus
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _delta_notification(
+    *,
+    thread_id: str = "thread-1",
+    turn_id: str = "turn-1",
+    text: str = "delta-text",
+) -> Notification:
+    return Notification(
+        method="item/agentMessage/delta",
+        payload=AgentMessageDeltaNotification.model_validate(
+            {
+                "delta": text,
+                "itemId": "item-1",
+                "threadId": thread_id,
+                "turnId": turn_id,
+            }
+        ),
+    )
+
+
+def _raw_response_notification(
+    *,
+    thread_id: str = "thread-1",
+    turn_id: str = "turn-1",
+    text: str = "raw-text",
+) -> Notification:
+    return Notification(
+        method="rawResponseItem/completed",
+        payload=RawResponseItemCompletedNotification.model_validate(
+            {
+                "item": {
+                    "type": "message",
+                    "role": "assistant",
+                    "content": [{"type": "output_text", "text": text}],
+                },
+                "threadId": thread_id,
+                "turnId": turn_id,
+            }
+        ),
+    )
+
+
+def _usage_notification(
+    *,
+    thread_id: str = "thread-1",
+    turn_id: str = "turn-1",
+) -> Notification:
+    return Notification(
+        method="thread/tokenUsage/updated",
+        payload=ThreadTokenUsageUpdatedNotification.model_validate(
+            {
+                "threadId": thread_id,
+                "turnId": turn_id,
+                "tokenUsage": {
+                    "last": {
+                        "cachedInputTokens": 0,
+                        "inputTokens": 1,
+                        "outputTokens": 2,
+                        "reasoningOutputTokens": 0,
+                        "totalTokens": 3,
+                    },
+                    "total": {
+                        "cachedInputTokens": 0,
+                        "inputTokens": 1,
+                        "outputTokens": 2,
+                        "reasoningOutputTokens": 0,
+                        "totalTokens": 3,
+                    },
+                },
+            }
+        ),
+    )
+
+
+def _completed_notification(
+    *,
+    thread_id: str = "thread-1",
+    turn_id: str = "turn-1",
+    status: str = "completed",
+) -> Notification:
+    return Notification(
+        method="turn/completed",
+        payload=public_api_module.TurnCompletedNotificationPayload.model_validate(
+            {
+                "threadId": thread_id,
+                "turn": {
+                    "id": turn_id,
+                    "items": [],
+                    "status": status,
+                },
+            }
+        ),
+    )
+
+
+def test_codex_init_failure_closes_client(monkeypatch: pytest.MonkeyPatch) -> None:
+    closed: list[bool] = []
+
+    class FakeClient:
+        def __init__(self, config=None) -> None:  # noqa: ANN001,ARG002
+            self._closed = False
+
+        def start(self) -> None:
+            return None
+
+        def initialize(self) -> InitializeResponse:
+            return InitializeResponse.model_validate({})
+
+        def close(self) -> None:
+            self._closed = True
+            closed.append(True)
+
+    monkeypatch.setattr(public_api_module, "AppServerClient", FakeClient)
+
+    with pytest.raises(RuntimeError, match="missing required metadata"):
+        Codex()
+
+    assert closed == [True]
+
+
+def test_async_codex_init_failure_closes_client() -> None:
+    async def scenario() -> None:
+        codex = AsyncCodex()
+        close_calls = 0
+
+        async def fake_start() -> None:
+            return None
+
+        async def fake_initialize() -> InitializeResponse:
+            return InitializeResponse.model_validate({})
+
+        async def fake_close() -> None:
+            nonlocal close_calls
+            close_calls += 1
+
+        codex._client.start = fake_start  # type: ignore[method-assign]
+        codex._client.initialize = fake_initialize  # type: ignore[method-assign]
+        codex._client.close = fake_close  # type: ignore[method-assign]
+
+        with pytest.raises(RuntimeError, match="missing required metadata"):
+            await codex.models()
+
+        assert close_calls == 1
+        assert codex._initialized is False
+        assert codex._init is None
+
+    asyncio.run(scenario())
+
+
+def test_async_codex_initializes_only_once_under_concurrency() -> None:
+    async def scenario() -> None:
+        codex = AsyncCodex()
+        start_calls = 0
+        initialize_calls = 0
+        ready = asyncio.Event()
+
+        async def fake_start() -> None:
+            nonlocal start_calls
+            start_calls += 1
+
+        async def fake_initialize() -> InitializeResponse:
+            nonlocal initialize_calls
+            initialize_calls += 1
+            ready.set()
+            await asyncio.sleep(0.02)
+            return InitializeResponse.model_validate(
+                {
+                    "userAgent": "codex-cli/1.2.3",
+                    "serverInfo": {"name": "codex-cli", "version": "1.2.3"},
+                }
+            )
+
+        async def fake_model_list(include_hidden: bool = False):  # noqa: ANN202,ARG001
+            await ready.wait()
+            return object()
+
+        codex._client.start = fake_start  # type: ignore[method-assign]
+        codex._client.initialize = fake_initialize  # type: ignore[method-assign]
+        codex._client.model_list = fake_model_list  # type: ignore[method-assign]
+
+        await asyncio.gather(codex.models(), codex.models())
+
+        assert start_calls == 1
+        assert initialize_calls == 1
+
+    asyncio.run(scenario())
+
+
+def test_turn_stream_rejects_second_active_consumer() -> None:
+    client = AppServerClient()
+    notifications: deque[Notification] = deque(
+        [
+            _delta_notification(turn_id="turn-1"),
+            _completed_notification(turn_id="turn-1"),
+        ]
+    )
+    client.next_notification = notifications.popleft  # type: ignore[method-assign]
+
+    first_stream = Turn(client, "thread-1", "turn-1").stream()
+    assert next(first_stream).method == "item/agentMessage/delta"
+
+    second_stream = Turn(client, "thread-1", "turn-2").stream()
+    with pytest.raises(RuntimeError, match="Concurrent turn consumers are not yet supported"):
+        next(second_stream)
+
+    first_stream.close()
+
+
+def test_async_turn_stream_rejects_second_active_consumer() -> None:
+    async def scenario() -> None:
+        codex = AsyncCodex()
+
+        async def fake_ensure_initialized() -> None:
+            return None
+
+        notifications: deque[Notification] = deque(
+            [
+                _delta_notification(turn_id="turn-1"),
+                _completed_notification(turn_id="turn-1"),
+            ]
+        )
+
+        async def fake_next_notification() -> Notification:
+            return notifications.popleft()
+
+        codex._ensure_initialized = fake_ensure_initialized  # type: ignore[method-assign]
+        codex._client.next_notification = fake_next_notification  # type: ignore[method-assign]
+
+        first_stream = AsyncTurn(codex, "thread-1", "turn-1").stream()
+        assert (await anext(first_stream)).method == "item/agentMessage/delta"
+
+        second_stream = AsyncTurn(codex, "thread-1", "turn-2").stream()
+        with pytest.raises(RuntimeError, match="Concurrent turn consumers are not yet supported"):
+            await anext(second_stream)
+
+        await first_stream.aclose()
+
+    asyncio.run(scenario())
+
+
+def test_turn_run_falls_back_to_completed_raw_response_text() -> None:
+    client = AppServerClient()
+    notifications: deque[Notification] = deque(
+        [
+            _raw_response_notification(text="hello from raw response"),
+            _usage_notification(),
+            _completed_notification(),
+        ]
+    )
+    client.next_notification = notifications.popleft  # type: ignore[method-assign]
+
+    result = Turn(client, "thread-1", "turn-1").run()
+
+    assert result.status == TurnStatus.completed
+    assert result.text == "hello from raw response"
+
+
+def test_retry_examples_compare_status_with_enum() -> None:
+    for path in (
+        ROOT / "examples" / "10_error_handling_and_retry" / "sync.py",
+        ROOT / "examples" / "10_error_handling_and_retry" / "async.py",
+    ):
+        source = path.read_text()
+        assert '== "failed"' not in source
+        assert "TurnStatus.failed" in source

sdk/python/tests/test_public_api_signatures.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import importlib.resources as resources
+import inspect
+from typing import Any
+
+from codex_app_server import AppServerConfig
+from codex_app_server.models import InitializeResponse
+from codex_app_server.public_api import AsyncCodex, AsyncThread, Codex, Thread
+
+
+def _keyword_only_names(fn: object) -> list[str]:
+    signature = inspect.signature(fn)
+    return [
+        param.name
+        for param in signature.parameters.values()
+        if param.kind == inspect.Parameter.KEYWORD_ONLY
+    ]
+
+
+def _assert_no_any_annotations(fn: object) -> None:
+    signature = inspect.signature(fn)
+    for param in signature.parameters.values():
+        if param.annotation is Any:
+            raise AssertionError(f"{fn} has public parameter typed as Any: {param.name}")
+    if signature.return_annotation is Any:
+        raise AssertionError(f"{fn} has public return annotation typed as Any")
+
+
+def test_root_exports_app_server_config() -> None:
+    assert AppServerConfig.__name__ == "AppServerConfig"
+
+
+def test_package_includes_py_typed_marker() -> None:
+    marker = resources.files("codex_app_server").joinpath("py.typed")
+    assert marker.is_file()
+
+
+def test_generated_public_signatures_are_snake_case_and_typed() -> None:
+    expected = {
+        Codex.thread_start: [
+            "approval_policy",
+            "base_instructions",
+            "config",
+            "cwd",
+            "developer_instructions",
+            "ephemeral",
+            "model",
+            "model_provider",
+            "personality",
+            "sandbox",
+            "service_name",
+            "service_tier",
+        ],
+        Codex.thread_list: [
+            "archived",
+            "cursor",
+            "cwd",
+            "limit",
+            "model_providers",
+            "search_term",
+            "sort_key",
+            "source_kinds",
+        ],
+        Codex.thread_resume: [
+            "approval_policy",
+            "base_instructions",
+            "config",
+            "cwd",
+            "developer_instructions",
+            "model",
+            "model_provider",
+            "personality",
+            "sandbox",
+            "service_tier",
+        ],
+        Codex.thread_fork: [
+            "approval_policy",
+            "base_instructions",
+            "config",
+            "cwd",
+            "developer_instructions",
+            "ephemeral",
+            "model",
+            "model_provider",
+            "sandbox",
+            "service_tier",
+        ],
+        Thread.turn: [
+            "approval_policy",
+            "cwd",
+            "effort",
+            "model",
+            "output_schema",
+            "personality",
+            "sandbox_policy",
+            "service_tier",
+            "summary",
+        ],
+        AsyncCodex.thread_start: [
+            "approval_policy",
+            "base_instructions",
+            "config",
+            "cwd",
+            "developer_instructions",
+            "ephemeral",
+            "model",
+            "model_provider",
+            "personality",
+            "sandbox",
+            "service_name",
+            "service_tier",
+        ],
+        AsyncCodex.thread_list: [
+            "archived",
+            "cursor",
+            "cwd",
+            "limit",
+            "model_providers",
+            "search_term",
+            "sort_key",
+            "source_kinds",
+        ],
+        AsyncCodex.thread_resume: [
+            "approval_policy",
+            "base_instructions",
+            "config",
+            "cwd",
+            "developer_instructions",
+            "model",
+            "model_provider",
+            "personality",
+            "sandbox",
+            "service_tier",
+        ],
+        AsyncCodex.thread_fork: [
+            "approval_policy",
+            "base_instructions",
+            "config",
+            "cwd",
+            "developer_instructions",
+            "ephemeral",
+            "model",
+            "model_provider",
+            "sandbox",
+            "service_tier",
+        ],
+        AsyncThread.turn: [
+            "approval_policy",
+            "cwd",
+            "effort",
+            "model",
+            "output_schema",
+            "personality",
+            "sandbox_policy",
+            "service_tier",
+            "summary",
+        ],
+    }
+
+    for fn, expected_kwargs in expected.items():
+        actual = _keyword_only_names(fn)
+        assert actual == expected_kwargs, f"unexpected kwargs for {fn}: {actual}"
+        assert all(name == name.lower() for name in actual), f"non snake_case kwargs in {fn}: {actual}"
+        _assert_no_any_annotations(fn)
+
+
+def test_lifecycle_methods_are_codex_scoped() -> None:
+    assert hasattr(Codex, "thread_resume")
+    assert hasattr(Codex, "thread_fork")
+    assert hasattr(Codex, "thread_archive")
+    assert hasattr(Codex, "thread_unarchive")
+    assert hasattr(AsyncCodex, "thread_resume")
+    assert hasattr(AsyncCodex, "thread_fork")
+    assert hasattr(AsyncCodex, "thread_archive")
+    assert hasattr(AsyncCodex, "thread_unarchive")
+    assert not hasattr(Codex, "thread")
+    assert not hasattr(AsyncCodex, "thread")
+
+    assert not hasattr(Thread, "resume")
+    assert not hasattr(Thread, "fork")
+    assert not hasattr(Thread, "archive")
+    assert not hasattr(Thread, "unarchive")
+    assert not hasattr(AsyncThread, "resume")
+    assert not hasattr(AsyncThread, "fork")
+    assert not hasattr(AsyncThread, "archive")
+    assert not hasattr(AsyncThread, "unarchive")
+
+    for fn in (
+        Codex.thread_archive,
+        Codex.thread_unarchive,
+        AsyncCodex.thread_archive,
+        AsyncCodex.thread_unarchive,
+    ):
+        _assert_no_any_annotations(fn)
+
+
+def test_initialize_metadata_parses_user_agent_shape() -> None:
+    parsed = Codex._parse_initialize(InitializeResponse.model_validate({"userAgent": "codex-cli/1.2.3"}))
+    assert parsed.user_agent == "codex-cli/1.2.3"
+    assert parsed.server_name == "codex-cli"
+    assert parsed.server_version == "1.2.3"
+
+
+def test_initialize_metadata_requires_non_empty_information() -> None:
+    try:
+        Codex._parse_initialize(InitializeResponse.model_validate({}))
+    except RuntimeError as exc:
+        assert "missing required metadata" in str(exc)
+    else:
+        raise AssertionError("expected RuntimeError when initialize metadata is missing")

sdk/python/tests/test_real_app_server_integration.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from codex_app_server import AppServerConfig, AsyncCodex, Codex, TextInput
+
+ROOT = Path(__file__).resolve().parents[1]
+EXAMPLES_DIR = ROOT / "examples"
+NOTEBOOK_PATH = ROOT / "notebooks" / "sdk_walkthrough.ipynb"
+
+RUN_REAL_CODEX_TESTS = os.environ.get("RUN_REAL_CODEX_TESTS") == "1"
+pytestmark = pytest.mark.skipif(
+    not RUN_REAL_CODEX_TESTS,
+    reason="set RUN_REAL_CODEX_TESTS=1 to run real Codex integration coverage",
+)
+
+# 11_cli_mini_app is interactive; we still run it by feeding '/exit'.
+EXAMPLE_CASES: list[tuple[str, str]] = [
+    ("01_quickstart_constructor", "sync.py"),
+    ("01_quickstart_constructor", "async.py"),
+    ("02_turn_run", "sync.py"),
+    ("02_turn_run", "async.py"),
+    ("03_turn_stream_events", "sync.py"),
+    ("03_turn_stream_events", "async.py"),
+    ("04_models_and_metadata", "sync.py"),
+    ("04_models_and_metadata", "async.py"),
+    ("05_existing_thread", "sync.py"),
+    ("05_existing_thread", "async.py"),
+    ("06_thread_lifecycle_and_controls", "sync.py"),
+    ("06_thread_lifecycle_and_controls", "async.py"),
+    ("07_image_and_text", "sync.py"),
+    ("07_image_and_text", "async.py"),
+    ("08_local_image_and_text", "sync.py"),
+    ("08_local_image_and_text", "async.py"),
+    ("09_async_parity", "sync.py"),
+    # 09_async_parity async path is represented by 01 async + dedicated async-based cases above.
+    ("10_error_handling_and_retry", "sync.py"),
+    ("10_error_handling_and_retry", "async.py"),
+    ("11_cli_mini_app", "sync.py"),
+    ("11_cli_mini_app", "async.py"),
+    ("12_turn_params_kitchen_sink", "sync.py"),
+    ("12_turn_params_kitchen_sink", "async.py"),
+    ("13_model_select_and_turn_params", "sync.py"),
+    ("13_model_select_and_turn_params", "async.py"),
+]
+
+
+def _run_example(
+    folder: str, script: str, *, timeout_s: int = 150
+) -> subprocess.CompletedProcess[str]:
+    path = EXAMPLES_DIR / folder / script
+    assert path.exists(), f"Missing example script: {path}"
+
+    env = os.environ.copy()
+    env.setdefault(
+        "CODEX_PYTHON_SDK_CODEX_BIN",
+        _real_test_config().codex_bin or "",
+    )
+
+    # Feed '/exit' only to interactive mini-cli examples.
+    stdin = "/exit\n" if folder == "11_cli_mini_app" else None
+
+    return subprocess.run(
+        [sys.executable, str(path)],
+        cwd=str(ROOT),
+        env=env,
+        input=stdin,
+        text=True,
+        capture_output=True,
+        timeout=timeout_s,
+        check=False,
+    )
+
+
+def _notebook_cell_source(cell_index: int) -> str:
+    notebook = json.loads(NOTEBOOK_PATH.read_text())
+    return "".join(notebook["cells"][cell_index]["source"])
+
+
+def _real_test_config() -> AppServerConfig:
+    codex_bin = os.environ.get("CODEX_PYTHON_SDK_CODEX_BIN") or shutil.which("codex")
+    if codex_bin is None:
+        raise RuntimeError(
+            "Real SDK integration tests require a Codex CLI binary.\n"
+            "Set RUN_REAL_CODEX_TESTS=1 and CODEX_PYTHON_SDK_CODEX_BIN=/absolute/path/to/codex, "
+            "or ensure `codex` is on PATH."
+        )
+    return AppServerConfig(codex_bin=codex_bin)
+
+
+def test_real_initialize_and_model_list():
+    with Codex(config=_real_test_config()) as codex:
+        metadata = codex.metadata
+        assert isinstance(metadata.user_agent, str) and metadata.user_agent.strip()
+        assert isinstance(metadata.server_name, str) and metadata.server_name.strip()
+        assert isinstance(metadata.server_version, str) and metadata.server_version.strip()
+
+        models = codex.models(include_hidden=True)
+        assert isinstance(models.data, list)
+
+
+def test_real_thread_and_turn_start_smoke():
+    with Codex(config=_real_test_config()) as codex:
+        thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+        result = thread.turn(TextInput("hello")).run()
+
+        assert isinstance(result.thread_id, str) and result.thread_id.strip()
+        assert isinstance(result.turn_id, str) and result.turn_id.strip()
+        assert isinstance(result.items, list)
+        assert result.usage is not None
+        assert result.usage.thread_id == result.thread_id
+        assert result.usage.turn_id == result.turn_id
+
+
+def test_real_async_thread_turn_usage_and_ids_smoke() -> None:
+    async def _run() -> None:
+        async with AsyncCodex(config=_real_test_config()) as codex:
+            thread = await codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+            result = await (await thread.turn(TextInput("say ok"))).run()
+
+            assert isinstance(result.thread_id, str) and result.thread_id.strip()
+            assert isinstance(result.turn_id, str) and result.turn_id.strip()
+            assert isinstance(result.items, list)
+            assert result.usage is not None
+            assert result.usage.thread_id == result.thread_id
+            assert result.usage.turn_id == result.turn_id
+
+    asyncio.run(_run())
+
+
+def test_notebook_bootstrap_resolves_sdk_from_unrelated_cwd() -> None:
+    cell_1_source = _notebook_cell_source(1)
+    env = os.environ.copy()
+    env["CODEX_PYTHON_SDK_DIR"] = str(ROOT)
+
+    with tempfile.TemporaryDirectory() as temp_cwd:
+        result = subprocess.run(
+            [sys.executable, "-c", cell_1_source],
+            cwd=temp_cwd,
+            env=env,
+            text=True,
+            capture_output=True,
+            timeout=60,
+            check=False,
+        )
+
+    assert result.returncode == 0, (
+        f"Notebook bootstrap failed from unrelated cwd.\n"
+        f"STDOUT:\n{result.stdout}\n"
+        f"STDERR:\n{result.stderr}"
+    )
+    assert "SDK source:" in result.stdout
+    assert "codex_app_server" in result.stdout or "sdk/python/src" in result.stdout
+
+
+def test_real_streaming_smoke_turn_completed():
+    with Codex(config=_real_test_config()) as codex:
+        thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+        turn = thread.turn(TextInput("Reply with one short sentence."))
+
+        saw_delta = False
+        saw_completed = False
+        for evt in turn.stream():
+            if evt.method == "item/agentMessage/delta":
+                saw_delta = True
+            if evt.method == "turn/completed":
+                saw_completed = True
+
+        assert saw_completed
+        # Some environments can produce zero deltas for very short output;
+        # this assert keeps the smoke test informative but non-flaky.
+        assert isinstance(saw_delta, bool)
+
+
+def test_real_turn_interrupt_smoke():
+    with Codex(config=_real_test_config()) as codex:
+        thread = codex.thread_start(model="gpt-5", config={"model_reasoning_effort": "high"})
+        turn = thread.turn(TextInput("Count from 1 to 200 with commas."))
+
+        # Best effort: interrupting quickly may race with completion on fast models.
+        _ = turn.interrupt()
+
+        # Confirm the session is still usable after interrupt race.
+        follow_up = thread.turn(TextInput("Say 'ok' only.")).run()
+        assert follow_up.status.value in {"completed", "failed"}
+
+@pytest.mark.parametrize(("folder", "script"), EXAMPLE_CASES)
+def test_real_examples_run_and_assert(folder: str, script: str):
+    result = _run_example(folder, script)
+
+    assert result.returncode == 0, (
+        f"Example failed: {folder}/{script}\n"
+        f"STDOUT:\n{result.stdout}\n"
+        f"STDERR:\n{result.stderr}"
+    )
+
+    out = result.stdout
+
+    # Minimal content assertions so we validate behavior, not just exit code.
+    if folder == "01_quickstart_constructor":
+        assert "Status:" in out and "Text:" in out
+        assert "Server: None None" not in out
+    elif folder == "02_turn_run":
+        assert "thread_id:" in out and "turn_id:" in out and "status:" in out
+        assert "usage: None" not in out
+    elif folder == "03_turn_stream_events":
+        assert "turn/completed" in out
+    elif folder == "04_models_and_metadata":
+        assert "models.count:" in out
+        assert "server_name=None" not in out
+        assert "server_version=None" not in out
+    elif folder == "05_existing_thread":
+        assert "Created thread:" in out
+    elif folder == "06_thread_lifecycle_and_controls":
+        assert "Lifecycle OK:" in out
+    elif folder in {"07_image_and_text", "08_local_image_and_text"}:
+        assert "completed" in out.lower() or "Status:" in out
+    elif folder == "09_async_parity":
+        assert "Thread:" in out and "Turn:" in out
+    elif folder == "10_error_handling_and_retry":
+        assert "Text:" in out
+    elif folder == "11_cli_mini_app":
+        assert "Thread:" in out
+    elif folder == "12_turn_params_kitchen_sink":
+        assert "Status:" in out and "Usage:" in out
+    elif folder == "13_model_select_and_turn_params":
+        assert "selected.model:" in out and "agent.message.params:" in out and "usage.params:" in out
+        assert "usage.params: None" not in out