revert: remove codex/protocol/runtime.py (undo last edit)

Author: gersmann

codex/__init__.py

@@ -4,27 +4,29 @@
 
 Usage:
     from codex import run_exec
-    output = run_exec("explain this codebase to me")
+    events = run_exec("explain this codebase to me")
 """
 
 from .api import (
     CodexClient,
     CodexError,
-    CodexNotFoundError,
-    CodexProcessError,
-    find_binary,
+    CodexNativeError,
+    Conversation,
     run_exec,
 )
+from .config import CodexConfig
+from .event import Event
 
 __all__ = [
     "__version__",
     "CodexError",
-    "CodexNotFoundError",
-    "CodexProcessError",
+    "CodexNativeError",
     "CodexClient",
-    "find_binary",
+    "Conversation",
     "run_exec",
+    "Event",
+    "CodexConfig",
 ]
 
 # Managed by Hatch via pyproject.toml [tool.hatch.version]
-__version__ = "0.1.2"
+__version__ = "0.1.2"

codex/api.py

@@ -1,181 +1,96 @@
 from __future__ import annotations
 
-import os
-import shutil
-import subprocess
 from collections.abc import Iterable, Mapping, Sequence
 from dataclasses import dataclass
+from typing import Iterator
+
+from .config import CodexConfig
+from .event import Event
+from .native import run_exec_collect as native_run_exec_collect
+from .native import start_exec_stream as native_start_exec_stream
 
 
 class CodexError(Exception):
     """Base exception for codex-python."""
 
 
-class CodexNotFoundError(CodexError):
-    """Raised when the 'codex' binary cannot be found or executed."""
+class CodexNativeError(CodexError):
+    """Raised when the native extension is not available or fails."""
 
-    def __init__(self, executable: str = "codex") -> None:
+    def __init__(self) -> None:
         super().__init__(
-            f"Codex CLI not found: '{executable}'.\n"
-            "Install from https://github.com/openai/codex or ensure it is on PATH."
+            "codex_native extension not installed or failed to run. "
+            "Run `make dev-native` or ensure native wheels are installed."
         )
-        self.executable = executable
 
 
 @dataclass(slots=True)
-class CodexProcessError(CodexError):
-    """Raised when the codex process exits with a non‑zero status."""
-
-    returncode: int
-    cmd: Sequence[str]
-    stdout: str
-    stderr: str
-
-    def __str__(self) -> str:  # pragma: no cover - repr is sufficient
-        return (
-            f"Codex process failed with exit code {self.returncode}.\n"
-            f"Command: {' '.join(self.cmd)}\n"
-            f"stderr:\n{self.stderr.strip()}"
-        )
-
+class Conversation:
+    """A stateful conversation with Codex, streaming events natively."""
 
-def find_binary(executable: str = "codex") -> str:
-    """Return the absolute path to the Codex CLI binary or raise if not found."""
-    path = shutil.which(executable)
-    if not path:
-        raise CodexNotFoundError(executable)
-    return path
+    _stream: Iterable[dict]
 
-
-def run_exec(
-    prompt: str,
-    *,
-    model: str | None = None,
-    oss: bool = False,
-    full_auto: bool = False,
-    cd: str | None = None,
-    skip_git_repo_check: bool = False,
-    timeout: float | None = None,
-    env: Mapping[str, str] | None = None,
-    executable: str = "codex",
-    extra_args: Iterable[str] | None = None,
-    json: bool = False,
-) -> str:
-    """
-    Run `codex exec` with the given prompt and return stdout as text.
-
-    - Raises CodexNotFoundError if the binary is unavailable.
-    - Raises CodexProcessError on non‑zero exit with captured stdout/stderr.
-    """
-    bin_path = find_binary(executable)
-
-    cmd: list[str] = [bin_path]
-
-    if cd:
-        cmd.extend(["--cd", cd])
-    if model:
-        cmd.extend(["-m", model])
-    if oss:
-        cmd.append("--oss")
-    if full_auto:
-        cmd.append("--full-auto")
-    if skip_git_repo_check:
-        cmd.append("--skip-git-repo-check")
-    if extra_args:
-        cmd.extend(list(extra_args))
-
-    cmd.append("exec")
-    if json:
-        cmd.append("--json")
-    cmd.append(prompt)
-
-    completed = subprocess.run(
-        cmd,
-        capture_output=True,
-        text=True,
-        timeout=timeout,
-        env={**os.environ, **(dict(env) if env else {})},
-        check=False,
-    )
-
-    stdout = completed.stdout or ""
-    stderr = completed.stderr or ""
-    if completed.returncode != 0:
-        raise CodexProcessError(
-            returncode=completed.returncode,
-            cmd=tuple(cmd),
-            stdout=stdout,
-            stderr=stderr,
-        )
-    return stdout
+    def __iter__(self) -> Iterator[Event]:
+        """Yield `Event` objects from the native stream."""
+        for item in self._stream:
+            yield Event.model_validate(item)
 
 
 @dataclass(slots=True)
 class CodexClient:
-    """Lightweight, synchronous client for the Codex CLI.
+    """Lightweight, synchronous client for the native Codex core.
 
-    Provides defaults for repeated invocations and convenience helpers.
+    Provides defaults for repeated invocations and conversation management.
     """
 
-    executable: str = "codex"
-    model: str | None = None
-    full_auto: bool = False
-    cd: str | None = None
+    config: CodexConfig | None = None
+    load_default_config: bool = True
     env: Mapping[str, str] | None = None
     extra_args: Sequence[str] | None = None
 
