Core src runtime, session, policy, and state tests

fn user_message(text: &str) -> ResponseItem

Purpose: Builds a fake user chat message for tests. It lets tests create realistic conversation history without repeating the full message structure every time.

Data flow: It receives plain text, wraps that text as user input content, and returns a ResponseItem marked with the role "user". It does not change any outside state.

Call relations: Several rollback and turn-start tests call this helper when they need user messages in a transcript. It hands back a ready-made message that those tests can insert into session history.

Call graph: called by 8 (recompute_token_usage_uses_session_base_instructions, thread_rollback_persists_marker_and_replays_cumulatively, thread_rollback_recomputes_previous_turn_settings_and_reference_context_from_replay, thread_rollback_restores_cleared_reference_context_item_after_compaction, try_start_turn_if_idle_rejects_active_review_turn_without_injecting, try_start_turn_if_idle_rejects_active_turn_without_injecting, try_start_turn_if_idle_rejects_pending_trigger_turn_without_injecting, try_start_turn_if_idle_rejects_plan_mode_without_injecting); 1 external calls (vec!).

fn assistant_message(text: &str) -> ResponseItem

Purpose: Builds a fake assistant reply for tests. It is the assistant-side companion to user_message.

Data flow: It receives plain text, wraps that text as assistant output content, and returns a ResponseItem marked with the role "assistant". Nothing is written elsewhere.

Call relations: Rollback tests use it to make saved conversation history look like a real exchange between user and assistant. The resulting item is later replayed or inspected by the session logic under test.

Call graph: called by 3 (thread_rollback_persists_marker_and_replays_cumulatively, thread_rollback_recomputes_previous_turn_settings_and_reference_context_from_replay, thread_rollback_restores_cleared_reference_context_item_after_compaction); 1 external calls (vec!).

fn test_session_telemetry_without_metadata() -> SessionTelemetry

Purpose: Creates a test telemetry object that records metrics in memory instead of sending them to a real metrics service. This makes metric assertions fast and self-contained.

Data flow: It creates an in-memory metric exporter, builds a MetricsClient around it, then creates SessionTelemetry with test model and source values. It returns that telemetry object with metadata tags disabled.

Call relations: Metric-focused tests call this helper before exercising session telemetry behavior. It supplies the fake measuring equipment that later assertions can read.

Call graph: calls 4 internal fn (new, new, in_memory, new); called by 2 (emit_thread_start_skill_metrics_records_description_truncated_chars_without_omitted_skills, emit_thread_start_skill_metrics_records_enabled_kept_and_truncated_values); 2 external calls (default, env!).

