[5/8] Rename Python SDK package to openai-codex (#21905)

## Why

The SDK should publish under the reserved public distribution name
`openai-codex`, and its import module should match that name in the
Python style. Since package names can contain hyphens but import modules
cannot, the public import path becomes `openai_codex`.

Keeping the rename separate from the public API surface change makes the
naming change easy to review and avoids mixing it with API curation.

## What

- Rename the SDK distribution from `openai-codex-app-server-sdk` to
`openai-codex`.
- Rename the import package from `codex_app_server` to `openai_codex`.
- Keep the runtime wheel as the separate `openai-codex-cli-bin`
dependency.
- Update docs, examples, notebooks, artifact scripts, lockfile metadata,
and tests for the new distribution/module names.

## Stack

1. #21891 `[1/8]` Pin Python SDK runtime dependency
2. #21893 `[2/8]` Generate Python SDK types from pinned runtime
3. #21895 `[3/8]` Run Python SDK tests in CI
4. #21896 `[4/8]` Define Python SDK public API surface
5. This PR `[5/8]` Rename Python SDK package to `openai-codex`
6. #21910 `[6/8]` Add high-level Python SDK approval mode
7. #22014 `[7/8]` Add Python SDK app-server integration harness
8. #22021 `[8/8]` Add Python SDK Ruff formatting

## Verification

- Updated package metadata and public API tests to assert the
distribution and import names.

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

sdk/python/src/openai_codex/__init__.py

@@ -0,0 +1,65 @@
+from .client import AppServerConfig
+from .errors import (
+    AppServerError,
+    AppServerRpcError,
+    InternalRpcError,
+    InvalidParamsError,
+    InvalidRequestError,
+    JsonRpcError,
+    MethodNotFoundError,
+    ParseError,
+    RetryLimitExceededError,
+    ServerBusyError,
+    TransportClosedError,
+    is_retryable_error,
+)
+from .api import (
+    AsyncCodex,
+    AsyncThread,
+    AsyncTurnHandle,
+    Codex,
+    ImageInput,
+    Input,
+    InputItem,
+    LocalImageInput,
+    MentionInput,
+    RunResult,
+    SkillInput,
+    TextInput,
+    Thread,
+    TurnHandle,
+)
+from .retry import retry_on_overload
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    "AppServerConfig",
+    "Codex",
+    "AsyncCodex",
+    "Thread",
+    "AsyncThread",
+    "TurnHandle",
+    "AsyncTurnHandle",
+    "RunResult",
+    "Input",
+    "InputItem",
+    "TextInput",
+    "ImageInput",
+    "LocalImageInput",
+    "SkillInput",
+    "MentionInput",
+    "retry_on_overload",
+    "AppServerError",
+    "TransportClosedError",
+    "JsonRpcError",
+    "AppServerRpcError",
+    "ParseError",
+    "InvalidRequestError",
+    "MethodNotFoundError",
+    "InvalidParamsError",
+    "InternalRpcError",
+    "ServerBusyError",
+    "RetryLimitExceededError",
+    "is_retryable_error",
+]

sdk/python/src/openai_codex/_inputs.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .models import JsonObject
+
+
+@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
+RunInput = Input | 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 _normalize_run_input(input: RunInput) -> Input:
+    if isinstance(input, str):
+        return TextInput(input)
+    return input

