codex_sdk

# Python Parity Status — 2025-10-17

## Overview
- 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.

## 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`) | ✅ Pending tool output/failure buffers are forwarded via `--tool-output/--tool-failure` flags and cleared after each attempt (`lib/codex/exec.ex:209`, `lib/codex/thread.ex:403`, `test/codex/thread_test.exs:120`). | Monitor for additional CLI payload formats (streams, attachments) and extend encoding helpers as needed. |
| **Thread Options: sandbox, working dir, Git checks** | Python exposes `sandboxMode`, `workingDirectory`, `skipGitRepoCheck`, and per-thread `model` overrides (`codex/sdk/typescript/src/threadOptions.ts:1`, `thread.ts:41`) | `Codex.Thread.Options` lacks these fields and the current argument builder in `Codex.Exec` never emits corresponding flags (`lib/codex/thread/options.ex:5`, `lib/codex/exec.ex:120`) | Extend `Thread.Options`, validate inputs, and forward `--sandbox-mode`, `--working-directory`, `--skip-git-repo-check`, and per-thread model flags to mirror Python. |
| **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 {@literal Codex.Files.upload/2} or remote propagation (`lib/codex/files.ex:69`) | Implement upload helpers (mirroring Python) and tests against codex CLI `--upload`/`--attach` workflows. |
| **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-rs` on 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.