kcode-codex-runtime-v2

kcode-codex-runtime-v2 runs standard multi-step Codex turns through the app-server JSON-RPC protocol. A caller supplies dynamic function schemas, receives function calls as events, returns their results, and receives the terminal assistant message without inventing a text tool protocol.

The existing Codex::start_turn API remains the standard text-and-dynamic-tool flow. Codex::start_image_turn is a separate flow for prompt-directed image analysis. It accepts caller-owned PNG, JPEG, WebP, or GIF bytes, Base64-encodes them into app-server image data-URL items, appends the exact text prompt, and always uses a fresh, ephemeral thread with no dynamic tools.

The runtime uses ChatGPT login from the configured Codex executable. It removes API-key environment variables, accepts an optional sanitized model catalog, requests read-only/never-approve operation, disables automatic compaction, and disables Codex web search, MCP servers, and optional built-in agent features. It overrides Codex's per-tool output policy to 180,000 tokens. Application tools remain owned and executed by the caller.

Every JSONL record written by the runtime is emitted verbatim as AgentEvent::ProviderInput. For a standard text turn, consumers may use this as the exact client-to-Codex transport record they control. For an image turn, the turn/start record contains the complete Base64-encoded image bytes and must be treated as media-bearing data rather than copied into an ordinary text journal. Consumers should instead retain their authoritative media object and record bounded metadata such as its identity, media type, byte length, and hash.

Codex or the upstream model may add instructions or metadata internally; this crate cannot expose bytes it never receives. Image understanding returns ordinary textual model output and does not guarantee OCR accuracy, bounding boxes, masks, coordinates, or deterministic annotations.

See Documentation.md for the API and Specification.md for normative behavior.