sdk/python/src/openai_codex/_message_router.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import queue
+import threading
+from collections import deque
+
+from .errors import AppServerError, map_jsonrpc_error
+from .generated.notification_registry import notification_turn_id
+from .models import JsonValue, Notification, UnknownNotification
+
+ResponseQueueItem = JsonValue | BaseException
+NotificationQueueItem = Notification | BaseException
+
+
+class MessageRouter:
+    """Route reader-thread messages to the SDK operation waiting for them.
+
+    The app-server stdio transport is a single ordered stream, so only the
+    reader thread should consume stdout. This router keeps the rest of the SDK
+    from competing for that stream by giving each in-flight JSON-RPC request
+    and active turn stream its own queue.
+    """
+
+    def __init__(self) -> None:
+        """Create empty response, turn, and global notification queues."""
+        self._lock = threading.Lock()
+        self._response_waiters: dict[str, queue.Queue[ResponseQueueItem]] = {}
+        self._turn_notifications: dict[str, queue.Queue[NotificationQueueItem]] = {}
+        self._pending_turn_notifications: dict[str, deque[Notification]] = {}
+        self._global_notifications: queue.Queue[NotificationQueueItem] = queue.Queue()
+
+    def create_response_waiter(self, request_id: str) -> queue.Queue[ResponseQueueItem]:
+        """Register a one-shot queue for a JSON-RPC response id."""
+
+        waiter: queue.Queue[ResponseQueueItem] = queue.Queue(maxsize=1)
+        with self._lock:
+            self._response_waiters[request_id] = waiter
+        return waiter
+
+    def discard_response_waiter(self, request_id: str) -> None:
+        """Remove a response waiter when the request could not be written."""
+
+        with self._lock:
+            self._response_waiters.pop(request_id, None)
+
+    def next_global_notification(self) -> Notification:
+        """Block until the next notification that is not scoped to a turn."""
+
+        item = self._global_notifications.get()
+        if isinstance(item, BaseException):
+            raise item
+        return item
+
+    def register_turn(self, turn_id: str) -> None:
+        """Register a queue for a turn stream and replay early events."""
+
+        turn_queue: queue.Queue[NotificationQueueItem] = queue.Queue()
+        with self._lock:
+            if turn_id in self._turn_notifications:
+                return
+            # A turn can emit events immediately after turn/start, before the
+            # caller receives the TurnHandle and starts streaming.
+            pending = self._pending_turn_notifications.pop(turn_id, deque())
+            self._turn_notifications[turn_id] = turn_queue
+        for notification in pending:
+            turn_queue.put(notification)
+
+    def unregister_turn(self, turn_id: str) -> None:
+        """Stop routing future turn events to the stream queue."""
+
+        with self._lock:
+            self._turn_notifications.pop(turn_id, None)
+
+    def next_turn_notification(self, turn_id: str) -> Notification:
+        """Block until the next notification for a registered turn."""
+
+        with self._lock:
+            turn_queue = self._turn_notifications.get(turn_id)
+        if turn_queue is None:
+            raise RuntimeError(f"turn {turn_id!r} is not registered for streaming")
+        item = turn_queue.get()
+        if isinstance(item, BaseException):
+            raise item
+        return item
+
+    def route_response(self, msg: dict[str, JsonValue]) -> None:
+        """Deliver a JSON-RPC response or error to its request waiter."""
+
+        request_id = msg.get("id")
+        with self._lock:
+            waiter = self._response_waiters.pop(str(request_id), None)
+        if waiter is None:
+            return
+
+        if "error" in msg:
+            err = msg["error"]
+            if isinstance(err, dict):
+                waiter.put(
+                    map_jsonrpc_error(
+                        int(err.get("code", -32000)),
+                        str(err.get("message", "unknown")),
+                        err.get("data"),
+                    )
+                )
+            else:
+                waiter.put(AppServerError("Malformed JSON-RPC error response"))
+            return
+
+        waiter.put(msg.get("result"))
+
+    def route_notification(self, notification: Notification) -> None:
+        """Deliver a notification to a turn queue or the global queue."""
+
+        turn_id = self._notification_turn_id(notification)
+        if turn_id is None:
+            self._global_notifications.put(notification)
+            return
+
+        with self._lock:
+            turn_queue = self._turn_notifications.get(turn_id)
+            if turn_queue is None:
+                if notification.method == "turn/completed":
+                    self._pending_turn_notifications.pop(turn_id, None)
+                    return
+                self._pending_turn_notifications.setdefault(turn_id, deque()).append(
+                    notification
+                )
+                return
+        turn_queue.put(notification)
+
+    def fail_all(self, exc: BaseException) -> None:
+        """Wake every blocked waiter when the reader thread exits."""
+
+        with self._lock:
+            response_waiters = list(self._response_waiters.values())
+            self._response_waiters.clear()
+            turn_queues = list(self._turn_notifications.values())
+            self._pending_turn_notifications.clear()
+        # Put the same transport failure into every queue so no SDK call blocks
+        # forever waiting for a response that cannot arrive.
+        for waiter in response_waiters:
+            waiter.put(exc)
+        for turn_queue in turn_queues:
+            turn_queue.put(exc)
+        self._global_notifications.put(exc)
+
+    def _notification_turn_id(self, notification: Notification) -> str | None:
+        """Extract routing ids from known generated payloads or raw unknown payloads."""
+        payload = notification.payload
+        if isinstance(payload, UnknownNotification):
+            raw_turn_id = payload.params.get("turnId")
+            if isinstance(raw_turn_id, str):
+                return raw_turn_id
+            raw_turn = payload.params.get("turn")
+            if isinstance(raw_turn, dict):
+                raw_nested_turn_id = raw_turn.get("id")
+                if isinstance(raw_nested_turn_id, str):
+                    return raw_nested_turn_id
+            return None
+        return notification_turn_id(payload)

