feat(protocol): add JSON event streaming client and Event model; extend run_exec with --json option; docs

Author: gersmann

Makefile

@@ -17,8 +17,8 @@ fmt:
 	uv run --group dev ruff format .
 
 lint:
-	uv run --group dev ruff format --check .
-	uv run --group dev ruff check .
+	uv run --group dev ruff format .
+	uv run --group dev ruff check --fix --unsafe-fixes .
 	uv run --group dev mypy codex
 
 test:

README.md

@@ -30,6 +30,18 @@ Options:
 - Full auto: `run_exec("scaffold a cli", full_auto=True)`
 - Run in another dir: `run_exec("...", cd="/path/to/project")`
 
+Streaming JSON events (no PyO3 required):
+
+```
+from codex.protocol.runtime import stream_exec_events
+
+for event in stream_exec_events("explain this repo", full_auto=True):
+    # event is a dict with shape {"id": str, "msg": {...}}
+    print(event)
+```
+
+The event payload matches the Pydantic models in `codex.protocol.types` (e.g., `EventMsg`).
+
 Using a client with defaults:
 
 ```

codex/api.py

@@ -57,6 +57,7 @@ def run_exec(
     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.
@@ -77,7 +78,10 @@ def run_exec(
     if extra_args:
         cmd.extend(list(extra_args))
 
-    cmd.extend(["exec", prompt])
+    cmd.append("exec")
+    if json:
+        cmd.append("--json")
+    cmd.append(prompt)
 
     completed = subprocess.run(
         cmd,

codex/protocol/runtime.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from collections.abc import Iterator
+
+from pydantic import BaseModel
+
+from .types import EventMsg
+
+
+class Event(BaseModel):
+    """Protocol event envelope emitted by `codex exec --json`."""
+
+    id: str
+    msg: EventMsg
+
+
+def stream_exec_events(
+    prompt: str,
+    *,
+    executable: str = "codex",
+    model: str | None = None,
+    full_auto: bool = False,
+    cd: str | None = None,
+    env: dict[str, str] | None = None,
+) -> Iterator[Event]:
+    """Spawn `codex exec --json` and yield Event objects from NDJSON stdout.
+
+    Non-event lines (config summary, prompt echo) are ignored.
+    """
+    cmd: list[str] = [executable]
+    if cd:
+        cmd += ["--cd", cd]
+    if model:
+        cmd += ["-m", model]
+    if full_auto:
+        cmd.append("--full-auto")
+    cmd += ["exec", "--json", prompt]
+
+    with subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        env={**os.environ, **(env or {})},
+    ) as proc:
+        assert proc.stdout is not None
+        for line in proc.stdout:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            # Filter out non-event helper lines
+            if not isinstance(obj, dict):
+                continue
+            if "id" in obj and "msg" in obj:
+                # Attempt to validate into our Pydantic Event model
+                yield Event.model_validate(obj)
+
+        # Drain stderr for diagnostics if the process failed
+        ret = proc.wait()
+        if ret != 0 and proc.stderr is not None:
+            err = proc.stderr.read()
+            raise RuntimeError(f"codex exec failed with {ret}: {err}")