docs: add PLAN.md outlining subprocess JSON path and PyO3 plan

Author: gersmann

PLAN.md

@@ -0,0 +1,68 @@
+# Plan: Python Interface to Codex
+
+## Goal
+Provide a clean Python interface to Codex suitable for apps and automation, with a quick path today (no native build) and a deeper path later (native bindings) while tracking the upstream protocol.
+
+## Phase 1 — Subprocess + JSON (Implemented)
+- Approach
+  - Invoke the Codex CLI (`codex exec`) with JSON output and parse NDJSON lines.
+  - Validate event payloads using generated Pydantic models derived from the upstream protocol.
+- Components
+  - `codex.api.run_exec(prompt, *, json=False, model=None, full_auto=False, cd=None, ...) -> str`
+    - Adds `--json` when `json=True`.
+  - `codex.protocol.runtime.stream_exec_events(prompt, *, model=None, full_auto=False, cd=None, ...) -> Iterator[Event]`
+    - Spawns `codex exec --json` and yields validated `Event` envelopes (`id: str`, `msg: EventMsg`).
+  - `codex.protocol.types` — Pydantic models (generated) for protocol request/response/event types.
+- Usage
+  - One‑shot: `from codex import run_exec`
+  - Streaming: `from codex.protocol.runtime import stream_exec_events`
+- Pros
+  - No native build or wheel distribution required.
+  - Works anywhere the CLI works; simple integration surface.
+- Cons
+  - Separate process; IPC via stdout/stderr.
+  - Less direct control than embedding codex directly.
+
+## Phase 2 — Native PyO3 Bindings (Optional, Future)
+- Motivation
+  - Single process; lower latency; richer control (interrupt/shutdown, approvals, patch streaming) exposed as Python calls.
+- Scope
+  - Create a Rust crate (e.g., `crates/codex_py`) using `pyo3`.
+  - Depend on upstream `codex-rs` crates via path deps under `codex-proj/codex-rs`.
+  - Expose minimal API initially:
+    - `start_session(config) -> Session`
+    - `Session.send_user_message(text, images=...) -> Iterator[Event]`
+    - `Session.interrupt()` / `Session.shutdown()`
+- Build & Publish
+  - Use `maturin` (or `hatch-maturin`) to build wheels.
+  - GH Actions matrix to build manylinux + macOS + Windows wheels on tags (`v*`).
+- Risks
+  - Cross‑platform wheel complexity.
+  - API surface alignment with evolving upstream.
+
+## Protocol Models — Generation Flow
+- Source of truth: `codex-proj/codex-rs/protocol-ts` (Rust → TypeScript via `ts-rs`).
+- Generation steps (Make target):
+  - `make gen-protocol`
+    - Runs the TS generator to `.generated/ts/`.
+    - Converts TS → Python Pydantic models at `codex/protocol/types.py`.
+- Notes
+  - Generated code forbids extra fields (`model_config = ConfigDict(extra='forbid')`).
+  - Optional TS fields (`| null`) map to Optional fields with default `None`.
+
+## CI & Release
+- CI runs `ruff`, `mypy`, and `pytest` on pushes/PRs.
+- PyPI publish via Trusted Publishing (OIDC) on tags matching `v*`.
+
+## Open Questions / Next Steps
+- Should we emit discriminated unions in Pydantic (e.g., `Field(discriminator="method")`) for simpler parsing of request/notification unions?
+- Add higher‑level convenience API: e.g., `CodexSession` in Python wrapping `stream_exec_events` with callbacks.
+- Windows and shell escaping: ensure prompts and cwd are robust on Windows.
+- Back‑pressure & large outputs: expose an async-friendly variant in the future (if needed).
+
+## Acceptance Criteria
+- Phase 1 usable APIs documented and tested:
+  - `run_exec(..., json=True)` returns JSON mode output.
+  - `stream_exec_events(...)` yields validated `Event` instances for typical flows.
+- Protocol generator (`make gen-protocol`) succeeds and passes lint/mypy.
+- Publishing workflow remains functional after additions.