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