fn find_metric(resource_metrics: &'a ResourceMetrics, name: &str) -> &'a Metric

Purpose: Looks up one named metric inside collected test metrics. It fails loudly if the metric is missing, which makes test failures clear.

Data flow: It receives a ResourceMetrics bundle and a metric name, walks through each metric group, and returns the matching Metric reference. If no match exists, it panics with the missing name.

Call relations: histogram_sum uses this as its first step. Together they let tests move from a large metrics dump to one specific measured value.

Call graph: called by 1 (histogram_sum); 2 external calls (scope_metrics, panic!).

fn histogram_sum(resource_metrics: &ResourceMetrics, name: &str) -> u64

Purpose: Reads the total sum from a histogram metric in test telemetry. A histogram is a metric that groups measured values, and this helper extracts the one total the tests care about.

Data flow: It receives collected metrics and a metric name, finds that metric, checks that it is a floating-point histogram with exactly one data point, rounds the sum, and returns it as an integer. If the metric has the wrong shape, it panics.

Call relations: It builds on find_metric. Tests that need to assert aggregate metric values can call this instead of knowing the nested telemetry format.

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

fn skill_message(text: &str) -> ResponseItem

Purpose: Builds a user-style message that contains skill text. In these tests, a skill is a block of instructions that may mention external apps or connectors.

Data flow: It receives text, stores it as user input text inside a ResponseItem, and returns that item. It is structurally the same as a user message, but the name signals that the text represents skill content.

Call relations: This helper feeds skill-parsing tests with realistic ResponseItem input. The app-id collection logic then reads the returned message and searches its text for connector mentions.

Call graph: 1 external calls (vec!).

async fn regular_turn_emits_turn_started_with_trace_id_without_waiting_for_startup_prewarm()

Purpose: Checks that a normal turn announces that it started right away, even if startup prewarming is still blocked. It also verifies that tracing information is preserved.

Data flow: The test creates a parent trace context, starts a session inside that trace, installs a startup prewarm task that never completes, then starts a regular task. It reads the first session event and expects a TurnStarted event with the same turn id and trace id, then aborts the task for cleanup.

Call relations: The async test runner calls this test. It uses make_session_and_context_with_rx for a session and event receiver, test_model_client_session for the blocked prewarm handle, and session task APIs to prove event emission does not wait on prewarm completion.

Call graph: calls 5 internal fn (make_session_and_context_with_rx, test_model_client_session, new, new, install_test_tracing); 10 external calls (clone, new, assert!, assert_eq!, info_span!, panic!, from_millis, now, spawn, timeout).

async fn request_mcp_server_elicitation_auto_accepts_when_auto_deny_is_enabled()

Purpose: Verifies a special MCP server prompt path: when automatic denial is enabled, the session accepts the elicitation locally without sending anything to the user. MCP is a tool/server protocol; an elicitation is a server asking the user for extra input.

Data flow: The test creates a session, turns on auto-deny for elicitations, builds a simple empty form schema, and asks the session to request an elicitation. It expects an Accept response with empty content, confirms nothing was sent outward, and confirms no event appeared on the receiver.

Call relations: The test runner invokes it directly. It exercises Session::request_mcp_server_elicitation through a real test session and checks both the returned response and the absence of outbound events.

Call graph: calls 1 internal fn (make_session_and_context_with_rx); 5 external calls (String, assert!, assert_eq!, json!, from_value).

async fn interrupting_regular_turn_waiting_on_startup_prewarm_emits_turn_aborted()

Purpose: Checks that interrupting a turn that is waiting on startup prewarm still produces a clear abort event. This prevents the user interface from getting stuck thinking a turn is active.

Data flow: The test creates a session, installs a startup prewarm task that waits forever, starts a regular task, receives the TurnStarted event, then aborts all tasks. It then expects a raw marker item followed by a TurnAborted event with the right turn id, reason, completion time, and duration.

Call relations: The async test runner calls it. It uses test_model_client_session to build the suspended prewarm session and relies on the session event channel to observe the start and abort sequence.

Call graph: calls 4 internal fn (make_session_and_context_with_rx, test_model_client_session, new, new); 10 external calls (clone, new, assert!, assert_eq!, panic!, from_millis, from_secs, now, spawn, timeout).

fn test_model_client_session() -> crate::client::ModelClientSession

Purpose: Builds a fake model client session for tests that need a model connection object but do not need a real network call.

Data flow: It creates a fixed test thread id, builds a ModelClient using an OpenAI-style provider configuration and test settings, then returns a new ModelClientSession from it.

Call relations: Startup-prewarm tests call this inside a spawned task. It supplies the object those tests would receive if prewarming finished successfully.

Call graph: calls 3 internal fn (new, create_openai_provider, try_from); called by 2 (interrupting_regular_turn_waiting_on_startup_prewarm_emits_turn_aborted, regular_turn_emits_turn_started_with_trace_id_without_waiting_for_startup_prewarm).

fn developer_input_texts(items: &[ResponseItem]) -> Vec<&str>

Purpose: Extracts all input-text strings from messages whose role is "developer". Developer messages are instructions supplied by the system or app, not by the end user.

Data flow: It receives a slice of ResponseItem values, keeps only developer messages, walks through their content items, and returns every input text as string slices borrowed from the original items.

Call relations: Initial-context and settings-update tests use this helper to check exactly which developer instructions the session produced. It turns nested message structures into a simple list of text snippets.

Call graph: called by 9 (build_initial_context_omits_default_image_save_location_with_image_history, build_initial_context_omits_default_image_save_location_without_image_history, build_initial_context_restates_realtime_start_when_reference_context_is_missing, build_initial_context_trims_skill_metadata_from_context_window_budget, build_initial_context_uses_previous_realtime_state, build_initial_context_uses_previous_turn_settings_for_realtime_end, build_settings_update_items_emits_realtime_end_when_session_stops_being_live, build_settings_update_items_emits_realtime_start_when_session_becomes_live, build_settings_update_items_uses_previous_turn_settings_for_realtime_end); 1 external calls (iter).

fn developer_message_texts(items: &[ResponseItem]) -> Vec<Vec<&str>>

Purpose: Extracts developer message text while preserving message boundaries. This is useful when a test needs to know not just the text, but which pieces came from the same developer message.

Data flow: It receives response items, filters for role "developer", then returns a vector for each developer message containing that message’s input-text strings. It only borrows text; it does not alter the items.

Call relations: Tests about prompt fragments and multi-agent usage hints call it to inspect generated developer messages. It gives those tests a clearer view of the message grouping.

Call graph: called by 6 (build_initial_context_adds_multi_agent_v2_root_usage_hint_as_developer_message, build_initial_context_adds_multi_agent_v2_subagent_usage_hint_as_developer_message, build_initial_context_includes_prompt_fragments_from_extensions, build_initial_context_omits_multi_agent_v2_usage_hints_when_feature_disabled, build_initial_context_omits_multi_agent_v2_usage_hints_when_hint_disabled, build_initial_context_omits_prompt_fragments_without_extension_state); 1 external calls (iter).

fn user_input_texts(items: &[ResponseItem]) -> Vec<&str>

Purpose: Extracts all input-text strings from user messages. Tests use it to check user-visible context updates such as environment notices.

Data flow: It receives response items, keeps only messages whose role is "user", pulls out input text content, and returns borrowed string slices. Non-user messages and non-text content are ignored.

Call relations: Settings-update tests call this after the session builds context items. It reduces a structured response list to the user text that those tests want to compare.

Call graph: called by 3 (build_settings_update_items_emits_environment_item_for_network_changes, build_settings_update_items_emits_environment_item_for_time_changes, build_settings_update_items_omits_environment_item_when_disabled); 1 external calls (iter).

fn write_project_hooks(dot_codex: &Path) -> std::io::Result<()>

Purpose: Writes a small hooks.json file into a project’s .codex directory for hook-loading tests. Hooks are commands that can run at certain session events.

Data flow: It receives a path, creates the directory if needed, and writes a JSON file defining one SessionStart command hook that echoes a message. It returns any filesystem error to the caller.

Call relations: Project trust tests call it to place hook configuration in test project layers. Those tests then verify whether the session loads or ignores the hook based on trust.

Call graph: called by 2 (session_start_hooks_only_load_from_trusted_project_layers, session_start_hooks_require_project_trust_without_config_toml); 3 external calls (join, create_dir_all, write).

async fn write_project_trust_config(
    codex_home: &Path,
    trusted_projects: &[(&Path, TrustLevel)],
) -> std::io::Result<()>

Purpose: Writes a test config.toml that marks selected project paths with trust levels. This lets tests simulate trusted and untrusted project configuration.

Data flow: It receives a Codex home directory and a list of project paths with trust levels. It serializes those into ConfigToml and writes the result asynchronously to the config file.

Call relations: Project hook trust tests call it after creating hook files. It supplies the trust settings that decide whether those project hooks are allowed to load.

Call graph: called by 2 (session_start_hooks_only_load_from_trusted_project_layers, session_start_hooks_require_project_trust_without_config_toml); 5 external calls (default, iter, join, write, to_string).

async fn preview_session_start_hooks(
    config: &crate::config::Config,
) -> std::io::Result<Vec<codex_protocol::protocol::HookRunSummary>>

Purpose: Builds a hook runner from a config and previews which SessionStart hooks would run. Previewing means listing the hook runs without actually executing command effects.

Data flow: It receives a Config, creates Hooks with the feature enabled and the config layer stack copied in, then asks for a session-start preview using test request data. It returns the list of hook summaries or an I/O error.

Call relations: This helper is available to hook tests that need to inspect hook selection. It hands the config into the hooks subsystem and returns the hook subsystem’s preview result.

Call graph: calls 2 internal fn (new, new); 1 external calls (default).

fn test_tool_runtime(session: Arc<Session>, turn_context: Arc<TurnContext>) -> ToolCallRuntime

Purpose: Creates a ToolCallRuntime for tests that need to run or inspect tool calls. A tool runtime is the bundle of routing, session, turn, and change-tracking state used when tools execute.

Data flow: It receives a session and turn context, builds a ToolRouter from the turn’s dynamic tools, creates a mutex-protected TurnDiffTracker, and returns a ToolCallRuntime containing all of them.

Call relations: Tool-related tests call it when they need a realistic runtime without repeating setup. It connects the session and turn context to the router used by tool execution.

Call graph: calls 3 internal fn (new, from_turn_context, new); called by 4 (handle_output_item_done_records_image_save_history_message, handle_output_item_done_skips_image_save_message_when_save_fails, shell_tool_cancellation_waits_for_runtime_cleanup, tool_calls_reopen_mailbox_delivery_for_current_turn); 4 external calls (new, default, new, new).

fn make_connector(id: &str, name: &str) -> AppInfo

Purpose: Creates a simple fake app connector record. A connector represents an external app integration such as Calendar.

Data flow: It receives an id and display name, fills an AppInfo struct with those values, marks it accessible and enabled, and leaves optional metadata empty.

Call relations: Skill app-id tests call this to build the connector catalog that skill text is matched against. The collection logic then decides whether mentions point to this connector.

Call graph: 1 external calls (new).

fn assistant_message_stream_parsers_can_be_seeded_from_output_item_added_text()

Purpose: Tests that assistant stream parsers can begin with text from an initial output item and continue correctly when later text arrives. This matters when internal citation tags are split across streaming events.

Data flow: The test creates parsers, seeds one item with partial text containing the start of a memory citation tag, parses the remaining tag and visible text as a delta, then finishes the item. It expects visible text to hide the citation markup and the citation list to contain the completed citation.

Call relations: The test runner invokes it. It exercises AssistantMessageStreamParsers through seed_item_text, parse_delta, and finish_item to prove the parser keeps state across calls.

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

fn assistant_message_stream_parsers_seed_buffered_prefix_stays_out_of_finish_tail()

Purpose: Checks that a partially buffered citation tag from seeded text is not leaked later as leftover visible text. This protects users from seeing broken internal markup.

Data flow: The test seeds text ending with an unfinished citation tag prefix, then parses the rest of the tag and normal text, then finishes the item. It expects only normal text to be visible, one citation to be recorded, and no tail text at finish.

Call relations: The test runner calls it directly. It focuses on the parser’s buffering behavior between seed_item_text, parse_delta, and finish_item.

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

fn assistant_message_stream_parsers_seed_plan_parser_across_added_and_delta_boundaries()

Purpose: Tests that proposed-plan markup can start in seeded text and finish in later streamed text. Plan mode separates ordinary assistant text from structured proposed plan sections.

Data flow: The test creates parsers in plan mode, seeds text ending halfway through a proposed-plan tag, parses the rest of the plan and trailing text, then finishes. It expects visible text to omit the plan body where appropriate and plan segments to mark the plan start, delta, end, and normal text.

Call relations: The test runner invokes it. It checks AssistantMessageStreamParsers when both citation-style buffering and plan-mode segmentation are active.

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

fn validated_network_policy_amendment_host_allows_normalized_match()

Purpose: Verifies that network policy amendments accept hostnames that match after normalization. Normalization means cleaning differences like case, a trailing dot, or a port number.

Data flow: The test creates an amendment for "ExAmPlE.Com.:443" and an approval context for "example.com" over HTTPS. It calls the session validation function and expects the normalized host "example.com" back.

Call relations: The test runner calls it. It exercises Session::validated_network_policy_amendment_host to confirm valid user approvals are not rejected for harmless formatting differences.

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

fn validated_network_policy_amendment_host_rejects_mismatch()

Purpose: Checks that a network policy amendment cannot silently apply to a different host than the one being approved. This prevents a request for one site from changing rules for another.

Data flow: The test creates an amendment for "evil.example.com" and a context for "api.example.com". It expects validation to fail and checks that the error message explains the host mismatch.

Call relations: The test runner invokes it. It covers the rejection path of Session::validated_network_policy_amendment_host.

Call graph: 2 external calls (assert!, validated_network_policy_amendment_host).

async fn start_managed_network_proxy_applies_execpolicy_network_rules() -> anyhow::Result<()>

Purpose: Tests that network allow rules from the execution policy are applied to the managed network proxy. The proxy is the controlled gateway used to restrict tool network access.

Data flow: The test builds a workspace-write permission profile, creates a proxy spec, adds an allow rule for example.com to an execution policy, and starts the managed proxy. It then reads the proxy configuration and expects example.com to be in the allowed domains list.

Call relations: The async test runner calls it. It drives Session::start_managed_network_proxy and then asks the started proxy for its live configuration.

Call graph: calls 2 internal fn (from_config_and_constraints, workspace_write); 5 external calls (assert_eq!, empty, start_managed_network_proxy, default, default).

async fn start_managed_network_proxy_ignores_invalid_execpolicy_network_rules() -> anyhow::Result<()>

Purpose: Checks that execution-policy network rules do not override stricter managed network requirements. This keeps centrally managed restrictions from being weakened by local rules.

Data flow: The test builds network constraints that allow only managed.example.com, then adds an execution-policy allow rule for example.com. After starting the proxy, it expects the allowed domains to remain managed.example.com only.

Call relations: The test runner invokes it. It uses Session::start_managed_network_proxy to verify how config constraints and execution policy are combined.

Call graph: calls 2 internal fn (from_config_and_constraints, workspace_write); 7 external calls (default, assert_eq!, empty, start_managed_network_proxy, default, default, from).

async fn managed_network_proxy_decider_survives_full_access_start() -> anyhow::Result<()>

Purpose: Ensures the network policy decider remains active even if the proxy is first started under full-access permissions and later switched to workspace-write rules. A decider is callback code that can approve, deny, or ask about a network request.

Data flow: The test starts a managed proxy with full-access permissions but with managed network requirements enabled and a decider that always asks/blocks. It then recomputes the spec for workspace-write, applies it, sends an HTTP request through the proxy, and expects a 403 response plus exactly one decider call.

Call relations: The async test runner calls it. It exercises proxy startup, live proxy reconfiguration, and an actual TCP request through the proxy to prove the decider is still wired in.

Call graph: calls 2 internal fn (from_config_and_constraints, workspace_write); 14 external calls (clone, new, default, from_secs, from_utf8_lossy, assert!, assert_eq!, empty, start_managed_network_proxy, default (+4 more)).

async fn new_turn_refreshes_managed_network_proxy_for_sandbox_change() -> anyhow::Result<()>

Purpose: Tests that starting a new turn with a different sandbox policy refreshes the managed network proxy configuration. A sandbox policy controls how much system access a turn gets.

Data flow: The test starts a session and proxy with workspace-write rules that include both configured and required domains. It stores that proxy in the session, starts a new turn that switches to danger-full-access, then checks the proxy’s allowed domains have been recomputed to remove the earlier config-only domain.

Call relations: The test runner invokes it. It uses Session::start_managed_network_proxy for setup and Session::new_turn_with_sub_id to trigger the refresh path.

Call graph: calls 3 internal fn (from_config_and_constraints, make_session_and_context, workspace_write); 9 external calls (new, default, assert_eq!, empty, start_managed_network_proxy, default, default, from, vec!).

async fn danger_full_access_turns_do_not_expose_managed_network_proxy() -> anyhow::Result<()>

Purpose: Verifies that a turn running in danger-full-access mode does not receive a managed network proxy. Full access means the usual sandbox restrictions are disabled, so exposing the managed proxy would be misleading.

Data flow: The test creates a config with managed network enabled but the disabled/full-access permission profile. It starts a default turn and expects the turn context’s network field to be empty.

Call relations: The async test runner calls it. It uses make_session_with_config to create the exact permission setup and then observes the new turn context.

Call graph: calls 2 internal fn (from_config_and_constraints, make_session_with_config); 3 external calls (default, assert!, default).

async fn danger_full_access_tool_attempts_do_not_enforce_managed_network() -> anyhow::Result<()>

Purpose: Checks that tool attempts in danger-full-access mode are not told to enforce managed network restrictions. This keeps tool sandbox attempts consistent with the turn’s full-access policy.

Data flow: The test defines a small probe tool runtime that records the enforce_managed_network flag from each sandbox attempt. It builds a full-access session with managed network requirements present, runs the probe tool through the tool orchestrator, and expects the recorded flag to be false.

Call relations: The test runner invokes it. It connects session setup, ToolOrchestrator::run, and the probe ToolRuntime implementation to observe the sandbox attempt settings.

Call graph: calls 4 internal fn (from_config_and_constraints, make_session_with_config, new, plain); 6 external calls (clone, default, default, assert!, assert_eq!, default).

async fn workspace_write_turns_continue_to_expose_managed_network_proxy() -> anyhow::Result<()>

Purpose: Confirms that workspace-write turns still receive a managed network proxy when managed networking is enabled. Workspace-write is a restricted mode where controlled network access can matter.

Data flow: The test creates a workspace-write permission profile with managed network enabled, builds a session from that config, starts a default turn, and expects the turn context’s network field to be present.

Call relations: The async test runner calls it. It is the positive counterpart to the danger-full-access network proxy tests.

Call graph: calls 3 internal fn (from_config_and_constraints, make_session_with_config, workspace_write); 3 external calls (default, assert!, default).

async fn user_shell_commands_do_not_inherit_managed_network_proxy() -> anyhow::Result<()>

Purpose: Verifies that shell commands explicitly run by the user do not inherit the session’s managed network proxy environment variables. This prevents user shell commands from being unexpectedly routed through tool network controls.

Data flow: The test creates a workspace-write session with managed networking, starts a turn, then runs a shell command that prints HTTP_PROXY or "not-set". It reads events until the command ends and expects exit code 0 with stdout showing "not-set".

Call relations: The test runner invokes it. It uses execute_user_shell_command and watches the session event receiver for ExecCommandEnd to check the shell environment.

Call graph: calls 3 internal fn (from_config_and_constraints, make_session_with_config_and_rx, workspace_write); 7 external calls (clone, new, default, assert!, assert_eq!, execute_user_shell_command, default).

async fn get_base_instructions_no_user_content()

Purpose: Checks that base model instructions come from model configuration and do not include user content. Base instructions are the system prompt text that guides the model before any user message.

Data flow: The test loads bundled model metadata, creates several model test cases, updates the session’s base instructions for each model, calls get_base_instructions, and compares the returned text to the model’s configured base instructions.

Call relations: The async test runner calls it. It uses test_config, bundled model data, and Session::get_base_instructions to verify the session reads the configured prompt text unchanged.

Call graph: calls 2 internal fn (test_config, make_session_and_context); 4 external calls (assert_eq!, bundled_models_response, include_str!, vec!).

async fn reload_user_config_layer_updates_effective_apps_config()

Purpose: Tests that reloading the user config file updates app settings visible through the session. App settings control whether named app integrations are enabled and whether destructive actions are allowed.

Data flow: The test writes a config.toml with calendar app settings, calls reload_user_config_layer, then reads the effective config from the session and deserializes the apps table. It expects calendar to be disabled and destructive_enabled to be false.

Call relations: The test runner invokes it. It checks Session::reload_user_config_layer by writing a real temporary user config file and then reading Session::get_config.

Call graph: calls 1 internal fn (make_session_and_context); 5 external calls (assert!, assert_eq!, deserialize, create_dir_all, write).

async fn reload_user_config_layer_updates_base_and_selected_profile_layers()

Purpose: Verifies that reloading user config updates both the base user config and the selected profile config. A profile is an alternate config file layered on top of the base settings.

Data flow: The test writes base and profile config files, installs a config that points at the profile, then changes both files and reloads. It expects the session to still point at the profile file, use the profile’s new model value, and use the base file’s updated approval policy.

Call relations: The async test runner calls it. It uses ConfigBuilder to create the profile-based setup and Session::reload_user_config_layer to refresh the layer stack.

Call graph: calls 3 internal fn (without_managed_config_for_tests, without_managed_config_for_tests, make_session_and_context); 4 external calls (new, assert_eq!, create_dir_all, write).

async fn reload_user_config_layer_refreshes_hooks() -> anyhow::Result<()>

Purpose: Checks that reloading user config also refreshes trusted hook definitions. This matters because a hook may become allowed only after its trusted hash is written to config.

Data flow: The test enables hooks, builds a session-start hook request, confirms no hook is initially previewed, computes the hook list and trust data, writes a trusted hook state into config.toml, reloads user config, and expects one hook to appear in the preview.

Call relations: The test runner invokes it. It combines codex_hooks::list_hooks with Session::reload_user_config_layer and Session::hooks to verify the live hook runner is rebuilt.

Call graph: calls 1 internal fn (make_session_with_config); 9 external calls (assert!, assert_eq!, list_hooks, default, from_value, json!, create_dir_all, write, to_string).

async fn refresh_runtime_config_refreshes_hooks() -> anyhow::Result<()>

Purpose: Tests that refreshing runtime config, not just reloading user config directly, also refreshes hooks. Runtime config refresh is the broader path used when the session is given a newly loaded config object.

Data flow: The test enables hooks in session state, writes a trusted hook configuration to config.toml, confirms no hook is currently previewed, loads the latest config for the session, refreshes runtime config, and expects the hook preview to include one hook.

Call relations: The async test runner calls it. It uses load_latest_config_for_session to build the next config and Session::refresh_runtime_config to install it.

Call graph: calls 2 internal fn (load_latest_config_for_session, make_session_and_context); 12 external calls (new, assert!, assert_eq!, try_from, version_for_toml, format!, from_value, json!, create_dir_all, write (+2 more)).

async fn reload_user_config_layer_updates_effective_tool_suggest_config()

Purpose: Verifies that reloading user config updates tool suggestion settings. Tool suggestion settings can disable suggested connectors or plugins.

Data flow: The test writes a config.toml with two disabled tools, including one connector id with extra spaces, reloads user config, and checks that the session config contains normalized disabled tool entries.

Call relations: The test runner invokes it. It exercises Session::reload_user_config_layer and then inspects Session::get_config for the tool_suggest result.

Call graph: calls 1 internal fn (make_session_and_context); 3 external calls (assert_eq!, create_dir_all, write).

async fn refresh_runtime_config_updates_runtime_refreshable_fields_and_keeps_session_static_settings()

Purpose: Checks that runtime config refresh updates fields meant to change live, while preserving settings that are fixed for the session. This avoids surprising mid-session changes to core choices like model or notification command.

Data flow: The test writes app and tool suggestion config, loads a next config, deliberately changes model and notify on that next config, and refreshes the session. It expects apps and disabled tools to update, while model and notify remain equal to the original session values.

Call relations: The async test runner calls it. It uses load_latest_config_for_session and Session::refresh_runtime_config to test the boundary between refreshable and static settings.

Call graph: calls 2 internal fn (load_latest_config_for_session, make_session_and_context); 6 external calls (assert!, assert_eq!, deserialize, create_dir_all, write, vec!).

fn collect_explicit_app_ids_from_skill_items_includes_linked_mentions()

Purpose: Tests that app mentions written as links inside skill text are collected as explicit app ids. For example, an app link can point directly to app://calendar.

Data flow: The test creates a calendar connector and a skill message containing a linked calendar mention. It calls collect_explicit_app_ids_from_skill_items and expects the returned set to contain "calendar".

Call relations: The test runner invokes it. It uses make_connector and skill-shaped message input to exercise the app-id collection logic.

Call graph: 3 external calls (new, assert_eq!, vec!).

fn collect_explicit_app_ids_from_skill_items_resolves_unambiguous_plain_mentions()

Purpose: Tests that a plain dollar-style mention, such as $calendar, is resolved to a connector when there is no ambiguity.

Data flow: The test creates one calendar connector and one skill message containing "$calendar". It calls the collection function with no conflicting skill names and expects the set to contain "calendar".

Call relations: The test runner calls it. It covers the plain-text mention path of collect_explicit_app_ids_from_skill_items.

Call graph: 3 external calls (new, assert_eq!, vec!).

fn collect_explicit_app_ids_from_skill_items_skips_plain_mentions_with_skill_conflicts()

Purpose: Checks that a plain app mention is ignored when the same name also belongs to a skill. This avoids guessing wrong when "$calendar" could mean either a skill or an app.

Data flow: The test creates a calendar connector, a skill message with "$calendar", and a skill-name count showing a calendar skill exists. It calls the collection function and expects an empty set.

Call relations: The test runner invokes it. It exercises the ambiguity guard in collect_explicit_app_ids_from_skill_items.

Call graph: 3 external calls (from, assert_eq!, vec!).

async fn reconstruct_history_matches_live_compactions()

Purpose: Verifies that rebuilding history from saved rollout items matches the history produced by live compaction. Compaction is when old conversation details are replaced by a shorter summary to save context space.

Data flow: The test creates a sample rollout and its expected compacted history, starts a fresh reconstruction turn, reconstructs history from the rollout, and compares both the reconstructed items and window id.

Call relations: The async test runner calls it. It uses sample_rollout for fixture data and Session::reconstruct_history_from_rollout for the behavior under test.

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

async fn reconstruct_history_uses_replacement_history_verbatim()

Purpose: Checks that when a compacted rollout item includes replacement_history, reconstruction uses that replacement exactly. This prevents reconstruction from trying to reinterpret already-prepared history.

Data flow: The test builds a compacted rollout item with a two-item replacement history and window id 42. It reconstructs history from that rollout and expects the same replacement items and window id.

Call relations: The test runner invokes it. It directly targets Session::reconstruct_history_from_rollout’s compacted-item shortcut behavior.

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

async fn record_initial_history_reconstructs_resumed_transcript()

Purpose: Tests that recording a resumed transcript reconstructs and installs the expected conversation history. Resuming means opening an existing saved conversation rather than starting fresh.

Data flow: The test builds a sample rollout, calls record_initial_history with InitialHistory::Resumed, then reads session history from state. It expects the installed raw items to match the reconstructed expected history.

Call relations: The async test runner calls it. It uses sample_rollout to provide saved transcript data and Session::record_initial_history to load it into session state.

Call graph: calls 3 internal fn (make_session_and_context, sample_rollout, default); 3 external calls (from, assert_eq!, Resumed).

async fn resize_all_images_prepares_failures_before_history_insertion()

Purpose: Verifies that broken images are converted to safe text before conversation items are inserted into history. This keeps unusable image data from polluting saved history.

Data flow: The test enables the ResizeAllImages feature, builds a function-call output containing text, one invalid base64 data image, and one URL image, then records it. It expects history to contain the text, a replacement notice for the bad image, and the untouched URL image.

Call relations: The test runner invokes it. It drives Session::record_conversation_items and then inspects session history to confirm preprocessing happened before insertion.

Call graph: calls 2 internal fn (make_session_and_context_with_auth_and_config_and_rx, from_api_key); 5 external calls (new, assert_eq!, ContentItems, from_ref, vec!).

async fn resize_all_images_prepares_resumed_history_before_installing_it()

Purpose: Checks that resumed history is also cleaned of broken image content before it becomes session history. This protects old transcripts loaded from disk just like new items.

Data flow: The test enables ResizeAllImages, creates a resumed user message with an invalid data image and normal text, records resumed history, and expects installed history to replace the image with an omission notice while keeping the text.

Call relations: The async test runner calls it. It tests Session::record_initial_history on the resumed-history path with image preprocessing enabled.

Call graph: calls 3 internal fn (make_session_and_context_with_auth_and_config_and_rx, from_api_key, default); 5 external calls (from, new, assert_eq!, Resumed, vec!).

fn resolve_multi_agent_version_handles_unset_and_legacy_history()

Purpose: Tests how the session decides which multi-agent protocol version applies when history is new, resumed, forked, inherited, or explicitly marked. Multi-agent mode controls how parent and sub-agent sessions coordinate.

Data flow: The test calls resolve_multi_agent_version with several combinations of initial history and inherited version. It expects new sessions without inheritance to stay unset, legacy resumed/forked histories to default to V1, inherited V2 to be kept when appropriate, and explicit metadata to win where defined.

Call relations: The test runner invokes it. It uses session_meta_item to build rollout metadata cases and focuses entirely on resolve_multi_agent_version’s decision table.

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

async fn record_initial_history_new_defers_initial_context_until_first_turn()

Purpose: Verifies that a brand-new session does not immediately write initial context into history. Instead, it waits until the first turn context update.

Data flow: The test records InitialHistory::New, then reads the session history, reference context item, and previous turn settings. It expects empty history, no reference context, and no previous settings.

Call relations: The async test runner calls it. It exercises Session::record_initial_history for the new-session case and checks state directly afterward.

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

fn session_meta_item(
    thread_id: ThreadId,
    multi_agent_version: Option<MultiAgentVersion>,
) -> RolloutItem

Purpose: Builds a saved transcript metadata item for tests. The metadata can include the thread id and optional multi-agent version.

Data flow: It receives a ThreadId and optional MultiAgentVersion, puts them into a SessionMeta value with defaults for other fields, wraps that in a SessionMetaLine, and returns it as a RolloutItem.

Call relations: resolve_multi_agent_version_handles_unset_and_legacy_history calls this helper to create rollout histories with explicit multi-agent metadata. The resulting rollout item is then read by resolve_multi_agent_version.

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

async fn resumed_history_injects_initial_context_on_first_context_update_only()

Purpose: Checks that resumed sessions add initial context exactly once, at the first context update. This avoids duplicate system/developer context being appended every time context is refreshed.

Data flow: The test records resumed history from a sample rollout and confirms the history initially matches the saved transcript. It then records context updates, appends the built initial context to the expected list, and confirms history matches. A second context update should leave history unchanged.

Call relations: The async test runner invokes it. It combines Session::record_initial_history, record_context_updates_and_set_reference_context_item, and build_initial_context to verify one-time seeding.

Call graph: calls 3 internal fn (make_session_and_context, sample_rollout, default); 3 external calls (from, assert_eq!, Resumed).

async fn record_initial_history_seeds_token_info_from_rollout()

Purpose: Tests that resuming a transcript restores the latest token usage information found in saved rollout events. Token usage tracks how many model tokens were consumed.

Data flow: The test creates sample rollout items, appends several TokenCount events including two with info and two empty ones, then records resumed history. It reads token_info from session state and expects the last non-empty token usage info to be stored.

Call relations: The async test runner calls it. It exercises Session::record_initial_history’s resume path and verifies that saved EventMsg::TokenCount entries seed session state.

Call graph: calls 3 internal fn (make_session_and_context, sample_rollout, default); 5 external calls (from, assert_eq!, TokenCount, Resumed, EventMsg).

async fn recompute_token_usage_uses_session_base_instructions()

Purpose: This test proves that recomputing token usage counts the session's current base instructions, not just the model's default instructions. That matters because long custom instructions can change how much context the conversation uses.

Data flow: It creates a test session, replaces the session's base instructions with a long distinctive string, records a user message, and calculates two possible token totals: one using the session instructions and one using the model defaults. After asking the session to recompute usage, it reads the stored token total and expects it to match the session-instruction estimate.

Call relations: The test builds its setup through make_session_and_context and user_message, then exercises session.recompute_token_usage. It compares the result against the conversation history's own token estimator to make sure recomputation follows the session configuration path.

Call graph: calls 2 internal fn (make_session_and_context, user_message); 3 external calls (assert_eq!, assert_ne!, from_ref).

async fn recompute_token_usage_updates_model_context_window()

Purpose: This test checks that recomputing token usage also refreshes the stored model context window, which is the maximum amount of text the model can consider at once. If this stayed stale, the app could make bad decisions about when to compact or trim history.

Data flow: It starts with token information that says the model window is 258,400 tokens. Then it changes the turn context to say the active model window is 128,000 tokens, recomputes token usage, and reads the session state back. The expected after-state is that the stored window is now 128,000.

Call relations: The test creates a normal session context, edits the test data directly, and then calls session.recompute_token_usage. It verifies that recomputation updates both usage and the model-window metadata kept in session state.

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

async fn record_token_usage_info_notifies_extension_contributors()

Purpose: This test makes sure extensions are notified whenever token usage is recorded. Extensions are plug-ins that can observe session events, so they need accurate totals and access to the right session and thread data stores.

Data flow: It installs a test token-usage recorder extension, adds marker values to the session-level and thread-level extension stores, and records two usage updates. The recorder captures the store IDs, whether it could see the markers, and the token usage snapshot it received. The final records must show the first usage alone, then the cumulative total after the second usage.

Call relations: The test wires a TokenUsageContributor into the extension registry, then calls session.record_token_usage_info twice. The session is expected to hand the contributor the session store, thread store, turn store, and freshly updated TokenUsageInfo each time.

Call graph: calls 1 internal fn (make_session_and_context); 7 external calls (clone, new, new, assert_eq!, new, new, vec!).

async fn turn_start_lifecycle_exposes_turn_metadata_and_token_baseline()

Purpose: This test checks that a turn-start extension callback receives the identity of the turn, the collaboration mode, and the token usage that existed before the turn began. That baseline lets extensions compare before-and-after usage.

Data flow: It registers a turn lifecycle recorder, marks the session and thread extension stores, sets an existing total token usage value, and starts a never-ending task to trigger turn start. After aborting the task, it checks that exactly one recorded callback contains the expected IDs, collaboration mode, starting token usage, and marker visibility.

Call relations: The test uses sess.spawn_task to enter the normal turn lifecycle path and abort_all_tasks to clean up. The TurnLifecycleContributor implementation observes on_turn_start and records what the session passes into that lifecycle hook.

Call graph: calls 2 internal fn (make_session_and_context, set_total_token_usage); 6 external calls (clone, new, new, assert_eq!, new, new).

async fn turn_error_lifecycle_exposes_error_and_stores()

Purpose: This test verifies that turn-error lifecycle callbacks receive both the error value and the correct extension data stores. This lets plug-ins respond to failures with enough context.

Data flow: It installs a lifecycle recorder extension, adds markers to session and thread stores, builds an expected record for a usage-limit error, and then emits that turn error. The recorded output must contain the right store IDs, turn ID, error kind, and marker visibility.

Call relations: The test calls session.emit_turn_error_lifecycle directly. That path should notify registered TurnLifecycleContributor implementations through their on_turn_error callback.

Call graph: calls 1 internal fn (make_session_and_context); 6 external calls (clone, new, new, assert_eq!, new, new).

async fn config_change_contributor_observes_effective_config_changes()

Purpose: This test ensures that configuration-change extensions see real effective changes, both from runtime settings and from refreshed user configuration files. It also verifies that extension stores are available during the notification.

Data flow: It registers a config recorder, remembers the original model and disabled tool list, changes the collaboration mode to a new model, then writes a config file that disables two tools and refreshes runtime config. The recorder should receive two changes: first the model change, then the disabled-tool change.

Call relations: The test drives two normal update paths: session.update_settings and session.refresh_runtime_config after load_latest_config_for_session. The ConfigContributor should be called after each effective config transition with previous and new config values.

Call graph: calls 2 internal fn (load_latest_config_for_session, make_session_and_context); 10 external calls (clone, new, default, new, assert_eq!, new, create_dir_all, write, new, vec!).

async fn record_initial_history_reconstructs_forked_transcript()

Purpose: This test checks that a forked session can rebuild its visible transcript from saved rollout items. A rollout is the saved event log of a thread.

Data flow: It creates a sample rollout and the expected reconstructed history, records that rollout as forked initial history, then reads the session's in-memory history. The final history must match the expected raw conversation items.

Call relations: The test uses sample_rollout to create realistic saved data, then calls session.record_initial_history with InitialHistory::Forked. It verifies that the session's history reconstruction path produces the same transcript that future model calls would use.

Call graph: calls 2 internal fn (make_session_and_context, sample_rollout); 2 external calls (assert_eq!, Forked).

async fn session_configured_reports_permission_profile_for_external_sandbox() -> anyhow::Result<()>

Purpose: This test makes sure a session configured with an external sandbox reports that exact permission profile to clients. The important point is that it must not be flattened into a less precise legacy file-system profile.

Data flow: It starts a mock server, configures the test session with an external sandbox and restricted network access, then builds the session. The session_configured event must contain the explicit external permission profile.

Call relations: The test uses test_codex and start_mock_server to go through normal session startup. It checks the session_configured data that clients receive after startup.

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

async fn session_permission_profile_rebinds_runtime_workspace_roots() -> anyhow::Result<()>

Purpose: This test checks that workspace-based permissions stay symbolic until the session knows its current workspace roots. In plain terms, a permission like 'workspace writable' should follow the current workspace, not stay stuck to an old path forever.

Data flow: It builds a config whose additional writable root is an old workspace path, creates permission-profile state from it, and confirms the stored policy has not hard-coded that old path. Then it builds a session configuration, applies a settings update with a new workspace root, and checks that the new root is writable while the old root is not.

Call relations: The test covers session_permission_profile_state_from_config and SessionConfiguration.apply. It ensures settings updates correctly rebind the sandbox policy to the latest workspace roots.

Call graph: calls 2 internal fn (make_session_configuration_for_tests, new); 7 external calls (default, new, assert!, default, test_path_buf, new, vec!).

async fn fork_startup_context_then_first_turn_diff_snapshot() -> anyhow::Result<()>

Purpose: This snapshot test checks the exact context sent to the model on the first turn after a fork, especially when startup settings and first-turn overrides differ. A snapshot is a saved expected text output used to catch accidental changes.

Data flow: It runs an initial conversation against a mock server, flushes its rollout to disk, forks the thread with a different approval policy, then submits a first forked turn in plan mode with its own settings. It captures the outgoing model request and formats a stripped-down context snapshot for comparison.

Call relations: The test goes through the full higher-level flow: test_codex startup, user submit, rollout materialization, thread_manager.fork_thread, another submit, and request snapshot formatting. The mock server records the model request so the test can compare the context that would have been sent externally.

Call graph: calls 7 internal fn (allow_any, default, format_labeled_requests_snapshot, mount_sse_once, sse, start_mock_server, test_codex); 4 external calls (default, wait_for_event, clone_current, vec!).

async fn record_initial_history_forked_hydrates_previous_turn_settings()

Purpose: This test ensures that when a fork is created from saved history, the session remembers the previous turn's model settings without duplicating that previous conversation into active history. That previous setting is needed as a reference for later diffs and context decisions.

Data flow: It builds rollout items containing a previous turn context with a custom model, records them as forked initial history, and then reads three pieces of state. The expected result is that previous_turn_settings contains the custom model, the active history is empty, and the reference context item matches the saved previous context.

Call relations: The test calls session.record_initial_history with InitialHistory::Forked. It checks the fork hydration path that separates reference metadata from the new fork's active conversation history.

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

async fn thread_rollback_drops_last_turn_from_history()

Purpose: This test checks the basic rollback behavior: removing the most recent completed turn from both in-memory history and persisted replay data. Rollback is the conversation equivalent of undo.

Data flow: It creates a session with persistence, builds initial context plus two turns, saves them, and sets stale previous-turn reference state. After rolling back one turn, it expects the event to report one turn removed, the in-memory history to contain only initial context plus turn one, and the stale reference state to be cleared. It also verifies that the saved rollout contains a rollback marker.

Call relations: The test calls handlers::thread_rollback, waits for a ThreadRolledBack event through the receiver, and reads persisted history through RolloutRecorder. This checks that rollback updates live state and disk history together.

Call graph: calls 5 internal fn (thread_rollback, attach_thread_persistence, make_session_and_context_with_rx, wait_for_thread_rolled_back, get_rollout_history); 6 external calls (get_mut, new, assert!, assert_eq!, panic!, vec!).

async fn thread_rollback_clears_history_when_num_turns_exceeds_existing_turns()

Purpose: This test checks that asking to roll back more turns than exist does not crash or leave partial user turns behind. The remaining history should be only the initial context.

Data flow: It saves a session with initial context and one user turn, then requests rollback of 99 turns. After the rollback event, the session history should contain only the initial context.

Call relations: The test drives handlers::thread_rollback with an intentionally oversized count. It confirms the rollback replay logic safely clamps the result to the available conversation turns.

Call graph: calls 4 internal fn (thread_rollback, attach_thread_persistence, make_session_and_context_with_rx, wait_for_thread_rolled_back); 4 external calls (get_mut, new, assert_eq!, vec!).

async fn thread_rollback_fails_without_persisted_thread_history()

Purpose: This test verifies that rollback refuses to run when there is no persisted thread history. Since rollback is replay-based, it needs the saved event log as its source of truth.

Data flow: It creates a session without attaching persistence, records initial context in memory, and requests rollback. The result should be a failure event with a clear message and error code, while the in-memory history remains unchanged.

Call relations: The test calls handlers::thread_rollback and then waits for a rollback-failed event. It confirms the handler protects the session instead of guessing from incomplete in-memory state.

Call graph: calls 3 internal fn (thread_rollback, make_session_and_context_with_rx, wait_for_thread_rollback_failed); 1 external calls (assert_eq!).

async fn thread_rollback_recomputes_previous_turn_settings_and_reference_context_from_replay()

Purpose: This test checks that rollback rebuilds previous-turn settings and reference context from the saved rollout, not from stale live state. That prevents old cached metadata from surviving after the conversation is rewound.

Data flow: It writes two completed turns to the persisted rollout, where the second turn has a different model and will be rolled back. It then deliberately sets stale in-memory history and stale previous-turn settings. After rolling back one turn, the history should contain only turn one's messages, previous-turn settings should match turn one's context, and the reference context should be turn one's saved context item.

Call relations: The test uses handlers::thread_rollback to trigger the replay path. It verifies that replayed rollout items, rather than the current in-memory values, determine the post-rollback session state.

Call graph: calls 6 internal fn (thread_rollback, assistant_message, attach_thread_persistence, make_session_and_context_with_rx, user_message, wait_for_thread_rolled_back); 11 external calls (get_mut, default, new, assert_eq!, TurnComplete, TurnStarted, UserMessage, EventMsg, ResponseItem, TurnContext (+1 more)).

async fn thread_rollback_restores_cleared_reference_context_item_after_compaction()

Purpose: This test covers rollback when a conversation has been compacted, meaning older messages were replaced by a shorter summary to save context space. After rolling back a later turn, the compacted history and window ID should be restored correctly.

Data flow: It writes a first turn, then a compaction event with replacement history and a window ID, then a second turn that will be rolled back. It seeds stale live history and an unrelated compact window ID. After rollback, the active history must be the compacted replacement history, the reference context item should be cleared, and the current window ID should reflect the compaction window.

Call relations: The test drives handlers::thread_rollback through a persisted rollout containing a Compacted item. It checks that rollback replay understands compaction events as well as normal message turns.

Call graph: calls 6 internal fn (thread_rollback, assistant_message, attach_thread_persistence, make_session_and_context_with_rx, user_message, wait_for_thread_rolled_back); 13 external calls (get_mut, default, new, assert!, assert_eq!, TurnComplete, TurnStarted, UserMessage, Compacted, EventMsg (+3 more)).

async fn thread_rollback_persists_marker_and_replays_cumulatively()

Purpose: This test verifies that multiple rollbacks stack correctly over time. Each rollback should be recorded, and the next rollback should replay history including the earlier rollback marker.

Data flow: It saves three completed turns, rolls back one turn, then rolls back one more turn. The final in-memory history should contain only turn one. The persisted rollout should contain two rollback markers.

Call relations: The test calls handlers::thread_rollback twice and observes two success events. It then reads the rollout file through RolloutRecorder to prove the markers were persisted and future replays can understand both undo steps.

Call graph: calls 7 internal fn (thread_rollback, assistant_message, attach_thread_persistence, make_session_and_context_with_rx, user_message, wait_for_thread_rolled_back, get_rollout_history); 11 external calls (get_mut, default, new, assert_eq!, panic!, TurnComplete, TurnStarted, UserMessage, EventMsg, ResponseItem (+1 more)).

async fn thread_rollback_fails_when_turn_in_progress()

Purpose: This test makes sure rollback is blocked while a turn is active. Rewinding while the assistant is still working could mix old and new state in unsafe ways.

Data flow: It records initial context, manually marks the session as having an active turn, and requests rollback. The expected result is a rollback-failed event, and the history remains unchanged.

Call relations: The test calls handlers::thread_rollback after setting active_turn. It verifies that the handler checks for in-progress work before changing conversation state.

Call graph: calls 4 internal fn (thread_rollback, make_session_and_context_with_rx, wait_for_thread_rollback_failed, default); 1 external calls (assert_eq!).

async fn thread_rollback_fails_when_num_turns_is_zero()

Purpose: This test checks input validation for rollback. A request to roll back zero turns is meaningless, so it should fail clearly.

Data flow: It records initial context, asks to roll back zero turns, and waits for a failure event. The event should say that num_turns must be at least one, carry the rollback failure error code, and leave history unchanged.

Call relations: The test exercises handlers::thread_rollback with an invalid count. It verifies that validation happens before any replay or history mutation.

Call graph: calls 3 internal fn (thread_rollback, make_session_and_context_with_rx, wait_for_thread_rollback_failed); 1 external calls (assert_eq!).

async fn set_rate_limits_retains_previous_credits()

Purpose: This test checks that partial rate-limit updates do not erase existing credit information. Some server updates may include new limit windows but omit account credits, so the session should keep the last known credits.

Data flow: It builds a session state, stores an initial rate-limit snapshot that includes credits and plan type, then applies an update with new primary and secondary windows but no credits or plan type. The final snapshot should use the new windows while retaining the earlier credits and plan type.

Call relations: The test constructs SessionState directly and calls state.set_rate_limits twice. It focuses on the merge behavior inside session state rather than going through a network event.

Call graph: calls 5 internal fn (build_test_config, new, construct_model_info_offline_for_tests, get_model_offline_for_tests, new); 6 external calls (clone, new, new, assert_eq!, from_config, tempdir).

async fn set_rate_limits_updates_plan_type_when_present()

Purpose: This test checks the companion case for rate-limit updates: when a new plan type is present, it should replace the old one. At the same time, missing credits should still be preserved.

Data flow: It creates an initial snapshot with Plus plan and credits, then applies an update with a Pro plan and no credits. The final snapshot should show the new Pro plan, keep the old credits, and update the limit window fields.

Call relations: Like the previous rate-limit test, this builds SessionState and calls state.set_rate_limits directly. Together they define how partial snapshots are merged.

Call graph: calls 5 internal fn (build_test_config, new, construct_model_info_offline_for_tests, get_model_offline_for_tests, new); 6 external calls (clone, new, new, assert_eq!, from_config, tempdir).

fn prefers_structured_content_when_present()

Purpose: This test checks that MCP tool results prefer structured content when it is available. MCP, or Model Context Protocol, is a way for tools to return data to the assistant; structured content is machine-readable data like JSON.

Data flow: It creates a tool result with both plain content and structured JSON content. When converted into a function-call output payload, the body should be the JSON string from structured content, and the success flag should be true.

Call relations: The test calls McpCallToolResult.into_function_call_output_payload. It confirms the conversion path ignores fallback text blocks when meaningful structured data exists.

Call graph: 5 external calls (assert_eq!, json!, Text, to_string, vec!).

async fn includes_timed_out_message()

Purpose: This test makes sure command output shown to the model includes a clear timeout message when a command exceeded its time limit. Without this, the model might treat partial output as a normal successful command.

Data flow: It builds an execution result marked as timed out with one second of duration and some aggregated output. After formatting, the output string should begin with 'command timed out after 1000 milliseconds' followed by the command output.

Call relations: The test creates a turn context for the truncation policy and calls format_exec_output_str. It verifies the user-visible formatting used for shell command results.

Call graph: calls 3 internal fn (make_session_and_context, format_exec_output_str, new); 3 external calls (from_secs, new, assert_eq!).

async fn turn_context_with_model_updates_model_fields()

Purpose: This test checks that changing the model on a turn context updates all related fields consistently. The model name, model metadata, reasoning effort, and truncation policy all need to agree.

Data flow: It starts with a turn context whose reasoning effort is Minimal, then asks for a copy using model gpt-5.4. The updated context should have gpt-5.4 in config and collaboration mode, model_info from the models manager, reasoning effort reset to Medium, and truncation policy derived from the new model info.

Call relations: The test calls turn_context.with_model, which consults session.services.models_manager. It then independently asks the models manager for expected model info to confirm the update path used the same source.

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

fn falls_back_to_content_when_structured_is_null()

Purpose: This test checks that a null structured-content value is treated as absent. In that case, the tool's normal content blocks should still be sent onward.

Data flow: It creates an MCP tool result with two text blocks and structured_content set to JSON null. Conversion should produce a text payload containing the serialized content blocks, with success true.

Call relations: The test calls McpCallToolResult.into_function_call_output_payload. It defines the fallback behavior for the converter when structured content exists syntactically but carries no useful value.

Call graph: 4 external calls (assert_eq!, Text, to_string, vec!).

fn success_flag_reflects_is_error_true()

Purpose: This test checks that a tool result marked as an error becomes an unsuccessful function-call output. The content can still be passed through, but the success flag must tell the model it was an error.

Data flow: It creates an MCP tool result with is_error set to true and structured JSON saying there was a bad message. Conversion should serialize that JSON as the body and set success to false.

Call relations: The test calls McpCallToolResult.into_function_call_output_payload. It verifies that error status is preserved during conversion rather than being lost when formatting the payload.

Call graph: 5 external calls (assert_eq!, json!, Text, to_string, vec!).

fn success_flag_true_with_no_error_and_content_used()

Purpose: Checks that a tool result marked as not an error becomes a function-call output marked as successful. It also verifies that the text content is the body that gets used.

Data flow: It starts with a fake MCP tool result containing one text block and is_error: false. It converts that result into a function-call output payload. The expected output is JSON text for the content plus success: true, and the test passes only if the conversion matches exactly.

Call relations: This is a standalone test for the conversion path from McpCallToolResult to FunctionCallOutputPayload. It uses text_block to make the small JSON content item that appears in both the input and expected output.

Call graph: 4 external calls (assert_eq!, Text, to_string, vec!).

async fn wait_for_thread_rolled_back(rx: &async_channel::Receiver<Event>) -> ThreadRolledBackEvent

Purpose: Waits until a test session emits a successful thread rollback event. It lets rollback tests ignore unrelated events and focus on the one they care about.

Data flow: It receives an event channel. For up to two seconds, it reads events from the channel. If an event is ThreadRolledBack, it returns that event payload; otherwise it keeps waiting. If no matching event arrives, the test fails with a timeout.

Call relations: Thread rollback tests call this helper after they trigger a rollback. It sits between the session's event stream and the assertion code, filtering the stream until it finds the success signal.

Call graph: calls 1 internal fn (recv); called by 5 (thread_rollback_clears_history_when_num_turns_exceeds_existing_turns, thread_rollback_drops_last_turn_from_history, thread_rollback_persists_marker_and_replays_cumulatively, thread_rollback_recomputes_previous_turn_settings_and_reference_context_from_replay, thread_rollback_restores_cleared_reference_context_item_after_compaction); 3 external calls (from_secs, now, timeout).

async fn wait_for_thread_rollback_failed(rx: &async_channel::Receiver<Event>) -> ErrorEvent

Purpose: Waits until a test session reports that thread rollback failed. It is used by tests that intentionally trigger invalid rollback requests.

Data flow: It receives an event channel. For up to two seconds, it reads events and looks for an error event whose error kind is ThreadRollbackFailed. When it finds that matching error, it returns it. Other events are skipped.

Call relations: Rollback failure tests call this after sending a bad rollback request, such as asking to roll back zero turns or rolling back while a turn is active. It turns a noisy event stream into the specific failure payload the test needs.

Call graph: calls 1 internal fn (recv); called by 3 (thread_rollback_fails_when_num_turns_is_zero, thread_rollback_fails_when_turn_in_progress, thread_rollback_fails_without_persisted_thread_history); 3 external calls (from_secs, now, timeout).

async fn attach_thread_persistence(session: &mut Session) -> PathBuf

Purpose: Adds real thread persistence to a test session so tests can check what gets saved to disk-like rollout storage. A rollout is the saved record of the thread's events.

Data flow: It reads the session's current configuration, creates a live persisted thread using the session's thread store and metadata such as current folder, model provider, and memory mode, installs that live thread into the session, materializes and flushes the rollout, then returns the path to the rollout file.

Call relations: Persistence and rollback tests call this when they need the session to behave as if it has a saved thread history. It hands the session a LiveThread, then uses the session's rollout methods to make sure there is an actual path tests can inspect.

Call graph: calls 2 internal fn (default, create); called by 9 (cached_guardian_subagent_exposes_its_rollout_path, record_context_updates_and_set_reference_context_item_persists_baseline_without_emitting_diffs, record_context_updates_and_set_reference_context_item_persists_full_reinjection_to_rollout, record_context_updates_and_set_reference_context_item_persists_split_file_system_policy_to_rollout, thread_rollback_clears_history_when_num_turns_exceeds_existing_turns, thread_rollback_drops_last_turn_from_history, thread_rollback_persists_marker_and_replays_cumulatively, thread_rollback_recomputes_previous_turn_settings_and_reference_context_from_replay, thread_rollback_restores_cleared_reference_context_item_after_compaction); 6 external calls (clone, new, current_rollout_path, ensure_rollout_materialized, flush_rollout, get_config).

fn text_block(s: &str) -> serde_json::Value

Purpose: Builds a small JSON object representing a text content block. Tests use it to avoid rewriting the same JSON shape by hand.

Data flow: It takes a string and returns JSON with type set to text and text set to that string. It does not change anything outside itself.

Call relations: The content conversion test uses this helper to create matching input and expected content. It is a tiny fixture builder for test data.

Call graph: 1 external calls (json!).

async fn build_test_config(codex_home: &Path) -> Config

Purpose: Creates a default configuration for tests under a temporary Codex home directory. This gives each test a clean, isolated setup.

Data flow: It receives a path for the test Codex home. It builds a configuration without managed user config, points it at that path, waits for it to load, and returns the finished Config.

Call relations: Many session-building helpers call this first. It supplies the base configuration that later helpers wrap in shared pointers and use to construct sessions, model information, and permission settings.

Call graph: calls 1 internal fn (without_managed_config_for_tests); called by 8 (make_session_and_context, make_session_and_context_with_auth_config_home_and_rx, make_session_configuration_for_tests, make_session_with_config_and_rx, make_session_with_history_source_and_agent_control_and_rx, session_new_fails_when_zsh_fork_enabled_without_packaged_zsh, set_rate_limits_retains_previous_credits, set_rate_limits_updates_plan_type_when_present); 1 external calls (to_path_buf).

fn session_telemetry(
    conversation_id: ThreadId,
    config: &Config,
    model_info: &ModelInfo,
    session_source: SessionSource,
) -> SessionTelemetry

Purpose: Creates a telemetry record for a test session. Telemetry here means the metadata used when reporting session-related analytics, not the conversation content itself.

Data flow: It takes a conversation id, config, model info, and session source. It chooses the offline test model name, fills in fixed test account details, disables prompt logging, and returns a SessionTelemetry value.

Call relations: Session construction helpers call this when they need a realistic telemetry object for TurnContext creation. It feeds test-safe metadata into the same paths used by real sessions.

Call graph: calls 2 internal fn (get_model_offline_for_tests, new); called by 2 (make_session_and_context, make_session_and_context_with_auth_config_home_and_rx).

fn model_with_default_service_tier(default_service_tier: Option<&str>) -> ModelInfo

Purpose: Builds model information for service-tier tests. A service tier is a request option that can ask the backend for a certain processing class, such as priority or default behavior.

Data flow: It starts from offline model info for a fake GPT model, replaces its supported service tiers with a single Fast tier, sets the model's default tier if one is provided, and returns the modified model info.

Call relations: The service-tier tests use this helper to create predictable model metadata. That lets each test focus on what get_service_tier does with configured values and the fast-mode flag.

Call graph: calls 1 internal fn (model_info_from_slug); called by 6 (get_service_tier_does_not_default_when_model_has_no_default, get_service_tier_does_not_use_model_default_when_absent_and_fast_mode_enabled, get_service_tier_does_not_use_model_default_when_fast_mode_disabled, get_service_tier_drops_unsupported_configured_tier_when_fast_mode_enabled, get_service_tier_ignores_configured_tier_when_fast_mode_disabled, get_service_tier_keeps_supported_explicit_tier); 1 external calls (vec!).

fn get_service_tier_does_not_use_model_default_when_absent_and_fast_mode_enabled()

Purpose: Checks that fast mode alone does not automatically choose the model's default service tier when the user did not configure one.

Data flow: It creates model info with Fast as the model default, calls get_service_tier with no configured tier and fast mode enabled, and expects None.

Call relations: This standalone service-tier test uses model_with_default_service_tier to set up the model metadata, then exercises get_service_tier directly.

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

fn get_service_tier_does_not_use_model_default_when_fast_mode_disabled()

Purpose: Checks that the model's default service tier is ignored when fast mode is disabled and the user did not configure a tier.

Data flow: It creates model info with a Fast default, calls get_service_tier with no configured tier and fast mode disabled, and expects no service tier to be sent.

Call relations: This is part of the service-tier test group. It pairs with the fast-mode-enabled case to show that model defaults are not automatically used in either situation.

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

fn get_service_tier_keeps_supported_explicit_tier()

Purpose: Checks that an explicitly configured supported service tier is kept when fast mode allows service-tier selection.

Data flow: It creates model info that supports Fast, passes Fast as the configured tier with fast mode enabled, and expects Fast to come back.

Call relations: This test exercises the positive path for get_service_tier: when the requested tier is valid for the model, the function should preserve it.

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

fn get_service_tier_does_not_default_when_model_has_no_default()

Purpose: Checks that no service tier is invented when the model has no default tier.

Data flow: It creates model info with no default service tier, calls get_service_tier without a configured tier while fast mode is enabled, and expects None.

Call relations: This service-tier test uses the shared model helper to prove that missing model metadata stays missing rather than being filled in with a guess.

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

fn get_service_tier_drops_unsupported_configured_tier_when_fast_mode_enabled()

Purpose: Checks that unsupported configured tiers are removed, while the special default request value is still allowed.

Data flow: It creates a model that supports only Fast. It then tries an unknown string, Flex, and the default service-tier request value. The first two return None; the default request value is preserved.

Call relations: This test drives get_service_tier through several invalid or special inputs. It protects the request-building path from sending tiers the selected model does not support.

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

fn get_service_tier_ignores_configured_tier_when_fast_mode_disabled()

Purpose: Checks that configured service-tier settings are ignored when fast mode is disabled.

Data flow: It tries Fast, the default request value, an unsupported string, and no configured value with fast mode disabled. Every case is expected to return None.

Call relations: This test completes the service-tier group by proving that the fast-mode flag is a gate. Even otherwise valid configured tiers are not used when the gate is closed.

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

async fn session_settings_null_service_tier_update_uses_default_service_tier()

Purpose: Checks how a settings update with a null service tier is interpreted. In this API shape, null means “use the default request value,” not “leave it absent.”

Data flow: It builds a test session configuration, applies a settings update where service_tier is present but contains None, and expects the updated configuration to contain the default service-tier request value.

Call relations: This test uses make_session_configuration_for_tests to get a realistic starting point, then exercises SessionConfiguration.apply for one service-tier edge case.

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

async fn session_settings_legacy_fast_service_tier_update_uses_priority_request_value()

Purpose: Checks that the old service-tier name fast is translated to the current request value for the fast or priority tier.

Data flow: It builds a test session configuration, applies a settings update with the string fast, and expects the stored tier to become ServiceTier::Fast.request_value().

Call relations: This test protects backward compatibility. Older clients can still send fast, while the session stores the newer canonical value.

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

async fn make_session_configuration_for_tests() -> SessionConfiguration

Purpose: Builds a realistic SessionConfiguration for tests without starting a full session. A session configuration is the bundle of choices such as model, instructions, permissions, working folder, and source.

Data flow: It creates a temporary Codex home, loads a test config, derives offline model information, builds the default collaboration mode, copies relevant config fields into a SessionConfiguration, and returns it.

Call relations: Many tests call this helper before applying setting updates or checking lock files and analytics. It centralizes the boilerplate so each test starts from a consistent default session setup.

Call graph: calls 4 internal fn (build_test_config, construct_model_info_offline_for_tests, get_model_offline_for_tests, new); called by 24 (lock_contains_prompts_and_materializes_features, lock_skips_session_values_when_model_catalog_fields_are_not_saved, lock_validation_can_ignore_codex_version_mismatch, lock_validation_ignores_removed_apps_mcp_path_override, lock_validation_rejects_codex_version_mismatch_by_default, lock_validation_reports_config_diff, active_profile_update_rebuilds_network_proxy_config, emit_subagent_session_started_includes_fork_lineage_from_session_configuration, session_configuration_apply_permission_profile_accepts_direct_write_roots, session_configuration_apply_permission_profile_preserves_existing_deny_read_entries (+14 more)); 5 external calls (clone, new, new, from_config, tempdir).

async fn emit_subagent_session_started_includes_fork_lineage_from_session_configuration()

Purpose: Checks that analytics for a subagent session include both its parent thread id and the thread it was forked from. A subagent is a child agent/session started from another session.

Data flow: It starts a mock HTTP server, configures an analytics client to send to it, creates parent, fork, and child thread ids, puts the fork id into a session configuration, emits the subagent-started analytics event, then waits until the mock server receives the event and checks the JSON fields.

Call relations: This test uses make_session_configuration_for_tests to create the thread configuration snapshot passed to emit_subagent_session_started. The mock server stands in for the real analytics service so the test can inspect the outgoing request.

Call graph: calls 6 internal fn (new, make_session_configuration_for_tests, from_auth_for_testing, create_dummy_chatgpt_auth_for_testing, from, new); 9 external calls (from_millis, from_secs, given, start, new, assert_eq!, from_slice, sleep, timeout).

async fn resolved_environments_for_configuration(
    session_configuration: &SessionConfiguration,
) -> (Arc<EnvironmentManager>, TurnEnvironmentSnapshot)

Purpose: Builds resolved test environments from a session configuration. An environment is where a turn runs, including its working folder and filesystem view.

Data flow: It creates a test environment manager and a ThreadEnvironments object with a default shell snapshot disabled. It applies the session configuration's environment selections, takes a snapshot of the resolved result, and returns both the manager and snapshot.

Call relations: Session-building helpers call this before making a TurnContext. It connects high-level environment choices in the configuration to concrete per-turn environment data.

Call graph: calls 5 internal fn (new, environment_selections, default_user_shell, disabled, default_for_tests); called by 2 (make_session_and_context, make_session_and_context_with_auth_config_home_and_rx); 3 external calls (clone, new, default).

async fn session_configuration_apply_preserves_profile_file_system_policy_on_cwd_only_update()

Purpose: Checks that changing only the current working directory does not erase or reinterpret a profile's file access policy. File access policy means the rules for what paths can be read or written.

Data flow: It builds a session configuration, creates a restricted filesystem policy with write access to project roots and read access to a docs folder, installs it as the permission profile, then applies an update that only changes the working directory. The expected result is the same policy materialized against the original workspace roots.

Call relations: This test exercises SessionConfiguration.apply for a directory-only update. It protects permission profiles from being accidentally rewritten just because the session moves to another folder.

Call graph: calls 6 internal fn (make_session_configuration_for_tests, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, restricted, from, new); 6 external calls (default, new, assert_eq!, create_dir_all, tempdir, vec!).

async fn session_configuration_apply_permission_profile_preserves_existing_deny_read_entries()

Purpose: Checks that applying a new permission profile does not discard existing deny rules. A deny rule is an explicit “do not allow this,” such as blocking .env files.

Data flow: It creates a workspace-write policy, adds a deny glob for **/*.env and a scan depth to the existing filesystem policy, then applies a requested permission profile based on the normal workspace policy. The updated configuration should include the requested policy plus the preserved deny rule and scan depth.

Call relations: This test calls SessionConfiguration.apply with a permission-profile update. It ensures safety-related restrictions survive profile changes instead of being overwritten by a more general request.

Call graph: calls 6 internal fn (make_session_configuration_for_tests, from_runtime_permissions, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd, new); 5 external calls (default, new, new_workspace_write_policy, assert_eq!, tempdir).

async fn session_configuration_apply_permission_profile_accepts_direct_write_roots()

Purpose: Checks that a permission profile can directly grant write access to an absolute folder outside the normal workspace-root shorthand.

Data flow: It creates a temporary external folder, canonicalizes it into an absolute path, builds a restricted filesystem policy granting write access to that path, converts it into a permission profile, and applies it. The updated configuration must keep that permission profile, keep the filesystem policy, and expose an equivalent legacy sandbox policy with that writable root.

Call relations: This test exercises the bridge between modern permission profiles and older sandbox policy fields. It proves direct path grants are not lost during conversion.

Call graph: calls 5 internal fn (make_session_configuration_for_tests, from_runtime_permissions, restricted, new, from_absolute_path); 6 external calls (default, new, assert_eq!, canonicalize_preserving_symlinks, tempdir, vec!).

async fn session_configuration_apply_rebinds_symbolic_profile_to_updated_workspace_roots()

Purpose: Checks that symbolic project-root permissions follow updated workspace roots. A symbolic permission is like saying “the project roots” instead of naming one exact folder.

Data flow: It starts with one old workspace root, creates a permission profile that writes to project_roots, then applies an update with a new workspace root, an active profile name, and profile workspace roots. The resulting policy should allow writing to the new root, not the old root, and should store the active profile metadata.

Call relations: This test drives SessionConfiguration.apply through a combined workspace-root and permission-profile update. It ensures symbolic rules are rebound to the new project roots at the right time.

Call graph: calls 4 internal fn (new, make_session_configuration_for_tests, from_runtime_permissions, restricted); 5 external calls (default, assert!, assert_eq!, tempdir, vec!).

async fn session_configuration_apply_retargets_implicit_workspace_root_on_cwd_update()

Purpose: Checks that when the current working directory is also an implicit workspace root, changing the directory retargets that implicit root while preserving extra roots.

Data flow: It sets the current directory and workspace roots to include an old root plus an extra root. It installs a symbolic project-root write policy, then applies a current-directory update to a new root. The updated workspace roots should be the new root plus the extra root, and the policy should write to those, not the old root.

Call relations: This test protects the logic that updates workspace roots during SessionConfiguration.apply. It distinguishes the automatically inferred root from user-added extra roots.

Call graph: calls 4 internal fn (make_session_configuration_for_tests, from_runtime_permissions, restricted, new); 6 external calls (default, new, assert!, assert_eq!, tempdir, vec!).

async fn active_profile_update_rebuilds_network_proxy_config() -> std::io::Result<()>

Purpose: Checks that switching permission profiles rebuilds the session's network proxy settings. A proxy is a network middleman the session may be required to use.

Data flow: It writes a temporary config file with two permission profiles: one locked down and one web-enabled with a proxy URL. It loads config for the locked profile and confirms the proxy is not selected, then loads config for the web-enabled profile. It applies that selected profile to an existing session configuration and verifies the resulting config now contains the proxy host and has SOCKS disabled.

Call relations: This test uses make_session_configuration_for_tests as a base, then replaces its stored permission state and original config. It exercises SessionConfiguration.apply to confirm that changing the active profile updates not only permissions but also runtime network configuration.

Call graph: calls 1 internal fn (make_session_configuration_for_tests); 13 external calls (clone, new, default, assert!, assert_eq!, assert_ne!, Access, default, from, write (+3 more)).

async fn new_default_turn_uses_config_aware_skills_for_role_overrides()

Purpose: Checks that a new default turn respects skills disabled by an applied agent role. Skills are reusable capability descriptions loaded from configuration files.

Data flow: It creates a session, writes a demo skill file, confirms the parent config sees the skill as enabled, then writes a role config that disables that skill. It applies the role to a cloned child config, stores that config in the session state, creates a new default turn, and verifies the skill is discovered but disabled.

Call relations: This test uses make_session_and_context to get a full test session. It then calls the role-application path and finally new_default_turn_with_sub_id, proving that turn creation reads the role-adjusted configuration when loading skills.

Call graph: calls 2 internal fn (apply_role_to_config, make_session_and_context); 8 external calls (clone, new, new, assert_eq!, skills_load_input_from_config, format!, create_dir_all, write).

async fn session_configuration_apply_retargets_legacy_workspace_root_on_cwd_update()

Purpose: Checks that older-style workspace-write sandbox rules follow the new current directory when the old workspace root was only implicit.

Data flow: It creates a session configuration whose workspace roots contain the original current directory. It builds a legacy workspace-write policy for that directory, installs it, then applies a current-directory update to another repo path. The updated configuration should have the new repo as its workspace root, allow writing there, and no longer allow writing to the old directory.

Call relations: This test focuses on legacy sandbox compatibility inside SessionConfiguration.apply. It makes sure older policies still behave safely when the session changes folders.

Call graph: calls 6 internal fn (make_session_configuration_for_tests, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd, from, new); 6 external calls (default, new, assert!, assert_eq!, tempdir, vec!).

async fn session_configuration_apply_preserves_absolute_cwd_write_root_on_cwd_update()

Purpose: Checks that an explicit absolute write grant to the old current directory stays exactly that, rather than being treated as a symbolic workspace-root grant.

Data flow: It creates two directories, sets the first as the current directory, and installs a filesystem policy that reads root and writes the first directory by absolute path. After applying an update to move the current directory to the second directory, the filesystem policy should be unchanged: the old absolute path remains writable and the new current directory is not automatically writable.

Call relations: This test guards an important distinction in SessionConfiguration.apply: exact path grants and symbolic workspace-root grants must not be confused.

Call graph: calls 4 internal fn (make_session_configuration_for_tests, from_runtime_permissions_with_enforcement, restricted, new); 7 external calls (default, new, assert!, assert_eq!, create_dir_all, tempdir, vec!).

async fn session_update_settings_does_not_rewrite_sticky_environment_cwds()

Purpose: Checks that updating the session's primary current directory does not rewrite the stored current directories of sticky turn environments. Sticky environments keep their own location across turns.

Data flow: It creates a session, records its current environment selections, creates a new project directory, and calls session.update_settings with a new primary current directory plus the existing environments. It then checks that the session's primary cwd changed, the stored environments stayed the same, and a newly created turn still uses the original config cwd.

Call relations: This test goes through the real Session.update_settings method rather than only SessionConfiguration.apply. It then creates a new default turn to confirm the setting change did not unexpectedly affect per-turn environment cwd behavior.

Call graph: calls 2 internal fn (make_session_and_context, new); 3 external calls (default, assert_eq!, create_dir_all).

async fn relative_cwd_update_without_environments_resolves_under_session_cwd()

Purpose: Checks that a current-directory update still works when there are no explicit environment selections.

Data flow: It creates a session, clears the stored environment list, builds a project path under the original current directory, creates that folder, and updates settings with that new path and no environments. The session configuration should now use the project path as cwd and still have no environment selections.

Call relations: This test uses the full session update path. It covers the simpler case where the session has only a primary cwd and no separate turn environments to preserve.

Call graph: calls 2 internal fn (make_session_and_context, new); 5 external calls (default, new, assert!, assert_eq!, create_dir_all).

async fn environment_settings_preserve_explicit_primary_cwd()

Purpose: Checks that explicit environment current directories are preserved when the session's primary current directory changes.

Data flow: It creates a session, installs an explicit local environment pointing at an environment folder, then updates the primary cwd to a different project folder while passing the same environment list. The session cwd should change, but the environment entry should still point at the original environment folder.

Call relations: This test exercises Session.update_settings with both a primary cwd update and explicit environments. It proves the update does not rewrite environment entries behind the caller's back.

Call graph: calls 2 internal fn (make_session_and_context, new); 4 external calls (default, assert_eq!, create_dir_all, vec!).

async fn absolute_cwd_update_with_turn_environment_is_allowed()

Purpose: Checks that starting a new turn with an absolute current directory and an explicit matching environment is valid.

Data flow: It creates a session with an event receiver, makes an absolute subdirectory, and starts a new turn with settings that choose that cwd and one local environment at the same path. The returned turn context should use that absolute cwd in both its deprecated direct field and its config, and should contain one resolved turn environment.

Call relations: This test calls new_turn_with_sub_id, which applies settings for a single turn. It confirms that absolute paths are accepted when they are paired with explicit environment selections.

Call graph: calls 2 internal fn (make_session_and_context_with_rx, new); 4 external calls (default, assert_eq!, create_dir_all, vec!).

async fn session_new_fails_when_zsh_fork_enabled_without_packaged_zsh()

Purpose: Checks that session startup fails clearly if the zsh-fork shell feature is enabled but no packaged zsh fork path is available. zsh is a Unix shell; this feature needs a bundled helper to work.

Data flow: It builds a test config, enables the shell zsh fork feature, removes the zsh path, then constructs all the services needed to call Session::new. It expects construction to fail and checks that the error message explains that no packaged zsh fork is available.

Call relations: This is a full session-construction failure test. It uses many of the same pieces as normal startup, but deliberately removes one required dependency so Session::new must reject the setup.

Call graph: calls 17 internal fn (new, new, default, new, new, build_test_config, models_manager_with_provider, default_for_tests, new, from_auth_for_testing (+7 more)); 12 external calls (clone, new, new, assert!, unbounded, default, default, format!, panic!, from_config (+2 more)).

async fn make_session_and_context() -> (Session, TurnContext)

Purpose: Builds a complete test Session and matching TurnContext. A turn context is the per-request view of the session, including config, model info, environments, and loaded skills.

Data flow: It creates a temporary config, fake authentication, model manager, agent control, execution policy, session configuration, telemetry, state, resolved environments, plugin and skill managers, network approval service, and all session services. It loads plugins and skills, builds a turn context, manually constructs the Session, and returns both.

Call relations: Many tests call this when they need more than a bare configuration. It is the main test fixture builder for code paths that require a real session object plus a ready-to-use turn context.

Call graph: calls 33 internal fn (new, new, new_uninitialized_with_permission_profile, new, new, new, new, default, new, new (+15 more)); called by 269 (process_compacted_history_with_test_session, test_review_params, build_guardian_prompt_includes_parent_turn_denied_reads, build_guardian_prompt_items_includes_parent_session_id, guardian_review_request_layout_matches_model_visible_request_snapshot, guardian_test_session_and_turn_with_base_url, routes_approval_to_guardian_allows_granular_review_policy, routes_approval_to_guardian_can_use_app_reviewer_override, routes_approval_to_guardian_requires_guardian_reviewer, hook_run_analytics_payload_falls_back_to_turn_context_id (+15 more)); 28 external calls (clone, new, new, new, default, new, from, new, new, from_pointee (+15 more)).

async fn make_session_with_config(
    mutator: impl FnOnce(&mut Config),
) -> anyhow::Result<Arc<Session>>

Purpose: Creates a test session after letting the caller modify the configuration. It is a convenience wrapper for tests that need a custom config but do not need the event receiver.

Data flow: It receives a function that mutates a Config. It forwards that mutator to make_session_with_config_and_rx, discards the returned event receiver, and returns the session wrapped in Arc, or an error if setup failed.

Call relations: Tests call this when they only need the session. It delegates the real setup work to make_session_with_config_and_rx, keeping callers shorter and clearer.

Call graph: calls 1 internal fn (make_session_with_config_and_rx); called by 5 (danger_full_access_tool_attempts_do_not_enforce_managed_network, danger_full_access_turns_do_not_expose_managed_network_proxy, reload_user_config_layer_refreshes_hooks, shell_tool_cancellation_waits_for_runtime_cleanup, workspace_write_turns_continue_to_expose_managed_network_proxy).

async fn load_latest_config_for_session(session: &Session) -> Config

Purpose: Reloads configuration from disk for the same Codex home and current directory as an existing session. Tests use this to check whether runtime config refresh sees new file changes.

Data flow: It asks the session for its current config, then builds a fresh config using the same Codex home and the session cwd as a fallback. The newly loaded Config is returned.

Call relations: Config-refresh tests call this after changing config files or session state. It represents the “what would the config loader see now?” step before comparing old and new effective settings.

Call graph: called by 3 (config_change_contributor_observes_effective_config_changes, refresh_runtime_config_refreshes_hooks, refresh_runtime_config_updates_runtime_refreshable_fields_and_keeps_session_static_settings); 2 external calls (default, get_config).

async fn make_session_with_config_and_rx(
    mutator: impl FnOnce(&mut Config),
) -> anyhow::Result<(Arc<Session>, async_channel::Receiver<Event>)>

Purpose: Builds a test session and returns both the session and a receiver that can observe events the session emits. Tests use it when they need to tweak the configuration before the session is created.

Data flow: It starts with a caller-provided configuration mutator. It creates a temporary Codex home, builds a default test config, lets the mutator change it, then constructs the many pieces a session needs: fake authentication, model information, permission settings, environment selection, plugin and skill managers, and event channels. It returns the finished shared session plus the event receiver.

Call relations: This helper is called by higher-level test helpers and by tests that need a customized session. Its main handoff is to Session::new, which receives the assembled configuration and services so the test can behave like a real session without contacting real services.

Call graph: calls 17 internal fn (new, new, default, new, new, build_test_config, models_manager_with_provider, default_for_tests, new, from_auth_for_testing (+7 more)); called by 2 (make_session_with_config, user_shell_commands_do_not_inherit_managed_network_proxy); 10 external calls (clone, new, new, unbounded, default, default, from_config, tempdir, vec!, channel).

async fn make_session_with_history_source_and_agent_control_and_rx(
    initial_history: InitialHistory,
    session_source: SessionSource,
    agent_control: AgentControl,
) -> anyhow::Result<(Arc<Se

Purpose: Builds a test session where the starting history, session source, and agent-control settings can be chosen. Tests use it to check how resumed root and subagent sessions pick their identities.

Data flow: It receives an initial history value, a description of where the session came from, and agent-control rules. It creates a temporary, ephemeral config, fake auth, model settings, environments, event channels, managers, and a local thread store backed by a test state database. It returns the created session and its event receiver.

Call relations: The resumed-session identity tests call this helper so they can create sessions with precise combinations of resumed history and parent-agent control. Like the other builder, it hands all prepared pieces to Session::new.

Call graph: calls 18 internal fn (new, new, default, new, new, build_test_config, models_manager_with_provider, default_for_tests, new, from_auth_for_testing (+8 more)); called by 2 (resumed_root_session_uses_thread_id_as_session_id, resumed_subagent_session_keeps_inherited_session_id); 10 external calls (clone, new, new, clone, unbounded, default, from_config, tempdir, vec!, channel).

async fn resumed_root_session_uses_thread_id_as_session_id()

Purpose: Checks that when a normal root session is resumed, its session id matches the resumed thread id. This matters because callers and events need a stable identity for the restored conversation.

Data flow: It creates a fresh thread id, resumes a session from that id, then reads the session's thread id, session id, and first configuration event. The expected result is that both the session object and the emitted event use the resumed thread as the session id.

Call relations: It uses make_session_with_history_source_and_agent_control_and_rx to create the resumed session. After setup, it waits for the SessionConfigured event and checks that Session::new reported the same identity outward.

Call graph: calls 2 internal fn (make_session_with_history_source_and_agent_control_and_rx, new); 5 external calls (new, assert_eq!, default, panic!, Resumed).

async fn resumed_subagent_session_keeps_inherited_session_id()

Purpose: Checks that a resumed subagent keeps the parent session id instead of replacing it with its own thread id. This preserves the idea that several agent threads can belong to one larger session.

Data flow: It creates a parent thread/session id and a separate child thread id. It resumes a subagent from the child thread while passing agent-control data that contains the parent session id. It then verifies that the thread id is the child thread, but the session id remains the inherited parent id, including in the emitted configuration event.

Call relations: It relies on make_session_with_history_source_and_agent_control_and_rx to build a resumed subagent session. The test observes the SessionConfigured event to ensure the identity choice is visible to clients too.

Call graph: calls 3 internal fn (make_session_with_history_source_and_agent_control_and_rx, from, new); 6 external calls (new, SubAgent, assert_eq!, default, panic!, Resumed).

async fn notify_request_permissions_response_ignores_unmatched_call_id()

Purpose: Checks that a permission response with an unknown call id is ignored. This prevents an unrelated or stale response from accidentally granting powers to the current turn.

Data flow: It creates a session, marks a default active turn, then sends a permission response for the call id "missing". Since no pending request uses that id, nothing should be recorded. Reading granted turn permissions afterward returns none.

Call relations: The test calls the session's notification method directly. It verifies the guard around matching permission responses to the original request before any grant-recording logic can run.

Call graph: calls 2 internal fn (make_session_and_context, default); 2 external calls (default, assert_eq!).

async fn record_granted_request_permissions_for_turn_uses_originating_turn()

Purpose: Checks that a turn-scoped permission grant is written to the turn that made the request, even if another turn has become active since then. This avoids granting permission to the wrong piece of work.

Data flow: It creates one active turn and saves its turn state, then replaces the session's active turn with a new one. It records a turn-scoped network permission while explicitly passing the original turn state. The original turn receives the grant; the current turn and the session-level grants remain unchanged.

Call relations: The test exercises record_granted_request_permissions_for_turn directly. It models the race where a response arrives after the active turn pointer has moved on.

Call graph: calls 2 internal fn (make_session_and_context, default); 3 external calls (clone, default, assert_eq!).

async fn request_permission_grants_are_environment_keyed()

Purpose: Checks that permission grants are stored separately for each environment. A grant for a remote environment must not silently apply to the local environment.

Data flow: It records a turn-scoped grant for environment "remote" and confirms only that environment sees it. Then it records a session-scoped grant for the same environment and confirms the session grant is also keyed to "remote", not "local".

Call relations: The test calls the session's grant-recording path twice, once for turn scope and once for session scope. It then reads back both turn and session permission stores to confirm environment separation.

Call graph: calls 2 internal fn (make_session_and_context, default); 3 external calls (clone, default, assert_eq!).

async fn enable_strict_auto_review_for_turn_uses_originating_turn()

Purpose: Checks that strict auto-review is enabled on the turn that asked for it, not merely on whatever turn is current later. Strict auto-review is a mode where later actions are checked more carefully.

Data flow: It creates an originating turn state, records a turn-scoped permission response with strict_auto_review set to true, and then reads that original turn state. The output is that strict auto-review is enabled there.

Call relations: This is another direct test of record_granted_request_permissions_for_turn. It focuses on the strict-auto-review flag rather than the permission profile itself.

Call graph: calls 2 internal fn (make_session_and_context, default); 3 external calls (clone, default, assert!).

fn strict_auto_review_session_scope_grants_no_permissions()

Purpose: Checks that a response asking for strict auto-review at session scope is normalized into a safe no-permission, turn-scoped response. This prevents a stricter review mode request from becoming a broad session grant.

Data flow: It builds a requested network permission and a response that combines session scope with strict auto-review. It passes both through the session's normalization function. The returned response has default empty permissions, turn scope, and strict auto-review turned off.

Call relations: The test exercises Session::normalize_request_permissions_response directly. It verifies the cleanup rule before any response would be recorded.

Call graph: 4 external calls (default, assert_eq!, normalize_request_permissions_response, new).

async fn request_permissions_emits_event_when_granular_policy_allows_requests()

Purpose: Checks that when the approval policy allows permission requests, the session emits a request event and waits for the answer. This is the user-facing approval flow.

Data flow: It creates a session and turn context, changes the approval policy so request-permissions is allowed, and starts a permission request in a background task. The test receives the emitted RequestPermissions event, checks its call id, environment id, and working directory, sends back an approval response, and confirms the original request returns that response.

Call relations: The test drives request_permissions_for_environment and observes the session event channel. It then uses notify_request_permissions_response to complete the pending request.

Call graph: calls 2 internal fn (make_session_and_context_with_rx, default); 11 external calls (clone, get_mut, new, new, from_secs, default, Granular, assert_eq!, panic!, spawn (+1 more)).

async fn request_permissions_tool_resolves_relative_paths_against_selected_environment()

Purpose: Checks that the request_permissions tool resolves relative file paths against the chosen environment's working directory. This prevents asking for access to the wrong file when multiple environments exist.

Data flow: It creates a special working directory for a "remote" environment and configures the turn to use it. Then it invokes the request_permissions tool with a relative path, "relative.txt". The emitted request contains an absolute path under the remote environment directory, and the handler completes after the test sends a matching response.

Call relations: The test goes through RequestPermissionsHandler, which parses the tool call and forwards the request into the session. It observes the emitted RequestPermissions event and answers it through notify_request_permissions_response.

Call graph: calls 6 internal fn (make_session_and_context_with_rx, new, default, new, plain, from_abs_path); 15 external calls (clone, get_mut, new, new, default, from_secs, Granular, assert_eq!, json!, panic! (+5 more)).

async fn request_permissions_tool_rejects_unknown_environment_id()

Purpose: Checks that the request_permissions tool rejects an environment id that is not part of the current turn. This gives the model a clear error instead of silently using the wrong environment.

Data flow: It invokes the tool with environment_id set to "missing" and a network permission request. The handler returns an error meant to be shown back to the model, saying the turn environment id is unknown.

Call relations: This test calls RequestPermissionsHandler directly. It confirms validation happens before the session tries to emit or record any permission request.

Call graph: calls 3 internal fn (make_session_and_context, new, plain); 6 external calls (new, new, assert_eq!, json!, panic!, new).

async fn request_permissions_response_materializes_session_cwd_grants_before_recording()

Purpose: Checks that special file-system permissions, such as "project roots", are converted into concrete paths before being stored as session-wide grants. This makes later permission checks compare real paths instead of vague placeholders.

Data flow: It requests write access to the special project-roots path, receives the emitted permission request, and replies with a session-scoped grant. The session turns that special path into the actual request working directory before returning the response and before saving the session grant.

Call relations: The test drives request_permissions_for_environment, answers through notify_request_permissions_response, and then reads granted_session_permissions to verify the recorded form is materialized.

Call graph: calls 3 internal fn (make_session_and_context_with_rx, default, from_read_write_roots); 12 external calls (clone, get_mut, new, new, default, from_secs, Granular, assert_eq!, panic!, spawn (+2 more)).

async fn request_permissions_is_auto_denied_when_granular_policy_blocks_tool_requests()

Purpose: Checks that permission requests are automatically denied when the granular approval policy disables request-permissions. In that mode, no user-facing request event should be emitted.

Data flow: It sets the policy so request_permissions is false, then asks for a network permission. The session immediately returns an empty turn-scoped response and the event receiver stays quiet.

Call relations: The test calls request_permissions_for_environment directly. It verifies that policy checking happens before the event-based approval flow starts.

Call graph: calls 2 internal fn (make_session_and_context_with_rx, default); 7 external calls (get_mut, new, new, default, Granular, assert!, assert_eq!).

async fn submit_with_id_captures_current_span_trace_context()

Purpose: Checks that when a submission is sent into Codex, it captures the current trace context if the submission does not already have one. Trace context is metadata that lets logs from related work be connected across tasks and services.

Data flow: It creates a Codex object with a submission channel, installs test tracing, and enters a span with a known W3C trace id. It submits an interrupt operation without trace data. The item received from the channel now contains the trace context from the current span.

Call relations: The test calls Codex::submit_with_id and then reads the submission channel. It proves the method enriches outgoing submissions with tracing information.

Call graph: calls 2 internal fn (make_session_and_context, install_test_tracing); 7 external calls (new, assert!, assert_eq!, bounded, unbounded, info_span!, channel).

async fn new_default_turn_captures_current_span_trace_id()

Purpose: Checks that a newly created default turn remembers the current trace id. This lets later turn work be tied back to the request that started it.

Data flow: It enters a tracing span with a known trace id, calls session.new_default_turn, and reads the turn context's trace_id field. The stored trace id matches the active span's trace id.

Call relations: The test calls new_default_turn inside an instrumented span. It verifies trace metadata is copied from the surrounding request into the turn context.

Call graph: calls 2 internal fn (make_session_and_context, install_test_tracing); 4 external calls (current, assert!, assert_eq!, info_span!).

fn submission_dispatch_span_prefers_submission_trace_context()

Purpose: Checks that a dispatch span uses the trace context attached to the submission rather than whatever trace is currently ambient. This keeps work connected to the client request that created the submission.

Data flow: It creates one ambient trace and a different trace on a submission. It builds the dispatch span while inside the ambient span. The dispatch span's trace id matches the submission trace, not the ambient one.

Call relations: The test calls submission_dispatch_span directly. It confirms the dispatch layer prioritizes explicit submission metadata.

Call graph: calls 1 internal fn (install_test_tracing); 3 external calls (assert!, assert_eq!, info_span!).

fn submission_dispatch_span_uses_debug_for_realtime_audio()

Purpose: Checks that dispatch spans for real-time audio submissions are logged at debug level. Audio frames can be frequent, so this avoids noisy normal-level tracing.

Data flow: It creates a submission whose operation is a real-time audio frame and asks for its dispatch span. The span metadata reports DEBUG level.

Call relations: The test calls submission_dispatch_span with a RealtimeConversationAudio operation. It verifies the special logging-level rule for high-volume audio events.

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

fn op_kind_for_input_and_context_ops()

Purpose: Checks the short string names returned for user-input and thread-settings operations. These names are useful for logging, tracing, and routing without dumping full operation data.

Data flow: It creates a UserInput operation and a ThreadSettings operation, calls kind on each, and compares the returned strings with the expected labels.

Call relations: The test exercises Op::kind directly. It protects the stable labels used elsewhere by the session machinery.

Call graph: 1 external calls (assert_eq!).

async fn user_turn_updates_approvals_reviewer()

Purpose: Checks that a user turn can update the session's approvals reviewer setting. This matters when a client changes how approvals should be reviewed during a conversation.

Data flow: It creates a session, builds a user input operation that includes thread settings with approvals_reviewer set to AutoReview, and passes it through the user-input handler. Afterward, the session state shows AutoReview in the session configuration.

Call relations: The test calls handlers::user_input_or_turn, which applies user input and thread-setting updates. It then inspects session state to confirm the setting was stored.

Call graph: calls 3 internal fn (user_input_or_turn, make_session_and_context_with_rx, local_selections); 3 external calls (default, assert_eq!, vec!).

async fn turn_environments_set_primary_environment()

Purpose: Checks that starting a turn with selected environments sets the primary environment and updates the turn working directory. The primary environment is the default place where tools run.

Data flow: It creates a selected working directory, starts a new turn with one local environment rooted there, then reads the turn context and stored environment service. The turn has one environment, that environment is primary, the turn config uses the selected directory, and later default turns reuse the stored primary environment.

Call relations: The test calls session.new_turn_with_sub_id with an environment update, then checks both the returned turn context and the session's turn-environment service. It also calls new_default_turn to verify the selection persists.

Call graph: calls 3 internal fn (make_session_and_context_with_rx, new, try_from); 4 external calls (default, assert!, assert_eq!, vec!).

async fn default_turn_does_not_overlay_legacy_fallback_cwd_onto_stored_thread_environments()

Purpose: Checks that a default turn respects stored thread environments instead of overwriting them with the older fallback working directory. This prevents losing the user's selected environment.

Data flow: It manually stores a selected environment and matching session configuration, then creates a default turn. The turn keeps that selected environment and uses its working directory in both the deprecated cwd field and the current config.

Call relations: The test updates the session's turn-environment service and session configuration, then calls new_default_turn. It verifies that stored environment state wins over legacy fallback behavior.

Call graph: calls 3 internal fn (make_session_and_context_with_rx, local, try_from); 3 external calls (assert!, assert_eq!, vec!).

async fn default_turn_honors_empty_stored_thread_environments()

Purpose: Checks that an explicitly empty environment list stays empty for a default turn. Empty means no primary environment, not "recreate the default one."

Data flow: It clears stored environment selections and the session configuration environment list, then creates a default turn. The turn has no primary environment and no turn environments, while its working directory falls back to the session config directory.

Call relations: The test prepares empty stored state and calls new_default_turn. It protects the distinction between missing environment data and deliberately empty environment data.

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

async fn primary_environment_uses_first_turn_environment()

Purpose: Checks that the primary environment is simply the first environment in the turn's environment list. This makes ordering meaningful and predictable.

Data flow: It starts with an existing turn environment, adds a second one with a different working directory, and then asks for the primary environment. The primary remains the first environment, while the second keeps its own working directory.

Call relations: The test mutates the turn context directly and calls the primary helper. It verifies the selection rule used by other session code.

Call graph: calls 3 internal fn (make_session_and_context, new, from_abs_path); 2 external calls (clone, assert_eq!).

async fn empty_turn_environments_clear_primary_environment()

Purpose: Checks that starting a turn with an empty environment selection clears the primary environment. This lets clients intentionally run a turn with no selected execution environment.

Data flow: It starts a new turn with an environment update containing an empty list. The returned turn context has no primary environment and no environment entries, while its working directory remains the session's configured directory.

Call relations: The test calls session.new_turn_with_sub_id with an empty TurnEnvironmentSelections value. It verifies the new-turn setup code does not invent a replacement environment.

Call graph: calls 2 internal fn (make_session_and_context_with_rx, new); 4 external calls (default, assert!, assert_eq!, vec!).

async fn spawn_task_turn_span_inherits_dispatch_trace_context()

Purpose: Checks that a spawned session task runs under a trace connected to the submission dispatch trace. This keeps logs from the task linked to the submission that caused it.

Data flow: It defines a small task that records the current trace context when it runs. The test creates a request trace, builds a submission dispatch span from it, spawns the task inside that span, waits for turn completion, and compares trace ids. The task has the same trace id but a different span id, meaning it is part of the same trace but has its own span.

Call relations: The test uses submission_dispatch_span and session.spawn_task together. The custom SessionTask captures the trace context so the test can verify tracing is inherited across the task boundary.

Call graph: calls 2 internal fn (make_session_and_context_with_rx, install_test_tracing); 11 external calls (clone, new, from_secs, assert!, assert_eq!, assert_ne!, context_from_w3c_trace_context, new, timeout, info_span! (+1 more)).

async fn shutdown_complete_does_not_append_to_thread_store_after_shutdown()

Purpose: Checks that once shutdown is complete, the session does not append extra data to the thread store. This avoids writing stale or duplicate persistence records after the conversation has ended.

Data flow: It replaces the session's thread store with an in-memory store that counts calls, creates live thread persistence, then runs the shutdown handler. The store reports one thread creation and one thread shutdown, with no extra append calls.

Call relations: The test sets up a LiveThread and calls handlers::shutdown. It checks the thread-store call counters afterward to verify clean persistence behavior.

Call graph: calls 3 internal fn (make_session_and_context, default, create); 6 external calls (clone, new, new, assert!, assert_eq!, default).

async fn submission_loop_channel_close_emits_thread_stop_lifecycle()

Purpose: Checks that when the submission channel closes, thread-stop lifecycle callbacks are run. Lifecycle callbacks let extensions clean up or record data when a thread ends.

Data flow: It registers a test extension contributor that checks the thread id and stored extension data when on_thread_stop runs. Then it closes the submission channel and runs the submission loop. The callback is called exactly once.

Call relations: The test configures the session extension registry and calls submission_loop with a closed receiver. The loop's shutdown path hands control to the extension lifecycle hook.

Call graph: calls 1 internal fn (make_session_and_context); 6 external calls (clone, new, assert_eq!, bounded, new, new).

async fn submission_loop_channel_close_aborts_active_turn_before_thread_stop_lifecycle()

Purpose: Checks shutdown ordering when the submission channel closes: active turns must be aborted before the thread-stop callback runs. This gives extensions a clear sequence of events.

Data flow: It registers a recorder for both turn-abort and thread-stop lifecycle events, starts a never-ending task as the active turn, closes the submission channel, and runs the submission loop. The recorded order is turn_abort first, then thread_stop.

Call relations: The test uses session.spawn_task to create active work, then calls submission_loop. The loop cancels the turn and invokes extension lifecycle callbacks in the expected order.

Call graph: calls 1 internal fn (make_session_and_context); 7 external calls (clone, new, new, assert_eq!, bounded, new, new).

async fn shutdown_and_wait_allows_multiple_waiters()

Purpose: Checks that more than one caller can wait for Codex shutdown at the same time. This is useful when different parts of the program all need to know when the session loop has ended.

Data flow: It creates a Codex object with a fake session loop that receives a shutdown submission and finishes after a short delay. Two tasks call shutdown_and_wait concurrently. Both complete successfully.

Call relations: The test calls Codex::shutdown_and_wait from two spawned tasks. The fake session-loop termination handle stands in for the real background loop.

Call graph: calls 1 internal fn (make_session_and_context); 9 external calls (clone, new, from_millis, assert_eq!, bounded, unbounded, spawn, sleep, channel).

async fn shutdown_and_wait_waits_when_shutdown_is_already_in_progress()

Purpose: Checks that shutdown_and_wait waits for the session loop to finish even if sending the shutdown command cannot start a fresh shutdown because shutdown is already underway. Waiting is still required so callers know cleanup is complete.

Data flow: It creates a Codex object whose submission receiver is already closed and whose session loop only finishes after a one-shot signal. It starts shutdown_and_wait, confirms it is still waiting, sends the completion signal, and then the waiter completes successfully.

Call relations: The test calls Codex::shutdown_and_wait while the fake loop is blocked. It verifies the method is tied to loop termination, not just to sending a shutdown message.

Call graph: calls 1 internal fn (make_session_and_context); 10 external calls (clone, new, from_millis, assert!, bounded, unbounded, spawn, channel, sleep, channel).

async fn shutdown_and_wait_shuts_down_cached_guardian_subagent()

Purpose: Checks that when a parent Codex session shuts down, a cached guardian subagent is also told to shut down. This matters because leftover child sessions could keep tasks, channels, or resources alive after the main session is gone.

Data flow: The test creates a parent session and a fake child Codex session, then stores the child inside the parent guardian-review cache. It calls the parent shutdown method and waits on a one-time signal from the child. The expected result is that the child receives a shutdown operation.

Call relations: The async test runner invokes this test. It builds sessions through make_session_and_context, starts lightweight background loops with tokio, then exercises Codex::shutdown_and_wait to prove shutdown flows from the parent to the cached guardian subagent.

Call graph: calls 1 internal fn (make_session_and_context); 8 external calls (clone, new, assert_eq!, bounded, unbounded, spawn, channel, channel).

async fn cached_guardian_subagent_exposes_its_rollout_path()

Purpose: Checks that a cached guardian subagent can report the path where its rollout, or saved thread record, is stored. This lets parent logic find the child session’s saved conversation trail.

Data flow: The test creates a parent session and a child session, attaches persistence to the child, and caches the child in the parent’s guardian review manager. It then asks the parent manager for the trunk rollout path. The returned value should be the child’s rollout path.

Call relations: The test runner calls this directly. It relies on attach_thread_persistence to give the child a saved-history location, then verifies the guardian-review manager exposes that location instead of hiding it inside the cached child.

Call graph: calls 2 internal fn (attach_thread_persistence, make_session_and_context); 6 external calls (new, assert_eq!, bounded, unbounded, spawn, channel).

async fn shutdown_and_wait_shuts_down_tracked_ephemeral_guardian_review()

Purpose: Checks that temporary guardian review sessions are shut down with their parent session. These ephemeral sessions are not cached long-term, but they still must not be left running.

Data flow: The test builds a parent session and a fake child review session. It registers the child as an ephemeral guardian review, shuts down the parent, and waits for a one-shot confirmation from the child. The child should receive an explicit shutdown operation.

Call relations: The async test runner calls this test. It uses make_session_and_context to create the parent and child, then verifies that Codex::shutdown_and_wait reaches sessions registered through the guardian-review tracking path.

Call graph: calls 1 internal fn (make_session_and_context); 8 external calls (clone, new, assert_eq!, bounded, unbounded, spawn, channel, channel).

async fn make_session_and_context_with_auth_and_config_and_rx(
    auth: CodexAuth,
    dynamic_tools: Vec<DynamicToolSpec>,
    configure_config: F,
) -> (
    Arc<Session>,
    Arc<TurnContext>,

Purpose: Builds a test session, its turn context, and an event receiver, while letting the caller choose authentication and adjust configuration. It is a convenience wrapper that creates a temporary Codex home directory automatically.

Data flow: The function receives test authentication, a list of dynamic tools, and a callback that edits the config. It creates a temporary directory and passes everything to the lower-level session builder. It returns an Arc-wrapped session, an Arc-wrapped turn context, and a channel receiver for emitted events.

Call relations: Several tests call this when they need a normal test session but with one or two config changes. It hands off the detailed setup to make_session_and_context_with_auth_config_home_and_rx so callers do not need to repeat boilerplate.

Call graph: calls 1 internal fn (make_session_and_context_with_auth_config_home_and_rx); called by 5 (build_initial_context_omits_multi_agent_v2_usage_hints_when_hint_disabled, make_multi_agent_v2_usage_hint_test_session, make_session_and_context_with_dynamic_tools_and_rx, resize_all_images_prepares_failures_before_history_insertion, resize_all_images_prepares_resumed_history_before_installing_it); 1 external calls (tempdir).

async fn make_session_and_context_with_auth_config_home_and_rx(
    auth: CodexAuth,
    dynamic_tools: Vec<DynamicToolSpec>,
    codex_home: &Path,
    configure_config: F,
) -> (
    Arc<Session>,

Purpose: Constructs a full in-memory test Session and TurnContext using a chosen Codex home folder. This is the main factory for tests that need realistic session objects without external network calls.

Data flow: The function takes authentication, dynamic tool descriptions, a home directory path, and a config-editing callback. It builds config, auth, model information, telemetry, environment objects, plugin and skill managers, session services, and event channels. It returns a ready-to-use session, turn context, and event receiver.

Call relations: Higher-level helpers call this to avoid duplicating a large setup sequence. The sessions it creates are then used by many tests to exercise real methods such as build_initial_context, build_settings_update_items, and record_context_updates_and_set_reference_context_item.

Call graph: calls 32 internal fn (new, new, new_uninitialized_with_permission_profile, new, new, new, new, default, new, new (+15 more)); called by 1 (make_session_and_context_with_auth_and_config_and_rx); 26 external calls (clone, new, new, new, default, new, from, new, from_pointee, from (+15 more)).

async fn make_session_and_context_with_dynamic_tools_and_rx(
    dynamic_tools: Vec<DynamicToolSpec>,
) -> (
    Arc<Session>,
    Arc<TurnContext>,
    async_channel::Receiver<Event>,
)

Purpose: Creates a standard test session with optional dynamic tools and a fake API key. It is useful when a test needs event output but does not need custom authentication or config.

Data flow: The function receives a list of dynamic tool specs. It supplies a test API key and an empty config callback to the more flexible session builder. It returns the session, turn context, and event receiver.

Call relations: Tests and the simpler make_session_and_context_with_rx helper call this. It delegates all real construction work to make_session_and_context_with_auth_and_config_and_rx.

Call graph: calls 2 internal fn (make_session_and_context_with_auth_and_config_and_rx, from_api_key); called by 4 (make_session_and_context_with_rx, assert_failed_apply_patch_tracks_committed_delta, invalidation_emits_empty_turn_diff, net_zero_patch_emits_empty_turn_diff).

async fn make_session_and_context_with_rx() -> (
    Arc<Session>,
    Arc<TurnContext>,
    async_channel::Receiver<Event>,
)

Purpose: Creates the most common kind of test session: no dynamic tools, default fake authentication, and an event receiver. It keeps individual tests short and focused on the behavior under test.

Data flow: The function takes no input. It calls the dynamic-tool helper with an empty list. The output is a standard session, turn context, and receiver for events emitted by the session.

Call relations: Many tests use this helper when they need to observe warnings or events. It is a thin wrapper around make_session_and_context_with_dynamic_tools_and_rx.

Call graph: calls 1 internal fn (make_session_and_context_with_dynamic_tools_and_rx); called by 68 (delegated_mcp_guardian_abort_returns_synthetic_decline_answer, delegated_mcp_user_reviewer_returns_none_without_metadata, forward_events_cancelled_while_send_blocked_shuts_down_delegate, forward_ops_preserves_submission_trace_context, handle_exec_approval_uses_call_id_for_guardian_review_and_approval_id_for_reply, handle_request_permissions_uses_tool_call_id_for_round_trip, run_codex_thread_interactive_respects_pre_cancelled_spawn, test_review_session, cancelled_guardian_review_emits_terminal_abort_without_warning, guardian_review_surfaces_responses_api_errors_in_rejection_reason (+15 more)); 1 external calls (new).

async fn refresh_mcp_servers_is_deferred_until_next_turn()

Purpose: Checks that MCP server refreshes are not applied immediately when requested, but are picked up at the next turn. MCP means Model Context Protocol, a way for external tools or servers to connect to the agent.

Data flow: The test creates a session and remembers the current cancellation token for MCP startup work. It stores a pending refresh config, confirms nothing changed yet, then calls the refresh method for the next turn. Afterward, the old token should be cancelled, the pending config cleared, and a fresh token installed.

Call relations: The test runner invokes this test. It uses make_session_and_context to set up a normal session and then directly exercises refresh_mcp_servers_if_requested, which is the method that consumes deferred refresh requests.

Call graph: calls 1 internal fn (make_session_and_context); 3 external calls (assert!, json!, to_value).

async fn spawn_task_does_not_update_previous_turn_settings_for_non_run_turn_tasks()

Purpose: Checks that background or non-run tasks do not accidentally overwrite the remembered settings from the previous user turn. This prevents unrelated tasks from confusing later context-difference logic.

Data flow: The test clears previous-turn settings, starts a never-ending regular task with simple user input, then aborts all tasks. It reads previous-turn settings afterward. The expected value is still None.

Call relations: The test runner calls this test. It uses make_session_and_context_with_rx for setup, then exercises Session::spawn_task and Session::abort_all_tasks to verify the previous-turn bookkeeping is left untouched.

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

async fn build_settings_update_items_emits_environment_item_for_network_changes()

Purpose: Checks that when network permission settings change, the session creates an environment-context update for the model. This helps the model understand which domains are allowed or denied.

Data flow: The test creates an old and new turn context, modifies the new config to allow one domain and deny another, then asks the session to build settings update items. It extracts user-visible text and looks for an environment block containing the network rules. The output should include the changed network context.

Call relations: The test runner invokes this test. It relies on build_settings_update_items to compare a previous context item with the current turn context and produce only the needed update.

Call graph: calls 4 internal fn (new, new, make_session_and_context, user_input_texts); 4 external calls (new, default, assert!, from).

async fn environment_context_uses_session_shell_when_environment_shell_is_absent()

Purpose: Checks the fallback rule for shell reporting in environment context. If an environment does not specify its own shell, the session shell should be shown; if it does, that environment shell should win.

Data flow: The test sets the session shell to PowerShell and removes shell values from all turn environments. It renders environment context and expects PowerShell. Then it sets the primary environment shell to Cmd, renders again, and expects Cmd.

Call relations: The test runner calls this directly. It uses EnvironmentContext::from_turn_context to verify how session-level and environment-level shell information are combined.

Call graph: calls 2 internal fn (from_turn_context, make_session_and_context); 3 external calls (new, from, assert!).

async fn build_settings_update_items_emits_environment_item_for_time_changes()

Purpose: Checks that changes to date and timezone are reported to the model as environment updates. This matters because the model may answer differently depending on the current date or local time zone.

Data flow: The test creates a previous context and a current context, then changes the current date and timezone. It asks the session for settings update items and searches the resulting text. The expected update includes both the new date and timezone.

Call relations: The test runner invokes this test. It exercises build_settings_update_items, which compares old and new context snapshots and emits a compact update when time-related environment data changed.

Call graph: calls 2 internal fn (make_session_and_context, user_input_texts); 2 external calls (new, assert!).

async fn build_settings_update_items_omits_environment_item_when_disabled()

Purpose: Checks that environment-context updates are not emitted when the configuration says to exclude environment context. This protects users or clients who intentionally turn that feature off.

Data flow: The test creates previous and current contexts, disables include_environment_context in the current config, and changes the current date. It builds update items and scans the user text. No environment-context block should appear.

Call relations: The test runner calls this test. It verifies build_settings_update_items respects the configuration flag even when there is a real environment change.

Call graph: calls 2 internal fn (make_session_and_context, user_input_texts); 2 external calls (new, assert!).

async fn build_settings_update_items_emits_realtime_start_when_session_becomes_live()

Purpose: Checks that the session tells the model when a realtime conversation becomes active. Realtime here means an ongoing live conversation mode rather than a normal single-turn exchange.

Data flow: The test starts with an inactive previous context, changes the current context to realtime active, and builds update items. It reads developer messages from those items. At least one should contain a realtime-conversation start marker.

Call relations: The test runner invokes this test. It exercises build_settings_update_items and the helper developer_input_texts to confirm the realtime start notice is produced.

Call graph: calls 2 internal fn (developer_input_texts, make_session_and_context); 2 external calls (new, assert!).

async fn build_settings_update_items_emits_realtime_end_when_session_stops_being_live()

Purpose: Checks that the session tells the model when realtime mode has ended. Without this, the model might keep assuming live-conversation rules still apply.

Data flow: The test marks the previous context as realtime active and the current context as inactive. It builds update items and scans developer text. The expected output includes an inactive reason.

Call relations: The test runner calls this directly. It validates build_settings_update_items behavior when realtime_active changes from true to false.

Call graph: calls 2 internal fn (developer_input_texts, make_session_and_context); 1 external calls (assert!).

async fn build_settings_update_items_uses_previous_turn_settings_for_realtime_end()

Purpose: Checks that realtime-end detection can use saved previous-turn settings when the previous context item does not contain realtime information. This keeps older or incomplete history records usable.

Data flow: The test removes realtime state from the previous context item, stores previous-turn settings saying realtime was active, and sets the current context to inactive. It builds update items and looks for the inactive message. The expected result is a realtime-end update based on the saved settings.

Call relations: The test runner invokes this test. It combines Session::set_previous_turn_settings with build_settings_update_items to verify the fallback path.

Call graph: calls 2 internal fn (developer_input_texts, make_session_and_context); 1 external calls (assert!).

async fn build_initial_context_uses_previous_realtime_state()

Purpose: Checks that initial context describes active realtime state once, but does not duplicate it when resuming from a matching reference context. This avoids repeating the same instruction to the model.

Data flow: The test first makes a realtime-active turn context and builds initial context, expecting a realtime marker. It then stores that context as the reference context and builds again. The resumed build should not include a duplicate realtime marker.

Call relations: The test runner calls this test. It exercises build_initial_context together with the session state’s reference context item, which acts as the baseline for what the model already knows.

Call graph: calls 2 internal fn (developer_input_texts, make_session_and_context); 1 external calls (assert!).

async fn make_multi_agent_v2_usage_hint_test_session(
    enable_multi_agent_v2: bool,
) -> (Arc<Session>, Arc<TurnContext>)

Purpose: Creates a test session configured with root-agent and subagent usage hints for the Multi-Agent V2 feature. It lets related tests switch the feature on or off without repeating setup.

Data flow: The function receives a boolean for enabling Multi-Agent V2. It builds a session with fake API authentication, sets both hint texts in the config, and optionally enables the feature flag. It returns the session and turn context.

Call relations: Multi-agent usage-hint tests call this helper. It delegates session creation to make_session_and_context_with_auth_and_config_and_rx and supplies the specific config needed for those tests.

Call graph: calls 2 internal fn (make_session_and_context_with_auth_and_config_and_rx, from_api_key); called by 3 (build_initial_context_adds_multi_agent_v2_root_usage_hint_as_developer_message, build_initial_context_adds_multi_agent_v2_subagent_usage_hint_as_developer_message, build_initial_context_omits_multi_agent_v2_usage_hints_when_feature_disabled); 1 external calls (new).

fn contribute(
        &'a self,
        _session_store: &'a codex_extension_api::ExtensionData,
        thread_store: &'a codex_extension_api::ExtensionData,
    ) -> std::pin::Pin<
        Box<dyn s

Purpose: Provides a fake prompt extension used by tests. It contributes a developer-policy prompt fragment only when test state exists in the thread extension store.

Data flow: The method receives session-level and thread-level extension data. It checks whether PromptExtensionTestState is present in the thread store. If present, it returns one developer prompt fragment; otherwise it returns an empty list.

Call relations: The test extension registry calls this contributor while building initial context. The prompt-extension tests use it to prove extension fragments are included only when the needed extension state has been inserted.

Call graph: 1 external calls (pin).

fn prompt_extension_test_registry() -> Arc<codex_extension_api::ExtensionRegistry<crate::config::Config>>

Purpose: Builds a tiny extension registry for tests, containing the fake prompt contributor. It gives tests a controlled way to simulate prompt extensions.

Data flow: The function creates a registry builder, registers PromptExtensionTestContributor, builds the registry, and wraps it in Arc for shared ownership. The output is a ready-to-install extension registry.

Call relations: The prompt-extension tests call this helper and assign the returned registry to session.services.extensions. During build_initial_context, the registry asks its contributor for prompt fragments.

Call graph: calls 1 internal fn (new); called by 2 (build_initial_context_includes_prompt_fragments_from_extensions, build_initial_context_omits_prompt_fragments_without_extension_state); 1 external calls (new).

async fn build_initial_context_includes_prompt_fragments_from_extensions()

Purpose: Checks that initial context includes prompt fragments supplied by an extension when that extension’s thread state is present. This proves extension hooks can add model instructions.

Data flow: The test installs the fake extension registry into a session and inserts the test state into thread extension data. It builds initial context and reads developer messages. The expected developer text is the fake extension’s prompt fragment.

Call relations: The test runner calls this test. It uses prompt_extension_test_registry, then verifies build_initial_context consults extension contributors.

Call graph: calls 3 internal fn (developer_message_texts, make_session_and_context, prompt_extension_test_registry); 1 external calls (assert!).

async fn build_initial_context_omits_prompt_fragments_without_extension_state()

Purpose: Checks that extension prompt text is not included when the extension has no enabling state. This prevents extensions from adding instructions accidentally.

Data flow: The test installs the fake registry but does not insert PromptExtensionTestState. It builds initial context and scans developer messages. The fake prompt text should be absent.

Call relations: The test runner invokes this test. It uses the same registry as the positive prompt-extension test but leaves the thread store empty to verify the opposite behavior.

Call graph: calls 3 internal fn (developer_message_texts, make_session_and_context, prompt_extension_test_registry); 1 external calls (assert!).

async fn build_initial_context_adds_multi_agent_v2_root_usage_hint_as_developer_message()

Purpose: Checks that a root thread gets the root usage hint when Multi-Agent V2 is enabled. This ensures the top-level agent receives the right guidance.

Data flow: The test creates a Multi-Agent V2 test session with the feature enabled, builds initial context, and reads developer messages. It expects a standalone root guidance message and no subagent guidance.

Call relations: The test runner calls this test. It relies on make_multi_agent_v2_usage_hint_test_session for setup and verifies build_initial_context chooses the root-agent hint.

Call graph: calls 2 internal fn (developer_message_texts, make_multi_agent_v2_usage_hint_test_session); 1 external calls (assert!).

async fn build_initial_context_adds_multi_agent_v2_subagent_usage_hint_as_developer_message()

Purpose: Checks that a subagent thread gets the subagent usage hint when Multi-Agent V2 is enabled. This keeps child agents from receiving instructions meant for the root agent.

Data flow: The test creates a Multi-Agent V2 session, changes the session source to a subagent thread, and mirrors that change in the turn context. It builds initial context and scans developer messages. It expects subagent guidance and rejects root guidance.

Call relations: The test runner invokes this test. It uses make_multi_agent_v2_usage_hint_test_session, then edits session state and turn context so build_initial_context sees the thread as a subagent.

Call graph: calls 4 internal fn (developer_message_texts, make_multi_agent_v2_usage_hint_test_session, try_from, new); 3 external calls (get_mut, SubAgent, assert!).

async fn build_initial_context_omits_multi_agent_v2_usage_hints_when_feature_disabled()

Purpose: Checks that Multi-Agent V2 usage hints are not added when the feature flag is off. Configured text alone should not activate the feature.

Data flow: The test creates a session with hint text but without enabling Multi-Agent V2. It builds initial context and reads developer messages. Neither the root nor subagent hint should appear.

Call relations: The test runner calls this test. It uses make_multi_agent_v2_usage_hint_test_session with the disabled setting to verify build_initial_context respects the feature flag.

Call graph: calls 2 internal fn (developer_message_texts, make_multi_agent_v2_usage_hint_test_session); 1 external calls (assert!).

async fn build_initial_context_omits_multi_agent_v2_usage_hints_when_hint_disabled()

Purpose: Checks that Multi-Agent V2 usage hints can be turned off even when the feature itself is enabled. This gives configuration a separate kill switch for the hint text.

Data flow: The test builds a session with Multi-Agent V2 enabled, usage hints disabled, and both hint strings set. It builds initial context and scans developer messages. Neither hint should be included.

Call relations: The test runner invokes this test. It uses make_session_and_context_with_auth_and_config_and_rx to create the exact configuration, then tests build_initial_context.

Call graph: calls 3 internal fn (developer_message_texts, make_session_and_context_with_auth_and_config_and_rx, from_api_key); 2 external calls (new, assert!).

async fn build_initial_context_omits_default_image_save_location_with_image_history()

Purpose: Checks that initial context does not include default image-save instructions even when the conversation history contains an image generation call. This avoids repeating unnecessary storage details.

Data flow: The test inserts an image-generation response item into session history. It then builds initial context and scans developer text. No message about generated images being saved to a default location should appear.

Call relations: The test runner calls this test. It uses replace_history to seed history and build_initial_context to verify what instructions are shown to the model.

Call graph: calls 2 internal fn (developer_input_texts, make_session_and_context); 2 external calls (assert!, vec!).

async fn build_initial_context_omits_default_image_save_location_without_image_history()

Purpose: Checks the same image-save instruction rule for an empty history. The initial context should not mention a default generated-image save location.

Data flow: The test creates a fresh session, builds initial context, and reads developer text. It expects no generated-image save-location instruction.

Call relations: The test runner invokes this test. It is the no-history companion to the image-history test and directly exercises build_initial_context.

Call graph: calls 2 internal fn (developer_input_texts, make_session_and_context); 1 external calls (assert!).

async fn build_initial_context_trims_skill_metadata_from_context_window_budget()

Purpose: Checks that skill metadata is trimmed when the model’s context window is very small. A context window is the amount of text the model can consider at once.

Data flow: The test gives the turn two skills and shrinks the model context window. It builds initial context and scans developer text. The output should contain neither the budget warning nor the skill entries, meaning the oversized skill list was removed from the model-visible context.

Call relations: The test runner calls this test. It sets TurnSkillsContext directly and relies on build_initial_context to apply the skill metadata budget.

Call graph: calls 3 internal fn (developer_input_texts, make_session_and_context, new); 4 external calls (new, assert!, default, vec!).

fn emit_thread_start_skill_metrics_records_enabled_kept_and_truncated_values()

Purpose: Checks that skill rendering records telemetry when the skill list is too large. Telemetry here means numeric runtime measurements used to understand behavior in aggregate.

Data flow: The test creates one skill, gives rendering a one-character budget, and asks build_available_skills to render it with thread-start side effects. It then reads the telemetry snapshot. Metrics should show one enabled skill, zero kept skills, one truncated skill, and four truncated description characters.

Call relations: The test runner calls this synchronous test. It exercises build_available_skills and verifies the telemetry side effects through test_session_telemetry_without_metadata.

Call graph: calls 1 internal fn (test_session_telemetry_without_metadata); 4 external calls (assert_eq!, default, Characters, vec!).

fn emit_thread_start_skill_metrics_records_description_truncated_chars_without_omitted_skills()

Purpose: Checks telemetry for a case where skill descriptions are shortened but no whole skills are omitted. This distinguishes partial trimming from dropping skills entirely.

Data flow: The test creates two skills and computes a budget large enough for their names and paths but not full descriptions. It renders the skills and inspects the report and telemetry. The result should show zero omitted skills and eight truncated description characters.

Call relations: The test runner invokes this test. It calls build_available_skills with thread-start telemetry side effects and verifies the metrics snapshot afterward.

Call graph: calls 1 internal fn (test_session_telemetry_without_metadata); 5 external calls (assert_eq!, default, Characters, test_path_buf, vec!).

async fn build_initial_context_emits_thread_start_skill_warning_on_repeated_builds()

Purpose: Checks that skill-budget warnings are emitted as events each time initial context is built, even on repeated builds. This ensures callers are warned whenever the oversized skill list affects a build.

Data flow: The test creates a session with an event receiver, installs two skills, and makes the context window tiny. It builds initial context, waits for a warning event, builds again, and waits for another warning. Both warnings should contain the same budget message.

Call relations: The test runner calls this async test. It uses make_session_and_context_with_rx so it can observe events emitted by build_initial_context.

Call graph: calls 2 internal fn (make_session_and_context_with_rx, new); 7 external calls (into_inner, new, from_secs, assert!, default, timeout, vec!).

async fn handle_output_item_done_records_image_save_history_message()

Purpose: Checks that a completed image-generation output saves the image file and records an explanatory history message before the image item. This tells future turns where generated images are stored.

Data flow: The test creates an image-generation response item with base64 content for “foo”, builds a handle-output context, and passes the item to handle_output_item_done. It then reads session history and the saved file. The expected history contains an image instructions message followed by the original item, and the file contains the decoded bytes.

Call relations: The test runner invokes this test. It uses test_tool_runtime and handle_output_item_done to exercise the same output-processing path used after model responses.

Call graph: calls 6 internal fn (into, new, make_session_and_context, test_tool_runtime, image_generation_artifact_path, new); 6 external calls (clone, new, new, assert_eq!, remove_file, vec!).

async fn handle_output_item_done_skips_image_save_message_when_save_fails()

Purpose: Checks that a bad image payload does not add a misleading save-location message to history. The output item itself should still be recorded.

Data flow: The test creates an image-generation item with invalid encoded data and processes it through handle_output_item_done. It reads history and checks the expected file path. The history should contain only the image item, and no file should exist.

Call relations: The test runner calls this test. It covers the failure branch of the same image-output processing path tested by the successful save case.

Call graph: calls 4 internal fn (make_session_and_context, test_tool_runtime, image_generation_artifact_path, new); 7 external calls (clone, new, new, assert!, assert_eq!, remove_file, vec!).

async fn build_initial_context_uses_previous_turn_settings_for_realtime_end()

Purpose: Checks that initial context can announce a realtime session ended based on saved previous-turn settings. This helps when there is no full reference context item to compare against.

Data flow: The test stores previous-turn settings saying realtime was active, then builds initial context for a currently inactive turn. It scans developer text. The expected text explains that realtime is inactive.

Call relations: The test runner invokes this test. It uses set_previous_turn_settings and build_initial_context to verify the fallback realtime-end path.

Call graph: calls 2 internal fn (developer_input_texts, make_session_and_context); 1 external calls (assert!).

async fn build_initial_context_restates_realtime_start_when_reference_context_is_missing()

Purpose: Checks that active realtime state is restated when there is no saved reference context, even if previous-turn settings also say realtime was active. Without a baseline, the model must be told the current state.

Data flow: The test marks the current turn as realtime active and stores previous-turn settings with realtime active too. It builds initial context and scans developer text. The output should include the realtime-conversation marker.

Call relations: The test runner calls this test. It exercises build_initial_context in the missing-reference-context case.

Call graph: calls 2 internal fn (developer_input_texts, make_session_and_context); 1 external calls (assert!).

fn file_system_policy_with_unreadable_glob(turn_context: &TurnContext) -> FileSystemSandboxPolicy

Purpose: Creates a test file-system sandbox policy that denies access to .env files under the current working directory. A sandbox policy is a set of rules saying which files the agent may read or write.

Data flow: The function receives a turn context, converts its legacy sandbox policy into the newer split file-system policy format, and appends a deny rule for a glob pattern matching .env files. It returns the modified policy.

Call relations: Tests that need a file-system policy different from the legacy equivalent call this helper. They use it to verify that special policies are stored in turn context items and persisted to rollout history.

Call graph: calls 2 internal fn (sandbox_policy, from_legacy_sandbox_policy_for_cwd); called by 2 (record_context_updates_and_set_reference_context_item_persists_split_file_system_policy_to_rollout, turn_context_item_stores_split_file_system_sandbox_policy_when_different); 1 external calls (format!).

async fn turn_context_item_uses_turn_context_comp_hash_snapshot()

Purpose: Checks that a turn context item uses the turn context’s own component hash snapshot, not a possibly different hash inside model information. This preserves the exact settings snapshot for the turn.

Data flow: The test sets one hash on the turn context and another on the model info. It converts the turn context into a stored context item. The stored hash should be the turn-context hash.

Call relations: The test runner invokes this test. It directly exercises TurnContext::to_turn_context_item.

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

async fn turn_context_item_omits_legacy_equivalent_file_system_sandbox_policy()

Purpose: Checks that the saved turn context does not redundantly store a file-system sandbox policy when it matches the legacy permission profile. This keeps stored context smaller and avoids duplicate information.

Data flow: The test creates a normal turn context and converts it into a context item. It expects the separate file-system sandbox policy field to be None, while the permission profile is still present.

Call relations: The test runner calls this test. It validates the default output of TurnContext::to_turn_context_item.

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

async fn turn_context_item_stores_split_file_system_sandbox_policy_when_different()

Purpose: Checks that a custom split file-system sandbox policy is stored when it differs from the legacy-equivalent policy. This preserves important extra access rules such as denied .env files.

Data flow: The test creates a custom policy with file_system_policy_with_unreadable_glob and updates the turn context permission profile with it. It converts the context to an item. The item should include the custom file-system policy and the permission profile.

Call relations: The test runner invokes this test. It uses the policy helper and then exercises TurnContext::to_turn_context_item.

Call graph: calls 3 internal fn (file_system_policy_with_unreadable_glob, make_session_and_context, from_runtime_permissions_with_enforcement); 1 external calls (assert_eq!).

async fn record_context_updates_and_set_reference_context_item_injects_full_context_when_baseline_missing()

Purpose: Checks that when there is no previous context baseline, the session records the full initial context into history. This ensures resumed conversations have the model instructions they need.

Data flow: The test calls record_context_updates_and_set_reference_context_item on a fresh session. It then compares session history with build_initial_context output and reads the saved reference context item. History should contain the full initial context, and the reference item should match the current turn context.

Call relations: The test runner calls this test. It exercises the session method that both writes context updates to history and updates the baseline used for future diffs.

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

async fn record_context_updates_and_set_reference_context_item_reinjects_full_context_after_clear()

Purpose: Checks that if the saved reference context is cleared, the session reinserts full context on the next update. This is important after history compaction or repair, when the baseline may be missing.

Data flow: The test records a compacted-summary message, records context once, clears the reference context, replaces history with only the summary, and records context again. It then expects history to contain the summary followed by the full initial context.

Call relations: The test runner invokes this test. It combines record_conversation_items, replace_history, and record_context_updates_and_set_reference_context_item to simulate a cleared baseline.

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

async fn record_context_updates_and_set_reference_context_item_persists_baseline_without_emitting_diffs()

Purpose: Checks that when a context change should be saved as the new baseline but not emitted as visible diff messages, the baseline is still persisted to rollout history. This protects resume behavior even when no conversation items are added.

Data flow: The test creates a previous context, switches to another model, stores the previous context as the reference, and attaches rollout persistence. It confirms update items are empty, records context updates, flushes the rollout, and reads saved rollout history. The persisted turn context should match the new turn context even though session history stayed empty.

Call relations: The test runner calls this test. It uses attach_thread_persistence and RolloutRecorder::get_rollout_history to verify the save-to-disk side of record_context_updates_and_set_reference_context_item.

Call graph: calls 3 internal fn (attach_thread_persistence, make_session_and_context, get_rollout_history); 2 external calls (assert_eq!, panic!).

async fn record_context_updates_and_set_reference_context_item_persists_split_file_system_policy_to_rollout()

Purpose: Checks that a custom split file-system sandbox policy is written into rollout history. Without this, a resumed session could lose important file access restrictions.

Data flow: The test creates a custom deny-.env policy, installs it into the turn context permission profile, attaches rollout persistence, records context updates, and flushes the rollout. It reads the saved rollout history and extracts the stored file-system policy. The stored policy should equal the custom policy.

Call relations: The test runner invokes this test. It uses file_system_policy_with_unreadable_glob, attach_thread_persistence, and RolloutRecorder::get_rollout_history to check persistence.

Call graph: calls 5 internal fn (attach_thread_persistence, file_system_policy_with_unreadable_glob, make_session_and_context, from_runtime_permissions_with_enforcement, get_rollout_history); 2 external calls (assert_eq!, panic!).

async fn build_initial_context_prepends_model_switch_message()

Purpose: Checks that initial context starts with a developer message when the model changed since the previous turn. This gives the new model an explicit note that it is taking over from another model.

Data flow: The test stores previous-turn settings with a different model name, builds initial context, and inspects the first response item. The first item should be a developer message containing a model-switch marker.

Call relations: The test runner calls this test. It uses set_previous_turn_settings and build_initial_context to verify model-switch messaging is placed at the front.

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

async fn record_context_updates_and_set_reference_context_item_persists_full_reinjection_to_rollout()

Purpose: Checks that when the session notices a changed turn context, it saves the full reinjected context into the rollout record. This matters because a resumed conversation needs the same context that was active during the original run.

Data flow: It creates a session and an earlier context, switches to a different model for the next context, attaches rollout persistence, and seeds the rollout with a user message. It clears the reference context, records the new context update, flushes the rollout file, then reads the file back. The expected result is that the persisted rollout contains a turn-context item matching the new turn context.

Call relations: The test builds its session with make_session_and_context, attaches storage with attach_thread_persistence, then exercises the session method that records context updates. It uses RolloutRecorder::get_rollout_history afterward to prove the saved file contains the same context item that the live session produced.

Call graph: calls 3 internal fn (attach_thread_persistence, make_session_and_context, get_rollout_history); 6 external calls (default, new, assert_eq!, panic!, UserMessage, EventMsg).

async fn run_user_shell_command_does_not_set_reference_context_item()

Purpose: Verifies that a standalone user shell command does not change the conversation’s remembered previous context. This prevents one-off shell tasks from accidentally affecting the next model turn.

Data flow: It starts a session with an event receiver, clears the reference context, runs a user shell command, and waits until the session reports the turn is complete. After that, it reads the session’s reference context. The expected result is still no reference context.

Call relations: The test calls handlers::run_user_shell_command as a client-facing command handler would. It watches events from the receiver until TurnComplete, then checks the session state directly to confirm the shell path did not use the same context-update path as normal turns.

Call graph: calls 2 internal fn (run_user_shell_command, make_session_and_context_with_rx); 5 external calls (from_secs, assert!, matches!, now, timeout).

async fn realtime_conversation_list_voices_emits_builtin_list()

Purpose: Checks that asking for realtime conversation voices returns the built-in voice list. This makes sure clients can reliably populate voice choices without needing an external lookup.

Data flow: It creates a session and event receiver, calls the voice-list handler, receives one event, and extracts the voice list from it. The output must exactly match the expected v1 voices, v2 voices, and defaults.

Call relations: The test exercises handlers::realtime_conversation_list_voices and then reads the event channel that clients would normally receive. It proves the handler sends a RealtimeConversationListVoicesResponse event with the hard-coded supported voices.

Call graph: calls 2 internal fn (realtime_conversation_list_voices, make_session_and_context_with_rx); 2 external calls (assert_eq!, panic!).

fn kind(&self) -> TaskKind

Purpose: Reports that this fake task is a regular session task. It is used by tests that need a task which behaves like a normal turn and completes quickly.

Data flow: It reads no external input and always returns TaskKind::Regular. Nothing else changes.

Call relations: Session task spawning code calls this method to classify the task. In these tests, CompletingTask is used when the session needs to run through normal completion behavior.

fn span_name(&self) -> &'static str

Purpose: Gives this fake task a tracing name for diagnostics. The name helps identify the task in logs or tracing output during tests.

Data flow: It takes the task object and returns the fixed text "session_task.completing". It does not change state.

Call relations: The session task runner can ask for this name when creating a trace span, which is a labeled timing/logging section.

async fn run(
        self: Arc<Self>,
        _session: Arc<SessionTaskContext>,
        _ctx: Arc<TurnContext>,
        _input: Vec<TurnInput>,
        _cancellation_token: CancellationToken,
    )

Purpose: Simulates a task that finishes immediately without producing a final assistant message. This lets tests check what the session does when a turn completes cleanly.

Data flow: It receives the session context, turn context, input, and cancellation token, but ignores them. It returns None, meaning there is no last agent message.

Call relations: The session task runner calls this after spawn_task. Tests use it to trigger normal task-finished cleanup without waiting for real model work.

fn kind(&self) -> TaskKind

Purpose: Reports which kind of fake task this is, such as regular or review. Tests use this to simulate different turn categories.

Data flow: It reads the task’s stored kind field and returns it. It does not alter anything.

Call relations: The session task runner calls this when deciding how the active turn should behave. Tests vary the stored kind to check rules for regular, review, and compact turns.

fn span_name(&self) -> &'static str

Purpose: Gives the never-ending fake task a tracing name. This keeps test traces readable if task activity is inspected.

Data flow: It returns the fixed text "session_task.never_ending". It does not read or change session state.

Call relations: The session task runner may use this when labeling the task’s async execution span.

async fn run(
        self: Arc<Self>,
        _session: Arc<SessionTaskContext>,
        _ctx: Arc<TurnContext>,
        _input: Vec<TurnInput>,
        cancellation_token: CancellationToken,
    ) -

Purpose: Simulates a task that keeps a turn open until cancelled, or ignores cancellation forever depending on its setting. This is useful for testing aborts, pending input, and active-turn rejection.

Data flow: It receives a cancellation token. If configured to listen, it waits until cancellation and then returns None. If configured not to listen, it sleeps forever in a loop, imitating a stuck task.

Call relations: Many tests spawn this task to keep the session busy. Abort and steering tests then observe how session code behaves while a turn is active or when the task is cancelled.

Call graph: 3 external calls (cancelled, from_secs, sleep).

fn kind(&self) -> TaskKind

Purpose: Reports that this fake guardian-denial task is a regular task. It lets guardian interruption tests run through the normal turn path.

Data flow: It always returns TaskKind::Regular and changes nothing.

Call relations: The session runner calls this when the task is spawned. The regular classification means the guardian circuit-breaker behavior is tested in a normal turn.

fn span_name(&self) -> &'static str

Purpose: Provides a trace label for the fake task that triggers guardian denials. This helps distinguish it from other test tasks.

Data flow: It returns the fixed text "session_task.guardian_denied_approval". It does not change state.

Call relations: The session runner can use this name when recording task execution in tracing.

async fn run(
        self: Arc<Self>,
        session: Arc<SessionTaskContext>,
        ctx: Arc<TurnContext>,
        _input: Vec<TurnInput>,
        cancellation_token: CancellationToken,
    ) ->

Purpose: Simulates a turn that records three guardian denials and then waits to be cancelled. It tests the safety circuit breaker that should interrupt a turn after repeated denials.

Data flow: It clones the session, records three guardian denial events for the turn, then waits on the cancellation token. It returns None after cancellation.

Call relations: guardian_auto_review_interrupts_after_three_consecutive_denials spawns this task. The task hands off to crate::guardian::record_guardian_denial_for_test, and the session should respond by aborting the turn.

Call graph: 2 external calls (cancelled, record_guardian_denial_for_test).

async fn guardian_auto_review_interrupts_after_three_consecutive_denials()

Purpose: Checks that three consecutive guardian denials during a normal turn interrupt that turn. This protects the system from continuing after repeated safety rejections.

Data flow: It starts a session, creates user input, spawns GuardianDeniedApprovalTask, and then reads events until it sees TurnAborted. The expected abort reason is Interrupted.

Call relations: The test relies on GuardianDeniedApprovalTask to create the denial sequence. It observes the client event stream to confirm the guardian circuit breaker reaches the session abort path.

Call graph: calls 1 internal fn (make_session_and_context_with_rx); 7 external calls (clone, new, assert_eq!, TurnAborted, from_secs, timeout, vec!).

async fn guardian_helper_review_interrupts_after_three_consecutive_denials()

Purpose: Checks that guardian denials coming from a helper review thread also interrupt the active turn. This matters because reviews can happen outside the main task flow.

Data flow: It starts a never-ending regular turn, then starts a separate thread with its own async runtime and records three guardian denials for the same turn. It watches session events until TurnAborted appears, and expects the reason to be Interrupted.

Call relations: The active turn is kept alive by NeverEndingTask. The helper thread calls crate::guardian::record_guardian_denial_for_test, and the session is expected to emit the same abort event as it would for denials recorded by the task itself.

Call graph: calls 1 internal fn (make_session_and_context_with_rx); 8 external calls (clone, from_secs, new, assert_eq!, TurnAborted, spawn, timeout, vec!).

async fn abort_regular_task_emits_marker_before_turn_aborted()

Purpose: Verifies that aborting a regular stuck task sends a model-visible abort marker before the client-facing TurnAborted event. The marker is important because future model context should know the previous turn was interrupted.

Data flow: It starts a regular never-ending task that ignores cancellation, aborts all tasks, then reads two events. The first must be a raw response item containing the marker, and the second must be TurnAborted with the Interrupted reason. It also checks no extra events remain.

Call relations: The test drives sess.abort_all_tasks directly while NeverEndingTask keeps the turn active. It confirms the session’s abort flow orders history/model marker output before the final client abort notification.

Call graph: calls 1 internal fn (make_session_and_context_with_rx); 7 external calls (clone, assert!, assert_eq!, panic!, from_secs, timeout, vec!).

async fn abort_gracefully_emits_marker_before_turn_aborted()

Purpose: Checks that even a task which cooperates with cancellation still emits the abort marker before TurnAborted. This keeps abort behavior consistent for both stuck and graceful tasks.

Data flow: It starts a regular never-ending task that listens for cancellation, aborts all tasks, and reads the event stream. It expects a RawResponseItem marker first, then TurnAborted with reason Interrupted, and no later events.

Call relations: This is the graceful-cancellation counterpart to abort_regular_task_emits_marker_before_turn_aborted. It uses NeverEndingTask with cancellation listening enabled to exercise the cleaner shutdown path.

Call graph: calls 1 internal fn (make_session_and_context_with_rx); 7 external calls (clone, assert!, assert_eq!, panic!, from_secs, timeout, vec!).

async fn task_finish_emits_turn_item_lifecycle_for_leftover_pending_user_input()

Purpose: Checks that if follow-up user input is still pending when a task finishes, the session records it and emits the full item lifecycle for clients. This prevents late user input from disappearing at turn completion.

Data flow: It starts a never-ending turn, clears earlier events, steers new user input into the active turn, then manually finishes the task. It checks history for the pending user message, then verifies events arrive as raw response item, item started, item completed, legacy user message, and turn complete.

Call relations: The test uses sess.steer_input to add pending input and sess.on_task_finished to trigger completion cleanup. It observes both stored history and outgoing events to prove the pending input is handled like a real user message.

Call graph: calls 2 internal fn (new, make_session_and_context_with_rx); 6 external calls (clone, default, assert!, from_secs, timeout, vec!).

async fn task_finish_emits_thread_idle_lifecycle_after_active_turn_clears()

Purpose: Verifies that thread-idle extension hooks run after the active turn has been cleared. This lets extensions safely react to a truly idle thread.

Data flow: It defines a test extension contributor that records calls and sends a signal when idle. It installs that contributor, spawns a CompletingTask, waits for the idle signal, and then checks the hook ran once and active_turn is None.

Call relations: CompletingTask causes the turn to finish quickly. The session’s completion path calls the extension registry’s thread idle lifecycle, and the test contributor confirms the correct thread ID and timing.

Call graph: calls 1 internal fn (make_session_and_context); 10 external calls (clone, new, from_secs, new, assert!, assert_eq!, bounded, new, new, timeout).

async fn thread_idle_lifecycle_waits_for_trigger_turn_mailbox_work()

Purpose: Checks that the thread-idle hook does not run while there is mailbox work that should trigger another turn. This avoids telling extensions the thread is idle too early.

Data flow: It installs a test idle contributor, enqueues a mailbox communication marked as trigger_turn, calls the session’s idle-check method, and reads the call count. The expected count is zero.

Call relations: The test uses the input queue to simulate pending inter-agent mail. When emit_thread_idle_lifecycle_if_idle runs, it should notice that trigger-turn work exists and skip the extension hook.

Call graph: calls 3 internal fn (make_session_and_context, root, new); 6 external calls (clone, new, new, assert_eq!, new, new).

async fn try_start_turn_if_idle_rejects_active_turn_without_injecting()

Purpose: Ensures automatic idle-start input is rejected while a turn is already active, and that the rejected input is not secretly queued. This prevents duplicate or misplaced turns.

Data flow: It starts a never-ending regular turn, creates a synthetic user message, and calls try_start_turn_if_idle. The function returns a Busy rejection containing the original input, and the input queue remains empty for the active turn.

Call relations: NeverEndingTask keeps the session busy. The test exercises sess.try_start_turn_if_idle and then checks both the rejection object and the queue to confirm no side effect occurred.

Call graph: calls 2 internal fn (make_session_and_context_with_rx, user_message); 4 external calls (clone, new, assert_eq!, vec!).

async fn try_start_turn_if_idle_rejects_plan_mode_without_injecting()

Purpose: Checks that automatic idle-start input is rejected in plan mode. Plan mode is a state where the system should not silently start work from this path.

Data flow: It changes the session collaboration mode to Plan, then calls try_start_turn_if_idle with a synthetic user message. The rejection reason is PlanMode, the input is returned untouched, no active turn appears, and nothing is queued.

Call relations: The test edits session configuration directly, then exercises sess.try_start_turn_if_idle. It proves the plan-mode guard runs before any input injection.

Call graph: calls 2 internal fn (make_session_and_context_with_rx, user_message); 3 external calls (assert!, assert_eq!, vec!).

async fn try_start_turn_if_idle_rejects_pending_trigger_turn_without_injecting()

Purpose: Ensures automatic idle-start input is rejected when trigger-turn mailbox mail is already waiting. This protects mailbox-triggered work from being bypassed or reordered.

Data flow: It enqueues trigger-turn inter-agent communication, then tries to start a turn with synthetic input. The result is a PendingTriggerTurn rejection, the original input is returned, no active turn starts, and the trigger mail remains waiting.

Call relations: The input queue supplies the pending trigger condition. sess.try_start_turn_if_idle is expected to notice that condition and leave the queue unchanged.

Call graph: calls 4 internal fn (make_session_and_context_with_rx, user_message, root, new); 4 external calls (new, assert!, assert_eq!, vec!).

async fn try_start_turn_if_idle_rejects_active_review_turn_without_injecting()

Purpose: Checks that idle-start input is rejected while a review turn is active. Review turns are special, so unrelated automatic input must not be injected into them.

Data flow: It starts a never-ending task marked as Review, calls try_start_turn_if_idle with synthetic input, and expects a Busy rejection. The input is returned unchanged and no pending input is added to the active turn.

Call relations: NeverEndingTask supplies an active review turn. The test confirms sess.try_start_turn_if_idle treats it as busy and does not use the steering or queueing path.

Call graph: calls 2 internal fn (make_session_and_context_with_rx, user_message); 4 external calls (clone, new, assert_eq!, vec!).

async fn steer_input_requires_active_turn()

Purpose: Checks that steering input fails when there is no active turn. Steering only makes sense when there is already a running turn to steer.

Data flow: It creates a session with no active task, prepares user text, and calls steer_input. The result is a NoActiveTurn error.

Call relations: The test directly exercises sess.steer_input before any spawn_task call. It confirms the session rejects the operation at the first safety check.

Call graph: calls 1 internal fn (make_session_and_context_with_rx); 3 external calls (default, assert!, vec!).

async fn steer_input_enforces_expected_turn_id()

Purpose: Verifies that steering input can require a specific active turn ID, and fails if the active turn is different. This prevents a client’s follow-up text from going into the wrong turn.

Data flow: It starts a regular never-ending turn, then calls steer_input with an expected turn ID that does not match. The returned error contains both the expected ID and the actual active turn ID.

Call relations: NeverEndingTask creates the active turn. sess.steer_input compares the caller’s expected ID to the active turn context and returns ExpectedTurnMismatch instead of queueing the input.

Call graph: calls 1 internal fn (make_session_and_context_with_rx); 5 external calls (clone, default, assert_eq!, panic!, vec!).

async fn steer_input_rejects_non_regular_turns()

Purpose: Checks that steering is rejected for review and compact turns. Those turn types have special meaning, so ordinary user follow-up input should not be mixed into them.

Data flow: For each non-regular task kind, it starts a turn, tries to steer user text, and expects ActiveTurnNotSteerable with the matching turn kind. It then aborts the task to clean up.

Call relations: The test creates review and compact active turns using NeverEndingTask. It exercises sess.steer_input and confirms the turn-kind guard blocks both cases.

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

async fn steer_input_returns_active_turn_id()

Purpose: Verifies that successful steering returns the ID of the turn that received the input. This gives callers confirmation that their follow-up went to the intended running turn.

Data flow: It starts a regular never-ending turn, steers user text with the matching expected turn ID, and receives a turn ID back. It checks the returned ID matches and that the input queue now has pending input.

Call relations: The active regular turn comes from NeverEndingTask. sess.steer_input accepts the input, appends it to the active turn’s pending queue, and returns the active turn’s sub_id.

Call graph: calls 1 internal fn (make_session_and_context_with_rx); 5 external calls (clone, default, assert!, assert_eq!, vec!).

async fn abort_empty_active_turn_preserves_pending_input()

Purpose: Checks that aborting an empty active turn does not discard pending input attached to that turn state. This protects input that should be available after cleanup.

Data flow: It manually creates an active turn state, adds a pending response item to that state, aborts all tasks with Replaced, and then confirms the active turn is cleared. It then takes pending input for the saved turn state and expects to get the original item back.

Call relations: This test touches the input queue and active_turn state directly to cover a narrow cleanup case. sess.abort_all_tasks clears the active turn but must not erase the turn-state-specific pending input.

Call graph: calls 1 internal fn (make_session_and_context_with_rx); 4 external calls (clone, assert!, assert_eq!, vec!).

async fn set_total_token_usage(sess: &Session, total_token_usage: TokenUsage)

Purpose: Sets test token-usage information on a session. It is a helper for tests that need the session to begin with a known token count.

Data flow: It locks the session state and stores TokenUsageInfo with the supplied total usage, default last usage, and no model context window. It returns nothing but changes session state.

Call relations: turn_start_lifecycle_exposes_turn_metadata_and_token_baseline calls this helper before checking lifecycle metadata. It prepares the session state so that later lifecycle code can read a known baseline.

Call graph: called by 1 (turn_start_lifecycle_exposes_turn_metadata_and_token_baseline); 1 external calls (default).

async fn queue_only_mailbox_mail_waits_for_next_turn_after_answer_boundary()

Purpose: Checks that non-trigger mailbox mail arriving after the current turn’s answer boundary waits for the next turn. This prevents late child-agent updates from being folded into a turn that has already effectively answered.

Data flow: It starts a regular turn, marks mailbox delivery as deferred to the next turn, then enqueues queue-only inter-agent communication. During the active turn, pending input is empty. After aborting/replacing the turn, the queued communication appears as pending input for the next turn.

Call relations: The test uses input_queue.defer_mailbox_delivery_to_next_turn to simulate the answer boundary. It verifies enqueue_mailbox_communication respects that boundary until abort_all_tasks clears the current turn.

Call graph: calls 4 internal fn (make_session_and_context_with_rx, root, try_from, new); 4 external calls (clone, new, assert!, assert_eq!).

async fn trigger_turn_mailbox_mail_waits_for_next_turn_after_answer_boundary()

Purpose: Checks that trigger-turn mailbox mail also waits after the current turn’s answer boundary. It should remain available to start a later turn, not extend the current one.

Data flow: It starts a regular active turn, defers mailbox delivery to the next turn, then enqueues trigger-turn communication. The active turn has no pending input. After the turn is replaced, the input queue still reports trigger-turn mailbox items waiting.

Call relations: Like the queue-only mailbox test, this uses NeverEndingTask and the input queue’s defer mechanism. The difference is that the mailbox item is marked trigger_turn, so the test checks the trigger mailbox state after abort.

Call graph: calls 4 internal fn (make_session_and_context_with_rx, root, try_from, new); 3 external calls (clone, new, assert!).

async fn steered_input_reopens_mailbox_delivery_for_current_turn()

Purpose: Verifies that when the user steers an active turn after the answer boundary, queued mailbox delivery can reopen for that current turn. This lets a follow-up bring in related child-agent updates.

Data flow: It starts a turn, defers mailbox delivery, enqueues a queued child update, then steers new user input into the same turn. The pending input for the active turn becomes the steered user input followed by the mailbox communication.

Call relations: sess.steer_input is the key action that reopens delivery. The test checks input_queue.get_pending_input to prove the previously buffered mailbox item is now attached to the active turn.

Call graph: calls 4 internal fn (make_session_and_context_with_rx, root, try_from, new); 5 external calls (clone, default, new, assert_eq!, vec!).

async fn stale_defer_mailbox_delivery_does_not_override_steered_input()

Purpose: Checks that an old or repeated defer call does not undo mailbox delivery after steering has reopened it. This prevents stale bookkeeping from hiding input that is already pending.

Data flow: It starts a turn, defers mailbox delivery, enqueues communication, steers user input so delivery reopens, then calls defer again for the same turn. The pending input remains the user input plus the mailbox communication.

Call relations: The test combines input_queue.defer_mailbox_delivery_to_next_turn and sess.steer_input in a race-like order. It confirms the queue treats the later stale defer as harmless once current-turn delivery has reopened.

Call graph: calls 4 internal fn (make_session_and_context_with_rx, root, try_from, new); 5 external calls (clone, default, new, assert_eq!, vec!).

async fn tool_calls_reopen_mailbox_delivery_for_current_turn()

Purpose: Checks that a tool call can also reopen mailbox delivery for the current turn. This matters because tool activity can mean the turn is still active and should receive queued child-agent updates.

Data flow: It starts a turn, defers mailbox delivery, enqueues communication, then simulates a function-call response item for a test tool. handle_output_item_done processes the tool call and reports that follow-up is needed. The queued mailbox communication becomes pending input for the active turn.

Call relations: The test builds a HandleOutputCtx with a test tool runtime and calls handle_output_item_done, the normal output-processing path for model tool calls. It then checks the input queue to confirm tool handling reopened delivery.

Call graph: calls 6 internal fn (make_session_and_context_with_rx, test_tool_runtime, new, root, try_from, new); 6 external calls (clone, new, new, new, assert!, assert_eq!).

async fn abort_review_task_emits_exited_then_aborted_and_records_history()

Purpose: Verifies that aborting a review task exits review mode before reporting the turn as aborted, and still records a turn-aborted marker in history. This preserves both correct client state and model memory.

Data flow: It starts a ReviewTask, aborts all tasks, then reads events until it sees ExitedReviewMode and TurnAborted. It checks that ExitedReviewMode came first and that the abort reason is Interrupted. Finally it scans history for a user message containing the turn-aborted marker.

Call relations: The test uses ReviewTask::new to enter review-mode behavior, then drives sess.abort_all_tasks. It observes client events and session history to prove both the review lifecycle and abort-history paths ran.

Call graph: calls 2 internal fn (make_session_and_context_with_rx, new); 7 external calls (clone, assert!, assert_eq!, from_secs, now, timeout, vec!).

async fn fatal_tool_error_stops_turn_and_reports_error()

Purpose: Checks that an incompatible shell tool payload becomes a fatal tool error. A fatal error means the turn should stop rather than pretending the tool returned normal output.

Data flow: It loads available tools, builds a ToolRouter, creates a custom tool call named shell_command with the wrong payload shape, builds a tool call, and dispatches it. The result must be FunctionCallError::Fatal with the expected message.

Call relations: The test exercises ToolRouter::build_tool_call and dispatch_tool_call_with_code_mode_result. It confirms the router and tool dispatch layer reject incompatible tool input in the fatal-error path.

Call graph: calls 4 internal fn (make_session_and_context_with_rx, build_tool_call, from_turn_context, new); 8 external calls (clone, new, new, default, new, assert_eq!, panic!, new).

async fn sample_rollout(
    session: &Session,
    _turn_context: &TurnContext,
) -> (Vec<RolloutItem>, Vec<ResponseItem>)

Purpose: Builds a sample rollout and the matching live conversation history for reconstruction tests. It gives those tests a realistic sequence with initial context, user and assistant messages, and compaction summaries.

Data flow: It creates initial context from a new default turn, adds personality instructions if needed, records those items into rollout_items and live_history, then adds several user/assistant exchanges. Twice it compacts the history by replacing older content with a summary. It returns both the rollout items and the final prompt-ready history.

Call relations: Several rollout reconstruction tests call this helper to get a known transcript. It uses the same session context-building and compaction code as production paths, so reconstruction tests compare against a realistic expected history rather than a hand-written shortcut.

Call graph: calls 4 internal fn (into, build_compacted_history, new, new); called by 5 (reconstruct_history_matches_live_compactions, record_initial_history_reconstructs_forked_transcript, record_initial_history_reconstructs_resumed_transcript, record_initial_history_seeds_token_info_from_rollout, resumed_history_injects_initial_context_on_first_context_update_only); 7 external calls (new, build_initial_context, new_default_turn, Compacted, ResponseItem, once, vec!).

async fn rejects_escalated_permissions_when_policy_not_on_request()

Purpose: Checks that the classic shell command tool rejects requests for escalated permissions unless the approval policy is OnRequest. This is a security rule: the model should not ask for extra power when the configured policy does not allow that request flow.

Data flow: It creates a session, changes the approval policy to OnFailure, and invokes shell_command with sandbox_permissions set to RequireEscalated. The tool returns an error message for the model, no turn permissions are granted, and a later non-escalated approval check for the same command still skips approval as expected.

Call relations: The test calls ShellCommandHandler::handle with a ToolInvocation, then consults the session’s granted permissions and exec policy. It proves the rejection is specific to escalated-permission requests and does not poison ordinary command handling.

Call graph: calls 4 internal fn (make_session_and_context, from, new, plain); 10 external calls (clone, get_mut, new, new, assert!, format!, panic!, assert_eq!, json!, new).

async fn shell_tool_cancellation_waits_for_runtime_cleanup() -> anyhow::Result<()>

Purpose: Verifies that cancelling a shell tool waits for the shell process to run its cleanup trap before the tool task finishes. This prevents leaked or half-cleaned command processes.

Data flow: It creates a session with unrestricted sandbox policy, writes a shell command that creates a ready file, waits forever, and on TERM writes a cleanup file. It starts the tool call, waits for the ready file, cancels the token, waits for the tool task to finish, and then reads the cleanup file. The expected contents are "cleaned".

Call relations: The test uses test_tool_runtime to run the same shell-tool path as normal tool dispatch. The cancellation token triggers shutdown, and the timeout around the task proves the runtime waits for process cleanup but still returns promptly.

Call graph: calls 3 internal fn (make_session_with_config, test_tool_runtime, build_tool_call); 13 external calls (clone, new, new, from_millis, from_secs, bail!, assert_eq!, format!, json!, new (+3 more)).

async fn unified_exec_rejects_escalated_permissions_when_policy_not_on_request()

Purpose: Checks the same escalated-permission security rule for the unified exec_command tool. It ensures both command-running backends enforce the approval policy consistently.

Data flow: It creates a session, sets approval policy to OnFailure, and invokes exec_command with RequireEscalated sandbox permissions and a justification. The handler returns FunctionCallError::RespondToModel with the expected rejection text.

Call relations: This test mirrors rejects_escalated_permissions_when_policy_not_on_request but goes through ExecCommandHandler instead of ShellCommandHandler. It confirms the newer unified execution path has the same guard.

Call graph: calls 4 internal fn (make_session_and_context, default, new, plain); 8 external calls (clone, new, new, format!, panic!, assert_eq!, json!, new).

async fn session_start_hooks_only_load_from_trusted_project_layers() -> std::io::Result<()>

Purpose: Checks that session-start hooks are discovered only from trusted project configuration layers. Hooks are scripts or actions loaded from project files, so trust boundaries matter for safety.

Data flow: It creates a temporary home and nested project, writes hook files at the project root and nested level, marks only the nested directory as trusted, and builds config from the nested working directory. It lists hooks and expects only the nested hook source to appear, marked untrusted, and previewing session-start hooks returns nothing.

Call relations: The test sets up files with write_project_hooks and trust data with write_project_trust_config, then calls codex_hooks::list_hooks and preview_session_start_hooks. It checks that config-layer trust controls hook discovery.

Call graph: calls 3 internal fn (write_project_hooks, write_project_trust_config, from_absolute_path); 8 external calls (assert!, assert_eq!, list_hooks, default, default, create_dir_all, write, tempdir).

async fn session_start_hooks_require_project_trust_without_config_toml() -> std::io::Result<()>

Purpose: Verifies that project hooks are loaded only when the project itself is trusted, even if there is no config.toml file. This prevents untrusted project directories from activating hooks just because hook files exist.

Data flow: It creates a temporary project with hooks and runs three cases: no trust entry, explicitly untrusted, and trusted. For each case it builds config and lists hooks. The expected hook count is zero for unknown and untrusted projects, and one for the trusted project; previewing session-start hooks still returns empty.

Call relations: The test repeatedly writes different trust configs and rebuilds ConfigBuilder output. It uses codex_hooks::list_hooks to confirm trust decisions, and preview_session_start_hooks to ensure no hook preview runs unexpectedly in these setups.

Call graph: calls 2 internal fn (write_project_hooks, write_project_trust_config); 11 external calls (new, assert!, assert_eq!, list_hooks, default, format!, default, create_dir_all, write, tempdir (+1 more)).

fn expect_text_output(output: &T) -> String

Purpose: This helper pulls plain text out of a tool result so tests can easily check what a command printed. It is used when a test expects a tool call to return normal output rather than an error.

Data flow: It receives any value that can be turned into a tool output. It converts that output into the same response item format the model would see, looks for a function-call output body, and returns the body as text. If the response is not a function-style output, it stops the test with a panic because the test setup expected a different kind of result.

Call relations: The shell-command tests call this after running a command handler. It sits between the low-level tool response format and the human-readable assertion, letting those tests simply ask whether the output contains text like “hi”.

Call graph: called by 3 (guardian_allows_shell_command_additional_permissions_requests_past_policy_validation, shell_command_allows_sticky_turn_permissions_without_inline_request_permissions_feature, strict_auto_review_turn_grant_forces_guardian_for_shell_command_policy_skip); 2 external calls (to_response_item, panic!).

async fn request_permissions_routes_to_guardian_when_reviewer_is_enabled()

Purpose: This test proves that a permission request is sent to Guardian when Guardian approval is enabled and the configuration says to use automatic review. It also proves that an approved request becomes a turn-scoped permission grant.

Data flow: The test starts a mock model server that will answer Guardian with an “allow” decision. It builds a session and turn context, turns on the approval policy and Guardian feature, asks for network permission, and waits for the permission request to finish. The result should be a permission response for the current turn, and the session should remember that network permission was granted for the local environment. The test also inspects the mock server request to confirm Guardian saw the permission request and its reason.

Call relations: The async test harness runs this test directly. Inside the test, the session’s permission-request path calls out to the configured model provider, which is pointed at the mock server. The mock server’s Guardian response flows back into the session, and the test then checks both the returned answer and the stored permission state.

Call graph: calls 5 internal fn (default, models_manager_with_provider, mount_sse_once, sse, start_mock_server); 11 external calls (clone, new, new, from_secs, default, assert!, assert_eq!, create_model_provider, format!, timeout (+1 more)).

async fn request_permissions_guardian_review_stops_when_cancelled()

Purpose: This test checks that a Guardian review can be cancelled safely. If the review is still waiting, cancelling should stop the permission request and avoid recording any grant.

Data flow: The test starts a mock server that begins a Guardian response but delays finishing it. It creates a session with Guardian approval enabled, starts a network permission request in a background task, and waits until a Guardian assessment event shows the review has begun. Then it cancels the cancellation token. The request should return no approval, and the session should have no saved turn permission.

Call relations: The test harness runs this as an async test. The spawned permission request enters the same session path used by real permission requests, while the test watches the session’s event channel to know when Guardian review has started. The cancellation token is then handed into that path as the signal to stop waiting.

Call graph: calls 6 internal fn (default, models_manager_with_provider, mount_response_once, sse, sse_response, start_mock_server); 13 external calls (clone, get_mut, new, new, from_secs, default, assert_eq!, create_model_provider, format!, matches! (+3 more)).

async fn guardian_allows_shell_command_additional_permissions_requests_past_policy_validation()

Purpose: This test proves that a shell command asking for extra permissions can pass policy validation when Guardian approves it. In everyday terms, it checks that a command is not blocked just because it needs a carefully reviewed temporary permission.

Data flow: The test prepares a mock Guardian response that allows the request, enables Guardian approval and execution permission approvals, and sets the turn’s normal permission profile to disabled. It then invokes the shell command tool with echo hi, asks for extra network permission, and includes a justification. If everything works, the command runs and its output contains “hi”.

Call relations: The test calls the shell command handler directly, using a tool invocation like the model would produce. The handler’s internal permission path consults Guardian through the mock model server. After the handler returns, the test uses expect_text_output to read the command output in a simple form.

Call graph: calls 8 internal fn (expect_text_output, models_manager_with_provider, from, new, mount_sse_once, sse, start_mock_server, plain); 11 external calls (clone, new, new, assert!, cfg!, codex_linux_sandbox_exe_or_skip!, create_model_provider, format!, json!, new (+1 more)).

async fn strict_auto_review_turn_grant_forces_guardian_for_shell_command_policy_skip()

Purpose: This test checks a stricter safety rule: even if a previous turn-scoped permission grant might let a command skip normal policy checks, a grant marked for strict auto-review still forces Guardian to review the command. This prevents a broad shortcut from bypassing the safety reviewer.

Data flow: The test records a turn permission grant for network access and marks it as requiring strict auto-review. It then configures the session so the normal approval reviewer is the user, not Guardian, and runs a simple echo hi shell command. The command should still run successfully, but the mock Guardian server should receive a request containing the command text.

Call relations: The test seeds session state before invoking the shell command handler. When the handler decides whether the command can run, the strict grant causes the flow to contact Guardian. The test then reads the command output with expect_text_output and inspects the mock server log to confirm Guardian was part of the path.

Call graph: calls 9 internal fn (expect_text_output, default, models_manager_with_provider, from, new, mount_sse_once, sse, start_mock_server, plain); 10 external calls (clone, new, new, default, assert!, create_model_provider, format!, json!, new, vec!).

async fn guardian_allows_unified_exec_additional_permissions_requests_past_policy_validation()

Purpose: This test checks validation for the newer unified exec command path when a command says it wants additional permissions but does not say which ones. Despite the name, the expected result here is a validation error because the request is incomplete.

Data flow: The test enables Guardian approval and execution permission approvals, then invokes the exec command tool with a request for with_additional_permissions but without the required additional_permissions details. The handler should not run the command. Instead, it should return a message telling the model to provide at least network or file-system permissions.

Call relations: The async test harness runs this test, and the test calls the exec command handler directly. The flow stops at validation before Guardian or command execution can matter, and the test checks that the error text is exactly the helpful message expected by the model-facing tool path.

Call graph: calls 3 internal fn (default, new, plain); 7 external calls (clone, new, new, assert_eq!, panic!, json!, new).

async fn process_compacted_history_preserves_separate_guardian_developer_message()

Purpose: This test makes sure that when conversation history is compacted, Guardian’s own developer instruction message is preserved separately and stale developer text is removed. This matters because Guardian’s safety instructions must remain clear and current.

Data flow: The test marks the session as a Guardian subagent and gives the turn context Guardian’s policy prompt as developer instructions. It then feeds compacted history containing an old developer message and a user summary into the history-compaction function. The refreshed history should not contain the stale developer message, should contain multiple developer messages, and should end with the current Guardian policy.

Call relations: The test calls process_compacted_history, which rebuilds the model-facing history after compaction. The Guardian session source and developer instructions are the important inputs, and the returned list of response items is inspected to confirm the Guardian prompt survived in the correct role.

Call graph: calls 1 internal fn (process_compacted_history); 6 external calls (SubAgent, assert!, assert_eq!, guardian_policy_prompt, Other, vec!).

async fn shell_command_allows_sticky_turn_permissions_without_inline_request_permissions_feature()

Purpose: This Unix-only test checks that a permission already granted for the current turn can still let a shell command run, even when inline additional-permission requests are not enabled. A “sticky” turn permission is like a temporary pass that should keep working for the rest of that turn.

Data flow: The test enables the request-permissions tool, creates an active turn, and directly records a network permission grant in that turn’s state. It then runs echo hi through the shell command handler without asking for new inline permissions. If the command succeeds, the output should contain “hi”; if it returns a model-facing validation error, that error must not claim that additional permissions are disabled.

Call relations: The test prepares the active turn state before calling the shell command handler. The handler reads the existing turn permission while deciding whether the command may run. If the handler returns normal output, the test uses expect_text_output; otherwise, it verifies that the error is not the specific validation failure this scenario is meant to avoid.

Call graph: calls 5 internal fn (expect_text_output, default, from, new, plain); 8 external calls (clone, new, new, default, assert!, panic!, json!, new).

async fn guardian_subagent_does_not_inherit_parent_exec_policy_rules()

Purpose: This test proves that a Guardian subagent does not inherit command policy rules from its parent session. That isolation is important because Guardian should review safety questions independently, not be blocked by parent rules meant for ordinary command execution.

Data flow: The test creates a temporary project with an execution policy rule that forbids commands starting with rm. It loads that policy and first confirms the parent policy would forbid rm. Then it spawns a Codex session whose source is the Guardian reviewer subagent and passes the parent policy as inherited policy. In the spawned Guardian session, checking the same rm command should be allowed by default heuristics rather than forbidden by the parent rule.

Call relations: The test builds a realistic Codex spawn setup with authentication, model, plugin, skill, environment, and thread-store services. It calls the policy loader to create the parent policy, then calls the Codex spawn path for a Guardian subagent. The final assertion checks the child session’s execution policy to confirm the spawn logic deliberately avoided inheriting the parent’s blocking rule.

Call graph: calls 13 internal fn (new, new, new, load, new, spawn, models_manager_with_provider, default_for_tests, from_auth_for_testing, from_api_key (+3 more)); 16 external calls (clone, new, default, new, default, SubAgent, assert_eq!, empty_extension_registry, default, default (+6 more)).

fn contribute(
        &'a self,
        _thread_store: &'a ExtensionData,
        _turn_store: &'a ExtensionData,
        item: &'a mut TurnItem,
    ) -> codex_extension_api::ExtensionFuture<'a, Res

Purpose: This is a test-only plug-in hook that rewrites an assistant message. It exists so the test can prove that contributed, modified turn items are the ones used later by plan mode.

Data flow: It receives shared extension data for the thread and turn, plus a mutable turn item. It ignores the extension data, checks whether the item is an agent message, and if so replaces its content with the text plan contributed assistant text. It returns a successful asynchronous result and changes the item in place.

Call relations: The test installs RewriteAgentMessageContributor into the session’s extension registry. When the plan-mode assistant item is processed, the extension system calls this contributor, and its rewritten message becomes the value the test expects to see as the last agent message.

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

fn assistant_output_text(text: &str) -> ResponseItem

Purpose: This helper builds a small fake assistant response containing the text the test wants to start with. It keeps the test readable by hiding the response-item construction details.

Data flow: It takes a plain text string, copies it into an assistant ResponseItem::Message, and fills in the minimal fields needed for the test, such as an id, role, and output-text content. It returns that response item to the caller.

Call relations: plan_mode_uses_contributed_turn_item_for_last_agent_message calls this helper to create the original assistant message. That original message is then sent through the plan-mode path, where the contributor is expected to replace its text.

Call graph: called by 1 (plan_mode_uses_contributed_turn_item_for_last_agent_message); 1 external calls (vec!).

async fn plan_mode_uses_contributed_turn_item_for_last_agent_message()

Purpose: This test proves that plan mode records the extension-modified assistant message as the last agent message. It guards against a bug where the system might accidentally keep the original assistant text instead of the contributed version.

Data flow: It starts by creating a test session and turn context. It then builds an extension registry containing the rewrite contributor and attaches it to the session. Next it creates turn-local extension data, plan-mode stream state, an empty last_agent_message, and an assistant response whose text says original assistant text. After running the plan-mode assistant-item completion path, it checks two outcomes: the item was handled, and last_agent_message now contains plan contributed assistant text.

Call relations: This is the top-level test case. It uses the session test helper to get a working session setup, uses assistant_output_text to make the input message, installs RewriteAgentMessageContributor, and then exercises the plan-mode processing path. The final assertions confirm that all those pieces worked together in the intended order.

Call graph: calls 5 internal fn (make_session_and_context, new, assistant_output_text, new, new); 3 external calls (new, assert!, assert_eq!).

fn user_message(text: &str) -> ResponseItem

Purpose: Creates a simple saved conversation item that looks like a user typing plain text. Tests use it so they can compare reconstructed history against clear expected messages.

Data flow: It receives a text string, wraps that text as input content from the user, and returns a ResponseItem message. It does not change any shared state.

Call relations: Rollback reconstruction tests call this helper when they need both rollout input and expected output to use the exact same message shape. It keeps those tests focused on reconstruction behavior rather than message construction details.

Call graph: called by 3 (reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_completed_turns, reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_incomplete_turn, reconstruct_history_rollback_skips_non_user_turns_for_history_and_metadata); 1 external calls (vec!).

fn assistant_message(text: &str) -> ResponseItem

Purpose: Creates a simple saved conversation item that looks like the assistant replying with plain text. Tests use it as the expected assistant side of rebuilt history.

Data flow: It receives a text string, wraps that text as output content from the assistant, and returns a ResponseItem message. Nothing outside the returned value is changed.

Call relations: Several rollback tests call this helper to build assistant replies before handing rollout items to the session reconstruction code. The helper makes those tests compare meaningful history entries rather than hand-built structures.

Call graph: called by 4 (reconstruct_history_rollback_counts_inter_agent_assistant_turns, reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_completed_turns, reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_incomplete_turn, reconstruct_history_rollback_skips_non_user_turns_for_history_and_metadata); 1 external calls (vec!).

fn inter_agent_assistant_message(text: &str) -> ResponseItem

Purpose: Creates an assistant message whose text is actually a serialized inter-agent communication. This tests the special case where one agent instructs or talks to another agent through the normal message stream.

Data flow: It receives human-readable text, builds an InterAgentCommunication from the root agent to a worker agent, turns that communication into JSON text, and returns it as an assistant ResponseItem. The result looks like an assistant message but carries structured agent-to-agent data.

Call relations: reconstruct_history_rollback_counts_inter_agent_assistant_turns uses this helper to prove that assistant-originated inter-agent turns are counted correctly during rollback. The helper relies on the protocol types that know how to describe agent paths and communication payloads.

Call graph: calls 2 internal fn (root, new); called by 1 (reconstruct_history_rollback_counts_inter_agent_assistant_turns); 2 external calls (new, vec!).

async fn record_initial_history_reconstructs_typed_inter_agent_message()

Purpose: Checks that resuming a session with a typed inter-agent communication restores it as the model input item the session expects. This protects the path where agent-to-agent messages are stored as structured rollout items.

Data flow: The test creates a session, builds an inter-agent communication, wraps it in resumed initial history, and records that history into the session. It then reads the session history and expects to see the communication converted into the model-facing input form.

Call relations: The async test runner invokes this test. It uses make_session_and_context to get a fresh session, then exercises record_initial_history, which is the real resume entry point being verified.

Call graph: calls 4 internal fn (make_session_and_context, root, new, default); 5 external calls (from, new, assert_eq!, Resumed, vec!).

async fn record_initial_history_resumed_bare_turn_context_does_not_hydrate_previous_turn_settings()

Purpose: Checks that a lone saved turn context is not enough to restore previous turn settings. A context item only becomes trustworthy when it appears inside a real turn lifecycle.

Data flow: The test creates a resumed history containing only a TurnContextItem with an older model name. After recording it into the session, it reads previous_turn_settings and reference_context_item and expects both to be empty.

Call relations: The test runner calls this case to guard record_initial_history. It sets up a session through make_session_and_context, then verifies that resume logic does not treat loose metadata as a completed prior turn.

Call graph: calls 2 internal fn (make_session_and_context, default); 5 external calls (from, assert!, assert_eq!, Resumed, vec!).

async fn record_initial_history_resumed_hydrates_previous_turn_settings_from_lifecycle_turn_with_missing_turn_context_id()

Purpose: Checks that previous turn settings can still be restored when the turn context itself is missing its turn id, as long as the surrounding turn events identify the turn. This supports older or imperfect logs.

Data flow: The test builds a rollout with turn-start, user-message, turn-context, and turn-complete records. The context has no turn_id, but the lifecycle events provide one. After resume, the session should remember the previous model, compatibility hash, and realtime setting.

Call relations: The test runner invokes it as a resume compatibility case. It uses record_initial_history to prove that reconstruction can connect a context item to its active turn even when the context item is incomplete.

Call graph: calls 2 internal fn (make_session_and_context, default); 4 external calls (from, assert_eq!, Resumed, vec!).

async fn reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_completed_turns()

Purpose: Checks that rolling back a completed later turn removes both its messages and its saved settings. The remaining history and metadata should both point to the same earlier turn.

Data flow: The test creates two completed turns, then adds a rollback that removes one turn. Reconstruction should output only the first turn’s user and assistant messages, and its previous-turn metadata should match the first turn’s context.

Call relations: This test calls user_message and assistant_message to build expected chat items, then calls reconstruct_history_from_rollout on the session. It verifies that rollback is not just deleting messages, but also rewinding the hidden context markers.

Call graph: calls 3 internal fn (assistant_message, user_message, make_session_and_context); 2 external calls (assert_eq!, vec!).

async fn reconstruct_history_rollback_keeps_history_and_metadata_in_sync_for_incomplete_turn()

Purpose: Checks that rollback also works when the later turn was never completed. An unfinished user turn should not leave behind messages or metadata after rollback.

Data flow: The test creates one completed turn, then starts a second user turn without completing it, and finally records a rollback. Reconstruction should keep only the first turn’s messages and restore metadata from the first turn.

Call relations: The test runner calls this to cover interrupted or partially written rollouts. It uses the message helpers for expected history and asks reconstruct_history_from_rollout to process the incomplete timeline.

Call graph: calls 3 internal fn (assistant_message, user_message, make_session_and_context); 2 external calls (assert_eq!, vec!).

async fn reconstruct_history_rollback_skips_non_user_turns_for_history_and_metadata()

Purpose: Checks that rollback counts user-facing turns, not every internal turn. A standalone assistant/internal task should not consume a rollback count meant for user turns.

Data flow: The test builds a valid first user turn, a second user turn, then a standalone assistant-only turn, followed by a rollback of one turn. Reconstruction should remove the second user turn and ignore the standalone turn for rollback counting, leaving the first turn’s history and metadata.

Call relations: This case uses user_message and assistant_message to build the rollout and expected result. It exercises reconstruct_history_from_rollout to make sure hidden non-user activity does not confuse user-visible undo behavior.

Call graph: calls 3 internal fn (assistant_message, user_message, make_session_and_context); 2 external calls (assert_eq!, vec!).

async fn reconstruct_history_rollback_counts_inter_agent_assistant_turns()

Purpose: Checks that an assistant turn carrying an inter-agent instruction is counted during rollback. Even though it is assistant-originated, it represents meaningful agent work that must be undoable.

Data flow: The test builds a normal user turn, then an assistant-driven inter-agent turn with a worker reply, then rolls back one turn. Reconstruction should remove that inter-agent turn and keep the earlier user turn’s history and metadata.

Call relations: This test calls inter_agent_assistant_message for the special instruction message and assistant_message for ordinary replies. It then uses reconstruct_history_from_rollout to verify the rollback classification rule.

Call graph: calls 3 internal fn (assistant_message, inter_agent_assistant_message, make_session_and_context); 2 external calls (assert_eq!, vec!).

async fn reconstruct_history_rollback_clears_history_and_metadata_when_exceeding_user_turns()

Purpose: Checks the safety behavior when a rollback asks to remove more turns than exist. The session should end up with no conversation history and no previous-turn metadata.

Data flow: The test builds a single completed user turn and then records a rollback for many turns. Reconstruction turns that into an empty history, no previous settings, and no reference context item.

Call relations: The async test runner invokes this boundary case. It calls the real reconstruction method to ensure excessive rollback does not leave stale context behind.

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

async fn record_initial_history_resumed_rollback_skips_only_user_turns()

Purpose: Checks that, during full session resume, rollback skips only user turns and does not let standalone task turns affect the count. This mirrors the direct reconstruction rule in the resume path.

Data flow: The test records a user turn, then a standalone task turn with no user message, then a rollback of one turn. After record_initial_history, the session should have no previous settings or reference context because the one user turn was removed.

Call relations: This test is driven by the async test runner and goes through record_initial_history, not just the lower-level reconstruction helper. It proves the production resume path applies the same rollback counting rule.

Call graph: calls 2 internal fn (make_session_and_context, default); 5 external calls (from, assert!, assert_eq!, Resumed, vec!).

async fn record_initial_history_resumed_rollback_drops_incomplete_user_turn_compaction_metadata()

Purpose: Checks that compaction metadata from an incomplete rolled-back user turn is not allowed to poison the restored reference context. The previous completed turn should remain the trusted baseline.

Data flow: The test builds one completed turn with context, then an incomplete user turn that includes a compaction record, then a rollback. After resume, previous settings and reference context should still come from the completed turn, not from the incomplete compacted one.

Call relations: The test runner invokes this resume case to protect record_initial_history from a subtle ordering problem. It ensures rollback removes the incomplete turn’s compaction effects from metadata accounting.

Call graph: calls 2 internal fn (make_session_and_context, default); 4 external calls (from, assert_eq!, Resumed, vec!).

async fn record_initial_history_resumed_bare_turn_context_does_not_seed_reference_context_item()

Purpose: Checks that a turn context by itself does not become the session’s reference context. The session requires real turn evidence before trusting that context.

Data flow: The test creates a resumed history containing only a context item. After recording it, it asks the session for its reference context and expects none.

Call relations: This is a focused resume test for record_initial_history. It complements the previous-turn-settings test by checking the separate reference-context field.

Call graph: calls 2 internal fn (make_session_and_context, default); 4 external calls (from, assert!, Resumed, vec!).

async fn record_initial_history_resumed_does_not_seed_reference_context_item_after_compaction()

Purpose: Checks that compaction prevents an earlier loose context item from becoming a trusted reference. Once history is compacted, old baseline context may no longer describe the current reconstructed history.

Data flow: The test records a bare context item followed by a compaction item. After resume, the session should have no previous settings and no reference context item.

Call relations: The test runner calls this to exercise record_initial_history with compaction present. It confirms that compaction clears trust in context that was not tied to a valid later turn.

Call graph: calls 2 internal fn (make_session_and_context, default); 5 external calls (from, assert!, assert_eq!, Resumed, vec!).

async fn reconstruct_history_legacy_compaction_without_replacement_history_does_not_inject_current_initial_context()

Purpose: Checks behavior for older compaction records that contain only a summary and no replacement history. Reconstruction should not secretly add the current session’s context into the rebuilt history.

Data flow: The test builds history with a user message, assistant reply, and a legacy compaction summary. Reconstruction should keep the original user message and add the summary as a user-style message, while leaving the reference context empty.

Call relations: This direct reconstruction test uses simple helper messages and calls reconstruct_history_from_rollout. It protects compatibility with old rollout files whose compaction format lacks newer metadata.

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

async fn reconstruct_history_legacy_compaction_without_replacement_history_clears_later_reference_context_item()

Purpose: Checks that a legacy compaction record blocks later context from being treated as a valid reference. This avoids trusting context after a history rewrite that cannot be fully reconstructed.

Data flow: The test builds a legacy compaction record, then a later normal-looking turn context. Reconstruction should still leave the reference context empty because the earlier compaction made the baseline unreliable.

Call relations: The test runner invokes this direct reconstruction case. It calls reconstruct_history_from_rollout to verify that old compaction behavior takes priority over later context seeding.

Call graph: calls 1 internal fn (make_session_and_context); 2 external calls (assert!, vec!).

async fn record_initial_history_resumed_turn_context_after_compaction_reestablishes_reference_context_item()

Purpose: Checks that a turn context appearing after compaction can re-establish a trusted reference when it is part of a real turn. Compaction clears the old baseline, but a later valid turn can create a new one.

Data flow: The test records a turn start and user message, then a compaction item, then a turn context, then turn completion. After resume, the session should restore previous settings and reference context from that post-compaction turn context.

Call relations: This test runs through record_initial_history to verify the full resume path. It demonstrates the intended reset-and-rebuild behavior around compaction.

Call graph: calls 2 internal fn (make_session_and_context, default); 4 external calls (from, assert_eq!, Resumed, vec!).

async fn record_initial_history_resumed_aborted_turn_without_id_clears_active_turn_for_compaction_accounting()

Purpose: Checks that an abort event with no turn id still clears the active turn for compaction bookkeeping. This matters because some interrupted turns may not record their id on abort.

Data flow: The test records a completed prior turn, then starts a new user turn, aborts it with no id, and adds a compaction item. After resume, previous settings should still come from the prior turn, but the reference context should be cleared by compaction.

Call relations: The test runner calls this resume scenario to protect record_initial_history from stale active-turn state. It verifies that an id-less abort is treated as applying to the currently active turn.

Call graph: calls 2 internal fn (make_session_and_context, default); 5 external calls (from, assert!, assert_eq!, Resumed, vec!).

async fn record_initial_history_resumed_unmatched_abort_preserves_active_turn_for_later_turn_context()

Purpose: Checks that an abort for a different turn does not clear the currently active turn. A later context for the active turn should still be accepted.

Data flow: The test records one completed prior turn, starts a current turn, inserts an abort event naming some other turn, then records the current turn’s context and completion. After resume, previous settings and reference context should come from the current turn.

Call relations: This test exercises record_initial_history with mismatched abort data. It pairs with the id-less abort test to define exactly when active-turn tracking should be cleared.

Call graph: calls 2 internal fn (make_session_and_context, default); 4 external calls (from, assert_eq!, Resumed, vec!).

async fn record_initial_history_resumed_trailing_incomplete_turn_compaction_clears_reference_context_item()

Purpose: Checks that if a final incomplete user turn is compacted, the reference context is cleared. The session can keep previous settings from the last completed turn, but should not keep a stale reference context.

Data flow: The test records a completed prior turn, then starts a trailing incomplete user turn and adds a compaction item. After resume, previous settings remain from the prior turn, while the reference context is empty.

Call relations: The test runner invokes this as a full resume case through record_initial_history. It verifies safe cleanup when a rollout ends after compaction but before the active turn finishes.

Call graph: calls 2 internal fn (make_session_and_context, default); 5 external calls (from, assert!, assert_eq!, Resumed, vec!).

async fn record_initial_history_resumed_trailing_incomplete_turn_preserves_turn_context_item()

Purpose: Checks that an unfinished trailing turn can still provide valid settings if it contains a turn context and has not been compacted away. This lets a resumed session continue from a partially recorded but context-bearing turn.

Data flow: The test starts a turn, records a user message and a turn context, but no completion. After resume, the session should restore previous settings and reference context from that context item.

Call relations: This test calls record_initial_history to cover the resume path for a rollout that ends mid-turn. It contrasts with the compaction case, where the reference context must be cleared.

Call graph: calls 2 internal fn (make_session_and_context, default); 4 external calls (from, assert_eq!, Resumed, vec!).

async fn record_initial_history_resumed_replaced_incomplete_compacted_turn_clears_reference_context_item()

Purpose: Checks that when an incomplete compacted turn is replaced by a newer turn start, its reference context stays cleared. A new turn starting without completing the old one should not revive stale compacted metadata.

Data flow: The test records a completed prior turn, then an incomplete user turn with compaction, then starts another turn that replaces it. After resume, previous settings remain from the completed prior turn, and the reference context is empty.

Call relations: The async test runner calls this final edge case through record_initial_history. It protects the active-turn and compaction accounting when logs contain overlapping or replaced turns.

Call graph: calls 2 internal fn (make_session_and_context, default); 5 external calls (from, assert!, assert_eq!, Resumed, vec!).

fn meta(value: Value) -> Option<Meta>

Purpose: This helper wraps a JSON object as MCP metadata for use in the tests. It makes test setup shorter and also catches mistakes where a test accidentally passes something other than a JSON object.

Data flow: It receives a JSON value. If that value is an object, it wraps the object in a Meta value and returns it inside Some, meaning metadata is present. If the value is not an object, it stops the test with a panic because metadata is expected to be object-shaped.

Call relations: The other test helpers and test cases call this when they need metadata. guardian_meta uses it after building the standard Guardian metadata, and two tests call it directly to create intentionally incomplete or unusual metadata shapes.

Call graph: called by 3 (guardian_elicitation_review_request_declines_unsupported_opt_in_shapes, guardian_elicitation_review_request_requires_opt_in, guardian_meta); 1 external calls (panic!).

fn guardian_meta(tool_params: Option<Value>) -> Option<Meta>

Purpose: This helper creates the standard metadata that says an MCP elicitation is asking Guardian to review an MCP tool call. It optionally includes the tool arguments that Guardian should review.

Data flow: It starts with a JSON object containing fields such as approval kind, request type, connector ID, connector name, tool name, and tool title. If tool parameters are provided, it adds them under tool_params. It then passes the finished JSON object to meta, which wraps it as MCP metadata.

Call relations: Several tests call this to create a realistic Guardian opt-in request before passing it through form_request. It hands off to meta so all metadata wrapping is done consistently.

Call graph: calls 1 internal fn (meta); called by 3 (guardian_elicitation_review_request_builds_mcp_tool_call, guardian_elicitation_review_request_declines_unsupported_opt_in_shapes, guardian_elicitation_review_request_defaults_missing_tool_params); 1 external calls (json!).

fn form_request(meta: Option<Meta>) -> ElicitationReviewRequest

Purpose: This helper builds a simple form-style MCP elicitation review request for tests. It represents a tool asking a yes-or-no style approval question with an empty requested form schema.

Data flow: It receives optional metadata. It creates an ElicitationReviewRequest for the browser-use server, gives it a numeric request ID, sets a message of “Allow origin?”, and builds an empty form schema. The finished request is returned for the test to inspect through the production conversion functions.

Call relations: Most of the Guardian conversion tests call this to avoid repeating the same request setup. Those tests vary only the metadata, then pass the resulting request into guardian_elicitation_review_request.

Call graph: called by 4 (guardian_elicitation_review_request_builds_mcp_tool_call, guardian_elicitation_review_request_declines_unsupported_opt_in_shapes, guardian_elicitation_review_request_defaults_missing_tool_params, guardian_elicitation_review_request_requires_opt_in); 2 external calls (builder, Number).

fn guardian_elicitation_review_request_builds_mcp_tool_call()

Purpose: This test verifies the happy path: a properly marked MCP elicitation becomes a Guardian approval request for an MCP tool call. It checks that important details are copied correctly, including the tool arguments and connector labels.

Data flow: It builds a form request with Guardian metadata and a sample origin argument. It sends that request into guardian_elicitation_review_request. It then unpacks the returned Guardian approval request and compares each important field against the expected values.

Call relations: This test uses guardian_meta and form_request to create the input. It exercises the production conversion function guardian_elicitation_review_request and confirms that the result has the exact shape Guardian needs for reviewing a tool call.

Call graph: calls 2 internal fn (form_request, guardian_meta); 3 external calls (assert_eq!, json!, panic!).

fn guardian_elicitation_review_request_defaults_missing_tool_params()

Purpose: This test checks that missing tool parameters are treated as an empty argument object rather than as an error or a missing value. That matters because Guardian still needs a stable request shape even when a tool has no arguments.

Data flow: It builds a Guardian-marked form request without tool_params. It passes the request to guardian_elicitation_review_request, extracts the arguments from the Guardian MCP tool-call request, and checks that they equal an empty JSON object.

Call relations: The test relies on guardian_meta to create metadata without optional parameters and form_request to make the review request. It verifies one narrow behavior of guardian_elicitation_review_request: safe defaulting of absent arguments.

Call graph: calls 2 internal fn (form_request, guardian_meta); 2 external calls (assert_eq!, panic!).

fn plugin_install_elicitation_telemetry_metadata_requires_install_tool_suggestion()

Purpose: This test checks that telemetry metadata is collected only for plugin install suggestions, not for other suggestion types such as enabling an already available plugin. Telemetry here means small structured facts used for logging or measurement.

Data flow: It first builds an elicitation event whose metadata says it is a tool suggestion to install a plugin named Slack. It calls plugin_install_elicitation_telemetry_metadata and expects the plugin type, ID, and name to be returned. Then it builds a similar event where the suggestion type is enable instead of install, calls the same function, and expects no metadata.

Call relations: This test directly exercises plugin_install_elicitation_telemetry_metadata with two event examples. The first shows the accepted path, and the second shows that the function filters out non-install suggestions.

Call graph: 4 external calls (String, assert_eq!, json!, ElicitationRequest).

fn guardian_elicitation_review_request_requires_opt_in()

Purpose: This test makes sure a request is not treated as a Guardian approval request unless it includes the explicit request-type marker. This prevents ordinary or incomplete metadata from being upgraded into an approval flow by accident.

Data flow: It creates metadata that says the approval kind is an MCP tool call and includes a tool name, but leaves out the codex_request_type approval marker. It builds a form request with that metadata, passes it to guardian_elicitation_review_request, and expects the result to be NotRequested.

Call relations: The test uses meta and form_request to create a deliberately incomplete request. It checks that guardian_elicitation_review_request refuses to enter the Guardian path unless the opt-in metadata is complete.

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

fn guardian_elicitation_review_request_declines_unsupported_opt_in_shapes()

Purpose: This test confirms that requests which opt into Guardian review but have unsupported shapes are declined safely. That is important because the system should not guess how to approve requests it does not understand.

Data flow: It creates three problematic requests: a URL-style elicitation, a form elicitation with a non-empty schema, and a form request missing the required tool name. Each one is passed to guardian_elicitation_review_request, and each is expected to produce a Decline result.

Call relations: The test uses guardian_meta, meta, and form_request for setup, plus schema builders for the non-empty form case. It exercises the defensive branches of guardian_elicitation_review_request, proving that unsupported opt-in requests are rejected rather than silently accepted.

Call graph: calls 3 internal fn (form_request, guardian_meta, meta); 6 external calls (new, builder, Boolean, assert!, json!, Number).

fn guardian_decisions_map_to_elicitation_responses_without_session_state()

Purpose: This test checks the translation from Guardian review decisions into MCP elicitation responses without needing a live session. It verifies what the tool server will receive after Guardian approves, denies, times out, or aborts a request.

Data flow: It calls mcp_elicitation_response_from_guardian_decision_parts with four decisions. Approved becomes an Accept response with empty content. Denied becomes Decline with the denial message. TimedOut becomes Decline with the standard Guardian timeout message. Abort becomes Cancel. Each response also includes metadata showing that the reviewer was the automatic Guardian reviewer.

Call relations: This test directly exercises mcp_elicitation_response_from_guardian_decision_parts. It stands apart from the request-building helpers because it checks the return trip: after Guardian has made a decision, the system must send the correct MCP response back.

Call graph: 1 external calls (assert_eq!).

async fn merge_connector_selection_deduplicates_entries()

Purpose: This test proves that adding connector IDs to the session removes repeats. A user or caller can ask for "calendar" twice, but the stored selection should contain it only once.

Data flow: It starts by asking make_session_configuration_for_tests for a test configuration, then creates a fresh SessionState with new. It feeds the state a small list containing two "calendar" entries and one "drive" entry. The result is compared with a set containing only "calendar" and "drive", so the before state with duplicates becomes an after state with unique IDs.

Call relations: During the test run, the async test runner calls this function. The function uses the shared test configuration helper and SessionState construction path, then checks the session state's connector-merging behavior with assert_eq!, which reports a clear failure if duplicates remain.

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

async fn clear_connector_selection_removes_entries()

Purpose: This test proves that clearing connector selection really empties the saved connector list. Without this, a later request might accidentally reuse a connector the user no longer wanted.

Data flow: It gets a test configuration, creates a new SessionState, and first stores one connector ID, "calendar". It then calls the clearing operation and reads the stored connector selection back. The expected output is an empty set, meaning the stored selection changed from containing one item to containing none.

Call relations: The async test runner invokes this as an isolated check. It relies on make_session_configuration_for_tests and new to create a clean state, then uses assert_eq! to confirm the clearing operation leaves no connector IDs behind.

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

async fn set_rate_limits_defaults_limit_id_to_codex_when_missing()

Purpose: This test checks the default rule for rate-limit updates that arrive without a limit ID. The session should label that update as the main "codex" limit instead of leaving the identity unclear.

Data flow: It creates a fresh SessionState from a test configuration. It then sends in a RateLimitSnapshot whose limit_id and limit_name are missing but whose primary usage window has values. After the update, it reads latest_rate_limits from the state and expects the stored limit_id to be "codex".

Call relations: The test runner calls this function as part of the state test suite. The function sets up a normal SessionState using make_session_configuration_for_tests and new, exercises the rate-limit update rule, and hands the final comparison to assert_eq!.

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

async fn replace_history_clears_auto_compact_window_prefill()

Purpose: This test makes sure that replacing the conversation history clears a saved token estimate used for auto-compaction. That matters because an estimate from old history would be misleading after the history has been replaced.

Data flow: It creates a new session state, stores an estimated prefill value of 100 tokens, and then replaces the history with an empty list and no reference context item. After that, it asks for the auto-compact window snapshot. The expected result is a snapshot with no prefill_input_tokens value, showing that the old estimate was removed.

Call relations: The async test runner invokes this check. It uses the shared test configuration helper, creates a SessionState with new, builds the expected AutoCompactWindowSnapshot value, and uses assert_eq! to verify that history replacement also resets the related compaction bookkeeping.

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

async fn set_rate_limits_defaults_to_codex_when_limit_id_missing_after_other_bucket()

Purpose: This test protects against a subtle mix-up between rate-limit buckets. If the session last saw a "codex_other" bucket and the next update has no ID, the missing ID should still default to "codex", not inherit "codex_other".

Data flow: It starts with a clean SessionState. First it stores a rate-limit snapshot explicitly marked as "codex_other". Then it stores a second snapshot with no limit_id. Finally it reads the latest stored rate-limit ID and expects it to be "codex". The important change is that a missing ID is actively filled with the main bucket name rather than copied from the previous update.

Call relations: The test runner calls this function to check a sequence of two updates, not just a single update. The setup comes from make_session_configuration_for_tests and new, and assert_eq! verifies that the second update follows the defaulting rule even after a different bucket was stored before.

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

async fn set_rate_limits_carries_account_metadata_from_codex_to_codex_other()

Purpose: This test checks that account-level details are preserved when moving from a main codex rate-limit update to a related codex_other update. The later bucket update may only contain usage-window data, but the session should not forget credits, spend limits, or plan type that still apply to the account.

Data flow: It creates a fresh SessionState and first stores a "codex" RateLimitSnapshot containing usage data plus credits, an individual spend-control limit, and the Plus plan type. It then stores a "codex_other" snapshot that has its own usage window but omits those account details. The final stored snapshot should combine the new "codex_other" usage data with the earlier account metadata from the codex snapshot.

Call relations: The async test runner invokes this as a regression check for rate-limit state merging. The function uses make_session_configuration_for_tests and new for setup, then sends two snapshots through the session state and uses assert_eq! to compare the whole final snapshot with the expected merged result.

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

fn error_completion_message_stays_below_manual_review_threshold()

Purpose: This test makes sure an error completion message is shortened enough to stay below the manual review size limit. It also verifies that the shortened message still includes the expected instruction about what should happen next.

Data flow: The test starts with a root agent path, a worker agent path, and an error status containing a deliberately huge repeated error string. It sends those into the completion-message formatter. The returned message is then measured with an approximate token counter and searched for the required next-action text. The test passes only if the message is small enough and still contains that guidance.

Call relations: During the test run, this function calls the agent-path helpers to describe who is reporting to whom, builds an errored agent status, and hands all of that to the shared completion-message formatting function. It then uses assertions to lock in the expected behavior: the formatter may trim or shape the error text, but it must not produce an oversized message or lose the standard error next step.

Call graph: calls 2 internal fn (root, try_from); 3 external calls (assert!, Errored, format_inter_agent_completion_message).

async fn process_compacted_history_with_test_session(
    compacted_history: Vec<ResponseItem>,
    previous_turn_settings: Option<&PreviousTurnSettings>,
) -> (Vec<ResponseItem>, Vec<ResponseItem>)

Purpose: This helper builds a realistic test session, optionally gives it previous-turn settings, and runs compacted history through the same refresh path used by the real system. Tests use it so they do not have to repeat the setup work each time.

Data flow: It receives a list of compacted conversation items and optional settings from the previous turn. It creates a test session and context, stores the previous settings if any, builds the fresh initial context, then asks the compaction-refresh code to process the history. It returns both the refreshed history and the initial context so each test can compare the result against an expected answer.

Call relations: Several async tests call this helper when they need the full session-based path. Inside, it asks make_session_and_context for a realistic session setup, then hands the compacted history to process_compacted_history so the test exercises the real refresh behavior rather than a hand-made shortcut.

Call graph: calls 2 internal fn (process_compacted_history, make_session_and_context); called by 6 (process_compacted_history_drops_legacy_warnings, process_compacted_history_drops_non_user_content_messages, process_compacted_history_inserts_context_before_last_real_user_message_only, process_compacted_history_reinjects_full_initial_context, process_compacted_history_reinjects_model_switch_message, process_compacted_history_replaces_developer_messages).

fn user_message(text: &str) -> ResponseItem

Purpose: This small helper creates a standard user message from plain text. It keeps tests shorter and makes each fake conversation item look like the real data structure used by the system.

Data flow: It takes a text string, wraps it in a user-role message with one input-text content item, and leaves optional fields such as id and metadata empty. The output is a ResponseItem ready to be placed in a test conversation history.

Call relations: The legacy-warning compaction test calls this helper to build several fake user messages quickly. The helper uses the usual vector-building machinery to put the content item into the message.

Call graph: called by 1 (process_compacted_history_drops_legacy_warnings); 1 external calls (vec!).

fn compacted_user_message(text: &str) -> CompactedUserMessage

Purpose: This helper creates a compacted user message from plain text. It is used when a test needs the smaller intermediate form that compaction code works with before rebuilding response history.

Data flow: It receives text, copies it into a CompactedUserMessage, and leaves metadata empty. The result is a simple compacted-message value that can be passed to history-building code.

Call relations: The token-limit truncation test calls this helper before passing the message into the compacted-history builder. It keeps that test focused on truncation behavior instead of setup details.

Call graph: called by 1 (build_token_limited_compacted_history_truncates_overlong_user_messages).

fn content_items_to_text_joins_non_empty_segments()

Purpose: This test checks that text content is combined in a clean, readable way. Empty text pieces should not create extra blank output.

Data flow: It starts with content containing hello, an empty text segment, and world. It converts the content to text and expects the result to be hello and world joined with a newline.

Call relations: This is a focused unit test: it builds its sample content locally and then compares the result with the expected text using an equality assertion.

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

fn content_items_to_text_ignores_image_only_content()

Purpose: This test makes sure image-only content is not treated as if it had text. That matters because compacted summaries and user-message collection should not invent text where none exists.

Data flow: It creates a content list with only an input image. After conversion, it expects no text result at all, represented as None.

Call relations: This test builds a single image content item and checks the conversion result directly with an equality assertion.

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

fn collect_user_messages_extracts_user_text_only()

Purpose: This test checks that only real user text is collected from a mixed conversation. Assistant messages and non-message items should be ignored.

Data flow: It creates a fake history with an assistant text message, a user text message, and an unrelated item. After collection, only the user's first message should remain in compacted form.

Call relations: The test constructs the mixed input locally and compares the collected output against a single expected compacted user message.

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

fn collect_user_messages_filters_session_prefix_entries()

Purpose: This test checks that generated setup text is not mistaken for something the user actually asked. Project instructions and environment context are useful internally, but they should not become part of the compacted user-message list.

Data flow: It feeds in three user-role messages: an AGENTS.md instruction block, an environment-context block, and a real user message. The collection step should drop the first two and return only real user message.

Call relations: The test builds all messages in place and verifies the filtering rule with an equality assertion.

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

fn collect_user_messages_filters_legacy_warnings()

Purpose: This test protects against old system warning messages being preserved as user intent. Those warnings were injected into history in older flows, but they should not influence future compacted conversations.

Data flow: It creates several warning-shaped user messages plus one real user message. The collection step should remove the warnings and keep only the real message.

Call relations: The test uses locally built input data and compares the collected result with the expected single compacted user message.

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

fn build_token_limited_compacted_history_truncates_overlong_user_messages()

Purpose: This test checks that very large user messages are shortened before being placed into compacted history. Without this, a compacted conversation could still exceed the model’s size limit.

Data flow: It sets a small token limit, creates a very long repeated-word message, and asks the history builder to include it with a summary. The output should contain two messages: a shortened user message with a clear truncation marker, and the summary message unchanged.

Call relations: The test calls compacted_user_message to make the oversized input, then hands it to build_compacted_history_with_limit. It uses assertions to check both the truncation marker and the final summary.

Call graph: calls 1 internal fn (compacted_user_message); 6 external calls (new, assert!, assert_eq!, panic!, from_ref, build_compacted_history_with_limit).

fn build_token_limited_compacted_history_appends_summary_message()

Purpose: This test confirms that the compacted history builder always adds the summary at the end. The summary is the condensed memory of earlier conversation, so losing it would make the model forget important context.

Data flow: It starts with no initial context, one compacted user message, and a summary string. After building history, it inspects the last item and expects it to be a user-role message containing exactly the summary text.

Call relations: This test builds its input data directly and checks the final history with assertions, including a failure path that reports an unexpected item if the last entry is not the expected message.

Call graph: 5 external calls (new, assert!, assert_eq!, panic!, vec!).

fn build_compacted_history_preserves_user_message_metadata()

Purpose: This test checks that metadata attached to a compacted user message, such as a turn id, survives when history is rebuilt. That link matters for tracing which turn a message came from.

Data flow: It creates one compacted user message with metadata containing turn-1, then builds compacted history with a summary. The rebuilt user message should still carry turn-1, while the new summary message should have no turn id.

Call relations: The test calls the history builder with a small prepared input and verifies the metadata on the resulting entries with equality assertions.

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

fn should_use_remote_compact_task_for_azure_provider()

Purpose: This test checks that Azure-backed model providers use the remote compaction task path. That matters because provider differences can affect which compaction method is safe or supported.

Data flow: It creates a model-provider description named Azure with response-style API settings. It asks the decision function whether remote compaction should be used and expects the answer to be true.

Call relations: This is a direct decision-rule test. It builds the provider record locally and uses an assertion to confirm the rule’s result.

Call graph: 1 external calls (assert!).

async fn process_compacted_history_replaces_developer_messages()

Purpose: This async test verifies that old developer messages inside compacted history are removed and replaced by fresh initial context. Developer messages are instruction-like messages from the system side, so stale ones could give the model outdated rules.

Data flow: It starts with compacted history containing stale developer text before and after a user summary. The helper processes the history in a test session. The expected result is the fresh initial context followed by the user summary, with stale developer messages gone.

Call relations: The test calls process_compacted_history_with_test_session, which in turn creates a test session and runs process_compacted_history. After that, the test appends the expected summary to the returned initial context and compares the whole refreshed history.

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

async fn process_compacted_history_reinjects_full_initial_context()

Purpose: This async test checks that even a simple compacted history gets the full current initial context added back. This keeps the continuing conversation aligned with the latest environment and instructions.

Data flow: It provides a compacted history containing only a user summary. Processing should produce the fresh initial context followed by that same summary message.

Call relations: The test uses process_compacted_history_with_test_session to exercise the real session-based refresh flow, then builds the expected output from the returned initial context and compares it to the refreshed result.

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

async fn process_compacted_history_drops_non_user_content_messages()

Purpose: This async test checks that generated context-like messages are removed from compacted history before fresh context is added. It prevents old project instructions, environment blocks, aborted-turn notes, and stale developer instructions from being duplicated or reused incorrectly.

Data flow: It feeds in several user-role messages that look like internal session context, one real summary message, and one stale developer message. After processing, only the fresh initial context and the real summary should remain.

Call relations: The test calls process_compacted_history_with_test_session to run the real refresh path. It then builds the expected result by taking the helper’s initial context and adding the summary message.

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

async fn process_compacted_history_drops_legacy_warnings()

Purpose: This async test verifies that old warning messages are discarded during compacted-history refresh. Those warnings are not user requests, so keeping them could confuse the next model turn.

Data flow: It creates three warning messages and one latest real user message. After processing through a test session, the refreshed history should contain the fresh initial context followed only by the latest real user message.

Call relations: The test uses user_message to create the fake messages and calls process_compacted_history_with_test_session to run the full refresh behavior. It compares the final result against initial context plus the one real message.

Call graph: calls 2 internal fn (process_compacted_history_with_test_session, user_message); 2 external calls (assert_eq!, vec!).

async fn process_compacted_history_inserts_context_before_last_real_user_message_only()

Purpose: This async test checks the exact insertion point for fresh context. The system should place current instructions before the latest real user message, not before an older user message or before a summary marker.

Data flow: It starts with an older user message, a summary-prefixed message, and a latest user message. After refresh, the older entries stay first, the fresh initial context is inserted next, and the latest user message remains after that.

Call relations: The test calls process_compacted_history_with_test_session, then constructs the expected sequence by combining hand-written older entries, the returned initial context, and the latest user message.

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

async fn process_compacted_history_reinjects_model_switch_message()

Purpose: This async test checks that a model-switch notice is restored when the previous turn used a different regular model. That notice tells the continuing conversation about the change, which can matter for consistency.

Data flow: It sets previous-turn settings with a model name, processes a compacted summary through a test session, and inspects the fresh initial context. The first context message should be a developer message containing a <model_switch> marker, and the final refreshed history should be that context plus the summary.

Call relations: The test passes previous-turn settings into process_compacted_history_with_test_session. The helper runs the real refresh path, and the test then checks both the model-switch text and the full refreshed history.

Call graph: calls 1 internal fn (process_compacted_history_with_test_session); 4 external calls (assert!, assert_eq!, panic!, vec!).

fn insert_initial_context_before_last_real_user_or_summary_keeps_summary_last()

Purpose: This test checks that inserting fresh initial context does not move a final summary out of its important last position. The summary is meant to close the compacted history, so it should remain at the end.

Data flow: It starts with an older user message, a latest user message, and a summary-prefixed message. It inserts one fresh developer-context message. The expected output places the fresh context before the latest real user message while leaving the summary as the final entry.

Call relations: This direct unit test builds both the compacted history and initial context locally, calls the insertion behavior under test, and compares the result to the exact expected ordering.

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

fn insert_initial_context_before_last_real_user_or_summary_keeps_compaction_last()

Purpose: This test checks that an encrypted compaction record stays last when fresh initial context is inserted. That protects the special compacted payload from being displaced by newly added setup messages.

Data flow: It starts with a history containing only an encrypted compaction item and a fresh developer-context message to insert. The output should put the developer context first and keep the encrypted compaction item last.

Call relations: This direct unit test constructs the two inputs locally, runs the insertion behavior, and verifies the final order with an equality assertion.

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

fn assistant_msg(text: &str) -> ResponseItem

Purpose: Builds a simple assistant message for tests. It saves each test from repeating the full message structure when only the assistant text matters.

Data flow: Text goes in → the helper wraps it as one assistant output-text item → a ResponseItem message comes out.

Call relations: Several tests call this when they need an assistant reply before checking filtering, turn rollback, or legacy inter-agent boundary behavior.

Call graph: called by 3 (drop_last_n_user_turns_treats_inter_agent_assistant_messages_as_instruction_turns, filters_non_api_messages, legacy_inter_agent_assistant_messages_are_not_turn_boundaries); 1 external calls (vec!).

fn inter_agent_assistant_msg(text: &str) -> ResponseItem

Purpose: Builds an assistant message whose text is actually structured inter-agent communication. Tests use it to prove that modern agent-to-agent messages are treated as instruction-like turn boundaries.

Data flow: Plain text goes in → the helper creates an InterAgentCommunication record from root to a worker agent and serializes it as JSON → an assistant message containing that JSON comes out.

Call relations: Boundary and prompt-preservation tests call this, then pass the result into history functions that decide whether it starts a turn or should be kept for the prompt.

Call graph: calls 2 internal fn (root, new); called by 3 (drop_last_n_user_turns_treats_inter_agent_assistant_messages_as_instruction_turns, for_prompt_preserves_inter_agent_assistant_messages, inter_agent_assistant_messages_are_turn_boundaries); 2 external calls (new, vec!).

fn create_history_with_items(items: Vec<ResponseItem>) -> ContextManager

Purpose: Creates a ContextManager already filled with test items. It gives tests a short, consistent way to set up a fake conversation.

Data flow: A list of response items goes in → a new ContextManager records them with a generous token budget → the populated history comes out.

Call relations: Most tests use this as their setup step before calling history methods such as for_prompt, normalize_history, remove_first_item, or drop_last_n_user_turns.

Call graph: calls 1 internal fn (new); called by 38 (drop_last_n_user_turns_clears_reference_context_for_mixed_developer_context_bundles, drop_last_n_user_turns_ignores_session_prefix_user_messages, drop_last_n_user_turns_preserves_prefix, drop_last_n_user_turns_treats_inter_agent_assistant_messages_as_instruction_turns, drop_last_n_user_turns_trims_context_updates_above_rolled_back_turn, estimate_token_count_with_base_instructions_uses_provided_text, for_prompt_clears_image_generation_result_when_images_are_unsupported, for_prompt_preserves_image_generation_calls_when_images_are_supported, for_prompt_preserves_inter_agent_assistant_messages, for_prompt_strips_images_when_model_does_not_support_images (+15 more)); 1 external calls (Tokens).

fn user_msg(text: &str) -> ResponseItem

Purpose: Builds a simple user message using output-text content. It is a compact test fixture for ordinary user turns.

Data flow: Text goes in → the helper wraps it as a user message item → a ResponseItem comes out.

Call relations: Filtering and token-count tests call this to add user content around assistant and tool-output items.

Call graph: called by 3 (filters_non_api_messages, items_after_last_model_generated_tokens_include_user_and_tool_output, total_token_usage_includes_all_items_after_last_model_generated_item); 1 external calls (vec!).

fn user_input_text_msg(text: &str) -> ResponseItem

Purpose: Builds a user message using input-text content, which is the form commonly sent into the model. Tests use it for real user turns and session-prefix items.

Data flow: Text goes in → it becomes one input-text content item inside a user message → a ResponseItem comes out.

Call relations: Rollback tests use this helper when building histories whose user turns, environment blocks, and instruction blocks must be distinguished.

Call graph: called by 1 (drop_last_n_user_turns_treats_inter_agent_assistant_messages_as_instruction_turns); 1 external calls (vec!).

fn developer_msg(text: &str) -> ResponseItem

Purpose: Builds a developer-role message for tests. Developer messages represent instructions from the application rather than the end user.

Data flow: Instruction text goes in → the helper wraps it as developer input text → a ResponseItem message comes out.

Call relations: It supports rollback tests that check whether context-update instructions are retained or removed with nearby turns.

Call graph: 1 external calls (vec!).

fn developer_msg_with_fragments(texts: &[&str]) -> ResponseItem

Purpose: Builds a developer message made of several text fragments. This lets tests model a mixed bundle of instructions instead of one plain string.

Data flow: A slice of text fragments goes in → each fragment becomes an input-text content item → one developer ResponseItem comes out.

Call relations: The mixed developer-context rollback test uses this to check that bundled contextual instructions are treated carefully.

fn reference_context_item() -> TurnContextItem

Purpose: Creates a realistic reference context snapshot for rollback tests. This snapshot describes things like current directory, date, model, approval policy, and sandbox policy.

Data flow: No input is needed → the helper fills a TurnContextItem with stable test values → that context item comes out.

Call relations: Rollback tests set this on the history, then check whether dropping turns keeps or clears the reference context.

Call graph: called by 2 (drop_last_n_user_turns_clears_reference_context_for_mixed_developer_context_bundles, drop_last_n_user_turns_trims_context_updates_above_rolled_back_turn); 2 external calls (from, new_read_only_policy).

fn custom_tool_call_output(call_id: &str, output: &str) -> ResponseItem

Purpose: Builds a custom tool output item with text content. Tests use it to check token accounting after model output.

Data flow: A call id and output text go in → the text is wrapped in a function-output payload → a CustomToolCallOutput item comes out.

Call relations: Token usage tests add this after assistant output to verify that fresh tool results are counted until the next model response.

Call graph: calls 1 internal fn (from_text); called by 2 (items_after_last_model_generated_tokens_include_user_and_tool_output, total_token_usage_includes_all_items_after_last_model_generated_item).

fn reasoning_msg(text: &str) -> ResponseItem

Purpose: Builds a reasoning item with visible reasoning text and a summary. Tests use it to check which non-message items are retained.

Data flow: Reasoning text goes in → the helper creates a reasoning response with a fixed summary and that text → a ResponseItem comes out.

Call relations: The filtering test records this beside ignored items to confirm reasoning is kept in history.

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

fn reasoning_with_encrypted_content(len: usize) -> ResponseItem

Purpose: Builds a reasoning item that has encrypted content instead of visible reasoning text. Tests use it for reasoning-token estimates.

Data flow: A length goes in → the helper creates encrypted content made of repeated characters of that length → a reasoning ResponseItem comes out.

Call relations: Reasoning-token tests use these items around user messages to check what counts before the latest user turn.

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

fn truncate_exec_output(content: &str) -> String

Purpose: Applies the same token-based truncation used for long execution output in tests. It keeps output small while preserving a truncation marker.

Data flow: A command-output string goes in → truncate_text shortens it to the configured token budget if needed → the possibly shortened string comes out.

Call relations: Execution-output tests call this, then use assertion helpers to check the marker, retained head and tail text, and removed-token count.

Call graph: called by 4 (format_exec_output_marks_byte_truncation_without_omitted_lines, format_exec_output_prefers_line_marker_when_both_limits_exceeded, format_exec_output_reports_omitted_lines_and_keeps_head_and_tail, format_exec_output_truncates_large_error); 2 external calls (truncate_text, Tokens).

fn approx_token_count_for_text(text: &str) -> i64

Purpose: Provides a simple estimate of token count from text length. A token is roughly a chunk of text the model counts for its context limit.

Data flow: Text goes in → its byte length is rounded up by groups of four → an integer estimate comes out.

Call relations: The base-instructions token-estimate test uses this helper to predict the expected difference between short and long instruction text.

Call graph: called by 1 (estimate_token_count_with_base_instructions_uses_provided_text); 1 external calls (try_from).

fn filters_non_api_messages()

Purpose: Checks that the history ignores items that should not be sent as API messages, while keeping useful reasoning, user, and assistant items.

Data flow: The test records a system message, reasoning item, Other item, user message, and assistant message → it reads raw history → it expects only reasoning, user, and assistant items to remain.

Call relations: The Rust test runner calls this; it uses the message helpers to exercise ContextManager::record_items.

Call graph: calls 3 internal fn (assistant_msg, reasoning_msg, user_msg); 4 external calls (assert_eq!, default, Tokens, vec!).

fn non_last_reasoning_tokens_return_zero_when_no_user_messages()

Purpose: Checks that old reasoning-token accounting returns zero when there has not been any user message yet.

Data flow: A history containing only encrypted reasoning goes in → the token counter is queried → zero is expected.

Call relations: The test runner calls it; it sets up history through create_history_with_items and then checks get_non_last_reasoning_items_tokens.

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

fn non_last_reasoning_tokens_ignore_entries_after_last_user()

Purpose: Checks that reasoning after the latest user turn is not counted as older reasoning. This avoids double-counting recent model work.

Data flow: A sequence of reasoning and user messages goes into history → the counter looks only before the last user boundary → the expected token total comes out.

Call relations: The test runner calls it; it relies on create_history_with_items to feed the ContextManager a controlled sequence.

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

fn items_after_last_model_generated_tokens_include_user_and_tool_output()

Purpose: Checks that items added after the latest model-generated response include both user messages and tool outputs for local token estimates.

Data flow: A history with assistant output, then user text and tool output, is built → items after the assistant output are gathered and estimated → their sum must match the expected estimate.

Call relations: The test runner calls it; it combines user_msg and custom_tool_call_output with ContextManager::items_after_last_model_generated_item.

Call graph: calls 3 internal fn (create_history_with_items, custom_tool_call_output, user_msg); 2 external calls (assert_eq!, vec!).

fn items_after_last_model_generated_tokens_are_zero_without_model_generated_items()

Purpose: Checks that no tail-token estimate is added before the model has produced anything. Without a model-generated marker, there is no previous API total to extend.

Data flow: A history with only a user message is built → items after the last model-generated item are requested → the estimated sum is zero.

Call relations: The test runner calls it; create_history_with_items supplies the single-message history.

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

fn inter_agent_assistant_messages_are_turn_boundaries()

Purpose: Checks that modern structured inter-agent assistant messages count as turn boundaries. This matters when one agent triggers another agent’s turn.

Data flow: A structured inter-agent assistant message is built → is_user_turn_boundary examines it → true is expected.

Call relations: The test runner calls it; it depends on inter_agent_assistant_msg to produce the exact structured message format.

Call graph: calls 1 internal fn (inter_agent_assistant_msg); 1 external calls (assert!).

fn for_prompt_preserves_inter_agent_assistant_messages()

Purpose: Checks that structured inter-agent assistant messages are not lost when preparing the prompt. They carry instructions between agents.

Data flow: An inter-agent item goes into history → raw_items and for_prompt are read → both should contain the same item.

Call relations: The test runner calls it; it uses create_history_with_items and then exercises ContextManager::for_prompt.

Call graph: calls 2 internal fn (create_history_with_items, inter_agent_assistant_msg); 2 external calls (assert_eq!, vec!).

fn drop_last_n_user_turns_treats_inter_agent_assistant_messages_as_instruction_turns()

Purpose: Checks rollback behavior when an inter-agent assistant message starts a worker turn. Dropping one user-like turn should remove that worker turn but keep earlier conversation.

Data flow: A normal turn plus an inter-agent-triggered turn go into history → one user turn is dropped → only the first turn remains.

Call relations: The test runner calls it; it uses assistant_msg, user_input_text_msg, and inter_agent_assistant_msg to build the scenario.

Call graph: calls 4 internal fn (assistant_msg, create_history_with_items, inter_agent_assistant_msg, user_input_text_msg); 2 external calls (assert_eq!, vec!).

fn legacy_inter_agent_assistant_messages_are_not_turn_boundaries()

Purpose: Checks that old plain-text inter-agent-looking messages are not mistaken for modern structured turn boundaries.

Data flow: A legacy formatted assistant string goes into is_user_turn_boundary → the result should be false.

Call relations: The test runner calls it; assistant_msg supplies the legacy-looking text without the structured JSON wrapper.

Call graph: calls 1 internal fn (assistant_msg); 1 external calls (assert!).

fn total_token_usage_includes_all_items_after_last_model_generated_item()

Purpose: Checks that total token usage combines the server-reported total with locally estimated items added afterward.

Data flow: A history starts with counted assistant output and server token usage → user and tool output are recorded later → total usage should equal server total plus those new estimates.

Call relations: The test runner calls it; it uses create_history_with_items, user_msg, and custom_tool_call_output before querying ContextManager::get_total_token_usage.

Call graph: calls 3 internal fn (create_history_with_items, custom_tool_call_output, user_msg); 4 external calls (default, assert_eq!, Tokens, vec!).

fn for_prompt_strips_images_when_model_does_not_support_images()

Purpose: Checks that image content is replaced with clear text placeholders for text-only models, while image-capable models keep images.

Data flow: Messages and tool outputs containing images go into history → for_prompt is called with text-only modalities → image parts become explanatory text; with image modalities they remain images.

Call relations: The test runner calls it; it uses create_history_with_items and default_input_modalities to compare unsupported and supported model behavior.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 4 external calls (assert!, assert_eq!, panic!, vec!).

fn for_prompt_preserves_image_generation_calls_when_images_are_supported()

Purpose: Checks that image generation results remain in the prompt when the model supports image input.

Data flow: An image-generation call and user message go into history → for_prompt runs with default image-capable modalities → the image-generation call is preserved unchanged.

Call relations: The test runner calls it; create_history_with_items supplies the history under test.

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

fn for_prompt_clears_image_generation_result_when_images_are_unsupported()

Purpose: Checks that a text-only model does not receive raw generated image data. The call metadata stays, but the image result is cleared.

Data flow: A user request and completed image-generation call go into history → for_prompt runs with text-only input → the result field becomes an empty string.

Call relations: The test runner calls it; it verifies ContextManager::for_prompt’s image-safety behavior.

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

fn estimate_token_count_with_base_instructions_uses_provided_text()

Purpose: Checks that token estimates include the actual base instruction text supplied by the caller.

Data flow: The same history is estimated once with short base instructions and once with long ones → the difference is compared with the helper’s text-token estimate.

Call relations: The test runner calls it; it uses approx_token_count_for_text to calculate the expected change.

Call graph: calls 2 internal fn (approx_token_count_for_text, create_history_with_items); 2 external calls (assert_eq!, vec!).

fn remove_first_item_removes_matching_output_for_function_call()

Purpose: Checks that removing a function call also removes its matching output. A tool call without its answer would leave history inconsistent.

Data flow: A function call followed by its output goes into history → remove_first_item is called → both items are gone.

Call relations: The test runner calls it; create_history_with_items sets up the paired call and output.

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

fn remove_first_item_removes_matching_call_for_output()

Purpose: Checks the reverse pairing rule: if the first item is a function output, its matching call is removed too.

Data flow: An output followed by its matching call goes into history → remove_first_item runs → history becomes empty.

Call relations: The test runner calls it; this protects bidirectional cleanup in ContextManager::remove_first_item.

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

fn replace_last_turn_images_replaces_tool_output_images()

Purpose: Checks that invalid images in the latest tool output can be replaced with text. This prevents repeatedly sending broken image data.

Data flow: A user turn and tool output containing an image go into history → replace_last_turn_images runs with replacement text → the tool image becomes text and the function returns true.

Call relations: The test runner calls it; it exercises image replacement on FunctionCallOutput content.

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

fn replace_last_turn_images_does_not_touch_user_images()

Purpose: Checks that the replacement routine does not modify images originally provided by the user.

Data flow: A user image goes into history → replace_last_turn_images is called → it returns false and the history stays unchanged.

Call relations: The test runner calls it; it guards the boundary between user-provided content and generated tool-output content.

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

fn remove_first_item_handles_local_shell_pair()

Purpose: Checks that local shell calls are cleaned up together with their output. A shell command and its result are another form of call-and-answer pair.

Data flow: A local shell call and matching function output go into history → remove_first_item runs → both are removed.

Call relations: The test runner calls it; create_history_with_items builds the shell-call pair.

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

fn drop_last_n_user_turns_preserves_prefix()

Purpose: Checks that rollback removes recent user turns but keeps session-prefix material that came before the first real user turn.

Data flow: A prefix assistant item and two turns go into history → dropping one or many turns removes only real turns after the prefix → the expected prefix or earlier turn remains.

Call relations: The test runner calls it; it prepares history and reads it back through for_prompt.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn drop_last_n_user_turns_ignores_session_prefix_user_messages()

Purpose: Checks that setup-style user messages, such as environment context and instruction blocks, are not counted as user turns during rollback.

Data flow: Several prefix user messages and two real turns go into history → one, two, or three turns are dropped → prefix messages remain and only real turns are removed.

Call relations: The test runner calls it; it uses create_history_with_items and default_input_modalities to inspect the final prompt.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn drop_last_n_user_turns_trims_context_updates_above_rolled_back_turn()

Purpose: Checks that context updates attached to a rolled-back turn are removed, while older persistent developer instructions can remain.

Data flow: A history with an old turn, developer instruction, context-diff messages, and a later turn is built → one turn is dropped → the old turn and safe developer instruction remain.

Call relations: The test runner calls it; reference_context_item is used to verify the stored reference context is still retained.

Call graph: calls 3 internal fn (create_history_with_items, reference_context_item, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn drop_last_n_user_turns_clears_reference_context_for_mixed_developer_context_bundles()

Purpose: Checks a conservative rollback case where contextual and persistent developer instructions are bundled together. Because the bundle is mixed, the reference context is cleared.

Data flow: A history with a mixed developer message, context update, and later turn is built → one turn is dropped → the mixed bundle is removed and reference context becomes none.

Call relations: The test runner calls it; it uses developer_msg_with_fragments indirectly through the scenario and reference_context_item for the stored context.

Call graph: calls 3 internal fn (create_history_with_items, reference_context_item, default_input_modalities); 3 external calls (assert!, assert_eq!, vec!).

fn remove_first_item_handles_custom_tool_pair()

Purpose: Checks that custom tool calls and their outputs are removed as a pair.

Data flow: A custom tool call and matching output go into history → remove_first_item runs → history becomes empty.

Call relations: The test runner calls it; it covers the custom-tool version of the call-and-answer cleanup rule.

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

fn normalization_retains_local_shell_outputs()

Purpose: Checks that normalization does not accidentally discard valid local shell outputs.

Data flow: A completed shell call and matching output go into history → for_prompt normalizes the prompt view → the same items come back.

Call relations: The test runner calls it; create_history_with_items and default_input_modalities prepare the prompt check.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn record_items_truncates_function_call_output_content()

Purpose: Checks that very long function-call output is shortened when recorded. This prevents tool output from filling the model’s context window.

Data flow: A huge function output goes into record_items with a small token budget → stored output is shorter and includes a truncation marker → metadata such as turn id is preserved.

Call relations: The test runner calls it; it directly creates a ContextManager and tests ContextManager::record_items.

Call graph: calls 1 internal fn (new); 6 external calls (assert!, assert_eq!, assert_ne!, panic!, Text, Tokens).

fn record_items_truncates_custom_tool_call_output_content()

Purpose: Checks that custom tool outputs get the same truncation treatment as standard function outputs.

Data flow: A huge custom tool output is recorded → the stored text differs from the original and contains a truncation marker → the item remains a custom tool output.

Call relations: The test runner calls it; it uses FunctionCallOutputPayload::from_text while exercising record_items.

Call graph: calls 2 internal fn (new, from_text); 5 external calls (assert!, assert_eq!, assert_ne!, panic!, Tokens).

fn record_items_respects_custom_token_limit()

Purpose: Checks that the caller’s token limit is honored during output truncation.

Data flow: A long function output and a very small token policy go into record_items → the stored output contains a token-truncation marker.

Call relations: The test runner calls it; it directly verifies ContextManager::record_items with a custom TruncationPolicy.

Call graph: calls 1 internal fn (new); 4 external calls (assert!, panic!, Text, Tokens).

fn assert_truncated_message_matches(message: &str, line: &str, expected_removed: usize)

Purpose: Asserts that a truncated output string has the expected shape and removed-token count. It keeps the truncation tests readable.

Data flow: A message, expected starting line, and expected removed count go in → a regular expression extracts the kept body and removed count → assertions confirm size and count.

Call relations: Execution-output tests call this after truncate_exec_output; it delegates pattern construction to truncated_message_pattern.

Call graph: calls 1 internal fn (truncated_message_pattern); called by 4 (format_exec_output_marks_byte_truncation_without_omitted_lines, format_exec_output_prefers_line_marker_when_both_limits_exceeded, format_exec_output_reports_omitted_lines_and_keeps_head_and_tail, format_exec_output_truncates_large_error); 3 external calls (new, assert!, assert_eq!).

fn truncated_message_pattern(line: &str) -> String

Purpose: Builds the regular expression used to recognize a truncation marker. It escapes the expected line so test text is treated literally.

Data flow: An expected line prefix goes in → it is escaped and inserted into a pattern with named body and removed-count captures → the pattern string comes out.

Call relations: assert_truncated_message_matches calls this before compiling the regular expression.

Call graph: called by 1 (assert_truncated_message_matches); 2 external calls (format!, escape).

fn format_exec_output_truncates_large_error()

Purpose: Checks that very large error output is shortened and reports the expected number of removed tokens.

Data flow: A repeated long error string is passed through truncate_exec_output → the result is compared with the original and checked against the truncation pattern.

Call relations: The test runner calls it; it uses assert_truncated_message_matches for the detailed checks.

Call graph: calls 2 internal fn (assert_truncated_message_matches, truncate_exec_output); 1 external calls (assert_ne!).

fn format_exec_output_marks_byte_truncation_without_omitted_lines()

Purpose: Checks that one extremely long line is truncated without claiming that whole lines were omitted.

Data flow: A single overlarge line goes into truncate_exec_output → the shortened result is checked for a token marker and absence of an omitted-lines marker.

Call relations: The test runner calls it; assert_truncated_message_matches verifies the common truncation format.

Call graph: calls 2 internal fn (assert_truncated_message_matches, truncate_exec_output); 2 external calls (assert!, assert_ne!).

fn format_exec_output_returns_original_when_within_limits()

Purpose: Checks that small command output is not changed. Truncation should only happen when needed.

Data flow: A short repeated output string is prepared → truncation behavior is checked by comparing expected original text with the result.

Call relations: The test runner calls it; this is the non-truncating counterpart to the large-output tests.

Call graph: 1 external calls (assert_eq!).

fn format_exec_output_reports_omitted_lines_and_keeps_head_and_tail()

Purpose: Checks that long multi-line output keeps useful beginning and ending context while marking that content was removed.

Data flow: Many generated lines go into truncate_exec_output → the result is checked for the first line, last line, and expected truncation marker.

Call relations: The test runner calls it; it uses assert_truncated_message_matches to validate the marker and count.

Call graph: calls 2 internal fn (assert_truncated_message_matches, truncate_exec_output); 2 external calls (assert!, format!).

fn format_exec_output_prefers_line_marker_when_both_limits_exceeded()

Purpose: Checks the marker choice when both line count and byte size are too large. The test expects the line-oriented truncation path to win.

Data flow: Many long lines go into truncate_exec_output → the truncated string is checked against the expected removed-token count.

Call relations: The test runner calls it; assert_truncated_message_matches performs the final validation.

Call graph: calls 2 internal fn (assert_truncated_message_matches, truncate_exec_output).

fn normalize_adds_missing_output_for_function_call()

Purpose: Checks release-build normalization for a function call missing its output. The history should be repaired by adding an aborted output.

Data flow: A lone function call goes into history → normalize_history runs → a matching FunctionCallOutput with text "aborted" is inserted.

Call relations: The test runner calls it only in non-debug builds; it uses create_history_with_items and default_input_modalities.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn normalize_adds_missing_output_for_custom_tool_call()

Purpose: Checks release-build normalization for a custom tool call missing its output.

Data flow: A lone custom tool call goes into history → normalize_history runs → a matching CustomToolCallOutput with "aborted" is inserted.

Call relations: The test runner calls it in non-debug builds; it covers repair behavior for custom tools.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn normalize_adds_missing_output_for_local_shell_call_with_id()

Purpose: Checks release-build normalization for a local shell call that has a call id but no output.

Data flow: A lone shell call goes into history → normalize_history runs → a matching function output marked "aborted" is added.

Call relations: The test runner calls it in non-debug builds; it covers shell calls as another call/output pair.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn normalize_removes_orphan_function_call_output()

Purpose: Checks release-build normalization for a function output that has no matching call.

Data flow: An orphan function output goes into history → normalize_history runs → the orphan is removed.

Call relations: The test runner calls it in non-debug builds; it verifies cleanup of unmatched outputs.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn normalize_removes_orphan_custom_tool_call_output()

Purpose: Checks release-build normalization for a custom tool output without a matching custom tool call.

Data flow: An orphan custom tool output goes into history → normalize_history runs → history becomes empty.

Call relations: The test runner calls it in non-debug builds; it is the custom-tool counterpart to orphan function-output cleanup.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn normalize_mixed_inserts_and_removals()

Purpose: Checks that normalization can repair several problems in one history: missing outputs are inserted and orphan outputs are removed.

Data flow: A mixed sequence of incomplete calls and orphan output goes into history → normalize_history runs → the final history contains repaired call/output pairs only.

Call relations: The test runner calls it in non-debug builds; it exercises the normalization pass as a whole.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn normalize_adds_missing_output_for_function_call_inserts_output()

Purpose: Checks that a missing standard function-call output is inserted. This version runs regardless of debug configuration.

Data flow: A single function call goes into history → normalize_history runs → a matching aborted output appears after it.

Call relations: The test runner calls it; it confirms the standard function-call repair path.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn normalize_adds_missing_output_for_tool_search_call()

Purpose: Checks that a client-side tool search call missing its output is repaired with an empty completed search output.

Data flow: A ToolSearchCall with a call id goes into history → normalize_history runs → a ToolSearchOutput with matching id, completed status, client execution, and no tools is inserted.

Call relations: The test runner calls it; it extends call/output normalization to tool search.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn normalize_adds_missing_output_for_custom_tool_call_panics_in_debug()

Purpose: Checks that debug builds panic when a custom tool call is missing its output. Debug mode catches developer mistakes loudly instead of silently repairing them.

Data flow: A lone custom tool call goes into history → normalize_history is called → the test expects a panic.

Call relations: The test runner calls it only in debug builds; it uses create_history_with_items for setup.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 1 external calls (vec!).

fn normalize_adds_missing_output_for_local_shell_call_with_id_panics_in_debug()

Purpose: Checks that debug builds panic when a local shell call with an id lacks an output.

Data flow: A lone shell call goes into history → normalize_history runs → the expected result is a panic.

Call relations: The test runner calls it in debug builds; it protects the shell-call pairing invariant during development.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 1 external calls (vec!).

fn normalize_removes_orphan_function_call_output_panics_in_debug()

Purpose: Checks that debug builds panic on an orphan function output.

Data flow: An unmatched function output goes into history → normalize_history is called → the test expects a panic.

Call relations: The test runner calls it in debug builds; it catches broken call/output ordering early.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 1 external calls (vec!).

fn normalize_removes_orphan_custom_tool_call_output_panics_in_debug()

Purpose: Checks that debug builds panic on an orphan custom tool output.

Data flow: An unmatched custom tool output goes into history → normalize_history is called → a panic is expected.

Call relations: The test runner calls it in debug builds; it mirrors the standard function-output panic case.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 1 external calls (vec!).

fn normalize_removes_orphan_client_tool_search_output()

Purpose: Checks release-build cleanup of a client tool-search output that has no matching search call.

Data flow: An orphan client ToolSearchOutput goes into history → normalize_history runs → it is removed.

Call relations: The test runner calls it in non-debug builds; it covers orphan cleanup for client-side search.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn normalize_removes_orphan_client_tool_search_output_panics_in_debug()

Purpose: Checks that debug builds panic on an orphan client tool-search output.

Data flow: An unmatched client ToolSearchOutput goes into history → normalize_history is called → the test expects a panic.

Call relations: The test runner calls it in debug builds; it is the debug counterpart of release cleanup.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 1 external calls (vec!).

fn normalize_keeps_server_tool_search_output_without_matching_call()

Purpose: Checks that server-side tool-search output can stand alone. Server execution may produce outputs without a local client call.

Data flow: A server ToolSearchOutput without a matching call goes into history → normalize_history runs → the output remains unchanged.

Call relations: The test runner calls it; it verifies that normalization treats server and client tool-search outputs differently.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 2 external calls (assert_eq!, vec!).

fn normalize_mixed_inserts_and_removals_panics_in_debug()

Purpose: Checks that debug builds panic on a history containing multiple normalization problems.

Data flow: A mixed broken history goes into ContextManager → normalize_history is called → the expected result is a panic.

Call relations: The test runner calls it in debug builds; it is the debug counterpart of the mixed repair test.

Call graph: calls 2 internal fn (create_history_with_items, default_input_modalities); 1 external calls (vec!).

fn image_data_url_payload_does_not_dominate_message_estimate()

Purpose: Checks that huge inline base64 image data in a user message is estimated as a fixed resized-image cost instead of raw string size.

Data flow: A message with a large data URL is serialized and estimated → the estimate subtracts the payload and adds a fixed image cost → it is smaller than raw JSON but larger than text-only.

Call relations: The test runner calls it; it directly tests estimate_response_item_model_visible_bytes.

Call graph: 5 external calls (assert!, assert_eq!, format!, to_string, vec!).

fn image_data_url_payload_does_not_dominate_function_call_output_estimate()

Purpose: Checks the same inline-image estimate rule for standard function-call outputs.

Data flow: A function output with text plus a large base64 image goes in → raw JSON length and model-visible estimate are compared → the payload is replaced by fixed image cost.

Call relations: The test runner calls it; FunctionCallOutputPayload::from_content_items builds the image-bearing output.

Call graph: calls 1 internal fn (from_content_items); 5 external calls (assert!, assert_eq!, format!, to_string, vec!).

fn image_data_url_payload_does_not_dominate_custom_tool_call_output_estimate()

Purpose: Checks that custom tool outputs also avoid counting huge inline image payloads at full size.

Data flow: A custom tool output with a large data URL is estimated → the raw payload length is replaced with a fixed image estimate → the estimate is below raw JSON length.

Call relations: The test runner calls it; it covers the custom-tool output variant of image estimation.

Call graph: calls 1 internal fn (from_content_items); 5 external calls (assert!, assert_eq!, format!, to_string, vec!).

fn non_base64_image_urls_are_unchanged()

Purpose: Checks that ordinary image URLs, such as web or file URLs, are not adjusted by the inline base64-image heuristic.

Data flow: Message and function-output items with non-base64 image URLs are estimated → each estimate equals its serialized JSON length.

Call relations: The test runner calls it; it verifies the estimator only special-cases inline base64 image data.

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