Result persistence, projection, and user-visible state updates

async fn apply_bespoke_event_handling(
    event: Event,
    conversation_id: ThreadId,
    conversation: Arc<CodexThread>,
    thread_manager: Arc<ThreadManager>,
    outgoing: ThreadScopedOutgoingMe

Purpose: This is the central dispatcher for one core event. It decides whether to notify the client, ask the client for a decision, update thread-watch state, or submit a response back into the running Codex thread.

Data flow: It receives a core event plus the thread, outgoing message sender, shared thread state, thread manager, and fallback configuration. It inspects the event kind, builds the matching app-server notification or request, updates shared state when needed, and either sends messages to clients or starts background tasks that wait for client replies. The visible result is that clients see live thread updates and Codex core receives any decisions or answers it needs.

Call relations: This function is called by tests and by the surrounding event loop in production. It hands specialized work to helpers such as handle_turn_complete, handle_error_notification, handle_token_count_event, start_command_execution_item, and the response-waiting functions when an event needs more than a direct notification.

Call graph: calls 38 internal fn (complete_command_execution_item, handle_error_notification, handle_thread_rollback_failed, handle_token_count_event, handle_turn_complete, handle_turn_diff, handle_turn_interrupted, handle_turn_plan_update, maybe_emit_hook_prompt_item_completed, maybe_emit_raw_response_item_completed (+15 more)); called by 3 (apply_guardian_assessment_event, interrupted_subagent_activity_removes_missing_thread_watch, turn_started_omits_active_snapshot_items); 46 external calls (DeprecationNotice, Error, GuardianWarning, HookCompleted, HookStarted, ItemCompleted, ItemStarted, McpServerStatusUpdated, ModelRerouted, ModelVerification (+15 more)).

async fn handle_turn_diff(
    conversation_id: ThreadId,
    event_turn_id: &str,
    turn_diff_event: TurnDiffEvent,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

Purpose: This sends clients the current text diff for a turn. A diff is a compact view of what changed in files, similar to what a code review shows.

Data flow: It takes the thread id, turn id, and core diff text. It wraps that text in a client-facing TurnDiffUpdated notification and sends it out. It does not change stored state.

Call relations: apply_bespoke_event_handling calls this when core reports a TurnDiff event. A test calls it directly to confirm the v2 notification shape.

Call graph: calls 1 internal fn (send_server_notification); called by 2 (apply_bespoke_event_handling, test_handle_turn_diff_emits_v2_notification); 2 external calls (TurnDiffUpdated, to_string).

async fn handle_turn_plan_update(
    conversation_id: ThreadId,
    event_turn_id: &str,
    plan_update_event: UpdatePlanArgs,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

Purpose: This tells clients that the assistant’s checklist or todo plan changed. It is for the update_plan tool, not for a separate planning mode.

Data flow: It receives the core plan update, converts each plan step into the app-server format, keeps any explanation text, and sends a TurnPlanUpdated notification. The output is a client-visible checklist update.

Call relations: apply_bespoke_event_handling calls it for PlanUpdate events. The related test verifies that plan steps and statuses are translated correctly.

Call graph: calls 1 internal fn (send_server_notification); called by 2 (apply_bespoke_event_handling, test_handle_turn_plan_update_emits_notification_for_v2); 2 external calls (TurnPlanUpdated, to_string).

async fn emit_turn_completed_with_status(
    conversation_id: ThreadId,
    event_turn_id: String,
    turn_completion_metadata: TurnCompletionMetadata,
    outgoing: &ThreadScopedOutgoingMessageSend

Purpose: This sends the final “turn completed” message with the chosen outcome, such as completed, failed, or interrupted.

Data flow: It receives a thread id, turn id, completion metadata, and outgoing sender. It builds a Turn object with no loaded items, attaches status, error, and timing data, then sends a TurnCompleted notification.

Call relations: handle_turn_complete and handle_turn_interrupted call this after they decide the final status. It is the shared last step for ending a turn.

Call graph: calls 1 internal fn (send_server_notification); called by 2 (handle_turn_complete, handle_turn_interrupted); 3 external calls (TurnCompleted, to_string, vec!).

async fn start_command_execution_item(
    conversation_id: &ThreadId,
    turn_id: String,
    item_id: String,
    command: String,
    cwd: AbsolutePathBuf,
    command_actions: Vec<V2ParsedCommand

Purpose: This announces that a command execution item has started, but only once for the same item. This prevents duplicate command rows in the client.

Data flow: It receives command details, the turn and thread ids, shared thread state, and the outgoing sender. It records the item id in the turn summary; if it was not already present, it sends an ItemStarted notification with an in-progress command item. It returns whether this was the first start.

Call relations: apply_bespoke_event_handling uses it for command approvals and guardian assessments before a command is actually allowed or denied. Tests call it directly to prove duplicate starts are suppressed.

Call graph: calls 2 internal fn (now_unix_timestamp_ms, send_server_notification); called by 3 (apply_bespoke_event_handling, command_execution_started_helper_emits_once, complete_command_execution_item_emits_declined_once_for_pending_command); 2 external calls (ItemStarted, to_string).

async fn complete_command_execution_item(
    conversation_id: &ThreadId,
    turn_id: String,
    item_id: String,
    command: String,
    cwd: AbsolutePathBuf,
    process_id: Option<String>,
    s

Purpose: This announces that a previously started command item has finished, failed, or was declined. It only emits a completion if the command had been marked as started.

Data flow: It receives command details, completion status, shared state, and the outgoing sender. It removes the command id from the set of started commands; if removal succeeds, it sends an ItemCompleted notification. If the command was not pending, it sends nothing.

Call relations: apply_bespoke_event_handling and on_command_execution_request_approval_response call this when a command-like approval ends negatively. Tests verify that it emits once and then clears the pending marker.

Call graph: calls 2 internal fn (now_unix_timestamp_ms, send_server_notification); called by 3 (apply_bespoke_event_handling, on_command_execution_request_approval_response, complete_command_execution_item_emits_declined_once_for_pending_command); 2 external calls (ItemCompleted, to_string).

async fn maybe_emit_raw_response_item_completed(
    conversation_id: ThreadId,
    turn_id: &str,
    item: codex_protocol::models::ResponseItem,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

Purpose: This forwards a raw model response item to clients as a completed raw-response item. It preserves the lower-level model output for clients that need it.

Data flow: It receives a thread id, turn id, raw response item, and outgoing sender. It wraps the item in RawResponseItemCompletedNotification and sends it. No state is changed.

Call relations: apply_bespoke_event_handling calls it when core emits a RawResponseItem event, after first checking whether the same raw item also represents a hook prompt.

Call graph: calls 1 internal fn (send_server_notification); called by 1 (apply_bespoke_event_handling); 2 external calls (RawResponseItemCompleted, to_string).

async fn maybe_emit_hook_prompt_item_completed(
    conversation_id: ThreadId,
    turn_id: &str,
    item: &codex_protocol::models::ResponseItem,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

Purpose: This detects when a raw response item is actually a hook prompt and emits a clearer hook-prompt item for clients. A hook prompt is generated text that asks the assistant to react to hook results.

Data flow: It receives a response item by reference. If the item is not a user message, or cannot be parsed as a hook prompt, it does nothing. If parsing succeeds, it converts the prompt fragments into app-server fragments and sends an ItemCompleted notification.

Call relations: apply_bespoke_event_handling calls it before forwarding raw response items. The hook prompt test builds a sample prompt and checks that this helper emits the expected item.

Call graph: calls 3 internal fn (now_unix_timestamp_ms, send_server_notification, parse_hook_prompt_message); called by 2 (apply_bespoke_event_handling, test_hook_prompt_raw_response_emits_item_completed); 2 external calls (ItemCompleted, to_string).

async fn find_and_remove_turn_summary(
    _conversation_id: ThreadId,
    thread_state: &Arc<Mutex<ThreadState>>,
) -> TurnSummary

Purpose: This takes the current turn summary out of shared thread state and resets that slot. The summary is scratch paper for one turn: errors, start time, and command-start markers.

Data flow: It locks the shared ThreadState, replaces the stored TurnSummary with a fresh empty one, and returns the old summary to the caller. The before state has accumulated turn details; the after state is ready for the next turn.

Call relations: handle_turn_complete and handle_turn_interrupted use this when a turn ends. Tests use it to inspect what handle_error recorded.

Call graph: called by 3 (handle_turn_complete, handle_turn_interrupted, test_handle_error_records_message); 1 external calls (take).

async fn handle_turn_complete(
    conversation_id: ThreadId,
    event_turn_id: String,
    turn_complete_event: TurnCompleteEvent,
    outgoing: &ThreadScopedOutgoingMessageSender,
    thread_state:

Purpose: This finishes a normal turn and decides whether it should be reported as completed or failed. A turn is marked failed if an earlier error was recorded in the turn summary.

Data flow: It removes the accumulated turn summary, checks for a stored error, combines that with completion timing from core, and asks emit_turn_completed_with_status to send the final notification. It clears per-turn summary state as part of finishing.

Call relations: apply_bespoke_event_handling calls it when core emits TurnComplete. Several tests call it directly to check successful, failed, and multi-turn behavior.

Call graph: calls 2 internal fn (emit_turn_completed_with_status, find_and_remove_turn_summary); called by 4 (apply_bespoke_event_handling, test_handle_turn_complete_emits_completed_without_error, test_handle_turn_complete_emits_error_multiple_turns, test_handle_turn_complete_emits_failed_with_error).

async fn handle_turn_interrupted(
    conversation_id: ThreadId,
    event_turn_id: String,
    turn_aborted_event: TurnAbortedEvent,
    outgoing: &ThreadScopedOutgoingMessageSender,
    thread_state

Purpose: This finishes a turn that was interrupted by the user or system. It reports the turn as interrupted rather than failed.

Data flow: It removes the accumulated turn summary, ignores any stored turn error for the final interrupted notification, attaches interruption timing, and sends a TurnCompleted notification with Interrupted status. The turn summary is cleared afterward.

Call relations: apply_bespoke_event_handling calls it for TurnAborted events. A test calls it directly to confirm interrupted turns do not surface a stored error as the final turn error.

Call graph: calls 2 internal fn (emit_turn_completed_with_status, find_and_remove_turn_summary); called by 2 (apply_bespoke_event_handling, test_handle_turn_interrupted_emits_interrupted_with_error).

async fn handle_thread_rollback_failed(
    _conversation_id: ThreadId,
    message: String,
    thread_state: &Arc<Mutex<ThreadState>>,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

Purpose: This fails a pending rollback request when core reports that rollback did not work. It prevents the client request from hanging forever.

Data flow: It takes any pending rollback request id out of thread state. If one exists, it sends an invalid-request error response containing the failure message. If no rollback is pending, it does nothing.

Call relations: apply_bespoke_event_handling calls it when an Error event is specifically marked as ThreadRollbackFailed.

Call graph: calls 2 internal fn (invalid_request, send_error); called by 1 (apply_bespoke_event_handling).

fn thread_rollback_response_from_stored_thread(
    stored_thread: codex_thread_store::StoredThread,
    session_id: String,
    fallback_model_provider: &str,
    fallback_cwd: &AbsolutePathBuf,

Purpose: This rebuilds the client-facing thread object after a rollback has changed stored history. It gives the requester a fresh view of the thread.

Data flow: It receives a stored thread, session id, fallback model provider, fallback working directory, and current loaded status. It converts the stored thread into the app-server thread model, requires persisted history to be present, repopulates turns from that history, applies the loaded status, and returns a ThreadRollbackResponse or an error string.

Call relations: apply_bespoke_event_handling calls it after core says a rollback completed. The rollback test calls it directly with a pathless stored thread to make sure history reconstruction works.

Call graph: called by 2 (apply_bespoke_event_handling, rollback_response_rebuilds_pathless_thread_from_stored_history); 3 external calls (populate_thread_turns_from_history, thread_from_stored_thread, format!).

async fn respond_to_pending_interrupts(
    thread_state: &Arc<Mutex<ThreadState>>,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

Purpose: This replies to any client requests that asked to interrupt a turn once the turn has actually ended or been aborted.

Data flow: It removes the list of pending interrupt request ids from shared state. For each id, it sends an empty TurnInterruptResponse. Afterward, no interrupt requests remain pending.

Call relations: apply_bespoke_event_handling calls it on TurnComplete and TurnAborted, because both mean outstanding interrupt requests can now be resolved.

Call graph: calls 1 internal fn (send_response); called by 1 (apply_bespoke_event_handling); 1 external calls (take).

async fn handle_token_count_event(
    conversation_id: ThreadId,
    turn_id: String,
    token_count_event: TokenCountEvent,
    outgoing: &ThreadScopedOutgoingMessageSender,
)

Purpose: This sends clients updated token usage and account rate-limit information. Tokens are pieces of text counted by the model, and rate limits describe usage caps.

Data flow: It receives token usage data and optional rate-limit data. If usage is present, it converts it into ThreadTokenUsageUpdatedNotification. If rate limits are present, it sends AccountRateLimitsUpdatedNotification. Either part may be absent.

Call relations: apply_bespoke_event_handling calls it for TokenCount events. Tests verify both the case with usage/rate limits and the case where nothing should be emitted.

Call graph: calls 1 internal fn (send_server_notification); called by 3 (apply_bespoke_event_handling, test_handle_token_count_event_emits_usage_and_rate_limits, test_handle_token_count_event_without_usage_info); 3 external calls (AccountRateLimitsUpdated, ThreadTokenUsageUpdated, to_string).

async fn handle_error(
    _conversation_id: ThreadId,
    error: TurnError,
    thread_state: &Arc<Mutex<ThreadState>>,
)

Purpose: This records that the current turn has hit an error. It does not notify the client by itself.

Data flow: It receives a TurnError and shared thread state. It locks the state and stores the error as the turn summary’s last error. Later turn completion can then mark the turn as failed.

Call relations: handle_error_notification calls it before sending an error notification. Tests call it directly to confirm the error is kept in the turn summary.

Call graph: called by 5 (handle_error_notification, test_handle_error_records_message, test_handle_turn_complete_emits_error_multiple_turns, test_handle_turn_complete_emits_failed_with_error, test_handle_turn_interrupted_emits_interrupted_with_error).

async fn handle_error_notification(
    conversation_id: ThreadId,
    event_turn_id: &str,
    error: TurnError,
    outgoing: &ThreadScopedOutgoingMessageSender,
    thread_state: &Arc<Mutex<ThreadS

Purpose: This records an error for the turn and also tells the client about it. It is used for errors that affect the turn’s final status.

Data flow: It receives the thread id, turn id, error, outgoing sender, and shared state. It stores the error through handle_error, then sends an Error notification with will_retry set to false. The client sees the error and the turn summary remembers it.

Call relations: apply_bespoke_event_handling calls it for status-affecting core errors. on_request_permissions_response also calls it if granted filesystem paths cannot be localized safely.

Call graph: calls 2 internal fn (handle_error, send_server_notification); called by 2 (apply_bespoke_event_handling, on_request_permissions_response); 3 external calls (Error, clone, to_string).

async fn on_request_user_input_response(
    event_turn_id: String,
    pending_request_id: RequestId,
    receiver: oneshot::Receiver<ClientRequestResult>,
    conversation: Arc<CodexThread>,
    thr

Purpose: This waits for the client’s answers to a tool’s user-input questions and sends those answers back to core. If the client fails, it sends an empty answer set so the tool can continue or stop cleanly.

Data flow: It receives the pending request id, a one-shot receiver for the client response, the conversation, thread state, and a guard marking user input as active. It waits for the response, clears the pending-request marker, drops the guard, deserializes answers if possible, and submits UserInputAnswer to the Codex thread.

Call relations: apply_bespoke_event_handling starts this in a background task after sending ToolRequestUserInput to the client. It is the return path from client UI back to core.

Call graph: calls 2 internal fn (is_turn_transition_server_request_error, resolve_server_request_on_thread_listener); called by 1 (apply_bespoke_event_handling); 2 external calls (new, error!).

async fn on_mcp_server_elicitation_response(
    server_name: String,
    request_id: codex_protocol::mcp::RequestId,
    pending_request_id: RequestId,
    receiver: oneshot::Receiver<ClientRequestRe

Purpose: This waits for the client’s answer to an MCP server elicitation request and submits that answer back to core. MCP is a tool-server protocol; elicitation means the server asks the user for a decision or data.

Data flow: It waits on the client response channel, clears pending-request state, drops the permission guard, converts the response into a safe app-server response, and submits ResolveElicitation to the Codex thread. The result is that the MCP server receives accept, decline, or cancel plus optional content.

Call relations: apply_bespoke_event_handling spawns it after sending McpServerElicitationRequest. It relies on mcp_server_elicitation_response_from_client_result to normalize errors and bad JSON.

Call graph: calls 2 internal fn (mcp_server_elicitation_response_from_client_result, resolve_server_request_on_thread_listener); called by 1 (apply_bespoke_event_handling); 1 external calls (error!).

fn mcp_server_elicitation_response_from_client_result(
    response: std::result::Result<ClientRequestResult, oneshot::error::RecvError>,
) -> McpServerElicitationRequestResponse

Purpose: This turns a raw client response for MCP elicitation into a safe, typed decision. It chooses conservative defaults when the client response is missing or malformed.

Data flow: It receives either a successful JSON value, a client error, or a closed response channel. Successful JSON is parsed into McpServerElicitationRequestResponse. Turn-transition errors become Cancel; other failures become Decline.

Call relations: on_mcp_server_elicitation_response calls it before submitting the decision to core. A test verifies that turn-transition errors map to Cancel.

Call graph: calls 1 internal fn (is_turn_transition_server_request_error); called by 2 (on_mcp_server_elicitation_response, mcp_server_elicitation_turn_transition_error_maps_to_cancel); 1 external calls (error!).

async fn on_request_permissions_response(
    pending_response: PendingRequestPermissionsResponse,
    conversation: Arc<CodexThread>,
    thread_state: Arc<Mutex<ThreadState>>,
)

Purpose: This waits for the client’s answer to a permission request and submits the granted permissions back to core. It also handles unsafe or invalid granted paths by reporting an error and interrupting the turn.

Data flow: It unpacks the pending permission request, waits for the client reply, clears pending state, drops the active permission guard, converts the reply with request_permissions_response_from_client_result, records the effective approval, and submits RequestPermissionsResponse to the Codex thread. If path conversion fails, it sends an error notification and asks core to interrupt.

Call relations: apply_bespoke_event_handling spawns it when core asks for broader permissions. It uses handle_error_notification for serious conversion failures and request_permissions_response_from_client_result for normal parsing.

Call graph: calls 3 internal fn (handle_error_notification, request_permissions_response_from_client_result, resolve_server_request_on_thread_listener); called by 1 (apply_bespoke_event_handling); 2 external calls (error!, format!).

fn request_permissions_response_from_client_result(
    requested_permissions: CoreRequestPermissionProfile,
    response: std::result::Result<ClientRequestResult, oneshot::error::RecvError>,
    cwd:

Purpose: This safely converts a client permission approval into the core permission format. It never grants more than core originally requested.

Data flow: It receives the requested permission profile, the raw client response, and the working directory used for path interpretation. Client failures become an empty turn-scoped grant, while turn-transition errors are ignored. Successful replies are parsed, validated, localized to filesystem paths, intersected with the requested permissions, and returned with scope and strict-auto-review settings.

Call relations: on_request_permissions_response calls it before submitting a permission decision to core. Many tests call it directly to confirm partial grants, session scope, strict auto-review rules, and path-scope safety.

Call graph: calls 2 internal fn (is_turn_transition_server_request_error, intersect_permission_profiles); called by 9 (on_request_permissions_response, request_permissions_response_accepts_explicit_child_grant_for_requested_cwd_scope, request_permissions_response_accepts_partial_network_and_file_system_grants, request_permissions_response_ignores_broader_cwd_grant_for_requested_child_path, request_permissions_response_preserves_session_scope, request_permissions_response_preserves_turn_scoped_strict_auto_review, request_permissions_response_rejects_child_grant_outside_requested_cwd_scope, request_permissions_response_rejects_session_scoped_strict_auto_review, request_permissions_turn_transition_error_is_ignored); 5 external calls (default, into, default, error!, matches!).

fn render_review_output_text(output: &ReviewOutputEvent) -> String

Purpose: This turns structured review output into readable text for the client. It combines an overall explanation with formatted findings.

Data flow: It receives a review output event. It trims the explanation, formats any findings, drops empty sections, and joins the remaining sections with blank lines. If nothing useful exists, it returns a fallback message.

Call relations: apply_bespoke_event_handling calls it when emitting an ExitedReviewMode item.

Call graph: calls 1 internal fn (format_review_findings_block); called by 1 (apply_bespoke_event_handling); 1 external calls (new).

fn map_file_change_approval_decision(decision: FileChangeApprovalDecision) -> ReviewDecision

Purpose: This translates a client-facing file-change approval choice into the core review decision type. It keeps the same meaning across two protocol layers.

Data flow: It receives a FileChangeApprovalDecision such as accept, accept for session, decline, or cancel. It returns the matching core ReviewDecision: approved, approved for session, denied, or abort.

Call relations: on_file_change_request_approval_response uses it before submitting PatchApproval to core. A test checks the accept-for-session mapping.

Call graph: called by 2 (on_file_change_request_approval_response, file_change_accept_for_session_maps_to_approved_for_session).

async fn on_file_change_request_approval_response(
    item_id: String,
    pending_request_id: RequestId,
    receiver: oneshot::Receiver<ClientRequestResult>,
    codex: Arc<CodexThread>,
    thread

Purpose: This waits for the client’s decision about a proposed file change and sends that decision back to core.

Data flow: It waits for the client response, clears the pending-request marker, drops the permission guard, parses the file-change approval response, maps it to a core review decision, and submits PatchApproval with the item id. Failures default to denial, except turn-transition errors are ignored.

Call relations: apply_bespoke_event_handling spawns it after sending FileChangeRequestApproval. It uses map_file_change_approval_decision for the protocol translation.

Call graph: calls 3 internal fn (map_file_change_approval_decision, is_turn_transition_server_request_error, resolve_server_request_on_thread_listener); called by 1 (apply_bespoke_event_handling); 1 external calls (error!).

async fn on_command_execution_request_approval_response(
    event_turn_id: String,
    conversation_id: ThreadId,
    approval_id: Option<String>,
    item_id: String,
    completion_item: Option<Com

Purpose: This waits for the client’s decision about running a command or changing network/exec policy, then submits the decision back to core. It can also close a visible command item if the command was declined or failed before running.

Data flow: It waits for the approval response, clears pending state, drops the permission guard, parses the decision, translates it into a core ReviewDecision, and determines whether a command item should be completed with declined or failed status. Finally it submits ExecApproval to the Codex thread.

Call relations: apply_bespoke_event_handling spawns it after sending CommandExecutionRequestApproval. It calls complete_command_execution_item when a visible pending command needs to be ended.

Call graph: calls 3 internal fn (complete_command_execution_item, is_turn_transition_server_request_error, resolve_server_request_on_thread_listener); called by 1 (apply_bespoke_event_handling); 1 external calls (error!).

fn now_unix_timestamp_ms() -> i64

Purpose: This returns the current time as milliseconds since the Unix epoch, which is a common timestamp starting point: midnight UTC on January 1, 1970.

Data flow: It reads the system clock, converts the duration since the Unix epoch into milliseconds, and returns that number. If the clock is somehow before the epoch, it returns zero.

Call relations: Event helpers use it when they need a started_at or completed_at timestamp for synthetic item notifications.

Call graph: called by 4 (apply_bespoke_event_handling, complete_command_execution_item, maybe_emit_hook_prompt_item_completed, start_command_execution_item); 1 external calls (now).

fn new_thread_state() -> Arc<Mutex<ThreadState>>

Purpose: This test helper creates a fresh shared ThreadState. It gives each test a clean piece of mutable thread state.

Data flow: It constructs a default ThreadState, wraps it in a Mutex so async code can lock it safely, then wraps that in Arc so multiple tasks can share it. The result is ready for tests to pass into handlers.

Call relations: Many tests use it before calling handlers that expect shared thread state.

Call graph: 3 external calls (new, new, default).

async fn recv_broadcast_message(
        rx: &mut mpsc::Receiver<OutgoingEnvelope>,
    ) -> Result<OutgoingMessage>

Purpose: This test helper receives one outgoing message from a channel and unwraps it from its envelope. It lets tests inspect what the server would send to clients.

Data flow: It waits for the next OutgoingEnvelope from a test channel. Whether the envelope is broadcast or connection-specific, it extracts and returns the contained OutgoingMessage. If no message arrives, it returns an error.

Call relations: Notification-focused tests call it after invoking a handler to check the emitted message.

Call graph: calls 1 internal fn (recv).

fn rollback_response_rebuilds_pathless_thread_from_stored_history() -> Result<()>

Purpose: This test proves rollback response construction can rebuild a thread from stored history even when the stored thread has no rollout path.

Data flow: It builds a fake stored thread with user and agent history, calls thread_rollback_response_from_stored_thread, and checks that the returned thread has expected metadata, status, and populated turn items.

Call relations: It directly exercises thread_rollback_response_from_stored_thread, covering the helper used after a real rollback completes.

Call graph: calls 3 internal fn (thread_rollback_response_from_stored_thread, read_only, from_string); 4 external calls (now, assert_eq!, test_path_buf, vec!).

fn turn_complete_event(turn_id: &str) -> TurnCompleteEvent

Purpose: This test helper builds a standard TurnCompleteEvent with fixed timing. Fixed values make assertions simple and repeatable.

Data flow: It receives a turn id and returns a TurnCompleteEvent with that id plus predefined completed_at and duration values. It does not touch shared state.

Call relations: Several turn-completion tests use it when calling handle_turn_complete.

fn turn_aborted_event(turn_id: &str) -> TurnAbortedEvent

Purpose: This test helper builds a standard interrupted TurnAbortedEvent. It keeps interruption tests focused on handler behavior rather than event setup.

Data flow: It receives a turn id and returns a TurnAbortedEvent with an Interrupted reason and fixed completion timing. The output is passed into handle_turn_interrupted.

Call relations: The interrupted-turn test uses it to simulate core reporting an aborted turn.

fn command_execution_completion_item(command: &str) -> CommandExecutionCompletionItem

Purpose: This test helper builds command details used by command-start and command-completion tests.

Data flow: It receives a command string, creates a test working directory, and returns a CommandExecutionCompletionItem with one parsed-command entry. The result is used as input to command item helpers.

Call relations: Command execution notification tests call it before invoking start_command_execution_item and complete_command_execution_item.

Call graph: 2 external calls (test_path_buf, vec!).

fn guardian_command_assessment(
        id: &str,
        turn_id: &str,
        status: GuardianAssessmentStatus,
    ) -> GuardianAssessmentEvent

Purpose: This test helper builds a guardian assessment event for a command. Guardian assessment is an automatic safety review before a risky action.

Data flow: It receives an item id, turn id, and guardian status. It fills in risk details appropriate to the status, creates a command action JSON payload, and returns a GuardianAssessmentEvent.

Call relations: The guardian lifecycle test uses it to feed apply_bespoke_event_handling realistic guardian events.

Call graph: 4 external calls (format!, json!, matches!, from_value).

async fn apply_guardian_assessment_event(&self, assessment: GuardianAssessmentEvent)

Purpose: This test helper applies one guardian assessment event using a prepared test context. It avoids repeating the long argument list for the main dispatcher.

Data flow: It receives a guardian assessment, builds a core Event from it, and calls apply_bespoke_event_handling with the context’s thread, manager, outgoing sender, state, and watch manager. Any emitted messages go to the test channel.

Call relations: guardian_command_execution_notifications_wrap_review_lifecycle calls it repeatedly to simulate a full guardian review sequence.

Call graph: calls 1 internal fn (apply_bespoke_event_handling); 5 external calls (new, clone, clone, GuardianAssessment, new).

fn guardian_assessment_started_uses_event_turn_id_fallback()

Purpose: This test checks that a guardian assessment with an empty turn id still produces a started notification using the surrounding event’s turn id.

Data flow: It builds a guardian assessment with no assessment turn id, calls the notification builder, and asserts that the notification uses the fallback turn id and contains the expected review details.

Call relations: It validates behavior relied on by apply_bespoke_event_handling when guardian assessment data is incomplete.

Call graph: calls 1 internal fn (new); 5 external calls (new, assert_eq!, guardian_auto_approval_review_notification, test_path_buf, panic!).

fn guardian_assessment_completed_emits_review_payload()

Purpose: This test checks the completed guardian review notification for a denied command assessment.

Data flow: It builds a completed guardian assessment with risk, authorization, rationale, and action details, then asserts that the generated notification preserves those fields in client-facing form.

Call relations: It exercises the external guardian_auto_approval_review_notification used by apply_bespoke_event_handling.

Call graph: calls 1 internal fn (new); 4 external calls (assert_eq!, guardian_auto_approval_review_notification, test_path_buf, panic!).

fn guardian_assessment_aborted_emits_completed_review_payload()

Purpose: This test checks that an aborted guardian assessment is reported as a completed review with aborted status.

Data flow: It creates a network-access guardian assessment marked aborted, generates the client notification, and verifies ids, status, decision source, and action data.

Call relations: It covers a guardian outcome that apply_bespoke_event_handling forwards to clients.

Call graph: calls 1 internal fn (new); 3 external calls (assert_eq!, guardian_auto_approval_review_notification, panic!).

async fn command_execution_started_helper_emits_once() -> Result<()>

Purpose: This test proves start_command_execution_item sends a command-start notification only the first time for an item id.

Data flow: It creates test state and an outgoing channel, starts the same command twice, reads the first emitted ItemStarted message, and confirms the second call emits nothing.

Call relations: It directly tests the duplicate-suppression behavior used by approval and guardian event handling.

Call graph: calls 5 internal fn (disabled, start_command_execution_item, new, new, new); 9 external calls (new, command_execution_completion_item, new_thread_state, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!).

async fn complete_command_execution_item_emits_declined_once_for_pending_command() -> Result<()>

Purpose: This test proves a pending command completion is emitted once and then cleared.

Data flow: It starts a command item, consumes the start notification, completes it as declined, checks the completion notification, then tries to complete it again and confirms no extra message appears.

Call relations: It directly tests complete_command_execution_item, which is used when approvals or guardian checks stop a command before normal execution.

Call graph: calls 6 internal fn (disabled, complete_command_execution_item, start_command_execution_item, new, new, new); 9 external calls (new, command_execution_completion_item, new_thread_state, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!).

async fn guardian_command_execution_notifications_wrap_review_lifecycle() -> Result<()>

Purpose: This integration-style test checks that guardian command reviews produce the right visible command and review notifications.

Data flow: It creates a test Codex thread and outgoing channel, sends guardian assessments for approved, denied, and missing-target cases, then reads emitted messages in order. It verifies when command items start, when review notifications start or complete, and when denied commands are completed as declined.

Call relations: It drives apply_bespoke_event_handling through GuardianAssessmentTestContext::apply_guardian_assessment_event and indirectly covers start_command_execution_item and complete_command_execution_item.

Call graph: calls 7 internal fn (disabled, new, new, new, thread_manager_with_models_provider_and_home, default_for_tests, create_dummy_chatgpt_auth_for_testing); 11 external calls (new, new, guardian_command_assessment, new_thread_state, recv_broadcast_message, assert!, assert_eq!, bail!, load_default_config_for_test, channel (+1 more)).

fn file_change_accept_for_session_maps_to_approved_for_session()

Purpose: This test confirms that accepting file changes for the whole session maps to the matching core decision.

Data flow: It passes AcceptForSession into map_file_change_approval_decision and checks that the result is ApprovedForSession.

Call relations: It directly tests the mapping used by on_file_change_request_approval_response.

Call graph: calls 1 internal fn (map_file_change_approval_decision); 1 external calls (assert_eq!).

fn mcp_server_elicitation_turn_transition_error_maps_to_cancel()

Purpose: This test checks that a client request ended because the turn changed is treated as cancellation for MCP elicitation.

Data flow: It creates a JSON-RPC-style error marked as a turn transition, passes it to mcp_server_elicitation_response_from_client_result, and asserts that the result is Cancel with no content.

Call relations: It directly covers the helper used by on_mcp_server_elicitation_response.

Call graph: calls 1 internal fn (mcp_server_elicitation_response_from_client_result); 2 external calls (assert_eq!, json!).

fn request_permissions_turn_transition_error_is_ignored()

Purpose: This test checks that permission responses ended by a turn transition are ignored rather than converted into denial.

Data flow: It builds a turn-transition client error, passes it to request_permissions_response_from_client_result, and expects None. None means no response should be submitted back to core.

Call relations: It verifies the early-return behavior used by on_request_permissions_response.

Call graph: calls 1 internal fn (request_permissions_response_from_client_result); 4 external calls (default, assert_eq!, json!, current_dir).

fn request_permissions_response_accepts_partial_network_and_file_system_grants()

Purpose: This test confirms that clients may grant only part of the permissions core requested, and that extra unrequested grants are ignored.

Data flow: It defines requested network and filesystem permissions, then tries several client responses. For each, it calls request_permissions_response_from_client_result and checks that the returned permissions are exactly the safe intersection of requested and granted permissions.

Call relations: It directly tests the safety rule enforced before on_request_permissions_response submits permissions to core.

Call graph: calls 1 internal fn (request_permissions_response_from_client_result); 6 external calls (from_read_write_roots, assert_eq!, cfg!, json!, current_dir, vec!).

fn request_permissions_response_preserves_session_scope()

Purpose: This test confirms that a client can grant permissions for the session scope when strict auto-review is not requested.

Data flow: It passes a response with session scope and empty permissions into request_permissions_response_from_client_result. It checks that the returned core response keeps Session scope.

Call relations: It covers one allowed scope path in the permission conversion helper.

Call graph: calls 1 internal fn (request_permissions_response_from_client_result); 4 external calls (default, assert_eq!, json!, current_dir).

fn request_permissions_response_rejects_session_scoped_strict_auto_review()

Purpose: This test confirms that strict auto-review cannot be granted for an entire session.

Data flow: It passes a client response asking for session scope and strictAutoReview. The conversion helper logs the invalid combination and returns an empty, turn-scoped, non-strict response.

Call relations: It protects the rule inside request_permissions_response_from_client_result that strict auto-review is only supported for a single turn.

Call graph: calls 1 internal fn (request_permissions_response_from_client_result); 4 external calls (default, assert_eq!, json!, current_dir).

fn request_permissions_response_preserves_turn_scoped_strict_auto_review()

Purpose: This test confirms that strict auto-review is preserved when it is only turn-scoped.

Data flow: It requests network permission, passes a client response granting network with strictAutoReview, and checks that the returned response remains turn-scoped and strict.

Call relations: It covers the valid strict-auto-review path in request_permissions_response_from_client_result.

Call graph: calls 1 internal fn (request_permissions_response_from_client_result); 5 external calls (default, assert!, assert_eq!, json!, current_dir).

fn request_permissions_response_accepts_explicit_child_grant_for_requested_cwd_scope()

Purpose: This test confirms that a client may grant a specific child path when core requested write access under the current project root.

Data flow: It creates a temporary working directory and child path, requests project-root write access, grants the child path, and checks that the converted permissions include that child path.

Call relations: It verifies path localization and safe intersection inside request_permissions_response_from_client_result.

Call graph: calls 2 internal fn (request_permissions_response_from_client_result, from_absolute_path); 5 external calls (default, new, assert_eq!, json!, vec!).

fn request_permissions_response_rejects_child_grant_outside_requested_cwd_scope()

Purpose: This test confirms that a granted path outside the requested working-directory scope is ignored.

Data flow: It creates separate request and later working directories, requests write access relative to the request directory, grants a child of the later directory, and expects no permissions to be returned.

Call relations: It protects request_permissions_response_from_client_result from accidentally using a changed working directory to broaden access.

Call graph: calls 2 internal fn (request_permissions_response_from_client_result, from_absolute_path); 5 external calls (default, new, assert_eq!, json!, vec!).

fn request_permissions_response_ignores_broader_cwd_grant_for_requested_child_path()

Purpose: This test confirms that a broader project-root grant is ignored when core only requested a specific child path.

Data flow: It requests write access to one child path, then provides a client response granting the whole project root. The helper returns no permission because the grant is broader than the request.

Call relations: It verifies the “never grant more than requested” rule in request_permissions_response_from_client_result.

Call graph: calls 2 internal fn (request_permissions_response_from_client_result, from_absolute_path); 6 external calls (from_read_write_roots, default, new, assert_eq!, json!, vec!).

async fn test_handle_error_records_message() -> Result<()>

Purpose: This test confirms that handle_error stores the error in the turn summary.

Data flow: It creates thread state, records a TurnError, removes the turn summary, and checks that the stored error matches the original message and error info.

Call relations: It directly tests handle_error and find_and_remove_turn_summary.

Call graph: calls 3 internal fn (find_and_remove_turn_summary, handle_error, new); 2 external calls (new_thread_state, assert_eq!).

async fn turn_started_omits_active_snapshot_items() -> Result<()>

Purpose: This test checks that a TurnStarted notification does not include already tracked active-turn items. The client should load items separately rather than receive stale duplicates.

Data flow: It preloads thread state with a turn and a user message, then sends a TurnStarted event through apply_bespoke_event_handling. It reads the notification and asserts that items are empty and marked NotLoaded.

Call relations: It exercises the TurnStarted branch of apply_bespoke_event_handling.

Call graph: calls 8 internal fn (disabled, apply_bespoke_event_handling, new, new, new, thread_manager_with_models_provider_and_home, default_for_tests, create_dummy_chatgpt_auth_for_testing); 15 external calls (new, default, new, new, new_thread_state, recv_broadcast_message, assert!, assert_eq!, bail!, load_default_config_for_test (+5 more)).

async fn interrupted_subagent_activity_removes_missing_thread_watch() -> Result<()>

Purpose: This test checks that an interrupted sub-agent whose thread no longer exists is removed from the thread watch manager.

Data flow: It creates a watched child thread id without an actual thread, sends a SubAgentActivity interrupted event through apply_bespoke_event_handling, and checks that the running count drops and the expected item completion notification is emitted.

Call relations: It exercises the SubAgentActivity branch of apply_bespoke_event_handling and its cleanup of missing child threads.

Call graph: calls 10 internal fn (disabled, apply_bespoke_event_handling, new, new, new, thread_manager_with_models_provider_and_home, default_for_tests, create_dummy_chatgpt_auth_for_testing, try_from, new); 11 external calls (new, new, new_thread_state, recv_broadcast_message, assert_eq!, bail!, load_default_config_for_test, channel, SubAgentActivity, new (+1 more)).

async fn test_handle_turn_complete_emits_completed_without_error() -> Result<()>

Purpose: This test confirms that a turn with no recorded error finishes as Completed.

Data flow: It prepares thread state with a started turn, calls handle_turn_complete, receives the TurnCompleted notification, and checks status, timing, empty items, and no error.

Call relations: It directly tests handle_turn_complete and the shared emit_turn_completed_with_status path.

Call graph: calls 5 internal fn (disabled, handle_turn_complete, new, new, new); 12 external calls (new, default, new_thread_state, recv_broadcast_message, turn_complete_event, assert!, assert_eq!, bail!, channel, TurnComplete (+2 more)).

async fn test_handle_turn_interrupted_emits_interrupted_with_error() -> Result<()>

Purpose: This test confirms that interrupted turns are reported as Interrupted even if an error was previously recorded.

Data flow: It records an error in thread state, calls handle_turn_interrupted, reads the final notification, and checks that status is Interrupted and error is omitted.

Call relations: It directly tests handle_turn_interrupted and shows how it differs from normal completion.

Call graph: calls 6 internal fn (disabled, handle_error, handle_turn_interrupted, new, new, new); 9 external calls (new, new_thread_state, recv_broadcast_message, turn_aborted_event, assert!, assert_eq!, bail!, channel, vec!).

async fn test_handle_turn_complete_emits_failed_with_error() -> Result<()>

Purpose: This test confirms that a completed turn with a recorded error is reported as Failed.

Data flow: It stores a TurnError in thread state, calls handle_turn_complete, receives the final notification, and checks that the status and error fields match the failure.

Call relations: It tests the error-aware branch of handle_turn_complete.

Call graph: calls 6 internal fn (disabled, handle_error, handle_turn_complete, new, new, new); 9 external calls (new, new_thread_state, recv_broadcast_message, turn_complete_event, assert!, assert_eq!, bail!, channel, vec!).

async fn test_handle_turn_plan_update_emits_notification_for_v2() -> Result<()>

Purpose: This test checks that plan updates are converted into v2 client notifications with the right step statuses.

Data flow: It builds an update with two plan steps, calls handle_turn_plan_update, receives the notification, and asserts thread id, turn id, explanation, step text, and statuses.

Call relations: It directly tests the helper used by apply_bespoke_event_handling for PlanUpdate events.

Call graph: calls 5 internal fn (disabled, handle_turn_plan_update, new, new, new); 7 external calls (new, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!).

async fn test_handle_token_count_event_emits_usage_and_rate_limits() -> Result<()>

Purpose: This test checks that token usage and rate-limit snapshots both produce notifications.

Data flow: It builds token usage and rate-limit data, calls handle_token_count_event, receives two notifications, and checks important usage and limit fields.

Call relations: It directly tests the helper used by apply_bespoke_event_handling for TokenCount events.

Call graph: calls 5 internal fn (disabled, handle_token_count_event, new, new, new); 7 external calls (new, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!).

async fn test_handle_token_count_event_without_usage_info() -> Result<()>

Purpose: This test confirms that no notification is emitted when a token-count event contains neither usage nor rate-limit data.

Data flow: It calls handle_token_count_event with both optional fields absent, then checks the outgoing channel is empty.

Call relations: It covers the no-op branch of handle_token_count_event.

Call graph: calls 5 internal fn (disabled, handle_token_count_event, new, new, new); 4 external calls (new, assert!, channel, vec!).

async fn test_handle_turn_complete_emits_error_multiple_turns() -> Result<()>

Purpose: This test checks that turn summary errors are cleared after each completed turn, so one turn’s error does not leak into the next.

Data flow: It records errors and completes multiple turns, then reads each final notification. The first two turns fail with their own errors, while the later turn completes successfully with no stale error.

Call relations: It exercises handle_error, handle_turn_complete, and find_and_remove_turn_summary across repeated turns.

Call graph: calls 6 internal fn (disabled, handle_error, handle_turn_complete, new, new, new); 9 external calls (new, new_thread_state, recv_broadcast_message, turn_complete_event, assert!, assert_eq!, bail!, channel, vec!).

async fn test_handle_turn_diff_emits_v2_notification() -> Result<()>

Purpose: This test checks that a core diff event becomes the correct v2 TurnDiffUpdated notification.

Data flow: It calls handle_turn_diff with a sample unified diff, receives the outgoing notification, and verifies thread id, turn id, and diff text.

Call relations: It directly tests handle_turn_diff, the helper used by apply_bespoke_event_handling.

Call graph: calls 5 internal fn (disabled, handle_turn_diff, new, new, new); 7 external calls (new, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!).

async fn test_hook_prompt_raw_response_emits_item_completed() -> Result<()>

Purpose: This test checks that hook prompt messages hidden inside raw response items are surfaced as completed HookPrompt items.

Data flow: It builds a hook prompt response item with two fragments, calls maybe_emit_hook_prompt_item_completed, receives the ItemCompleted notification, and verifies the fragments and hook run ids.

Call relations: It directly tests the hook-prompt detection path used before raw response items are forwarded.

Call graph: calls 6 internal fn (disabled, maybe_emit_hook_prompt_item_completed, new, new, build_hook_prompt_message, new); 8 external calls (new, from_single_hook, recv_broadcast_message, assert!, assert_eq!, bail!, channel, vec!).

fn new(
        manager: ThreadWatchManager,
        thread_id: String,
        guard_type: ThreadWatchActiveGuardType,
    ) -> Self

Purpose: Creates a guard object that represents one active wait, such as waiting for approval or user input. The guard remembers which thread it belongs to so the wait can be cleared later.

Data flow: It receives a manager, a thread id, and the kind of wait. It records those values and also captures the current async runtime handle, then returns a guard ready to be held by the caller.

Call relations: It is called by ThreadWatchManager::note_pending_request after that method has marked a thread as waiting. The returned guard becomes the token whose lifetime controls when the waiting state ends.

Call graph: called by 1 (note_pending_request); 1 external calls (current).

fn drop(&mut self)

Purpose: Automatically clears one pending wait when the guard goes out of scope. This is a cleanup safety net, like returning a library checkout card when you are done.

Data flow: When the guard is destroyed, it copies the manager, thread id, and wait type. It then spawns an async task that tells the manager to reduce the matching pending counter.

Call relations: This is triggered by Rust’s automatic drop behavior rather than by a normal direct call. It hands work to ThreadWatchManager::note_active_guard_released so status updates still happen through the manager.

Call graph: 2 external calls (spawn, clone).

fn default() -> Self

Purpose: Provides the standard empty manager when code asks for a default value. It is a convenience wrapper around normal construction.

Data flow: It takes no input, calls the regular constructor, and returns a manager with empty thread state and no outgoing notification sender.

Call relations: It delegates to ThreadWatchManager::new, keeping the default setup identical to explicit construction.

Call graph: 1 external calls (new).

fn new() -> Self

Purpose: Creates a thread status manager for code that only needs in-memory tracking and subscriptions. It does not send outgoing client notifications.

Data flow: It starts with no thread records, creates a shared locked state store, creates a watch channel for the running-turn count with initial value zero, and returns the manager.

Call relations: It is used by tests and by server setup paths that need a fresh status tracker. Later calls such as upsert_thread, note_turn_started, and subscribe_running_turn_count use the state created here.

Call graph: called by 11 (guardian_command_execution_notifications_wrap_review_lifecycle, interrupted_subagent_activity_removes_missing_thread_watch, turn_started_omits_active_snapshot_items, has_running_turns_tracks_runtime_running_flag_only, loaded_status_defaults_to_not_loaded_for_untracked_threads, loaded_statuses_default_to_not_loaded_for_untracked_threads, shutdown_marks_thread_not_loaded, status_updates_track_single_thread, status_watchers_receive_only_their_thread_updates, system_error_sets_idle_flag_until_next_turn (+1 more)); 4 external calls (new, new, default, channel).

fn new_with_outgoing(outgoing: Arc<OutgoingMessageSender>) -> Self

Purpose: Creates a manager that can also broadcast thread status changes to connected clients. This is used when UI-facing notifications are needed.

Data flow: It receives an outgoing message sender, stores it, creates empty shared state, creates a running-turn-count watch channel set to zero, and returns the manager.

Call relations: It is called by setup and tests that verify notifications. Its outgoing sender is later used by mutate_and_publish whenever a status actually changes.

Call graph: called by 3 (new, silent_upsert_skips_initial_notification, status_change_emits_notification); 4 external calls (new, new, default, channel).

async fn upsert_thread(&self, thread: Thread)

Purpose: Marks a thread as known and loaded, creating it if needed or refreshing it if already present. It can emit a status-change notification.

Data flow: It receives a Thread, uses its id, updates the stored runtime facts to say the thread is loaded, recalculates status, and may publish a change.

Call relations: Thread resume and listener attachment flows call this when a thread becomes available. It performs the actual state change through mutate_and_publish.

Call graph: calls 1 internal fn (mutate_and_publish); called by 2 (thread_resume_inner, try_attach_thread_listener).

async fn upsert_thread_silently(&self, thread: Thread)

Purpose: Marks a thread as known and loaded without sending the initial notification. This is useful when the server is preparing internal state and does not want to announce a harmless setup step.

Data flow: It receives a Thread, stores or refreshes its loaded state, updates any local watchers, and suppresses the outgoing status notification for that upsert.

Call relations: Forking and detached review startup use this quiet version. It still goes through mutate_and_publish, but the state layer is told not to emit the initial notification.

Call graph: calls 1 internal fn (mutate_and_publish); called by 2 (thread_fork_inner, start_detached_review).

async fn remove_thread(&self, thread_id: &str)

Purpose: Forgets a thread and marks it as not loaded. This lets subscribers and clients know that the thread is no longer active in memory.

Data flow: It receives a thread id, removes that thread’s runtime facts, updates any watcher for that id to NotLoaded, and may publish a status-change notification.

Call relations: Teardown and unload paths call this when a thread is being removed. It uses mutate_and_publish so the running count and outgoing messages stay consistent.

Call graph: calls 1 internal fn (mutate_and_publish); called by 3 (apply_bespoke_event_handling, unload_thread_without_subscribers, finalize_thread_teardown).

async fn loaded_status_for_thread(&self, thread_id: &str) -> ThreadStatus

Purpose: Returns the current public status for one thread. Unknown threads are treated as NotLoaded.

Data flow: It receives a thread id, reads the locked state, asks the state for that thread’s loaded status, and returns a ThreadStatus value.

Call relations: Many response-building paths call this when they need to show one thread’s status. It reads state directly and does not publish anything.

Call graph: called by 11 (apply_bespoke_event_handling, handle_pending_thread_resume_request, read_thread_view, resume_running_thread, thread_fork_inner, thread_metadata_update_response_inner, thread_resume_inner, thread_turns_list_response_inner, thread_unarchive_response, start_detached_review (+1 more)).

async fn loaded_statuses_for_threads(
        &self,
        thread_ids: Vec<String>,
    ) -> HashMap<String, ThreadStatus>

Purpose: Returns statuses for several threads at once. This avoids repeated locking when building lists or search results.

Data flow: It receives a list of thread ids, locks the state once, looks up each id, substitutes NotLoaded for missing ones, and returns a map from id to status.

Call relations: Thread list and thread search responses call this when they need statuses for many results. It relies on ThreadWatchState::loaded_status_for_thread for each item.

Call graph: called by 2 (thread_list_response_inner, thread_search_response_inner).

async fn running_turn_count(&self) -> usize

Purpose: Test-only helper that counts how many threads currently have a running turn. It checks the raw running flag rather than broader active states.

Data flow: It reads all stored runtime records, counts the ones whose running flag is true, and returns that number.

Call relations: Tests use it to confirm that waiting for approval alone does not count as a running turn. Production code uses the watch subscription instead.

fn subscribe_running_turn_count(&self) -> watch::Receiver<usize>

Purpose: Lets other code listen for changes in the total number of running turns. This is useful for UI or coordination code that only cares whether work is currently underway.

Data flow: It takes no input, creates a new receiver attached to the existing watch channel, and returns that receiver to the caller.

Call relations: subscribe_running_assistant_turn_count calls this to expose the live count. The count is updated by mutate_and_publish after every relevant state change.

Call graph: called by 1 (subscribe_running_assistant_turn_count); 1 external calls (subscribe).

async fn note_turn_started(&self, thread_id: &str)

Purpose: Records that a thread has begun doing assistant work. It also clears any previous system error for that thread.

Data flow: It receives a thread id, marks that thread loaded and running, clears has_system_error, recalculates the status, and publishes changes.

Call relations: Event-handling code calls this when it observes a turn start. It delegates the actual edit to update_runtime_for_thread.

Call graph: calls 1 internal fn (update_runtime_for_thread); called by 1 (apply_bespoke_event_handling).

async fn note_turn_completed(&self, thread_id: &str, _failed: bool)

Purpose: Records that a thread’s turn finished. The current _failed argument is accepted but not used here.

Data flow: It receives a thread id, clears the running flag and any pending approval or user-input waits, then publishes the resulting status.

Call relations: Event-handling code calls this when a turn completes. It shares cleanup logic with interruptions through clear_active_state.

Call graph: calls 1 internal fn (clear_active_state); called by 1 (apply_bespoke_event_handling).

async fn note_turn_interrupted(&self, thread_id: &str)

Purpose: Records that a thread’s turn stopped before normal completion. For status purposes, it clears the same active markers as a completed turn.

Data flow: It receives a thread id, clears running and pending request counters, then publishes the updated status.

Call relations: Event-handling code calls this when a turn is interrupted. It delegates to clear_active_state, just like note_turn_completed.

Call graph: calls 1 internal fn (clear_active_state); called by 1 (apply_bespoke_event_handling).

async fn note_thread_shutdown(&self, thread_id: &str)

Purpose: Records that a thread runtime has shut down. This marks the thread as no longer loaded.

Data flow: It receives a thread id, clears running and pending waits, sets is_loaded to false, recalculates status as NotLoaded, and publishes changes.

Call relations: Event-handling code calls this when shutdown is observed. It changes the stored runtime through update_runtime_for_thread.

Call graph: calls 1 internal fn (update_runtime_for_thread); called by 1 (apply_bespoke_event_handling).

async fn note_system_error(&self, thread_id: &str)

Purpose: Records that a thread hit a system-level failure. The thread stops being active and is shown as being in error.

Data flow: It receives a thread id, clears running and pending waits, sets the system-error flag, recalculates status, and publishes changes.

Call relations: Event-handling code calls this when an error event arrives. A later note_turn_started clears the error flag for the next run.

Call graph: calls 1 internal fn (update_runtime_for_thread); called by 1 (apply_bespoke_event_handling).

async fn clear_active_state(&self, thread_id: &str)

Purpose: Shared helper that removes all active-turn markers from one thread. It is used when a turn finishes or is interrupted.

Data flow: It receives a thread id, clears the running flag and both pending request counters, then lets the manager recalculate and publish status.

Call relations: note_turn_completed and note_turn_interrupted both call this so they do not duplicate the same cleanup steps.

Call graph: calls 1 internal fn (update_runtime_for_thread); called by 2 (note_turn_completed, note_turn_interrupted).

async fn note_permission_requested(
        &self,
        thread_id: &str,
    ) -> ThreadWatchActiveGuard

Purpose: Records that a thread is waiting for approval. It returns a guard that keeps that waiting state alive until the request is finished.

Data flow: It receives a thread id, increases the pending permission count, updates status to include WaitingOnApproval, and returns a guard object.

Call relations: Event-handling code calls this when a permission request appears. It delegates to note_pending_request with the permission kind.

Call graph: calls 1 internal fn (note_pending_request); called by 1 (apply_bespoke_event_handling).

async fn note_user_input_requested(
        &self,
        thread_id: &str,
    ) -> ThreadWatchActiveGuard

Purpose: Records that a thread is waiting for the user to type or provide input. It returns a guard that clears the wait when dropped.

Data flow: It receives a thread id, increases the pending user-input count, updates status to include WaitingOnUserInput, and returns a guard object.

Call relations: Event-handling code calls this when a user-input request appears. It delegates to note_pending_request with the user-input kind.

Call graph: calls 1 internal fn (note_pending_request); called by 1 (apply_bespoke_event_handling).

async fn note_pending_request(
        &self,
        thread_id: &str,
        guard_type: ThreadWatchActiveGuardType,
    ) -> ThreadWatchActiveGuard

Purpose: Shared helper for marking a thread as waiting on either approval or user input. It also creates the lifetime guard for that wait.

Data flow: It receives a thread id and wait type, marks the thread loaded, increments the matching pending counter safely, publishes the new status, and returns a ThreadWatchActiveGuard.

Call relations: note_permission_requested and note_user_input_requested both call this. It calls update_runtime_for_thread for the state change, then ThreadWatchActiveGuard::new for the cleanup token.

Call graph: calls 2 internal fn (new, update_runtime_for_thread); called by 2 (note_permission_requested, note_user_input_requested).

async fn mutate_and_publish(&self, mutate: F)

Purpose: Applies one state change and then broadcasts any effects. This is the manager’s central “change state, then tell everyone” path.

Data flow: It receives a closure that edits ThreadWatchState. While holding the lock, it applies the edit and counts running turns; after releasing the lock, it updates the running-count watch channel and sends an outgoing notification if one was produced.

Call relations: upsert_thread, upsert_thread_silently, remove_thread, and update_runtime_for_thread all use this. It is where internal changes become external updates.

Call graph: called by 4 (remove_thread, update_runtime_for_thread, upsert_thread, upsert_thread_silently); 2 external calls (send, ThreadStatusChanged).

async fn subscribe(
        &self,
        thread_id: ThreadId,
    ) -> Option<watch::Receiver<ThreadStatus>>

Purpose: Lets a caller listen to status changes for one specific thread. The caller immediately has access to the current status and later receives changes.

Data flow: It receives a typed thread id, converts it to text, locks the state, creates or reuses that thread’s watch sender, and returns a receiver.

Call relations: Code that needs a live view of one thread calls this. The returned receiver is fed by ThreadWatchState::update_status_watcher whenever that thread changes.

Call graph: 1 external calls (to_string).

async fn note_active_guard_released(
        &self,
        thread_id: String,
        guard_type: ThreadWatchActiveGuardType,
    )

Purpose: Clears one pending approval or user-input wait after its guard is dropped. It prevents a thread from staying falsely marked as waiting.

Data flow: It receives a thread id and wait type, finds the matching counter, subtracts one without going below zero, recalculates status, and publishes any change.

Call relations: ThreadWatchActiveGuard::drop schedules this method. It uses update_runtime_for_thread so guard cleanup follows the same publish path as other updates.

Call graph: calls 1 internal fn (update_runtime_for_thread).

async fn update_runtime_for_thread(&self, thread_id: &str, update: F)

Purpose: Shared helper for changing the stored runtime facts for one thread. It ensures missing records are created and changes are published.

Data flow: It receives a thread id and an update function, converts the id to owned text, asks the state to apply the update, and then sends any resulting notifications through mutate_and_publish.

Call relations: Turn starts, shutdowns, errors, pending requests, guard releases, and active-state cleanup all call this. It is the bridge between high-level events and the raw state object.

Call graph: calls 1 internal fn (mutate_and_publish); called by 6 (clear_active_state, note_active_guard_released, note_pending_request, note_system_error, note_thread_shutdown, note_turn_started).

fn pending_counter(
        runtime: &mut RuntimeFacts,
        guard_type: ThreadWatchActiveGuardType,
    ) -> &mut u32

Purpose: Chooses which pending-request counter to edit based on the kind of wait. It keeps approval and user-input counts separate.

Data flow: It receives mutable runtime facts and a guard type. It returns a mutable reference to either the permission counter or the user-input counter.

Call relations: note_pending_request uses it to increment the right counter, and note_active_guard_released uses it to decrement the same kind of counter.

fn resolve_thread_status(
    status: ThreadStatus,
    has_in_progress_turn: bool,
) -> ThreadStatus

Purpose: Corrects a race where a real running turn may be known before the thread watcher has observed it. In that narrow case, it prefers showing Active over Idle or NotLoaded.

Data flow: It receives a status and a boolean saying whether a turn is in progress. If the boolean is true and the status looks inactive, it returns Active with no flags; otherwise it returns the original status.

Call relations: Tests call this directly. In the larger design, it is a small safety helper for code that combines watcher status with another source of “turn is running” truth.

Call graph: called by 1 (resolves_in_progress_turn_to_active_status); 2 external calls (new, matches!).

fn upsert_thread(
        &mut self,
        thread_id: String,
        emit_notification: bool,
    ) -> Option<ThreadStatusChangedNotification>

Purpose: Adds or refreshes one thread inside the raw state store. It marks the thread loaded and optionally prepares a change notification.

Data flow: It receives a thread id and a flag for whether to notify. It records the previous status, marks the runtime loaded, updates any watcher, and returns a notification only if requested and the status changed.

Call relations: ThreadWatchManager::upsert_thread and upsert_thread_silently reach this through mutate_and_publish. It calls status and watcher helpers to keep views current.

Call graph: calls 3 internal fn (status_changed_notification, status_for, update_status_watcher_for_thread).

fn remove_thread(&mut self, thread_id: &str) -> Option<ThreadStatusChangedNotification>

Purpose: Removes one thread from the raw state store and moves its public status to NotLoaded. It tells watchers even when the runtime record disappears.

Data flow: It receives a thread id, remembers its previous status, deletes its runtime facts, sends NotLoaded to that thread’s watcher, and returns a notification if there was a meaningful change.

Call relations: ThreadWatchManager::remove_thread reaches this through mutate_and_publish. It uses status_for and update_status_watcher to compare old and new visible state.

Call graph: calls 2 internal fn (status_for, update_status_watcher).

fn update_runtime(
        &mut self,
        thread_id: &str,
        mutate: F,
    ) -> Option<ThreadStatusChangedNotification>

Purpose: Applies a focused edit to one thread’s runtime facts and reports whether its public status changed. This is the core state update operation.

Data flow: It receives a thread id and a mutation function. It saves the old status, creates a runtime record if needed, marks it loaded, runs the mutation, updates watchers, and returns a notification if the status changed.

Call relations: ThreadWatchManager::update_runtime_for_thread calls this inside mutate_and_publish. It relies on status_changed_notification to decide whether clients need a message.

Call graph: calls 3 internal fn (status_changed_notification, status_for, update_status_watcher_for_thread).

fn status_for(&self, thread_id: &str) -> Option<ThreadStatus>

Purpose: Looks up the current status for a thread only if the thread has a runtime record. Missing threads return no status here.

Data flow: It receives a thread id, checks the runtime map, converts found runtime facts with loaded_thread_status, and returns either a status or None.

Call relations: Several state methods call this before and after changes. loaded_status_for_thread wraps it to provide the public default of NotLoaded.

Call graph: called by 5 (loaded_status_for_thread, remove_thread, status_changed_notification, update_runtime, upsert_thread).

fn loaded_status_for_thread(&self, thread_id: &str) -> ThreadStatus

Purpose: Returns a public status for one thread, using NotLoaded when the thread is unknown. This is the safe lookup used by callers.

Data flow: It receives a thread id, asks status_for for a stored status, and returns that status or ThreadStatus::NotLoaded.

Call relations: Manager status queries, subscriptions, and watcher updates rely on this behavior so missing threads are shown consistently.

Call graph: calls 1 internal fn (status_for); called by 2 (subscribe, update_status_watcher_for_thread).

fn subscribe(&mut self, thread_id: String) -> watch::Receiver<ThreadStatus>

Purpose: Creates or reuses a live status channel for one thread. A watch channel is like a shared latest-value feed that subscribers can wait on.

Data flow: It receives a thread id, computes the current status, creates a sender for that thread if none exists, and returns a receiver subscribed to it.

Call relations: ThreadWatchManager::subscribe calls this after locking state. Later update_status_watcher_for_thread sends changes to the receivers created here.

Call graph: calls 1 internal fn (loaded_status_for_thread).

fn update_status_watcher_for_thread(&mut self, thread_id: &str)

Purpose: Recomputes one thread’s current status and pushes it to that thread’s watchers. It is a convenience wrapper for watcher updates after state changes.

Data flow: It receives a thread id, gets the latest loaded status, and passes that status to update_status_watcher.

Call relations: upsert_thread and update_runtime call this after changing runtime facts. It keeps subscribers synchronized with the stored state.

Call graph: calls 2 internal fn (loaded_status_for_thread, update_status_watcher); called by 2 (update_runtime, upsert_thread).

fn update_status_watcher(&mut self, thread_id: &str, status: &ThreadStatus)

Purpose: Sends a new status to subscribers for one thread, but only if the value actually changed. It also cleans up unused watcher channels.

Data flow: It receives a thread id and status. If a watcher exists, it updates the current value only when different, then removes the sender if there are no receivers left.

Call relations: remove_thread calls it directly to send NotLoaded, and update_status_watcher_for_thread calls it after normal state updates.

Call graph: called by 2 (remove_thread, update_status_watcher_for_thread); 1 external calls (clone).

fn status_changed_notification(
        &self,
        thread_id: String,
        previous_status: Option<ThreadStatus>,
    ) -> Option<ThreadStatusChangedNotification>

Purpose: Builds an outgoing status-change notification when a thread’s visible status has changed. It avoids noisy duplicate messages.

Data flow: It receives a thread id and the previous status. It calculates the current status, compares old and new, and returns either no notification or a ThreadStatusChangedNotification.

Call relations: upsert_thread and update_runtime call this after changing state. mutate_and_publish later sends the notification if one is returned.

Call graph: calls 1 internal fn (status_for); called by 2 (update_runtime, upsert_thread).

fn loaded_thread_status(runtime: &RuntimeFacts) -> ThreadStatus

Purpose: Converts raw runtime facts into the public ThreadStatus shown to clients. It is the rulebook for status priority.

Data flow: It receives runtime facts. If the thread is not loaded, it returns NotLoaded; otherwise it builds active flags for pending waits, returns Active if running or waiting, returns SystemError if errored, and finally returns Idle.

Call relations: ThreadWatchState::status_for uses this whenever it needs to turn stored facts into a visible status.

Call graph: 1 external calls (new).

async fn loaded_status_defaults_to_not_loaded_for_untracked_threads()

Purpose: Checks that asking about an unknown thread returns NotLoaded. This protects the default behavior callers rely on.

Data flow: It creates a fresh manager, asks for the status of an id that was never inserted, and asserts that the result is NotLoaded.

Call relations: This test exercises ThreadWatchManager::new and loaded_status_for_thread in the simplest missing-thread case.

Call graph: calls 1 internal fn (new); 1 external calls (assert_eq!).

async fn tracks_non_interactive_thread_status()

Purpose: Checks that a non-interactive thread becomes active when a turn starts. The source of the thread should not stop basic running-state tracking.

Data flow: It creates a manager, inserts a test thread, marks a turn started, then reads the status and expects Active with no special waiting flags.

Call relations: This test uses ThreadWatchManager::new, upsert_thread, and note_turn_started to verify the normal active path.

Call graph: calls 1 internal fn (new); 2 external calls (test_thread, assert_eq!).

async fn status_updates_track_single_thread()

Purpose: Checks the full status journey for one interactive thread: active, waiting for approval, waiting for input, then idle. It also verifies guard-based cleanup.

Data flow: It creates a manager and thread, starts a turn, opens permission and user-input waits, drops each guard, waits for the status to update, then completes the turn and expects idle.

Call relations: This test drives note_permission_requested, note_user_input_requested, guard dropping, and note_turn_completed, with wait_for_status helping observe async cleanup.

Call graph: calls 1 internal fn (new); 4 external calls (test_thread, wait_for_status, assert_eq!, vec!).

fn resolves_in_progress_turn_to_active_status()

Purpose: Checks that resolve_thread_status upgrades inactive-looking statuses when another signal says a turn is in progress.

Data flow: It passes Idle and NotLoaded statuses with has_in_progress_turn set to true, then asserts both come back as Active.

Call relations: This test calls resolve_thread_status directly to protect the race-condition workaround.

Call graph: calls 1 internal fn (resolve_thread_status); 1 external calls (assert_eq!).

fn keeps_status_when_no_in_progress_turn()

Purpose: Checks that statuses are not changed when there is no in-progress turn signal. The helper should only intervene in the special race case.

Data flow: It passes statuses with has_in_progress_turn set to false and asserts the same statuses come back.

Call relations: This test complements tests::resolves_in_progress_turn_to_active_status by verifying the no-op path.

Call graph: 1 external calls (assert_eq!).

async fn system_error_sets_idle_flag_until_next_turn()

Purpose: Checks that a system error is shown after a failed runtime state, and that starting a new turn clears the error. This protects recovery behavior.

Data flow: It creates and loads a thread, starts a turn, records a system error, checks for SystemError, then starts another turn and expects Active.

Call relations: This test drives note_system_error and note_turn_started, confirming their ordering rules in loaded_thread_status.

Call graph: calls 1 internal fn (new); 2 external calls (test_thread, assert_eq!).

async fn shutdown_marks_thread_not_loaded()

Purpose: Checks that shutting down a thread makes it appear not loaded. This matters because clients should stop treating it as ready or active.

Data flow: It creates and loads a thread, starts a turn, records shutdown, then reads the status and expects NotLoaded.

Call relations: This test exercises note_thread_shutdown after normal setup through ThreadWatchManager::new and upsert_thread.

Call graph: calls 1 internal fn (new); 2 external calls (test_thread, assert_eq!).

async fn loaded_statuses_default_to_not_loaded_for_untracked_threads()

Purpose: Checks batch status lookup for a mix of known and unknown threads. Unknown items should still appear with NotLoaded.

Data flow: It creates one active thread, asks for statuses for that thread and another missing one, then asserts the returned map contains both expected statuses.

Call relations: This test exercises loaded_statuses_for_threads, which is used by list and search response paths.

Call graph: calls 1 internal fn (new); 3 external calls (test_thread, assert_eq!, vec!).

async fn has_running_turns_tracks_runtime_running_flag_only()

Purpose: Checks that the running-turn count only counts actual running turns, not pending permission waits. This keeps global “work is running” signals accurate.

Data flow: It creates a thread, checks count zero, adds a permission wait and still expects zero, starts a turn and expects one, then completes it and expects zero.

Call relations: This test uses the test-only running_turn_count helper to verify how note_permission_requested, note_turn_started, and note_turn_completed affect the running flag.

Call graph: calls 1 internal fn (new); 2 external calls (test_thread, assert_eq!).

async fn status_change_emits_notification()

Purpose: Checks that visible status changes are sent through the outgoing notification channel. This protects client-facing live updates.

Data flow: It creates a manager with an outgoing sender, inserts a thread, starts a turn, removes the thread, and after each step receives and compares the broadcast notification.

Call relations: This test exercises new_with_outgoing, upsert_thread, note_turn_started, remove_thread, and the helper recv_status_changed_notification.

Call graph: calls 3 internal fn (disabled, new, new_with_outgoing); 4 external calls (new, test_thread, assert_eq!, channel).

async fn silent_upsert_skips_initial_notification()

Purpose: Checks that silent insertion records a thread without broadcasting the initial idle status. Later real changes should still notify.

Data flow: It creates a notifying manager, silently upserts a thread, confirms no message arrives quickly, then starts a turn and confirms an active notification is sent.

Call relations: This test compares upsert_thread_silently with later note_turn_started, using the outgoing channel and recv_status_changed_notification.

Call graph: calls 3 internal fn (disabled, new, new_with_outgoing); 5 external calls (new, test_thread, assert!, assert_eq!, channel).

async fn status_watchers_receive_only_their_thread_updates()

Purpose: Checks that per-thread subscriptions only receive updates for the thread they subscribed to. This prevents unrelated UI panels from refreshing incorrectly.

Data flow: It creates two threads, subscribes to both, starts a turn on one, confirms that subscriber receives Active, and confirms the other subscriber receives no update and remains idle.

Call relations: This test exercises ThreadWatchManager::subscribe and the watcher update path inside the state object.

Call graph: calls 2 internal fn (new, from_string); 5 external calls (from_secs, test_thread, assert!, assert_eq!, timeout).

async fn wait_for_status(
        manager: &ThreadWatchManager,
        thread_id: &str,
        expected_status: ThreadStatus,
    )

Purpose: Test helper that waits until a thread reaches an expected status. It is useful because some cleanup happens asynchronously after a guard is dropped.

Data flow: It receives a manager, thread id, and expected status. It repeatedly reads the current status, yields to other tasks between checks, and fails the test if the expected value does not appear before the timeout.

Call relations: tests::status_updates_track_single_thread uses this after dropping guards, allowing the async drop cleanup task time to publish the new status.

Call graph: calls 1 internal fn (loaded_status_for_thread); 3 external calls (from_secs, yield_now, timeout).

async fn recv_status_changed_notification(
        outgoing_rx: &mut mpsc::Receiver<OutgoingEnvelope>,
    ) -> ThreadStatusChangedNotification

Purpose: Test helper that receives one outgoing thread-status notification and extracts its payload. It fails loudly if the wrong kind of message arrives.

Data flow: It receives a mutable outgoing-message receiver, waits with a timeout for one envelope, verifies it is a broadcast thread-status-changed message, and returns the notification inside.

Call relations: Notification tests call this after actions that should publish. It checks the result of mutate_and_publish sending through the outgoing channel.

Call graph: calls 1 internal fn (recv); 3 external calls (from_secs, panic!, timeout).

fn test_thread(thread_id: &str, source: codex_app_server_protocol::SessionSource) -> Thread

Purpose: Test helper that builds a minimal Thread value with predictable fields. It keeps the tests focused on status behavior instead of thread construction details.

Data flow: It receives a thread id and source, fills in required thread fields with simple test values, and returns a Thread starting with NotLoaded status.

Call relations: Most tests call this before upserting a thread into the manager. It supplies realistic enough data for status tracking without involving storage or real sessions.

Call graph: 3 external calls (new, new, test_path_buf).

fn format_location(item: &ReviewFinding) -> String

Purpose: This function turns a finding’s code location into a compact human-readable place marker, like a file path followed by a start and end line. Someone reading the review can use it to know exactly where the comment applies.

Data flow: It receives one review finding. It reads the finding’s absolute file path and its line range, then combines them into one string in the form path:start-end. It does not change the finding; it only returns the formatted location text.

Call relations: This is a small helper used by format_review_findings_block while building each review comment line. The larger formatter asks it for the location so the main review text can include both what the issue is and where it appears.

Call graph: called by 1 (format_review_findings_block); 1 external calls (format!).

fn format_review_findings_block(
    findings: &[ReviewFinding],
    selection: Option<&[bool]>,
) -> String

Purpose: This function builds the plain-text block that lists one or more review findings. It is used when the system needs to show review comments in a readable form, with optional checkbox markers for selected and unselected items.

Data flow: It receives a list of review findings and, optionally, a matching list of true-or-false selection values. It starts with a blank line and a header, choosing singular or plural wording depending on how many findings there are. For each finding, it asks format_location for the file-and-line text, writes a bullet line with the title and location, adds a checkbox marker if selections were provided, and then indents each line of the finding body underneath. It returns the whole block as one string joined with newline characters. If a selection list is shorter than the findings list, missing entries are treated as selected.

Call relations: render_review_output_text calls this when it needs to include findings inside a full review summary. exit_review_mode also calls it when leaving review mode and presenting or preserving the review comments. Inside its own work, it relies on format_location to keep location formatting consistent.

Call graph: calls 1 internal fn (format_location); called by 3 (render_review_output_text, render_review_output_text, exit_review_mode); 5 external calls (new, new, format!, iter, len).

fn render_review_output_text(output: &ReviewOutputEvent) -> String

Purpose: This function creates the final user-facing review message from a complete review output event. It decides whether to show the overall explanation, the findings, both, or a fallback message when the reviewer returned nothing useful.

Data flow: It receives a review output event. It trims the overall explanation and keeps it only if it has visible text. If there are findings, it passes them to format_review_findings_block without checkbox selections, trims that result, and keeps it if it is not empty. If it collected any sections, it joins them with a blank line between them. If it collected none, it returns the fallback failure message.

Call relations: This is the higher-level formatter used when review output is ready to become text. exit_review_mode calls it as part of presenting the final review result, and review_op_emits_lifecycle_and_review_output calls it in test coverage for the review operation flow. When findings need detailed formatting, it hands that work to format_review_findings_block.

Call graph: calls 1 internal fn (format_review_findings_block); called by 2 (exit_review_mode, review_op_emits_lifecycle_and_review_output); 1 external calls (new).

fn item_event_to_server_notification(
    msg: EventMsg,
    thread_id: &str,
    turn_id: &str,
) -> ServerNotification

Purpose: Turns one core Codex event into one app-server notification for clients. This is used when the server already knows the surrounding context, such as the thread and turn, and only needs the direct event-to-notification translation.

Data flow: It receives a core event message, a thread ID, and a turn ID. It copies the IDs into owned strings, inspects which kind of event arrived, and builds the matching notification payload. For example, command output bytes become readable text, patch changes are converted into the v2 patch shape, and collaborative-agent statuses are converted into completed or failed tool-call states. The result is a ServerNotification; the function does not keep state or update outside data.

Call relations: This function is the central translator in the file. For command execution and patch events, it hands off the detailed conversion to helper builders such as build_command_execution_begin_item, build_command_execution_end_item, and convert_patch_changes. The tests call it with sample resume-agent and command-output events, then compare the returned notification against the expected client-facing shape.

Call graph: calls 4 internal fn (build_command_execution_begin_item, build_command_execution_end_item, convert_patch_changes, from); called by 3 (collab_resume_begin_maps_to_item_started_resume_agent, collab_resume_end_maps_to_item_completed_resume_agent, exec_command_output_delta_maps_to_command_execution_output_delta); 17 external calls (new, AgentMessageDelta, CommandExecutionOutputDelta, FileChangePatchUpdated, ItemCompleted, ItemStarted, PlanDelta, ReasoningSummaryPartAdded, ReasoningSummaryTextDelta, ReasoningTextDelta (+7 more)).

fn assert_item_started_server_notification(
        notification: ServerNotification,
        expected: ItemStartedNotification,
    )

Purpose: Checks that a returned server notification is specifically an “item started” notification and that its contents are exactly what the test expected. It gives tests a clearer failure message than a raw comparison would.

Data flow: It receives an actual notification and an expected ItemStartedNotification. If the actual notification is the right variant, it compares the inner data. If it is any other kind of notification, it stops the test with a message explaining what was received instead.

Call relations: The resume-begin test uses this helper after calling item_event_to_server_notification. It keeps the test focused on the behavior being checked instead of repeating the same match-and-compare code.

Call graph: 2 external calls (assert_eq!, panic!).

fn assert_item_completed_server_notification(
        notification: ServerNotification,
        expected: ItemCompletedNotification,
    )

Purpose: Checks that a returned server notification is specifically an “item completed” notification and that its contents match the expected value. It is a small test helper for completed timeline items.

Data flow: It takes the actual notification and the expected completed-item payload. If the notification contains a completed item, it compares that payload. If the notification is a different kind, it fails the test and reports the unexpected value.

Call relations: The resume-end test uses this helper after exercising item_event_to_server_notification. This makes the test read like a short story: build an event, translate it, then assert that the completed item looks right.

Call graph: 2 external calls (assert_eq!, panic!).

fn assert_command_execution_output_delta_server_notification(
        notification: ServerNotification,
        expected: CommandExecutionOutputDeltaNotification,
    )

Purpose: Checks that a returned notification is a command-output text update and that the update matches what the test expected. This is useful for verifying streaming command output, where bytes from a process become text sent to the client.

Data flow: It receives an actual notification and the expected command-output delta payload. If the notification is the command-output-delta variant, it compares the payload. Otherwise, it fails the test and names the unexpected notification.

Call relations: The command-output test uses this helper after calling item_event_to_server_notification. It confirms that command output is translated into the specific notification type clients listen for.

Call graph: 2 external calls (assert_eq!, panic!).

fn collab_resume_begin_maps_to_item_started_resume_agent()

Purpose: Verifies that a collaborative-agent resume start event becomes an “item started” notification for the ResumeAgent tool. This protects the client timeline from showing the wrong kind of tool action when an agent is being resumed.

Data flow: The test creates a sample resume-begin event with a call ID, start time, sender thread, and receiver thread. It sends that event through item_event_to_server_notification, then builds the exact notification it expects: an in-progress collaborative tool call with the resume tool selected. The assertion confirms the actual output matches that expected shape.

Call relations: This test drives the main mapper directly. It then uses tests::assert_item_started_server_notification to check that the mapper chose the correct notification variant and filled in the collaborative-agent fields correctly.

Call graph: calls 2 internal fn (item_event_to_server_notification, new); 4 external calls (new, assert_item_started_server_notification, CollabResumeBegin, vec!).

fn collab_resume_end_maps_to_item_completed_resume_agent()

Purpose: Verifies that a collaborative-agent resume end event becomes an “item completed” notification, and that a missing agent is reported as a failed resume. This matters because clients need to show a failed tool call when the target agent cannot be found.

Data flow: The test creates a resume-end event whose status is NotFound. It translates that event with item_event_to_server_notification. It then expects a completed collaborative tool-call item whose status is failed, whose receiver thread is recorded, and whose agent state records the not-found outcome. The assertion confirms all of those fields are preserved and converted correctly.

Call relations: This test exercises the failure branch of the main mapper’s resume-end logic. It relies on CollabAgentState::from through the mapper’s conversion path, then uses tests::assert_item_completed_server_notification to verify the final client-facing notification.

Call graph: calls 3 internal fn (item_event_to_server_notification, from, new); 3 external calls (assert_item_completed_server_notification, CollabResumeEnd, vec!).

fn exec_command_output_delta_maps_to_command_execution_output_delta()

Purpose: Verifies that a chunk of command output becomes a command-output-delta notification with readable text. This protects the live terminal-style output clients receive while a command is running.

Data flow: The test creates a command-output event containing the bytes for hello. It passes the event through item_event_to_server_notification. The expected result is a notification tied to the same call ID, thread, and turn, with the byte chunk converted into the string hello.

Call relations: This test calls the main mapper for the command-output streaming case. It then uses tests::assert_command_execution_output_delta_server_notification to confirm the mapper produced the notification type that clients use for incremental command output.

Call graph: calls 1 internal fn (item_event_to_server_notification); 2 external calls (assert_command_execution_output_delta_server_notification, ExecCommandOutputDelta).

fn build_file_change_approval_request_item(
    payload: &ApplyPatchApprovalRequestEvent,
) -> ThreadItem

Purpose: Creates a thread item for a patch that is asking for approval before it is applied. This lets the client show the proposed file changes as an in-progress file-change item.

Data flow: It receives an apply-patch approval event containing a call ID and a set of file changes. It copies the call ID, converts the raw patch changes into display-friendly file update records, marks the status as in progress, and returns a ThreadItem::FileChange.

Call relations: When the approval-request handler sees that a patch needs permission, it calls this builder to create the visible thread item. The builder delegates the file-change conversion to convert_patch_changes so patch display is consistent with other patch paths.

Call graph: calls 1 internal fn (convert_patch_changes); called by 1 (handle_apply_patch_approval_request).

fn build_file_change_begin_item(payload: &PatchApplyBeginEvent) -> ThreadItem

Purpose: Creates a thread item when a patch application starts. It gives clients an immediate visible record that file changes are underway.

Data flow: It receives a patch-begin event with a call ID and file-change map. It converts those changes into client-facing records, sets the status to in progress, and returns a ThreadItem::FileChange with that information.

Call relations: The patch-begin handler calls this when patch work starts. Like the approval and completion builders, it sends the raw patch map through convert_patch_changes so all file-change items have the same shape.

Call graph: calls 1 internal fn (convert_patch_changes); called by 1 (handle_patch_apply_begin).

fn build_file_change_end_item(payload: &PatchApplyEndEvent) -> ThreadItem

Purpose: Creates a final thread item for a patch after it has finished. This records the same file changes together with the final success or failure status.

Data flow: It receives a patch-end event containing the call ID, the changed files, and the core patch status. It converts the files for display, translates the status into the app-server status type, and returns a completed ThreadItem::FileChange.

Call relations: The patch-end handler calls this after patch application finishes. It relies on convert_patch_changes for the visible file list, while the final status comes from the patch event itself.

Call graph: calls 1 internal fn (convert_patch_changes); called by 1 (handle_patch_apply_end).

fn build_command_execution_approval_request_item(
    payload: &ExecApprovalRequestEvent,
) -> ThreadItem

Purpose: Creates a command-execution thread item for a command that is asking for approval before it runs. It lets the UI show what command is being considered, even though no process has started yet.

Data flow: It receives a command approval request with the command arguments, working directory, call ID, and parsed command details. It turns the argument list into a readable command string, converts parsed command information into app-server command actions, marks the item as in progress, and leaves runtime fields like process ID, output, exit code, and duration empty.

Call relations: This builder is used for the pre-execution approval path. It uses shlex_join to make the command readable as a shell-style string, then packages the command as a ThreadItem::CommandExecution for clients.

Call graph: calls 1 internal fn (shlex_join).

fn build_command_execution_begin_item(payload: &ExecCommandBeginEvent) -> ThreadItem

Purpose: Creates a command-execution thread item when a command actually starts running. It includes the process ID and source so the client can show a live command in progress.

Data flow: It receives a command-begin event with command arguments, working directory, process ID, source, and parsed command details. It joins the arguments into a readable command string, converts parsed command details into display actions, marks the command as in progress, and returns a ThreadItem::CommandExecution without final output or exit information yet.

Call relations: This is called both by live command-begin handling and by code that turns item events into server notifications. It prepares the first visible command item, while later completion handling can replace or update it with final details.

Call graph: calls 1 internal fn (shlex_join); called by 2 (item_event_to_server_notification, handle_exec_command_begin).

fn build_command_execution_end_item(payload: &ExecCommandEndEvent) -> ThreadItem

Purpose: Creates a final command-execution thread item after a command finishes. It records what ran, what it produced, how it ended, and how long it took.

Data flow: It receives a command-end event with the command, working directory, process ID, final status, output, exit code, duration, and parsed command details. It joins the command arguments into a readable string, omits aggregated output if it is empty, converts the duration to milliseconds with a safe maximum if it is too large, translates the status, and returns a completed ThreadItem::CommandExecution.

Call relations: This is called by command-end handling and by the item-event-to-notification path. It is the counterpart to build_command_execution_begin_item: the begin builder shows the running command, and this builder produces the final version with outcome details.

Call graph: calls 1 internal fn (shlex_join); called by 2 (item_event_to_server_notification, handle_exec_command_end); 1 external calls (try_from).

fn build_item_from_guardian_event(
    assessment: &GuardianAssessmentEvent,
    status: CommandExecutionStatus,
) -> Option<ThreadItem>

Purpose: Builds a command-execution thread item from a guardian assessment when the guardian is reviewing a command-like action. The guardian is a safety review layer, and this function lets its review target appear as a normal command item in the thread.

Data flow: It receives a guardian assessment and the command status that should be shown. If the assessment is for a shell command, it uses the target item ID, command text, and working directory to create an in-progress-style command item. If it is for an execve action, meaning a direct program launch with arguments, it rebuilds a readable command line, tries to parse it into known command actions, and falls back to an unknown action if parsing finds nothing. For non-command guardian actions, it returns nothing.

Call relations: Guardian assessment handling calls this when it wants to synthesize a visible thread item from a safety review. The function uses shlex_join for readable command text and parse_command to identify useful command actions where possible.

Call graph: calls 2 internal fn (parse_command, shlex_join); called by 1 (handle_guardian_assessment); 2 external calls (once, vec!).

fn guardian_auto_approval_review_notification(
    conversation_id: &ThreadId,
    event_turn_id: &str,
    assessment: &GuardianAssessmentEvent,
) -> ServerNotification

Purpose: Creates a server notification that tells clients a guardian approval review has started or completed. This is how automatic safety decisions become visible in the app-server protocol.

Data flow: It receives the conversation ID, the event turn ID, and the guardian assessment. It chooses the best turn ID, translates the guardian status, risk level, authorization, rationale, and action into app-server types, then returns either a “review started” notification for in-progress assessments or a “review completed” notification for approved, denied, timed-out, or aborted assessments. If completion time is missing, it uses the start time as a fallback.

Call relations: This function sits on the notification path for guardian review events. It packages the review details into either ItemGuardianApprovalReviewStartedNotification or ItemGuardianApprovalReviewCompletedNotification so clients receive a clear lifecycle update.

Call graph: 3 external calls (ItemGuardianApprovalReviewCompleted, ItemGuardianApprovalReviewStarted, to_string).

fn convert_patch_changes(changes: &HashMap<PathBuf, FileChange>) -> Vec<FileUpdateChange>

Purpose: Converts raw patch file changes into the simpler list of file updates that clients display. It also sorts them by path so the same patch appears in a predictable order.

Data flow: It receives a map from file paths to raw file-change records. For each entry, it turns the path into text, translates the kind of change, formats the diff or content, collects the results into a list, sorts that list by path, and returns it.

Call relations: The file-change builders call this whenever they need to show patch contents. Other conversion paths also use it, which keeps approval requests, patch starts, patch ends, and rebuilt history from drifting apart in how file changes are shown.

Call graph: called by 5 (item_event_to_server_notification, build_file_change_approval_request_item, build_file_change_begin_item, build_file_change_end_item, from).

fn map_patch_change_kind(change: &FileChange) -> PatchChangeKind

Purpose: Translates the core patch change type into the app-server change type used by clients. It preserves whether a file was added, deleted, updated, or moved.

Data flow: It receives one raw file change. It checks which variant it is: add, delete, or update. It returns the matching PatchChangeKind, carrying along the move target when an update represents a move.

Call relations: This is a small helper used as part of patch-change conversion. It supplies the “what kind of change is this?” piece while the surrounding conversion builds the full client-facing file update record.

fn format_file_change_diff(change: &FileChange) -> String

Purpose: Produces the text clients should show for a single file change. For moved files, it adds a short note showing the new path.

Data flow: It receives one raw file change. For added or deleted files, it returns the file content stored in the change. For updated files, it returns the unified diff, which is a standard before-and-after patch format; if the file was moved, it appends a “Moved to” line with the destination path.

Call relations: This helper is used during patch-change conversion to fill the display text for each changed file. It keeps the formatting rule for moved files in one place instead of repeating it in every patch builder.

Call graph: 1 external calls (format!).

async fn send_thread_token_usage_update_to_connection(
    outgoing: &Arc<OutgoingMessageSender>,
    connection_id: ConnectionId,
    thread_id: ThreadId,
    thread: &Thread,
    conversation: &Code

Purpose: Sends a saved token-usage update to one specific connection that has attached to an existing thread. It is used for replaying already-recorded usage, not for creating a new model event.

Data flow: It receives the outgoing message sender, the target connection id, the thread id, the rebuilt thread, the live conversation object, and an optional turn id already chosen for the token usage. It asks the conversation for saved token-usage information; if there is none, it stops. If there is usage data, it builds a thread-token-usage notification, choosing the provided turn id or falling back to the latest suitable turn in the thread, converts the usage data into the protocol shape, and sends the notification only to the given connection.

Call relations: A higher-level request processor calls this after deciding replay is allowed for a newly attached client. Inside, it calls token_usage_info to read the saved usage, uses ThreadTokenUsage::from to convert that data for the app-server protocol, builds a ThreadTokenUsageUpdatedNotification, and hands it to the outgoing-message sender so only the attaching connection receives it.

Call graph: calls 2 internal fn (from, token_usage_info); 2 external calls (ThreadTokenUsageUpdated, to_string).

fn latest_token_usage_turn_id_from_rollout_items(
    rollout_items: &[RolloutItem],
    turns: &[Turn],
) -> Option<String>

Purpose: Finds which rebuilt turn should receive the latest saved token-usage update. It exists because a saved history may contain old turn ids that no longer match the rebuilt thread.

Data flow: It receives the saved rollout items and the list of rebuilt turns. It walks through the rollout items in order with a thread-history builder, watching for token-count events. Whenever it sees one, it records a snapshot of the currently active turn: both its id and its position in the turn list. After the walk, it returns the saved id if that id still appears in the rebuilt turns. If not, it uses the saved position to look up the corresponding rebuilt turn and returns that rebuilt id. If no token-count owner can be found, it returns nothing.

Call relations: This function is the normal attribution path used before replaying token usage. It creates a ThreadHistoryBuilder with new, iterates through the rollout history, checks each item for a token-count event, and relies on the builder’s view of the active turn to map old persisted history back to the rebuilt Turn list.

Call graph: calls 1 internal fn (new); 2 external calls (iter, matches!).

fn latest_token_usage_turn_id(thread: &Thread) -> String

Purpose: Chooses a backup turn id when the more precise rollout-based attribution is unavailable. It gives the replay notification a stable turn id even for unusual or incomplete histories.

Data flow: It receives a rebuilt thread. It scans the turns from newest to oldest and prefers the latest turn that is completed or failed, because those are the most likely to have finished usage information. If none are completed or failed, it uses the last turn in the thread. If the thread has no turns at all, it returns an empty string.

Call relations: This is the fallback used by send_thread_token_usage_update_to_connection when no token-usage turn id was supplied. It does not call out to other project helpers; it simply inspects the thread’s turns and picks the best available id.

fn replay_attribution_uses_already_loaded_history()

Purpose: Checks that token usage is attributed to the original rebuilt turn when the saved turn id still matches. This protects the normal replay path.

Data flow: It builds a small fake rollout history with one user turn, one agent answer, a token count, and then another user turn. It rebuilds turns from that history, asks latest_token_usage_turn_id_from_rollout_items for the owner of the token usage, and asserts that the answer is the first turn’s id.

Call relations: This test uses tests::token_usage_history to create the sample history and build_turns_from_rollout_items to rebuild the visible turns. It then exercises the attribution function directly and uses assert_eq! to lock in the expected result.

Call graph: 3 external calls (token_usage_history, assert_eq!, build_turns_from_rollout_items).

fn replay_attribution_falls_back_to_rebuilt_turn_position()

Purpose: Checks that attribution still works when the old saved turn id no longer matches the rebuilt thread. This protects the position-based fallback.

Data flow: It creates the same fake rollout history and rebuilds the turns, then deliberately changes the first rebuilt turn’s id to a new value. It asks latest_token_usage_turn_id_from_rollout_items for the token-usage owner and asserts that the function returns the new rebuilt id at the same position.

Call relations: This test mirrors the normal-history test but simulates regenerated turn ids. It calls tests::token_usage_history, rebuilds turns with build_turns_from_rollout_items, mutates the first turn id, and confirms with assert_eq! that the attribution function falls back by position.

Call graph: 3 external calls (token_usage_history, assert_eq!, build_turns_from_rollout_items).

fn token_usage_history() -> Vec<RolloutItem>

Purpose: Creates a compact sample conversation history for the replay-attribution tests. The history is shaped to show a token count saved after the first answer and before the second turn begins.

Data flow: It takes no input. It returns a vector of rollout items: a user message for the first turn, an agent message answering it, a token-count event, and a user message starting a second turn.

Call relations: The two replay-attribution tests call this helper so they share the same controlled history. It uses the standard vector-building macro to produce the rollout items that are then fed into build_turns_from_rollout_items and the attribution function.

Call graph: 1 external calls (vec!).

fn build_turns_from_rollout_items(items: &[RolloutItem]) -> Vec<Turn>

Purpose: Rebuilds a full list of turns from saved rollout items, which are the persisted log records for a thread. Callers use it when resuming or displaying an existing thread.

Data flow: It receives a slice of saved rollout items → creates a fresh ThreadHistoryBuilder → feeds each item to the builder in order → finishes the builder and returns the completed list of turns.

Call relations: Many tests exercise this as the public replay path. Internally it starts with ThreadHistoryBuilder::new, then relies on ThreadHistoryBuilder::handle_rollout_item and ThreadHistoryBuilder::finish to do the actual reconstruction.

Call graph: calls 1 internal fn (new); called by 29 (assigns_late_exec_completion_to_original_turn, drops_last_turns_on_thread_rollback, error_then_turn_complete_preserves_failed_status, ignores_plain_user_response_items_in_rollout_replay, ignores_user_message_item_lifecycle_events, late_turn_aborted_does_not_interrupt_active_turn, late_turn_complete_does_not_close_active_turn, marks_turn_as_interrupted_when_aborted, out_of_turn_error_does_not_create_or_fail_a_turn, preserves_agent_message_phase_in_history (+15 more)).

fn is_empty(&self) -> bool

Purpose: Checks whether a change set contains no useful updates. This is a quick way for callers to skip unnecessary client notifications.

Data flow: It reads the three lists inside the change set → checks that changed items, changed turns, and removed turn IDs are all empty → returns true only if nothing changed.

Call relations: This is a small helper for consumers of incremental history updates. It does not call other project code and is used after handlers produce a ThreadHistoryChangeSet.

fn from_pending_turn(turn: &PendingTurn) -> Self

Purpose: Creates a lightweight turn-status snapshot from an open, not-yet-finished turn. It lets incremental update code report that a turn has started or changed without copying every item.

Data flow: It reads the pending turn’s ID, status, error, timestamps, and duration → copies those fields into a ThreadHistoryTurnChange → returns that snapshot.

Call relations: record_changed_pending_turn calls this when an active turn is created or updated while change tracking is enabled.

Call graph: called by 1 (record_changed_pending_turn).

fn from_turn(turn: &Turn) -> Self

Purpose: Creates a lightweight turn-status snapshot from a finished turn. It is used when older turns are updated after they have already left the active slot.

Data flow: It reads the finished turn’s ID, status, error, timestamps, and duration → copies those fields into a ThreadHistoryTurnChange → returns that snapshot.

Call relations: handle_turn_aborted and handle_turn_complete use this when an event targets a turn already stored in the finished-turn list.

Call graph: called by 2 (handle_turn_aborted, handle_turn_complete).

fn push(&mut self, changes: ThreadHistoryChangeSet)

Purpose: Adds one event’s changes into a batch accumulator. It keeps the batch tidy by routing removals, item changes, and turn changes through deduping helpers.

Data flow: It receives a ThreadHistoryChangeSet → processes removed turns first, then changed items, then changed turns → updates the accumulator’s internal lists and lookup tables.

Call relations: handle_rollout_items_with_changes calls this for each rollout item in a batch. It hands work to push_removed_turn_id, push_item_change, and push_turn_change.

Call graph: calls 3 internal fn (push_item_change, push_removed_turn_id, push_turn_change).

fn finish(self) -> ThreadHistoryChangeSet

Purpose: Turns the accumulator’s internal state into the final batch change set. It removes entries that were intentionally blanked out because a later rollback made them obsolete.

Data flow: It consumes the accumulator → drops None placeholders from item and turn lists → returns a ThreadHistoryChangeSet with final changed items, changed turns, and removed turn IDs.

Call relations: handle_rollout_items_with_changes calls this after all rollout items in the batch have been processed.

fn push_item_change(&mut self, change: ThreadHistoryItemChange)

Purpose: Records the latest snapshot for one changed item while preserving the position of its first change in the batch. This stops repeated updates to the same item from being sent multiple times.

Data flow: It receives an item change → builds a key from turn ID and item ID → replaces the earlier snapshot if that key was already seen, or appends it if it is new.

Call relations: ThreadHistoryChangeAccumulator::push calls this for each changed item produced by a single rollout item.

Call graph: called by 1 (push).

fn push_turn_change(&mut self, change: ThreadHistoryTurnChange)

Purpose: Records the latest metadata snapshot for one turn while keeping first-change ordering. This avoids sending both “started” and “completed” snapshots for the same turn in one batch when only the final state matters.

Data flow: It receives a turn change → checks whether that turn ID already has an entry → replaces the old snapshot or appends a new one → updates the index map.

Call relations: ThreadHistoryChangeAccumulator::push calls this for each changed turn produced by a single rollout item.

Call graph: called by 1 (push).

fn push_removed_turn_id(&mut self, turn_id: String)

Purpose: Records that a turn was removed and clears any earlier item or turn changes for that same turn. This keeps clients from receiving “update this turn” and “delete this turn” at the same time.

Data flow: It receives a turn ID → adds it to the removed list if not already present → removes pending turn metadata changes for that ID → removes pending item changes belonging to that turn.

Call relations: ThreadHistoryChangeAccumulator::push calls this before adding other changes from the same event, so rollback cleanup wins over stale updates.

Call graph: called by 1 (push).

fn default() -> Self

Purpose: Creates a fresh builder using the same setup as new. It exists so code can use Rust’s standard default-construction pattern.

Data flow: It receives no input → delegates to ThreadHistoryBuilder::new → returns an empty builder.

Call relations: This is the standard Default implementation and is equivalent to calling new directly.

Call graph: 1 external calls (new).

fn new() -> Self

Purpose: Creates an empty thread-history builder ready to receive events. This is the starting point for both full replay and live tracking.

Data flow: It initializes empty finished turns, no current turn, item numbering at 1, rollout indexes at 0, and no active change set → returns the builder.

Call relations: build_turns_from_rollout_items, many tests, and other runtime code call this before feeding events into the builder.

Call graph: called by 15 (build_turns_from_rollout_items, apply_patch_approval_request_updates_active_turn_snapshot_with_file_change, builds_multiple_turns_with_reasoning_items, changed_rollout_item_reports_new_item_snapshot, changed_rollout_item_reports_streaming_item_mutation, changed_rollout_item_reports_turn_completion_metadata, changed_rollout_item_reports_updated_existing_item_snapshot, changed_rollout_items_dedupe_turn_metadata_snapshots, changed_rollout_items_dedupe_updated_item_snapshots, changed_rollout_items_drop_prior_changes_for_removed_turns (+5 more)); 1 external calls (new).

fn reset(&mut self)

Purpose: Clears the builder back to its initial empty state. This lets a long-lived owner reuse the same builder after a thread is cleared or restarted.

Data flow: It takes the existing builder → replaces all internal state with a newly constructed builder → leaves no finished or active turn behind.

Call relations: Runtime helpers such as clear_listener and track_current_turn_event call this when they need to discard the current reconstructed history.

Call graph: called by 2 (clear_listener, track_current_turn_event); 1 external calls (new).

fn finish(mut self) -> Vec<Turn>

Purpose: Completes history construction and returns the final turn list. It makes sure any still-open turn is included if it should be visible.

Data flow: It takes ownership of the builder → closes the current turn through finish_current_turn → returns the stored Vec<Turn>.

Call relations: build_turns_from_rollout_items calls this after replaying all saved items. It depends on finish_current_turn to apply the rules for keeping or dropping an empty implicit turn.

Call graph: calls 1 internal fn (finish_current_turn).

fn active_turn_snapshot(&self) -> Option<Turn>

Purpose: Returns a copy of the current turn as it looks right now. If no turn is open, it returns the latest finished turn instead.

Data flow: It reads the open pending turn if present, otherwise the last finished turn → clones or converts it into a Turn → returns it as an optional value.

Call relations: Live display code can call this when it wants the current visible state without finishing the builder.

Call graph: called by 1 (active_turn_snapshot).

fn turn_snapshot(&self, turn_id: &str) -> Option<Turn>

Purpose: Returns a copy of a specific turn by ID. It works whether the turn is still open or already finished.

Data flow: It receives a turn ID → checks the current pending turn first → otherwise searches finished turns → returns a cloned Turn if found.

Call relations: This is a lookup helper for callers that need one turn’s current materialized state instead of the whole history.

fn active_turn_position(&self) -> Option<usize>

Purpose: Reports where the active turn appears in the final turn list. This helps callers place live updates in the same order they will have after replay finishes.

Data flow: It inspects whether a current turn exists and how many finished turns exist → returns the index of the current turn, the last finished turn, or nothing if there is no turn at all.

Call relations: This helper is used by code that tracks or displays the active turn’s position without forcing the turn to close.

fn has_active_turn(&self) -> bool

Purpose: Answers whether a turn is currently open. This is a simple guard for code that treats live turns differently from finished history.

Data flow: It checks whether current_turn is Some → returns true or false.

Call relations: track_current_turn_event calls this to decide how to update current-turn state.

Call graph: called by 1 (track_current_turn_event).

fn active_turn_id_if_explicit(&self) -> Option<String>

Purpose: Returns the current turn’s ID only if that turn was opened by an explicit turn-start event. This distinguishes modern streams from older implicit grouping behavior.

Data flow: It checks the current pending turn → verifies its explicit-open flag → returns the turn ID copy if both conditions hold.

Call relations: Callers use this when they must know whether a live turn has a real persisted turn boundary.

fn active_turn_start_index(&self) -> Option<usize>

Purpose: Reports which rollout item opened the current turn. This helps resume or rejoin logic know where the active turn began in the saved stream.

Data flow: It reads the current pending turn’s rollout_start_index → returns that index if a turn is open.

Call relations: This is a state-inspection helper for code coordinating rollout replay with live updates.

fn handle_event(&mut self, event: &EventMsg)

Purpose: Routes one low-level event to the specific handler that knows how to turn it into history. It is the main dispatcher for event replay.

Data flow: It receives an EventMsg → matches on its variant → calls the matching handle_* method or ignores variants that should not affect visible thread history.

Call relations: handle_rollout_item and live tracking code call this. It hands off to many specialized handlers such as handle_user_message, handle_exec_command_end, and handle_turn_complete.

Call graph: calls 40 internal fn (handle_agent_message, handle_agent_reasoning, handle_agent_reasoning_raw_content, handle_apply_patch_approval_request, handle_collab_agent_interaction_begin, handle_collab_agent_interaction_end, handle_collab_agent_spawn_begin, handle_collab_agent_spawn_end, handle_collab_close_begin, handle_collab_close_end (+15 more)); called by 2 (handle_rollout_item, track_current_turn_event).

fn handle_rollout_item(&mut self, item: &RolloutItem)

Purpose: Processes one saved rollout item and advances the builder’s replay position. Rollout items may be events, compaction markers, response items, or metadata.

Data flow: It updates the current and next rollout indexes → examines the item kind → sends event messages to handle_event, compaction markers to handle_compacted, hook response items to handle_response_item, and ignores metadata-only items.

Call relations: build_turns_from_rollout_items calls this for full replay. The change-tracking path also wraps this through handle_rollout_item_with_changes.

Call graph: calls 3 internal fn (handle_compacted, handle_event, handle_response_item).

fn handle_event_with_changes(&mut self, event: &EventMsg) -> ThreadHistoryChangeSet

Purpose: Processes one event and returns only the materialized history changes caused by that event. This is for live clients that want efficient incremental updates.

Data flow: It receives an event → starts temporary change collection → runs handle_event → returns the collected changed items, changed turns, and removed turns.

Call relations: It uses collect_changes as the common wrapper for change tracking.

Call graph: calls 1 internal fn (collect_changes).

fn handle_rollout_item_with_changes(
        &mut self,
        item: &RolloutItem,
    ) -> ThreadHistoryChangeSet

Purpose: Processes one saved rollout item and reports the visible history changes it caused. This is the rollout-item version of incremental update handling.

Data flow: It receives a rollout item → starts temporary change collection → runs handle_rollout_item → returns the collected ThreadHistoryChangeSet.

Call relations: handle_rollout_items_with_changes calls this once per item when building a coalesced batch update.

Call graph: calls 1 internal fn (collect_changes); called by 1 (handle_rollout_items_with_changes).

fn handle_rollout_items_with_changes(
        &mut self,
        items: &[RolloutItem],
    ) -> ThreadHistoryChangeSet

Purpose: Processes several rollout items and returns one cleaned-up batch of changes. Repeated updates to the same item or turn are collapsed to their final state.

Data flow: It receives a slice of rollout items → creates a ThreadHistoryChangeAccumulator → processes each item with handle_rollout_item_with_changes → pushes each result into the accumulator → returns the accumulator’s final change set.

Call relations: This is the batch-oriented incremental API. It relies on ThreadHistoryChangeAccumulator to deduplicate and remove stale changes.

Call graph: calls 1 internal fn (handle_rollout_item_with_changes); 1 external calls (default).

fn collect_changes(&mut self, handle: impl FnOnce(&mut Self)) -> ThreadHistoryChangeSet

Purpose: Temporarily turns on change recording while one handler runs. It is the shared wrapper behind the incremental APIs.

Data flow: It asserts no change set is already active → installs an empty change set → runs the provided closure against the builder → takes and returns the collected changes.

Call relations: handle_event_with_changes and handle_rollout_item_with_changes both call this so normal handlers do not need separate incremental versions.

Call graph: called by 2 (handle_event_with_changes, handle_rollout_item_with_changes); 2 external calls (default, debug_assert!).

fn handle_response_item(&mut self, item: &codex_protocol::models::ResponseItem)

Purpose: Extracts hook-prompt messages from saved response items and adds them to the current turn. Plain user response items are ignored because they are not special hook prompts.

Data flow: It receives a response item → keeps only user-role message items → tries to parse hook-prompt content → converts fragments into v2 history fragments → pushes a HookPrompt item into the current turn.

Call relations: handle_rollout_item calls this for RolloutItem::ResponseItem. It uses parse_hook_prompt_message and then push_item_in_current_turn.

Call graph: calls 2 internal fn (push_item_in_current_turn, parse_hook_prompt_message); called by 1 (handle_rollout_item).

fn handle_user_message(&mut self, payload: &UserMessageEvent)

Purpose: Adds a user message to history and starts a new implicit turn when needed. It preserves explicit turns so mid-turn steering messages stay in the same turn.

Data flow: It receives a user-message event → may close the current implicit turn → generates a new item ID → converts text and images with build_user_inputs → pushes a UserMessage item.

Call relations: handle_event calls this for user messages. It uses finish_current_turn, next_item_id, build_user_inputs, and push_item_in_current_turn.

Call graph: calls 4 internal fn (build_user_inputs, finish_current_turn, next_item_id, push_item_in_current_turn); called by 1 (handle_event).

fn handle_agent_message(
        &mut self,
        text: String,
        phase: Option<MessagePhase>,
        memory_citation: Option<crate::protocol::v2::MemoryCitation>,
    )

Purpose: Adds an agent-visible message to the current turn. Empty messages are skipped so they do not create blank timeline items.

Data flow: It receives text, optional phase, and optional memory citation → returns early if the text is empty → generates an item ID → pushes an AgentMessage item.

Call relations: handle_event calls this when an agent message event arrives.

Call graph: calls 2 internal fn (next_item_id, push_item_in_current_turn); called by 1 (handle_event).

fn handle_agent_reasoning(&mut self, payload: &AgentReasoningEvent)

Purpose: Adds or extends the agent’s reasoning summary. Consecutive reasoning-summary chunks are merged into one item so streamed text appears as one coherent block.

Data flow: It receives a reasoning event → ignores empty text → ensures a turn exists → if the last item is reasoning, appends to its summary and records the updated item → otherwise creates a new reasoning item.

Call relations: handle_event calls this. It uses ensure_turn for the active turn, record_changed_item for live updates, and push_item_in_current_turn for new reasoning items.

Call graph: calls 5 internal fn (ensure_turn, is_tracking_changes, next_item_id, push_item_in_current_turn, record_changed_item); called by 1 (handle_event); 2 external calls (new, vec!).

fn handle_agent_reasoning_raw_content(&mut self, payload: &AgentReasoningRawContentEvent)

Purpose: Adds or extends the raw reasoning content for the agent. It mirrors summary handling but writes to the detailed content field.

Data flow: It receives raw reasoning text → ignores empty text → ensures a turn exists → appends to the last reasoning item if possible → otherwise creates a new reasoning item containing raw content.

Call relations: handle_event calls this for raw reasoning events. It shares the same change-recording pattern as handle_agent_reasoning.

Call graph: calls 5 internal fn (ensure_turn, is_tracking_changes, next_item_id, push_item_in_current_turn, record_changed_item); called by 1 (handle_event); 2 external calls (new, vec!).

fn handle_item_started(&mut self, payload: &ItemStartedEvent)

Purpose: Rebuilds supported lifecycle items when a persisted item-started event appears. At present it only materializes plan and sleep items from these generic lifecycle events.

Data flow: It receives an item-started payload → checks the embedded turn item → converts non-empty plans and sleeps into ThreadItems → upserts them into the referenced turn → ignores other item types because they are represented by their own event kinds.

Call relations: handle_event calls this. It relies on upsert_item_in_turn_id so updates land in the explicit turn named by the event.

Call graph: calls 2 internal fn (upsert_item_in_turn_id, from); called by 1 (handle_event).

fn handle_item_completed(&mut self, payload: &ItemCompletedEvent)

Purpose: Rebuilds supported lifecycle items when a persisted item-completed event appears. It keeps completed plan and sleep items visible after replay.

Data flow: It receives an item-completed payload → converts non-empty plans and sleeps into ThreadItems → upserts them into the referenced turn → ignores item types handled elsewhere.

Call relations: handle_event calls this. Like handle_item_started, it sends converted items to upsert_item_in_turn_id.

Call graph: calls 2 internal fn (upsert_item_in_turn_id, from); called by 1 (handle_event).

fn handle_web_search_begin(&mut self, payload: &WebSearchBeginEvent)

Purpose: Shows that a web search has started. It creates a placeholder search item that can later be updated with the final query and action.

Data flow: It receives a search-begin event → builds a WebSearch item with the call ID, empty query, and no action → upserts it into the current turn.

Call relations: handle_event calls this. A later handle_web_search_end with the same ID replaces the placeholder.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event); 1 external calls (new).

fn handle_web_search_end(&mut self, payload: &WebSearchEndEvent)

Purpose: Stores the completed web search details. It updates the placeholder item if one already exists.

Data flow: It receives a search-end event → converts the core web search action to the v2 form → builds a complete WebSearch item → upserts it into the current turn.

Call relations: handle_event calls this after search completion events. It pairs naturally with handle_web_search_begin.

Call graph: calls 2 internal fn (upsert_item_in_current_turn, from); called by 1 (handle_event).

fn handle_exec_command_begin(&mut self, payload: &ExecCommandBeginEvent)

Purpose: Adds or updates a command-execution item when a shell command starts. This lets the history show running commands.

Data flow: It receives a command-begin event → asks an item-builder helper to convert it into a v2 history item → upserts that item into the event’s turn ID.

Call relations: handle_event calls this. It uses build_command_execution_begin_item for conversion and upsert_item_in_turn_id for placement.

Call graph: calls 2 internal fn (build_command_execution_begin_item, upsert_item_in_turn_id); called by 1 (handle_event).

fn handle_exec_command_end(&mut self, payload: &ExecCommandEndEvent)

Purpose: Adds or updates a command-execution item when a shell command finishes. It uses the event’s turn ID so late command exits are attached to the turn that started them.

Data flow: It receives a command-end event → converts it into a complete command item → upserts it into the turn named by the event, even if another turn is currently active.

Call relations: handle_event calls this. This is important for out-of-order command completion, where a background process may finish after a newer turn has begun.

Call graph: calls 2 internal fn (build_command_execution_end_item, upsert_item_in_turn_id); called by 1 (handle_event).

fn handle_guardian_assessment(&mut self, payload: &GuardianAssessmentEvent)

Purpose: Turns safety-review events into visible command items when a command is being reviewed, declined, aborted, or timed out. Approved reviews are not shown as separate items.

Data flow: It receives a guardian assessment → maps the guardian status to a command status → asks a builder helper for the item → inserts it into the current turn or the explicit turn ID if provided.

Call relations: handle_event calls this for guardian assessment events. It uses build_item_from_guardian_event and the upsert helpers.

Call graph: calls 3 internal fn (build_item_from_guardian_event, upsert_item_in_current_turn, upsert_item_in_turn_id); called by 1 (handle_event).

fn handle_apply_patch_approval_request(&mut self, payload: &ApplyPatchApprovalRequestEvent)

Purpose: Shows a file-change item when a patch needs approval. This gives the client a visible record of the proposed edit.

Data flow: It receives an approval request → converts it into a file-change item → upserts it into either the current turn or the turn ID carried by the payload.

Call relations: handle_event calls this. It uses build_file_change_approval_request_item for the conversion.

Call graph: calls 3 internal fn (build_file_change_approval_request_item, upsert_item_in_current_turn, upsert_item_in_turn_id); called by 1 (handle_event).

fn handle_patch_apply_begin(&mut self, payload: &PatchApplyBeginEvent)

Purpose: Shows that a file patch has started applying. It creates or updates the file-change item as in progress.

Data flow: It receives a patch-begin event → converts the patch details into a v2 file-change item → inserts it into the current or named turn.

Call relations: handle_event calls this. It pairs with handle_patch_apply_end, which later records the final outcome.

Call graph: calls 3 internal fn (build_file_change_begin_item, upsert_item_in_current_turn, upsert_item_in_turn_id); called by 1 (handle_event).

fn handle_patch_apply_end(&mut self, payload: &PatchApplyEndEvent)

Purpose: Stores the final result of applying a file patch. This updates the file-change item with success, failure, or declined status.

Data flow: It receives a patch-end event → builds the final file-change item → upserts it into the current or named turn.

Call relations: handle_event calls this after patch completion. It uses build_file_change_end_item and the upsert helpers.

Call graph: calls 3 internal fn (build_file_change_end_item, upsert_item_in_current_turn, upsert_item_in_turn_id); called by 1 (handle_event).

fn handle_dynamic_tool_call_request(
        &mut self,
        payload: &codex_protocol::dynamic_tools::DynamicToolCallRequest,
    )

Purpose: Adds a dynamic-tool call when the agent requests a tool that is described at runtime. The initial item is marked in progress.

Data flow: It receives a dynamic tool request → builds a DynamicToolCall item with namespace, tool name, arguments, and in-progress status → inserts it into the current or named turn.

Call relations: handle_event calls this. handle_dynamic_tool_call_response later replaces the item with the completed result.

Call graph: calls 2 internal fn (upsert_item_in_current_turn, upsert_item_in_turn_id); called by 1 (handle_event).

fn handle_dynamic_tool_call_response(&mut self, payload: &DynamicToolCallResponseEvent)

Purpose: Stores the result of a dynamic-tool call. It records success or failure, returned content, and duration.

Data flow: It receives a dynamic tool response → maps success to completed or failed status → converts duration to milliseconds if possible → converts output content items → upserts the final DynamicToolCall item into the current or named turn.

Call relations: handle_event calls this. It depends on convert_dynamic_tool_content_items for output conversion.

Call graph: calls 3 internal fn (upsert_item_in_current_turn, upsert_item_in_turn_id, convert_dynamic_tool_content_items); called by 1 (handle_event); 1 external calls (try_from).

fn handle_mcp_tool_call_begin(&mut self, payload: &McpToolCallBeginEvent)

Purpose: Adds an in-progress MCP tool call. MCP means Model Context Protocol, a way for the agent to call external tools or servers.

Data flow: It receives an MCP begin event → extracts server, tool, arguments, resource URI, and plugin ID → builds an in-progress McpToolCall item → upserts it into the current turn.

Call relations: handle_event calls this. handle_mcp_tool_call_end later updates the same call ID with the result.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event).

fn handle_mcp_tool_call_end(&mut self, payload: &McpToolCallEndEvent)

Purpose: Stores the completed MCP tool call, including either its result or its error message. It also records how long the call took.

Data flow: It receives an MCP end event → decides completed versus failed → converts duration to milliseconds → splits the result into either a result object or an error object → upserts the final McpToolCall item.

Call relations: handle_event calls this after MCP completion events. It updates items first created by handle_mcp_tool_call_begin, or creates the completed item directly during replay.

Call graph: calls 2 internal fn (upsert_item_in_current_turn, is_success); called by 1 (handle_event); 2 external calls (new, try_from).

fn handle_view_image_tool_call(&mut self, payload: &ViewImageToolCallEvent)

Purpose: Adds a history item when the agent views an image file. This keeps image-inspection actions visible in the thread.

Data flow: It receives a view-image event → builds an ImageView item with the call ID and path → upserts it into the current turn.

Call relations: handle_event calls this for image-view tool events.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event).

fn handle_image_generation_begin(&mut self, payload: &ImageGenerationBeginEvent)

Purpose: Shows that image generation has started. It creates a placeholder item before the generated result is available.

Data flow: It receives an image-generation begin event → builds an ImageGeneration item with blank result fields → upserts it into the current turn.

Call relations: handle_event calls this. handle_image_generation_end later fills in status, prompt, result, and saved path.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event); 1 external calls (new).

fn handle_image_generation_end(&mut self, payload: &ImageGenerationEndEvent)

Purpose: Stores the final image-generation result. It records status, revised prompt, generated data, and the saved file path if present.

Data flow: It receives an image-generation end event → builds a complete ImageGeneration item → upserts it into the current turn.

Call relations: handle_event calls this after image generation completes, updating the placeholder from handle_image_generation_begin if present.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event).

fn handle_collab_agent_spawn_begin(
        &mut self,
        payload: &codex_protocol::protocol::CollabAgentSpawnBeginEvent,
    )

Purpose: Adds an in-progress collaborative-agent spawn call. This shows that one agent is starting another agent.

Data flow: It receives a spawn-begin event → builds a CollabAgentToolCall for the spawn operation with prompt, model, reasoning effort, and sender thread ID → upserts it into the current turn.

Call relations: handle_event calls this. handle_collab_agent_spawn_end later records whether the new agent was created.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event); 2 external calls (new, new).

fn handle_collab_agent_spawn_end(
        &mut self,
        payload: &codex_protocol::protocol::CollabAgentSpawnEndEvent,
    )

Purpose: Stores the result of spawning a collaborative agent. It records the new thread ID and agent state when creation succeeds.

Data flow: It receives a spawn-end event → decides completed or failed based on status and whether a receiver thread exists → builds receiver IDs and agent-state map → upserts the final spawn tool-call item.

Call relations: handle_event calls this. It converts core agent status into v2 CollabAgentState for display.

Call graph: calls 2 internal fn (upsert_item_in_current_turn, from); called by 1 (handle_event); 3 external calls (new, new, vec!).

fn handle_collab_agent_interaction_begin(
        &mut self,
        payload: &codex_protocol::protocol::CollabAgentInteractionBeginEvent,
    )

Purpose: Adds an in-progress send-input call to another agent. This represents one agent asking another agent to do something.

Data flow: It receives an interaction-begin event → builds a CollabAgentToolCall with the sender, receiver, and prompt → marks it in progress → upserts it into the current turn.

Call relations: handle_event calls this. handle_collab_agent_interaction_end later records the receiver’s state.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event); 2 external calls (new, vec!).

fn handle_collab_agent_interaction_end(
        &mut self,
        payload: &codex_protocol::protocol::CollabAgentInteractionEndEvent,
    )

Purpose: Stores the result of sending input to another agent. It treats missing or errored receivers as failed and other statuses as a completed send operation.

Data flow: It receives an interaction-end event → maps the receiver status to tool-call status and agent state → builds the final CollabAgentToolCall → upserts it into the current turn.

Call relations: handle_event calls this. It complements handle_collab_agent_interaction_begin.

Call graph: calls 2 internal fn (upsert_item_in_current_turn, from); called by 1 (handle_event); 1 external calls (vec!).

fn handle_sub_agent_activity(
        &mut self,
        payload: &codex_protocol::protocol::SubAgentActivityEvent,
    )

Purpose: Adds a visible note that a sub-agent performed some activity. This lets the parent thread show related agent movement.

Data flow: It receives a sub-agent activity event → copies the event ID, kind, agent thread ID, and agent path → upserts a SubAgentActivity item into the current turn.

Call relations: handle_event calls this for sub-agent activity events.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event); 1 external calls (from).

fn handle_collab_waiting_begin(
        &mut self,
        payload: &codex_protocol::protocol::CollabWaitingBeginEvent,
    )

Purpose: Adds an in-progress wait call for collaborative agents. It shows that this thread is waiting on one or more other agent threads.

Data flow: It receives a waiting-begin event → converts receiver thread IDs to strings → builds an in-progress CollabAgentToolCall with tool Wait → upserts it into the current turn.

Call relations: handle_event calls this. handle_collab_waiting_end later records the final states of the waited-on agents.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event); 1 external calls (new).

fn handle_collab_waiting_end(
        &mut self,
        payload: &codex_protocol::protocol::CollabWaitingEndEvent,
    )

Purpose: Stores the result of waiting on collaborative agents. The wait is failed if any waited-on agent errored or was not found.

Data flow: It receives a waiting-end event → checks all agent statuses → sorts receiver IDs for stable output → converts statuses into an agent-state map → upserts the completed wait item.

Call relations: handle_event calls this after wait completion events.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event).

fn handle_collab_close_begin(
        &mut self,
        payload: &codex_protocol::protocol::CollabCloseBeginEvent,
    )

Purpose: Adds an in-progress close-agent call. This shows that one thread is asking another agent thread to close.

Data flow: It receives a close-begin event → builds a CollabAgentToolCall with tool CloseAgent, sender, and receiver → marks it in progress → upserts it into the current turn.

Call relations: handle_event calls this. handle_collab_close_end later records the outcome.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event); 2 external calls (new, vec!).

fn handle_collab_close_end(&mut self, payload: &codex_protocol::protocol::CollabCloseEndEvent)

Purpose: Stores the result of closing a collaborative agent. It records whether the close operation succeeded and the receiver’s final state.

Data flow: It receives a close-end event → maps errored or missing receivers to failed, otherwise completed → builds an agent-state map → upserts the final close item.

Call relations: handle_event calls this after close completion events.

Call graph: calls 2 internal fn (upsert_item_in_current_turn, from); called by 1 (handle_event); 1 external calls (vec!).

fn handle_collab_resume_begin(
        &mut self,
        payload: &codex_protocol::protocol::CollabResumeBeginEvent,
    )

Purpose: Adds an in-progress resume-agent call. This shows that one thread is trying to resume another agent thread.

Data flow: It receives a resume-begin event → builds a CollabAgentToolCall with tool ResumeAgent, sender, and receiver → marks it in progress → upserts it into the current turn.

Call relations: handle_event calls this. handle_collab_resume_end later records the result.

Call graph: calls 1 internal fn (upsert_item_in_current_turn); called by 1 (handle_event); 2 external calls (new, vec!).

fn handle_collab_resume_end(
        &mut self,
        payload: &codex_protocol::protocol::CollabResumeEndEvent,
    )

Purpose: Stores the result of resuming a collaborative agent. It records the receiver’s state after the resume request.

Data flow: It receives a resume-end event → maps failure statuses to failed and others to completed → builds a receiver state map → upserts the final resume item.

Call relations: handle_event calls this for collaborative-agent resume completion events.

Call graph: calls 2 internal fn (upsert_item_in_current_turn, from); called by 1 (handle_event); 1 external calls (vec!).

fn handle_context_compacted(&mut self, _payload: &ContextCompactedEvent)

Purpose: Adds a visible marker that the conversation context was compacted. Compaction means old context was summarized or compressed to fit within limits.

Data flow: It receives a compaction event → generates a new item ID → pushes a ContextCompaction item into the current turn.

Call relations: handle_event calls this for ContextCompacted events. Separate handle_compacted handles persisted compaction records that do not render an item.

Call graph: calls 2 internal fn (next_item_id, push_item_in_current_turn); called by 1 (handle_event).

fn handle_entered_review_mode(&mut self, payload: &codex_protocol::protocol::ReviewRequest)

Purpose: Adds a visible marker when the thread enters review mode. It uses a user-facing hint if one was supplied.

Data flow: It receives a review request → picks the provided hint or a default review message → generates an item ID → pushes an EnteredReviewMode item.

Call relations: handle_event calls this when review mode starts.

Call graph: calls 2 internal fn (next_item_id, push_item_in_current_turn); called by 1 (handle_event).

fn handle_exited_review_mode(
        &mut self,
        payload: &codex_protocol::protocol::ExitedReviewModeEvent,
    )

Purpose: Adds a visible marker when review mode ends. It records the reviewer’s explanation or a fallback message if no usable output exists.

Data flow: It receives an exited-review event → renders the review output text if present → otherwise uses the fallback string → generates an item ID → pushes an ExitedReviewMode item.

Call relations: handle_event calls this. It uses render_review_output_text to turn structured review output into display text.

Call graph: calls 2 internal fn (next_item_id, push_item_in_current_turn); called by 1 (handle_event).

fn handle_error(&mut self, payload: &ErrorEvent)

Purpose: Marks the current turn as failed when an error should affect turn status. Errors that are request-level or unrelated to the active turn are ignored for turn history.

Data flow: It receives an error event → asks whether the error affects turn status → if a current turn exists, sets its status to failed and stores error details → records a changed turn when change tracking is active.

Call relations: handle_event calls this for error events. It uses affects_turn_status from the error payload and record_changed_turn for incremental updates.

Call graph: calls 3 internal fn (is_tracking_changes, record_changed_turn, affects_turn_status); called by 1 (handle_event).

fn handle_turn_aborted(&mut self, payload: &TurnAbortedEvent)

Purpose: Marks a turn as interrupted when an abort event arrives. It prefers the turn ID in the event so late aborts do not accidentally interrupt the wrong active turn.

Data flow: It receives an abort payload → tries to update the matching current turn → otherwise tries finished turns → otherwise falls back to the active turn if no usable ID exists → records the changed turn.

Call relations: handle_event calls this. It uses ThreadHistoryTurnChange::from_turn when updating a finished turn.

Call graph: calls 2 internal fn (record_changed_turn, from_turn); called by 1 (handle_event).

fn handle_turn_started(&mut self, payload: &TurnStartedEvent)

Purpose: Starts a new explicit turn. Explicit turns are preserved even if they later contain no renderable items.

Data flow: It receives a turn-start event → closes any current turn → creates a new pending turn with the provided ID, in-progress status, and start time → marks it explicitly opened → records a changed turn → stores it as current.

Call relations: handle_event calls this for turn-start events. It uses finish_current_turn, new_turn, and record_changed_pending_turn.

Call graph: calls 3 internal fn (finish_current_turn, new_turn, record_changed_pending_turn); called by 1 (handle_event).

fn handle_turn_complete(&mut self, payload: &TurnCompleteEvent)

Purpose: Marks a turn as completed and closes it when appropriate. It is careful not to close the active turn if the completion event belongs to an older turn.

Data flow: It receives a completion event → updates the matching current turn and closes it, or updates a matching finished turn, or falls back to the active turn if the event cannot be matched → preserves failed status if the turn had already failed.

Call relations: handle_event calls this. It uses finish_current_turn for the active matching turn and ThreadHistoryTurnChange::from_turn for already finished turns.

Call graph: calls 3 internal fn (finish_current_turn, record_changed_turn, from_turn); called by 1 (handle_event); 1 external calls (matches!).

fn handle_compacted(&mut self, _payload: &CompactedItem)

Purpose: Notes that the current turn contains a persisted compaction marker, even if that marker does not render as an item. This prevents certain legacy compaction-only turns from disappearing.

Data flow: It receives a compacted rollout payload → ensures a turn exists → sets the pending turn’s saw_compaction flag.

Call relations: handle_rollout_item calls this for RolloutItem::Compacted. finish_current_turn later uses the flag to decide whether to keep an otherwise empty implicit turn.

Call graph: calls 1 internal fn (ensure_turn); called by 1 (handle_rollout_item).

fn handle_thread_rollback(&mut self, payload: &ThreadRolledBackEvent)

Purpose: Removes the most recent turns after a rollback event. Rollback means the thread history was intentionally rewound.

Data flow: It receives a rollback payload with a number of turns → closes the current turn → computes which turn IDs will be removed → records those removals for incremental updates → truncates or clears finished turns → resets the next generated item ID based on remaining items.

Call relations: handle_event calls this. It relies on finish_current_turn before removal so the active turn is included in rollback calculations.

Call graph: calls 2 internal fn (finish_current_turn, record_removed_turn_ids); called by 1 (handle_event); 3 external calls (new, try_from, try_from).

fn finish_current_turn(&mut self)

Purpose: Moves the current pending turn into the finished-turn list if it should be kept. Empty implicit turns are dropped unless they represent compaction.

Data flow: It takes the current pending turn if present → checks whether it has items, was explicitly opened, or saw compaction → drops it if none are true → otherwise converts it into a Turn and appends it.

Call relations: finish, handle_user_message, handle_turn_started, handle_turn_complete, and handle_thread_rollback call this whenever the current turn boundary changes.

Call graph: called by 5 (finish, handle_thread_rollback, handle_turn_complete, handle_turn_started, handle_user_message); 1 external calls (from).

fn new_turn(&mut self, id: Option<String>) -> PendingTurn

Purpose: Creates a fresh pending turn with the right ID and default metadata. It supports both explicit turn IDs and legacy implicit IDs.

Data flow: It receives an optional ID → uses it if present → otherwise generates a UUID before replay begins or a rollout-based ID during replay → initializes empty items, completed status, no timestamps, and bookkeeping flags.

Call relations: ensure_turn uses this for implicit turns, and handle_turn_started uses it for explicit turns.

Call graph: called by 2 (ensure_turn, handle_turn_started); 1 external calls (new).

fn ensure_turn(&mut self) -> &mut PendingTurn

Purpose: Guarantees that there is a current pending turn and returns it. This lets item handlers add content without first checking whether a turn exists.

Data flow: It checks whether current_turn is missing → creates a new implicit turn and records its metadata if needed → returns a mutable reference to the current turn.

Call relations: Many item handlers reach this through push_item_in_current_turn or upsert_item_in_current_turn. handle_compacted and reasoning handlers call it directly.

Call graph: calls 2 internal fn (new_turn, record_changed_pending_turn); called by 5 (handle_agent_reasoning, handle_agent_reasoning_raw_content, handle_compacted, push_item_in_current_turn, upsert_item_in_current_turn); 1 external calls (unreachable!).

fn push_item_in_current_turn(&mut self, item: ThreadItem)

Purpose: Appends a new item to the current turn. It is used when an event always creates a fresh visible item rather than updating an existing one.

Data flow: It receives a ThreadItem → ensures a turn exists → appends the item to that turn → records the item snapshot if change tracking is active.

Call relations: User messages, agent messages, review markers, hook prompts, context compaction, and new reasoning items use this helper.

Call graph: calls 3 internal fn (ensure_turn, is_tracking_changes, record_changed_item); called by 8 (handle_agent_message, handle_agent_reasoning, handle_agent_reasoning_raw_content, handle_context_compacted, handle_entered_review_mode, handle_exited_review_mode, handle_response_item, handle_user_message).

fn upsert_item_in_turn_id(&mut self, turn_id: &str, item: ThreadItem)

Purpose: Inserts or replaces an item in a specific turn by ID. This is crucial for events that may arrive late but still belong to an earlier turn.

Data flow: It receives a turn ID and item → looks for a matching current turn, then a matching finished turn → replaces an existing item with the same item ID or appends it → records the changed item if tracking → logs a warning and drops the item if the turn ID is unknown.

Call relations: Command, patch, dynamic tool, and generic lifecycle handlers call this when their payload carries an explicit turn ID.

Call graph: calls 3 internal fn (is_tracking_changes, record_changed_item, upsert_turn_item); called by 10 (handle_apply_patch_approval_request, handle_dynamic_tool_call_request, handle_dynamic_tool_call_response, handle_exec_command_begin, handle_exec_command_end, handle_guardian_assessment, handle_item_completed, handle_item_started, handle_patch_apply_begin, handle_patch_apply_end); 1 external calls (warn!).

fn upsert_item_in_current_turn(&mut self, item: ThreadItem)

Purpose: Inserts or replaces an item in the current turn. It is used for events whose correct turn is simply the active one.

Data flow: It receives a ThreadItem → ensures a current turn exists → replaces any item with the same ID or appends it → records the changed item if change tracking is active.

Call relations: Most tool begin/end handlers and collaborative-agent handlers call this. It delegates item replacement to upsert_turn_item.

Call graph: calls 4 internal fn (ensure_turn, is_tracking_changes, record_changed_item, upsert_turn_item); called by 24 (handle_apply_patch_approval_request, handle_collab_agent_interaction_begin, handle_collab_agent_interaction_end, handle_collab_agent_spawn_begin, handle_collab_agent_spawn_end, handle_collab_close_begin, handle_collab_close_end, handle_collab_resume_begin, handle_collab_resume_end, handle_collab_waiting_begin (+14 more)).

fn is_tracking_changes(&self) -> bool

Purpose: Reports whether the builder is currently collecting incremental changes. Handlers use this to avoid extra cloning when no one asked for change details.

Data flow: It checks whether active_change_set is present → returns true if change collection is active.

Call relations: Several handlers and record helpers call this inside collect_changes-driven flows.

Call graph: called by 7 (handle_agent_reasoning, handle_agent_reasoning_raw_content, handle_error, push_item_in_current_turn, record_changed_pending_turn, upsert_item_in_current_turn, upsert_item_in_turn_id).

fn record_changed_item(&mut self, turn_id: String, item: ThreadItem)

Purpose: Adds one changed item snapshot to the active change set. It does nothing when change tracking is not active.

Data flow: It receives a turn ID and item → if an active change set exists, appends a ThreadHistoryItemChange containing both.

Call relations: Item push and upsert helpers call this, and reasoning handlers call it when they mutate an existing reasoning item.

Call graph: called by 5 (handle_agent_reasoning, handle_agent_reasoning_raw_content, push_item_in_current_turn, upsert_item_in_current_turn, upsert_item_in_turn_id).

fn record_changed_pending_turn(&mut self, turn: &PendingTurn)

Purpose: Records the current metadata snapshot for a pending turn when incremental tracking is active.

Data flow: It receives a pending turn → checks whether change tracking is active → converts it with ThreadHistoryTurnChange::from_pending_turn → stores it through record_changed_turn.

Call relations: ensure_turn calls this for newly created implicit turns, and handle_turn_started calls it for explicit turns.

Call graph: calls 3 internal fn (is_tracking_changes, record_changed_turn, from_pending_turn); called by 2 (ensure_turn, handle_turn_started).

fn record_changed_turn(&mut self, turn: ThreadHistoryTurnChange)

Purpose: Adds one turn metadata snapshot to the active change set. It is the common sink for status, error, and timing updates.

Data flow: It receives a ThreadHistoryTurnChange → if an active change set exists, appends it to changed_turns.

Call relations: Turn start, completion, abort, error, and pending-turn recording paths call this.

Call graph: called by 4 (handle_error, handle_turn_aborted, handle_turn_complete, record_changed_pending_turn).

fn record_removed_turn_ids(&mut self, removed_turn_ids: Vec<String>)

Purpose: Adds removed turn IDs to the active change set. This tells clients which turns to delete after rollback.

Data flow: It receives a list of turn IDs → if an active change set exists, extends its removed_turn_ids list.

Call relations: handle_thread_rollback calls this after deciding which turns rollback removed.

Call graph: called by 1 (handle_thread_rollback).

fn next_item_id(&mut self) -> String

Purpose: Generates the next synthetic item ID for history items that do not already have one. IDs are simple sequential strings like item-1.

Data flow: It formats the current item counter into an ID string → increments the counter → returns the ID.

Call relations: Handlers for user messages, agent messages, reasoning, context compaction, and review markers call this before pushing new items.

Call graph: called by 7 (handle_agent_message, handle_agent_reasoning, handle_agent_reasoning_raw_content, handle_context_compacted, handle_entered_review_mode, handle_exited_review_mode, handle_user_message); 1 external calls (format!).

fn build_user_inputs(&self, payload: &UserMessageEvent) -> Vec<UserInput>

Purpose: Converts a user-message event into the list of text and image inputs shown in history. It preserves image-detail metadata for both remote and local images.

Data flow: It receives a user-message payload → adds a text input if the message is not blank → adds remote image inputs with matching details → adds local image inputs with matching details → returns the ordered input list.

Call relations: handle_user_message calls this before creating a UserMessage history item.

Call graph: called by 1 (handle_user_message); 1 external calls (new).

fn render_review_output_text(output: &ReviewOutputEvent) -> String

Purpose: Turns review output into plain display text. It provides a fallback when the reviewer produced no explanation.

Data flow: It receives a review output event → trims the overall explanation → returns the explanation if non-empty, otherwise returns the fallback message.

Call relations: handle_exited_review_mode uses this when review mode ends with structured review output.

fn convert_dynamic_tool_content_items(
    items: &[codex_protocol::dynamic_tools::DynamicToolCallOutputContentItem],
) -> Vec<DynamicToolCallOutputContentItem>

Purpose: Converts dynamic-tool output content from the core protocol type into the app-server v2 protocol type. This keeps the history model independent from the raw event model.

Data flow: It receives a slice of core dynamic-tool content items → maps each text or image item to the matching v2 variant → returns the converted vector.

Call relations: handle_dynamic_tool_call_response calls this while building the final dynamic-tool history item.

Call graph: called by 1 (handle_dynamic_tool_call_response); 1 external calls (iter).

fn upsert_turn_item(items: &mut Vec<ThreadItem>, item: ThreadItem) -> &ThreadItem

Purpose: Replaces an existing turn item with the same ID or appends it if it is new. This supports begin/end events that update one visible item over time.

Data flow: It receives a mutable item list and a new item → searches for an existing item with the same ID → replaces and returns it if found → otherwise appends and returns the inserted item.

Call relations: upsert_item_in_current_turn and upsert_item_in_turn_id use this as their shared item-replacement helper.

Call graph: called by 2 (upsert_item_in_current_turn, upsert_item_in_turn_id).

fn opened_explicitly(mut self) -> Self

Purpose: Marks a pending turn as coming from an explicit turn-start event. Explicit turns are kept even if they contain no visible items.

Data flow: It receives a pending turn by value → sets its opened_explicitly flag → returns the modified turn.

Call relations: handle_turn_started uses this in its builder-style setup of a new pending turn.

fn with_status(mut self, status: TurnStatus) -> Self

Purpose: Sets the initial status of a pending turn in a builder-style chain. This keeps turn creation readable.

Data flow: It receives a pending turn and a status → stores the status → returns the modified turn.

Call relations: handle_turn_started uses this to mark a newly started explicit turn as in progress.

fn with_started_at(mut self, started_at: Option<i64>) -> Self

Purpose: Sets the start timestamp of a pending turn in a builder-style chain. The timestamp is optional because older events may not have one.

Data flow: It receives a pending turn and optional start time → stores it → returns the modified turn.

Call relations: handle_turn_started uses this while building the new active turn from a turn-start event.

fn from(value: &PendingTurn) -> Self

Purpose: Converts a pending turn into the public v2 Turn shape. This is the final materialized form sent to clients.

Data flow: It receives a pending turn or a reference to one → copies or moves ID, items, status, error, and timestamps → sets the item view to full → returns a Turn.

Call relations: finish_current_turn uses the owned conversion when closing a turn, and snapshot methods use the borrowed conversion to preview an open turn.

fn builds_multiple_turns_with_reasoning_items()

Purpose: Checks that legacy implicit user messages split history into separate turns and that reasoning summary/raw content merge into one reasoning item.

Data flow: It builds a sequence of user, agent, and reasoning events → feeds them through a builder → asserts the resulting turns, item IDs, and item contents.

Call relations: This test exercises ThreadHistoryBuilder::new, event handling, and finalization for basic conversation replay.

Call graph: calls 1 internal fn (new); 4 external calls (assert!, assert_eq!, assert_ne!, vec!).

fn rebuilds_user_message_image_details_from_legacy_events()

Purpose: Verifies that remote and local image detail settings survive replay from older user-message events.

Data flow: It creates a saved user-message rollout item with text, remote image, local image, and detail metadata → rebuilds turns → checks the user input list.

Call relations: This test calls build_turns_from_rollout_items, covering handle_user_message and build_user_inputs.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 3 external calls (from, assert_eq!, vec!).

fn ignores_user_message_item_lifecycle_events()

Purpose: Ensures generic item lifecycle events do not duplicate user messages. User messages are rebuilt from their dedicated event instead.

Data flow: It creates a turn with both a user-message event and a user-message lifecycle item → rebuilds history → asserts only one user message appears.

Call relations: This test exercises handle_item_started ignoring user-message lifecycle items while handle_user_message supplies the real item.

Call graph: calls 2 internal fn (build_turns_from_rollout_items, new); 2 external calls (assert_eq!, vec!).

fn rebuilds_sleep_item_from_persisted_completion()

Purpose: Checks that a persisted sleep item can be reconstructed from an item-completed event.

Data flow: It creates an explicit turn with a completed sleep lifecycle item → rebuilds turns → asserts the sleep item is present with its duration.

Call relations: This test covers handle_item_completed and upsert_item_in_turn_id for supported lifecycle items.

Call graph: calls 2 internal fn (build_turns_from_rollout_items, new); 3 external calls (Sleep, assert_eq!, vec!).

fn preserves_user_message_client_id_from_legacy_event()

Purpose: Verifies that a user message’s client-provided ID is preserved during replay.

Data flow: It creates events containing a user message with a client ID → rebuilds history → checks that the final UserMessage item includes that client ID.

Call relations: This test covers handle_user_message and confirms lifecycle events do not overwrite the rebuilt message.

Call graph: calls 2 internal fn (build_turns_from_rollout_items, new); 2 external calls (assert_eq!, vec!).

fn preserves_agent_message_phase_in_history()

Purpose: Checks that agent message phase metadata, such as final-answer phase, is kept in history.

Data flow: It creates an agent-message event with a phase → rebuilds turns → asserts the resulting agent item has the same phase.

Call relations: This test exercises handle_agent_message through build_turns_from_rollout_items.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn replays_image_generation_end_events_into_turn_history()

Purpose: Verifies that completed image-generation events are visible after replay.

Data flow: It creates an explicit turn with a user request and image-generation end event → rebuilds history → checks the final image-generation item fields.

Call relations: This test covers handle_image_generation_end and normal explicit turn boundaries.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn splits_reasoning_when_interleaved()

Purpose: Ensures reasoning chunks merge only when they are adjacent reasoning items. If another item appears between them, a new reasoning item is created.

Data flow: It creates reasoning summary and raw content, then an agent message, then more reasoning → rebuilds history → checks that two reasoning items exist.

Call relations: This test covers the merge behavior in handle_agent_reasoning and handle_agent_reasoning_raw_content.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn marks_turn_as_interrupted_when_aborted()

Purpose: Checks that an abort event marks the affected turn as interrupted and that later user input starts a new turn.

Data flow: It creates a first user-agent exchange, aborts it, then creates a second exchange → rebuilds history → asserts the first turn is interrupted and the second is completed.

Call relations: This test exercises handle_turn_aborted, implicit turn finishing, and new-turn creation.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn drops_last_turns_on_thread_rollback()

Purpose: Verifies that rollback removes the requested number of latest turns and that new history continues afterward.

Data flow: It creates two implicit turns, rolls back one, then adds a third input → rebuilds history → asserts only the first and post-rollback turns remain.

Call relations: This test covers handle_thread_rollback, finish_current_turn, and item counter reset after rollback.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 3 external calls (assert_eq!, assert_ne!, vec!).

fn thread_rollback_clears_all_turns_when_num_turns_exceeds_history()

Purpose: Checks that rolling back more turns than exist clears the whole history safely.

Data flow: It creates two turns then requests rollback of a much larger number → rebuilds history → asserts the result is empty.

Call relations: This test exercises the clearing branch in handle_thread_rollback.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn uses_explicit_turn_boundaries_for_mid_turn_steering()

Purpose: Ensures multiple user messages inside an explicitly opened turn stay together. This supports mid-turn steering by the user.

Data flow: It creates one explicit turn with two user messages before completion → rebuilds history → asserts both messages are in the same turn.

Call relations: This test covers handle_turn_started, handle_user_message, and handle_turn_complete working together.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn reconstructs_tool_items_from_persisted_completion_events()

Purpose: Checks that completed tool events can rebuild final web search, command, and MCP tool-call items even without begin events.

Data flow: It creates a turn with a user message and several tool completion events → rebuilds history → asserts each tool item has the expected final fields.

Call relations: This test exercises handle_web_search_end, handle_exec_command_end, and handle_mcp_tool_call_end.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn reconstructs_mcp_tool_result_meta_from_persisted_completion_events()

Purpose: Verifies that MCP tool results keep structured content and metadata during replay.

Data flow: It creates an MCP tool completion event with result content, structured content, metadata, URI, and plugin ID → rebuilds history → checks the full item.

Call relations: This test focuses on handle_mcp_tool_call_end result conversion.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn reconstructs_dynamic_tool_items_from_request_and_response_events()

Purpose: Checks that dynamic-tool request and response events combine into one completed dynamic-tool item.

Data flow: It creates a request followed by a successful response with output content → rebuilds history → asserts the final item is completed and contains the converted output.

Call relations: This test exercises handle_dynamic_tool_call_request, handle_dynamic_tool_call_response, and convert_dynamic_tool_content_items.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn reconstructs_declined_exec_and_patch_items()

Purpose: Verifies that declined command and patch events are represented as declined visible items.

Data flow: It creates an explicit turn with a declined command completion and declined patch completion → rebuilds history → checks statuses and displayed details.

Call relations: This test covers handle_exec_command_end and handle_patch_apply_end for declined outcomes.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn reconstructs_declined_guardian_command_item()

Purpose: Checks that a denied guardian assessment becomes a declined command item in history.

Data flow: It creates in-progress and denied guardian assessment events for a command → rebuilds history → asserts the command item is declined.

Call relations: This test exercises handle_guardian_assessment and build_item_from_guardian_event integration.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn reconstructs_in_progress_guardian_execve_item()

Purpose: Verifies that an in-progress guardian assessment for an execve-style command creates an in-progress command item.

Data flow: It creates a guardian assessment containing program and argument data → rebuilds history → checks the reconstructed command string and status.

Call relations: This test covers handle_guardian_assessment for guardian execve actions.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn assigns_late_exec_completion_to_original_turn()

Purpose: Ensures a command completion that arrives after a newer turn starts is still attached to its original turn.

Data flow: It creates turn A, completes it, starts turn B, then sends a command-end event for turn A → rebuilds history → checks the command appears in turn A, not turn B.

Call relations: This test validates the turn-ID routing in handle_exec_command_end and upsert_item_in_turn_id.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn drops_late_turn_scoped_item_for_unknown_turn_id()

Purpose: Checks that a late item with an unknown turn ID is dropped instead of being attached to the wrong active turn.

Data flow: It creates two explicit turns and sends a command-end event for a missing turn ID → finishes history → asserts no extra command item appears.

Call relations: This test covers the warning-and-drop path in upsert_item_in_turn_id.

Call graph: calls 1 internal fn (new); 2 external calls (assert_eq!, vec!).

fn patch_apply_begin_updates_active_turn_snapshot_with_file_change()

Purpose: Verifies that an in-progress patch item appears in the active-turn snapshot before the turn is complete.

Data flow: It starts a turn, adds a user message and patch-begin event → asks for the active snapshot → checks the file-change item is present and in progress.

Call relations: This test covers handle_patch_apply_begin and active_turn_snapshot.

Call graph: calls 1 internal fn (new); 2 external calls (assert_eq!, vec!).

fn apply_patch_approval_request_updates_active_turn_snapshot_with_file_change()

Purpose: Checks that a patch approval request updates the active-turn snapshot immediately.

Data flow: It starts a turn, adds a user message and approval request → reads the active snapshot → asserts the file-change item is visible.

Call relations: This test covers handle_apply_patch_approval_request and snapshot behavior.

Call graph: calls 1 internal fn (new); 2 external calls (assert_eq!, vec!).

fn late_turn_complete_does_not_close_active_turn()

Purpose: Ensures a completion event for an older turn does not close the currently active newer turn.

Data flow: It completes turn A, starts turn B, then sends another completion for turn A before finishing B → rebuilds history → asserts turn B still receives later items.

Call relations: This test validates ID matching in handle_turn_complete.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn late_turn_aborted_does_not_interrupt_active_turn()

Purpose: Ensures an abort event for an older turn does not interrupt the current newer turn.

Data flow: It completes turn A, starts turn B, then sends an abort for turn A → rebuilds history → asserts turn B remains in progress with its items.

Call relations: This test validates ID matching in handle_turn_aborted.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn preserves_compaction_only_turn()

Purpose: Checks that an explicitly started turn containing only a persisted compaction marker is kept.

Data flow: It creates a turn-start, compacted rollout item, and turn-complete sequence → rebuilds history → asserts the empty turn remains.

Call relations: This test covers handle_compacted and the keep/drop rules in finish_current_turn.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn reconstructs_collab_resume_end_item()

Purpose: Verifies that a collaborative-agent resume completion creates the correct resume tool-call item.

Data flow: It creates a user message followed by a collab resume-end event → rebuilds history → checks sender, receiver, status, and agent state.

Call relations: This test exercises handle_collab_resume_end.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn reconstructs_collab_spawn_end_item_with_model_metadata()

Purpose: Checks that spawning a collaborative agent preserves model and reasoning-effort metadata.

Data flow: It creates a spawn-end event with sender, new thread ID, prompt, model, effort, and running status → rebuilds history → asserts all metadata appears in the tool-call item.

Call relations: This test covers handle_collab_agent_spawn_end.

Call graph: calls 2 internal fn (build_turns_from_rollout_items, try_from); 2 external calls (assert_eq!, vec!).

fn reconstructs_interrupted_send_input_as_completed_collab_call()

Purpose: Ensures that redirecting a child agent with an interrupted receiver state is still shown as a completed send-input operation.

Data flow: It creates a collab interaction begin/end pair where the receiver status is interrupted → rebuilds history → checks the tool call is completed while the agent state says interrupted.

Call relations: This test exercises handle_collab_agent_interaction_begin and handle_collab_agent_interaction_end.

Call graph: calls 2 internal fn (build_turns_from_rollout_items, try_from); 2 external calls (assert_eq!, vec!).

fn rollback_failed_error_does_not_mark_turn_failed()

Purpose: Verifies that a rollback-failed error does not incorrectly fail the visible turn.

Data flow: It creates a normal turn followed by a rollback-failed error event → rebuilds history → asserts the turn stays completed and has no error.

Call relations: This test covers the filtering logic in handle_error through affects_turn_status.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn out_of_turn_error_does_not_create_or_fail_a_turn()

Purpose: Checks that an error arriving after a turn is already complete does not create a new failed turn.

Data flow: It creates and completes a turn, then sends a request-level error → rebuilds history → asserts only the completed turn remains.

Call relations: This test validates handle_error when there is no current turn.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn error_then_turn_complete_preserves_failed_status()

Purpose: Ensures that a failed turn remains failed even if a later turn-complete event arrives.

Data flow: It starts a turn, adds a user message, records a stream error, then completes the turn → rebuilds history → asserts the final turn status is failed with error details.

Call relations: This test covers handle_error followed by handle_turn_complete.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 2 external calls (assert_eq!, vec!).

fn rebuilds_hook_prompt_items_from_rollout_response_items()

Purpose: Verifies that special hook-prompt response items are reconstructed into visible hook-prompt history items.

Data flow: It builds a hook prompt response item, places it in an explicit turn, replays the rollout → checks the resulting hook-prompt fragments.

Call relations: This test exercises handle_response_item and parse_hook_prompt_message.

Call graph: calls 2 internal fn (build_turns_from_rollout_items, build_hook_prompt_message); 3 external calls (from_single_hook, assert_eq!, vec!).

fn ignores_plain_user_response_items_in_rollout_replay()

Purpose: Checks that ordinary user response items are ignored during rollout replay. Only hook-prompt response items should become history items.

Data flow: It creates a plain user response item inside a turn → rebuilds history → asserts the turn has no items.

Call relations: This test covers the early-return behavior in handle_response_item.

Call graph: calls 1 internal fn (build_turns_from_rollout_items); 3 external calls (assert!, assert_eq!, vec!).

fn changed_rollout_item_reports_new_item_snapshot()

Purpose: Checks that processing one rollout item with change tracking reports both the new item and the newly created turn metadata.

Data flow: It creates a fresh builder → processes one user-message rollout item with changes enabled → compares the returned change set to the expected item and turn snapshots.

Call relations: This test covers handle_rollout_item_with_changes, collect_changes, and change recording in push_item_in_current_turn and ensure_turn.

Call graph: calls 1 internal fn (new); 5 external calls (default, new, assert_eq!, UserMessage, EventMsg).

fn changed_rollout_item_reports_updated_existing_item_snapshot()

Purpose: Verifies that updating an existing item reports the latest item snapshot, not a duplicate new item.

Data flow: It first processes a web-search begin event → then processes a web-search end event with changes enabled → checks that the change set contains the updated search item.

Call relations: This test exercises upsert_item_in_current_turn and record_changed_item.

Call graph: calls 1 internal fn (new); 4 external calls (assert_eq!, WebSearchBegin, WebSearchEnd, EventMsg).

fn changed_rollout_item_reports_streaming_item_mutation()

Purpose: Checks that mutating an existing reasoning item during streaming is reported as a changed item snapshot.

Data flow: It creates a reasoning summary item → processes raw reasoning content with change tracking → asserts the returned item contains both summary and raw content.

Call relations: This test covers the in-place mutation path in handle_agent_reasoning_raw_content.

Call graph: calls 1 internal fn (new); 4 external calls (assert_eq!, AgentReasoning, AgentReasoningRawContent, EventMsg).

fn changed_rollout_item_reports_turn_completion_metadata()

Purpose: Verifies that turn-start and turn-complete events produce turn metadata changes when tracking is enabled.

Data flow: It processes a start event and checks the in-progress snapshot → processes a user message and completion event → checks the completed timestamp and duration snapshot.

Call relations: This test covers record_changed_pending_turn and record_changed_turn.

Call graph: calls 1 internal fn (new); 7 external calls (default, new, assert_eq!, TurnComplete, TurnStarted, UserMessage, EventMsg).

fn changed_rollout_items_dedupe_updated_item_snapshots()

Purpose: Checks that a batch containing begin and end updates for the same item returns only the final item snapshot.

Data flow: It processes web-search begin and end events as one batch → examines the coalesced change set → confirms only the completed search item is reported.

Call relations: This test exercises handle_rollout_items_with_changes and ThreadHistoryChangeAccumulator::push_item_change.

Call graph: calls 1 internal fn (new); 4 external calls (assert_eq!, WebSearchBegin, WebSearchEnd, EventMsg).

fn changed_rollout_items_dedupe_turn_metadata_snapshots()

Purpose: Checks that a batch with start and complete metadata for the same turn returns only the final turn snapshot.

Data flow: It processes turn-start and turn-complete events as one batch → examines the coalesced change set → confirms the turn is reported as completed with final timing.

Call relations: This test exercises ThreadHistoryChangeAccumulator::push_turn_change.

Call graph: calls 1 internal fn (new); 5 external calls (default, assert_eq!, TurnComplete, TurnStarted, EventMsg).

fn changed_rollout_items_drop_prior_changes_for_removed_turns()

Purpose: Verifies that if a batch creates a turn and then rolls it back, the final change set only says the turn was removed.

Data flow: It processes turn-start, user-message, and rollback events as one batch → examines the coalesced change set → confirms item and turn changes were dropped and only the removed ID remains.

Call relations: This test exercises ThreadHistoryChangeAccumulator::push_removed_turn_id and rollback change recording.

Call graph: calls 1 internal fn (new); 7 external calls (default, new, assert_eq!, ThreadRolledBack, TurnStarted, UserMessage, EventMsg).

fn new(
        codex_home: PathBuf,
        thread_manager: Arc<ThreadManager>,
        thread_store: Arc<dyn ThreadStore>,
        config_manager: ConfigManager,
        arg0_paths: Arg0DispatchPath

Purpose: Creates a reusable importer with all the shared services it needs to turn external sessions into Codex threads. It also creates the gate that prevents two full import batches from running at the same time.

Data flow: It receives the Codex home path, thread manager, thread store, configuration manager, and helper executable paths. It stores those values in a new ExternalAgentSessionImporter, wraps the import gate in shared ownership so cloned importers use the same gate, and returns the ready-to-use importer.

Call relations: This is called when the surrounding request-processing setup builds the session importer. The returned importer is later used by the import flow, especially ExternalAgentSessionImporter::import_sessions, which clones it for individual session work.

Call graph: called by 1 (new); 2 external calls (new, new).

async fn import_sessions(
        &self,
        sessions: Vec<ExternalAgentSessionMigration>,
        mut item_result: ExternalAgentConfigImportItemResult,
    ) -> ExternalAgentConfigImportItemResul

Purpose: Imports a batch of external sessions and updates the user-facing import result with successes and errors. It is the top-level method for this file’s workflow.

Data flow: It takes a list of requested session migrations and an import-result object that is already being built. If the list is empty, it returns the result unchanged. Otherwise it acquires the batch gate, starts importing sessions with limited parallelism, records each success or failure into the result, writes a ledger of completed imports, and returns the updated result.

Call relations: This method is called by the broader external-agent configuration import process when session migrations are part of the import. For each session it hands work to ExternalAgentSessionImporter::import_requested_session. When a session succeeds, it records the success in the import item result; when a failure comes back, it uses record_import_error so the caller can report the problem. At the end it calls record_completed_session_imports to remember which source files have been imported.

Call graph: calls 2 internal fn (record_success, record_import_error); 4 external calls (new, record_completed_session_imports, pin_mut!, iter).

async fn import_requested_session(
        &self,
        session: ExternalAgentSessionMigration,
    ) -> Result<Option<CompletedExternalAgentSessionImport>, SessionImportFailure>

Purpose: Imports one requested external session, if it is valid and still needs importing. It turns preparation and persistence errors into a structured failure that says which source file failed and at what stage.

Data flow: It receives one external session migration request. It first keeps the source path for error reporting, then asks ExternalAgentSessionImporter::prepare_session_import to validate and prepare the session. If preparation says there is nothing to import, it returns no completed import. If preparation succeeds, it sends the prepared session to ExternalAgentSessionImporter::persist_session, then returns a completed-import record containing the source path, source content hash, and new Codex thread id.

Call relations: This is the per-session worker used by ExternalAgentSessionImporter::import_sessions. It coordinates the two main substeps: preparation first, persistence second. Its result is then interpreted by the batch importer as either a success to record, a skipped session, or a failure to show in the import report.

Call graph: calls 2 internal fn (persist_session, prepare_session_import).

async fn prepare_session_import(
        &self,
        session: ExternalAgentSessionMigration,
    ) -> Result<Option<PendingSessionImport>, String>

Purpose: Checks and prepares an external session before Codex tries to save it as a thread. It runs the potentially slow file and validation work away from the async task scheduler so other server work is not blocked.

Data flow: It receives one external session migration request and clones the Codex home path. It then runs prepare_validated_session_import on a blocking worker thread. The result is either a prepared pending import, a clean “nothing to import” answer, or a plain error message explaining what went wrong.

Call relations: This is called by ExternalAgentSessionImporter::import_requested_session before any thread is created. It hands off the heavy preparation work to spawn_blocking, then returns a simplified result so the caller can either skip, continue to persistence, or report a preparation failure.

Call graph: called by 1 (import_requested_session); 2 external calls (clone, spawn_blocking).

async fn persist_session(
        &self,
        session: ImportedExternalAgentSession,
    ) -> Result<ThreadId, String>

Purpose: Saves one prepared external session as a real Codex thread. This is where imported conversation data becomes part of Codex’s normal thread store.

Data flow: It receives a prepared imported session containing the original working folder, optional title, first user message, and saved conversation items. It loads configuration for that working folder, chooses model and instruction information, creates a new thread id, builds thread creation settings and metadata, filters out conversation items that should not be persisted, creates the thread, appends the saved items, updates metadata, persists the thread to storage, shuts it down, and returns the new thread id. If appending items fails after thread creation, it tries to discard the partially created thread before returning an error.

Call relations: This is called by ExternalAgentSessionImporter::import_requested_session after preparation succeeds. It relies on the configuration manager for session-specific settings, the thread manager for model and source information, and the thread store for all thread storage actions. Its returned thread id becomes part of the completed-import record that the batch importer later reports and writes to the import ledger.

Call graph: calls 2 internal fn (load_with_overrides, new); called by 1 (import_requested_session); 5 external calls (default, now, new, env!, format!).

fn should_redact_thread_resume_payloads(client_name: Option<&str>) -> bool

Purpose: Decides whether thread-resume payloads should be redacted for a given client name. It is used to limit this special behavior to the ChatGPT remote Android and iOS clients.

Data flow: It receives an optional client name. If there is no name, it returns false. If there is a name, it checks whether it exactly matches one of the known remote ChatGPT mobile client names, then returns true or false.

Call relations: No caller is shown in the provided function graph, but this function is the gatekeeper for the redaction step. In the wider request flow, code can ask this question before choosing whether to call redact_thread_resume_payloads.

fn redact_thread_resume_payloads(turns: &mut [Turn])

Purpose: Edits a list of conversation turns so the thread-resume response is safe and smaller for selected remote clients. It keeps the shape of MCP tool-call history but hides the large or sensitive parts, and it removes image-generation items entirely.

Data flow: It receives a mutable list of turns. For each turn, it walks through the items in that turn. MCP tool-call items have their arguments replaced with the string "[redacted]"; any successful result is replaced with a small redacted result; any error message is also replaced. Image-generation items are dropped from the list. Other items are left as they were. It does not return a new value; it changes the provided turns in place.

Call relations: The tests redacts_mcp_success_result_and_removes_image_generation and redacts_mcp_error_message call this function after building sample thread data. In normal use, this is the main worker that would run after the caller has decided that the client needs redacted thread-resume payloads. When it needs a replacement MCP result, it uses redacted_mcp_tool_call_result.

Call graph: called by 2 (redacts_mcp_error_message, redacts_mcp_success_result_and_removes_image_generation).

fn redacted_mcp_tool_call_result() -> McpToolCallResult

Purpose: Builds the small placeholder result used when an MCP tool call originally had a successful result. This preserves the fact that there was a result while hiding its actual contents.

Data flow: It takes no input. It creates a new MCP tool-call result whose content is a single text entry containing "[redacted]", and whose structured content and metadata are empty. It returns that replacement result to the caller.

Call relations: redact_thread_resume_payloads uses this helper when it finds an MCP tool-call item with an existing result. The helper centralizes the exact replacement shape so the redaction pass does not have to rebuild it inline each time.

Call graph: 1 external calls (vec!).

fn redacts_mcp_success_result_and_removes_image_generation()

Purpose: Checks the main success case: ordinary messages stay, successful MCP tool-call payloads are redacted, and image-generation items are removed. This protects against future changes accidentally sending back large or sensitive data.

Data flow: It creates a sample thread containing an agent message, a completed MCP tool call with secret-looking arguments and result data, and an image-generation item. It runs redact_thread_resume_payloads on the thread’s turns. It then compares the edited thread items with the expected result: the message is unchanged, the MCP tool call keeps its useful metadata but has redacted payloads, and the image-generation item is gone.

Call relations: This test calls the test_thread helper to build realistic thread data, then calls redact_thread_resume_payloads as the behavior under test. It also compares the final items with expected values, including the same redacted_mcp_tool_call_result shape used by the production redaction code.

Call graph: calls 1 internal fn (redact_thread_resume_payloads); 3 external calls (test_thread, assert_eq!, vec!).

fn redacts_mcp_error_message()

Purpose: Checks the failure case for MCP tool calls. It makes sure that when a tool call failed, both its arguments and its error message are hidden before the thread-resume response is sent.

Data flow: It creates a sample thread with one failed MCP tool call whose arguments and error message contain secret-looking text. It runs redact_thread_resume_payloads. It then verifies that the tool call is still present and still marked as failed, but the arguments and error message have both become "[redacted]".

Call relations: This test uses test_thread to create the sample thread and then calls redact_thread_resume_payloads to exercise the real redaction path. The final assertion documents the expected behavior for MCP errors.

Call graph: calls 1 internal fn (redact_thread_resume_payloads); 3 external calls (test_thread, assert_eq!, vec!).

fn test_thread(items: Vec<ThreadItem>) -> Thread

Purpose: Builds a complete test thread around a supplied list of thread items. It saves the tests from repeating a large amount of setup that is not the focus of the redaction behavior.

Data flow: It receives a list of thread items. It wraps those items inside one completed turn, then wraps that turn inside a thread with fixed test values such as IDs, status, model provider, current working directory, and source. It returns the finished thread object to the test.

Call relations: The two test cases call this helper before running redact_thread_resume_payloads. Its job is to provide realistic enough surrounding data so the tests can focus on how individual thread items are changed.

Call graph: 2 external calls (test_path_buf, vec!).

async fn read_summary_from_rollout(
    path: &Path,
    fallback_provider: &str,
) -> std::io::Result<ConversationSummary>

Purpose: This test-only helper reads a saved conversation rollout file and builds a short ConversationSummary from it. It is used to check that stored conversation files can still be summarized for thread listings.

Data flow: It receives a file path and a fallback model provider name. It reads the start of the file, expects the first record to be session metadata, adds missing sub-agent nickname or role information when needed, finds an updated time from the file metadata, and then tries to extract a preview from the first user message. If no preview can be found, it still returns a summary with empty preview text. If the file is empty or does not start with session metadata, it returns an input/output error.

Call relations: In the test flow, this is the top-level reader for a rollout summary. It relies on with_thread_spawn_agent_metadata to repair agent metadata, asks read_updated_at for a best-effort modification time, and delegates the preview-building path to extract_conversation_summary when the saved file contains a usable first user message.

Call graph: calls 3 internal fn (extract_conversation_summary, read_updated_at, with_thread_spawn_agent_metadata); 4 external calls (to_path_buf, new, other, format!).

fn extract_conversation_summary(
    path: PathBuf,
    head: &[serde_json::Value],
    session_meta: &SessionMeta,
    git: Option<&CoreGitInfo>,
    fallback_provider: &str,
    updated_at: Option<S

Purpose: This test-only helper tries to build a conversation summary from the records already read from the start of a rollout file. Its main job is to find a human-readable preview from the first user message.

Data flow: It receives the rollout path, the already-read JSON records, session metadata, optional Git metadata, a fallback provider, and an optional updated timestamp. It scans the records for response items that represent user messages, strips a known message marker if present, and combines that preview with session details. If it cannot find a user message, it returns nothing.

Call relations: read_summary_from_rollout calls this after it has loaded the file header and session metadata. When this helper succeeds, the caller can return the richer summary immediately; when it fails, the caller falls back to a summary with an empty preview.

Call graph: called by 1 (read_summary_from_rollout); 1 external calls (iter).

fn map_git_info(git_info: &CoreGitInfo) -> ConversationGitInfo

Purpose: This test-only helper converts Git information from the core conversation format into the app-server summary format. Git information means details like the commit, branch, and remote repository URL.

Data flow: It receives core Git metadata. It copies the commit hash, branch name, and repository URL into a ConversationGitInfo value, using None where the source has no value.

Call relations: It is used by the rollout-summary conversion path when a saved conversation includes Git context. That lets the summary and reconstructed thread carry repository details without exposing the core protocol type directly.

fn with_thread_spawn_agent_metadata(
    source: codex_protocol::protocol::SessionSource,
    agent_nickname: Option<String>,
    agent_role: Option<String>,
) -> codex_protocol::protocol::SessionSour

Purpose: This helper fills in missing nickname or role information for a thread spawned by a sub-agent. It preserves the original source unless there is new agent metadata worth adding.

Data flow: It receives a session source plus optional agent nickname and role strings. If both optional values are missing, it returns the source unchanged. If the source describes a sub-agent thread spawn, it returns a new source where the provided nickname or role fills the corresponding fields, while keeping existing values when no replacement is provided. Other kinds of sources pass through unchanged.

Call relations: read_summary_from_rollout calls this while reading session metadata from a rollout file. The goal is to make older or differently shaped metadata look like the newer thread-spawn source format before it is turned into a summary.

Call graph: called by 1 (read_summary_from_rollout); 1 external calls (SubAgent).

fn thread_response_active_permission_profile(
    active_permission_profile: Option<codex_protocol::models::ActivePermissionProfile>,
) -> Option<codex_app_server_protocol::ActivePermissionProfile>

Purpose: This helper converts the currently active permission profile from the core model into the app-server response model. A permission profile is a named set of rules about what the assistant may do.

Data flow: It receives an optional core permission profile. If a profile is present, it converts it into the app-server version; if it is missing, it returns missing as well.

Call relations: Both thread_settings_from_config_snapshot and thread_settings_from_core_snapshot use this while building ThreadSettings. It is the small translation step that keeps the response type independent from the core protocol type.

Call graph: called by 2 (thread_settings_from_config_snapshot, thread_settings_from_core_snapshot).

fn thread_response_sandbox_policy(
    permission_profile: &codex_protocol::models::PermissionProfile,
    cwd: &Path,
) -> codex_app_server_protocol::SandboxPolicy

Purpose: This helper computes the sandbox policy to report for a thread. A sandbox policy is the practical rule set that limits file and system access for safety.

Data flow: It receives a permission profile and the thread’s working directory. It asks the sandboxing layer to produce the compatible sandbox policy for that combination, then converts the result into the app-server response type.

Call relations: thread_settings_from_config_snapshot and thread_settings_from_core_snapshot both call this because they need to show clients the effective safety rules, not just the raw permission profile.

Call graph: called by 2 (thread_settings_from_config_snapshot, thread_settings_from_core_snapshot); 1 external calls (compatibility_sandbox_policy_for_permission_profile).

fn thread_settings_from_config_snapshot(
    config_snapshot: &ThreadConfigSnapshot,
) -> ThreadSettings

Purpose: This function builds a ThreadSettings response from a stored configuration snapshot. It gives clients one clear view of the model, approval rules, sandbox rules, working directory, and assistant behavior settings for a thread.

Data flow: It receives a ThreadConfigSnapshot. It copies basic settings such as working directory, model, provider, service tier, reasoning options, collaboration mode, and personality. It converts approval-related values into response types, computes the sandbox policy from the permission profile and working directory, and converts the active permission profile if one exists. The output is a complete ThreadSettings value.

Call relations: This is used when the app server has a configuration snapshot rather than a core protocol snapshot. Inside that conversion, it calls thread_response_sandbox_policy for the effective sandbox rules and thread_response_active_permission_profile for the optional active profile.

Call graph: calls 3 internal fn (thread_response_active_permission_profile, thread_response_sandbox_policy, cwd).

fn thread_settings_from_core_snapshot(
    snapshot: codex_protocol::protocol::ThreadSettingsSnapshot,
) -> ThreadSettings

Purpose: This function builds the same ThreadSettings response, but from a snapshot produced by the core protocol. It normalizes core thread settings into the app-server shape clients expect.

Data flow: It receives a core ThreadSettingsSnapshot and breaks it into its fields. It computes the sandbox policy using the permission profile and working directory, converts approval and active-profile values into app-server response types, and copies the model, provider, reasoning, collaboration, and personality values into a new ThreadSettings.

Call relations: This is the sibling of thread_settings_from_config_snapshot for data that comes from the running core session. It uses the same two conversion helpers, thread_response_sandbox_policy and thread_response_active_permission_profile, so clients see consistent settings no matter where the snapshot came from.

Call graph: calls 2 internal fn (thread_response_active_permission_profile, thread_response_sandbox_policy).

fn parse_datetime(timestamp: Option<&str>) -> Option<DateTime<Utc>>

Purpose: This test-only helper turns an optional timestamp string into a UTC date-time value. UTC is a shared time standard, useful because saved files may be read on machines in different time zones.

Data flow: It receives either no timestamp or a timestamp string. If a string is present and follows the RFC 3339 date-time format, it parses it and converts it to UTC. If the string is missing or invalid, it returns nothing.

Call relations: summary_to_thread uses this when rebuilding a thread from a conversation summary in tests. That lets the reconstructed thread store creation and update times as numeric timestamps.

Call graph: called by 1 (summary_to_thread).

async fn read_updated_at(path: &Path, created_at: Option<&str>) -> Option<String>

Purpose: This test-only helper finds the best available “last updated” time for a saved rollout file. It prefers the file’s modification time and falls back to the creation timestamp from the session metadata.

Data flow: It receives a file path and an optional created-at timestamp. It asks the operating system for the file metadata, reads the modified time if available, and formats it as an RFC 3339 timestamp with milliseconds. If any of that fails, it returns the provided created-at timestamp instead.

Call relations: read_summary_from_rollout calls this before creating a summary. The summary can then show when the conversation was last touched, even if the rollout itself does not explicitly store an updated time.

Call graph: called by 1 (read_summary_from_rollout); 1 external calls (metadata).

fn thread_started_notification(mut thread: Thread) -> ThreadStartedNotification

Purpose: This helper prepares the notification sent when a thread starts. It deliberately removes the thread’s turns, meaning the message history, so the start event stays small and does not leak conversation contents.

Data flow: It receives a full Thread value. Before wrapping it in a ThreadStartedNotification, it clears the list of turns inside the thread. The returned notification contains the same thread identity and metadata, but no turn history.

Call relations: Other request-processing code can call this when it needs to announce a newly started thread. It does not delegate to other helpers; it performs one focused cleanup before producing the notification object.

fn summary_to_thread(
    summary: ConversationSummary,
    fallback_cwd: &AbsolutePathBuf,
) -> Thread

Purpose: This test-only helper rebuilds a lightweight Thread from a ConversationSummary. It is useful for tests that start with a saved summary but need the app-server thread shape.

Data flow: It receives a conversation summary and a fallback working directory. It parses creation and update times, converts Git metadata, normalizes the saved working directory into an absolute local path, and falls back to the supplied directory if normalization fails. It then creates a Thread marked as not loaded, with no turns, using the summary preview, model provider, source, timestamps, path, Git details, and agent metadata.

Call relations: This sits after the summary-reading path in tests: a summary can be produced from a rollout file and then converted into a thread-like record. It calls parse_datetime for timestamp conversion and uses path-normalization helpers so the reconstructed thread has a usable working directory on the current machine.

Call graph: calls 2 internal fn (parse_datetime, relative_to_current_dir); 2 external calls (new, normalize_for_native_workdir).

fn turn_ids_are_compatible(active_turn_id: Option<&str>, item_turn_id: Option<&str>) -> bool

Purpose: This small helper decides whether two turn identifiers can be treated as referring to the same turn. It is permissive when either side has no identifier, because older or partial rollout records may not always carry one.

Data flow: It receives an optional active turn id and an optional item turn id. If the active id is missing, it accepts the item. If the item id is missing, it also accepts it. If both are present, it returns true only when the strings match.

Call relations: During reverse reconstruction, Session::reconstruct_history_from_rollout uses this helper when attaching turn metadata or closing a turn segment. It prevents metadata from a clearly different turn from being mixed into the active segment, while still allowing incomplete older records to be replayed.

Call graph: called by 1 (reconstruct_history_from_rollout).

fn finalize_active_segment(
    active_segment: ActiveReplaySegment<'a>,
    base_replacement_history: &mut Option<&'a [ResponseItem]>,
    previous_turn_settings: &mut Option<PreviousTurnSettings>,

Purpose: This function takes one completed replay segment and decides which parts of it still matter for the rebuilt session. It applies rollback rules, captures the newest useful checkpoint, and records the latest surviving resume metadata.

Data flow: It receives an accumulated segment plus mutable slots for the chosen replacement history, previous turn settings, reference context item, window id, and pending rollback count. If a rollback still needs to remove user turns, it may skip this whole segment. Otherwise, it fills any still-empty output slots with information from this segment, but only when that segment is the newest surviving source for that kind of data.

Call relations: Session::reconstruct_history_from_rollout builds segments while scanning the rollout backward and calls this function when a segment is complete, or once more at the end for any unfinished segment. The helper hands back the decisions that let the larger reconstruction stop early and later replay only the needed suffix.

Call graph: called by 1 (reconstruct_history_from_rollout); 1 external calls (matches!).

async fn reconstruct_history_from_rollout(
        &self,
        turn_context: &TurnContext,
        rollout_items: &[RolloutItem],
    ) -> RolloutReconstruction

Purpose: This is the main reconstruction routine. Given a saved rollout log, it rebuilds the conversation history and returns the metadata needed to continue the session as if it had never been unloaded.

Data flow: It takes the current turn context and a slice of rollout items. First it scans backward to find the newest surviving replacement-history checkpoint, last relevant turn settings, reference context, and compaction window id, while honoring rollback events. Then it creates a fresh ContextManager and replays the surviving rollout items forward to rebuild the final list of response items. It returns a RolloutReconstruction containing the rebuilt history, optional previous turn settings, optional reference context item, and window id.

Call relations: This method is called when a session needs to resume or fork from persisted rollout data. Inside, it uses turn_ids_are_compatible to safely group turn-scoped records, finalize_active_segment to decide what survives the backward scan, and ContextManager to rebuild history during the forward replay. When it encounters older compaction records without a saved replacement history, it falls back to collect_user_messages and build_compacted_history to recreate a compacted prompt shape as well as it can.

Call graph: calls 5 internal fn (build_compacted_history, collect_user_messages, new, finalize_active_segment, turn_ids_are_compatible); 10 external calls (new, default, new, Latest, is_user_turn_boundary, matches!, iter, once, try_from, try_from).

fn map_session_init_error(err: &anyhow::Error, codex_home: &Path) -> CodexErr

Purpose: This function converts a broad session startup error into the kind of error Codex can show to a user. It tries to find a useful file-system cause first, so the final message can include a concrete fix instead of a generic failure.

Data flow: It takes an error and the Codex home directory path. It looks through the error and its underlying causes, searching for an operating-system input/output error. If a known session-storage problem is found, it returns that clearer fatal error; otherwise it returns a general fatal message that includes the full original error text.

Call relations: This is the public helper within the crate for session rollout startup failures. During session initialization, higher-level startup code can pass its failure here before reporting it. It delegates the detailed interpretation of file-system error kinds to map_rollout_io_error, then hands the resulting CodexErr back to the caller for display or shutdown.

Call graph: 3 external calls (chain, format!, Fatal).

fn map_rollout_io_error(io_err: &std::io::Error, codex_home: &Path) -> Option<CodexErr>

Purpose: This helper turns specific operating-system file errors into practical messages about Codex session storage. It is used when Codex knows the failure happened while preparing or reading the sessions directory.

Data flow: It receives a file-system error and the Codex home directory. It builds the expected sessions directory path, checks what kind of file error occurred, and creates a tailored explanation for known cases such as permission trouble, a missing folder, corrupt data, or the wrong kind of path. It returns a fatal Codex error when it recognizes the problem, or nothing if the error kind is not one it knows how to explain.

Call relations: This function is the specialist called from map_session_init_error after an input/output error has been found inside a larger failure. It supplies the user-friendly wording and then hands that mapped error back up, so the broader session initialization path can report the most helpful message available.

Call graph: 4 external calls (join, kind, format!, Fatal).

fn load_session_for_import(path: &Path) -> io::Result<Option<ImportedExternalAgentSession>>

Purpose: This test-only helper loads an imported session but drops the file content hash from the result. Tests use it when they only care about the imported conversation, not about identifying the exact source file contents.

Data flow: It receives a file path. It asks load_session_for_import_with_content_sha256 to do the real loading, then keeps only the session part if one was found. It returns either no session, a loaded session, or an input/output error from reading the file.

Call relations: The import tests call this as their simple doorway into the importer. It immediately hands the work to load_session_for_import_with_content_sha256, which is the production loader that also returns the content hash.

Call graph: calls 1 internal fn (load_session_for_import_with_content_sha256); called by 7 (adds_import_marker_without_copying_last_agent_message, builds_visible_turns_for_imported_history, emits_token_usage_for_imported_history, loads_ai_title_for_imported_session, loads_custom_title_for_imported_session, loads_custom_title_over_later_ai_title_for_imported_session, stores_imported_messages_as_response_items_and_visible_events).

fn load_session_for_import_with_content_sha256(
    path: &Path,
) -> io::Result<Option<(ImportedExternalAgentSession, String)>>

Purpose: This is the main loader for an external session file. It reads the file, decides whether it contains enough information to import, builds Codex-ready history items, and returns the imported session together with a SHA-256 content hash, which is a fingerprint of the file contents.

Data flow: It takes a path to a session file. It reads parsed session data from read_session_import, checks for a working directory, chooses a title, converts conversation messages into rollout items, and rejects empty imports. If successful, it returns an ImportedExternalAgentSession plus the file hash; otherwise it returns None or a read/parse error.

Call relations: This function is called by the higher-level import flow through load_importable_session, and by the test helper load_session_for_import. After reading the raw import records, it hands the message list to rollout_items_from_messages so the rest of Codex can consume the conversation in its normal internal shape.

Call graph: calls 2 internal fn (rollout_items_from_messages, read_session_import); called by 2 (load_session_for_import, load_importable_session).

fn rollout_items_from_messages(messages: Vec<ConversationMessage>) -> Vec<RolloutItem>

Purpose: This function converts plain imported chat messages into Codex’s internal timeline of turn events, visible messages, stored response messages, token counts, and completion markers. It is the heart of the import translation.

Data flow: It receives a list of imported conversation messages. It walks through them in order, starts a new turn for each user message, adds user and assistant text as both visible events and stored response items, estimates token usage from message byte length, and closes turns when needed. It returns a list of rollout items ready to be shown and saved by Codex.

Call relations: It is called by load_session_for_import_with_content_sha256 after the external file has been parsed. While building the timeline, it uses helper functions such as response_item, message_byte_count, external_session_imported_marker_item, token_count_item, and turn_complete_item to create each specific kind of internal record.

Call graph: calls 5 internal fn (external_session_imported_marker_item, message_byte_count, response_item, token_count_item, turn_complete_item); called by 1 (load_session_for_import_with_content_sha256); 9 external calls (default, new, approx_tokens_from_byte_count_i64, format!, AgentMessage, TurnStarted, UserMessage, EventMsg, ResponseItem).

fn external_session_imported_marker_item() -> RolloutItem

Purpose: This creates the visible marker message that says the previous content came from an external import. It prevents the imported transcript from being mistaken for a live assistant response generated during the current Codex session.

Data flow: It takes no input. It wraps the fixed text <EXTERNAL SESSION IMPORTED> inside an agent-message event and returns that as a rollout item.

Call relations: At the end of rollout_items_from_messages, this marker is inserted into the final open turn. The thread-building code later displays it like an assistant message, making the boundary between imported history and future work clear.

Call graph: called by 1 (rollout_items_from_messages); 2 external calls (AgentMessage, EventMsg).

fn response_item(message: ConversationMessage) -> ResponseItem

Purpose: This converts one imported message into a stored response-message record. That stored form preserves the message in the same structure Codex normally uses for user and assistant conversation content.

Data flow: It receives a ConversationMessage with a role and text. If the role is user, it creates input-text content and labels the message as user; if the role is assistant, it creates output-text content and labels it as assistant. It returns a ResponseItem::Message containing that content.

Call relations: It is called from rollout_items_from_messages for every imported user or assistant message that becomes part of the Codex history. It works alongside the visible event records, so the imported session is available both for display and for stored conversation context.

Call graph: called by 1 (rollout_items_from_messages); 1 external calls (vec!).

fn message_byte_count(message: &ConversationMessage) -> i64

Purpose: This measures how large a message’s text is in bytes, using a safe fallback if the size is too large to fit normally. The importer uses this size to estimate token usage.

Data flow: It receives a reference to a conversation message. It reads the length of the message text, converts that length to a signed number, and returns it; if conversion would overflow, it returns the largest possible signed value instead.

Call relations: It is called by rollout_items_from_messages each time an imported message is counted toward the rough token estimate. That byte count is later passed through an approximate byte-to-token conversion before token_count_item records the usage.

Call graph: called by 1 (rollout_items_from_messages); 1 external calls (try_from).

fn token_count_item(last_model_visible_tokens: i64) -> RolloutItem

Purpose: This creates a token-usage event for the imported history. Tokens are the small text pieces language models count internally, and this event gives Codex a rough idea of how much conversation context the import represents.

Data flow: It receives an estimated number of visible tokens. It puts that number into both the total usage and last usage fields, leaves unknown fields empty, and returns a rollout item containing a token-count event.

Call relations: It is called near the end of rollout_items_from_messages, after message sizes have been accumulated and converted into an approximate token count. The resulting event lets later parts of Codex treat imported history more like normal model conversation history.

Call graph: called by 1 (rollout_items_from_messages); 3 external calls (TokenCount, EventMsg, default).

fn turn_complete_item(turn_id: String, completed_at: Option<i64>) -> RolloutItem

Purpose: This creates the event that says a conversation turn is finished. It is used to close imported turns cleanly in the same way Codex closes live turns.

Data flow: It receives a turn ID and an optional completion timestamp. It builds a turn-complete event with that ID, includes the timestamp if one is known, leaves timing details empty, and returns it as a rollout item.

Call relations: It is called by rollout_items_from_messages when a new user message starts and the previous turn must be closed, and once more at the end to close the final imported turn. The thread-building code depends on these boundaries to group messages into visible turns.

Call graph: called by 1 (rollout_items_from_messages); 2 external calls (TurnComplete, EventMsg).

fn builds_visible_turns_for_imported_history()

Purpose: This test checks that imported messages are grouped into visible turns correctly. It protects the user-facing shape of imported conversations.

Data flow: It creates a temporary project and a fake JSON-lines session file with two user requests and one assistant answer. It imports the file, converts rollout items into thread turns, and checks that there are two visible turns with the expected number of displayed items, including the import marker in the second turn.

Call relations: The test calls load_session_for_import, which exercises the real importer, then calls external thread-building code to see what a user would see. It verifies that rollout_items_from_messages produces turn events that downstream display code can understand.

Call graph: calls 1 internal fn (load_session_for_import); 7 external calls (new, assert_eq!, build_turns_from_rollout_items, jsonl, record, create_dir_all, write).

fn adds_import_marker_without_copying_last_agent_message()

Purpose: This test makes sure the import marker is shown without being stored as the turn’s last real assistant answer. That distinction avoids confusing imported-history bookkeeping with an actual assistant reply.

Data flow: It writes a temporary session containing a user request and assistant answer, imports it, builds visible turns, and confirms that the last displayed item is the import marker. It then looks back through the raw rollout items and checks that the final turn-complete event does not copy that marker into its last_agent_message field.

Call relations: The test goes through load_session_for_import and then inspects both the user-facing thread and the underlying rollout data. It specifically protects the behavior created by external_session_imported_marker_item and turn_complete_item working together.

Call graph: calls 1 internal fn (load_session_for_import); 7 external calls (new, assert_eq!, build_turns_from_rollout_items, jsonl, record, create_dir_all, write).

fn stores_imported_messages_as_response_items_and_visible_events()

Purpose: This test confirms that imported messages are saved in both important forms: visible events for the interface and response items for the stored conversation record.

Data flow: It creates a fake session with a long user request and a long assistant answer, imports it, then counts rollout items. It expects two stored response messages and two matching visible message events.

Call relations: The test calls load_session_for_import, which reaches rollout_items_from_messages. It checks that the converter calls response_item while also emitting user-message and agent-message events.

Call graph: calls 1 internal fn (load_session_for_import); 6 external calls (new, assert_eq!, jsonl, record, create_dir_all, write).

fn loads_custom_title_for_imported_session()

Purpose: This test checks that a title explicitly provided by the source app is used for the imported session. That lets an imported chat keep the name the user or source tool gave it.

Data flow: It writes a temporary session containing a user message and a custom-title record. After importing the session, it reads the imported title and checks that it matches the custom title.

Call relations: The test calls load_session_for_import, which relies on the parsed data returned by read_session_import. It verifies the title-selection part of load_session_for_import_with_content_sha256.

Call graph: calls 1 internal fn (load_session_for_import); 7 external calls (new, assert_eq!, custom_title_record, jsonl, record, create_dir_all, write).

fn loads_ai_title_for_imported_session()

Purpose: This test checks that an AI-generated title from the source app can also become the imported session title. This preserves useful naming even when the title was generated automatically.

Data flow: It writes a temporary session with a user message and an AI-title record. It imports the file and checks that the resulting session title is the AI-provided title.

Call relations: The test uses load_session_for_import to exercise the real loading path. It confirms that the parser and load_session_for_import_with_content_sha256 pass through source titles, not just message text summaries.

Call graph: calls 1 internal fn (load_session_for_import); 7 external calls (new, assert_eq!, ai_title_record, jsonl, record, create_dir_all, write).

fn loads_custom_title_over_later_ai_title_for_imported_session()

Purpose: This test makes sure a custom title wins over a later AI-generated title. In human terms, a user-chosen name should not be overwritten by an automatic suggestion.

Data flow: It creates a fake session with a user message, a custom-title record, and then an AI-title record. After import, it checks that the final title is still the custom one.

Call relations: The test calls load_session_for_import and depends on read_session_import preserving title priority before the loader chooses the session title. It protects the rule that user/source custom naming takes precedence.

Call graph: calls 1 internal fn (load_session_for_import); 8 external calls (new, assert_eq!, ai_title_record, custom_title_record, jsonl, record, create_dir_all, write).

fn emits_token_usage_for_imported_history()

Purpose: This test checks that imported history includes a token-count event. That matters because later parts of Codex use token counts to understand how much text is already in the conversation.

Data flow: It writes a temporary session with two user messages and one assistant message, imports it, searches the rollout items for a token-count event, and verifies that the reported token count is greater than zero and internally consistent.

Call relations: The test exercises load_session_for_import, which reaches rollout_items_from_messages and token_count_item. It protects the importer’s promise that imported sessions carry approximate usage information.

Call graph: calls 1 internal fn (load_session_for_import); 7 external calls (new, assert!, assert_eq!, jsonl, record, create_dir_all, write).

fn record(role: &str, text: &str, cwd: &Path) -> JsonValue

Purpose: This test helper builds one fake chat-message record in the same JSON shape expected from an external session file. It keeps the test setup short and consistent.

Data flow: It receives a role name, message text, and working-directory path. It adds the current timestamp and returns a JSON object containing the type, directory, timestamp, and message content.

Call relations: Most tests call this helper when writing temporary JSON-lines session files. Those files are then passed into load_session_for_import, allowing the tests to exercise the importer with realistic input.

Call graph: 2 external calls (now, json!).

fn custom_title_record(title: &str) -> JsonValue

Purpose: This test helper builds a fake JSON record for a custom session title. Tests use it to check how imported titles are chosen.

Data flow: It receives a title string. It returns a JSON object whose type is custom-title and whose custom title field contains that string.

Call relations: Title-related tests include this record in their temporary session files before calling load_session_for_import. It supplies the input needed to verify custom-title behavior.

Call graph: 1 external calls (json!).

fn ai_title_record(title: &str) -> JsonValue

Purpose: This test helper builds a fake JSON record for an AI-generated session title. It lets tests cover automatically generated source titles without repeating JSON details.

Data flow: It receives a title string. It returns a JSON object whose type is ai-title and whose AI title field contains that string.

Call relations: The AI-title tests write this record into temporary JSON-lines files and then call load_session_for_import. It provides the source data used to confirm AI-title import behavior and title priority rules.

Call graph: 1 external calls (json!).

fn jsonl(records: &[JsonValue]) -> String

Purpose: This test helper turns a list of JSON records into JSON Lines text, where each record is one JSON object on its own line. That matches the file format the importer reads.

Data flow: It receives a slice of JSON values. It converts each value to text, joins them with newline characters, and returns the resulting string for writing to a temporary session file.

Call relations: All the import tests use this helper before writing their fake session files to disk. The resulting file is then read through load_session_for_import, so tests start from the same line-based format as real imports.

Call graph: 1 external calls (iter).

fn is_persisted_rollout_item(item: &RolloutItem) -> bool

Purpose: This is the main yes-or-no check for whether one rollout item should be written to the saved rollout history. It looks at the broad kind of item first, then uses the more detailed policy for response items or event messages.

Data flow: It receives one RolloutItem. If the item wraps a model response, it asks should_persist_response_item. If it wraps an event message, it asks should_persist_event_msg. If it is inter-agent communication or one of the important session/executive markers, it keeps it. The output is a boolean: true means save it, false means leave it out.

Call relations: persisted_rollout_items calls this function while scanning a batch of rollout items. This function is the middle step: it understands the outer RolloutItem shape, then hands the detailed decision to should_persist_response_item or should_persist_event_msg when needed.

Call graph: calls 2 internal fn (should_persist_event_msg, should_persist_response_item); called by 1 (persisted_rollout_items).

fn persisted_rollout_items(items: &[RolloutItem]) -> Vec<RolloutItem>

Purpose: This function takes a list of rollout items and returns only the ones that should be saved. It is used when appending live activity to a rollout file so the file receives the canonical, filtered set.

Data flow: It receives a slice of RolloutItem values. It starts with a new empty list, checks each item with is_persisted_rollout_item, clones the items that pass the policy, and skips the ones that do not. The output is a new Vec of RolloutItem values containing only the saved records.

Call relations: This is the batch-level entry into the policy in this file. It repeatedly calls is_persisted_rollout_item, which then delegates to the response-item or event-message rules. The result is ready for the rollout-writing code to append without carrying unwanted temporary events.

Call graph: calls 1 internal fn (is_persisted_rollout_item); 1 external calls (new).

fn should_persist_response_item(item: &ResponseItem) -> bool

Purpose: This function decides whether a model response item should be saved in rollout files. It keeps the response records that represent meaningful conversation content, tool calls, tool results, searches, image generation, and compaction records, while dropping items that are only triggers or unknown placeholders.

Data flow: It receives a ResponseItem. It compares the item against the known response variants. Most substantive response items produce true. CompactionTrigger and Other produce false. The result is a boolean that tells the caller whether this response item belongs in the rollout history.

Call relations: is_persisted_rollout_item calls this when it sees a RolloutItem::ResponseItem. This function does not call other project functions; it is the response-specific checklist used by the top-level rollout filter.

Call graph: called by 1 (is_persisted_rollout_item).

fn should_persist_response_item_for_memories(item: &ResponseItem) -> bool

Purpose: This function applies a separate saving rule for memories, which are long-term records used later as context. It is more selective than rollout persistence because memories should avoid some internal or sensitive system material, such as developer-role messages.

Data flow: It receives a ResponseItem. For normal messages, it reads the message role and keeps it unless the role is "developer". It also keeps several tool-call and tool-output records. It rejects agent-only messages, reasoning, image generation calls, compaction records, triggers, context compaction, and unknown items. The output is true if the response item may be stored for memories, otherwise false.

Call relations: This function is a standalone policy helper in this file. It is not called by the other listed functions here, which means memory-saving code elsewhere can use it without going through the rollout-file policy.

fn should_persist_event_msg(ev: &EventMsg) -> bool

Purpose: This function decides whether an event message should be saved in rollout files. It keeps important milestones that are useful for replaying or understanding a run, and drops short-lived lifecycle, streaming, approval, startup, and progress events.

Data flow: It receives an EventMsg. It checks the event against a long explicit list. User and agent messages, reasoning summaries, patch completion, token counts, turn start and finish, web search completion, image generation completion, sub-agent activity, and similar durable events return true. Many begin-events, deltas, requests, warnings, setup notices, and transient collaboration or tool events return false. For ItemCompleted, it looks more closely and only keeps completions for plan and sleep items, because those do not have another raw item form to replay from. The output is a boolean decision.

Call relations: is_persisted_rollout_item calls this when a rollout item contains an EventMsg. Inside the ItemCompleted case, it uses Rust's matches! helper to make the special plan-or-sleep check concise. This function is the event-specific half of the rollout persistence policy.

Call graph: called by 1 (is_persisted_rollout_item); 1 external calls (matches!).

fn builder_from_session_meta(
    session_meta: &SessionMetaLine,
    rollout_path: &Path,
) -> Option<ThreadMetadataBuilder>

Purpose: Creates a metadata builder from the explicit session metadata stored inside a rollout file. This is the best source of truth because it was written by the session itself.

Data flow: It receives a session metadata line and the path to the rollout file. It parses the session timestamp into a UTC time, copies identity, source, model, agent, working directory, CLI version, and git details into a ThreadMetadataBuilder, and sets safe defaults for sandbox and approval settings. If the timestamp cannot be understood, it returns nothing.

Call relations: builder_from_items calls this when it finds a SessionMeta item in the rollout. This function does the focused work of turning that one rich metadata record into the builder that later becomes full thread metadata.

Call graph: calls 2 internal fn (parse_timestamp_to_utc, new); called by 1 (builder_from_items); 2 external calls (to_path_buf, new_read_only_policy).

fn builder_from_items(
    items: &[RolloutItem],
    rollout_path: &Path,
) -> Option<ThreadMetadataBuilder>

Purpose: Finds enough information in a rollout file’s items to start building thread metadata. It prefers real embedded session metadata, but can fall back to the rollout filename when older or incomplete files do not contain it.

Data flow: It receives all parsed rollout items and the rollout file path. First it searches the items for a SessionMeta record and, if found, delegates to builder_from_session_meta. If not found, it reads the file name, strips any compression-related naming, parses a timestamp and UUID from it, converts those into a creation time and thread id, and returns a basic metadata builder. If any required clue is missing or malformed, it returns nothing.

Call relations: extract_metadata_from_rollout uses this as the first step after loading a file. The call graph also shows apply_rollout_items using it in related reconstruction flows. It hands back the starting point that later rollout items can refine.

Call graph: calls 4 internal fn (from_string, parse_timestamp_uuid_from_filename, builder_from_session_meta, new); called by 2 (extract_metadata_from_rollout, apply_rollout_items); 6 external calls (from_timestamp, file_name, to_path_buf, default, parse_rollout_file_name, iter).

async fn extract_metadata_from_rollout(
    rollout_path: &Path,
    default_provider: &str,
) -> anyhow::Result<ExtractionOutcome>

Purpose: Reads one rollout file and produces the final metadata summary that should be stored in the state database. This is the single-file extraction path used by backfill and reconciliation code.

Data flow: It receives a rollout path and a default model provider name. It loads the rollout items from disk, rejects empty files, builds initial metadata with builder_from_items, then walks every item and applies any metadata-changing information to the summary. It also uses the file’s modified time as the updated-at time when available. It returns an ExtractionOutcome containing the finished metadata, the most recent memory mode found in session metadata, and a count of parse errors.

Call relations: backfill_sessions_with_lease calls this for each discovered rollout file. Other flows such as resume matching and rollout reconciliation also call it when they need to compare or rebuild metadata from the saved file. It relies on RolloutRecorder for reading the file and on apply_rollout_item from the state layer for interpreting each saved item.

Call graph: calls 3 internal fn (builder_from_items, file_modified_time_utc, load_rollout_items); called by 4 (backfill_sessions_with_lease, resume_candidate_matches_cwd, reconcile_rollout, reconcile_rollout_preserves_existing_explicit_title); 2 external calls (anyhow!, apply_rollout_item).

async fn backfill_sessions(
    runtime: &codex_state::StateRuntime,
    codex_home: &Path,
    default_provider: &str,
)

Purpose: Starts the normal session metadata backfill using the standard lease duration. It is a small wrapper so callers do not need to know the lease setting.

Data flow: It receives the state runtime, the Codex home directory, and the default provider. It passes those values plus the built-in lease length to backfill_sessions_with_lease. It does not return a value; its effect is to start and await the backfill work.

Call relations: wait_for_backfill_gate calls this when the system needs database metadata to be populated before proceeding. It delegates all real work to backfill_sessions_with_lease.

Call graph: calls 1 internal fn (backfill_sessions_with_lease); called by 1 (wait_for_backfill_gate).

async fn backfill_sessions_with_lease(
    runtime: &codex_state::StateRuntime,
    codex_home: &Path,
    default_provider: &str,
    backfill_lease_seconds: i64,
)

Purpose: Scans saved session files and writes their metadata into the state database, while making sure only one worker does that job at a time. This is the main backfill engine.

Data flow: It receives a state runtime, the Codex home path, the default provider, and a lease duration. It reads the current backfill state, tries to claim the lease, marks the job running, finds rollout files under active and archived session folders, sorts them by a stable watermark, and skips anything already checkpointed. For each file it extracts metadata, normalizes the working directory, preserves useful existing database fields when appropriate, fills archive time for archived files, upserts the thread metadata, and restores memory mode. After each batch it checkpoints progress, and at the end it marks the backfill complete. It also logs warnings and records metrics for successes, failures, parse errors, and duration.

Call relations: backfill_sessions calls this with the normal lease, and wait_for_backfill_gate can call it directly in controlled flows such as tests or gatekeeping. It calls collect_rollout_paths to find files, extract_metadata_from_rollout to understand each file, file_modified_time_utc for timestamps, normalize_cwd_for_state_db before database storage, and state runtime methods to read, claim, checkpoint, and update the database.

Call graph: calls 5 internal fn (collect_rollout_paths, extract_metadata_from_rollout, file_modified_time_utc, normalize_cwd_for_state_db, default); called by 2 (backfill_sessions, wait_for_backfill_gate); 15 external calls (default, join, new, global, info!, checkpoint_backfill, get_backfill_state, get_thread, mark_backfill_complete, mark_backfill_running (+5 more)).

fn backfill_watermark_for_path(codex_home: &Path, path: &Path) -> String

Purpose: Creates the stable progress marker used to know how far the backfill has scanned. The marker is based on the rollout path relative to the Codex home directory.

Data flow: It receives the Codex home path and a rollout file path. It tries to remove the home directory prefix, converts the remaining path to text, and changes Windows-style backslashes into forward slashes. It returns that normalized string as the watermark.

Call relations: backfill_sessions_with_lease uses this when collecting rollout files, so it can sort them and later checkpoint progress. The function is not shown as being called elsewhere; it exists to keep watermark formatting consistent.

Call graph: 1 external calls (strip_prefix).

async fn file_modified_time_utc(path: &Path) -> Option<DateTime<Utc>>

Purpose: Reads a file’s last modified time and converts it into a UTC timestamp. This gives metadata a reasonable updated or archived time when the rollout contents do not provide one directly.

Data flow: It receives a file path. It asks the compression/file helper for the modified time, handles missing or failed reads by returning nothing, and converts the timestamp into a DateTime in UTC when possible. The output is either a usable UTC time or no value.

Call relations: extract_metadata_from_rollout uses this to set a session’s updated-at time from the rollout file. backfill_sessions_with_lease uses it as a fallback archived-at time for files found in the archived sessions folder.

Call graph: calls 1 internal fn (file_modified_time); called by 2 (backfill_sessions_with_lease, extract_metadata_from_rollout); 1 external calls (from_timestamp).

fn parse_timestamp_to_utc(ts: &str) -> Option<DateTime<Utc>>

Purpose: Parses the timestamp text stored in session metadata into a UTC time. It supports both the project’s filename-like timestamp format and standard RFC 3339 timestamps, which are common internet date strings like 2024-01-01T12:00:00Z.

Data flow: It receives a timestamp string. It first tries the local rollout filename style, then tries RFC 3339. If parsing succeeds, it returns the equivalent UTC time, trimming nanoseconds for the filename-style format. If neither format matches, it returns nothing.

Call relations: builder_from_session_meta calls this before it can create a metadata builder. If this parsing fails, that explicit metadata line cannot be used for builder creation.

Call graph: called by 1 (builder_from_session_meta); 3 external calls (from_naive_utc_and_offset, parse_from_rfc3339, parse_from_str).

async fn collect_rollout_paths(root: &Path) -> std::io::Result<Vec<PathBuf>>

Purpose: Finds rollout files under a directory tree. It is the file-system search step used before backfill can extract metadata.

Data flow: It receives a root directory. It walks through that directory and all nested directories using a stack, reads entries asynchronously, skips unreadable entries with warnings, descends into folders, ignores non-files, and uses the rollout file recognizer to keep only valid rollout files. It returns a list of paths to those rollout files.

Call relations: backfill_sessions_with_lease calls this separately for the active sessions folder and the archived sessions folder. It hands back the raw file list that the backfill code turns into sorted, checkpointable work.

Call graph: calls 1 internal fn (from_path); called by 1 (backfill_sessions_with_lease); 4 external calls (new, read_dir, vec!, warn!).

fn apply_rollout_item(
    metadata: &mut ThreadMetadata,
    item: &RolloutItem,
    default_provider: &str,
)

Purpose: Updates a thread summary using one item from the saved conversation history. This is the main entry point for turning detailed rollout records into the compact metadata stored for a thread.

Data flow: It receives a mutable ThreadMetadata record, one RolloutItem, and a fallback model provider name. It inspects the item type, passes it to the helper for that type, then fills in the fallback provider if the metadata still has no provider. The same metadata object is changed in place; nothing separate is returned.

Call relations: The tests call this function to exercise the real update path. During that path it delegates session records to apply_session_meta_from_item, turn settings to apply_turn_context, events to apply_event_msg, and response items to apply_response_item.

Call graph: calls 4 internal fn (apply_event_msg, apply_response_item, apply_session_meta_from_item, apply_turn_context); called by 10 (event_msg_blank_user_message_without_images_keeps_first_user_message_empty, event_msg_image_only_user_message_sets_image_placeholder_preview, event_msg_thread_goal_sets_preview_only_and_later_user_sets_message_title, event_msg_user_messages_set_title_and_first_user_message, response_item_user_messages_do_not_set_title_or_first_user_message, session_meta_does_not_set_model_or_reasoning_effort, turn_context_does_not_override_session_cwd, turn_context_sets_cwd_when_session_cwd_missing, turn_context_sets_model_and_reasoning_effort, turn_context_sets_permission_profile_metadata).

fn rollout_item_affects_thread_metadata(item: &RolloutItem) -> bool

Purpose: Answers whether a rollout item is worth considering when updating the thread summary stored in SQLite, the local database. It helps avoid unnecessary work for records that cannot change metadata.

Data flow: It receives a RolloutItem and checks its variant. It returns true for session metadata, turn context, token counts, user messages, and thread goal updates; it returns false for other event types, response items, inter-agent communication, and compacted records.

Call relations: This is a filtering helper. Code that scans rollout history can use it before deciding whether to run metadata extraction, while the actual field updates happen through apply_rollout_item and its helpers.

fn apply_session_meta_from_item(metadata: &mut ThreadMetadata, meta_line: &SessionMetaLine)

Purpose: Copies stable session-level facts into the thread summary. These are facts like where the session came from, which working directory it used, which CLI version created it, and what Git repository it was in.

Data flow: It receives mutable metadata and a SessionMetaLine. First it checks that the session metadata belongs to the same thread ID; if not, it ignores it to avoid mixing in data from a forked source thread. If it matches, it writes session source, thread source, agent fields, provider, CLI version, working directory, and optional Git commit, branch, and remote URL into the metadata.

Call relations: apply_rollout_item calls this when it sees a session metadata rollout item. It uses enum_to_string to turn enum-like protocol values into the plain strings stored in metadata.

Call graph: calls 1 internal fn (enum_to_string); called by 1 (apply_rollout_item).

fn apply_turn_context(metadata: &mut ThreadMetadata, turn_ctx: &TurnContextItem)

Purpose: Copies facts about a particular conversation turn into the thread summary. This includes the model, reasoning effort, approval behavior, and sandbox or permission settings.

Data flow: It receives mutable metadata and a TurnContextItem. If the metadata has no working directory yet, it uses the turn’s folder as a fallback. It then stores the model, reasoning effort, serialized permission profile, and approval mode. The metadata is changed in place.

Call relations: apply_rollout_item calls this for turn context records. It calls permission_profile on the turn context to get the effective safety profile, serializes it to text for storage, and uses enum_to_string to store the approval policy as a simple string.

Call graph: calls 2 internal fn (permission_profile, enum_to_string); called by 1 (apply_rollout_item); 1 external calls (to_string).

fn apply_event_msg(metadata: &mut ThreadMetadata, event: &EventMsg)

Purpose: Extracts metadata from live event messages, such as token counts, user prompts, and thread goal updates. These events are what usually provide the visible title and preview for a thread.

Data flow: It receives mutable metadata and an EventMsg. For token counts, it records the latest nonnegative total token use. For user messages, it builds a preview, records the first user message if none exists, sets the preview only if it is still empty, and creates a title from the message text if the title is empty. For thread goal updates, it uses the goal objective as a preview if no preview has been set.

Call relations: apply_rollout_item calls this for event message records. It relies on user_message_preview to make readable preview text, strip_user_message_prefix to remove protocol wrapping from raw user text, and set_preview_if_empty so earlier previews are not overwritten.

Call graph: calls 3 internal fn (set_preview_if_empty, strip_user_message_prefix, user_message_preview); called by 1 (apply_rollout_item).

fn apply_response_item(_metadata: &mut ThreadMetadata, _item: &ResponseItem)

Purpose: Currently does nothing for response items. Its presence makes the dispatch in apply_rollout_item explicit and leaves a clear place to add response-derived metadata later if needed.

Data flow: It receives mutable metadata and a ResponseItem, but it does not read or change either value. The metadata before and after the call is the same.

Call relations: apply_rollout_item calls this when it sees a response item. The tests confirm an important consequence: even response items with role "user" do not set the thread title or first user message.

Call graph: called by 1 (apply_rollout_item).

fn set_preview_if_empty(metadata: &mut ThreadMetadata, preview: Option<String>)

Purpose: Sets the thread preview only if no preview has been chosen yet. This protects the first useful preview from being overwritten by later events.

Data flow: It receives mutable metadata and an optional preview string. If metadata.preview is empty, it stores the provided value; if a preview already exists, it leaves it unchanged.

Call relations: apply_event_msg calls this when processing user messages and thread goal updates. This is why an early goal preview can remain visible even after a later user message arrives.

Call graph: called by 1 (apply_event_msg).

fn strip_user_message_prefix(text: &str) -> &str

Purpose: Removes the protocol marker that can appear before the real user text. This turns stored wire-format text into something a person would expect to see as a title or preview.

Data flow: It receives raw text. If it finds the USER_MESSAGE_BEGIN marker, it returns the text after that marker with surrounding whitespace removed. If the marker is not present, it returns the trimmed original text.

Call relations: apply_event_msg uses it when forming a title, and user_message_preview uses it when forming preview text. It is the shared cleanup step for user-facing message text.

Call graph: called by 2 (apply_event_msg, user_message_preview).

fn user_message_preview(user: &UserMessageEvent) -> Option<String>

Purpose: Builds a short readable preview for a user message. It prefers actual text, but if the message only contains images it returns the placeholder “[Image]”.

Data flow: It receives a UserMessageEvent. It strips any protocol prefix from the message text; if text remains, it returns that text. If the text is empty but remote or local images are present, it returns the image placeholder. If there is neither text nor images, it returns no preview.

Call relations: apply_event_msg calls this when it sees a user message. It calls strip_user_message_prefix so preview text and title text are cleaned in the same way.

Call graph: calls 1 internal fn (strip_user_message_prefix); called by 1 (apply_event_msg).

fn enum_to_string(value: &T) -> String

Purpose: Converts serializable enum-like values into the plain strings used in ThreadMetadata. This avoids storing Rust debug formatting and instead uses the protocol’s JSON representation.

Data flow: It receives any value that can be serialized. It asks serde_json to turn it into a JSON value. If that JSON value is a string, it returns the string; if it is another JSON shape, it returns that shape as text; if serialization fails, it returns an empty string.

Call relations: apply_session_meta_from_item and apply_turn_context call this for fields such as session source and approval mode. Other parts of the crate, including build and test_thread_metadata according to the call graph, also use it when they need the same plain-string conversion.

Call graph: called by 4 (apply_session_meta_from_item, apply_turn_context, build, test_thread_metadata); 2 external calls (new, to_value).

fn response_item_user_messages_do_not_set_title_or_first_user_message()

Purpose: Checks that response items do not count as incoming user messages for metadata purposes. This protects titles and first-message fields from being filled by the wrong kind of record.

Data flow: It creates test metadata and a response item whose role is "user" and whose content says hello. After passing that item through apply_rollout_item, it verifies that first_user_message, preview, and title are still empty.

Call relations: This test calls apply_rollout_item to prove the production dispatch reaches apply_response_item and leaves user-facing metadata unchanged for response items.

Call graph: calls 1 internal fn (apply_rollout_item); 4 external calls (assert_eq!, ResponseItem, metadata_for_test, vec!).

fn event_msg_user_messages_set_title_and_first_user_message()

Purpose: Checks the normal happy path for a real user event. A user message event should set the first user message, preview, and title.

Data flow: It creates test metadata and a user message event containing the protocol marker followed by real text. After apply_rollout_item runs, it expects the marker to be removed and the cleaned text to appear in first_user_message, preview, and title.

Call relations: This test drives apply_rollout_item through apply_event_msg, which then uses user_message_preview and strip_user_message_prefix.

Call graph: calls 1 internal fn (apply_rollout_item); 7 external calls (default, assert_eq!, format!, UserMessage, EventMsg, metadata_for_test, vec!).

fn event_msg_image_only_user_message_sets_image_placeholder_preview()

Purpose: Checks that an image-only user message still produces a useful preview. Instead of showing nothing, the metadata should show the placeholder “[Image]”.

Data flow: It creates test metadata and a user message event with no text but with an image URL. After apply_rollout_item runs, it verifies that first_user_message and preview contain the image placeholder, while title remains empty because there was no text to title the thread with.

Call relations: This test exercises apply_rollout_item and apply_event_msg, especially the image branch inside user_message_preview.

Call graph: calls 1 internal fn (apply_rollout_item); 7 external calls (default, new, assert_eq!, UserMessage, EventMsg, metadata_for_test, vec!).

fn event_msg_blank_user_message_without_images_keeps_first_user_message_empty()

Purpose: Checks that a blank user message with no images does not create misleading metadata. Empty input should not become a fake title or preview.

Data flow: It creates test metadata and a user message event containing only whitespace and no images. After apply_rollout_item runs, it verifies that first_user_message, preview, and title remain empty.

Call relations: This test calls apply_rollout_item to cover the path where apply_event_msg asks user_message_preview for text and receives no usable preview.

Call graph: calls 1 internal fn (apply_rollout_item); 6 external calls (default, assert_eq!, UserMessage, EventMsg, metadata_for_test, vec!).

fn event_msg_thread_goal_sets_preview_only_and_later_user_sets_message_title()

Purpose: Checks how goal updates and later user messages share metadata fields. A thread goal can provide an early preview, but it should not become the first user message or title.

Data flow: It first applies a thread goal update with the objective “optimize the benchmark” and confirms that only preview is set. It then applies a normal user message and confirms that the existing preview stays the same, while first_user_message and title are filled from the later prompt.

Call relations: This test calls apply_rollout_item twice. The first call reaches the thread-goal branch of apply_event_msg and set_preview_if_empty; the second reaches the user-message branch and proves set_preview_if_empty does not overwrite the earlier preview.

Call graph: calls 1 internal fn (apply_rollout_item); 8 external calls (default, assert_eq!, format!, ThreadGoalUpdated, UserMessage, EventMsg, metadata_for_test, vec!).

fn turn_context_does_not_override_session_cwd()

Purpose: Checks that the session’s working directory wins over a later turn context directory. This matters for forked or copied histories where turn context might describe a parent workspace instead of the child thread’s real workspace.

Data flow: It starts with metadata whose working directory is empty, applies session metadata with a child worktree path, then applies turn context with a different parent workspace path. It verifies that the child path remains, and also checks that sandbox and approval metadata are stored in their expected text forms.

Call relations: This test calls apply_rollout_item first through apply_session_meta_from_item and then through apply_turn_context. It documents the rule that turn context only fills the working directory when session metadata has not already done so.

Call graph: calls 2 internal fn (from_string, apply_rollout_item); 7 external calls (from, new, now_v7, assert_eq!, SessionMeta, TurnContext, metadata_for_test).

fn turn_context_sets_permission_profile_metadata()

Purpose: Checks that a turn’s explicit permission profile is what gets stored as sandbox metadata. This ensures the summary reflects the effective safety permissions rather than an older or less precise field.

Data flow: It creates a workspace-write permission profile and places it in a turn context. After apply_rollout_item runs, it compares metadata.sandbox_policy with the JSON text for that same permission profile.

Call relations: This test drives apply_rollout_item into apply_turn_context, covering the call to the turn context’s permission_profile logic and the JSON serialization step.

Call graph: calls 2 internal fn (workspace_write, apply_rollout_item); 4 external calls (from, assert_eq!, TurnContext, metadata_for_test).

fn turn_context_sets_cwd_when_session_cwd_missing()

Purpose: Checks the fallback behavior for working directories. If session metadata did not provide a folder, the turn context folder should be used.

Data flow: It clears the test metadata’s working directory, then applies a turn context with a fallback workspace path. After apply_rollout_item runs, it verifies that metadata.cwd now contains that fallback path.

Call relations: This test calls apply_rollout_item and reaches apply_turn_context. It complements the non-overwrite test by showing when turn context is allowed to set the working directory.

Call graph: calls 1 internal fn (apply_rollout_item); 6 external calls (from, new, new_read_only_policy, assert_eq!, TurnContext, metadata_for_test).

fn turn_context_sets_model_and_reasoning_effort()

Purpose: Checks that turn context records populate the model and reasoning effort fields. These fields describe how the assistant was configured for that turn.

Data flow: It creates a turn context with model “gpt-5” and high reasoning effort. After apply_rollout_item runs, it verifies that those values were copied into the metadata.

Call relations: This test calls apply_rollout_item to exercise apply_turn_context’s model and reasoning-effort assignments.

Call graph: calls 1 internal fn (apply_rollout_item); 5 external calls (from, new_read_only_policy, assert_eq!, TurnContext, metadata_for_test).

fn session_meta_does_not_set_model_or_reasoning_effort()

Purpose: Checks that session metadata does not fill fields that belong to turn context. This keeps long-lived session facts separate from per-turn model settings.

Data flow: It creates session metadata with normal session information and applies it to test metadata. After apply_rollout_item runs, it verifies that model and reasoning_effort are still unset.

Call relations: This test calls apply_rollout_item through apply_session_meta_from_item and confirms that model-specific fields are only set by apply_turn_context.

Call graph: calls 1 internal fn (apply_rollout_item); 4 external calls (from, assert_eq!, SessionMeta, metadata_for_test).

fn metadata_for_test() -> ThreadMetadata

Purpose: Builds a complete, predictable ThreadMetadata value for the tests. It keeps the tests focused on the one field or behavior they are checking.

Data flow: It creates a fixed thread ID, timestamp, rollout path, provider, working directory, CLI version, token count, and other default metadata fields. It returns a ThreadMetadata object that each test can modify or pass into apply_rollout_item.

Call relations: Most tests call this helper before exercising apply_rollout_item or metadata comparison. It is test support code, not part of the production metadata extraction flow.

Call graph: calls 1 internal fn (from_string); 4 external calls (from_timestamp, from, new, from_u128).

fn diff_fields_detects_changes()

Purpose: Checks that ThreadMetadata can report which fields differ between two metadata records. Although the diff method lives on the model type, this test confirms it behaves as expected with metadata shaped like this file produces.

Data flow: It creates a base metadata record, clones it, changes the clone’s token count and title, then asks the base record for the changed field names. It expects exactly “title” and “tokens_used”.

Call relations: This test uses metadata_for_test to create realistic metadata and then calls ThreadMetadata::diff_fields. It is included here because the extraction tests also rely on accurate metadata field behavior.

Call graph: calls 1 internal fn (from_string); 3 external calls (now_v7, assert_eq!, metadata_for_test).

async fn archive_thread(
    store: &LocalThreadStore,
    params: ArchiveThreadParams,
) -> ThreadStoreResult<()>

Purpose: Archives one thread by finding its active session file, moving it to the archived sessions folder, and optionally updating the state database. This is used when a caller wants the thread hidden from normal active listings without deleting its saved data.

Data flow: It receives a local thread store and archive parameters containing the thread id. It reads the store configuration to find the Codex home folder, asks the store for an optional state database context, locates the rollout file for that thread id, checks that the path and file name are safe and correct, creates the archive folder if needed, and moves the file there. It returns success when the move completes, or a thread-store error if the thread cannot be found or the filesystem operation fails; if a state database is available, it also records the archived path and timestamp.

Call relations: This is the worker behind the local store’s archive operation. It leans on lookup code to find the thread file, helper checks to make sure the file is inside the expected sessions area and matches the requested id, filesystem calls to create the destination folder and move the file, and the state database to keep metadata in step with the moved file.

Call graph: calls 3 internal fn (state_db, matching_rollout_file_name, scoped_rollout_path); called by 1 (archive_thread); 4 external calls (now, find_thread_path_by_id_str, create_dir_all, rename).

async fn archive_thread_moves_rollout_to_archived_collection()

Purpose: Checks the basic archive behavior from a user’s point of view: an active session file should disappear from the active location, reappear in the archived folder, and show up in archived thread listings.

Data flow: The test creates a temporary Codex home folder, builds a local thread store with no state database, writes a fake session file for a known thread id, and calls the archive operation. Afterward, it checks that the original file path no longer exists, that the same file name exists in the archived sessions folder, and that listing archived threads returns that thread with the archived path and archive time.

Call relations: This test drives the public store archive flow in a simple filesystem-only setup. It uses test helpers to create the store configuration and session file, then relies on the store’s listing behavior to confirm that the archive operation produces data other parts of the thread store can still read.

Call graph: calls 4 internal fn (from_string, new, test_config, write_session_file); 5 external calls (new, from_u128, new, assert!, assert_eq!).

async fn archive_thread_updates_sqlite_metadata_when_present()

Purpose: Checks the extra behavior that happens when the optional SQLite state database is present: archiving should update the database record as well as move the file. SQLite is a small file-based database used here to speed up and organize thread metadata.

Data flow: The test creates a temporary home folder, starts a state database runtime, writes a fake active session file, inserts matching thread metadata into the database, and then calls the archive operation. It then reads the thread metadata back from the database and verifies that the stored rollout path now points to the archived file and that an archive timestamp was recorded.

Call relations: This test covers the path where the archive function has both filesystem data and database metadata to update. It sets up the database state before calling the store archive operation, then reads directly from the runtime afterward to prove that the archive function handed the new path and time to the database layer.

Call graph: calls 6 internal fn (from_string, new, init, new, test_config, write_session_file); 5 external calls (new, now, from_u128, assert!, assert_eq!).

async fn unarchive_thread(
    store: &LocalThreadStore,
    params: ArchiveThreadParams,
) -> ThreadStoreResult<StoredThread>

Purpose: Restores one archived thread into the normal local sessions folder and returns its updated thread summary. Someone would use this when a user chooses to unarchive a conversation so it appears with active threads again.

Data flow: It receives a local thread store and an ArchiveThreadParams value containing the thread id. It looks up the archived rollout file, verifies the file is in the expected archived area, extracts the date from its filename, creates the matching normal sessions folder, moves the file there, updates its timestamp, optionally updates the state database, then reads the moved file back into a StoredThread. On success it returns that restored thread; on failure it returns a clear thread-store error.

Call relations: This function is the core worker used by the store’s unarchive operation. It asks state_db for optional database access, uses find_archived_thread_path_by_id_str to locate the archived file, uses scoped_rollout_path and matching_rollout_file_name to validate that the file is safe and matches the requested thread, uses rollout_date_parts to choose the destination folder, calls touch_modified_time after moving the file, and finally hands the restored rollout item to stored_thread_from_rollout_item so callers get the normal thread object back.

Call graph: calls 5 internal fn (state_db, matching_rollout_file_name, scoped_rollout_path, stored_thread_from_rollout_item, touch_modified_time); called by 1 (unarchive_thread); 6 external calls (find_archived_thread_path_by_id_str, read_thread_item_from_rollout, rollout_date_parts, format!, create_dir_all, rename).

async fn unarchive_thread_restores_rollout_and_returns_updated_thread()

Purpose: Checks the basic unarchive behavior without a state database. It proves that the archived file is removed from the archive folder, recreated in the normal sessions folder, and returned as an active thread with the expected preview text.

Data flow: The test creates a temporary home folder, builds a local store, writes a fake archived session file for a known thread id, then calls unarchive_thread. After the call, it checks that the old archived path no longer exists, the new sessions path exists, and the returned StoredThread has the right id, path, non-archived status, and message preview.

Call relations: This test sets up its store with test_config, creates the archived rollout using write_archived_session_file, then exercises the store’s unarchive path. Its assertions describe the expected result of the production unarchive_thread function from a user-visible point of view.

Call graph: calls 4 internal fn (from_string, new, test_config, write_archived_session_file); 4 external calls (new, from_u128, assert!, assert_eq!).

async fn unarchive_thread_updates_sqlite_metadata_when_present()

Purpose: Checks that unarchiving also updates SQLite metadata when the local store has a state database. This matters because the file system and the database must agree about where the thread lives and whether it is archived.

Data flow: The test creates a temporary home folder, writes an archived session file, starts a state database runtime, inserts metadata that says the thread is archived, and then calls unarchive_thread. Afterward it reads the database record and confirms the rollout path now points to the restored sessions file and archived_at has been cleared.

Call relations: This test builds the same kind of archived file setup as the basic test, but also uses codex_state::StateRuntime::init and thread metadata objects to prepare a database record. It then calls the store’s unarchive operation and verifies that the production function’s optional database update step happened correctly.

Call graph: calls 6 internal fn (from_string, new, init, new, test_config, write_archived_session_file); 4 external calls (new, now, from_u128, assert_eq!).

async fn update_thread_metadata(
    store: &LocalThreadStore,
    params: UpdateThreadMetadataParams,
) -> ThreadStoreResult<StoredThread>

Purpose: This is the main update path for changing a thread's metadata. It applies the requested patch, then performs extra compatibility writes to rollout files when fields like name, memory mode, or Git information need to be visible outside SQLite.

Data flow: It receives a local store and update parameters containing a thread id, a patch, and whether archived threads may be searched. If the patch is empty, it simply reads the thread back. Otherwise it writes metadata to SQLite through apply_metadata_update, decides whether rollout compatibility work is needed, locates or persists the rollout file, appends memory-mode or Git metadata when needed, updates the thread-name index when needed, and finally reads back a StoredThread as the result.

Call relations: The store's update operation reaches this function when a caller wants metadata changed. It delegates the broad SQLite update to apply_metadata_update, uses resolve_rollout_path and refresh_resolved_rollout_path to keep pointing at the current transcript file, calls rollout-specific helpers for name, memory mode, and Git information, and falls back to reading by rollout path if the normal read does not find the thread.

Call graph: calls 17 internal fn (reconcile_rollout, state_db, git_info_from_parts, persist_thread, rollout_path, read_thread, read_thread_by_rollout_path, apply_metadata_update, apply_thread_git_info, apply_thread_git_info_to_rollout (+7 more)); called by 1 (update_thread_metadata); 1 external calls (format!).

async fn refresh_resolved_rollout_path(resolved: &mut ResolvedRolloutPath)

Purpose: This small helper refreshes a previously found rollout file path in case the real file has moved or been canonicalized. It keeps later writes aimed at the file that actually exists.

Data flow: It receives a mutable resolved path record. It asks the rollout layer for the existing path corresponding to that file, and if one is found it replaces the stored path with the fresher one. It returns nothing and only changes the path record.

Call relations: After update_thread_metadata appends memory-mode or Git metadata, it calls this helper before doing more rollout work. That keeps the rest of the update flow from writing to a stale file location.

Call graph: called by 1 (update_thread_metadata); 1 external calls (existing_rollout_path).

async fn apply_metadata_update(
    store: &LocalThreadStore,
    thread_id: ThreadId,
    patch: ThreadMetadataPatch,
    include_archived: bool,
    require_sqlite_write: bool,
) -> ThreadStoreResul

Purpose: This function applies the general metadata patch to the SQLite state database and then reads the updated thread back. It is the broad updater for fields such as preview, title, model, timestamps, source, permissions, tokens, first user message, current folder, and Git fields.

Data flow: It receives the store, thread id, patch, archived-search flag, and a flag saying whether SQLite failure must stop the update. It finds a live or stored rollout path if needed, reads any existing SQLite row, creates one from rollout information when appropriate, overlays each patch field, normalizes paths, converts enum-like values to strings, resolves partial Git changes, and writes the row back. It may also update the memory-mode index. It then returns the result of reading the thread, unless a required database write failed.

Call relations: update_thread_metadata calls this first so the main metadata index is updated before compatibility work. Inside, it leans on helpers such as resolve_rollout_path, enum_to_string, normalize_cwd, resolve_git_info_patch, memory_mode_as_str, and sqlite_write_error_is_best_effort to keep the update rules consistent.