sdk/python/src/openai_codex/_run.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import AsyncIterator, Iterator
+
+from .generated.v2_all import (
+    AgentMessageThreadItem,
+    ItemCompletedNotification,
+    MessagePhase,
+    ThreadItem,
+    ThreadTokenUsage,
+    ThreadTokenUsageUpdatedNotification,
+    Turn as AppServerTurn,
+    TurnCompletedNotification,
+    TurnStatus,
+)
+from .models import Notification
+
+
+@dataclass(slots=True)
+class RunResult:
+    final_response: str | None
+    items: list[ThreadItem]
+    usage: ThreadTokenUsage | None
+
+
+def _agent_message_item_from_thread_item(
+    item: ThreadItem,
+) -> AgentMessageThreadItem | None:
+    thread_item = item.root if hasattr(item, "root") else item
+    if isinstance(thread_item, AgentMessageThreadItem):
+        return thread_item
+    return None
+
+
+def _final_assistant_response_from_items(items: list[ThreadItem]) -> str | None:
+    last_unknown_phase_response: str | None = None
+
+    for item in reversed(items):
+        agent_message = _agent_message_item_from_thread_item(item)
+        if agent_message is None:
+            continue
+        if agent_message.phase == MessagePhase.final_answer:
+            return agent_message.text
+        if agent_message.phase is None and last_unknown_phase_response is None:
+            last_unknown_phase_response = agent_message.text
+
+    return last_unknown_phase_response
+
+
+def _raise_for_failed_turn(turn: AppServerTurn) -> None:
+    if turn.status != TurnStatus.failed:
+        return
+    if turn.error is not None and turn.error.message:
+        raise RuntimeError(turn.error.message)
+    raise RuntimeError(f"turn failed with status {turn.status.value}")
+
+
+def _collect_run_result(stream: Iterator[Notification], *, turn_id: str) -> RunResult:
+    completed: TurnCompletedNotification | None = None
+    items: list[ThreadItem] = []
+    usage: ThreadTokenUsage | None = None
+
+    for event in stream:
+        payload = event.payload
+        if isinstance(payload, ItemCompletedNotification) and payload.turn_id == turn_id:
+            items.append(payload.item)
+            continue
+        if isinstance(payload, ThreadTokenUsageUpdatedNotification) and payload.turn_id == turn_id:
+            usage = payload.token_usage
+            continue
+        if isinstance(payload, TurnCompletedNotification) and payload.turn.id == turn_id:
+            completed = payload
+
+    if completed is None:
+        raise RuntimeError("turn completed event not received")
+
+    _raise_for_failed_turn(completed.turn)
+    return RunResult(
+        final_response=_final_assistant_response_from_items(items),
+        items=items,
+        usage=usage,
+    )
+
+
+async def _collect_async_run_result(
+    stream: AsyncIterator[Notification], *, turn_id: str
+) -> RunResult:
+    completed: TurnCompletedNotification | None = None
+    items: list[ThreadItem] = []
+    usage: ThreadTokenUsage | None = None
+
+    async for event in stream:
+        payload = event.payload
+        if isinstance(payload, ItemCompletedNotification) and payload.turn_id == turn_id:
+            items.append(payload.item)
+            continue
+        if isinstance(payload, ThreadTokenUsageUpdatedNotification) and payload.turn_id == turn_id:
+            usage = payload.token_usage
+            continue
+        if isinstance(payload, TurnCompletedNotification) and payload.turn.id == turn_id:
+            completed = payload
+
+    if completed is None:
+        raise RuntimeError("turn completed event not received")
+
+    _raise_for_failed_turn(completed.turn)
+    return RunResult(
+        final_response=_final_assistant_response_from_items(items),
+        items=items,
+        usage=usage,
+    )

sdk/python/src/openai_codex/_version.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import re
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as distribution_version
+from pathlib import Path
+
+DISTRIBUTION_NAME = "openai-codex"
+UNKNOWN_VERSION = "0+unknown"
+
+
+def package_version() -> str:
+    source_version = _source_tree_project_version()
+    if source_version is not None:
+        return source_version
+
+    try:
+        return distribution_version(DISTRIBUTION_NAME)
+    except PackageNotFoundError:
+        return UNKNOWN_VERSION
+
+
+def _source_tree_project_version() -> str | None:
+    pyproject_path = Path(__file__).resolve().parents[2] / "pyproject.toml"
+    if not pyproject_path.exists():
+        return None
+
+    match = re.search(
+        r'(?m)^version = "([^"]+)"$',
+        pyproject_path.read_text(encoding="utf-8"),
+    )
+    if match is None:
+        return None
+    return match.group(1)
+
+
+__version__ = package_version()

sdk/python/src/openai_codex/api.py

