chore: unify runtime

Author: gersmann

.gitignore

@@ -67,5 +67,4 @@ crates/**/Cargo.lock
 .beads/
 codex/vendor/**
 !codex/vendor/.gitkeep
-/.desloppify/config.json
-/.desloppify/config.json.bak
+/.desloppify

README.md

@@ -4,9 +4,14 @@ Python SDK for Codex with bundled `codex` binaries inside platform wheels.
 
 This package exposes two supported APIs:
 
-- `Codex`: a simple, local, CLI-backed interface built on `codex exec`
+- `Codex`: a simple, local convenience interface backed by a private stdio app-server session
 - `AppServerClient`: a richer app-server client for thread management, streaming events, approvals, and typed protocol access
 
+Canonical import paths:
+
+- use `from codex import ...` for the high-level `Codex` facade
+- use `from codex.app_server import ...` for the raw app-server client and app-server option types
+
 ## Install
 
 ```bash
@@ -19,7 +24,9 @@ pip install codex-python
 
 Use `Codex` when you want the smallest surface area for local automation:
 
-- one process per run
+- one private local app-server session per `Codex` instance
+- stateless `run*()` convenience (fresh internal thread per call)
+- stateful thread workflows when needed via `start_thread()` / `resume_thread()`
 - simple request/response usage
 - optional streaming over the exec event stream
 - structured output via `TurnOptions(output_schema=...)`
@@ -40,18 +47,16 @@ Use `AppServerClient` when you want a deeper integration:
 from codex import Codex
 
 client = Codex()
-thread = client.start_thread()
-
-summary = thread.run_text("Diagnose the failing tests and propose a fix")
+summary = client.run_text("Diagnose the failing tests and propose a fix")
 print(summary)
 ```
 
-More exec-based examples: [docs/exec_api.md](docs/exec_api.md)
+More `Codex` examples: [docs/exec_api.md](docs/exec_api.md)
 
 ## Quickstart: `AppServerClient`
 
 ```python
-from codex import AppServerClient, AppServerClientInfo, AppServerInitializeOptions
+from codex.app_server import AppServerClient, AppServerClientInfo, AppServerInitializeOptions
 
 initialize_options = AppServerInitializeOptions(
     client_info=AppServerClientInfo(
@@ -68,6 +73,7 @@ with AppServerClient.connect_stdio(initialize_options=initialize_options) as cli
 ```
 
 More app-server examples: [docs/app_server.md](docs/app_server.md)
+For websocket transport, install the optional extra: `pip install "codex-python[websocket]"`.
 
 ## Structured output
 
@@ -84,8 +90,7 @@ schema = {
 }
 
 client = Codex()
-thread = client.start_thread()
-payload = thread.run_json("Summarize repository status", TurnOptions(output_schema=schema))
+payload = client.run_json("Summarize repository status", TurnOptions(output_schema=schema))
 print(payload["summary"])
 ```
 
@@ -94,7 +99,7 @@ print(payload["summary"])
 ```python
 from pydantic import BaseModel
 
-from codex import AppServerClient
+from codex.app_server import AppServerClient, AppServerTurnOptions
 
 
 class Summary(BaseModel):
@@ -112,31 +117,35 @@ with AppServerClient.connect_stdio() as client:
 
 `run_model()` uses `Summary` both as the validation model and, by default, as the output schema sent
 to Codex. If you want JSON back without validation, you can also pass the model class directly to
-`outputSchema`, for example `thread.run_json(..., outputSchema=Summary)`.
+`output_schema`, for example `thread.run_json(..., AppServerTurnOptions(output_schema=Summary))`.
 
 ## Streaming
 
-### Exec stream
+### `Codex` stream
 
 ```python
 from codex import Codex
 from codex.protocol import types as protocol
 
 client = Codex()
-thread = client.start_thread()
-
-stream = thread.run("Investigate this bug")
+stream = client.run("Investigate this bug")
 for event in stream:
-    if isinstance(event, protocol.AgentMessageDeltaEventMsg):
-        print(event.delta, end="", flush=True)
+    if isinstance(event, protocol.ItemAgentMessageDeltaNotification):
+        print(event.params.delta, end="", flush=True)
 
 print()
 ```
 
+`Codex.run*()` starts a fresh internal thread for each call. Use
+`start_thread()` or `resume_thread()` when you want later runs to share context.
+
+High-level `Codex` helpers raise `ThreadRunError` on failed or interrupted terminal turns and
+preserve the final turn metadata on the exception for debugging and UI handling.
+
 ### App-server stream
 
 ```python
-from codex import AppServerClient
+from codex.app_server import AppServerClient
 from codex.protocol import types as protocol
 
 with AppServerClient.connect_stdio() as client:
@@ -150,12 +159,13 @@ with AppServerClient.connect_stdio() as client:
     print()
 ```
 
-Advanced app-server usage: [docs/app_server_advanced.md](docs/app_server_advanced.md)
+Advanced app-server usage, including typed stable RPC domains such as `client.models` and the raw `client.rpc` fallback: [docs/app_server_advanced.md](docs/app_server_advanced.md)
 
 ## Examples
 
 - [examples/basic_conversation.py](examples/basic_conversation.py): minimal `Codex` flow
 - [examples/app_server_conversation.py](examples/app_server_conversation.py): minimal app-server flow
+- [examples/app_server_websocket_conversation.py](examples/app_server_websocket_conversation.py): minimal websocket app-server flow
 - [examples/app_server_stream_events.py](examples/app_server_stream_events.py): protocol-native app-server streaming
 - [examples/app_server_tool_handler.py](examples/app_server_tool_handler.py): typed app-server request handling
 
@@ -171,7 +181,7 @@ If the bundled binary is not present, for example in a source checkout, the SDK
 You can override the executable path with:
 
 - `CodexOptions(codex_path_override=...)`
-- `AppServerProcessOptions(codex_path_override=...)`
+- `codex.app_server.AppServerProcessOptions(codex_path_override=...)`
 
 ## Development
 

codex/__init__.py

@@ -1,78 +1,31 @@
 """Python SDK for embedding Codex via the bundled CLI binary."""
 
-from codex.app_server import (
-    AppServerClient,
-    AppServerClientInfo,
-    AppServerClosedError,
-    AppServerConnectionError,
-    AppServerError,
-    AppServerInitializeOptions,
-    AppServerProcessOptions,
-    AppServerProtocolError,
-    AppServerRpcError,
-    AppServerThread,
-    AsyncAppServerClient,
-    AsyncAppServerThread,
-    AsyncRpcClient,
-    AsyncTurnStream,
-    GenericNotification,
-    GenericServerRequest,
-    RpcClient,
-    TurnStream,
-)
+from __future__ import annotations
+
 from codex.codex import Codex
 from codex.errors import CodexError, CodexExecError, CodexParseError, ThreadRunError
 from codex.options import (
-    ApprovalMode,
     CancelSignal,
     CodexConfigObject,
     CodexConfigValue,
     CodexOptions,
-    ModelReasoningEffort,
-    SandboxMode,
-    ThreadOptions,
+    ThreadResumeOptions,
+    ThreadStartOptions,
     TurnOptions,
-    WebSearchMode,
 )
-from codex.thread import ExecTurnStream, Input, Thread, UserInput
 
 __version__ = "1.0.1"
 
 __all__ = [
     "Codex",
-    "AppServerClient",
-    "AppServerThread",
-    "AsyncAppServerClient",
-    "AsyncAppServerThread",
-    "RpcClient",
-    "AsyncRpcClient",
-    "TurnStream",
-    "AsyncTurnStream",
-    "AppServerError",
-    "AppServerConnectionError",
-    "AppServerClosedError",
-    "AppServerProtocolError",
-    "AppServerRpcError",
-    "GenericNotification",
-    "GenericServerRequest",
-    "AppServerClientInfo",
-    "AppServerInitializeOptions",
-    "AppServerProcessOptions",
     "CodexError",
     "CodexExecError",
     "CodexParseError",
     "ThreadRunError",
-    "Thread",
-    "ExecTurnStream",
-    "Input",
-    "UserInput",
     "CodexOptions",
-    "ThreadOptions",
+    "ThreadStartOptions",
+    "ThreadResumeOptions",
     "TurnOptions",
-    "ApprovalMode",
-    "SandboxMode",
-    "ModelReasoningEffort",
-    "WebSearchMode",
     "CodexConfigValue",
     "CodexConfigObject",
     "CancelSignal",

codex/_binary.py

@@ -6,6 +6,10 @@
 from codex.errors import CodexExecError
 
 
+class BundledCodexNotFoundError(CodexExecError):
+    """The platform wheel does not contain a bundled Codex binary."""
+
+
 def resolve_target_triple(system_name: str | None = None, machine_name: str | None = None) -> str:
     system = (system_name or platform.system()).lower()
     machine = (machine_name or platform.machine()).lower()
@@ -35,7 +39,7 @@ def bundled_codex_path(target_triple: str | None = None) -> Path:
     binary_name = "codex.exe" if "windows" in triple else "codex"
     binary_path = package_root / "vendor" / triple / "codex" / binary_name
     if not binary_path.exists():
-        raise CodexExecError(
+        raise BundledCodexNotFoundError(
             "Bundled codex binary not found at "
             f"{binary_path}. Install a platform wheel or provide codex_path_override."
         )

codex/_config_types.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+type CodexConfigValue = (
+    str | int | float | bool | list["CodexConfigValue"] | dict[str, "CodexConfigValue"]
+)
+type CodexConfigObject = dict[str, CodexConfigValue]

codex/_file_utils.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, text: str, *, encoding: str = "utf-8") -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_path_str = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temp_path = Path(temp_path_str)
+    try:
+        with os.fdopen(fd, "w", encoding=encoding) as handle:
+            handle.write(text)
+        temp_path.replace(path)
+    except Exception:
+        temp_path.unlink(missing_ok=True)
+        raise