From 540f88dcba251812e191d4de786b474daf32dba0 Mon Sep 17 00:00:00 2001 From: Owen Lin Date: Tue, 7 Oct 2025 15:48:20 -0700 Subject: [PATCH] oops wrong doc --- codex_app_server_integration_plan.md | 59 ------------------- run_codex_convo_plan.md | 86 ++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+), 59 deletions(-) delete mode 100644 codex_app_server_integration_plan.md create mode 100644 run_codex_convo_plan.md diff --git a/codex_app_server_integration_plan.md b/codex_app_server_integration_plan.md deleted file mode 100644 index 917ebcb6b2..0000000000 --- a/codex_app_server_integration_plan.md +++ /dev/null @@ -1,59 +0,0 @@ -# Codex App-Server Integration Plan (Rust Learning Track) - -## Goals - -- Practice Rust fundamentals through a concrete, asynchronous systems project. -- Understand the Codex JSON-RPC contract (`codex-rs/protocol/src/mcp_protocol.rs` and `protocol/src/protocol.rs`). -- Build confidence with tooling (`tokio`, `serde`, `clap`, `tracing`, `ratatui`). - -## Project Ideas - -1. **Minimal MCP Client** - - Spawn `codex-app-server` with `tokio::process::Command` and manage stdio streams. - - Implement JSON-RPC handshake (`initialize`, `newConversation`). - - Send `addConversationListener` to receive `codex/event/*` notifications. - -2. **Protocol Bindings Crate** - - Re-export the schema types from Codex or mirror them in a new crate. - - Derive `serde` traits and optionally generate TypeScript definitions with `ts_rs`. - - Provide helper builders for common requests. - -3. **Event Reactor** - - Write an async dispatcher that matches notification `method` values. - - Map `params.msg.type` to enums and forward them to handlers. - - Demonstrate logging of plan updates, approvals, and tool call progress. - -4. **CLI Wrapper** - - Build a `clap`-based CLI: `new`, `send`, `interrupt`, `status`. - - Manage Request IDs, handle JSON-RPC errors, serialize inputs with `serde_json`. - - Support piping stdin into user messages. - -5. **Tracing & Diagnostics** - - Instrument the client with `tracing` spans around requests and responses. - - Emit structured logs for event handling and error paths. - - Optionally integrate with `tracing-subscriber` for pretty output or JSON logs. - -6. **TUI Conversation Viewer** - - Use `ratatui` to render conversation history, plan updates, and approvals. - - Represent `PlanUpdate` events as checklists and reasoning deltas as streaming text. - - Explore async UI patterns using `tokio` + `crossterm`. - -7. **Diff & Approval UX** - - Parse `applyPatchApproval` payloads and render diffs with crates like `dissimilar` or `similar`. - - Provide approve/deny keybindings and feed decisions back via JSON-RPC. - -8. **Custom MCP Tool Prototype** - - Implement a Rust tool service that Codex can call (mirroring the plan tool pattern). - - Showcase serde-based argument parsing and structured responses. - -## Learning Outcomes - -- Async process management, buffered IO, and JSON serialization in Rust. -- Familiarity with Codex’s turn lifecycle, event taxonomy, and approval flows. -- Experience building CLI/TUI applications and instrumenting them for observability. - -## Next Steps - -- Set up a dedicated Rust workspace with integration tests that launch `codex-app-server` in-process. -- Prioritize Project 1 to establish the transport loop, then layer on additional ideas as separate modules or binaries. - diff --git a/run_codex_convo_plan.md b/run_codex_convo_plan.md new file mode 100644 index 0000000000..def16afba0 --- /dev/null +++ b/run_codex_convo_plan.md @@ -0,0 +1,86 @@ +# `run_codex_convo` CLI Plan + +## Goal + +Single-command Rust utility that takes a user message, runs it through Codex app-server (JSON-RPC over stdio), and prints the streamed assistant output until the turn finishes. + +## Assumptions + +- `codex-app-server` binary is discoverable in `$PATH`. +- User already configured Codex (auth, model defaults) so a fresh conversation can run without extra prompts. +- Project will live in its own cargo crate (`run_codex_convo` workspace member). + +## Functional Requirements + +1. Accept a single positional argument `user_message`; optional flags: + - `--cwd`, `--model`, `--approval-policy`, `--sandbox` (pass-through overrides). +2. Launch `codex-app-server` as a child process with stdio pipes. +3. Perform JSON-RPC handshake (`initialize`, `initialized`). +4. Start a conversation (`newConversation`) with optional overrides. +5. Send the user message (`sendUserMessage`). +6. Subscribe to the conversation (`addConversationListener`). +7. Stream `codex/event/*` notifications: + - Print assistant text (`agent_message`, `agent_message_delta`). + - Surface approvals/errors for visibility. +8. Stop once the server emits `task_complete` or `turn_aborted` for that request. +9. Shutdown child process gracefully (send EOF / kill on timeout). + +## Implementation Outline + +### 1. Workspace Setup + +- Create new binary crate with `tokio` + `anyhow` + `serde` + `serde_json` + `clap` + `tracing`. +- Add helper module re-exporting Codex protocol types or lightweight copies for requests/responses (consider depending on `codex-rs` workspace crate if feasible). + +### 2. Process & IO Management + +- Use `tokio::process::Command` to spawn `codex-app-server` with piped stdin/stdout/stderr. +- Wrap stdio with framed readers/writers (`tokio_util::codec::LinesCodec` or manual line buffering) to handle newline-delimited JSON. +- Spawn task to log stderr from the child for troubleshooting. + +### 3. JSON-RPC Layer + +- Define structs for requests/responses using `serde`. +- Implement `RequestId` generator and helper to send requests and await matching responses (maintain pending map keyed by id, fulfilled when response arrives). +- Parse incoming messages: discriminate between responses (`result`/`error`) and notifications (`method` w/out `id`). + +### 4. Conversation Flow + +1. Send `initialize` with client metadata. +2. Post `initialized` notification. +3. Issue `newConversation` (with optional overrides) and capture `conversationId`. +4. Immediately call `addConversationListener`. +5. Send `sendUserMessage` payload containing provided text. +6. Track the request id of `sendUserMessage` to correlate events. + +### 5. Streaming Output Rendering + +- For `codex/event/agent_message` and `agent_message_delta`, print to stdout (buffer deltas to form cohesive message). +- Optionally colorize using `owo-colors` or similar. +- Surface `agent_reasoning` events as faint/optional output behind a `--show-reasoning` flag. +- If `exec_approval_request` or `apply_patch_approval_request` arrives, log notice that approvals were requested but auto-denied (since CLI cannot interact). + +### 6. Completion Criteria + +- Monitor events for `task_complete` or `turn_aborted` matching this conversation. +- Once received, flush output, collect final status, and exit with code 0 (or non-zero if `error` occurred). +- Ensure outstanding pending requests are dropped to avoid hanging tasks. + +### 7. Graceful Shutdown + +- After completion, send EOF to server stdin or issue `interruptConversation`/`archiveConversation` if desired. +- Await child termination with timeout; on failure, send kill signal. + +### 8. Testing Strategy + +- Unit-test JSON parsing and request builders. +- Write integration test spawning a mocked Codex server (or use real binary behind feature flag) verifying handshake + message flow. +- Add CLI smoke test using `assert_cmd` if Codex binary available. + +## Enhancements (Later) + +- Support multi-turn conversations (`run_codex_convo --repl`). +- Add `--plan` flag to render plan tool output as checklist. +- Stream structured logs to file for debugging. +- Accept stdin message body when positional arg omitted. +