Event Processing and State Management

Relevant source files

• codex-rs/app-server-protocol/src/protocol/thread_history.rs
• codex-rs/app-server/tests/suite/v2/client_metadata.rs
• codex-rs/app-server/tests/suite/v2/imagegen_extension.rs
• codex-rs/core/src/context/contextual_user_message.rs
• codex-rs/core/src/context/contextual_user_message_tests.rs
• codex-rs/core/src/context/mod.rs
• codex-rs/core/src/context/world_state/environment.rs
• codex-rs/core/src/context/world_state/environment_render_tests.rs
• codex-rs/core/src/context/world_state/environment_tests.rs
• codex-rs/core/src/context/world_state/mod.rs
• codex-rs/core/src/context/world_state/world_state_tests.rs
• codex-rs/core/src/context_manager/updates.rs
• codex-rs/core/src/event_mapping.rs
• codex-rs/core/src/event_mapping_tests.rs
• codex-rs/core/src/responses_metadata.rs
• codex-rs/core/src/session/world_state.rs
• codex-rs/core/src/stream_events_utils.rs
• codex-rs/core/src/tools/handlers/extension_tools.rs
• codex-rs/core/src/turn_metadata.rs
• codex-rs/core/src/turn_metadata_tests.rs
• codex-rs/core/tests/suite/agent_websocket.rs
• codex-rs/core/tests/suite/extension_sandbox.rs
• codex-rs/core/tests/suite/items.rs
• codex-rs/core/tests/suite/permissions_messages.rs
• codex-rs/core/tests/suite/responses_lite.rs
• codex-rs/ext/image-generation/Cargo.toml
• codex-rs/ext/image-generation/imagegen_description.md
• codex-rs/ext/image-generation/src/extension.rs
• codex-rs/ext/image-generation/src/tests.rs
• codex-rs/ext/image-generation/src/tool.rs
• codex-rs/protocol/src/items.rs
• codex-rs/protocol/src/legacy_events.rs
• codex-rs/protocol/src/lib.rs
• codex-rs/rollout/src/persistence_metrics.rs
• codex-rs/tools/src/tool_call.rs

This page documents how the core agent system maps raw API streaming events into protocol-level EventMsg variants, how session state accumulates and updates per-turn data (token usage, conversation history), and how those updates flow from the end of each turn back into the session for subsequent turns.

For the Op submission side of the protocol, see 2.1 Protocol Layer (Submission/Event System). For conversation history representation and truncation, see 3.5 Conversation History Management.

---

Event Processing Pipeline

When a turn runs, the model provider streams raw deltas. The turn runner consumes these events and maps them to protocol-level outputs. The CodexThread manages the submission loop and event emission via an internal event channel.

API Response-to-EventMsg Pipeline

Sources: codex-rs/core/src/stream_events_utils.rs76-88 codex-rs/core/src/stream_events_utils.rs90-129 codex-rs/core/src/stream_events_utils.rs188-199

Turn Item Processing and Persistence

Finalization of model output items occurs through utilities that bridge the streaming turn state and persistent session history.

• History Recording: record_completed_response_item persists items into the session's conversation history via sess.record_conversation_items codex-rs/core/src/stream_events_utils.rs96-97
• External Context Pollution: Certain items (Web Search, Tool Search) are flagged as "polluting" the thread's memory mode, which may disable memory systems if disable_on_external_context is set codex-rs/core/src/stream_events_utils.rs131-156
• Citations: The system parses assistant output for memory citations using strip_citations and records usage in the StateDb via record_stage1_output_usage codex-rs/core/src/stream_events_utils.rs158-186
• Extension Tool Emission: Extension tools use a CoreTurnItemEmitter to wrap extension-specific items into TurnItem::Extension and emit them as ItemStarted or ItemCompleted events codex-rs/core/src/tools/handlers/extension_tools.rs84-114

Sources: codex-rs/core/src/stream_events_utils.rs76-186 codex-rs/core/src/tools/handlers/extension_tools.rs84-114

---

EventMsg and TurnItem Mapping

The system translates internal ResponseItem types (used for model communication) into TurnItem types (used for UI and history) via parse_turn_item codex-rs/core/src/event_mapping.rs174-181

Key Event Payloads

Event	Payload Context
ItemStarted	Signals the beginning of a TurnItem, such as a UserMessage or AgentMessage codex-rs/core/tests/suite/items.rs104-111
ItemCompleted	Signals completion, providing the finalized TurnItem with full content and IDs codex-rs/core/tests/suite/items.rs112-119
AgentMessageContentDelta	Incremental text updates for assistant messages codex-rs/core/tests/suite/items.rs27
ReasoningContentDelta	Incremental updates for model reasoning/thought chains codex-rs/core/tests/suite/items.rs31
TurnComplete	Signals the end of a turn, often used to trigger UI state transitions codex-rs/core/tests/suite/permissions_messages.rs96

Sources: codex-rs/core/src/event_mapping.rs174-181 codex-rs/core/tests/suite/items.rs75-133 codex-rs/protocol/src/items.rs41-75

---

State Management and Synchronization

World State Construction

The Session constructs a WorldState for each step, which aggregates contextual information to be injected into the model prompt codex-rs/core/src/session/world_state.rs26-29

• Model/Personality: Injects instructions specific to the model slug and active personality codex-rs/core/src/session/world_state.rs59-85
• Permissions: Adds PermissionsState based on the active PermissionProfile and exec_policy codex-rs/core/src/session/world_state.rs105-129
• Environments: Formats environment context and sub-agent information codex-rs/core/src/session/world_state.rs136-144
• Diff Rendering: Sections implement WorldStateSection to render diffs relative to previous snapshots, minimizing redundant context injection codex-rs/core/src/context/world_state/mod.rs205-206

Sources: codex-rs/core/src/session/world_state.rs26-163 codex-rs/core/src/context/world_state/mod.rs205-206

Turn Metadata

The TurnMetadataState tracks ephemeral data required for API requests and tool execution, such as Git repository info and sandbox tags codex-rs/core/src/turn_metadata.rs88-106

• Sandbox Tagging: Generates sandbox tags based on PermissionProfile and WindowsSandboxLevel codex-rs/core/src/turn_metadata.rs124-131
• MCP Context: Filters and provides metadata for External MCP requests, ensuring sensitive tool data is not exposed codex-rs/core/src/turn_metadata.rs153-190

Sources: codex-rs/core/src/turn_metadata.rs88-151 codex-rs/core/src/turn_metadata.rs153-190

---

Data Flow: Natural Language to Code Entity Space

This diagram maps how user-facing events relate to the underlying Rust structs and logic.

Sources: codex-rs/core/src/event_mapping.rs174-181 codex-rs/protocol/src/items.rs41-75 codex-rs/core/src/session/world_state.rs26-29

Turn State Synchronization Lifecycle

Sources: codex-rs/core/src/stream_events_utils.rs90-129 codex-rs/core/src/session/world_state.rs26-29 codex-rs/core/src/turn_metadata.rs178-181