-    def ensure_available(self) -> str:
-        """Return the resolved binary path or raise CodexNotFoundError."""
-        return find_binary(self.executable)
-
-    def run(
+    def start_conversation(
         self,
         prompt: str,
         *,
-        model: str | None = None,
-        oss: bool | None = None,
-        full_auto: bool | None = None,
-        cd: str | None = None,
-        skip_git_repo_check: bool | None = None,
-        timeout: float | None = None,
-        env: Mapping[str, str] | None = None,
-        extra_args: Iterable[str] | None = None,
-    ) -> str:
-        """Execute `codex exec` and return stdout.
-
-        Explicit arguments override the client's defaults.
-        """
-        eff_model = model if model is not None else self.model
-        eff_full_auto = full_auto if full_auto is not None else self.full_auto
-        eff_cd = cd if cd is not None else self.cd
-        eff_oss = bool(oss) if oss is not None else False
-        eff_skip_git = bool(skip_git_repo_check) if skip_git_repo_check is not None else False
-
-        # Merge environment overlays; run_exec will merge with os.environ
-        merged_env: Mapping[str, str] | None
-        if self.env and env:
-            tmp = dict(self.env)
-            tmp.update(env)
-            merged_env = tmp
-        else:
-            merged_env = env or self.env
-
-        # Compose extra args
-        eff_extra: list[str] = []
-        if self.extra_args:
-            eff_extra.extend(self.extra_args)
-        if extra_args:
-            eff_extra.extend(list(extra_args))
-
-        return run_exec(
+        config: CodexConfig | None = None,
+        load_default_config: bool | None = None,
+    ) -> Conversation:
+        """Start a new conversation and return a streaming iterator over events."""
+        eff_config = config if config is not None else self.config
+        eff_load_default_config = (
+            load_default_config
+            if load_default_config is not None
+            else self.load_default_config
+        )
+
+        try:
+            stream = native_start_exec_stream(
+                prompt,
+                config_overrides=eff_config.to_dict() if eff_config else None,
+                load_default_config=eff_load_default_config,
+            )
+            return Conversation(_stream=stream)
+        except RuntimeError as e:
+            raise CodexNativeError() from e
+
+
+def run_exec(
+    prompt: str,
+    *,
+    config: CodexConfig | None = None,
+    load_default_config: bool = True,
+) -> list[Event]:
+    """
+    Run a prompt through the native Codex engine and return a list of events.
+
+    - Raises CodexNativeError if the native extension is unavailable or fails.
+    """
+    try:
+        events = native_run_exec_collect(
             prompt,
-            model=eff_model,
-            oss=eff_oss,
-            full_auto=eff_full_auto,
-            cd=eff_cd,
-            skip_git_repo_check=eff_skip_git,
-            timeout=timeout,
-            env=merged_env,
-            executable=self.executable,
-            extra_args=eff_extra,
+            config_overrides=config.to_dict() if config else None,
+            load_default_config=load_default_config,
         )
+        return [Event.model_validate(e) for e in events]
+    except RuntimeError as e:
+        raise CodexNativeError() from e

codex/config.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+AskForApproval = "Always" | "Never" | "Auto"
+SandboxMode = "None" | "WorkspaceWrite" | "ReadOnly"
+
+
+@dataclass(slots=True)
+class CodexConfig:
+    """Configuration for the Codex client.
+
+    Attributes:
+        model: The model to use for the conversation.
+        model_provider: The provider of the model.
+        approval_policy: The policy for approving tool calls.
+        sandbox_mode: The sandbox mode to use for shell commands.
+        cwd: The working directory to use for the conversation.
+    """
+
+    model: str | None = None
+    model_provider: str | None = None
+    approval_policy: AskForApproval | None = None
+    sandbox_mode: SandboxMode | None = None
+    cwd: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the config to a dictionary, filtering out None values."""
+        return {k: v for k, v in asdict(self).items() if v is not None}

codex/event.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class Event(BaseModel):
+    """Protocol event envelope."""
+
+    id: str
+    msg: dict[str, Any]

codex/native.py

@@ -9,7 +9,10 @@
 
 
 def run_exec_collect(
-    prompt: str, *, model: str | None = None, full_auto: bool = False, cd: str | None = None
+    prompt: str,
+    *,
+    config_overrides: dict[str, Any] | None = None,
+    load_default_config: bool = True,
 ) -> list[dict]:
     """Run Codex natively (in‑process) and return a list of events as dicts.
 
@@ -20,15 +23,18 @@ def run_exec_collect(
         raise RuntimeError(
             "codex_native extension not installed. Run `make dev-native` or build wheels via maturin."
         )
-    return [dict(e) for e in _run_exec_collect(prompt, model, full_auto, cd)]
+    return _run_exec_collect(prompt, config_overrides, load_default_config)
 
 
 def start_exec_stream(
-    prompt: str, *, model: str | None = None, full_auto: bool = False, cd: str | None = None
+    prompt: str,
+    *,
+    config_overrides: dict[str, Any] | None = None,
+    load_default_config: bool = True,
 ) -> Any:
     """Return a native streaming iterator over Codex events (dicts)."""
     if _start_exec_stream is None:
         raise RuntimeError(
             "codex_native extension not installed. Run `make dev-native` or build wheels via maturin."
         )
-    return _start_exec_stream(prompt, model, full_auto, cd)
+    return _start_exec_stream(prompt, config_overrides, load_default_config)