@@ -0,0 +1,774 @@
+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 (
+    ApprovalsReviewer,
+    AskForApproval,
+    ModelListResponse,
+    Personality,
+    ReasoningEffort,
+    ReasoningSummary,
+    SandboxMode,
+    SandboxPolicy,
+    SortDirection,
+    ThreadArchiveResponse,
+    ThreadCompactStartResponse,
+    ThreadForkParams,
+    ThreadListCwdFilter,
+    ThreadListParams,
+    ThreadListResponse,
+    ThreadReadResponse,
+    ThreadResumeParams,
+    ThreadSetNameResponse,
+    ThreadSortKey,
+    ThreadSource,
+    ThreadSourceKind,
+    ThreadStartSource,
+    ThreadStartParams,
+    Turn as AppServerTurn,
+    TurnCompletedNotification,
+    TurnInterruptResponse,
+    TurnStartParams,
+    TurnSteerResponse,
+)
+from .models import InitializeResponse, JsonObject, Notification, ServerInfo
+from ._inputs import (
+    ImageInput as ImageInput,
+    Input,
+    InputItem as InputItem,
+    LocalImageInput as LocalImageInput,
+    MentionInput as MentionInput,
+    RunInput,
+    SkillInput as SkillInput,
+    TextInput as TextInput,
+    _normalize_run_input,
+    _to_wire_input,
+)
+from ._run import (
+    RunResult,
+    _collect_async_run_result,
+    _collect_run_result,
+)
+
+
+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
+
+
+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._validate_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 _validate_initialize(payload: InitializeResponse) -> InitializeResponse:
+        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})"
+            )
+
+        if server is None:
+            payload.serverInfo = ServerInfo(
+                name=normalized_server_name,
+                version=normalized_server_version,
+            )
+        else:
+            server.name = normalized_server_name
+            server.version = normalized_server_version
+
+        return payload
+
+    @property
+    def metadata(self) -> InitializeResponse:
+        return self._init
+
+    def close(self) -> None:
+        self._client.close()
+
+    # BEGIN GENERATED: Codex.flat_methods
+    def thread_start(
+        self,
+        *,
+        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | 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: str | None = None,
+        session_start_source: ThreadStartSource | None = None,
+        thread_source: ThreadSource | None = None,
+    ) -> Thread:
+        params = ThreadStartParams(
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            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,
+            session_start_source=session_start_source,
+            thread_source=thread_source,
+        )
+        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: ThreadListCwdFilter | None = None,
+        limit: int | None = None,
+        model_providers: list[str] | None = None,
+        search_term: str | None = None,
+        sort_direction: SortDirection | None = None,
+        sort_key: ThreadSortKey | None = None,
+        source_kinds: list[ThreadSourceKind] | None = None,
+        use_state_db_only: bool | None = None,
+    ) -> ThreadListResponse:
+        params = ThreadListParams(
+            archived=archived,
+            cursor=cursor,
+            cwd=cwd,
+            limit=limit,
+            model_providers=model_providers,
+            search_term=search_term,
+            sort_direction=sort_direction,
+            sort_key=sort_key,
+            source_kinds=source_kinds,
+            use_state_db_only=use_state_db_only,
+        )
+        return self._client.thread_list(params)
+
+    def thread_resume(
+        self,
+        thread_id: str,
+        *,
+        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | 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: str | None = None,
+    ) -> Thread:
+        params = ThreadResumeParams(
+            thread_id=thread_id,
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            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,
+        approvals_reviewer: ApprovalsReviewer | 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: str | None = None,
+        thread_source: ThreadSource | None = None,
+    ) -> Thread:
+        params = ThreadForkParams(
+            thread_id=thread_id,
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            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,
+            thread_source=thread_source,
+        )
+        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`.
+
+    Prefer ``async with AsyncCodex()`` so initialization and shutdown are
+    explicit and paired. The async client initializes lazily on context entry
+    or first awaited API use.
+    """
+
+    def __init__(self, config: AppServerConfig | None = None) -> None:
+        self._client = AsyncAppServerClient(config=config)
+        self._init: InitializeResponse | 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._validate_initialize(payload)
+                self._initialized = True
+            except Exception:
+                await self._client.close()
+                self._init = None
+                self._initialized = False
+                raise
+
+    @property
+    def metadata(self) -> InitializeResponse:
+        if self._init is None:
+            raise RuntimeError(
+                "AsyncCodex is not initialized yet. Prefer `async with AsyncCodex()`; "
+                "initialization also happens on first awaited API use."
+            )
+        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,
+        approvals_reviewer: ApprovalsReviewer | 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: str | None = None,
+        session_start_source: ThreadStartSource | None = None,
+        thread_source: ThreadSource | None = None,
+    ) -> AsyncThread:
+        await self._ensure_initialized()
+        params = ThreadStartParams(
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            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,
+            session_start_source=session_start_source,
+            thread_source=thread_source,
+        )
+        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: ThreadListCwdFilter | None = None,
+        limit: int | None = None,
+        model_providers: list[str] | None = None,
+        search_term: str | None = None,
+        sort_direction: SortDirection | None = None,
+        sort_key: ThreadSortKey | None = None,
+        source_kinds: list[ThreadSourceKind] | None = None,
+        use_state_db_only: bool | 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_direction=sort_direction,
+            sort_key=sort_key,
+            source_kinds=source_kinds,
+            use_state_db_only=use_state_db_only,
+        )
+        return await self._client.thread_list(params)
+
+    async def thread_resume(
+        self,
+        thread_id: str,
+        *,
+        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | 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: str | None = None,
+    ) -> AsyncThread:
+        await self._ensure_initialized()
+        params = ThreadResumeParams(
+            thread_id=thread_id,
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            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,
+        approvals_reviewer: ApprovalsReviewer | 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: str | None = None,
+        thread_source: ThreadSource | None = None,
+    ) -> AsyncThread:
+        await self._ensure_initialized()
+        params = ThreadForkParams(
+            thread_id=thread_id,
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            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,
+            thread_source=thread_source,
+        )
+        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
+
+    def run(
+        self,
+        input: RunInput,
+        *,
+        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | 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: str | None = None,
+        summary: ReasoningSummary | None = None,
+    ) -> RunResult:
+        turn = self.turn(
+            _normalize_run_input(input),
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            cwd=cwd,
+            effort=effort,
+            model=model,
+            output_schema=output_schema,
+            personality=personality,
+            sandbox_policy=sandbox_policy,
+            service_tier=service_tier,
+            summary=summary,
+        )
+        stream = turn.stream()
+        try:
+            return _collect_run_result(stream, turn_id=turn.id)
+        finally:
+            stream.close()
+
+    # BEGIN GENERATED: Thread.flat_methods
+    def turn(
+        self,
+        input: Input,
+        *,
+        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | 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: str | None = None,
+        summary: ReasoningSummary | None = None,
+    ) -> TurnHandle:
+        wire_input = _to_wire_input(input)
+        params = TurnStartParams(
+            thread_id=self.id,
+            input=wire_input,
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            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 TurnHandle(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
+
+    async def run(
+        self,
+        input: RunInput,
+        *,
+        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | 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: str | None = None,
+        summary: ReasoningSummary | None = None,
+    ) -> RunResult:
+        turn = await self.turn(
+            _normalize_run_input(input),
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            cwd=cwd,
+            effort=effort,
+            model=model,
+            output_schema=output_schema,
+            personality=personality,
+            sandbox_policy=sandbox_policy,
+            service_tier=service_tier,
+            summary=summary,
+        )
+        stream = turn.stream()
+        try:
+            return await _collect_async_run_result(stream, turn_id=turn.id)
+        finally:
+            await stream.aclose()
+
+    # BEGIN GENERATED: AsyncThread.flat_methods
+    async def turn(
+        self,
+        input: Input,
+        *,
+        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | 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: str | None = None,
+        summary: ReasoningSummary | None = None,
+    ) -> AsyncTurnHandle:
+        await self._codex._ensure_initialized()
+        wire_input = _to_wire_input(input)
+        params = TurnStartParams(
+            thread_id=self.id,
+            input=wire_input,
+            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
+            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 AsyncTurnHandle(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 TurnHandle:
+    _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]:
+        """Yield only notifications routed to this turn handle."""
+        self._client.register_turn_notifications(self.id)
+        try:
+            while True:
+                event = self._client.next_turn_notification(self.id)
+                yield event
+                if (
+                    event.method == "turn/completed"
+                    and isinstance(event.payload, TurnCompletedNotification)
+                    and event.payload.turn.id == self.id
+                ):
+                    break
+        finally:
+            self._client.unregister_turn_notifications(self.id)
+
+    def run(self) -> AppServerTurn:
+        completed: TurnCompletedNotification | None = None
+        stream = self.stream()
+        try:
+            for event in stream:
+                payload = event.payload
+                if (
+                    isinstance(payload, TurnCompletedNotification)
+                    and payload.turn.id == self.id
+                ):
+                    completed = payload
+        finally:
+            stream.close()
+
+        if completed is None:
+            raise RuntimeError("turn completed event not received")
+        return completed.turn
+
+
+@dataclass(slots=True)
+class AsyncTurnHandle:
+    _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]:
+        """Yield only notifications routed to this async turn handle."""
+        await self._codex._ensure_initialized()
+        self._codex._client.register_turn_notifications(self.id)
+        try:
+            while True:
+                event = await self._codex._client.next_turn_notification(self.id)
+                yield event
+                if (
+                    event.method == "turn/completed"
+                    and isinstance(event.payload, TurnCompletedNotification)
+                    and event.payload.turn.id == self.id
+                ):
+                    break
+        finally:
+            self._codex._client.unregister_turn_notifications(self.id)
+
+    async def run(self) -> AppServerTurn:
+        completed: TurnCompletedNotification | None = None
+        stream = self.stream()
+        try:
+            async for event in stream:
+                payload = event.payload
+                if (
+                    isinstance(payload, TurnCompletedNotification)
+                    and payload.turn.id == self.id
+                ):
+                    completed = payload
+        finally:
+            await stream.aclose()
+
+        if completed is None:
+            raise RuntimeError("turn completed event not received")
+        return completed.turn

sdk/python/src/openai_codex/async_client.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterator
+from typing import AsyncIterator, Callable, 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:
+        """Create the wrapped sync client that owns the transport process."""
+        self._sync = AppServerClient(config=config)
+
+    async def __aenter__(self) -> "AsyncAppServerClient":
+        """Start the app-server process when entering an async context."""
+        await self.start()
+        return self
+
+    async def __aexit__(self, _exc_type, _exc, _tb) -> None:
+        """Close the app-server process when leaving an async context."""
+        await self.close()
+
+    async def _call_sync(
+        self,
+        fn: Callable[ParamsT, ReturnT],
+        /,
+        *args: ParamsT.args,
+        **kwargs: ParamsT.kwargs,
+    ) -> ReturnT:
+        """Run a blocking sync-client operation without blocking the event loop."""
+        return await asyncio.to_thread(fn, *args, **kwargs)
+
+    @staticmethod
+    def _next_from_iterator(
+        iterator: Iterator[AgentMessageDeltaNotification],
+    ) -> tuple[bool, AgentMessageDeltaNotification | None]:
+        """Convert StopIteration into a value that can cross asyncio.to_thread."""
+        try:
+            return True, next(iterator)
+        except StopIteration:
+            return False, None
+
+    async def start(self) -> None:
+        """Start the wrapped sync client in a worker thread."""
+        await self._call_sync(self._sync.start)
+
+    async def close(self) -> None:
+        """Close the wrapped sync client in a worker thread."""
+        await self._call_sync(self._sync.close)
+
+    async def initialize(self) -> InitializeResponse:
+        """Initialize the app-server session."""
+        return await self._call_sync(self._sync.initialize)
+
+    def register_turn_notifications(self, turn_id: str) -> None:
+        """Register a turn notification queue on the wrapped sync client."""
+        self._sync.register_turn_notifications(turn_id)
+
+    def unregister_turn_notifications(self, turn_id: str) -> None:
+        """Unregister a turn notification queue on the wrapped sync client."""
+        self._sync.unregister_turn_notifications(turn_id)
+
+    async def request(
+        self,
+        method: str,
+        params: JsonObject | None,
+        *,
+        response_model: type[ModelT],
+    ) -> ModelT:
+        """Send a typed JSON-RPC request through the wrapped sync client."""
+        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:
+        """Start a thread using the wrapped sync client."""
+        return await self._call_sync(self._sync.thread_start, params)
+
+    async def thread_resume(
+        self,
+        thread_id: str,
+        params: V2ThreadResumeParams | JsonObject | None = None,
+    ) -> ThreadResumeResponse:
+        """Resume a thread using the wrapped sync client."""
+        return await self._call_sync(self._sync.thread_resume, thread_id, params)
+
+    async def thread_list(
+        self, params: V2ThreadListParams | JsonObject | None = None
+    ) -> ThreadListResponse:
+        """List threads using the wrapped sync client."""
+        return await self._call_sync(self._sync.thread_list, params)
+
+    async def thread_read(
+        self, thread_id: str, include_turns: bool = False
+    ) -> ThreadReadResponse:
+        """Read a thread using the wrapped sync client."""
+        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:
+        """Fork a thread using the wrapped sync client."""
+        return await self._call_sync(self._sync.thread_fork, thread_id, params)
+
+    async def thread_archive(self, thread_id: str) -> ThreadArchiveResponse:
+        """Archive a thread using the wrapped sync client."""
+        return await self._call_sync(self._sync.thread_archive, thread_id)
+
+    async def thread_unarchive(self, thread_id: str) -> ThreadUnarchiveResponse:
+        """Unarchive a thread using the wrapped sync client."""
+        return await self._call_sync(self._sync.thread_unarchive, thread_id)
+
+    async def thread_set_name(self, thread_id: str, name: str) -> ThreadSetNameResponse:
+        """Rename a thread using the wrapped sync client."""
+        return await self._call_sync(self._sync.thread_set_name, thread_id, name)
+
+    async def thread_compact(self, thread_id: str) -> ThreadCompactStartResponse:
+        """Start thread compaction using the wrapped sync client."""
+        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:
+        """Start a turn using the wrapped sync client."""
+        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:
+        """Interrupt a turn using the wrapped sync client."""
+        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:
+        """Send steering input to a turn using the wrapped sync client."""
+        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:
+        """List models using the wrapped sync client."""
+        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:
+        """Send a typed request with the sync client's overload retry policy."""
+        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:
+        """Wait for the next global notification without blocking the event loop."""
+        return await self._call_sync(self._sync.next_notification)
+
+    async def next_turn_notification(self, turn_id: str) -> Notification:
+        """Wait for the next notification routed to one turn."""
+        return await self._call_sync(self._sync.next_turn_notification, turn_id)
+
+    async def wait_for_turn_completed(self, turn_id: str) -> TurnCompletedNotification:
+        """Wait for the completion notification routed to one turn."""
+        return await self._call_sync(self._sync.wait_for_turn_completed, turn_id)
+
+    async def stream_text(
+        self,
+        thread_id: str,
+        text: str,
+        params: V2TurnStartParams | JsonObject | None = None,
+    ) -> AsyncIterator[AgentMessageDeltaNotification]:
+        """Stream text deltas from one turn without monopolizing the event loop."""
+        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/openai_codex/client.py

@@ -0,0 +1,579 @@
+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, Iterator, TypeVar
+
+from pydantic import BaseModel
+
+from .errors import AppServerError, TransportClosedError
+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 ._message_router import MessageRouter
+from .retry import retry_on_overload
+from ._version import __version__ as SDK_VERSION
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+ApprovalHandler = Callable[[str, JsonObject | None], JsonObject]
+RUNTIME_PKG_NAME = "openai-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 = SDK_VERSION
+    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._router = MessageRouter()
+        self._stderr_lines: deque[str] = deque(maxlen=400)
+        self._stderr_thread: threading.Thread | None = None
+        self._reader_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,
+            encoding="utf-8",
+            cwd=self.config.cwd,
+            env=env,
+            bufsize=1,
+        )
+
+        self._start_stderr_drain_thread()
+        self._start_reader_thread()
+
+    def close(self) -> None:
+        if self._proc is None:
+            return
+        proc = self._proc
+        self._proc = 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)
+        if self._reader_thread and self._reader_thread.is_alive():
+            self._reader_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:
+        """Send a JSON-RPC request and wait for the reader thread to route its response."""
+        request_id = str(uuid.uuid4())
+        waiter = self._router.create_response_waiter(request_id)
+
+        try:
+            self._write_message(
+                {"id": request_id, "method": method, "params": params or {}}
+            )
+        except BaseException:
+            self._router.discard_response_waiter(request_id)
+            raise
+
+        item = waiter.get()
+        if isinstance(item, BaseException):
+            raise item
+        return item
+
+    def notify(self, method: str, params: JsonObject | None = None) -> None:
+        """Send a JSON-RPC notification without waiting for a response."""
+        self._write_message({"method": method, "params": params or {}})
+
+    def next_notification(self) -> Notification:
+        """Return the next notification that is not scoped to an active turn."""
+        return self._router.next_global_notification()
+
+    def register_turn_notifications(self, turn_id: str) -> None:
+        """Start routing notifications for one turn into its dedicated queue."""
+        self._router.register_turn(turn_id)
+
+    def unregister_turn_notifications(self, turn_id: str) -> None:
+        """Stop routing notifications for one turn into its dedicated queue."""
+        self._router.unregister_turn(turn_id)
+
+    def next_turn_notification(self, turn_id: str) -> Notification:
+        """Return the next routed notification for the requested turn id."""
+        return self._router.next_turn_notification(turn_id)
+
+    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:
+        """Start a turn and register its notification queue as early as possible."""
+        payload = {
+            **_params_dict(params),
+            "threadId": thread_id,
+            "input": self._normalize_input_items(input_items),
+        }
+        started = self.request("turn/start", payload, response_model=TurnStartResponse)
+        self.register_turn_notifications(started.turn.id)
+        return started
+
+    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:
+        """Block on the routed turn stream until the matching completion arrives."""
+        self.register_turn_notifications(turn_id)
+        try:
+            while True:
+                notification = self.next_turn_notification(turn_id)
+                if (
+                    notification.method == "turn/completed"
+                    and isinstance(notification.payload, TurnCompletedNotification)
+                    and notification.payload.turn.id == turn_id
+                ):
+                    return notification.payload
+        finally:
+            self.unregister_turn_notifications(turn_id)
+
+    def stream_text(
+        self,
+        thread_id: str,
+        text: str,
+        params: V2TurnStartParams | JsonObject | None = None,
+    ) -> Iterator[AgentMessageDeltaNotification]:
+        """Start a text turn and yield only its agent-message delta payloads."""
+        started = self.turn_start(thread_id, text, params=params)
+        turn_id = started.turn.id
+        self.register_turn_notifications(turn_id)
+        try:
+            while True:
+                notification = self.next_turn_notification(turn_id)
+                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
+        finally:
+            self.unregister_turn_notifications(turn_id)
+
+    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:
+        """Accept approval requests when the caller did not provide a handler."""
+        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 _start_reader_thread(self) -> None:
+        """Start the sole stdout reader that fans messages into router queues."""
+        if self._proc is None or self._proc.stdout is None:
+            return
+
+        self._reader_thread = threading.Thread(target=self._reader_loop, daemon=True)
+        self._reader_thread.start()
+
+    def _reader_loop(self) -> None:
+        """Continuously classify transport messages into requests, responses, and events."""
+        try:
+            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:
+                    method = msg["method"]
+                    if isinstance(method, str):
+                        self._router.route_notification(
+                            self._coerce_notification(method, msg.get("params"))
+                        )
+                    continue
+                self._router.route_response(msg)
+        except BaseException as exc:
+            self._router.fail_all(exc)
+
+    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/openai_codex/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/openai_codex/generated/__init__.py

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

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

@@ -0,0 +1,177 @@
+# 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 ExternalAgentConfigImportCompletedNotification
+from .v2_all import FileChangeOutputDeltaNotification
+from .v2_all import FileChangePatchUpdatedNotification
+from .v2_all import FsChangedNotification
+from .v2_all import FuzzyFileSearchSessionCompletedNotification
+from .v2_all import FuzzyFileSearchSessionUpdatedNotification
+from .v2_all import GuardianWarningNotification
+from .v2_all import HookCompletedNotification
+from .v2_all import HookStartedNotification
+from .v2_all import ItemCompletedNotification
+from .v2_all import ItemGuardianApprovalReviewCompletedNotification
+from .v2_all import ItemGuardianApprovalReviewStartedNotification
+from .v2_all import ItemStartedNotification
+from .v2_all import McpServerOauthLoginCompletedNotification
+from .v2_all import McpServerStatusUpdatedNotification
+from .v2_all import McpToolCallProgressNotification
+from .v2_all import ModelReroutedNotification
+from .v2_all import ModelVerificationNotification
+from .v2_all import PlanDeltaNotification
+from .v2_all import ProcessExitedNotification
+from .v2_all import ProcessOutputDeltaNotification
+from .v2_all import ReasoningSummaryPartAddedNotification
+from .v2_all import ReasoningSummaryTextDeltaNotification
+from .v2_all import ReasoningTextDeltaNotification
+from .v2_all import RemoteControlStatusChangedNotification
+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 ThreadGoalClearedNotification
+from .v2_all import ThreadGoalUpdatedNotification
+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 ThreadRealtimeSdpNotification
+from .v2_all import ThreadRealtimeStartedNotification
+from .v2_all import ThreadRealtimeTranscriptDeltaNotification
+from .v2_all import ThreadRealtimeTranscriptDoneNotification
+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 WarningNotification
+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,
+    "externalAgentConfig/import/completed": ExternalAgentConfigImportCompletedNotification,
+    "fs/changed": FsChangedNotification,
+    "fuzzyFileSearch/sessionCompleted": FuzzyFileSearchSessionCompletedNotification,
+    "fuzzyFileSearch/sessionUpdated": FuzzyFileSearchSessionUpdatedNotification,
+    "guardianWarning": GuardianWarningNotification,
+    "hook/completed": HookCompletedNotification,
+    "hook/started": HookStartedNotification,
+    "item/agentMessage/delta": AgentMessageDeltaNotification,
+    "item/autoApprovalReview/completed": ItemGuardianApprovalReviewCompletedNotification,
+    "item/autoApprovalReview/started": ItemGuardianApprovalReviewStartedNotification,
+    "item/commandExecution/outputDelta": CommandExecutionOutputDeltaNotification,
+    "item/commandExecution/terminalInteraction": TerminalInteractionNotification,
+    "item/completed": ItemCompletedNotification,
+    "item/fileChange/outputDelta": FileChangeOutputDeltaNotification,
+    "item/fileChange/patchUpdated": FileChangePatchUpdatedNotification,
+    "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,
+    "mcpServer/startupStatus/updated": McpServerStatusUpdatedNotification,
+    "model/rerouted": ModelReroutedNotification,
+    "model/verification": ModelVerificationNotification,
+    "process/exited": ProcessExitedNotification,
+    "process/outputDelta": ProcessOutputDeltaNotification,
+    "remoteControl/status/changed": RemoteControlStatusChangedNotification,
+    "serverRequest/resolved": ServerRequestResolvedNotification,
+    "skills/changed": SkillsChangedNotification,
+    "thread/archived": ThreadArchivedNotification,
+    "thread/closed": ThreadClosedNotification,
+    "thread/compacted": ContextCompactedNotification,
+    "thread/goal/cleared": ThreadGoalClearedNotification,
+    "thread/goal/updated": ThreadGoalUpdatedNotification,
+    "thread/name/updated": ThreadNameUpdatedNotification,
+    "thread/realtime/closed": ThreadRealtimeClosedNotification,
+    "thread/realtime/error": ThreadRealtimeErrorNotification,
+    "thread/realtime/itemAdded": ThreadRealtimeItemAddedNotification,
+    "thread/realtime/outputAudio/delta": ThreadRealtimeOutputAudioDeltaNotification,
+    "thread/realtime/sdp": ThreadRealtimeSdpNotification,
+    "thread/realtime/started": ThreadRealtimeStartedNotification,
+    "thread/realtime/transcript/delta": ThreadRealtimeTranscriptDeltaNotification,
+    "thread/realtime/transcript/done": ThreadRealtimeTranscriptDoneNotification,
+    "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,
+    "warning": WarningNotification,
+    "windows/worldWritableWarning": WindowsWorldWritableWarningNotification,
+    "windowsSandbox/setupCompleted": WindowsSandboxSetupCompletedNotification,
+}
+
+DIRECT_TURN_ID_NOTIFICATION_TYPES: tuple[type[BaseModel], ...] = (
+    AgentMessageDeltaNotification,
+    CommandExecutionOutputDeltaNotification,
+    ContextCompactedNotification,
+    ErrorNotification,
+    FileChangeOutputDeltaNotification,
+    FileChangePatchUpdatedNotification,
+    HookCompletedNotification,
+    HookStartedNotification,
+    ItemCompletedNotification,
+    ItemGuardianApprovalReviewCompletedNotification,
+    ItemGuardianApprovalReviewStartedNotification,
+    ItemStartedNotification,
+    McpToolCallProgressNotification,
+    ModelReroutedNotification,
+    ModelVerificationNotification,
+    PlanDeltaNotification,
+    ReasoningSummaryPartAddedNotification,
+    ReasoningSummaryTextDeltaNotification,
+    ReasoningTextDeltaNotification,
+    TerminalInteractionNotification,
+    ThreadGoalUpdatedNotification,
+    ThreadTokenUsageUpdatedNotification,
+    TurnDiffUpdatedNotification,
+    TurnPlanUpdatedNotification,
+)
+
+NESTED_TURN_NOTIFICATION_TYPES: tuple[type[BaseModel], ...] = (
+    TurnCompletedNotification,
+    TurnStartedNotification,
+)
+
+
+def notification_turn_id(payload: BaseModel) -> str | None:
+    """Return the turn id carried by generated notification payload metadata."""
+    if isinstance(payload, DIRECT_TURN_ID_NOTIFICATION_TYPES):
+        return payload.turn_id if isinstance(payload.turn_id, str) else None
+    if isinstance(payload, NESTED_TURN_NOTIFICATION_TYPES):
+        return payload.turn.id
+    return None

sdk/python/src/openai_codex/models.py

@@ -0,0 +1,99 @@
+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
+    platformFamily: str | None = None
+    platformOs: str | None = None

sdk/python/src/openai_codex/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/src/openai_codex/types.py

@@ -0,0 +1,69 @@
+"""Public generated app-server model exports for type annotations and matching."""
+
+from __future__ import annotations
+
+from .generated.v2_all import (
+    ApprovalsReviewer,
+    AskForApproval,
+    ModelListResponse,
+    Personality,
+    PlanType,
+    ReasoningEffort,
+    ReasoningSummary,
+    SandboxMode,
+    SandboxPolicy,
+    SortDirection,
+    ThreadArchiveResponse,
+    ThreadCompactStartResponse,
+    ThreadItem,
+    ThreadListCwdFilter,
+    ThreadListResponse,
+    ThreadReadResponse,
+    ThreadSetNameResponse,
+    ThreadSortKey,
+    ThreadSource,
+    ThreadSourceKind,
+    ThreadStartSource,
+    ThreadTokenUsage,
+    ThreadTokenUsageUpdatedNotification,
+    Turn,
+    TurnCompletedNotification,
+    TurnInterruptResponse,
+    TurnStatus,
+    TurnSteerResponse,
+)
+from .models import InitializeResponse, JsonObject, Notification
+
+__all__ = [
+    "ApprovalsReviewer",
+    "AskForApproval",
+    "InitializeResponse",
+    "JsonObject",
+    "ModelListResponse",
+    "Notification",
+    "Personality",
+    "PlanType",
+    "ReasoningEffort",
+    "ReasoningSummary",
+    "SandboxMode",
+    "SandboxPolicy",
+    "SortDirection",
+    "ThreadArchiveResponse",
+    "ThreadCompactStartResponse",
+    "ThreadItem",
+    "ThreadListCwdFilter",
+    "ThreadListResponse",
+    "ThreadReadResponse",
+    "ThreadSetNameResponse",
+    "ThreadSortKey",
+    "ThreadSource",
+    "ThreadSourceKind",
+    "ThreadStartSource",
+    "ThreadTokenUsage",
+    "ThreadTokenUsageUpdatedNotification",
+    "Turn",
+    "TurnCompletedNotification",
+    "TurnInterruptResponse",
+    "TurnStatus",
+    "TurnSteerResponse",
+]