Python Parity Status — 2025-10-17
View SourceOverview
- Reviewed the vendored
codex/repository, including the shared Rust event schema (codex/codex-rs/exec/src/exec_events.rs) and TypeScript SDK (codex/sdk/typescript/src/thread.ts,threadOptions.ts). The Python SDK (openai/codex) is not vendored here, but it drives the same codex-rs protocol and features documented upstream. - Cross-checked the current Elixir implementation (
lib/codex/**/*.ex) and tests to determine which Python capabilities are still missing. Recent work (e.g. attachment TTL registry) is already reflected below. - Goal: enumerate every known Python feature we lack so follow-up tasks can be planned without rediscovery.
Update (2025-12-14)
As of codex_sdk 0.3.0, the SDK supports both exec JSONL (codex exec --experimental-json) and app-server JSON-RPC over stdio (codex app-server). For current parity tracking and protocol mappings, see docs/20251214/multi_transport_refactor/README.md.
Gap Inventory
| Area | Python capability (evidence) | Elixir status (evidence) | Gap & Next Steps |
|---|---|---|---|
| Event & Item Coverage | ThreadEvent covers item.started, item.updated, command executions, file changes, MCP tool calls, web search, todo list, etc. (codex/codex-rs/exec/src/exec_events.rs:1) | ✅ All item variants now deserialize into typed structs via Codex.Items, and the turn pipeline preserves the richer data (lib/codex/items.ex, lib/codex/events.ex, test/codex/events_test.exs:38). | Maintain parity as codex-rs adds new item types (add tests/structs on schema updates). |
| Structured Output | Python/TypeScript write JSON schemas to disk and pass them to the binary (createOutputSchemaFile / outputSchema in codex/sdk/typescript/src/thread.ts:33) | ✅ Schemas are persisted, decoded responses populate Items.AgentMessage.parsed, and helpers expose the parsed payload (lib/codex/thread.ex:360, lib/codex/turn/result.ex:28, test/codex/thread_test.exs:107). | Track edge cases (nested structs, large payloads) and extend helpers once schema builders land. |
| Per-turn Tool Bridging | Python feeds tool outputs/failures back into codex-rs so continuation turns consume them (see tool harness in codex/codex-rs/core/tests/suite/tool_harness.rs) | 🟡 The SDK can buffer tool outputs/failures internally, but neither exec JSONL nor app-server v2 currently exposes a supported external-client mechanism to inject tool results back into the agent loop. | Prefer hosting tools via MCP or wait for an upstream protocol surface that supports tool result injection. Keep exec transport honest and avoid undocumented flags. |
| Thread Options: sandbox, working dir, Git checks | Python exposes sandbox/workdir/git toggles plus per-run model overrides (codex CLI flags and config) | ✅ Thread-level exec options are exposed via Codex.Thread.Options and forwarded to codex exec (sandbox, working_directory, additional_directories, skip_git_repo_check, etc.). | Track upstream CLI flags for drift; app-server uses the v2 thread/turn params instead of CLI flags. |
| MCP Tool Surfacing | Event schema includes McpToolCall items and Rust core differentiates MCP call lifecycles (codex/codex-rs/exec/src/exec_events.rs:60) | Codex.MCP.Client exists but nothing in the turn pipeline inspects MCP-specific items or dispatches to external transports (lib/codex/mcp/client.ex:1, lib/codex/thread.ex:245) | Add item parsing plus orchestration so MCP tool calls flow through approvals/registries just like Python’s MCP support. |
| File Upload APIs | Python client offers staging and upload helpers for the HTTP file endpoints (docs/design/attachments-files.md:24 describes parity goal) | Elixir exposes stage/2, attach/2, TTL cleanup, but no file upload helper to a remote API. | If needed, implement upload helpers against the OpenAI Files API and document how they relate (or don’t) to codex exec (which only supports --image attachments). |
| Temporary Attachment Helpers | Python provides RAII-style helpers for ephemeral files (referenced in design doc docs/design/attachments-files.md:26) | Elixir missing {@literal Codex.Files.temporary/1} or similar API | Implement helper returning disposable attachment structs and cover via unit tests. |
| Structured Logging / Telemetry Parity | Python emits structured logs alongside telemetry (see roadmap docs/20251018/codex-sdk-completion/module-implementation.md:54) | Elixir telemetry exists for threads/tools/approvals/attachments, but logging output hasn’t been aligned with Python formats (lib/codex/telemetry.ex:1) | Add logger helpers / formatting utilities so CLI-integrated apps see the same log payloads Python produces. |
| Binary Lifecycle Mix Tasks | Python packaging bundles the codex binary; parity plan calls for install/verify tasks (docs/20251018/codex-sdk-completion/integration-readiness.md:5) | Only mix codex.verify is wired; no installer/build task yet (mix.exs:12) | Provide mix codex.install (Rust build/download), document usage, and integrate with CI. |
Observations & Open Questions
- Python source is external, so parity tracking relies on codex-rs schemas, TypeScript SDK behavior, and harvested fixtures. Any hidden Python-only helpers (async APIs, context managers) need confirmation once the repo is available locally.
- Event schema evolves quickly; re-check
codex/codex-rson each update so we don’t miss new item types or fields.
Update this status doc whenever we land a missing feature or discover additional Python-only capabilities.