feat(api/native): introduce proper stateful Conversation via native bindings\n\n- Native: add pyclass with iteration and control methods\n (submit_user_turn, submit_review, approve_exec, approve_patch, interrupt,\n shutdown) and constructor. Stores per-turn defaults\n derived from Config and updates them per turn.

- API: restore  and  wrappers over the native handle.
- Keep , , and the convenience  for one-offs.
- Update exports and smoke tests.\n\nBuild & tests:\n- make dev-native\n- make lint && make test (all green).

Author: gersmann

CODE_OF_CONDUCT.md

@@ -31,7 +31,7 @@ If there’s no prebuilt wheel for your platform/Python, pip will build from sou
 Run a prompt and collect structured events (typed):
 
 ```python
-from codex.api import run_exec, CodexClient, CodexNativeError
+from codex import run_exec, CodexClient, CodexNativeError
 from codex.config import CodexConfig, ApprovalPolicy, SandboxMode
 
 cfg = CodexConfig(
@@ -51,26 +51,42 @@ except CodexNativeError as e:
 
 # Conversation (streaming)
 client = CodexClient(config=cfg)
-for ev in client.start_conversation("Add a smoke test"):
-    print(ev.id, ev.msg.type)
+conv = client.start_conversation()
+conv.submit_user_turn("Add a smoke test")
+for ev in conv:
+    print(ev.id, getattr(getattr(ev.msg, "root", ev.msg), "type", "unknown"))
 ```
 
 Notes
 - `Event.msg` is a typed union (`EventMsg`). For raw dicts from the native layer, use `codex.native.start_exec_stream`.
 
 ## 3) API Overview
 
-- `codex.api.run_exec(prompt, config, load_default_config=True) -> list[Event]`
-  Synchronous one‑shot execution; returns all events.
+- `codex.run_exec(prompt, *, config=None, load_default_config=True, output_schema=None) -> list[Event]`
+  Synchronous one‑shot; returns all events.
 
-- `codex.api.CodexClient(config).start_conversation(prompt, load_default_config=None) -> Iterable[Event]`
-  Streaming conversation iterator.
+- `codex.run_review(prompt, *, user_facing_hint=None, config=None, load_default_config=True) -> list[Event]`
+  Synchronous review flow; returns all events.
+
+- `codex.run_prompt(prompt, *, config=None, load_default_config=True, output_schema=None) -> str | Any`
+  Convenience: returns the final assistant message (or parsed JSON when `output_schema` is set).
+
+- `codex.CodexClient(config).start_conversation(... ) -> Conversation`
+  Creates a stateful session. Iterate over `Conversation` to stream events.
+  - `Conversation.submit_user_turn(prompt, *, cwd=None, approval_policy=..., sandbox_mode=..., model=None, effort=..., summary=..., output_schema=None)`
+  - `Conversation.submit_review(prompt, user_facing_hint=None)`
+  - `Conversation.approve_exec(id, decision)` / `approve_patch(id, decision)`
+  - `Conversation.interrupt()`, `Conversation.shutdown()`
+  - Utility: `user_input_text`, `override_turn_context`, `add_to_history`, `get_history_entry`, `get_path`, `list_mcp_tools`, `list_custom_prompts`, `compact`
+
+- `await codex.CodexClient(...).astart_conversation() -> AsyncConversation`
+  Async iterator with the same methods as `Conversation` (async variants).
 
 - Exceptions
-  - `CodexError` base class; `CodexNativeError` wraps native failures and missing extension.
+  - `CodexError` base; `CodexNativeError` wraps native failures / missing extension.
 
-- Native helpers
-  - `codex.native.preview_config(config_overrides, load_default_config)` returns a compact snapshot of the effective configuration (useful in tests).
+- Native helper
+  - `codex.native.preview_config(config_overrides, load_default_config)` → compact effective config snapshot (testing aid).
 
 ## 4) Configuration
 

README.md

@@ -7,15 +7,10 @@
     events = run_exec("explain this codebase to me")
 """
 
-from .api import (
-    CodexClient,
-    CodexError,
-    CodexNativeError,
-    Conversation,
-    run_exec,
-)
+from .client import AsyncConversation, CodexClient, CodexError, CodexNativeError, Conversation
 from .config import CodexConfig
 from .event import Event
+from .exec import run_exec, run_prompt, run_review
 from .protocol.types import EventMsg
 
 __all__ = [
@@ -24,7 +19,10 @@
     "CodexNativeError",
     "CodexClient",
     "Conversation",
+    "AsyncConversation",
+    "run_prompt",
     "run_exec",
+    "run_review",
     "Event",
     "EventMsg",
     "CodexConfig",