mirror of
https://github.com/openai/codex.git
synced 2026-04-24 14:45:27 +00:00
oops wrong doc
This commit is contained in:
Owen Lin
@@ -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.
|
||||
|
||||
86
run_codex_convo_plan.md
Normal file
86
run_codex_convo_plan.md
Normal file
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user