# Specification
## Scope
The crate owns one interaction boundary: Codex app-server turns with either
caller-defined dynamic functions or caller-owned inline image bytes. It does
not execute application functions, implement application policy, retain media
objects, or prescribe the meaning of a prompt or function.
The standard text-and-dynamic-tool API and the dedicated image-analysis API are
separate. Adding image support does not change `AgentRequest` or the behavior
of `Codex::start_turn`.
## Startup
- `Codex::open` rejects empty configuration and requires a successful Codex
`login status` identifying ChatGPT authentication.
- Provider API-key variables are removed from child processes.
- Each turn uses a fresh app-server process with JSONL over standard IO.
- The client initializes with the experimental API capability because dynamic
tools are currently experimental in Codex app-server.
- Codex receives never-approve and read-only policies. Built-in web search,
configured MCP servers, the shell tool, and optional built-in agent features
are disabled.
- An optional caller-supplied sanitized model catalog is passed to Codex, and
automatic compaction is disabled.
- The Codex tool-output token-limit override is fixed at 180,000 tokens for
every app-server process.
## Standard turns
- `Codex::start_turn` accepts an `AgentRequest`.
- A fresh thread receives the supplied model, base instruction, dynamic tool
definitions, ephemerality setting, and exact input text.
- A continued thread is resumed by ID and receives only the supplied new input.
- The `turn/start` input remains one text item containing the exact caller
input.
- Dynamic calls are yielded in the order Codex requests them. The caller must
return one matching result before a sequential Codex call can proceed.
- The runtime does not add application idempotency, batching, or retry policy.
## Image-analysis turns
- `Codex::start_image_turn` accepts an `ImageTurnRequest` and does not modify or
delegate through the public standard-turn API.
- Every image is supplied as caller-owned bytes with a declared PNG, JPEG,
WebP, or GIF media type.
- Empty image bytes are rejected.
- A request must contain between one and eight images and no more than 20 MiB
of image bytes in aggregate.
- The runtime does not inspect, decode, transform, copy to the filesystem, or
retain the image bytes after the running turn releases them.
- Every image is Base64-encoded as an app-server input item of the form
`{"type":"image","url":"data:<media-type>;base64,<encoded-bytes>"}`.
- Image items preserve caller order. One text item containing the exact caller
prompt follows all image items.
- Image turns always create a fresh ephemeral thread, never resume a previous
thread, and expose no caller-defined dynamic tools.
- The configured base instruction still applies. The runtime adds no fixed
captioning or annotation prompt.
- The caller remains responsible for cancelling the turn when its parent
operation is cancelled.
- The completed answer is ordinary prompt-directed text. The crate does not
claim guaranteed OCR accuracy, bounding boxes, coordinates, masks,
segmentation, or deterministic annotations.
## Provider input
- `ProviderInput` contains the exact UTF-8 bytes, represented as a `String`,
written to Codex for each client request or response, including the trailing
newline. The crate does not reformat that event.
- For image turns, the `turn/start` provider input contains the complete
Base64-encoded image bytes.
- The runtime does not redact or replace those bytes because `ProviderInput`
represents the exact outbound transport record.
- Consumers must treat image-turn provider input as media-bearing data rather
than copy it into an ordinary text journal. The authoritative media object
should be retained separately, with only bounded metadata such as object
identity, media type, byte length, and hash recorded in textual history.
## Completion
- A completed turn contains the final non-commentary assistant item, thread and
turn IDs, and the latest reported token usage.
- Completion and usage parsing are identical for standard and image turns.
## Failure
Malformed requests fail before process startup. Authentication, timeout,
transport, cancellation, and protocol failures have stable `ErrorKind` values.
Dropping or cancelling `AgentTurn` terminates the owned app-server process.