Core Agent Runtime
Overview
This area is the Rust runtime that owns Codex threads, turn orchestration, the client/agent protocol, prompt assembly, persistent rollout history, and runtime diagnostics. External callers normally enter through the public facade in codex-rs/…/lib.rs, which re-exports ThreadManager, CodexThread, protocol Op/EventMsg, configuration types, state DB setup, thread-store construction, model/auth managers, and extension hooks from the covered crates.
codex-rs/…/thread_manager.rs is the process-level orchestrator. ThreadManager::new wires long-lived services from config: auth/runtime auth, model catalog, environment manager, extension registry, user instructions provider, analytics client, attachment store, thread store, MCP/plugin/skills managers, code-mode session provider, and optional agent graph/attestation/time providers. It starts fresh threads with start_thread, resumes from rollout/history with resume_legacy_thread_from_rollout or resume_thread_with_history, spawns internal sessions through a parent thread, and forks via persisted history. ThreadStoreBuilder in codex-rs/…/thread_store_builder.rs selects LocalThreadStore or InMemoryThreadStore; local stores can also kick off startup rollout migration and compression.
CodexThread in codex-rs/…/codex_thread.rs is the handle exposed to hosts and UI layers. It wraps a Session plus SessionIo queues, submits protocol operations (submit), exposes high-level turn entrypoints (start_or_steer_turn, start_turn_if_idle, steer_turn, recover_turn_if_idle), and drains runtime events with next_event. It also exposes lifecycle and host handoffs such as shutdown, background terminal inspection, response-item injection, child-agent preparation/creation, thread metadata updates, config snapshots, and conversation-history snapshots. CodexThreadSettingsOverrides in the same file is the sparse host-facing settings patch applied before future turns.
The wire protocol is defined in codex-rs/…/protocol.rs and codex-rs/…/turn_input.rs. The runtime uses a submission queue/event queue pattern: callers enqueue an Op, and the session loop emits Event { id, msg: EventMsg } back to consumers. Important Op variants include turn input/recovery, realtime conversation start/audio/text/close, approvals, elicitation and dynamic-tool responses, thread-settings updates, MCP refresh, compaction, review, and shutdown. Important EventMsg variants include session configuration, turn lifecycle, user/assistant/reasoning items and deltas, token counts, tool/exec/MCP/realtime events, approval requests, raw response items, and multi-agent activity. SessionConfiguredEvent carries the initial session/thread IDs, model/provider, permission profile, cwd, service tier, network proxy, and rollout path; it is also deserialized compatibly from older rollout records.
The per-thread runtime lives in codex-rs/…/session.rs and codex-rs/…/mod.rs. Session stores thread IDs, item ID generation, event sender, agent status, mutable SessionState, persistence semaphores, MCP refresh state, realtime conversation/history managers, active turn state, async hook results, InputQueue, and a SessionServices bundle. SessionConfiguration captures the effective provider, step settings, environments, developer/base instructions, permission profile, shell/sandbox policy, codex home, source/lineage, originator, dynamic tools, and plugin selection inherited by future turns. SessionIo in codex-rs/…/mod.rs wraps submitted Ops into Submission records from codex-rs/…/submission.rs, preserving trace context, turn extension data, residency guards, and message-delivery receipts.
The submission dispatch loop in codex-rs/…/handlers.rs is the central router. It waits on shutdown, config/catalog/mailbox signals, or queued submissions, then matches each Op and forwards to the appropriate handler. Turn input goes to session/turn_input.rs; realtime ops go to realtime_conversation; approval/elicitation/dynamic-tool replies resolve waiters in the active turn state; ThreadSettings updates are serialized with thread-settings persistence; Shutdown tears down session runtime and live persistence. Session::send_event and send_event_raw_with_persistence in codex-rs/…/mod.rs persist protocol events as RolloutItem::EventMsg, update rollout traces, mirror selected text into realtime handoff streams, notify private Guardian parents, update agent status, and finally deliver on the event queue.
Turn execution is implemented in codex-rs/…/turn.rs. run_turn validates input modalities, drains async hook results, optionally compacts before sampling, gathers MCP/plugin requirements from user input, captures a StepContext, records context/world-state updates, builds skills/plugin injections, runs startup hooks and Guardian preparation, then records input and enters one or more sampling requests. run_sampling_request clones current history, converts it to prompt input through ContextManager::for_prompt, attaches executed tool-call outputs, builds a Prompt, injects Guardian/native-search metadata, and sends it through ModelClientSession. Tool execution and code-mode workers run around the streaming response; steering and mailbox activity can preempt retry handling and schedule follow-up sampling. codex-rs/…/client.rs owns provider calls: ModelClient is session-scoped, ModelClientSession is per-turn, carries Responses/WebSocket state, emits auth recovery events, attaches x-codex-* metadata, and uses codex-response-debug-context to sanitize HTTP/request diagnostics.
Prompt text comes from a few layers. codex-rs/…/model_instructions.rs renders the base instruction template from captured ModelInfo; codex-rs/…/model_messages.rs resolves catalog-supplied or bundled text for permissions, apps, plugins, collaboration, multi-agent, auto-review, token-budget, tool, and context-management messages. codex-rs/core/src/session/turn.rs::build_prompt combines model-visible history, tool specs, base instructions, output schema, prompt-cache TTL, and cyber access settings. Context snippets and durable user/developer fragments are represented by codex-rs/…/lib.rs; core records them as Responses items and filters harness-owned contextual messages in codex-rs/…/event_mapping.rs so UI turn items do not display invisible prompt scaffolding.
Persistence is split between replay rollouts and queryable indexes. codex-rs/…/lib.rs defines RolloutItem, RolloutLine, InitialHistory, ResumedHistory, ResponseItemEnvelope, compaction records, retained context, realtime items, world state, token-usage records, and event records. codex-rs/…/lib.rs parses JSONL rollout lines through a canonical JSON decoder, lists/finds sessions, opens compressed/plain readers, resolves metadata, applies persistence policy, and exposes RolloutRecorder. codex-rs/…/recorder.rs writes canonical JSONL records with session metadata, rollout IDs, source/parent/fork data, base instructions, dynamic tools, selected capability roots, multi-agent version, history mode, history base, and initial context-window ID. codex-rs/…/store.rs is the storage-neutral boundary used by core to create, resume, append, persist, flush, list, fork, archive, delete, and attach metadata to threads. The local implementation in codex-rs/…/mod.rs keeps canonical JSONL history readable without SQLite while mirroring metadata into SQLite when available; it serializes writer access, lifecycle locks, fork reservations, and lazy materialization.
codex-rs/…/lib.rs owns SQLite-backed metadata/runtime state. It indexes rollout-derived thread metadata, projects, sections, queues, attachments, goals, memory/read-state data, model IDs, remote-control enrollment, logs, corruption handling, and DB telemetry. codex-rs/thread-store re-exports this through its store APIs so core can route thread list/read/search/timeline/attachment/section/project operations without depending on concrete DB calls. codex-rs/…/lib.rs is separate from thread replay: it appends user prompt text to ~/.codex/history.jsonl according to config, using file locking and size trimming.
Attachments and media flow through codex-rs/…/lib.rs. Core receives an AttachmentStore in ThreadManager::new; the trait uploads bytes into either inline data or external file IDs, resolves metadata and expiring URLs, and lets prompt preparation drop only file references confirmed missing. InlineAttachmentStore is the no-op implementation for hosts that keep attachments inline. Thread-level app attachments are persisted through thread-store/state attachment APIs, while model-visible image/audio preparation in core consults the attachment store before building prompt input.
Realtime and trace history are first-class runtime side channels. Realtime Op variants in codex-rs/…/protocol.rs are handled by core's realtime_conversation modules; Session::send_event mirrors assistant text/reasoning into active realtime handoffs and persists reduced realtime presentation as rollout items through realtime_history. Diagnostic trace bundles are owned by codex-rs/…/lib.rs: hot-path core code records thread starts, protocol events, inference attempts, compaction checkpoints, MCP/tool dispatch, code cells, and agent results through no-op-capable trace contexts. The consumer-facing API is reduced state.json; raw trace.jsonl replay is only for the exact binary that wrote it.
Telemetry and feedback are integrated but kept on sanitized boundaries. codex-rs/…/lib.rs exports AnalyticsEventsClient and typed facts for turn errors/config/token usage/profile, compaction, Guardian reviews, plugin/app/skill usage, subagent starts, code-mode/control-tool calls, artifacts, and product attribution. Core stores an analytics client in SessionServices, tracks accepted input and resolved turn config from session/turn.rs, errors and Guardian events from session/mod.rs, and subagent starts near session startup. codex-rs/…/lib.rs captures diagnostic logs into a bounded ring, records sanitized auth/request tags, implements SQLite log-write failure reporting, collects Guardian review failures, and prepares bounded report attachments for upload. codex-rs/…/lib.rs extracts request IDs, Cloudflare ray IDs, and auth error codes from HTTP headers while ensuring telemetry error messages do not include upstream response bodies.
Path-routing notes for the covered crates:
- Runtime orchestration, turns, tools, provider client, config snapshots, event persistence, MCP/realtime/agent handoffs:
codex-rs/core/**. - Public API surface for hosts/apps/tests:
codex-rs/core-api/**. - Stable protocol/event/input/config/shared model types:
codex-rs/protocol/**. - Prompt templates and model-message resolution:
codex-rs/prompts/**. - JSONL rollout parsing/writing/listing/search/compression and trace bundle schema:
codex-rs/rollout/**,codex-rs/rollout-trace/**. - Replay-domain data and standalone prompt history:
codex-rs/history/**,codex-rs/message-history/**. - Thread persistence abstraction, local implementation, and SQLite runtime state:
codex-rs/thread-store/**,codex-rs/state/**. - Prompt/context fragments, debug context, attachment storage, feedback, analytics:
codex-rs/context-fragments/**,codex-rs/response-debug-context/**,codex-rs/attachment-store/**,codex-rs/feedback/**,codex-rs/analytics/**.
Coupling
- If an
Opvariant is added or its semantics change in codex-rs/…/protocol.rs, update dispatch in codex-rs/…/handlers.rs and any host-facing re-export in codex-rs/…/lib.rs; otherwise callers can submit an operation that the session loop silently ignores via the non-exhaustive fallback. - If an
EventMsgvariant becomes durable or changes wire fields in codex-rs/…/protocol.rs, verifySession::send_event_raw_with_persistencein codex-rs/…/mod.rs, rollout decoding in codex-rs/…/lib.rs,RolloutItemserialization in codex-rs/…/lib.rs, UI event projection in codex-rs/…/event_mapping.rs, and trace recording incodex-rs/rollout-trace/**. - If prompt wrapper tags or contextual developer/user fragments change in codex-rs/…/protocol.rs,
codex-rs/prompts/**, orcodex-rs/context-fragments/**, update codex-rs/…/event_mapping.rs; rollback, display projection, and history reconstruction depend on recognizing harness-owned messages instead of treating them as user-visible turns. - If turn-input routing or retention changes in codex-rs/…/turn_input.rs, verify codex-rs/…/codex_thread.rs, codex-rs/…/turn_input.rs, codex-rs/…/input_queue.rs, and codex-rs/…/lib.rs; start/steer/recover decisions, per-input extension data, and compaction retention are split across those layers.
- If rollout metadata fields change in codex-rs/…/lib.rs or codex-rs/…/recorder.rs, update codex-rs/…/types.rs, local materialization in
codex-rs/thread-store/src/local/**, and SQLite extraction incodex-rs/state/src/**; local storage uses JSONL as canonical replay while SQLite is a derived query index. - If thread-store persistence guarantees change in codex-rs/…/store.rs, verify all
PersistContextusers incodex-rs/core/src/session/**and lifecycle calls in codex-rs/…/thread_manager.rs; turn start and steered input allow background persistence, but standard persistence and shutdown/fork paths require durable/readable history before acknowledgement. - If model-message catalog fields change in codex-rs/…/model_messages.rs, update consumers in codex-rs/…/turn.rs, permission/tool rendering, Guardian, plugin/app/skills prompts, and tests around
build_prompt; missing catalog text intentionally falls back to bundled defaults, while explicit empty strings can be meaningful overrides. - If attachment file-reference semantics change in codex-rs/…/lib.rs, verify media prompt conversion in
codex-rs/core/src/context_manager/**, image/audio preparation in codex-rs/…/turn.rs, and thread attachment persistence incodex-rs/thread-store/**/codex-rs/state/**; prompt construction keeps unknown external file IDs unless the authoritative store confirms they are missing. - If analytics or feedback payloads add request/auth details, keep sanitization aligned with codex-rs/…/lib.rs and codex-rs/…/lib.rs; upstream response bodies and raw secrets must not flow into telemetry or feedback logs.
Risks
- codex-rs/…/handlers.rs has a catch-all
_ => falsefor unknownOps. If a new protocol operation is added without an explicit dispatch arm, submissions appear accepted but produce no behavior or error, which can deadlock callers waiting for side effects not enforced by the type system. codex-rs/core/src/session/mod.rs::send_event_raw_with_persistencecouples event ordering, rollout persistence, realtime-history reduction, MCP observation, trace recording, and event delivery. Reordering this path can make UI-visible events arrive before their durable rollout entries or make realtime history disagree with replay.codex-rs/rollout/src/lib.rs::decode_rollout_lineexists because Serde's flattened-envelope buffering can corrupt arbitrary-precision JSON decimals. Readers that bypassparse_rollout_line/parse_rollout_line_bytesrisk losing numeric fidelity and producing histories that cannot be faithfully replayed.- codex-rs/…/mod.rs maintains separate writer and lifecycle locks. Cleanup hooks installed through codex-rs/…/thread_store_builder.rs are explicitly forbidden from calling store operations that reacquire those locks; doing so during deletion can deadlock live persistence.
- codex-rs/…/lib.rs documents that raw trace replay is only compatible with the exact Codex binary that wrote the bundle. Changing raw trace payloads without updating the writer/reducer together can leave diagnostic traces unreplayable; changing reduced state.json without bumping the reduced schema can break consumers.