RPC request routing

fn deserialize_client_request(
    request: &JSONRPCRequest,
) -> Result<ClientRequest, JSONRPCErrorError>

Purpose: Turns a raw JSON-RPC request into the project’s typed ClientRequest form. This gives the rest of the server a safe, known shape to work with instead of loose JSON.

Data flow: It receives a raw request object. It first converts it to JSON data, then tries to parse that JSON as a known client request. If parsing works, it returns the typed request; if not, it returns an “invalid request” error that can be sent back to the client.

Call relations: When MessageProcessor::process_request receives a JSON-RPC message, it calls this function before any real work begins. A successful result is passed into the shared request handler; a failed result is turned into a client error response.

Call graph: called by 1 (process_request); 1 external calls (to_value).

fn map_reason(reason: ExternalAuthRefreshReason) -> ChatgptAuthTokensRefreshReason

Purpose: Converts the login system’s reason for refreshing authentication into the protocol reason that can be sent to the client. Right now, it maps an unauthorized-token case into the matching client-facing reason.

Data flow: It receives an internal refresh reason. It matches that reason to the equivalent app-server protocol value and returns it.

Call relations: The auth refresh bridge uses this before it asks the client for new tokens, so both sides speak the same protocol language.

fn auth_mode(&self) -> LoginAuthMode

Purpose: Reports that this external authentication bridge is for ChatGPT authentication. The login system can use this to know what kind of tokens it should expect.

Data flow: It reads no outside data. It returns the fixed authentication mode value for ChatGPT.

Call relations: This is part of the ExternalAuth interface used by the login manager after MessageProcessor::new installs the bridge.

fn refresh(
        &self,
        context: ExternalAuthRefreshContext,
    ) -> codex_login::ExternalAuthFuture<'_, ExternalAuthTokens>

Purpose: Asks the connected client to provide fresh ChatGPT authentication tokens. This lets the server recover when tokens expire or are rejected, without doing the refresh itself.

Data flow: It receives a refresh context, including why refresh is needed and the previous account id. It sends a token-refresh request to the client, waits up to a fixed timeout, converts any response JSON into token data, and returns fresh external auth tokens. If the client does not answer, cancels, or returns an error, it returns an I/O error.

Call relations: The login manager calls this through the ExternalAuth interface when it needs refreshed credentials. It sends the request through OutgoingMessageSender, then hands the resulting tokens back to the login flow.

Call graph: calls 1 internal fn (chatgpt); 7 external calls (pin, map_reason, ChatgptAuthTokensRefresh, other, format!, from_value, timeout).

fn default() -> Self

Purpose: Creates a fresh connection session state using the normal defaults. This supports standard Rust default construction while keeping all setup in one place.

Data flow: It receives no input. It calls the normal constructor and returns a new uninitialized session state.

Call relations: Code that needs a default session can use this instead of calling ConnectionSessionState::new directly.

Call graph: 1 external calls (new).

fn new() -> Self

Purpose: Creates the per-connection record used to track initialization and request shutdown. Every client connection gets one of these so the server can remember what that client is allowed to do.

Data flow: It receives no input. It creates a new RPC gate, which is a guard used to stop or drain in-flight remote calls, and an empty one-time initialization slot. It returns the new session state.

Call relations: Startup and connection setup code call this when a new connection begins. Later request-handling code reads and updates this state.

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

fn initialized(&self) -> bool

Purpose: Answers whether this connection has completed the required initialize step. The server uses this to reject normal requests that arrive too early.

Data flow: It reads the session’s one-time initialization slot. It returns true if that slot has been filled, otherwise false.

Call relations: MessageProcessor::dispatch_initialized_client_request uses this gate before sending requests to feature processors.

Call graph: called by 1 (initialize); 1 external calls (get).

fn experimental_api_enabled(&self) -> bool

Purpose: Answers whether this client opted into experimental API calls. Experimental calls are blocked unless this returns true.

Data flow: It reads the initialized session data, if present. It returns the stored experimental flag, or false if the connection was never initialized.

Call relations: The initialized request dispatcher checks this when a request says it needs an experimental API.

Call graph: 1 external calls (get).

fn opted_out_notification_methods(&self) -> HashSet<String>

Purpose: Returns the notification method names that this client does not want to receive. This helps the server avoid sending unwanted notification types.

Data flow: It reads the initialized session data. If present, it clones and returns the stored set of method names; if not, it returns an empty set.

Call relations: Other connection and outgoing-message code can use this session setting after initialization.

Call graph: 1 external calls (get).

fn app_server_client_name(&self) -> Option<&str>

Purpose: Returns the client application name that was provided during initialization. This is useful for logging, tracing, and feature behavior that depends on the calling client.

Data flow: It reads the initialized session data. It returns the client name as text if initialization happened, or no value if it did not.

Call relations: Tracing and request dispatch use this value to label requests and to pass client identity to processors such as remote control or thread handling.

Call graph: called by 2 (client_name, typed_request_span); 1 external calls (get).

fn client_version(&self) -> Option<&str>

Purpose: Returns the client version supplied during initialization. This helps the server understand which client build is talking to it.

Data flow: It reads the initialized session data. It returns the version text if present, or no value before initialization.

Call relations: Tracing and some request processors receive this value so thread and turn activity can be associated with the client version.

Call graph: called by 2 (client_version, typed_request_span); 1 external calls (get).

fn request_attestation(&self) -> bool

Purpose: Answers whether this client requested attestation, which is a proof-like check about the running app environment. The server uses this when enabling connection capabilities.

Data flow: It reads the initialized session data. It returns the stored attestation flag, or false if the connection is not initialized.

Call relations: After initialization, MessageProcessor::handle_client_request and MessageProcessor::connection_initialized pass this capability to the thread processor.

Call graph: 1 external calls (get).

fn initialize(&self, session: InitializedConnectionSessionState) -> Result<(), ()>

Purpose: Stores the finalized initialization information for a connection. It is intentionally one-time only, so a connection cannot silently change its identity or feature permissions later.

Data flow: It receives an initialized session record. It tries to place that record into the session’s one-time slot. It returns success if the slot was empty, or failure if initialization had already happened.

Call relations: The initialize request processor calls this during the client’s initialize request. Later session-checking methods read the stored values.

Call graph: called by 1 (initialize); 1 external calls (set).

fn new(args: MessageProcessorArgs) -> Self

Purpose: Builds the main message processor and all of the specialized processors it delegates to. This is the server’s wiring step: it connects configuration, authentication, thread state, plugins, file watching, analytics, and outgoing messages.

Data flow: It receives a large bundle of shared services and startup settings. It installs the external auth refresh bridge, creates core thread and environment services, builds each request processor with the dependencies it needs, optionally starts plugin warmup work, and returns a fully ready MessageProcessor.

Call relations: Server startup paths call this before requests can be handled. The object it returns is then used by JSON-RPC transports and in-process clients to process requests, responses, notifications, and connection shutdown.

Call graph: calls 27 internal fn (new, new, new, new, new, new, new, new, new, new (+15 more)); called by 4 (start_uninitialized, build_test_processor, run_main_with_transport_options, run_main); 11 external calls (clone, new, new_cyclic, new, new, new, new, default, default, thread_store_from_config (+1 more)).

fn clear_runtime_references(&self)

Purpose: Breaks selected runtime links during cleanup. This helps long-lived components stop holding references to authentication and background watchers after the processor is no longer active.

Data flow: It reads the stored account, apps, and skills watcher processors. It clears external auth from the account processor and asks the apps and skills watchers to shut down.

Call relations: Shutdown or test cleanup code can call this when the processor should release background/runtime resources.

Call graph: calls 2 internal fn (clear_external_auth, shutdown).

async fn process_request(
        self: &Arc<Self>,
        connection_id: ConnectionId,
        request: JSONRPCRequest,
        transport: &AppServerTransport,
        session: Arc<ConnectionSession

Purpose: Processes a raw JSON-RPC request received over a transport such as a websocket. It adds tracing, turns JSON into a typed request, and sends errors back if anything fails.

Data flow: It receives the connection id, raw request, transport information, and session state. It builds a connection-scoped request id and tracing context, deserializes the request, runs the shared request handler, and sends an error response if the request cannot be parsed or handled.

Call relations: This is the JSON transport entry point into the processor. It calls deserialize_client_request, then delegates valid requests to MessageProcessor::handle_client_request inside MessageProcessor::run_request_with_context.

Call graph: calls 4 internal fn (request_span, handle_client_request, deserialize_client_request, new); 3 external calls (clone, run_request_with_context, trace!).

async fn process_client_request(
        self: &Arc<Self>,
        connection_id: ConnectionId,
        request: ClientRequest,
        session: Arc<ConnectionSessionState>,
        outbound_initializ

Purpose: Processes an already-typed request from an in-process client. This skips JSON parsing but otherwise follows the same rules as network requests.

Data flow: It receives a connection id, typed request, session state, and a flag used to mark outgoing messages as ready after initialization. It builds request identity and tracing information, calls the shared handler, and sends an error response if handling fails.

Call relations: In-process embedders use this instead of process_request. It still delegates to MessageProcessor::handle_client_request so behavior stays consistent across client types.

Call graph: calls 3 internal fn (typed_request_span, handle_client_request, new); 4 external calls (clone, id, run_request_with_context, trace!).

async fn process_notification(&self, notification: JSONRPCNotification)

Purpose: Receives a raw JSON-RPC notification from a client and logs it. The server currently does not expect clients to send notifications here.

Data flow: It receives a notification object. It writes an informational log entry and makes no other state changes.

Call relations: Transport code can call this when a notification arrives. Since notifications are not part of the expected client protocol, it does not delegate further.

Call graph: 1 external calls (info!).

async fn process_client_notification(&self, notification: ClientNotification)

Purpose: Receives a typed notification from an in-process client and logs it. This mirrors the raw notification path for clients that do not use JSON.

Data flow: It receives a typed client notification. It records it in the logs and returns without changing server state.

Call relations: In-process client code can call this when it has a notification. Like process_notification, it does not hand the message to a feature processor.

Call graph: 1 external calls (info!).

async fn run_request_with_context(
        outgoing: Arc<OutgoingMessageSender>,
        request_context: RequestContext,
        request_fut: F,
    )

Purpose: Runs a request while registering its context for outgoing messages and tracing. This makes logs and responses easier to connect back to the original request.

Data flow: It receives the outgoing message sender, a request context, and the future that performs the request work. It registers the context, runs the future inside the tracing span, and produces no direct response itself.

Call relations: process_request and process_client_request wrap their request handling with this helper before calling deeper request logic.

Call graph: calls 1 internal fn (span); 2 external calls (instrument, clone).

fn thread_created_receiver(&self) -> broadcast::Receiver<ThreadId>

Purpose: Provides a subscription channel that reports when new threads are created. Other parts of the server can listen for thread creation without owning the thread processor.

Data flow: It reads the thread processor and asks it for a receiver. It returns that receiver to the caller.

Call relations: Code that needs thread-created events calls this on the message processor, which forwards the request to the thread processor.

Call graph: calls 1 internal fn (thread_created_receiver).

async fn send_initialize_notifications_to_connection(
        &self,
        connection_id: ConnectionId,
    )

Purpose: Sends the startup notifications that belong to one specific connection. This is used after a client initializes so it receives the current server state.

Data flow: It receives a connection id. It asks the initialize processor to send initialization notifications only to that connection.

Call relations: Connection setup code calls this around the initialize flow. The work is delegated to the initialize processor.

Call graph: calls 1 internal fn (send_initialize_notifications_to_connection).

async fn connection_initialized(
        &self,
        connection_id: ConnectionId,
        request_attestation: bool,
    )

Purpose: Tells the thread processor that a connection has finished initialization and what capabilities it has. This lets thread-related notifications and behavior become active for that connection.

Data flow: It receives a connection id and whether attestation is requested. It builds a connection capabilities record and passes it to the thread processor.

Call relations: Connection lifecycle code can call this after initialization. The same capability update also happens from handle_client_request when an initialize request completes.

Call graph: calls 1 internal fn (connection_initialized).

async fn send_initialize_notifications(&self)

Purpose: Sends initialization-related notifications broadly, not just to one connection. This is useful when global initial state needs to be pushed out.

Data flow: It reads the initialize processor and asks it to send its notifications. It returns after that asynchronous work completes.

Call relations: Startup or connection orchestration code calls this, and the initialize processor does the actual notification sending.

Call graph: calls 1 internal fn (send_initialize_notifications).

async fn try_attach_thread_listener(
        &self,
        thread_id: ThreadId,
        connection_ids: Vec<ConnectionId>,
    )

Purpose: Attempts to attach one or more connections as listeners to a thread. This is how clients can start receiving updates for a thread they care about.

Data flow: It receives a thread id and a list of connection ids. It passes both to the thread processor, which decides whether and how to attach the listeners.

Call relations: Connection orchestration uses this when restoring or setting up thread subscriptions. The message processor simply forwards the request to the thread processor.

Call graph: calls 1 internal fn (try_attach_thread_listener).

async fn drain_background_tasks(&self)

Purpose: Waits for thread-related background work to settle. This is useful during shutdown or tests so work does not keep running unexpectedly.

Data flow: It reads the thread processor and awaits its background-task drain operation. It returns when the thread processor reports completion.

Call relations: Shutdown and test flows call this through the message processor, which delegates to the thread processor.

Call graph: calls 1 internal fn (drain_background_tasks).

async fn cancel_active_login(&self)

Purpose: Cancels any login flow that is currently in progress. This prevents an abandoned login attempt from continuing after the user or connection no longer needs it.

Data flow: It reads the account processor and asks it to cancel the active login operation. It returns once cancellation has been requested or completed.

Call relations: Connection or app shutdown code can call this. The actual login state lives in the account processor.

Call graph: calls 1 internal fn (cancel_active_login).

async fn clear_all_thread_listeners(&self)

Purpose: Removes all registered thread listeners. This is a cleanup tool for stopping thread updates from being sent to stale connections.

Data flow: It reads the thread processor and asks it to clear every listener registration. It returns when that cleanup finishes.

Call relations: Lifecycle cleanup code calls this through the message processor, which delegates to the thread processor.

Call graph: calls 1 internal fn (clear_all_thread_listeners).

async fn shutdown_threads(&self)

Purpose: Shuts down active thread work. This helps the server stop conversations and related background processing cleanly.

Data flow: It reads the thread processor and awaits its shutdown operation. It returns once the thread processor has completed its shutdown steps.

Call relations: Server teardown calls this on the message processor; the thread processor performs the actual shutdown.

Call graph: calls 1 internal fn (shutdown_threads).

async fn connection_closed(
        &self,
        connection_id: ConnectionId,
        session_state: &ConnectionSessionState,
    )

Purpose: Cleans up everything tied to a connection after it closes. This stops pending RPCs, removes outgoing state, ends file watches and command/process sessions, and detaches thread listeners.

Data flow: It receives the closed connection id and its session state. It waits for the connection’s RPC gate to drain, but only up to a timeout; if that times out it logs a warning. Then it notifies the outgoing sender and several processors that the connection is gone.

Call relations: Transport code calls this when a client disconnects. The method fans the close event out to the subsystems that may have stored connection-specific resources.

Call graph: calls 4 internal fn (connection_closed, connection_closed, connection_closed, connection_closed); 2 external calls (timeout, warn!).

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

Purpose: Returns a live subscription to the number of assistant turns currently running. A caller can use this to update UI or shutdown logic when active work changes.

Data flow: It asks the thread processor for a watch receiver, which is a small channel that always holds the latest value. It returns that receiver.

Call relations: Other app-server code calls this through the message processor; the count itself is maintained by the thread processor.

Call graph: calls 1 internal fn (subscribe_running_assistant_turn_count).

async fn process_response(&self, response: JSONRPCResponse)

Purpose: Processes a standalone response sent by the client. This is mainly for server-initiated requests where the server is waiting for the client’s answer.

Data flow: It receives a JSON-RPC response, logs it, extracts the id and result, and notifies the outgoing message sender so the waiting request can continue.

Call relations: Transport code calls this when the peer sends a response. It connects that response back to a pending request previously sent through OutgoingMessageSender, such as auth token refresh.

Call graph: 1 external calls (info!).

async fn process_error(&self, err: JSONRPCError)

Purpose: Processes an error response sent by the client. This lets a server-initiated request fail in the right waiting task instead of being lost.

Data flow: It receives a JSON-RPC error object, logs it as an error, extracts its id and error details, and notifies the outgoing message sender.

Call relations: Transport code calls this when the peer answers a server request with an error. The outgoing message sender wakes the code waiting for that response.

Call graph: 1 external calls (error!).

async fn handle_client_request(
        self: &Arc<Self>,
        connection_request_id: ConnectionRequestId,
        codex_request: ClientRequest,
        session: Arc<ConnectionSessionState>,

Purpose: Applies the first major rule for client requests: initialize requests are handled specially, and all other requests go through the initialized-request path. This keeps connection setup separate from normal work.

Data flow: It receives a connection request id, typed request, session state, optional outbound-ready flag, and request context. If the request is initialize, it asks the initialize processor to initialize the session and then informs the thread processor if the connection became initialized. Otherwise, it passes the request to the initialized dispatcher.

Call relations: process_request and process_client_request both call this. It either delegates to the initialize processor or to MessageProcessor::dispatch_initialized_client_request.

Call graph: calls 3 internal fn (dispatch_initialized_client_request, initialize, connection_initialized); called by 2 (process_client_request, process_request).

async fn dispatch_initialized_client_request(
        self: &Arc<Self>,
        connection_request_id: ConnectionRequestId,
        codex_request: ClientRequest,
        session: Arc<ConnectionSession

Purpose: Checks that a normal request is allowed to run, then schedules it. This protects the server from requests before initialization and from experimental calls made without opt-in.

Data flow: It receives the connection request id, typed request, session state, and request context. It rejects the request if the session is not initialized or if the request needs experimental access that the session lacks. Otherwise, it records the request, wraps the work in a queued request object, and either enqueues it in a serialization queue or spawns it immediately.

Call relations: handle_client_request calls this for every non-initialize request. It eventually runs MessageProcessor::handle_initialized_client_request, either directly in a spawned task or through a queue when ordering is required.

Call graph: calls 6 internal fn (invalid_request, span, track_initialized_request, new, from_scope, enqueue); called by 1 (handle_client_request); 6 external calls (clone, experimental_reason, serialization_scope, clone, experimental_required_message, spawn).

async fn handle_initialized_client_request(
        self: Arc<Self>,
        connection_request_id: ConnectionRequestId,
        codex_request: ClientRequest,
        request_context: RequestContext,

Purpose: This is the main request router for all fully initialized client requests. It matches each request type to the specialized processor that actually knows how to do the work.

Data flow: It receives the connection/request identity, typed request, request context, and optional client name/version. It builds the response request id, matches on the request variant, calls the right processor with the request parameters, then sends either a response payload, no response for fire-and-follow-up operations, or an error back to the client.

Call relations: dispatch_initialized_client_request schedules this after initialization checks pass. It hands work to processors for config, remote control, files, threads, turns, catalog, marketplace, plugins, apps, MCP, sandbox setup, accounts, git, search, command execution, process execution, and feedback upload.

Call graph: calls 120 internal fn (cancel_login_account, get_account, get_account_rate_limits, get_account_token_usage, get_auth_status, login_account, logout_account, send_add_credits_nudge_email, apps_list, collaboration_mode_list (+15 more)); 4 external calls (id, consume_account_rate_limit_reset_credit, thread_delete, panic!).

fn resolve_request_cwd(cwd: Option<PathBuf>) -> Result<Option<AbsolutePathBuf>, JSONRPCErrorError>

Purpose: This helper checks and normalizes an optional current working directory sent by a client. It makes sure the path can be treated as an absolute path the server understands, and turns bad input into a clear JSON-RPC request error.

Data flow: It receives either no path or a client-provided path. If there is no path, it returns no path. If there is a path, it first normalizes it for the machine’s native working-directory rules, then tries to resolve it relative to the current directory into an absolute path. On success, the output is the cleaned absolute path; on failure, the output is an error saying the cwd is invalid.

Call relations: This is a shared request-layer helper used when a processor needs to accept a client-supplied working directory before starting or reading something. It prepares the path before deeper code sees it, so lower layers can work with a trusted absolute path instead of re-checking raw client text.

fn resolve_turn_environment_selections(
    thread_manager: &ThreadManager,
    environments: Option<Vec<TurnEnvironmentParams>>,
) -> Result<Option<Vec<TurnEnvironmentSelection>>, JSONRPCErrorError>

Purpose: This helper translates a client’s requested turn environments into the core engine’s environment selection format. It also asks the thread manager to confirm that those selections are allowed and meaningful.

Data flow: It receives the thread manager and an optional list of environment choices from the client. If the list is missing, it returns no selections. If present, it walks each choice, extracts the environment id, converts the provided working directory into an absolute path URI, and rejects paths that do not look like valid POSIX or Windows absolute paths. After building the list, it asks the thread manager to validate it. The result is either a checked list of environment selections or a request error.

Call relations: Request processors use this before a turn is run in one or more environments. Inside, it builds the list efficiently, then hands the finished selections to validate_environment_selections so the thread manager can enforce the rules it owns. That keeps path parsing in the request layer and environment validity in the thread layer.

Call graph: calls 1 internal fn (validate_environment_selections); 1 external calls (with_capacity).

fn resolve_runtime_workspace_roots(workspace_roots: Vec<AbsolutePathBuf>) -> Vec<AbsolutePathBuf>

Purpose: This helper removes duplicate workspace root paths while keeping their original order. It is used so runtime setup sees each workspace folder only once.

Data flow: It receives a list of absolute workspace root paths. It creates a fresh output list, walks the input from left to right, and copies each path only if it has not already been added. The output is the same set of roots without repeats, preserving the first occurrence of each one.

Call relations: This sits between request/config input and the runtime workspace setup. Other request-processing code can pass potentially repeated roots through it before handing them to lower layers, avoiding redundant work or confusing duplicated workspace entries.

Call graph: 1 external calls (new).

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

Purpose: This helper rebuilds client-facing conversation turns from stored rollout history. A rollout item is a saved piece of thread history; this function keeps only the items that should count as persisted conversation history.

Data flow: It receives a slice of rollout history items. It creates a new ThreadHistoryBuilder, checks each item with is_persisted_rollout_item, and feeds only the persisted items into the builder. At the end, it asks the builder to finish and returns a list of API Turn objects suitable for sending back to a client.

Call relations: This is used when request processors need to present saved thread history through the app-server protocol. It relies on is_persisted_rollout_item to avoid exposing temporary or non-history events, then delegates the actual assembly of turns to ThreadHistoryBuilder.

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

fn environment_selection_error(err: CodexErr) -> JSONRPCErrorError

Purpose: This function converts a CodexErr from environment selection validation into the JSON-RPC error type expected by the server response path. It preserves client-input errors as “invalid request” errors, and turns all other failures into internal server errors.

Data flow: It receives one error value. If that value says the request itself was invalid, it takes the included message and produces an invalid-request JSON-RPC error. For any other error, it builds a message explaining that environment selection validation failed, includes the original error text, and returns an internal JSON-RPC error.

Call relations: This helper sits at the boundary between validation code and API response code. When request-processing code needs to report a failed environment selection check, it can call this function to get the right client-facing JSON-RPC error. Inside, it only formats the unexpected-error message before handing it to the standard internal-error response builder.

Call graph: 1 external calls (format!).

fn skills_to_info(
    skills: &[codex_core::skills::SkillMetadata],
    disabled_paths: &HashSet<AbsolutePathBuf>,
) -> Vec<codex_app_server_protocol::SkillMetadata>

Purpose: Turns internal skill records into the public skill records sent to clients. It also marks each skill as enabled or disabled by checking whether its file path appears in the disabled-path list.

Data flow: It receives a list of internal skill metadata and a set of disabled skill paths. For each skill, it copies user-facing fields such as name, descriptions, interface details, dependencies, path, and scope into protocol-friendly objects, then adds an enabled flag. It returns a new list ready to include in a response.

Call relations: This is a translation step used when building a skills list response. The skill loader produces detailed internal records, and this helper reshapes them into the simpler form the client expects.

Call graph: 1 external calls (iter).

fn hooks_to_info(hooks: &[codex_hooks::HookListEntry]) -> Vec<HookMetadata>

Purpose: Turns internal hook entries into hook metadata that can be sent over the app server protocol. A hook is a command or action that can run when a named event happens.

Data flow: It receives hook entries from the hook system. For each one, it copies fields such as key, event name, handler type, command, timeout, source, plugin id, enabled state, and trust status into a protocol record. It returns the converted list.

Call relations: When CatalogRequestProcessor::hooks_list_response has finished asking the hook system for hooks, it calls this helper to prepare those hooks for the client response.

Call graph: called by 1 (hooks_list_response); 1 external calls (iter).

fn errors_to_info(
    errors: &[codex_core::skills::SkillError],
) -> Vec<codex_app_server_protocol::SkillErrorInfo>

Purpose: Turns internal skill loading errors into error records that clients can display. This keeps the client from needing to know the internal error type.

Data flow: It receives skill errors, each with a path and message. It copies each path and message into a protocol error object. It returns the list of displayable error records.

Call relations: This helper sits between skill loading and response creation. When skill discovery finds problems, this function packages those problems in the response format.

Call graph: 1 external calls (iter).

fn new(
        outgoing: Arc<OutgoingMessageSender>,
        skills_watcher: Arc<SkillsWatcher>,
        auth_manager: Arc<AuthManager>,
        thread_manager: Arc<ThreadManager>,
        config: Ar

Purpose: Creates a CatalogRequestProcessor with all the shared services it needs. This is the setup step that gives later request handlers access to configuration, authentication, threads, skills, and outgoing notifications.

Data flow: It receives shared pointers to server services and stores them in a new processor struct. Nothing is loaded or sent yet; the result is a ready-to-use processor object.

Call relations: This constructor is called during server setup when request processors are assembled. Later, the initialized processor is used by the central client request handler.

Call graph: called by 1 (new).

async fn skills_list(
        &self,
        params: SkillsListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Handles the public skills/list style request. It asks the detailed skills-list helper for the answer and wraps that answer as a generic client response.

Data flow: It receives skill list parameters, including requested folders and whether to force a reload. It passes them to CatalogRequestProcessor::skills_list_response, then converts the typed response into the common response payload shape. It returns either that payload or a JSON-RPC error.

Call relations: The central initialized-client request dispatcher calls this method when the client asks for skills. This method then hands the real work to CatalogRequestProcessor::skills_list_response.

Call graph: calls 1 internal fn (skills_list_response); called by 1 (handle_initialized_client_request).

async fn hooks_list(
        &self,
        params: HooksListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Handles the public hook-list request. It delegates the real lookup to the hook-list helper and wraps the result for the client.

Data flow: It receives hook list parameters, passes them to CatalogRequestProcessor::hooks_list_response, and converts the typed hook response into a generic client response payload. It returns the payload or an error.

Call relations: The main client request handler calls this when a client asks to list hooks. It acts as the doorway into CatalogRequestProcessor::hooks_list_response.

Call graph: calls 1 internal fn (hooks_list_response); called by 1 (handle_initialized_client_request).

async fn skills_config_write(
        &self,
        params: SkillsConfigWriteParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Handles a request to change whether a skill is enabled. It validates and applies the change through the inner helper, then returns a client response.

Data flow: It receives parameters naming a skill by path or name plus the desired enabled state. It passes them to CatalogRequestProcessor::skills_config_write_response_inner, then wraps the typed result. The returned response tells the client the effective enabled value.

Call relations: The initialized-client request dispatcher calls this for skill configuration writes. This method keeps the public request shape separate from the lower-level config editing work.

Call graph: calls 1 internal fn (skills_config_write_response_inner); called by 1 (handle_initialized_client_request).

async fn skills_extra_roots_set(
        &self,
        params: SkillsExtraRootsSetParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Handles a request to set extra runtime folders where skills should be searched for. This lets the client add skill sources without editing permanent configuration.

Data flow: It receives a list of extra root paths and passes them to CatalogRequestProcessor::skills_extra_roots_set_response. The helper updates the watcher and skill manager, sends a change notification, and returns an empty success response wrapped for the client.

Call relations: The central request handler calls this when the client changes extra skill roots. It delegates to the response helper that performs the update and notifies listeners.

Call graph: calls 1 internal fn (skills_extra_roots_set_response); called by 1 (handle_initialized_client_request).

async fn model_list(
        &self,
        params: ModelListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Handles a request to list available AI models. It supports paging so clients can ask for models in chunks instead of needing the whole list at once.

Data flow: It receives model list parameters such as limit, cursor, and whether to include hidden models. It calls the model-listing helper with the thread manager, then wraps the typed response as a client payload. It returns that payload or an error for invalid input such as a bad cursor.

Call relations: The initialized-client request handler calls this for model list requests. It hands off to CatalogRequestProcessor::list_models, which does the actual model collection and pagination.

Call graph: called by 1 (handle_initialized_client_request); 1 external calls (list_models).

async fn experimental_feature_list(
        &self,
        params: ExperimentalFeatureListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Handles a request to list feature flags, including whether each feature is enabled. Feature flags are switches used to expose, hide, or retire product behavior.

Data flow: It receives feature list parameters, including optional thread context and paging information. It calls CatalogRequestProcessor::experimental_feature_list_response, then wraps the typed response for the client. The output is a page of feature records.

Call relations: The central initialized-client request dispatcher calls this method for experimental feature list requests. It delegates the detailed config and workspace checks to the response helper.

Call graph: calls 1 internal fn (experimental_feature_list_response); called by 1 (handle_initialized_client_request).

async fn permission_profile_list(
        &self,
        params: PermissionProfileListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Handles a request to list permission profiles. A permission profile is a named bundle of rules about what the assistant may do.

Data flow: It receives optional folder and paging parameters, passes them to CatalogRequestProcessor::permission_profile_list_response, and wraps the typed result into a generic client response. Errors are returned if configuration cannot be read or the cursor is invalid.

Call relations: The initialized-client request handler calls this when the client asks for permission profiles. This method forwards the work to the helper that reads configuration layers and builds the page.

Call graph: calls 1 internal fn (permission_profile_list_response); called by 1 (handle_initialized_client_request).

async fn collaboration_mode_list(
        &self,
        params: CollaborationModeListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Handles a request to list available collaboration modes. These modes describe different ways the user and assistant can work together in a thread.

Data flow: It receives an empty collaboration-mode parameter object, asks the thread manager for the available modes through the helper, and wraps the result. It returns the list in the client response format.

Call relations: The central client request handler calls this for collaboration-mode requests. It delegates to CatalogRequestProcessor::list_collaboration_modes, which asks the thread manager for the actual data.

Call graph: called by 1 (handle_initialized_client_request); 1 external calls (list_collaboration_modes).

async fn mock_experimental_method(
        &self,
        params: MockExperimentalMethodParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Handles a test-like experimental request by echoing a value back to the caller. It is useful for checking that the request path and response wrapping work.

Data flow: It receives a value in the request parameters, passes it to CatalogRequestProcessor::mock_experimental_method_inner, and wraps the echo response. The output contains the same value under an echoed field.

Call relations: The initialized-client request dispatcher calls this for the mock experimental method. The public method simply connects that request to the inner echo helper.

Call graph: calls 1 internal fn (mock_experimental_method_inner); called by 1 (handle_initialized_client_request).

async fn resolve_cwd_config(
        &self,
        cwd: &Path,
    ) -> Result<(AbsolutePathBuf, ConfigLayerStack), String>

Purpose: Converts a requested working directory into an absolute path and loads the configuration layers that apply there. Configuration layers are the stacked settings from places like defaults, user config, and workspace config.

Data flow: It receives a folder path, makes it absolute relative to the current process, then asks the configuration manager to load the config layers for that folder. It returns the absolute folder and its layer stack, or a plain error message string if something fails.

Call relations: This helper is used when a request depends on folder-specific configuration, including permission profile listing and skill listing. It relies on path conversion and the config manager’s load_config_layers_for_cwd operation.

Call graph: calls 2 internal fn (load_config_layers_for_cwd, relative_to_current_dir); called by 1 (permission_profile_list_response).

async fn load_latest_config(
        &self,
        fallback_cwd: Option<PathBuf>,
    ) -> Result<Config, JSONRPCErrorError>

Purpose: Reloads the newest effective configuration. This prevents catalog answers from being based on stale settings after the user has changed config files.

Data flow: It receives an optional fallback working directory, asks the configuration manager for the latest config, and converts any load failure into a JSON-RPC internal error. It returns a fresh Config object on success.

Call relations: Feature listing and skill listing call this before deciding what is enabled. It is a small adapter around the config manager that also standardizes the error message.

Call graph: calls 1 internal fn (load_latest_config); called by 2 (experimental_feature_list_response, skills_list_response).

async fn workspace_codex_plugins_enabled(
        &self,
        config: &Config,
        auth: Option<&CodexAuth>,
    ) -> bool

Purpose: Checks whether Codex plugins are allowed for the current workspace. If the check fails, it logs a warning and chooses to allow plugins rather than hide them because of a lookup problem.

Data flow: It receives the current config and optional authentication information. It asks the workspace settings system, using the local cache, whether plugins are enabled. It returns a boolean; on error it writes a warning and returns true.

Call relations: Skill listing, hook listing, and feature listing call this before exposing plugin-related capabilities. It is the gatekeeper that combines workspace policy with catalog results.

Call graph: calls 1 internal fn (codex_plugins_enabled_for_workspace); called by 3 (experimental_feature_list_response, hooks_list_response, skills_list_response); 1 external calls (warn!).

async fn list_models(
        thread_manager: Arc<ThreadManager>,
        params: ModelListParams,
    ) -> Result<ModelListResponse, JSONRPCErrorError>

Purpose: Builds a paged list of supported AI models. Paging keeps the response manageable and gives the client a cursor for the next page.

Data flow: It receives a thread manager plus parameters for limit, cursor, and hidden-model visibility. It gets the full model list, checks and parses the cursor, slices out the requested page, and returns the page plus the next cursor if more models remain. Bad cursors become invalid-request errors.

Call relations: The public CatalogRequestProcessor::model_list method calls this when the client asks for models. This helper performs the list lookup and pagination before handing the typed response back.

Call graph: 2 external calls (new, format!).

async fn list_collaboration_modes(
        thread_manager: Arc<ThreadManager>,
        params: CollaborationModeListParams,
    ) -> Result<CollaborationModeListResponse, JSONRPCErrorError>

Purpose: Collects the collaboration modes known to the thread manager and converts them into protocol records. It is a simple catalog lookup with no paging.

Data flow: It receives a thread manager and empty parameters. It asks the thread manager for collaboration modes, converts each one into the response type, and returns them in a response object.

Call relations: The public CatalogRequestProcessor::collaboration_mode_list method calls this. The thread manager owns the source list, and this helper packages it for the client.

async fn experimental_feature_list_response(
        &self,
        params: ExperimentalFeatureListParams,
    ) -> Result<ExperimentalFeatureListResponse, JSONRPCErrorError>

Purpose: Creates the actual response for listing feature flags. It tells the client each feature’s name, stage, display text when available, and whether it is currently enabled.

Data flow: It receives paging parameters and an optional thread id. If a thread id is provided, it loads configuration as that thread sees it; otherwise it reloads the latest general config. It checks workspace plugin policy, converts every feature specification into an API feature record, applies paging, and returns the selected page with an optional next cursor.

Call relations: The public CatalogRequestProcessor::experimental_feature_list method calls this. Inside, it may load thread-specific config, call CatalogRequestProcessor::load_latest_config, and call CatalogRequestProcessor::workspace_codex_plugins_enabled so plugin and app features are reported correctly.

Call graph: calls 4 internal fn (load_latest_config_for_thread, load_latest_config, workspace_codex_plugins_enabled, from_string); called by 1 (experimental_feature_list); 2 external calls (new, format!).

async fn permission_profile_list_response(
        &self,
        params: PermissionProfileListParams,
    ) -> Result<PermissionProfileListResponse, JSONRPCErrorError>

Purpose: Creates the actual response for listing permission profiles. It includes built-in profiles and any custom profiles defined in configuration.

Data flow: It receives an optional working directory plus paging fields. If a folder is given, it resolves the folder and loads its config layers; otherwise it loads general config layers. It reads the effective config, starts with the built-in profiles, adds sorted custom profiles, slices the requested page, and returns it with a next cursor when needed.

Call relations: The public CatalogRequestProcessor::permission_profile_list method calls this. It uses CatalogRequestProcessor::resolve_cwd_config for folder-specific requests and the config manager for non-folder-specific requests.

Call graph: calls 2 internal fn (load_config_layers, resolve_cwd_config); called by 1 (permission_profile_list); 3 external calls (from, format!, vec!).

async fn mock_experimental_method_inner(
        &self,
        params: MockExperimentalMethodParams,
    ) -> Result<MockExperimentalMethodResponse, JSONRPCErrorError>

Purpose: Returns the provided value unchanged in an echo response. This gives developers or clients a minimal experimental endpoint for checking request and response plumbing.

Data flow: It receives parameters containing a value. It places that value into a response object as echoed and returns it. It does not read configuration or change server state.

Call relations: The public CatalogRequestProcessor::mock_experimental_method method calls this. It is the whole business logic for that mock endpoint.

Call graph: called by 1 (mock_experimental_method).

async fn skills_list_response(
        &self,
        params: SkillsListParams,
    ) -> Result<SkillsListResponse, JSONRPCErrorError>

Purpose: Creates the actual response for listing skills for one or more working directories. A skill is a reusable capability described by metadata, often loaded from files or plugins.

Data flow: It receives requested folders and a force-reload flag. If no folders are provided, it uses the server’s current working directory. It reloads config, checks auth and workspace plugin policy, then processes the folders with limited concurrency so several folders can be checked at once without flooding the system. For each folder, it resolves config, computes plugin skill roots when allowed, loads skills, converts skills and errors into protocol records, preserves the original folder order, and returns all entries.

Call relations: The public CatalogRequestProcessor::skills_list method calls this. It uses CatalogRequestProcessor::load_latest_config, CatalogRequestProcessor::workspace_codex_plugins_enabled, the thread manager’s skill and plugin managers, and the conversion helpers for skill and error records.

Call graph: calls 2 internal fn (load_latest_config, workspace_codex_plugins_enabled); called by 1 (skills_list); 2 external calls (iter, vec!).

async fn skills_extra_roots_set_response(
        &self,
        params: SkillsExtraRootsSetParams,
    ) -> Result<SkillsExtraRootsSetResponse, JSONRPCErrorError>

Purpose: Applies a runtime list of extra folders where skills should be discovered. After changing the list, it notifies clients that the skill catalog has changed.

Data flow: It receives extra root paths. It registers them with the skill watcher, gives them to the skill manager, sends a SkillsChanged server notification through the outgoing message sender, and returns an empty success response.

Call relations: The public CatalogRequestProcessor::skills_extra_roots_set method calls this. This helper updates both the watching side and the loading side, then broadcasts the change so clients know to refresh.

Call graph: called by 1 (skills_extra_roots_set); 1 external calls (SkillsChanged).

async fn hooks_list_response(
        &self,
        params: HooksListParams,
    ) -> Result<HooksListResponse, JSONRPCErrorError>

Purpose: Creates the actual response for listing hooks for one or more working directories. Hooks can come from configuration and, when allowed, from plugins.

Data flow: It receives requested folders, defaulting to the server’s current folder if none are supplied. For each folder, it loads config; if config loading fails, it records an error entry for that folder and moves on. Otherwise it checks whether workspace plugins and the plugin feature are enabled, gathers plugin hook sources and warnings when allowed, asks the hook system to list hooks using the effective settings, converts the hooks into protocol metadata, and returns one entry per folder.

Call relations: The public CatalogRequestProcessor::hooks_list method calls this. It uses config loading, CatalogRequestProcessor::workspace_codex_plugins_enabled, plugin lookup, the external hook lister, and hooks_to_info to assemble the client response.

Call graph: calls 3 internal fn (load_for_cwd, workspace_codex_plugins_enabled, hooks_to_info); called by 1 (hooks_list); 6 external calls (default, new, list_hooks, default, default, vec!).

async fn skills_config_write_response_inner(
        &self,
        params: SkillsConfigWriteParams,
    ) -> Result<SkillsConfigWriteResponse, JSONRPCErrorError>

Purpose: Writes a configuration change that enables or disables a skill, identified either by file path or by name. It clears related caches afterward so future catalog requests see the new setting.

Data flow: It receives a path, a name, and the desired enabled state. It requires exactly one usable identifier: either a path or a non-empty name. It builds a config edit, applies it under the Codex home directory, clears plugin and skill caches on success, and returns the effective enabled value. Invalid input becomes an invalid-parameters error; write failures become internal errors.

Call relations: The public CatalogRequestProcessor::skills_config_write method calls this. It uses the config edit builder to change saved settings, then tells the managers to forget cached data so later skill and plugin lookups reload fresh information.

Call graph: calls 1 internal fn (new); called by 1 (skills_config_write); 1 external calls (vec!).

fn new(environment_manager: Arc<EnvironmentManager>) -> Self

Purpose: Creates an EnvironmentRequestProcessor and gives it access to the shared EnvironmentManager. This is used when the server is wiring together its request-processing pieces.

Data flow: It receives a shared EnvironmentManager reference as input. It stores that reference inside a new EnvironmentRequestProcessor. The result is a processor object that can later answer environment-related client requests.

Call relations: During setup, the broader request-processing construction code calls this function to make the environment processor. After that, other request-handling code can keep this processor and use it whenever an environment request arrives.

Call graph: called by 1 (new).

async fn environment_add(
        &self,
        params: EnvironmentAddParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Registers a client-provided environment, or updates it if it is already known. It returns a simple success response when the environment manager accepts the change.

Data flow: It receives request parameters containing an environment ID and an execution server URL. It passes those values to the EnvironmentManager, which records them. If that recording fails, the error is converted into a client-facing JSON-RPC invalid request error; if it succeeds, the function returns an environment-add success response.

Call relations: After the client has been initialized, the main request handler calls this function when it sees an environment-add request. This function then hands the real registry update to the EnvironmentManager and translates the outcome back into the response shape the client expects.

Call graph: called by 1 (handle_initialized_client_request).

fn new(args: ExternalAgentConfigRequestProcessorArgs) -> Self

Purpose: Builds a ready-to-use processor with all the pieces it needs: outgoing messages, migration services, session importing, thread access, configuration refreshing, and optional history storage.

Data flow: It receives a bundle of shared server services and paths. It creates an ExternalAgentSessionImporter for session migration and an ExternalAgentConfigService for detecting and importing configuration. It returns a processor that keeps references to those services for later requests.

Call relations: This is called when the app-server wires up its request processors. After this setup step, client request handling can call methods like detect, import, and read_import_histories on the created processor.

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

async fn detect(
        &self,
        params: ExternalAgentConfigDetectParams,
    ) -> Result<ExternalAgentConfigDetectResponse, JSONRPCErrorError>

Purpose: Looks for external-agent items that could be imported into Codex and returns a client-friendly list of them.

Data flow: It receives detection options from the client, such as whether to include the home directory and which working directories to inspect. It asks the migration service to scan those places. It converts the found core migration items into protocol response items and returns them, or turns scan failures into a JSON-RPC error.

Call relations: The initialized client request handler calls this when the client asks what can be imported. This function delegates the actual searching to the migration service, then translates the result into the app-server protocol.

Call graph: calls 1 internal fn (detect); called by 1 (handle_initialized_client_request).

async fn import(
        &self,
        request_id: ConnectionRequestId,
        params: ExternalAgentConfigImportParams,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Starts an import chosen by the client, sends the client an import ID, reports progress, and eventually sends a final completion notification.

Data flow: It receives the request ID and the list of selected migration items. It creates a unique import ID, checks whether the running app will need refreshed settings, validates selected sessions, imports the non-session configuration, and sends an immediate response containing the import ID. It then sends progress messages for completed work. If plugin or session work remains, it launches background tasks and sends the final result after they finish; otherwise it sends the final notification right away.

Call relations: The initialized client request handler calls this for an import request. Inside the flow it uses validation, core config import, plugin completion, session import, progress notification helpers, final notification helpers, and runtime cache refreshes so the client can see both immediate and background progress.

Call graph: calls 8 internal fn (record_import_error, handle_config_mutation, import_external_agent_config, validate_pending_session_imports, apply_plugin_outcome_to_item_result, migration_items_need_runtime_refresh, send_completed_import_notification, send_import_progress); called by 1 (handle_initialized_client_request); 7 external calls (clone, new, new_v4, new, clone, join!, spawn).

async fn read_import_histories(
        &self,
    ) -> Result<ExternalAgentConfigImportHistoriesReadResponse, JSONRPCErrorError>

Purpose: Reads previously completed external-agent import records so the client can show import history.

Data flow: It checks that a state database is available. It reads saved import history records from that database. It converts each stored record into protocol format and returns the list; if the database is missing or the read fails, it returns a client-visible internal error.

Call relations: The initialized client request handler calls this when the client asks for import histories. It relies on the history records that send_completed_import_notification may have stored after past imports.

Call graph: called by 1 (handle_initialized_client_request).

fn validate_pending_session_imports(
        &self,
        params: &ExternalAgentConfigImportParams,
    ) -> (Vec<CoreSessionMigration>, Option<CoreImportItemResult>)

Purpose: Checks selected session imports before doing the slower background session import work. It filters out missing or duplicate session sources and records validation errors for the client.

Data flow: It reads the selected migration items and extracts any session entries. For each session, it asks the migration service for the real source path. Missing or invalid sessions become recorded errors; duplicate canonical paths are skipped so the same session is not imported twice. It returns the remaining sessions to import plus a validation result describing any problems.

Call relations: The main import flow calls this before starting imports. Its validation result is sent as an early progress update, while the valid session list is handed to the background session importer.

Call graph: calls 2 internal fn (external_agent_session_source_path, record_import_error); called by 1 (import); 4 external calls (new, new, new, format!).

async fn import_external_agent_config(
        &self,
        params: ExternalAgentConfigImportParams,
    ) -> Result<CoreImportOutcome, JSONRPCErrorError>

Purpose: Runs the main configuration import for all selected items except sessions, which are handled separately.

Data flow: It receives the client’s import parameters. It removes session items, converts the remaining protocol-shaped items into the core migration service’s types, and asks that service to import them. It returns the core import outcome, including immediate item results and any plugin imports that still need background completion.

Call relations: The main import method calls this after session validation. This function hands the actual copying work to the migration service and gives import the results it needs for progress reporting and background plugin work.

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

async fn complete_pending_plugin_import(
        &self,
        pending_plugin_import: PendingPluginImport,
    ) -> Result<PluginImportOutcome, JSONRPCErrorError>

Purpose: Finishes a plugin import that could not be completed in the initial import pass.

Data flow: It receives a pending plugin import with its working directory and details. It asks the migration service to import those plugins. It returns the plugin outcome, or converts any failure into a JSON-RPC internal error.

Call relations: The background part of import calls this for each pending plugin import. Its result is then folded into an item result by apply_plugin_outcome_to_item_result before progress is sent.

Call graph: calls 1 internal fn (import_plugins).

async fn send_import_progress(
    outgoing: &OutgoingMessageSender,
    import_id: &str,
    item_result: &CoreImportItemResult,
)

Purpose: Sends a progress notification for one imported item type to the client.

Data flow: It receives the outgoing message sender, the import ID, and one core item result. It converts that item result into protocol format and sends a server notification containing successes and failures for that item type. It does not return data to the caller beyond completing the send.

Call relations: The import method calls this after validation, after immediate imports, and after background session or plugin imports. It is the small helper that keeps the client informed during a longer import.

Call graph: calls 1 internal fn (send_server_notification); called by 1 (import); 2 external calls (ExternalAgentConfigImportProgress, vec!).

async fn send_completed_import_notification(
    outgoing: &OutgoingMessageSender,
    state_db: Option<&StateDbHandle>,
    import_id: String,
    item_results: &[CoreImportItemResult],
)

Purpose: Builds and sends the final import-completed notification, and saves it to history if a state database is available.

Data flow: It receives the outgoing sender, optional database handle, import ID, and all item results. It creates a completed notification from those results. If there is a database, it tries to record the notification; failures are logged but do not stop the client notification. It then sends the final completion notification to the client.

Call relations: The main import flow calls this either immediately, when no background work is needed, or after background session and plugin imports finish. It uses completed_notification to shape the client message and record_completed_import_notification to save history.

Call graph: calls 3 internal fn (send_server_notification, completed_notification, record_completed_import_notification); called by 1 (import); 2 external calls (ExternalAgentConfigImportCompleted, warn!).

async fn record_completed_import_notification(
    state_db: &StateDbHandle,
    notification: &ExternalAgentConfigImportCompletedNotification,
) -> anyhow::Result<()>

Purpose: Stores a completed import’s successes and failures in the state database for later history views.

Data flow: It receives the database handle and the completed notification. It extracts each success and failure, converts their item types into the database’s stored form, and calls the database method that records the completed import. It returns success or an error if conversion or database writing fails.

Call relations: send_completed_import_notification calls this before notifying the client. This helper is only about persistence: it turns the outgoing notification into saved history records.

Call graph: called by 1 (send_completed_import_notification); 1 external calls (record_external_agent_config_import_completed).

fn protocol_import_history(
    record: codex_state::ExternalAgentConfigImportHistoryRecord,
) -> Result<ExternalAgentConfigImportHistory, JSONRPCErrorError>

Purpose: Converts one stored import history record into the protocol format the client expects.

Data flow: It receives a database history record containing an import ID, completion time, successes, and failures. It converts each success and failure record into protocol records. It returns a complete protocol history entry or an error if an item type cannot be decoded.

Call relations: read_import_histories uses this while preparing the history response. It sits between database storage format and client message format.

fn protocol_import_success_record(
    record: ExternalAgentConfigImportSuccessRecord,
) -> Result<ProtocolImportSuccess, JSONRPCErrorError>

Purpose: Converts one stored success record into a client-facing success record.

Data flow: It receives a stored success with an item type, working directory, source, and target. It decodes the stored item type into the protocol enum and copies over the remaining fields. It returns the protocol success record or an error if the item type is invalid.

Call relations: protocol_import_history calls this for each saved success. It relies on protocol_import_record_item_type for the item type conversion.

Call graph: calls 1 internal fn (protocol_import_record_item_type).

fn protocol_import_failure_record(
    record: ExternalAgentConfigImportFailureRecord,
) -> Result<ProtocolImportFailure, JSONRPCErrorError>

Purpose: Converts one stored failure record into a client-facing failure record.

Data flow: It receives a stored failure with its item type, error kind, failure stage, message, working directory, and source. It decodes the item type and copies the rest of the information into protocol format. It returns the protocol failure record or an error if the item type cannot be decoded.

Call relations: protocol_import_history calls this for each saved failure. It uses protocol_import_record_item_type so stored history can be safely turned back into protocol values.

Call graph: calls 1 internal fn (protocol_import_record_item_type).

fn protocol_import_record_item_type(
    item_type: String,
) -> Result<ExternalAgentConfigMigrationItemType, JSONRPCErrorError>

Purpose: Decodes an item type string from saved history into the protocol’s item type value.

Data flow: It receives a string such as a stored item type name. It asks the JSON serializer/deserializer to interpret that string as an ExternalAgentConfigMigrationItemType. It returns the decoded item type or a clear internal error if the string is not recognized.

Call relations: The success and failure history converters call this whenever they need to turn database text back into protocol data. This keeps history reading from silently accepting unknown item types.

Call graph: called by 2 (protocol_import_failure_record, protocol_import_success_record); 2 external calls (String, from_value).

fn completed_notification(
    import_id: String,
    item_results: &[CoreImportItemResult],
) -> ExternalAgentConfigImportCompletedNotification

Purpose: Creates the final client notification that summarizes all import successes and failures, grouped by item type.

Data flow: It receives the import ID and all core item results. For each result, it converts successes and raw errors into protocol records, merges results that share the same item type, and sorts item types into a stable order. It returns the completed notification ready to send.

Call relations: send_completed_import_notification calls this before saving or sending the final result. It uses the lower-level protocol conversion helpers so the notification has the same shape the client expects.

Call graph: calls 1 internal fn (protocol_migration_item_type); called by 1 (send_completed_import_notification); 1 external calls (new).

fn protocol_import_type_result(item_result: &CoreImportItemResult) -> ProtocolImportTypeResult

Purpose: Converts one core item result into one protocol item-type result for progress updates.

Data flow: It receives a core result for one migration item type. It converts the item type, all successes, and all raw errors into protocol fields. It returns a protocol result that can be placed inside a progress notification.

Call relations: send_import_progress calls this while preparing progress messages. It shares conversion helpers with the final notification path so progress and completion messages stay consistent.

Call graph: calls 1 internal fn (protocol_migration_item_type).

fn protocol_import_success(
    success: &crate::config::external_agent_config::ExternalAgentConfigImportSuccess,
) -> ProtocolImportSuccess

Purpose: Converts one core import success into the protocol success format sent to the client.

Data flow: It receives a core success record with item type, working directory, source, and target. It converts the item type and clones the descriptive fields. It returns the protocol success record.

Call relations: completed_notification and protocol_import_type_result use this when building final and progress messages. It relies on protocol_migration_item_type for the item type mapping.

Call graph: calls 1 internal fn (protocol_migration_item_type).

fn protocol_import_raw_error(raw_error: &CoreImportRawError) -> ProtocolImportFailure

Purpose: Converts one core import error into the protocol failure format sent to the client.

Data flow: It receives a raw core error with item type, error type, failure stage, message, working directory, and source. It converts the item type and copies the error details into protocol format. It returns the protocol failure record.

Call relations: completed_notification and protocol_import_type_result use this to include failures in progress and final notifications. It keeps error reporting shaped for the client rather than for internal code.

Call graph: calls 1 internal fn (protocol_migration_item_type).

fn protocol_migration_item_type(
    item_type: CoreMigrationItemType,
) -> ExternalAgentConfigMigrationItemType

Purpose: Maps a core migration item type to the matching protocol item type.

Data flow: It receives an internal enum value for an import category, such as config, plugins, hooks, commands, or sessions. It matches that value to the equivalent protocol enum. It returns the protocol item type.

Call relations: Several conversion helpers call this whenever internal migration results need to be sent over the app-server protocol. It is the central mapping that prevents each caller from duplicating the same match logic.

Call graph: called by 4 (completed_notification, protocol_import_raw_error, protocol_import_success, protocol_import_type_result).

fn apply_plugin_outcome_to_item_result(
    item_result: &mut CoreImportItemResult,
    plugin_outcome: PluginImportOutcome,
)

Purpose: Adds the results of a completed plugin import into the general import item result used for progress and completion reporting.

Data flow: It receives a mutable plugin item result and a plugin outcome. Each successful plugin ID is recorded as a success. Each raw plugin error is recorded as an error. The item result is changed in place and becomes ready for notification.

Call relations: The background plugin part of import calls this after complete_pending_plugin_import succeeds. It turns plugin-specific output into the common result format used by send_import_progress and the final completion notification.

Call graph: called by 1 (import); 2 external calls (record_error, record_success).

fn migration_items_need_runtime_refresh(items: &[ExternalAgentConfigMigrationItem]) -> bool

Purpose: Decides whether the selected import items can affect the running Codex environment and therefore require a configuration refresh.

Data flow: It receives the selected migration items. It checks whether any item is a runtime-sensitive type, such as config, skills, MCP server config, hooks, commands, or plugins. It returns true if the app should refresh its active configuration after import, otherwise false.

Call relations: The main import method calls this near the start. If it returns true, import later asks the config processor to refresh after the core import work so the running server notices the imported changes.

Call graph: called by 1 (import); 1 external calls (iter).

fn new(
        auth_manager: Arc<AuthManager>,
        thread_manager: Arc<ThreadManager>,
        outgoing: Arc<OutgoingMessageSender>,
        config_manager: ConfigManager,
    ) -> Self

Purpose: Creates a new MCP request processor with the shared services it needs. These services include authentication, thread lookup, outgoing replies, and configuration loading.

Data flow: It receives references to the authentication manager, thread manager, outgoing message sender, and config manager. It stores them inside a new processor object. The result is a ready-to-use processor that can respond to MCP-related client requests.

Call relations: A higher-level constructor calls this when the request-processing system is being built. After that, the created processor is used whenever initialized client requests need MCP work.

Call graph: called by 1 (new).

async fn mcp_server_oauth_login(
        &self,
        params: McpServerOauthLoginParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Starts an OAuth login flow for an MCP server and returns the URL the user must visit. OAuth is a common login method where the user authorizes access in a browser.

Data flow: It receives login parameters such as the server name, requested permission scopes, and timeout. It asks the more detailed login function to do the work, then wraps the response into the standard client response format. The output is either a response containing an authorization URL or a JSON-RPC error.

Call relations: The initialized client request handler calls this when the client asks to log in to an MCP server. This function delegates the real work to McpRequestProcessor::mcp_server_oauth_login_response.

Call graph: calls 1 internal fn (mcp_server_oauth_login_response); called by 1 (handle_initialized_client_request).

async fn mcp_server_refresh(
        &self,
        params: Option<()>,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Refreshes the app’s view of configured MCP servers. This is useful when server configuration or availability may have changed.

Data flow: It receives an empty optional parameter, because this request does not need extra details. It asks the refresh response function to queue the refresh work, then wraps the successful response into the standard client response format. It returns either that response or a JSON-RPC error.

Call relations: The initialized client request handler calls this for MCP refresh requests. It hands the request to McpRequestProcessor::mcp_server_refresh_response, which queues the actual refresh.

Call graph: calls 1 internal fn (mcp_server_refresh_response); called by 1 (handle_initialized_client_request).

async fn mcp_server_status_list(
        &self,
        request_id: &ConnectionRequestId,
        params: ListMcpServerStatusParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Begins a request to list the status of MCP servers. The final status is sent later through the outgoing message channel instead of being returned directly here.

Data flow: It receives the connection request ID and status-list parameters such as detail level, cursor, limit, and optional thread ID. It starts the internal status-list flow, and if that setup succeeds it returns no immediate payload. Any later result is sent using the saved request ID.

Call relations: The initialized client request handler calls this when the client asks for MCP server status. It delegates setup and background execution to McpRequestProcessor::list_mcp_server_status.

Call graph: calls 1 internal fn (list_mcp_server_status); called by 1 (handle_initialized_client_request).

async fn mcp_resource_read(
        &self,
        request_id: &ConnectionRequestId,
        params: McpResourceReadParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Begins a request to read a resource exposed by an MCP server. A resource is data the server makes available, identified here by a URI, which is a standard text address.

Data flow: It receives the connection request ID and resource-read parameters: optional thread ID, server name, and resource URI. It starts the read flow and returns no immediate payload if the read was successfully scheduled. The actual resource content or error is sent later using the request ID.

Call relations: The initialized client request handler calls this for resource-read requests. It delegates the setup and background read work to McpRequestProcessor::read_mcp_resource.

Call graph: calls 1 internal fn (read_mcp_resource); called by 1 (handle_initialized_client_request).

async fn mcp_server_tool_call(
        &self,
        request_id: &ConnectionRequestId,
        params: McpServerToolCallParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Begins a request to call a tool on an MCP server within a specific conversation thread. A tool is an action the external MCP server can perform for the app.

Data flow: It receives the connection request ID and tool-call parameters, including the thread ID, server name, tool name, arguments, and optional metadata. It schedules the tool call and returns no immediate payload if scheduling succeeds. The tool result or error is sent later.

Call relations: The initialized client request handler calls this when a client asks to run an MCP tool. It passes the work to McpRequestProcessor::call_mcp_server_tool.

Call graph: calls 1 internal fn (call_mcp_server_tool); called by 1 (handle_initialized_client_request).

async fn mcp_server_refresh_response(
        &self,
        _params: Option<()>,
    ) -> Result<McpServerRefreshResponse, JSONRPCErrorError>

Purpose: Queues a strict refresh of MCP servers and returns a small success response. A strict refresh means failures are treated as real errors instead of being quietly ignored.

Data flow: It receives no meaningful input besides access to the processor’s thread and config managers. It asks the MCP refresh system to refresh using the current thread and configuration state. If queuing succeeds, it returns an empty refresh response; if it fails, it returns an internal JSON-RPC error.

Call relations: McpRequestProcessor::mcp_server_refresh calls this after receiving the public request. This function hands the actual refresh scheduling to queue_strict_refresh.

Call graph: calls 1 internal fn (queue_strict_refresh); called by 1 (mcp_server_refresh).

async fn load_latest_config(
        &self,
        fallback_cwd: Option<PathBuf>,
    ) -> Result<Config, JSONRPCErrorError>

Purpose: Loads the newest configuration and converts any loading failure into a client-facing JSON-RPC error. This keeps callers from accidentally using stale MCP settings.

Data flow: It receives an optional fallback working directory. It asks the config manager to load the latest config using that fallback if needed. It returns the loaded config, or an internal error that explains the reload failure.

Call relations: OAuth login, server-status listing, and threadless resource reading call this before they inspect MCP settings. It is a small shared helper around the config manager’s load_latest_config operation.

Call graph: calls 1 internal fn (load_latest_config); called by 3 (list_mcp_server_status, mcp_server_oauth_login_response, read_mcp_resource).

async fn load_thread(
        &self,
        thread_id: &str,
    ) -> Result<(ThreadId, Arc<CodexThread>), JSONRPCErrorError>

Purpose: Finds an existing conversation thread from a thread ID string. It also validates that the thread ID has the correct format before looking it up.

Data flow: It receives a thread ID as text. First it parses that text into the project’s ThreadId type; if parsing fails, it returns an invalid-request error. Then it asks the thread manager for the matching thread; if none is found, it returns an invalid-request error. On success, it returns both the parsed ID and the thread object.

Call relations: Tool calls, status listing for a specific thread, and resource reads inside a thread all call this. It uses ThreadId::from_string for validation before asking the thread manager for the thread.

Call graph: calls 1 internal fn (from_string); called by 3 (call_mcp_server_tool, list_mcp_server_status, read_mcp_resource).

async fn mcp_server_oauth_login_response(
        &self,
        params: McpServerOauthLoginParams,
    ) -> Result<McpServerOauthLoginResponse, JSONRPCErrorError>

Purpose: Does the detailed work needed to start OAuth login for one configured MCP server. It checks the server exists, verifies that its transport supports OAuth, resolves permission scopes, starts the login, and arranges for a completion notification.

Data flow: It receives the server name, optional requested scopes, and optional timeout. It reloads config, reads current authentication, and asks the MCP manager for the effective server list. It finds the named server, checks that it uses streamable HTTP transport, discovers or resolves OAuth scopes, and starts the login flow. It returns an authorization URL immediately. Separately, a background task waits for the login to finish and sends a success or failure notification.

Call relations: McpRequestProcessor::mcp_server_oauth_login calls this for the public request. Inside, it uses McpRequestProcessor::load_latest_config, consults the MCP manager and auth manager, starts OAuth through the OAuth helper, then spawns a background notification task using the outgoing sender.

Call graph: calls 1 internal fn (load_latest_config); called by 1 (mcp_server_oauth_login); 4 external calls (clone, McpServerOauthLoginCompleted, format!, spawn).

async fn list_mcp_server_status(
        &self,
        request_id: &ConnectionRequestId,
        params: ListMcpServerStatusParams,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Prepares a server-status request and starts the background task that will collect and send the status. It supports both global MCP status and status as seen from a particular conversation thread.

Data flow: It receives the request ID and listing parameters. If the parameters include a thread ID, it loads that thread and reloads config using the thread’s config. Otherwise it loads the latest global config. It builds the runtime MCP configuration, collects current authentication and environment context, then starts a background task. The immediate result is success or a setup error; the actual list is sent later.

Call relations: McpRequestProcessor::mcp_server_status_list calls this when a client asks for status. This function may call McpRequestProcessor::load_thread, McpRequestProcessor::load_latest_config, or the config manager’s thread-specific config loader, then hands the long-running work to McpRequestProcessor::list_mcp_server_status_task in a spawned task.

Call graph: calls 4 internal fn (load_latest_config_for_thread, load_latest_config, load_thread, new); called by 1 (mcp_server_status_list); 4 external calls (clone, list_mcp_server_status_task, clone, spawn).

async fn list_mcp_server_status_task(
        outgoing: Arc<OutgoingMessageSender>,
        request_id: ConnectionRequestId,
        params: ListMcpServerStatusParams,
        mcp_config: codex_mcp::M

Purpose: Runs the background half of a status-list request and sends the final answer back to the client. It exists so the initial request handler does not have to wait while MCP servers are inspected.

Data flow: It receives the outgoing sender, request ID, original parameters, prepared MCP config, authentication, and runtime context. It asks the response-building function to collect and shape the status data. Then it sends either the completed response or an error through the outgoing message sender.

Call relations: McpRequestProcessor::list_mcp_server_status starts this in the background. This task calls McpRequestProcessor::list_mcp_server_status_response to build the response, then uses the outgoing sender to deliver it for the original request ID.

Call graph: 1 external calls (list_mcp_server_status_response).

async fn list_mcp_server_status_response(
        request_id: String,
        params: ListMcpServerStatusParams,
        mcp_config: codex_mcp::McpConfig,
        auth: Option<CodexAuth>,
        runt

Purpose: Builds the actual paged list of MCP server statuses. It combines server information, available tools, resources, resource templates, and authentication state into one response.

Data flow: It receives the original request ID as text, list parameters, MCP configuration, optional authentication, and runtime context. It chooses how much detail to collect, asks the MCP status collector for a snapshot, merges all server names that appear in any part of that snapshot, sorts them, and applies pagination using limit and cursor. It returns a response containing the selected page of server statuses and, if there is more data, a next cursor.

Call relations: McpRequestProcessor::list_mcp_server_status_task calls this while preparing the final reply. It relies on the MCP status snapshot collector, then shapes the raw snapshot into the client-facing ListMcpServerStatusResponse.

Call graph: 1 external calls (format!).

async fn read_mcp_resource(
        &self,
        request_id: &ConnectionRequestId,
        params: McpResourceReadParams,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Starts the process of reading a resource from an MCP server, either through a specific conversation thread or without a thread. The thread path uses that thread’s existing MCP runtime; the threadless path builds one from current config.

Data flow: It receives the request ID and parameters containing an optional thread ID, server name, and URI. If there is a thread ID, it loads the thread and starts a background task that asks the thread to read the resource. If there is no thread ID, it loads current config, builds MCP runtime config and context, and starts a background task that reads without a thread. In both cases, the eventual result is sent through the outgoing sender.

Call relations: McpRequestProcessor::mcp_resource_read calls this for client resource-read requests. It may use McpRequestProcessor::load_thread or McpRequestProcessor::load_latest_config, then spawns work and hands final response formatting to McpRequestProcessor::send_mcp_resource_read_response.

Call graph: calls 3 internal fn (load_latest_config, load_thread, new); called by 1 (mcp_resource_read); 4 external calls (clone, send_mcp_resource_read_response, clone, spawn).

async fn send_mcp_resource_read_response(
        outgoing: Arc<OutgoingMessageSender>,
        request_id: ConnectionRequestId,
        result: anyhow::Result<serde_json::Value>,
    )

Purpose: Converts the raw result of reading an MCP resource into the exact response type expected by the client, then sends it. This keeps both thread-based and threadless read paths using the same reply format.

Data flow: It receives the outgoing sender, the original request ID, and either a JSON value or an error. If there is an error, it turns it into an internal JSON-RPC error. If there is a JSON value, it tries to decode it as an McpResourceReadResponse; decoding failure also becomes an internal error. It then sends the final success or error result to the client.

Call relations: The background tasks started by McpRequestProcessor::read_mcp_resource call this after the resource read finishes. It is the final delivery step before the outgoing sender replies to the original request.

async fn call_mcp_server_tool(
        &self,
        request_id: &ConnectionRequestId,
        params: McpServerToolCallParams,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Starts a tool call against an MCP server inside a conversation thread. It makes sure the thread exists and adds the thread ID to the tool metadata before the call is made.

Data flow: It receives the request ID and tool-call parameters. It loads the thread named by the parameters, updates the metadata so it includes the thread ID when possible, and starts a background task. That task asks the thread to call the named server tool with the provided arguments, turns the result into a client response, and sends it back through the outgoing sender.

Call relations: McpRequestProcessor::mcp_server_tool_call calls this for client tool-call requests. It uses McpRequestProcessor::load_thread to find the conversation and with_mcp_tool_call_thread_id_meta to enrich metadata before handing the call to the thread.

Call graph: calls 2 internal fn (load_thread, with_mcp_tool_call_thread_id_meta); called by 1 (mcp_server_tool_call); 3 external calls (clone, clone, spawn).

fn with_mcp_tool_call_thread_id_meta(
    meta: Option<serde_json::Value>,
    thread_id: &str,
) -> Option<serde_json::Value>

Purpose: Adds the conversation thread ID to MCP tool-call metadata when the metadata is a JSON object or missing. This lets downstream tools know which thread caused the call.

Data flow: It receives optional JSON metadata and a thread ID string. If the metadata is an object, it inserts a threadId field into that object. If there is no metadata, it creates a new object containing threadId. If the metadata is some other JSON type, such as a string or array, it leaves it unchanged. The output is the updated optional metadata.

Call relations: McpRequestProcessor::call_mcp_server_tool calls this just before starting a tool call. The resulting metadata is passed along to the thread’s MCP tool-call operation.

Call graph: called by 1 (call_mcp_server_tool); 3 external calls (new, Object, String).

fn map_additional_context(
    additional_context: Option<HashMap<String, AdditionalContextEntry>>,
) -> BTreeMap<String, CoreAdditionalContextEntry>

Purpose: Converts extra context sent by the app-server client into the matching format used by the core conversation engine. This lets callers attach named pieces of information while preserving whether each piece is trusted application data or untrusted external data.

Data flow: It receives an optional map of context entries. If nothing was provided, it treats that as an empty map. For each entry, it copies the text value and translates the context kind into the core protocol’s kind, then returns the converted map sorted by key.

Call relations: When a new turn starts or a running turn is steered, the inner turn methods use this helper before sending input to the core thread. It is one of the small translation steps between the app-server API and the core protocol.

Call graph: called by 2 (turn_start_inner, turn_steer_inner).

fn new(
        auth_manager: Arc<AuthManager>,
        thread_manager: Arc<ThreadManager>,
        outgoing: Arc<OutgoingMessageSender>,
        analytics_events_client: AnalyticsEventsClient,

Purpose: Builds a TurnRequestProcessor with all the shared services it needs. Someone uses this when wiring the app server together so later request handlers can reuse the same processor.

Data flow: It receives references to managers, senders, configuration, state trackers, and watchers. It stores them in the processor without doing extra work. The result is a ready-to-use processor object.

Call relations: This is called during setup by the component that creates request processors. The returned object is later used by the initialized-client request handler to serve turn, settings, realtime, and review requests.

Call graph: called by 1 (new).

async fn turn_start(
        &self,
        request_id: ConnectionRequestId,
        params: TurnStartParams,
        app_server_client_name: Option<String>,
        app_server_client_version: Option<

Purpose: Receives a client request to start a new turn in an existing thread. It is the public request-facing wrapper that returns the response in the generic client payload shape.

Data flow: It takes the request id, turn parameters, and optional client name/version. It passes them to the deeper start logic, then wraps the successful turn-start response as a client response payload. Errors pass back unchanged as JSON-RPC errors.

Call relations: The initialized-client request dispatcher calls this for turn/start. This wrapper delegates to turn_start_inner, which does validation, thread lookup, settings conversion, and submission to the core thread.

Call graph: calls 1 internal fn (turn_start_inner); called by 1 (handle_initialized_client_request).

async fn thread_inject_items(
        &self,
        params: ThreadInjectItemsParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Receives a request to insert already-formed response items into a thread. This is useful when another part of the system needs to add items directly to the thread’s recorded conversation.

Data flow: It takes the injection parameters, sends them to the inner injection method, and wraps the result as a generic client response payload. If parsing or insertion fails, it returns a client-facing error.

Call relations: The initialized-client request dispatcher calls this for injection requests. It hands the real work to thread_inject_items_response_inner.

Call graph: calls 1 internal fn (thread_inject_items_response_inner); called by 1 (handle_initialized_client_request).

async fn thread_settings_update(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadSettingsUpdateParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Receives a client request to change settings for a thread, such as model, approvals, sandboxing, permissions, or personality. It is the request-facing wrapper around the settings update flow.

Data flow: It receives a request id and settings parameters. It calls the inner method that validates and submits the settings update, then wraps the empty success response for the client.

Call relations: The initialized-client request dispatcher calls this when a client sends thread/settings/update. It delegates to thread_settings_update_inner, which builds and submits the actual core settings operation.

Call graph: calls 1 internal fn (thread_settings_update_inner); called by 1 (handle_initialized_client_request).

async fn turn_steer(
        &self,
        request_id: &ConnectionRequestId,
        params: TurnSteerParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Receives extra user input meant to guide an already-running turn. Steering is like adding a note to someone while they are still working, rather than starting a new job.

Data flow: It takes the request id and steering parameters, calls the inner steering logic, and wraps the returned turn id for the client. Validation errors or core errors are returned as JSON-RPC errors.

Call relations: The initialized-client request dispatcher calls this for turn/steer. The wrapper relies on turn_steer_inner to check the active turn, convert input, and send the steering data to the thread.

Call graph: calls 1 internal fn (turn_steer_inner); called by 1 (handle_initialized_client_request).

async fn turn_interrupt(
        &self,
        request_id: &ConnectionRequestId,
        params: TurnInterruptParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Receives a request to stop startup work or interrupt an active turn. It is the public wrapper that adapts the inner interrupt result to the client response format.

Data flow: It accepts the request id and interrupt parameters, calls the inner interrupt method, and converts an optional interrupt response into the generic payload. Some interrupts respond immediately, while normal turn interrupts may wait for a later abort event.

Call relations: The initialized-client request dispatcher calls this for interrupt requests. It delegates to turn_interrupt_inner, which checks the target turn and submits the core interrupt operation.

Call graph: calls 1 internal fn (turn_interrupt_inner); called by 1 (handle_initialized_client_request).

async fn thread_realtime_start(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeStartParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Receives a request to begin a realtime conversation session for a thread. Realtime here means streaming-style interaction, such as voice or live text.

Data flow: It takes the request id and start parameters, calls the inner realtime-start logic, and wraps the optional response. If the client connection is already closed during listener setup, the response can be absent.

Call relations: The initialized-client request dispatcher calls this for realtime start requests. It delegates to thread_realtime_start_inner, which prepares the thread and submits the core start operation.

Call graph: calls 1 internal fn (thread_realtime_start_inner); called by 1 (handle_initialized_client_request).

async fn thread_realtime_append_audio(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendAudioParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCE

Purpose: Receives an audio chunk for an ongoing realtime conversation. It is the request-facing wrapper for sending that audio to the core thread.

Data flow: It accepts the request id and audio parameters, calls the inner append-audio method, and wraps the optional success response. Errors are returned if the thread is missing, unsupported, or the core operation fails.

Call relations: The initialized-client request dispatcher calls this while a realtime conversation is active. The actual preparation and core submission happen in thread_realtime_append_audio_inner.

Call graph: calls 1 internal fn (thread_realtime_append_audio_inner); called by 1 (handle_initialized_client_request).

async fn thread_realtime_append_text(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendTextParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErr

Purpose: Receives a text message for an ongoing realtime conversation. This lets clients add live text input to the same realtime flow used for voice or other streaming interaction.

Data flow: It takes the request id and text parameters, calls the inner text-append method, and wraps the optional success response. The text and role are passed onward to the core operation.

Call relations: The initialized-client request dispatcher calls this for realtime text input. It delegates to thread_realtime_append_text_inner.

Call graph: calls 1 internal fn (thread_realtime_append_text_inner); called by 1 (handle_initialized_client_request).

async fn thread_realtime_append_speech(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendSpeechParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRP

Purpose: Receives text that should be treated as speech input in a realtime conversation. This is different from raw audio: the client provides the spoken content as text.

Data flow: It receives the request id and speech text parameters, calls the inner speech-append method, and wraps the optional response. On success, the core thread receives a speech operation.

Call relations: The initialized-client request dispatcher calls this for realtime speech input. It delegates to thread_realtime_append_speech_inner.

Call graph: calls 1 internal fn (thread_realtime_append_speech_inner); called by 1 (handle_initialized_client_request).

async fn thread_realtime_stop(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeStopParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Receives a request to close an ongoing realtime conversation. It is the public wrapper around the core stop operation.

Data flow: It takes the request id and stop parameters, calls the inner stop method, and wraps the optional success response. If listener preparation shows the connection is closed, no response is sent.

Call relations: The initialized-client request dispatcher calls this for realtime stop requests. It delegates to thread_realtime_stop_inner.

Call graph: calls 1 internal fn (thread_realtime_stop_inner); called by 1 (handle_initialized_client_request).

async fn thread_realtime_list_voices(
        &self,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Returns the built-in list of voices available for realtime conversation. This lets clients show voice choices without starting a session.

Data flow: It takes no parameters from the request body. It asks the realtime voice list for the built-in voices, places them in a response object, and returns that as a client payload.

Call relations: The initialized-client request dispatcher calls this when a client asks for realtime voices. Unlike most methods here, it does not need a thread or core operation; it simply returns local built-in data.

Call graph: calls 1 internal fn (builtin); called by 1 (handle_initialized_client_request).

async fn review_start(
        &self,
        request_id: &ConnectionRequestId,
        params: ReviewStartParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Receives a request to start a code review. It is the request-facing wrapper that starts the review flow and normally sends the response separately.

Data flow: It accepts the request id and review parameters, calls the inner review-start logic, and maps success to no immediate generic payload. The review-start response is emitted through the outgoing message sender.

Call relations: The initialized-client request dispatcher calls this for review requests. It delegates to review_start_inner, which decides between inline and detached review.

Call graph: calls 1 internal fn (review_start_inner); called by 1 (handle_initialized_client_request).

fn track_error_response(
        &self,
        request_id: &ConnectionRequestId,
        error: &JSONRPCErrorError,
        error_type: Option<AnalyticsJsonRpcError>,
    )

Purpose: Records a failed JSON-RPC response for analytics. This helps the project understand which client requests fail and why, without changing the response itself.

Data flow: It receives the request id, the error object, and an optional analytics category. It extracts the connection id and request id, clones the error, and sends the information to the analytics client. Nothing is returned.

Call relations: Validation paths in turn start, turn steer, and direct-input checks call this before returning an error. It connects request-handling failures to the analytics system.

Call graph: calls 1 internal fn (track_error_response); called by 3 (ensure_direct_input_allowed, turn_start_inner, turn_steer_inner); 1 external calls (clone).

async fn load_thread(
        &self,
        thread_id: &str,
    ) -> Result<(ThreadId, Arc<CodexThread>), JSONRPCErrorError>

Purpose: Finds the core thread object for a thread id string supplied by a client. It also turns malformed or unknown ids into clear client-facing errors.

Data flow: It receives a thread id as text. First it parses the text into the internal thread id type; then it asks the thread manager for the corresponding thread. It returns both the parsed id and the thread object, or an invalid-request error.

Call relations: Most inner request handlers begin here, because they need a real thread before doing anything else. Realtime preparation, review start, item injection, settings updates, interrupts, turn start, and turn steer all depend on it.

Call graph: calls 1 internal fn (from_string); called by 7 (prepare_realtime_conversation_thread, review_start_inner, thread_inject_items_response_inner, thread_settings_update_inner, turn_interrupt_inner, turn_start_inner, turn_steer_inner).

async fn ensure_direct_input_allowed(
        &self,
        request_id: &ConnectionRequestId,
        thread: &CodexThread,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Blocks direct client input to a restricted kind of multi-agent sub-agent thread. This protects the multi-agent flow from outside messages being inserted where only the parent agent should control the sub-agent.

Data flow: It reads the thread’s multi-agent version and session source. If the thread is a version-2 sub-agent spawned by another thread, it creates and tracks an invalid-request error. Otherwise it returns success without changing anything.

Call relations: Turn start and turn steer call this after loading the thread. When it rejects input, it also uses track_error_response so the blocked request is visible in analytics.

Call graph: calls 2 internal fn (track_error_response, multi_agent_version); called by 2 (turn_start_inner, turn_steer_inner); 1 external calls (matches!).

fn normalize_collaboration_mode(
        &self,
        mut collaboration_mode: CollaborationMode,
    ) -> CollaborationMode

Purpose: Fills in missing developer instructions for a collaboration mode using built-in presets. This lets clients choose a named mode without having to resend all of its default instructions.

Data flow: It receives a collaboration mode object. If the object has no developer instructions, it searches the built-in presets for the selected mode and copies non-empty default instructions into the settings. It returns the possibly enriched mode.

Call relations: This helper is used while building thread settings overrides. It is part of the settings translation path before the final settings are previewed or submitted.

fn review_request_from_target(
        target: ApiReviewTarget,
    ) -> Result<(ReviewRequest, String), JSONRPCErrorError>

Purpose: Turns a client’s review target into the core review request format. It also cleans up user-provided strings and rejects empty branch names, commit SHAs, or custom instructions.

Data flow: It receives a target such as uncommitted changes, a base branch, a commit, or custom instructions. It trims and validates text fields, converts the target to the core type, asks the review prompt code for a human-readable hint, and returns both the core review request and the display hint.

Call relations: The review-start flow calls this before choosing inline or detached delivery. The returned request is what later gets submitted to the core thread as a review operation.

Call graph: 1 external calls (user_facing_hint).

async fn request_trace_context(
        &self,
        request_id: &ConnectionRequestId,
    ) -> Option<codex_protocol::protocol::W3cTraceContext>

Purpose: Looks up tracing information for the current request. A trace context is a set of identifiers that lets logs and downstream work be connected back to one client request.

Data flow: It receives a request id and asks the outgoing message sender for any stored trace context. It returns that context if one exists, or None if there is no trace information.

Call relations: Core submissions use this so the work they trigger can be traced. It is called directly by turn start and detached review creation, and indirectly through submit_core_op.

Call graph: called by 3 (start_detached_review, submit_core_op, turn_start_inner).

async fn submit_core_op(
        &self,
        request_id: &ConnectionRequestId,
        thread: &CodexThread,
        op: Op,
    ) -> CodexResult<String>

Purpose: Submits an operation to a core thread while attaching request trace information. It is the common doorway from app-server request handling into the core conversation engine.

Data flow: It receives the request id, a thread, and a core operation. It fetches trace context for the request, then asks the thread to submit the operation with that trace. It returns the core submission id or a core error.

Call relations: Settings updates, realtime start and append operations, realtime stop, reviews, and interrupts all use this helper. It keeps core submission behavior consistent across many request types.

Call graph: calls 2 internal fn (request_trace_context, submit_with_trace); called by 9 (start_detached_review, start_inline_review, thread_realtime_append_audio_inner, thread_realtime_append_speech_inner, thread_realtime_append_text_inner, thread_realtime_start_inner, thread_realtime_stop_inner, thread_settings_update_inner, turn_interrupt_inner).

fn input_too_large_error(actual_chars: usize) -> JSONRPCErrorError

Purpose: Builds the specific JSON-RPC error used when user input exceeds the allowed character limit. The extra error data helps clients show a useful message and recover gracefully.

Data flow: It receives the actual number of characters supplied. It creates an invalid-parameters error message and attaches structured data: the error code, the maximum allowed characters, and the actual count. It returns that error object.

Call relations: Input-size validation calls this when a request is too large. Turn start and turn steer then track and return the resulting error.

Call graph: 2 external calls (format!, json!).

fn validate_v2_input_limit(items: &[V2UserInput]) -> Result<(), JSONRPCErrorError>

Purpose: Checks that a list of version-2 user input items is not too large. This prevents a client from sending more text than the system is prepared to process.

Data flow: It receives the input items, counts the text characters across all of them, and compares the total with the maximum limit. If the total is too high, it returns the special too-large error; otherwise it returns success.

Call relations: Turn start and turn steer call this before converting and submitting user input. It uses input_too_large_error to create the client-facing failure.

Call graph: 2 external calls (input_too_large_error, iter).

async fn turn_start_inner(
        &self,
        request_id: ConnectionRequestId,
        params: TurnStartParams,
        app_server_client_name: Option<String>,
        app_server_client_version: O

Purpose: Performs the real work of starting a turn. It validates the request, translates client input and settings into core forms, submits the user input to the thread, and returns a new in-progress turn.

Data flow: It receives the request id, turn parameters, and client identity. It loads the thread, checks whether direct input is allowed, enforces the input size limit, stores client info, resolves environment and settings overrides, converts input items and extra context, and submits a user-input operation to the core thread. It records the resulting turn id and returns a turn object with in-progress status.

Call relations: turn_start calls this after the request dispatcher chooses the turn-start path. This method pulls together many helpers: thread loading, error tracking, context mapping, environment building, settings building, trace lookup, and memory-startup scheduling when real input was provided.

Call graph: calls 7 internal fn (build_environment_override, build_thread_settings_overrides, ensure_direct_input_allowed, load_thread, request_trace_context, track_error_response, map_additional_context); called by 1 (turn_start); 6 external calls (clone, set_app_server_client_info, validate_v2_input_limit, Input, start_memories_startup_task, vec!).

async fn build_environment_override(
        &self,
        thread: &CodexThread,
        cwd: Option<AbsolutePathBuf>,
        environment_selections: Option<Vec<TurnEnvironmentSelection>>,
    ) ->

Purpose: Builds the environment selection override for a turn or settings update. This decides which working directory and environment choices the core thread should use for the request.

Data flow: It receives a thread, an optional current working directory, and optional environment selections. If neither is present, it returns no override. If only a directory is present, it asks the thread manager for default selections. If selections are present, it chooses a fallback directory from the request, local environment selection, or thread snapshot, then returns a complete environment selection object.

Call relations: Turn start and thread settings update call this before building thread settings. It feeds the environment part of the settings overrides sent to the core thread.

Call graph: calls 2 internal fn (config_snapshot, new); called by 2 (thread_settings_update_inner, turn_start_inner).

async fn build_thread_settings_overrides(
        &self,
        thread: &CodexThread,
        params: ThreadSettingsBuildParams,
    ) -> Result<codex_protocol::protocol::ThreadSettingsOverrides, JSO

Purpose: Converts optional client-supplied thread settings into validated core settings overrides. It protects against invalid combinations, such as sending both permissions and sandboxPolicy.

Data flow: It receives a thread and a bundle of possible settings changes. It normalizes collaboration mode, resolves workspace roots, converts approval and sandbox choices to core types, and, if permissions are named, loads configuration for the relevant directory to compute the permission profile. If anything was changed, it asks the thread to preview the overrides so invalid settings are rejected before submission. It returns the final core override object.

Call relations: Turn start and thread settings update both use this before sending settings to the core thread. It depends on configuration loading and thread preview checks so request handlers do not accept settings the thread cannot actually use.

Call graph: calls 3 internal fn (load_for_cwd, config_snapshot, preview_thread_settings_overrides); called by 2 (thread_settings_update_inner, turn_start_inner); 2 external calls (default, format!).

async fn thread_settings_update_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadSettingsUpdateParams,
    ) -> Result<ThreadSettingsUpdateResponse, JSONRPCErrorEr

Purpose: Applies a client-requested settings update to an existing thread. It queues a core settings operation only when there is something to change.

Data flow: It loads the target thread, resolves an optional working directory, builds validated settings overrides, and compares them with the default empty override. If changes exist, it submits a ThreadSettings operation to the core thread. It returns an empty success response once the update has been accepted for processing.

Call relations: thread_settings_update calls this for client settings requests. It shares the same environment and settings-building helpers used by turn start, then submits through submit_core_op.

Call graph: calls 4 internal fn (build_environment_override, build_thread_settings_overrides, load_thread, submit_core_op); called by 1 (thread_settings_update); 1 external calls (default).

async fn thread_inject_items_response_inner(
        &self,
        params: ThreadInjectItemsParams,
    ) -> Result<ThreadInjectItemsResponse, JSONRPCErrorError>

Purpose: Adds serialized response items directly into a thread after validating their shape. This is a controlled way to insert conversation items that are already represented as raw JSON values.

Data flow: It loads the thread, then walks through the supplied JSON items one by one and parses each into a ResponseItem. If any item is invalid, it reports which array position failed. If all parse correctly, it asks the thread to inject them and returns an empty success response.

Call relations: thread_inject_items calls this for injection requests. It talks directly to the thread’s item-injection API rather than submitting a normal turn operation.

Call graph: calls 1 internal fn (load_thread); called by 1 (thread_inject_items).

async fn set_app_server_client_info(
        thread: &CodexThread,
        app_server_client_name: Option<String>,
        app_server_client_version: Option<String>,
    ) -> Result<(), JSONRPCErrorEr

Purpose: Stores the app-server client name and version on the thread, along with a compatibility flag for one older Xcode client line. This lets core behavior adapt to client capabilities.

Data flow: It receives a thread and optional client name/version. It checks whether the client is Xcode 26.4 and should auto-deny MCP elicitation requests, then asks the thread to save the client information and flag. It returns success or an internal error.

Call relations: The turn-start flow calls this before submitting user input. It uses xcode_26_4_mcp_elicitations_auto_deny for the compatibility decision.

Call graph: calls 2 internal fn (xcode_26_4_mcp_elicitations_auto_deny, set_app_server_client_info).

async fn turn_steer_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: TurnSteerParams,
    ) -> Result<TurnSteerResponse, JSONRPCErrorError>

Purpose: Performs the real work of steering an active turn with additional input. It makes sure the caller names the expected active turn and turns core steering failures into clear client errors.

Data flow: It loads the thread, checks direct-input rules, verifies that expectedTurnId is not empty, records that turn id for the request, enforces the input size limit, converts input and extra context, and calls the thread’s steering API. It returns the turn id accepted by the core thread, or a detailed error for cases like no active turn, mismatched turn id, non-steerable review/compact turns, or empty input.

Call relations: turn_steer calls this. It uses the same thread loading, direct-input guard, input validation, context mapping, and analytics error tracking patterns as turn start.

Call graph: calls 4 internal fn (ensure_direct_input_allowed, load_thread, track_error_response, map_additional_context); called by 1 (turn_steer); 2 external calls (validate_v2_input_limit, Input).

async fn prepare_realtime_conversation_thread(
        &self,
        request_id: &ConnectionRequestId,
        thread_id: &str,
    ) -> Result<Option<(ThreadId, Arc<CodexThread>)>, JSONRPCErrorError

Purpose: Prepares a thread for realtime conversation requests. It makes sure the client is listening for events and that the thread supports realtime conversation.

Data flow: It receives a request id and thread id string. It loads the thread, attaches or confirms a conversation listener for the request’s connection, and checks the thread feature flag for realtime conversation. It returns the thread when ready, None if the connection is already closed, or an error if the thread cannot support the request.

Call relations: Every realtime inner method calls this before submitting its core operation. It uses ensure_conversation_listener so realtime events have somewhere to go.

Call graph: calls 2 internal fn (ensure_conversation_listener, load_thread); called by 5 (thread_realtime_append_audio_inner, thread_realtime_append_speech_inner, thread_realtime_append_text_inner, thread_realtime_start_inner, thread_realtime_stop_inner); 1 external calls (format!).

async fn thread_realtime_start_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeStartParams,
    ) -> Result<Option<ThreadRealtimeStartResponse>, JSONRPCEr

Purpose: Starts a realtime conversation in a prepared thread. It packages client options such as model, voice, transport, and output mode into the core start operation.

Data flow: It prepares the thread, returns no response if the client connection closed, converts the requested transport into the core transport type, fills defaults for optional booleans, and submits a RealtimeConversationStart operation. On success it returns the default start response.

Call relations: thread_realtime_start calls this. It relies on prepare_realtime_conversation_thread first, then submits through submit_core_op.

Call graph: calls 2 internal fn (prepare_realtime_conversation_thread, submit_core_op); called by 1 (thread_realtime_start); 2 external calls (default, RealtimeConversationStart).

async fn thread_realtime_append_audio_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendAudioParams,
    ) -> Result<Option<ThreadRealtimeAppendAudioR

Purpose: Sends one audio frame into an active realtime conversation. This is how streamed microphone data reaches the core conversation engine.

Data flow: It prepares the realtime thread, converts the provided audio frame into the core frame type, and submits a RealtimeConversationAudio operation. On success it returns the default append-audio response, or no response if the connection closed during preparation.

Call relations: thread_realtime_append_audio calls this. It follows the common realtime pattern: prepare listener and thread, then submit a core operation.

Call graph: calls 2 internal fn (prepare_realtime_conversation_thread, submit_core_op); called by 1 (thread_realtime_append_audio); 2 external calls (default, RealtimeConversationAudio).

async fn thread_realtime_append_text_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendTextParams,
    ) -> Result<Option<ThreadRealtimeAppendTextResp

Purpose: Sends live text into an active realtime conversation. The text includes a role so the core engine knows who the message represents.

Data flow: It prepares the realtime thread, puts the request’s text and role into core conversation text parameters, and submits a RealtimeConversationText operation. It returns the default success response when accepted.

Call relations: thread_realtime_append_text calls this. Like the other realtime append methods, it depends on prepare_realtime_conversation_thread and submit_core_op.

Call graph: calls 2 internal fn (prepare_realtime_conversation_thread, submit_core_op); called by 1 (thread_realtime_append_text); 2 external calls (default, RealtimeConversationText).

async fn thread_realtime_append_speech_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeAppendSpeechParams,
    ) -> Result<Option<ThreadRealtimeAppendSpee

Purpose: Sends speech-as-text into an active realtime conversation. This gives the core engine spoken content without requiring raw audio bytes.

Data flow: It prepares the realtime thread, wraps the provided text in speech parameters, and submits a RealtimeConversationSpeech operation. It returns the default success response if the operation is accepted.

Call relations: thread_realtime_append_speech calls this. It shares the same preparation and submission flow as realtime audio and text.

Call graph: calls 2 internal fn (prepare_realtime_conversation_thread, submit_core_op); called by 1 (thread_realtime_append_speech); 2 external calls (default, RealtimeConversationSpeech).

async fn thread_realtime_stop_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRealtimeStopParams,
    ) -> Result<Option<ThreadRealtimeStopResponse>, JSONRPCError

Purpose: Stops an active realtime conversation for a thread. It tells the core engine to close the realtime session.

Data flow: It prepares the realtime thread and then submits a RealtimeConversationClose operation. On success it returns the default stop response, unless preparation found that the connection had already closed.

Call relations: thread_realtime_stop calls this. It uses the common realtime preparation helper and the shared core-operation submission helper.

Call graph: calls 2 internal fn (prepare_realtime_conversation_thread, submit_core_op); called by 1 (thread_realtime_stop); 1 external calls (default).

fn build_review_turn(turn_id: String, display_text: &str) -> Turn

Purpose: Creates the client-facing Turn object used when a review starts. It gives the UI an in-progress turn, optionally containing a synthesized user message that describes what is being reviewed.

Data flow: It receives a turn id and display text. If the display text is empty, it creates a turn with no items. Otherwise it creates a user-message item containing that text. It returns an in-progress turn with no error or timing information yet.

Call relations: Inline and detached review flows call this after submitting the core review operation. The resulting turn is sent to the client by emit_review_started.

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

async fn emit_review_started(
        &self,
        request_id: &ConnectionRequestId,
        turn: Turn,
        review_thread_id: String,
    )

Purpose: Sends the review-start response to the client. This response includes the in-progress review turn and the thread id where the review is running.

Data flow: It receives the request id, the constructed turn, and the review thread id string. It wraps them in a review-start response and sends that response through the outgoing message sender. It does not return a payload to the caller.

Call relations: Both inline and detached review starters call this after they have a core turn id. It is why review_start can complete without returning a normal immediate payload.

Call graph: called by 2 (start_detached_review, start_inline_review); 1 external calls (clone).

async fn start_inline_review(
        &self,
        request_id: &ConnectionRequestId,
        parent_thread: Arc<CodexThread>,
        review_request: ReviewRequest,
        display_text: &str,

Purpose: Starts a review inside the existing parent thread. This keeps the review as another turn in the same conversation.

Data flow: It receives the request id, parent thread, core review request, display text, and parent thread id string. It submits a review operation to the parent thread, builds a client-facing review turn from the returned turn id, sends the review-start response, and returns success.

Call relations: review_start_inner calls this when the requested delivery is inline. It uses submit_core_op, build_review_turn, and emit_review_started in sequence.

Call graph: calls 2 internal fn (emit_review_started, submit_core_op); called by 1 (review_start_inner); 1 external calls (build_review_turn).

async fn start_detached_review(
        &self,
        request_id: &ConnectionRequestId,
        parent_thread_id: ThreadId,
        parent_thread: Arc<CodexThread>,
        review_request: ReviewRequ

Purpose: Starts a review in a newly forked thread instead of the parent thread. This lets the review run separately while still starting from the parent conversation’s history.

Data flow: It first makes sure the parent thread’s stored rollout is current, then loads the parent history. It clones the server config, optionally switches to the configured review model, and asks the thread manager to fork a new thread from the parent history. It attaches a listener, updates thread-watch state and sends a thread-started notification when possible, submits the review operation to the new thread, builds the review turn, and sends the review-start response with the new thread id.

Call relations: review_start_inner calls this when detached delivery is requested. It coordinates thread persistence, thread creation, listener attachment, watch-state notification, core review submission, and response emission.

Call graph: calls 6 internal fn (emit_review_started, ensure_conversation_listener, request_trace_context, submit_core_op, loaded_status_for_thread, upsert_thread_silently); called by 1 (review_start_inner); 4 external calls (build_review_turn, ThreadStarted, Resumed, warn!).

async fn review_start_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ReviewStartParams,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Runs the main review-start decision flow. It validates the target, loads the parent thread, and chooses whether the review should be inline or detached.

Data flow: It receives the parent thread id, review target, and optional delivery choice. It loads the parent thread, converts the target into a core review request plus display text, defaults delivery to inline if missing, and calls either the inline or detached review starter. It returns success after the chosen starter sends the response.

Call relations: review_start calls this. It relies on load_thread, review_request_from_target, start_inline_review, and start_detached_review.

Call graph: calls 3 internal fn (load_thread, start_detached_review, start_inline_review); called by 1 (review_start); 1 external calls (review_request_from_target).

async fn turn_interrupt_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: TurnInterruptParams,
    ) -> Result<Option<TurnInterruptResponse>, JSONRPCErrorError>

Purpose: Performs the real work of interrupting startup or an active turn. It carefully records normal turn interrupts so the server can answer when the core later reports that the turn was aborted.

Data flow: It receives the thread id and turn id. An empty turn id means startup interrupt. It loads the thread, and for normal turn interrupts it checks thread state to make sure the requested turn is active or plausibly running, records the pending interrupt request, and records the turn id for outgoing tracking. It submits an interrupt operation to the core thread. Startup interrupts return immediately; normal turn interrupts usually return later. If submission fails, it removes the pending interrupt record.

Call relations: turn_interrupt calls this. It combines thread lookup, thread-state inspection, outgoing request tracking, and submit_core_op to make interrupt responses line up with later turn-aborted events.

Call graph: calls 3 internal fn (load_thread, submit_core_op, thread_state); called by 1 (turn_interrupt); 3 external calls (clone, format!, matches!).

fn listener_task_context(&self) -> ListenerTaskContext

Purpose: Builds the bundle of shared services needed by background listener tasks. A listener task watches a core thread and forwards its events to connected clients.

Data flow: It copies or clones references to the thread manager, thread state manager, outgoing sender, unload set, watch manager, semaphore, fallback model provider, Codex home path, and skills watcher. It returns them as a ListenerTaskContext.

Call relations: ensure_conversation_listener calls this before delegating to the thread lifecycle code. It keeps listener setup from needing direct access to every field on TurnRequestProcessor.

Call graph: called by 1 (ensure_conversation_listener); 3 external calls (clone, clone, clone).

async fn ensure_conversation_listener(
        &self,
        conversation_id: ThreadId,
        connection_id: ConnectionId,
        raw_events_enabled: bool,
    ) -> Result<EnsureConversationListen

Purpose: Makes sure a client connection has a listener attached to a thread. Without this, the client might start realtime work or a detached review but never receive the resulting events.

Data flow: It receives a conversation id, connection id, and a flag for raw event forwarding. It builds a listener context and passes everything to the thread lifecycle helper. It returns whether a listener was attached, the connection was closed, or an error occurred.

Call relations: Realtime preparation calls this before realtime operations, and detached review startup calls it for the newly forked review thread. Internally it delegates to the shared thread-lifecycle listener function.

Call graph: calls 2 internal fn (ensure_conversation_listener, listener_task_context); called by 2 (prepare_realtime_conversation_thread, start_detached_review).

fn xcode_26_4_mcp_elicitations_auto_deny(
    client_name: Option<&str>,
    client_version: Option<&str>,
) -> bool

Purpose: Detects one older Xcode client line that should automatically deny MCP elicitation requests. This is a compatibility workaround for a client version that shipped before those requests were visible to users.

Data flow: It receives optional client name and version strings. It returns true only when the name is exactly Xcode and the version starts with 26.4; otherwise it returns false.

Call relations: set_app_server_client_info calls this before saving client information on the thread. The result changes how the core thread treats MCP elicitation behavior for that client.

Call graph: called by 1 (set_app_server_client_info).

fn new(
        outgoing: Arc<OutgoingMessageSender>,
        config: Arc<Config>,
        config_manager: ConfigManager,
    ) -> Self

Purpose: Creates a Windows sandbox request processor with the shared pieces it needs: outgoing client messaging, current configuration, and a configuration loader. This is used when the server is wiring together its request-processing components.

Data flow: It receives shared references to the outgoing message sender and configuration, plus a configuration manager. It stores those values inside a new processor object. The result is a ready-to-use processor that can answer sandbox requests later.

Call relations: A higher-level constructor calls this while assembling the server’s request processors. After that, request-handling code can use the returned processor for readiness checks and setup requests.

Call graph: called by 1 (new).

async fn windows_sandbox_readiness(
        &self,
    ) -> Result<WindowsSandboxReadinessResponse, JSONRPCErrorError>

Purpose: Answers the client’s question: “Is Windows sandbox support ready to use?” It wraps the readiness check in the request processor’s async interface so it can be called as part of normal client request handling.

Data flow: It reads the processor’s current configuration, passes it to the readiness helper, and returns the resulting readiness response. It does not change files, settings, or server state.

Call relations: The initialized client request handler calls this when a client asks about sandbox readiness. This function delegates the actual decision to determine_windows_sandbox_readiness and sends the answer back through the normal request-response path.

Call graph: calls 1 internal fn (determine_windows_sandbox_readiness); called by 1 (handle_initialized_client_request).

async fn windows_sandbox_setup_start(
        &self,
        request_id: &ConnectionRequestId,
        params: WindowsSandboxSetupStartParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErr

Purpose: Starts the Windows sandbox setup flow for a client request. Its public-facing job is to trigger setup and return no normal response payload because the real status comes later as a notification.

Data flow: It receives the request id and setup parameters, passes both into the inner setup routine, and converts a successful empty result into an empty optional client response. If setup cannot even be started, it returns an error instead.

Call relations: The initialized client request handler calls this when a client asks to begin setup. It keeps the outer request API simple and hands the real work to windows_sandbox_setup_start_inner.

Call graph: calls 1 internal fn (windows_sandbox_setup_start_inner); called by 1 (handle_initialized_client_request).

async fn windows_sandbox_setup_start_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: WindowsSandboxSetupStartParams,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Performs the careful start-up sequence for Windows sandbox setup. It validates that the requested mode is allowed, acknowledges the request, then launches the longer setup operation in the background.

Data flow: It starts with the client request id and setup parameters, including an optional working folder and requested setup mode. It chooses a working folder, reloads configuration for that folder, checks whether the requested sandbox mode is permitted, then sends an immediate “started” response. After that, it spawns a background task that builds a setup request using permissions, workspace roots, environment variables, and the Codex home folder. When setup finishes, it sends a completion notification with the chosen mode, whether it succeeded, and any error text.

Call relations: windows_sandbox_setup_start calls this as the real implementation. Inside, it asks the configuration manager to load settings for the relevant folder, uses resolve_allowed_windows_sandbox_setup_mode to enforce policy, calls the core Windows sandbox setup routine, and finally uses the outgoing message sender to notify the original connection when setup is done.

Call graph: calls 3 internal fn (load_for_cwd, resolve_allowed_windows_sandbox_setup_mode, run_windows_sandbox_setup); called by 1 (windows_sandbox_setup_start); 6 external calls (clone, default, WindowsSandboxSetupCompleted, clone, vars, spawn).

fn resolve_allowed_windows_sandbox_setup_mode(
    requirements: &codex_config::ConfigRequirements,
    requested_mode: WindowsSandboxSetupMode,
) -> Result<CoreWindowsSandboxSetupMode, JSONRPCErrorEr

Purpose: Checks whether the setup mode requested by the client is allowed by the current configuration requirements. This prevents the server from starting a sandbox setup mode that policy says cannot be saved or used.

Data flow: It receives the managed configuration requirements and the requested API mode, either elevated or unelevated. It translates that request into the core setup mode and the configuration-file form of the same choice, asks the requirements whether that value is allowed, and returns either the core mode or an invalid-request error.

Call relations: windows_sandbox_setup_start_inner uses this before acknowledging setup, so clients do not get a false “started” response for a forbidden mode. A unit test also calls it directly to prove that disallowed modes are rejected with the right kind of error.

Call graph: called by 2 (windows_sandbox_setup_start_inner, resolve_allowed_windows_sandbox_setup_mode_rejects_disallowed_mode).

fn determine_windows_sandbox_readiness(config: &Config) -> WindowsSandboxReadinessResponse

Purpose: Decides the current Windows sandbox readiness from the real configuration and platform. It is the bridge between the server’s stored settings and the simpler readiness answer sent to clients.

Data flow: It receives the current configuration. If the program is not running on Windows, it returns “not configured.” On Windows, it reads the configured sandbox level, checks whether elevated sandbox setup has already been completed under the Codex home folder, and passes those facts to the state-based readiness helper.

Call relations: windows_sandbox_readiness calls this to answer a client request. This function keeps platform and configuration lookup in one place, then relies on determine_windows_sandbox_readiness_from_state for the final status rules.

Call graph: calls 1 internal fn (determine_windows_sandbox_readiness_from_state); called by 1 (windows_sandbox_readiness); 2 external calls (cfg!, from_config).

fn determine_windows_sandbox_readiness_from_state(
    windows_sandbox_level: WindowsSandboxLevel,
    sandbox_setup_is_complete: bool,
) -> WindowsSandboxReadinessResponse

Purpose: Turns two simple facts into a client-facing readiness status: the configured sandbox level and whether setup is complete. This small rule table is easy to test because it does not need real files or a real Windows machine.

Data flow: It receives a sandbox level and a true-or-false setup-complete flag. Disabled becomes “not configured,” restricted-token mode becomes “ready,” and elevated mode becomes “ready” only when setup is complete; otherwise it becomes “update required.” It returns a readiness response containing that status.

Call relations: determine_windows_sandbox_readiness calls this after gathering real state. Several tests call it directly with hand-picked inputs to verify each important readiness outcome.

Call graph: called by 5 (determine_windows_sandbox_readiness, determine_windows_sandbox_readiness_reports_not_configured_when_disabled, determine_windows_sandbox_readiness_reports_ready_for_complete_elevated_mode, determine_windows_sandbox_readiness_reports_ready_for_unelevated_mode, determine_windows_sandbox_readiness_reports_update_required_when_elevated_setup_is_stale).

fn resolve_allowed_windows_sandbox_setup_mode_rejects_disallowed_mode()

Purpose: Checks that the mode validator refuses a setup mode that configuration requirements do not allow. This protects the policy-enforcement behavior from accidental changes.

Data flow: It builds requirements that allow only elevated sandbox mode, then asks to resolve unelevated mode. The expected result is an invalid-request error whose message says the sandbox setup mode is invalid.

Call relations: This test calls resolve_allowed_windows_sandbox_setup_mode directly. It stands as a focused safety check for the validation step used before setup is started.

Call graph: calls 3 internal fn (resolve_allowed_windows_sandbox_setup_mode, new, allow_only); 3 external calls (default, assert!, assert_eq!).

fn determine_windows_sandbox_readiness_reports_not_configured_when_disabled()

Purpose: Verifies that a disabled sandbox configuration is reported to clients as not configured. This confirms the simplest “feature is off” case.

Data flow: It passes the disabled sandbox level and a false setup-complete flag into the state-based readiness helper. It expects the returned status to be “not configured.”

Call relations: This test calls determine_windows_sandbox_readiness_from_state directly, checking one branch of the rule table used by the real readiness request path.

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

fn determine_windows_sandbox_readiness_reports_ready_for_unelevated_mode()

Purpose: Verifies that restricted-token, or unelevated, sandbox mode is considered ready without needing the separate elevated setup step.

Data flow: It passes the restricted-token sandbox level and a false setup-complete flag into the readiness helper. It expects the returned status to be “ready.”

Call relations: This test calls determine_windows_sandbox_readiness_from_state directly. It protects the rule that unelevated sandboxing does not depend on the setup-complete marker.

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

fn determine_windows_sandbox_readiness_reports_ready_for_complete_elevated_mode()

Purpose: Verifies that elevated sandbox mode is reported as ready after its setup has been completed. This confirms the happy path for the stronger sandbox mode.

Data flow: It passes the elevated sandbox level and a true setup-complete flag into the readiness helper. It expects the returned status to be “ready.”

Call relations: This test calls determine_windows_sandbox_readiness_from_state directly. It checks the same rule that the real readiness request uses after looking for completed setup on disk.

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

fn determine_windows_sandbox_readiness_reports_update_required_when_elevated_setup_is_stale()

Purpose: Verifies that elevated sandbox mode reports “update required” when setup is missing or stale. This tells clients they need to run setup before relying on that mode.

Data flow: It passes the elevated sandbox level and a false setup-complete flag into the readiness helper. It expects the returned status to be “update required.”

Call relations: This test calls determine_windows_sandbox_readiness_from_state directly. It protects the warning path used when elevated sandbox configuration exists but the machine has not been prepared yet.

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

fn collect_resume_override_mismatches(
    request: &ThreadResumeParams,
    config_snapshot: &ThreadConfigSnapshot,
) -> Vec<String>

Purpose: Checks whether a client trying to resume an already running thread asked for settings that differ from the thread’s current settings. It explains each mismatch so the server can warn or decide whether a cold restart is needed.

Data flow: It receives resume parameters and a live configuration snapshot, compares fields like model, provider, working directory, sandbox, permissions, and instructions, and returns a list of human-readable mismatch messages.

Call relations: When resume_running_thread finds that the target thread is already loaded, it calls this helper before deciding whether to simply rejoin the live thread or shut down an idle cached thread and resume fresh.

Call graph: calls 2 internal fn (cwd, sandbox_policy); called by 1 (resume_running_thread); 4 external calls (new, format!, matches!, from).

fn merge_persisted_resume_metadata(
    request_overrides: &mut Option<HashMap<String, serde_json::Value>>,
    typesafe_overrides: &mut ConfigOverrides,
    persisted_metadata: &ThreadMetadata,
)

Purpose: Fills in model-related resume settings from saved thread metadata when the client did not explicitly override them. This helps resumed threads keep using the model they originally used.

Data flow: It receives mutable request overrides, typed config overrides, and saved metadata; if no model override is already present, it copies the saved model, provider, and reasoning effort into the override structures.

Call relations: load_and_apply_persisted_resume_metadata calls this during cold resume so the later configuration load starts from the saved thread’s model choices.

Call graph: calls 1 internal fn (has_model_resume_override); called by 1 (load_and_apply_persisted_resume_metadata); 1 external calls (String).

fn normalize_thread_list_cwd_filters(
    cwd: Option<ThreadListCwdFilter>,
) -> Result<Option<Vec<PathBuf>>, JSONRPCErrorError>

Purpose: Turns a client’s working-directory filter for thread listing into normalized absolute paths. This makes path comparisons reliable even if the client used relative paths.

Data flow: It receives either no filter, one path, or many paths; it resolves each path against the current directory and returns either no filter or a list of normalized paths, or an invalid-parameters error.

Call relations: thread_list_response_inner uses this before asking storage for matching threads, so later filtering compares paths in a consistent form.

Call graph: calls 1 internal fn (relative_to_current_dir); called by 1 (thread_list_response_inner); 2 external calls (with_capacity, vec!).

fn has_model_resume_override(
    request_overrides: Option<&HashMap<String, serde_json::Value>>,
    typesafe_overrides: &ConfigOverrides,
) -> bool

Purpose: Answers whether the resume request already contains any model-related override. It prevents saved metadata from accidentally overwriting an explicit client choice.

Data flow: It reads typed overrides and raw JSON override keys, checks for model, provider, or reasoning effort settings, and returns true or false.

Call relations: merge_persisted_resume_metadata calls it as a guard before adding model information from persisted metadata.

Call graph: called by 1 (merge_persisted_resume_metadata).

fn validate_dynamic_tools(tools: &[DynamicToolSpec]) -> Result<(), String>

Purpose: Checks that client-provided dynamic tools have safe names, valid namespaces, no duplicates, and supported input schemas. This protects the model tool interface from malformed or reserved tool definitions.

Data flow: It receives a list of tool specifications, validates names, lengths, namespace descriptions, reserved words, duplicate names, deferred-loading rules, and schemas, then returns success or a clear error string.

Call relations: thread_start_task calls this just before creating a new thread, so bad tool definitions are rejected before they reach the core thread engine.

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

fn new(
        auth_manager: Arc<AuthManager>,
        thread_manager: Arc<ThreadManager>,
        outgoing: Arc<OutgoingMessageSender>,
        arg0_paths: Arg0DispatchPaths,
        config: Arc<Con

Purpose: Builds a ThreadRequestProcessor with all the services it needs. It is the constructor that gathers authentication, thread storage, configuration, outgoing messaging, live-state tracking, and watchers into one request-handling object.

Data flow: It receives shared service handles and stores them on the processor, also creating a task tracker for background work; it returns the ready processor.

Call relations: The server setup code calls this once when wiring request processors, and all later thread API methods use the stored services.

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

async fn thread_start(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadStartParams,
        app_server_client_name: Option<String>,
        app_server_client_version: Opt

Purpose: Public handler for the client’s thread/start request. It starts the deeper start flow and returns no immediate payload because the background task sends the response itself.

Data flow: It receives a request id, start parameters, client identity, and tracing context, forwards them to thread_start_inner, and maps successful completion to no direct response payload.

Call relations: handle_initialized_client_request calls this when a client asks to start a thread; it delegates all real work to thread_start_inner.

Call graph: calls 1 internal fn (thread_start_inner); called by 1 (handle_initialized_client_request).

async fn thread_unsubscribe(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadUnsubscribeParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for unsubscribing a connection from updates for a thread. It returns whether the connection was unsubscribed, was not subscribed, or the thread was not loaded.

Data flow: It receives request and unsubscribe parameters, calls the inner unsubscribe logic with the connection id, and wraps the response for the client.

Call relations: handle_initialized_client_request calls this for thread/unsubscribe; thread_unsubscribe_response_inner performs the state update.

Call graph: calls 1 internal fn (thread_unsubscribe_response_inner); called by 1 (handle_initialized_client_request).

async fn thread_resume(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadResumeParams,
        app_server_client_name: Option<String>,
        app_server_client_version: O

Purpose: Public handler for resuming or rejoining a thread. It kicks off the resume flow and lets that flow send responses or errors through the outgoing channel.

Data flow: It receives the request id, resume parameters, and client identity, forwards them to thread_resume_inner, and returns no direct response payload on success.

Call relations: handle_initialized_client_request calls this for thread/resume; thread_resume_inner handles both already-running and cold-resume cases.

Call graph: calls 1 internal fn (thread_resume_inner); called by 1 (handle_initialized_client_request).

async fn thread_fork(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadForkParams,
        app_server_client_name: Option<String>,
        app_server_client_version: Optio

Purpose: Public handler for creating a new thread from an existing thread’s history. Forking lets a client branch from a previous conversation state.

Data flow: It receives fork parameters and client identity, delegates to thread_fork_inner, and returns no direct payload because the inner flow sends the response.

Call relations: handle_initialized_client_request calls this for thread/fork; thread_fork_inner performs storage reads, thread creation, listener attachment, and response sending.

Call graph: calls 1 internal fn (thread_fork_inner); called by 1 (handle_initialized_client_request).

async fn thread_archive(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadArchiveParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for archiving a thread and any spawned descendants that should be archived with it. It also broadcasts archive notifications.

Data flow: It receives an archive request, calls the archive inner flow, sends the JSON-RPC response, then sends a server notification for each archived thread id.

Call relations: handle_initialized_client_request calls this for thread/archive; thread_archive_inner and thread_archive_response do the actual storage and teardown work.

Call graph: calls 1 internal fn (thread_archive_inner); called by 1 (handle_initialized_client_request); 2 external calls (ThreadArchived, clone).

async fn thread_increment_elicitation(
        &self,
        params: ThreadIncrementElicitationParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler that tells a thread an out-of-band elicitation is active. An elicitation is a side request for user input, and the count can pause other work.

Data flow: It receives the target thread id, delegates to the inner counter increment, and returns the new count plus whether the thread is paused.

Call relations: handle_initialized_client_request calls this; thread_increment_elicitation_inner loads the live thread and updates its counter.

Call graph: calls 1 internal fn (thread_increment_elicitation_inner); called by 1 (handle_initialized_client_request).

async fn thread_decrement_elicitation(
        &self,
        params: ThreadDecrementElicitationParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler that marks one out-of-band elicitation as finished. It lets the thread resume once the count reaches zero.

Data flow: It receives the target thread id, delegates to the inner decrement, and returns the new count plus whether any elicitation still pauses the thread.

Call relations: handle_initialized_client_request calls this; thread_decrement_elicitation_inner performs validation and updates the live thread.

Call graph: calls 1 internal fn (thread_decrement_elicitation_inner); called by 1 (handle_initialized_client_request).

async fn thread_set_name(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadSetNameParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for renaming a thread. It updates stored metadata and notifies clients when the visible name changes.

Data flow: It receives a request id and name parameters, calls the inner update, sends the response, and optionally sends a ThreadNameUpdated notification.

Call relations: handle_initialized_client_request calls this; thread_set_name_response_inner validates and writes the new name.

Call graph: calls 1 internal fn (thread_set_name_response_inner); called by 1 (handle_initialized_client_request); 2 external calls (ThreadNameUpdated, clone).

async fn thread_metadata_update(
        &self,
        params: ThreadMetadataUpdateParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for updating extra thread metadata, currently focused on Git information. Git is the version-control system data attached to a thread.

Data flow: It receives metadata update parameters, delegates to the inner update, and returns the updated thread view.

Call relations: handle_initialized_client_request calls this; thread_metadata_update_response_inner validates and writes the metadata patch.

Call graph: calls 1 internal fn (thread_metadata_update_response_inner); called by 1 (handle_initialized_client_request).

async fn thread_memory_mode_set(
        &self,
        params: ThreadMemoryModeSetParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for changing a thread’s memory mode. This affects how the thread should use saved memory features.

Data flow: It receives a thread id and mode, delegates to the inner metadata update, and returns an empty success response.

Call relations: handle_initialized_client_request calls this; thread_memory_mode_set_response_inner writes the new mode to thread metadata.

Call graph: calls 1 internal fn (thread_memory_mode_set_response_inner); called by 1 (handle_initialized_client_request).

async fn memory_reset(
        &self,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for clearing stored memory data. This is a global reset, not just a single-thread operation.

Data flow: It calls the inner memory reset routine and converts the success result into a client response payload.

Call relations: handle_initialized_client_request calls this; memory_reset_response_inner clears both database rows and memory directories.

Call graph: calls 1 internal fn (memory_reset_response_inner); called by 1 (handle_initialized_client_request).

async fn thread_unarchive(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadUnarchiveParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for making an archived thread visible again. It sends both a response and a notification that the thread was unarchived.

Data flow: It receives unarchive parameters, calls the inner flow, sends the response, then broadcasts a ThreadUnarchived notification.

Call relations: handle_initialized_client_request calls this; thread_unarchive_inner serializes the operation and delegates storage work.

Call graph: calls 1 internal fn (thread_unarchive_inner); called by 1 (handle_initialized_client_request); 2 external calls (ThreadUnarchived, clone).

async fn thread_compact_start(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadCompactStartParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for starting compaction of a thread. Compaction asks the core to summarize or shrink history so the conversation is cheaper to continue.

Data flow: It receives a thread id and request id, delegates to the inner operation submission, and returns an empty success response.

Call relations: handle_initialized_client_request calls this; thread_compact_start_inner loads the live thread and submits the core Compact operation.

Call graph: calls 1 internal fn (thread_compact_start_inner); called by 1 (handle_initialized_client_request).

async fn thread_background_terminals_clean(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadBackgroundTerminalsCleanParams,
    ) -> Result<Option<ClientResponsePayload>

Purpose: Public handler for asking a thread to clean up finished background terminal processes. This keeps old process entries from cluttering the thread.

Data flow: It receives the target thread id, delegates to the inner core operation, and returns an empty success response.

Call relations: handle_initialized_client_request calls this; thread_background_terminals_clean_inner submits the cleanup operation to the live thread.

Call graph: calls 1 internal fn (thread_background_terminals_clean_inner); called by 1 (handle_initialized_client_request).

async fn thread_background_terminals_list(
        &self,
        params: ThreadBackgroundTerminalsListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for listing background terminals started by a thread. It supports paging so clients can fetch results in chunks.

Data flow: It receives list parameters, delegates to the inner listing code, and returns terminal entries plus an optional next cursor.

Call relations: handle_initialized_client_request calls this; thread_background_terminals_list_inner reads live terminal state and paginates it.

Call graph: calls 1 internal fn (thread_background_terminals_list_inner); called by 1 (handle_initialized_client_request).

async fn thread_background_terminals_terminate(
        &self,
        params: ThreadBackgroundTerminalsTerminateParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for stopping one background terminal process belonging to a thread.

Data flow: It receives a thread id and process id, delegates to the inner terminator, and returns whether a process was actually terminated.

Call relations: handle_initialized_client_request calls this; thread_background_terminals_terminate_inner parses the process id and calls the live thread.

Call graph: calls 1 internal fn (thread_background_terminals_terminate_inner); called by 1 (handle_initialized_client_request).

async fn thread_rollback(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRollbackParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for rolling a thread back by a number of turns. Rollback removes recent conversation progress so the user can try again from an earlier point.

Data flow: It receives rollback parameters, delegates to thread_rollback_inner, and returns no direct payload because the operation completes through thread events.

Call relations: handle_initialized_client_request calls this; thread_rollback_start submits the rollback command and tracks the pending request.

Call graph: calls 1 internal fn (thread_rollback_inner); called by 1 (handle_initialized_client_request).

async fn thread_list(
        &self,
        params: ThreadListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for listing stored threads. It supports filters, sorting, and paging.

Data flow: It receives list parameters, delegates to thread_list_response_inner, and returns a page of thread summaries.

Call relations: handle_initialized_client_request calls this; thread_list_response_inner normalizes filters and converts stored records into API threads.

Call graph: calls 1 internal fn (thread_list_response_inner); called by 1 (handle_initialized_client_request).

async fn thread_search(
        &self,
        params: ThreadSearchParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for searching stored threads by text. It returns matching threads with snippets.

Data flow: It receives search parameters, delegates to the inner search flow, and returns paged search results.

Call relations: handle_initialized_client_request calls this; thread_search_response_inner performs the storage search and live-status decoration.

Call graph: calls 1 internal fn (thread_search_response_inner); called by 1 (handle_initialized_client_request).

async fn thread_loaded_list(
        &self,
        params: ThreadLoadedListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for listing only threads that are currently loaded in memory. This is different from listing all saved threads.

Data flow: It receives cursor and limit parameters, delegates to the inner list, and returns loaded thread ids plus an optional cursor.

Call relations: handle_initialized_client_request calls this; thread_loaded_list_response_inner reads ids from the live thread manager.

Call graph: calls 1 internal fn (thread_loaded_list_response_inner); called by 1 (handle_initialized_client_request).

async fn thread_read(
        &self,
        params: ThreadReadParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for reading one thread’s details, optionally including its turns.

Data flow: It receives a thread id and include-turns flag, delegates to read logic, and returns a full thread view.

Call relations: handle_initialized_client_request calls this; thread_read_response_inner parses the id and calls read_thread_view.

Call graph: calls 1 internal fn (thread_read_response_inner); called by 1 (handle_initialized_client_request).

async fn thread_turns_list(
        &self,
        params: ThreadTurnsListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for listing a thread’s turns in pages. A turn is one user-and-assistant exchange or related unit of conversation.

Data flow: It receives paging and display options, delegates to the inner turn-list builder, and returns turns plus cursors.

Call relations: handle_initialized_client_request calls this; thread_turns_list_response_inner rebuilds turns from rollout history and live state.

Call graph: calls 1 internal fn (thread_turns_list_response_inner); called by 1 (handle_initialized_client_request).

async fn thread_turns_items_list(
        &self,
        _params: ThreadTurnsItemsListParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Placeholder handler for an API that is not implemented yet. It clearly reports that the method is unavailable.

Data flow: It ignores the request parameters and returns a method-not-found error.

Call relations: handle_initialized_client_request may route thread/turns/items/list here, but this function intentionally stops the request.

Call graph: calls 1 internal fn (method_not_found); called by 1 (handle_initialized_client_request).

async fn thread_shell_command(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadShellCommandParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for running a user shell command inside a live thread’s local environment. A shell command is a command-line instruction.

Data flow: It receives a thread id and command, delegates to the inner validator and core operation submitter, and returns an empty success response.

Call relations: handle_initialized_client_request calls this; thread_shell_command_inner checks local environment support and submits the command.

Call graph: calls 1 internal fn (thread_shell_command_inner); called by 1 (handle_initialized_client_request).

async fn thread_approve_guardian_denied_action(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadApproveGuardianDeniedActionParams,
    ) -> Result<Option<ClientResponseP

Purpose: Public handler for approving an action that a Guardian policy previously denied. Guardian is a safety or permission layer.

Data flow: It receives a thread id and serialized denial event, delegates to the inner flow, and returns an empty success response.

Call relations: handle_initialized_client_request calls this; thread_approve_guardian_denied_action_inner parses the event and submits approval to the live thread.

Call graph: calls 1 internal fn (thread_approve_guardian_denied_action_inner); called by 1 (handle_initialized_client_request).

async fn conversation_summary(
        &self,
        params: GetConversationSummaryParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public handler for fetching a compact summary of a conversation. It is useful when a client needs metadata but not full turns.

Data flow: It receives either a thread id or rollout path request, delegates to the summary reader, and returns a summary object.

Call relations: handle_initialized_client_request calls this; get_thread_summary_response_inner reads from storage and converts the record.

Call graph: calls 1 internal fn (get_thread_summary_response_inner); called by 1 (handle_initialized_client_request).

async fn load_thread(
        &self,
        thread_id: &str,
    ) -> Result<(ThreadId, Arc<CodexThread>), JSONRPCErrorError>

Purpose: Finds a live thread by its string id and reports friendly errors if the id is invalid or the thread is not loaded.

Data flow: It parses the string into a ThreadId, asks the thread manager for the live CodexThread, and returns both the parsed id and thread handle.

Call relations: Many live-only operations call this first, such as compaction, rollback, terminal operations, elicitations, shell commands, and Guardian approval.

Call graph: calls 1 internal fn (from_string); called by 9 (thread_approve_guardian_denied_action_inner, thread_background_terminals_clean_inner, thread_background_terminals_list_inner, thread_background_terminals_terminate_inner, thread_compact_start_inner, thread_decrement_elicitation_inner, thread_increment_elicitation_inner, thread_rollback_start, thread_shell_command_inner).

async fn acquire_thread_list_state_permit(
        &self,
    ) -> Result<SemaphorePermit<'_>, JSONRPCErrorError>

Purpose: Acquires a permit that serializes operations affecting thread list state. A semaphore permit is like a ticket that limits how many tasks enter a sensitive area at once.

Data flow: It waits on the thread-list semaphore and returns a permit, or an internal error if the semaphore is closed.

Call relations: Archive, unarchive, resume, rename, and metadata update paths call this before changing state that thread/list clients observe.

Call graph: called by 5 (thread_archive_inner, thread_metadata_update_response_inner, thread_resume_inner, thread_set_name_response_inner, thread_unarchive_inner).

async fn set_app_server_client_info(
        thread: &CodexThread,
        app_server_client_name: Option<String>,
        app_server_client_version: Option<String>,
    ) -> Result<(), JSONRPCErrorEr

Purpose: Stores the client name and version on a thread, including one compatibility flag for older Xcode clients. This lets the core adapt behavior to the connected app.

Data flow: It receives a live thread and optional client identity, computes whether MCP elicitations should be auto-denied, sends all of that to the thread, and returns success or an internal error.

Call relations: Start, resume, fork, and running-resume paths call this after they have a live thread.

Call graph: calls 2 internal fn (xcode_26_4_mcp_elicitations_auto_deny, set_app_server_client_info).

async fn finalize_thread_teardown(&self, thread_id: ThreadId)

Purpose: Cleans app-server bookkeeping after a thread is gone or no longer usable. It removes pending unload state, cancels outstanding requests, clears thread state, and removes watch entries.

Data flow: It receives a thread id, mutates several managers to forget or cancel state for that thread, and returns nothing.

Call relations: Unsubscribe, removal, connection cleanup, and resume replacement paths call this after the core thread has disappeared or been shut down.

Call graph: calls 2 internal fn (remove_thread_state, remove_thread); called by 4 (connection_closed, prepare_thread_for_removal, resume_running_thread, thread_unsubscribe_response_inner); 1 external calls (to_string).

async fn thread_unsubscribe_response_inner(
        &self,
        params: ThreadUnsubscribeParams,
        connection_id: ConnectionId,
    ) -> Result<ThreadUnsubscribeResponse, JSONRPCErrorError>

Purpose: Performs the actual unsubscribe operation for one connection and thread. It also cleans stale state if the thread is already unloaded.

Data flow: It parses the thread id, checks whether the live thread exists, possibly finalizes teardown, otherwise removes the connection from the thread’s subscriber set and returns a status.

Call relations: thread_unsubscribe calls this and wraps its status into the client response.

Call graph: calls 3 internal fn (finalize_thread_teardown, unsubscribe_connection_from_thread, from_string); called by 1 (thread_unsubscribe).

async fn prepare_thread_for_archive(&self, thread_id: ThreadId)

Purpose: Prepares one thread to be archived by using the general removal preparation path. It names the operation as archive for logs.

Data flow: It receives a thread id and passes it to prepare_thread_for_removal with the archive label.

Call relations: thread_archive_response calls this before writing archive state to storage.

Call graph: calls 1 internal fn (prepare_thread_for_removal); called by 1 (thread_archive_response).

async fn prepare_thread_for_removal(&self, thread_id: ThreadId, operation: &str)

Purpose: Stops a live thread before an operation removes or archives it. This avoids leaving a still-running conversation behind after storage changes.

Data flow: It removes the thread from the live manager, waits briefly for shutdown if it was active, logs failures or timeouts, then finalizes app-server teardown.

Call relations: prepare_thread_for_archive uses this, and archive flows rely on it before marking threads archived.

Call graph: calls 1 internal fn (finalize_thread_teardown); called by 1 (prepare_thread_for_archive); 3 external calls (error!, info!, warn!).

fn listener_task_context(&self) -> ListenerTaskContext

Purpose: Packages the shared handles needed by thread listener tasks. A listener task watches a live thread and forwards events to clients.

Data flow: It clones references to the thread manager, state manager, outgoing sender, watch manager, configuration details, and skills watcher into a small context object.

Call relations: ensure_conversation_listener and ensure_listener_task_running call this before delegating to the thread lifecycle module.

Call graph: called by 2 (ensure_conversation_listener, ensure_listener_task_running); 3 external calls (clone, clone, clone).

async fn ensure_conversation_listener(
        &self,
        conversation_id: ThreadId,
        connection_id: ConnectionId,
        raw_events_enabled: bool,
    ) -> Result<EnsureConversationListen

Purpose: Makes sure a connection is subscribed to live events for a thread. It starts or reuses the listener machinery as needed.

Data flow: It receives a thread id, connection id, and raw-event flag, builds a listener context, and delegates to the lifecycle helper, returning the attach result.

Call relations: Resume, fork, and try_attach_thread_listener use this when a client should begin receiving updates for a thread.

Call graph: calls 2 internal fn (ensure_conversation_listener, listener_task_context); called by 3 (thread_fork_inner, thread_resume_inner, try_attach_thread_listener).

async fn ensure_listener_task_running(
        &self,
        conversation_id: ThreadId,
        conversation: Arc<CodexThread>,
        thread_state: Arc<Mutex<ThreadState>>,
    ) -> Result<(), JSON

Purpose: Ensures the background listener task exists for an already loaded thread. This is needed before a running resume can ask the listener to send a resume response.

Data flow: It receives the thread id, live thread handle, and thread state, builds listener context, and delegates to the lifecycle helper.

Call relations: resume_running_thread calls this when rejoining a live thread.

Call graph: calls 2 internal fn (ensure_listener_task_running, listener_task_context); called by 1 (resume_running_thread).

async fn thread_start_inner(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadStartParams,
        app_server_client_name: Option<String>,
        app_server_client_versio

Purpose: Validates a start request and launches the expensive start work in the background. This keeps the request handler responsive while the thread is created.

Data flow: It unpacks parameters, rejects incompatible sandbox and permission settings, builds config overrides and listener context, then spawns thread_start_task; errors from the task are sent through the outgoing channel.

Call relations: thread_start calls this; thread_start_task later creates the core thread and sends the actual response.

Call graph: calls 3 internal fn (request_trace, span, build_thread_config_overrides); called by 1 (thread_start); 7 external calls (clone, thread_start_task, spawn, clone, clone, clone, clone).

async fn drain_background_tasks(&self)

Purpose: Waits for this processor’s background tasks to finish during shutdown. It prevents tasks from being abandoned silently.

Data flow: It closes the task tracker, waits up to ten seconds, and logs a warning if tasks do not stop in time.

Call relations: Server shutdown code calls this through the processor wrapper when tearing down the app server.

Call graph: called by 1 (drain_background_tasks); 5 external calls (from_secs, close, wait, timeout, warn!).

async fn clear_all_thread_listeners(&self)

Purpose: Drops all recorded listener subscriptions. This is used when the server needs a clean listener state, usually during shutdown or reset.

Data flow: It calls the thread state manager to clear all listeners and returns nothing.

Call relations: Higher-level teardown code calls this method on the processor.

Call graph: calls 1 internal fn (clear_all_listeners); called by 1 (clear_all_thread_listeners).

async fn shutdown_threads(&self)

Purpose: Asks the core thread manager to shut down all live threads, with a timeout. It logs any threads that could not be shut down cleanly.

Data flow: It requests bounded shutdown, receives a report of failed or timed-out thread ids, and writes warnings for those cases.

Call relations: Higher-level server shutdown code calls this when stopping the app server.

Call graph: called by 1 (shutdown_threads); 2 external calls (from_secs, warn!).

async fn request_trace_context(
        &self,
        request_id: &ConnectionRequestId,
    ) -> Option<codex_protocol::protocol::W3cTraceContext>

Purpose: Looks up distributed tracing information for a request. Tracing information helps connect logs and timing across async work.

Data flow: It receives a request id, asks the outgoing message sender for any saved trace context, and returns it if present.

Call relations: submit_core_op, resume, and fork use this when submitting work to the core so downstream activity keeps the same trace.

Call graph: called by 3 (submit_core_op, thread_fork_inner, thread_resume_inner).

async fn submit_core_op(
        &self,
        request_id: &ConnectionRequestId,
        thread: &CodexThread,
        op: Op,
    ) -> CodexResult<String>

Purpose: Submits an operation to a live Codex thread while preserving request trace context. It is the common doorway for thread commands like compact or shell command.

Data flow: It receives a request id, live thread, and core operation, fetches trace context, submits the operation to the thread, and returns the core submission result.

Call relations: Rollback, compact, background-terminal cleanup, shell command, and Guardian approval handlers all use this helper.

Call graph: calls 2 internal fn (request_trace_context, submit_with_trace); called by 5 (thread_approve_guardian_denied_action_inner, thread_background_terminals_clean_inner, thread_compact_start_inner, thread_rollback_start, thread_shell_command_inner).

async fn thread_start_task(
        listener_task_context: ListenerTaskContext,
        config_manager: ConfigManager,
        request_id: ConnectionRequestId,
        app_server_client_name: Option<S

Purpose: Does the full work of creating a new thread and sending the start response. This includes loading configuration, validating tools, creating the core thread, attaching a listener, and notifying clients.

Data flow: It receives prepared context, request data, config overrides, tools, capability roots, environment choices, and trace context; it loads config, may persist project trust, validates tools, starts the thread, builds the API thread object, sends the response, and broadcasts ThreadStarted.

Call relations: thread_start_inner spawns this as a background task so thread startup can run asynchronously without blocking the dispatcher.

Call graph: calls 10 internal fn (current_cli_overrides, load_with_cli_overrides, load_with_overrides, ensure_conversation_listener, build_thread_from_snapshot, permission_profile_trusts_project, requested_permissions_trust_project, validate_dynamic_tools, set_project_trust_level, new); 12 external calls (set_app_server_client_info, ThreadStarted, String, Table, clone, initialize_executor_plugin_thread_data, clone, once, now, new (+2 more)).

fn build_thread_config_overrides(
        &self,
        model: Option<String>,
        model_provider: Option<String>,
        service_tier: Option<Option<String>>,
        cwd: Option<String>,

Purpose: Converts client-supplied thread settings into the core configuration override structure. This keeps request parsing separate from config loading.

Data flow: It receives optional model, provider, working directory, workspace roots, approval, sandbox, permissions, instructions, and personality settings, translates app-server enum values to core values, and returns ConfigOverrides.

Call relations: Start, resume, and fork paths call this before asking ConfigManager to load the effective configuration.

Call graph: called by 3 (thread_fork_inner, thread_resume_inner, thread_start_inner); 1 external calls (default).

async fn thread_archive_inner(
        &self,
        params: ThreadArchiveParams,
    ) -> Result<(ThreadArchiveResponse, Vec<String>), JSONRPCErrorError>

Purpose: Serializes and starts the archive operation. It obtains the thread-list state permit before changing stored archive state.

Data flow: It acquires the permit, then calls thread_archive_response and returns its response plus archived ids.

Call relations: thread_archive calls this before sending the client response and archive notifications.

Call graph: calls 2 internal fn (acquire_thread_list_state_permit, thread_archive_response); called by 1 (thread_archive).

async fn thread_archive_response(
        &self,
        params: ThreadArchiveParams,
    ) -> Result<(ThreadArchiveResponse, Vec<String>), JSONRPCErrorError>

Purpose: Archives one thread and eligible spawned descendants. It shuts down live versions before changing the store.

Data flow: It parses the target id, finds descendants from state DB when available, checks which records are not already archived, prepares each for archive, writes archive markers, and returns the archived ids.

Call relations: thread_archive_inner calls this after acquiring the state permit; it uses prepare_thread_for_archive and state_db_spawn_subtree_thread_ids.

Call graph: calls 4 internal fn (prepare_thread_for_archive, state_db_spawn_subtree_thread_ids, thread_store_archive_error, from_string); called by 1 (thread_archive_inner); 2 external calls (new, warn!).

async fn state_db_spawn_subtree_thread_ids(
        &self,
        thread_id: ThreadId,
    ) -> Result<Vec<ThreadId>, JSONRPCErrorError>

Purpose: Builds the list of a thread plus spawned descendant thread ids using the state database when available. Spawned descendants are child threads created by agents.

Data flow: It starts with the given id, optionally asks the state DB for descendants, removes duplicates, and returns the resulting list.

Call relations: thread_archive_response calls this so archiving a parent can also archive its spawned subtree.

Call graph: called by 1 (thread_archive_response); 2 external calls (from, vec!).

async fn thread_increment_elicitation_inner(
        &self,
        params: ThreadIncrementElicitationParams,
    ) -> Result<ThreadIncrementElicitationResponse, JSONRPCErrorError>

Purpose: Increments the live thread’s count of active out-of-band elicitations. This count tells clients whether the thread is paused for side input.

Data flow: It loads the live thread, calls its increment method, and returns the new count and paused flag.

Call relations: thread_increment_elicitation delegates to this after request routing.

Call graph: calls 1 internal fn (load_thread); called by 1 (thread_increment_elicitation).

async fn thread_decrement_elicitation_inner(
        &self,
        params: ThreadDecrementElicitationParams,
    ) -> Result<ThreadDecrementElicitationResponse, JSONRPCErrorError>

Purpose: Decrements the live thread’s out-of-band elicitation count, with friendly errors for invalid decrement requests.

Data flow: It loads the live thread, calls its decrement method, maps core errors into JSON-RPC errors, and returns the new count and paused flag.

Call relations: thread_decrement_elicitation delegates to this after request routing.

Call graph: calls 1 internal fn (load_thread); called by 1 (thread_decrement_elicitation).

async fn thread_set_name_response_inner(
        &self,
        params: ThreadSetNameParams,
    ) -> Result<(ThreadSetNameResponse, Option<ThreadNameUpdatedNotification>), JSONRPCErrorError>

Purpose: Validates and stores a new thread name. It returns both the API response and the notification payload to send if the update succeeds.

Data flow: It parses the thread id, normalizes the name, rejects an empty name, acquires the state permit, writes a metadata patch through the thread manager, and returns success plus a name-updated notification.

Call relations: thread_set_name calls this, then sends the response and notification.

Call graph: calls 3 internal fn (acquire_thread_list_state_permit, normalize_thread_name, from_string); called by 1 (thread_set_name); 1 external calls (default).

async fn thread_memory_mode_set_response_inner(
        &self,
        params: ThreadMemoryModeSetParams,
    ) -> Result<ThreadMemoryModeSetResponse, JSONRPCErrorError>

Purpose: Stores a thread’s new memory mode in metadata. The response is empty because the requested change is the whole result.

Data flow: It parses the thread id, converts the app-server mode to the core mode, writes a metadata patch, and returns success.

Call relations: thread_memory_mode_set calls this for the public request.

Call graph: calls 1 internal fn (from_string); called by 1 (thread_memory_mode_set); 1 external calls (default).

async fn memory_reset_response_inner(&self) -> Result<MemoryResetResponse, JSONRPCErrorError>

Purpose: Clears all saved memory data from both the state database and memory directories. This is a destructive reset used when the user wants memory wiped.

Data flow: It requires a state DB handle, clears memory rows, clears memory-root directory contents under the Codex home directory, and returns success or an internal error.

Call relations: memory_reset calls this when the client requests a global memory reset.

Call graph: called by 1 (memory_reset).

async fn thread_metadata_update_response_inner(
        &self,
        params: ThreadMetadataUpdateParams,
    ) -> Result<ThreadMetadataUpdateResponse, JSONRPCErrorError>

Purpose: Updates thread metadata, currently Git fields, and returns a refreshed thread view. It lets clients attach repository state to saved conversations.

Data flow: It parses the thread id, validates that at least one Git field is present, normalizes each field, writes the metadata patch under the state permit, converts the stored result into an API thread, adds live session/status/name details, and returns it.

Call relations: thread_metadata_update calls this; it uses normalize_thread_metadata_git_field, thread_from_stored_thread, and attach_thread_name.

Call graph: calls 5 internal fn (acquire_thread_list_state_permit, attach_thread_name, thread_from_stored_thread, loaded_status_for_thread, from_string); called by 1 (thread_metadata_update); 2 external calls (default, normalize_thread_metadata_git_field).

fn normalize_thread_metadata_git_field(
        value: Option<Option<String>>,
        name: &str,
    ) -> Result<Option<Option<String>>, JSONRPCErrorError>

Purpose: Normalizes one optional Git metadata field. It trims strings and rejects fields that become empty.

Data flow: It receives a nested option that can mean unchanged, clear the field, or set a string; it trims set strings, errors on empty values, and returns the normalized patch value.

Call relations: thread_metadata_update_response_inner calls this for SHA, branch, and origin URL fields.

Call graph: 1 external calls (format!).

async fn thread_unarchive_inner(
        &self,
        params: ThreadUnarchiveParams,
    ) -> Result<(ThreadUnarchiveResponse, ThreadUnarchivedNotification), JSONRPCErrorError>

Purpose: Serializes the unarchive operation and builds the notification payload. It uses the thread-list permit because visible list state changes.

Data flow: It acquires the permit, calls thread_unarchive_response, and wraps the returned id into a ThreadUnarchived notification.

Call relations: thread_unarchive calls this before sending the response and notification.

Call graph: calls 2 internal fn (acquire_thread_list_state_permit, thread_unarchive_response); called by 1 (thread_unarchive).

async fn thread_unarchive_response(
        &self,
        params: ThreadUnarchiveParams,
    ) -> Result<(ThreadUnarchiveResponse, String), JSONRPCErrorError>

Purpose: Marks a stored thread as unarchived and returns its refreshed API representation.

Data flow: It parses the thread id, asks the store to unarchive it, converts the stored record into an API thread, applies live status and saved name, and returns the response plus thread id string.

Call relations: thread_unarchive_inner calls this after acquiring the permit.

Call graph: calls 4 internal fn (attach_thread_name, thread_from_stored_thread, loaded_status_for_thread, from_string); called by 1 (thread_unarchive_inner).

async fn thread_rollback_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRollbackParams,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Small wrapper that starts rollback. It exists to match the public handler shape.

Data flow: It receives request id and rollback parameters, forwards them to thread_rollback_start, and returns that result.

Call relations: thread_rollback calls this; thread_rollback_start contains the validation and core submission.

Call graph: calls 1 internal fn (thread_rollback_start); called by 1 (thread_rollback).

async fn thread_rollback_start(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadRollbackParams,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Starts a rollback on a live thread and records that a rollback response is pending. It prevents two rollbacks from racing on the same thread.

Data flow: It validates numTurns, loads the live thread, checks and sets pending rollback state under a lock, submits the core rollback operation, and clears pending state if submission fails.

Call relations: thread_rollback_inner calls this; later thread events are expected to complete the pending rollback request.

Call graph: calls 3 internal fn (load_thread, submit_core_op, thread_state); called by 1 (thread_rollback_inner); 2 external calls (clone, format!).

async fn thread_compact_start_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadCompactStartParams,
    ) -> Result<ThreadCompactStartResponse, JSONRPCErrorError>

Purpose: Submits a compaction request to a live thread. It returns once the core accepts the operation.

Data flow: It parses and loads the thread, submits Op::Compact with trace context, and returns an empty response or an internal error.

Call relations: thread_compact_start calls this from the public request path.

Call graph: calls 2 internal fn (load_thread, submit_core_op); called by 1 (thread_compact_start).

async fn thread_background_terminals_clean_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadBackgroundTerminalsCleanParams,
    ) -> Result<ThreadBackgroundTermina

Purpose: Asks a live thread to remove stale background terminal entries. This is a core operation rather than direct list mutation.

Data flow: It loads the thread, submits Op::CleanBackgroundTerminals, and returns an empty response on successful submission.

Call relations: thread_background_terminals_clean calls this.

Call graph: calls 2 internal fn (load_thread, submit_core_op); called by 1 (thread_background_terminals_clean).

async fn thread_background_terminals_list_inner(
        &self,
        params: ThreadBackgroundTerminalsListParams,
    ) -> Result<ThreadBackgroundTerminalsListResponse, JSONRPCErrorError>

Purpose: Reads the live thread’s background terminal list and pages it for the client.

Data flow: It loads the thread, maps core terminal records into app-server terminal objects, paginates them by cursor and limit, and returns data plus next cursor.

Call relations: thread_background_terminals_list calls this; paginate_background_terminals does the page slicing.

Call graph: calls 2 internal fn (load_thread, paginate_background_terminals); called by 1 (thread_background_terminals_list).

async fn thread_background_terminals_terminate_inner(
        &self,
        params: ThreadBackgroundTerminalsTerminateParams,
    ) -> Result<ThreadBackgroundTerminalsTerminateResponse, JSONRPCErrorE

Purpose: Terminates one background terminal process by process id.

Data flow: It parses the process id as a number, loads the live thread, asks the thread to terminate that process, and returns whether it succeeded.

Call relations: thread_background_terminals_terminate calls this.

Call graph: calls 1 internal fn (load_thread); called by 1 (thread_background_terminals_terminate).

async fn thread_shell_command_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadShellCommandParams,
    ) -> Result<ThreadShellCommandResponse, JSONRPCErrorError>

Purpose: Validates and submits a user shell command to a live thread. It only works when a local environment is configured.

Data flow: It trims the command, rejects empty commands, checks for local environment support, loads the thread, submits Op::RunUserShellCommand, and returns success.

Call relations: thread_shell_command calls this; submit_core_op handles trace-aware submission.

Call graph: calls 2 internal fn (load_thread, submit_core_op); called by 1 (thread_shell_command).

async fn thread_approve_guardian_denied_action_inner(
        &self,
        request_id: &ConnectionRequestId,
        params: ThreadApproveGuardianDeniedActionParams,
    ) -> Result<ThreadApproveGua

Purpose: Submits approval for a previously denied Guardian action to a live thread.

Data flow: It parses the event JSON into the expected core event type, loads the thread, submits Op::ApproveGuardianDeniedAction, and returns success.

Call relations: thread_approve_guardian_denied_action calls this.

Call graph: calls 2 internal fn (load_thread, submit_core_op); called by 1 (thread_approve_guardian_denied_action); 1 external calls (from_value).

async fn thread_list_response_inner(
        &self,
        params: ThreadListParams,
    ) -> Result<ThreadListResponse, JSONRPCErrorError>

Purpose: Builds the response for thread/list, including filters, sorting, pagination, conversion to API threads, and live status decoration.

Data flow: It normalizes filter parameters, clamps page size, maps sort options, calls list_threads_common, computes a backwards cursor, converts stored threads, fetches live statuses, and returns the page.

Call relations: thread_list calls this; list_threads_common performs the repeated storage paging and filtering.

Call graph: calls 4 internal fn (list_threads_common, normalize_thread_list_cwd_filters, thread_from_stored_thread, loaded_statuses_for_threads); called by 1 (thread_list); 1 external calls (with_capacity).

async fn thread_search_response_inner(
        &self,
        params: ThreadSearchParams,
    ) -> Result<ThreadSearchResponse, JSONRPCErrorError>

Purpose: Searches stored threads by text and returns matching threads with snippets. It also applies source filters that may need app-side interpretation.

Data flow: It validates a non-empty search term, clamps page size, repeatedly asks the store for search pages until enough matches survive filtering, converts each stored record, adds live statuses, and returns search results with cursors.

Call relations: thread_search calls this from the public request path.

Call graph: calls 2 internal fn (thread_from_stored_thread, loaded_statuses_for_threads); called by 1 (thread_search); 1 external calls (with_capacity).

async fn thread_loaded_list_response_inner(
        &self,
        params: ThreadLoadedListParams,
    ) -> Result<ThreadLoadedListResponse, JSONRPCErrorError>

Purpose: Lists currently loaded thread ids in sorted pages. This is useful for clients or diagnostics that care about memory-resident threads.

Data flow: It gets live thread ids, sorts them, applies a cursor and limit, and returns the selected ids plus a next cursor when more remain.

Call relations: thread_loaded_list calls this.

Call graph: calls 1 internal fn (from_string); called by 1 (thread_loaded_list); 1 external calls (format!).

async fn thread_read_response_inner(
        &self,
        params: ThreadReadParams,
    ) -> Result<ThreadReadResponse, JSONRPCErrorError>

Purpose: Parses a thread/read request and returns a detailed thread view.

Data flow: It parses the thread id, calls read_thread_view with the include-turns flag, maps read errors to JSON-RPC errors, and wraps the resulting thread.

Call relations: thread_read calls this; read_thread_view decides whether to use persisted data, live data, or both.

Call graph: calls 2 internal fn (read_thread_view, from_string); called by 1 (thread_read).

async fn read_thread_view(
        &self,
        thread_id: ThreadId,
        include_turns: bool,
    ) -> Result<Thread, ThreadReadViewError>

Purpose: Builds the best available API view for one thread from stored metadata, stored history, and live state. It handles cases where a thread is loaded but not yet fully materialized on disk.

Data flow: It checks whether the thread is loaded, chooses persisted or live reading based on includeTurns and availability, merges status and stale-turn information, and returns a Thread or a read-specific error.

Call relations: thread_read_response_inner calls this; it delegates to load_persisted_thread_for_read and load_live_thread_view.

Call graph: calls 3 internal fn (load_live_thread_view, load_persisted_thread_for_read, loaded_status_for_thread); called by 1 (thread_read_response_inner); 3 external calls (InvalidRequest, format!, matches!).

async fn load_persisted_thread_for_read(
        &self,
        thread_id: ThreadId,
        include_turns: bool,
    ) -> Result<Option<Thread>, ThreadReadViewError>

Purpose: Attempts to read a thread from persistent storage for thread/read. It treats missing rollout data as “not available” rather than always fatal.

Data flow: It asks the thread store for metadata and optionally history, converts the stored record to an API thread, optionally builds turns from history, and returns Some thread, None for missing materialization, or an error.

Call relations: read_thread_view calls this before falling back to live thread snapshots.

Call graph: calls 1 internal fn (thread_from_stored_thread); called by 1 (read_thread_view); 3 external calls (Internal, InvalidRequest, format!).

async fn load_live_thread_view(
        &self,
        thread_id: ThreadId,
        include_turns: bool,
        loaded_thread: &CodexThread,
        persisted_thread: Option<Thread>,
    ) -> Result<

Purpose: Builds a thread/read view from a live thread and optional persisted metadata. It is used when live state is newer than storage or storage is not ready.

Data flow: It reads the live config snapshot, rejects includeTurns for ephemeral threads, builds a fallback thread from live data, merges persisted fields when present, then applies stored name/history fields.

Call relations: read_thread_view calls this when a thread is loaded and live data is needed.

Call graph: calls 3 internal fn (apply_thread_read_store_fields, build_thread_from_loaded_snapshot, config_snapshot); called by 1 (read_thread_view); 1 external calls (InvalidRequest).

async fn apply_thread_read_store_fields(
        &self,
        thread_id: ThreadId,
        thread: &mut Thread,
        include_turns: bool,
        loaded_thread: &CodexThread,
    ) -> Result<(),

Purpose: Adds store-backed details to a live thread/read view. This includes the saved name and, when requested, reconstructed turns.

Data flow: It attaches a saved thread name, optionally loads live history from the thread store path, converts rollout items into API turns, and mutates the Thread object.

Call relations: load_live_thread_view calls this after constructing the base live thread view.

Call graph: calls 2 internal fn (attach_thread_name, load_history); called by 1 (load_live_thread_view).

async fn thread_turns_list_response_inner(
        &self,
        params: ThreadTurnsListParams,
    ) -> Result<ThreadTurnsListResponse, JSONRPCErrorError>

Purpose: Builds a paged list of turns for one thread, merging stored history with the current live turn when needed.

Data flow: It parses the thread id, loads rollout history, checks live running status, optionally gets an active-turn snapshot from thread state, then builds a paged response according to cursor, limit, sort direction, and item view.

Call relations: thread_turns_list calls this; build_thread_turns_page_response reconstructs and paginates the turns.

Call graph: calls 5 internal fn (load_thread_turns_list_history, build_thread_turns_page_response, thread_state, loaded_status_for_thread, from_string); called by 1 (thread_turns_list); 1 external calls (matches!).

async fn load_thread_turns_list_history(
        &self,
        thread_id: ThreadId,
    ) -> Result<Vec<RolloutItem>, ThreadReadViewError>

Purpose: Loads the rollout items needed to reconstruct a thread’s turns. It falls back to a live thread history load when the stored rollout is not yet materialized.

Data flow: It first tries the thread store with history; if storage says the thread is missing or not materialized, it looks for a live thread, rejects ephemeral threads, and loads history from the live thread.

Call relations: thread_turns_list_response_inner calls this before building the page.

Call graph: called by 1 (thread_turns_list_response_inner); 3 external calls (Internal, InvalidRequest, format!).

fn thread_created_receiver(&self) -> broadcast::Receiver<ThreadId>

Purpose: Returns a subscription receiver for newly created thread ids. A receiver lets other parts of the server listen for thread creation events.

Data flow: It asks the thread manager for its thread-created broadcast receiver and returns it.

Call relations: A higher-level processor method exposes this to code that wants to react to new threads.

Call graph: called by 1 (thread_created_receiver).

async fn connection_initialized(
        &self,
        connection_id: ConnectionId,
        capabilities: ConnectionCapabilities,
    )

Purpose: Records that a client connection has finished initialization and what capabilities it supports.

Data flow: It receives a connection id and capability set, forwards them to the thread state manager, and returns nothing.

Call relations: Connection-handling code calls this after initialization and before thread listeners rely on capability information.

Call graph: calls 1 internal fn (connection_initialized); called by 2 (connection_initialized, handle_client_request).

async fn connection_closed(&self, connection_id: ConnectionId)

Purpose: Cleans up thread subscriptions for a closed client connection. It also reconciles stale thread state for threads no longer loaded.

Data flow: It removes the connection from the thread state manager, receives affected thread ids, and for any id no longer live, finalizes thread teardown.

Call relations: Connection teardown code calls this when a client disconnects.

Call graph: calls 2 internal fn (finalize_thread_teardown, remove_connection); called by 1 (connection_closed).

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

Purpose: Returns a watch receiver for the number of running assistant turns. A watch receiver gives subscribers the latest value whenever it changes.

Data flow: It delegates to the thread watch manager and returns the receiver.

Call relations: Higher-level server code exposes this metric to interested components.

Call graph: calls 1 internal fn (subscribe_running_turn_count); called by 1 (subscribe_running_assistant_turn_count).

async fn try_attach_thread_listener(
        &self,
        thread_id: ThreadId,
        connection_ids: Vec<ConnectionId>,
    )

Purpose: Best-effort helper that subscribes initialized connections to a thread. It is used when a thread appears and clients should start receiving updates.

Data flow: It optionally reads live config, updates the watch manager with a loaded-thread view, inherits raw-event settings from a parent thread, then attempts listener attachment for each connection id.

Call relations: External orchestration calls this; it uses ensure_conversation_listener for each connection.

Call graph: calls 4 internal fn (ensure_conversation_listener, build_thread_from_snapshot, thread_state, upsert_thread); called by 1 (try_attach_thread_listener).

async fn thread_resume_inner(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadResumeParams,
        app_server_client_name: Option<String>,
        app_server_client_vers

Purpose: Handles the complete resume flow for both already-running and cold-stored threads. It validates inputs, loads history, configures a new core thread if needed, attaches listeners, and sends the resume response.

Data flow: It checks pending unloads and invalid sandbox/permission combinations, may rejoin a running thread, otherwise reads history from request or storage, applies persisted metadata, loads config, resumes the core thread, builds the API thread and optional initial turns page, sends response and token-usage updates, and resumes goal processing.

Call relations: thread_resume calls this; it coordinates many helpers including resume_running_thread, resume_thread_from_rollout, build_thread_config_overrides, and load_thread_from_resume_source_or_send_internal.

Call graph: calls 16 internal fn (load_for_cwd, emit_resume_goal_snapshot_and_continue, acquire_thread_list_state_permit, build_thread_config_overrides, ensure_conversation_listener, load_and_apply_persisted_resume_metadata, load_thread_from_resume_source_or_send_internal, request_trace_context, resume_running_thread, resume_thread_from_history (+6 more)); called by 1 (thread_resume); 2 external calls (set_app_server_client_info, format!).

async fn load_and_apply_persisted_resume_metadata(
        &self,
        thread_history: &InitialHistory,
        request_overrides: &mut Option<HashMap<String, serde_json::Value>>,
        typesafe_

Purpose: Loads saved metadata for a resumed thread and applies model-related defaults when appropriate.

Data flow: It checks that the initial history is a resumed history, reads the thread metadata from the state DB if available, merges it into request/config overrides, and returns the metadata if found.

Call relations: thread_resume_inner calls this before loading the effective configuration for a cold resume.

Call graph: calls 1 internal fn (merge_persisted_resume_metadata); called by 1 (thread_resume_inner).

async fn resume_running_thread(
        &self,
        request_id: &ConnectionRequestId,
        params: &ThreadResumeParams,
        app_server_client_name: Option<String>,
        app_server_client_

Purpose: Handles the special case where a resume request targets a thread that is already loaded. It either delegates the response to the running listener or reports that no running thread handled it.

Data flow: It identifies any live thread by id or rollout path, validates stale path and ignored override situations, may shut down an idle cached thread so cold resume can replace it, ensures the listener is running, builds summary and history payloads, and sends a command to the listener to answer the resume request.

Call relations: thread_resume_inner calls this before cold resume; it uses collect_resume_override_mismatches, ensure_listener_task_running, read_stored_thread_for_resume, and stored_thread_to_api_thread.

Call graph: calls 10 internal fn (pending_resume_goal_state, ensure_listener_task_running, finalize_thread_teardown, read_stored_thread_for_resume, stored_thread_to_api_thread, collect_resume_override_mismatches, subscribed_connection_ids, thread_state, loaded_status_for_thread, from_string); called by 1 (thread_resume_inner); 10 external calls (new, set_app_server_client_info, clone, NotRunning, SendThreadResumeResponse, format!, matches!, paths_match_after_normalization, warn!, warn!).

async fn resume_thread_from_history(
        &self,
        history: &[ResponseItem],
    ) -> Result<InitialHistory, JSONRPCErrorError>

Purpose: Converts client-provided response history into initial history for a fork-like resume. It rejects empty history.

Data flow: It receives response items, checks that the slice is not empty, wraps each as a rollout item, and returns InitialHistory::Forked.

Call relations: thread_resume_inner calls this when the resume request includes inline history.

Call graph: called by 1 (thread_resume_inner); 3 external calls (is_empty, iter, Forked).

async fn resume_thread_from_rollout(
        &self,
        thread_id: &str,
        path: Option<&PathBuf>,
    ) -> Result<(InitialHistory, StoredThread), JSONRPCErrorError>

Purpose: Loads a stored thread and converts its rollout history into initial history for resume.

Data flow: It reads the stored thread by id or path, converts it to InitialHistory::Resumed, and returns both the initial history and the stored source thread.

Call relations: thread_resume_inner calls this when no inline history or running-thread probe provides the source.

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

async fn read_stored_thread_for_resume(
        &self,
        thread_id: &str,
        path: Option<&PathBuf>,
        include_history: bool,
    ) -> Result<StoredThread, JSONRPCErrorError>

Purpose: Reads a stored thread by rollout path or thread id for resume or fork, while rejecting archived threads.

Data flow: It chooses path-based or id-based store lookup, requests optional history, maps storage errors into resume-friendly errors, checks archived_at, and returns the stored thread.

Call relations: resume_running_thread, resume_thread_from_rollout, and thread_fork_inner use this to obtain the source conversation.

Call graph: calls 1 internal fn (from_string); called by 3 (resume_running_thread, resume_thread_from_rollout, thread_fork_inner); 1 external calls (format!).

async fn stored_thread_to_initial_history(
        &self,
        stored_thread: &StoredThread,
    ) -> Result<InitialHistory, JSONRPCErrorError>

Purpose: Converts a stored thread with history into the core InitialHistory form used to resume a conversation.

Data flow: It reads the stored history items, errors if history was not included, and returns InitialHistory::Resumed with the original conversation id and rollout path.

Call relations: resume_thread_from_rollout and thread_resume_inner use this after reading stored thread history.

Call graph: called by 2 (resume_thread_from_rollout, thread_resume_inner); 1 external calls (Resumed).

fn stored_thread_to_api_thread(
        &self,
        stored_thread: StoredThread,
        fallback_provider: &str,
        include_turns: bool,
    ) -> Thread

Purpose: Converts a stored thread record into the app-server Thread object, optionally filling its turns from stored history.

Data flow: It calls thread_from_stored_thread, and if include_turns is true and history is present, populates the thread’s turns from rollout items.

Call relations: resume_running_thread and thread_fork_inner use this when they need a client-facing thread summary from storage.

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

async fn read_stored_thread_for_new_fork(
        &self,
        thread_id: ThreadId,
        include_history: bool,
    ) -> Result<StoredThread, JSONRPCErrorError>

Purpose: Reads the newly created fork thread from storage. This is used when the fork has already materialized its own rollout file.

Data flow: It asks the thread store for the given id, includes archived records and optionally history, maps errors, and returns the stored thread.

Call relations: thread_fork_inner calls this after creating a persistent fork.

Call graph: called by 1 (thread_fork_inner).

async fn load_thread_from_resume_source_or_send_internal(
        &self,
        thread_id: ThreadId,
        thread: &CodexThread,
        thread_history: &InitialHistory,
        rollout_path: &Path

Purpose: Builds the Thread object returned by a cold resume response. It prefers stored metadata for resumed threads and builds a fresh snapshot for forked-history resumes.

Data flow: It receives the new live thread id, live core thread, initial history, rollout path, optional stored source, and include-turns flag; it builds or reloads metadata, fixes id/session/path, optionally populates turns, attaches the saved name, and returns the Thread or an internal-error string.

Call relations: thread_resume_inner calls this after the core has resumed the thread.

Call graph: calls 7 internal fn (attach_thread_name, build_thread_from_snapshot, preview_from_rollout_items, thread_from_stored_thread, config_snapshot, session_configured, get_rollout_items); called by 1 (thread_resume_inner); 4 external calls (into, to_path_buf, format!, to_string).

async fn attach_thread_name(&self, thread_id: ThreadId, thread: &mut Thread)

Purpose: Adds a saved display name to a Thread object when storage has one. It avoids duplicating the preview as the name.

Data flow: It reads stored metadata without history, trims the saved title, and if the title is non-empty and different from preview, mutates the Thread name.

Call relations: Read, resume, metadata update, and unarchive flows call this before returning thread objects.

Call graph: calls 1 internal fn (set_thread_name_from_title); called by 4 (apply_thread_read_store_fields, load_thread_from_resume_source_or_send_internal, thread_metadata_update_response_inner, thread_unarchive_response).

async fn thread_fork_inner(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadForkParams,
        app_server_client_name: Option<String>,
        app_server_client_version:

Purpose: Creates a new thread by copying another thread’s history. It supports changing configuration, making the fork ephemeral, and optionally excluding turns from the response.

Data flow: It validates settings, reads the source stored thread and history, prepares config overrides, loads config, asks the thread manager to fork, sets client info, optionally inherits the source name, attaches a listener, builds a response thread from storage or live snapshot, sends the response, sends restored token usage when needed, and broadcasts ThreadStarted.

Call relations: thread_fork calls this; it uses read_stored_thread_for_resume, build_thread_config_overrides, read_stored_thread_for_new_fork, stored_thread_to_api_thread, and ensure_conversation_listener.

Call graph: calls 12 internal fn (load_for_cwd, build_thread_config_overrides, ensure_conversation_listener, read_stored_thread_for_new_fork, read_stored_thread_for_resume, request_trace_context, stored_thread_to_api_thread, build_thread_from_snapshot, preview_from_rollout_items, set_thread_name_from_title (+2 more)); called by 1 (thread_fork); 7 external calls (default, set_app_server_client_info, ThreadStarted, cfg!, from_config, Resumed, json!).

async fn get_thread_summary_response_inner(
        &self,
        params: GetConversationSummaryParams,
    ) -> Result<GetConversationSummaryResponse, JSONRPCErrorError>

Purpose: Reads a compact conversation summary by thread id or rollout path.

Data flow: It chooses the appropriate store lookup, verifies rollout-path lookup is supported by the local store, maps read errors, converts the stored thread into a ConversationSummary, and returns it.

Call relations: conversation_summary calls this for client summary requests.

Call graph: calls 1 internal fn (summary_from_stored_thread); called by 1 (conversation_summary).

async fn list_threads_common(
        &self,
        requested_page_size: usize,
        cursor: Option<String>,
        sort_key: StoreThreadSortKey,
        sort_direction: SortDirection,
        fi

Purpose: Shared paging and filtering engine for thread/list. It repeatedly asks storage for pages until enough client-visible items pass filters.

Data flow: It receives page size, cursor, sort settings, and filters; it chooses default model-provider and source filters, loops through store pages, applies extra source and path filtering, protects against repeated cursors, and returns items plus next cursor.

Call relations: thread_list_response_inner calls this as its storage-facing workhorse.

Call graph: called by 1 (thread_list_response_inner); 3 external calls (new, with_capacity, vec!).

fn xcode_26_4_mcp_elicitations_auto_deny(
    client_name: Option<&str>,
    client_version: Option<&str>,
) -> bool

Purpose: Implements a temporary compatibility rule for Xcode 26.4 clients. Those clients shipped before MCP elicitation requests were visible, so the server auto-denies them.

Data flow: It receives optional client name and version and returns true only for client name Xcode with a version starting 26.4.

Call relations: set_app_server_client_info calls this before storing client info on a thread.

Call graph: called by 1 (set_app_server_client_info).

fn thread_backwards_cursor_for_sort_key(
    thread: &StoredThread,
    sort_key: StoreThreadSortKey,
    sort_direction: SortDirection,
) -> Option<String>

Purpose: Creates a cursor for paging in the opposite direction through thread lists. It nudges the timestamp by one millisecond so the anchor item is included correctly.

Data flow: It receives a stored thread, sort key, and direction, chooses the relevant timestamp, adjusts it forward or backward, formats it as an RFC3339 timestamp string, and returns it.

Call relations: Thread list and search response builders use it when computing backwards cursors.

Call graph: 1 external calls (milliseconds).

fn paginate_thread_turns(
    turns: Vec<Turn>,
    cursor: Option<&str>,
    limit: Option<u32>,
    sort_direction: SortDirection,
) -> Result<ThreadTurnsPage, JSONRPCErrorError>

Purpose: Slices a full turn list into one page according to cursor, limit, and sort direction.

Data flow: It parses the optional cursor, validates the anchor turn exists, orders turns ascending or descending, removes turns before or after the anchor, truncates to page size, and returns the selected turns plus next and backwards cursors.

Call relations: build_thread_turns_page_response calls this after reconstructing and trimming each turn’s item view.

Call graph: called by 1 (build_thread_turns_page_response); 1 external calls (new).

fn serialize_thread_turns_cursor(
    turn_id: &str,
    include_anchor: bool,
) -> Result<String, JSONRPCErrorError>

Purpose: Encodes a turn cursor as JSON text. The cursor stores the anchor turn id and whether the anchor should be included.

Data flow: It receives a turn id and include-anchor flag, serializes them into a JSON string, and returns that string or an internal serialization error.

Call relations: paginate_thread_turns uses this to produce next and backwards cursors.

Call graph: 1 external calls (to_string).

fn parse_thread_turns_cursor(cursor: &str) -> Result<ThreadTurnsCursor, JSONRPCErrorError>

Purpose: Decodes a turn-list cursor supplied by a client. It rejects malformed cursor strings.

Data flow: It receives cursor text, attempts to parse it as the expected JSON cursor object, and returns the object or an invalid-request error.

Call relations: paginate_thread_turns uses this before slicing a turn list.

Call graph: 1 external calls (from_str).

fn build_thread_turns_page_response(
    items: &[RolloutItem],
    loaded_status: ThreadStatus,
    has_live_running_thread: bool,
    active_turn: Option<Turn>,
    options: ThreadTurnsPageOptions<'

Purpose: Builds the complete response for a paged turn-list request. It reconstructs turns, applies item detail level, and paginates.

Data flow: It receives rollout items, loaded status, live-running information, optional active turn, and page options; it reconstructs turns, adjusts item visibility, paginates, and returns data plus cursors.

Call relations: thread_turns_list_response_inner and build_thread_resume_initial_turns_page call this.

Call graph: calls 3 internal fn (apply_thread_turns_items_view, paginate_thread_turns, reconstruct_thread_turns_for_turns_list); called by 2 (thread_turns_list_response_inner, build_thread_resume_initial_turns_page).

fn build_thread_resume_initial_turns_page(
    items: &[RolloutItem],
    loaded_status: ThreadStatus,
    has_live_running_thread: bool,
    active_turn: Option<Turn>,
    params: &ThreadResumeInitia

Purpose: Builds an optional initial page of turns to include directly in a resume response. This saves the client from making an immediate second request.

Data flow: It receives rollout items, status, live-turn information, and resume page parameters, calls the normal turn page builder with no cursor, and converts the result to the resume response type.

Call relations: thread_resume_inner and pending running-resume handling use this when the client asks for initialTurnsPage.

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

fn apply_thread_turns_items_view(turns: &mut [Turn], items_view: TurnItemsView)

Purpose: Reduces or preserves each turn’s item list according to the requested detail level. This controls how much conversation content is sent over the network.

Data flow: It receives mutable turns and an items view; for NotLoaded it clears items, for Summary it keeps the first user message and final agent message, and for Full it leaves items intact while marking the view.

Call relations: build_thread_turns_page_response calls this before pagination.

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

fn reconstruct_thread_turns_for_turns_list(
    items: &[RolloutItem],
    loaded_status: ThreadStatus,
    has_live_running_thread: bool,
    active_turn: Option<Turn>,
) -> Vec<Turn>

Purpose: Turns raw rollout items into API turns for listing, with live status correction and optional active-turn merging.

Data flow: It builds turns from rollout items, normalizes in-progress statuses based on live thread status, merges an active turn snapshot if present, and returns the final turn list.

Call relations: build_thread_turns_page_response calls this as the first step in turn-list response creation.

Call graph: calls 1 internal fn (normalize_thread_turns_status); called by 1 (build_thread_turns_page_response).

fn normalize_thread_turns_status(
    turns: &mut [Turn],
    loaded_status: ThreadStatus,
    has_live_in_progress_turn: bool,
)

Purpose: Marks stale in-progress turns as interrupted when the thread is not actually active. This prevents old saved history from looking like work is still running.

Data flow: It resolves the effective thread status from loaded status and live-running flag; if not active, it scans turns and changes any InProgress turn to Interrupted.

Call relations: reconstruct_thread_turns_for_turns_list calls this after building turns from rollout history.

Call graph: called by 1 (reconstruct_thread_turns_for_turns_list); 1 external calls (matches!).

fn thread_read_view_error(err: ThreadReadViewError) -> JSONRPCErrorError

Purpose: Converts internal read-view errors into JSON-RPC errors for clients.

Data flow: It receives a ThreadReadViewError, maps invalid requests, unsupported operations, and internal failures to the matching JSON-RPC error type, and returns it.

Call relations: thread_read_response_inner and thread_turns_list_response_inner use this when read helpers fail.

Call graph: calls 1 internal fn (unsupported_thread_store_operation).

fn unsupported_thread_store_operation(operation: &'static str) -> JSONRPCErrorError

Purpose: Creates a standard method-not-found error for thread store features that are not implemented. This gives clients a consistent message.

Data flow: It receives an operation name and returns a JSON-RPC method-not-found error saying the operation is not supported yet.

Call relations: Several storage error mappers call this when the current thread store cannot perform an operation.

Call graph: calls 1 internal fn (method_not_found); called by 7 (thread_store_delete_error, conversation_summary_rollout_path_read_error, conversation_summary_thread_id_read_error, thread_read_view_error, thread_store_archive_error, thread_store_list_error, thread_store_resume_read_error); 1 external calls (format!).

fn thread_store_list_error(err: ThreadStoreError) -> JSONRPCErrorError

Purpose: Maps storage-layer errors from listing threads into client-facing JSON-RPC errors.

Data flow: It receives a ThreadStoreError and returns invalid-request for bad inputs, method-not-found for unsupported store operations, or internal-error for unexpected failures.

Call relations: list_threads_common and search/list paths use this style of mapping for storage failures.

Call graph: calls 1 internal fn (unsupported_thread_store_operation); 1 external calls (format!).

fn thread_store_resume_read_error(err: ThreadStoreError) -> JSONRPCErrorError

Purpose: Maps storage read errors that happen during resume or fork into user-friendly errors.

Data flow: It receives a ThreadStoreError and turns invalid requests, unsupported operations, missing threads, and other failures into the correct JSON-RPC error.

Call relations: read_stored_thread_for_resume and read_stored_thread_for_new_fork use this when storage reads fail.

Call graph: calls 1 internal fn (unsupported_thread_store_operation); 1 external calls (format!).

fn thread_turns_list_history_load_error(
    thread_id: ThreadId,
    err: ThreadStoreError,
) -> ThreadReadViewError

Purpose: Converts history-load errors for thread/turns/list into read-view errors. It gives a clearer message when a thread is not materialized yet.

Data flow: It receives a thread id and store error, recognizes unresolved rollout paths, maps invalid and unsupported cases, and otherwise returns an internal read error.

Call relations: load_thread_turns_list_history uses this when live history loading fails.

Call graph: 4 external calls (Internal, InvalidRequest, Unsupported, format!).

fn thread_read_history_load_error(
    thread_id: ThreadId,
    err: ThreadStoreError,
) -> ThreadReadViewError

Purpose: Converts history-load errors for thread/read includeTurns into read-view errors. It explains when turns are unavailable before the first user message.

Data flow: It receives a thread id and store error, maps not-materialized or missing rollout cases to invalid requests, handles unsupported operations, and wraps unexpected failures as internal errors.

Call relations: apply_thread_read_store_fields uses this when it cannot load history for includeTurns.

Call graph: 4 external calls (Internal, InvalidRequest, Unsupported, format!).

fn conversation_summary_thread_id_read_error(
    conversation_id: ThreadId,
    err: ThreadStoreError,
) -> JSONRPCErrorError

Purpose: Maps storage errors from reading a conversation summary by thread id into JSON-RPC errors.

Data flow: It receives the requested id and storage error, turns missing-rollout and not-found cases into a summary not-found message, handles unsupported operations, and wraps unexpected failures.

Call relations: get_thread_summary_response_inner uses this for thread-id summary lookups.

Call graph: calls 2 internal fn (conversation_summary_not_found_error, unsupported_thread_store_operation); 1 external calls (format!).

fn conversation_summary_not_found_error(conversation_id: ThreadId) -> JSONRPCErrorError

Purpose: Creates the standard error message for a missing conversation summary.

Data flow: It receives a conversation id and returns an invalid-request error saying no rollout was found for that id.

Call relations: conversation_summary_thread_id_read_error calls this for not-found cases.

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

fn conversation_summary_rollout_path_read_error(
    path: &Path,
    err: ThreadStoreError,
) -> JSONRPCErrorError

Purpose: Maps storage errors from reading a conversation summary by rollout path into JSON-RPC errors.

Data flow: It receives a path and storage error, maps invalid requests and unsupported operations directly, and wraps other failures with the path in an internal error.

Call relations: get_thread_summary_response_inner uses this for rollout-path summary lookups.

Call graph: calls 1 internal fn (unsupported_thread_store_operation); 1 external calls (format!).

fn core_thread_write_error(operation: &str, err: CodexErr) -> JSONRPCErrorError

Purpose: Converts core thread write failures into JSON-RPC errors. Core write failures can happen while changing metadata such as names or memory mode.

Data flow: It receives an operation label and core error, maps thread-not-found and invalid-request cases to client errors, unsupported operations to method-not-found, and everything else to internal-error.

Call relations: Metadata-writing flows call this when ThreadManager update operations fail.

Call graph: calls 1 internal fn (method_not_found); called by 1 (thread_delete_response); 1 external calls (format!).

fn thread_store_archive_error(operation: &str, err: ThreadStoreError) -> JSONRPCErrorError

Purpose: Maps storage errors during archive or unarchive into client-facing JSON-RPC errors.

Data flow: It receives an operation name and store error, maps invalid requests and unsupported operations directly, and wraps other failures as internal archive/unarchive errors.

Call relations: thread_archive_response and unarchive storage paths use this error mapping.

Call graph: calls 1 internal fn (unsupported_thread_store_operation); called by 1 (thread_archive_response); 1 external calls (format!).

fn set_thread_name_from_title(thread: &mut Thread, title: String)

Purpose: Sets a thread display name only when it is meaningful. It avoids empty names and names that merely duplicate the preview.

Data flow: It receives a mutable Thread and title string, trims and compares the title, and sets thread.name only if it should be shown separately.

Call relations: attach_thread_name and thread_fork_inner use this when applying saved or inherited names.

Call graph: called by 2 (attach_thread_name, thread_fork_inner).

fn thread_from_stored_thread(
    thread: StoredThread,
    fallback_provider: &str,
    fallback_cwd: &AbsolutePathBuf,
) -> (Thread, Option<codex_thread_store::StoredThreadHistory>)

Purpose: Converts a stored thread database record into the app-server Thread shape. It also returns any stored history separately.

Data flow: It normalizes the working directory, converts Git and source metadata, fills timestamps, provider, path, preview, names, and other fields, sets status to NotLoaded, and returns the Thread plus optional history.

Call relations: List, search, read, resume, unarchive, metadata update, and fork helpers all use this as the main storage-to-API conversion.

Call graph: calls 1 internal fn (relative_to_current_dir); called by 7 (load_persisted_thread_for_read, load_thread_from_resume_source_or_send_internal, stored_thread_to_api_thread, thread_list_response_inner, thread_metadata_update_response_inner, thread_search_response_inner, thread_unarchive_response); 2 external calls (new, normalize_for_native_workdir).

fn summary_from_stored_thread(
    thread: StoredThread,
    fallback_provider: &str,
) -> ConversationSummary

Purpose: Converts a stored thread into a compact ConversationSummary. It keeps enough metadata for history pickers without loading turns.

Data flow: It reads path, preview, timestamps, provider, working directory, CLI version, source, and Git data from storage and fills fallback provider when needed.

Call relations: get_thread_summary_response_inner calls this after successfully reading storage.

Call graph: called by 1 (get_thread_summary_response_inner).

fn summary_from_state_db_metadata(
    conversation_id: ThreadId,
    path: PathBuf,
    first_user_message: Option<String>,
    preview: Option<String>,
    timestamp: String,
    updated_at: String,

Purpose: Test-only helper that builds a ConversationSummary from state database metadata fields. It mirrors older metadata-row shapes used in tests.

Data flow: It receives individual metadata values, derives preview, parses source, builds optional Git info, and returns a ConversationSummary.

Call relations: summary_from_thread_metadata calls this in test builds.

Call graph: called by 1 (summary_from_thread_metadata); 1 external calls (from_str).

fn summary_from_thread_metadata(metadata: &ThreadMetadata) -> ConversationSummary

Purpose: Test-only helper that converts a ThreadMetadata object into a ConversationSummary.

Data flow: It extracts fields from ThreadMetadata, formats timestamps, and passes them to summary_from_state_db_metadata.

Call relations: Unit tests use this path to compare metadata-derived summaries.

Call graph: calls 1 internal fn (summary_from_state_db_metadata).

fn preview_from_rollout_items(items: &[RolloutItem]) -> String

Purpose: Finds a short preview string from the first user message in rollout history. The preview helps clients show a thread in a list.

Data flow: It scans rollout items, parses response items into turn items, finds the first user message, strips a known marker if present, and returns the cleaned text or an empty string.

Call relations: Resume and fork response builders use this when they need a preview from copied history.

Call graph: called by 2 (load_thread_from_resume_source_or_send_internal, thread_fork_inner); 1 external calls (iter).

fn requested_permissions_trust_project(overrides: &ConfigOverrides, cwd: &Path) -> bool

Purpose: Determines whether the client explicitly requested permissions that imply trusting the project directory. Trust affects whether the server should persist project trust for the working directory.

Data flow: It checks sandbox mode, named permission profiles, and explicit permission profiles against the current working directory, returning true if any requested setting trusts project writes or full access.

Call relations: thread_start_task calls this while deciding whether to mark a requested working directory as trusted.

Call graph: called by 1 (thread_start_task); 1 external calls (matches!).

fn permission_profile_trusts_project(
    profile: &codex_protocol::models::PermissionProfile,
    cwd: &Path,
) -> bool

Purpose: Checks whether an effective permission profile gives enough access to consider the project trusted. A permission profile is a bundle of file-system and approval rules.

Data flow: It receives a permission profile and working directory, returns true for disabled or external profiles, or checks whether a managed sandbox can write to the cwd.

Call relations: thread_start_task uses this alongside requested_permissions_trust_project during startup trust handling.

Call graph: calls 1 internal fn (file_system_sandbox_policy); called by 1 (thread_start_task).

fn build_thread_from_snapshot(
    thread_id: ThreadId,
    session_id: String,
    config_snapshot: &ThreadConfigSnapshot,
    path: Option<PathBuf>,
) -> Thread

Purpose: Builds a client-facing Thread object from a live configuration snapshot. It is used before or without a stored thread record.

Data flow: It receives thread id, session id, config snapshot, and optional path, fills current timestamps, cwd, provider, source, thread source, ephemeral flag, and default empty preview/turns, then returns the Thread.

Call relations: Start, resume, fork, listener attachment, and build_thread_from_loaded_snapshot use this to represent live threads.

Call graph: calls 1 internal fn (cwd); called by 5 (load_thread_from_resume_source_or_send_internal, thread_fork_inner, thread_start_task, try_attach_thread_listener, build_thread_from_loaded_snapshot); 5 external calls (new, new, env!, to_string, now_utc).

fn paginate_background_terminals(
    terminals: &[ThreadBackgroundTerminal],
    cursor: Option<String>,
    limit: Option<u32>,
) -> Result<(Vec<ThreadBackgroundTerminal>, Option<String>), JSONRPCEr

Purpose: Slices a list of background terminal records into a cursor-based page.

Data flow: It receives terminal records, optional cursor, and optional limit; it finds the first terminal after the cursor process id, applies the limit, and returns the page plus next cursor.

Call relations: thread_background_terminals_list_inner calls this after collecting live terminal records.

Call graph: called by 1 (thread_background_terminals_list_inner); 2 external calls (iter, len).

fn build_thread_from_loaded_snapshot(
    thread_id: ThreadId,
    config_snapshot: &ThreadConfigSnapshot,
    loaded_thread: &CodexThread,
) -> Thread

Purpose: Convenience helper that builds a Thread object from a live loaded thread and its config snapshot.

Data flow: It receives a thread id, config snapshot, and live thread, extracts the live session id and rollout path, and calls build_thread_from_snapshot.

Call relations: load_live_thread_view uses this as the fallback live representation for thread/read.

Call graph: calls 3 internal fn (build_thread_from_snapshot, rollout_path, session_configured); called by 1 (load_live_thread_view).

fn new(
        thread_manager: Arc<ThreadManager>,
        outgoing: Arc<OutgoingMessageSender>,
        config: Arc<Config>,
        thread_state_manager: ThreadStateManager,
        state_db: Optio

Purpose: Creates a processor with all the shared services it needs: thread lookup, outgoing messages, configuration, thread state, optional state database access, and the goal service.

Data flow: The caller provides shared references to the surrounding server pieces. The function stores them inside a new ThreadGoalRequestProcessor. The result is a ready-to-use object that can answer goal-related client requests.

Call relations: It is called during the larger server setup path named new, so the request-handling layer can later route goal requests to this processor.

Call graph: called by 1 (new).

async fn thread_goal_set(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadGoalSetParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public request wrapper for setting or updating a thread goal. It adapts the internal success result into the standard client-response shape used by the request processor framework.

Data flow: It receives a client request id and goal-setting parameters. It passes both to thread_goal_set_inner. If the inner work succeeds, it returns no extra payload because the response is sent explicitly inside the inner function.

Call relations: handle_initialized_client_request calls this when an initialized client sends a goal-set request. This function immediately hands the real work to thread_goal_set_inner.

Call graph: calls 1 internal fn (thread_goal_set_inner); called by 1 (handle_initialized_client_request).

async fn thread_goal_get(
        &self,
        params: ThreadGoalGetParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public request wrapper for reading the current goal for a thread. It converts the internal response into the generic payload type expected by the client request system.

Data flow: It receives goal-get parameters, asks thread_goal_get_inner to fetch the goal, and wraps the returned response so it can be sent back through the normal request path.

Call relations: handle_initialized_client_request calls this for goal-get requests. It delegates the lookup and validation to thread_goal_get_inner.

Call graph: calls 1 internal fn (thread_goal_get_inner); called by 1 (handle_initialized_client_request).

async fn thread_goal_clear(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadGoalClearParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: Public request wrapper for clearing a thread goal. It adapts the internal clear operation to the standard request processor return format.

Data flow: It receives a client request id and clear parameters. It calls thread_goal_clear_inner, which sends the actual clear response. On success this wrapper returns no extra payload.

Call relations: handle_initialized_client_request calls this for goal-clear requests. It passes control to thread_goal_clear_inner for the real validation, storage update, and notification work.

Call graph: calls 1 internal fn (thread_goal_clear_inner); called by 1 (handle_initialized_client_request).

async fn emit_resume_goal_snapshot_and_continue(
        &self,
        thread_id: ThreadId,
        thread: &CodexThread,
    )

Purpose: Sends the client a snapshot of the thread goal during thread resume, then lets the thread continue its normal idle lifecycle. This preserves a predictable order: resume data first, extension reactions second.

Data flow: It receives a thread id and the running thread object. If the goals feature is off, it does nothing. If goals are enabled, it emits a goal snapshot, then asks the thread to emit its idle lifecycle event if it is idle.

Call relations: thread_resume_inner calls this during resume. It calls emit_thread_goal_snapshot first, then emit_thread_idle_lifecycle_if_idle so later extension work does not race ahead of the resume snapshot.

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

async fn pending_resume_goal_state(
        &self,
        thread: &CodexThread,
    ) -> (bool, Option<StateDbHandle>)

Purpose: Figures out whether resume should include goal-state work and which state database should be used for it.

Data flow: It receives a thread. It checks the feature flag. If goals are enabled, it prefers the thread’s own state database and otherwise falls back to the processor’s shared one. It returns a yes-or-no flag plus the database handle, if any.

Call relations: resume_running_thread calls this while preparing a resumed thread. It reads the thread’s state_db when available so later resume code can use the right storage source.

Call graph: calls 1 internal fn (state_db); called by 1 (resume_running_thread).

async fn thread_goal_set_inner(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadGoalSetParams,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Does the real work for setting a thread goal: validate the request, make sure storage is up to date, save the new goal, reply to the client, notify listeners, and apply any runtime side effects.

Data flow: It starts with a request id and client parameters. It checks the feature flag, parses the thread id, finds the correct state database, reconciles the thread rollout into storage, gathers the listener channel, and asks the goal service to set the requested objective, status, and token budget. It sends a set response, emits a goal-updated notification, applies runtime effects, and returns success or a JSON-RPC error.

Call relations: thread_goal_set calls this. Inside, it uses parse_thread_id_for_request, state_db_for_materialized_thread, reconcile_thread_goal_rollout, thread_state, conversion helpers from the goal types, and emit_thread_goal_updated_ordered to complete the full set-request flow.

Call graph: calls 6 internal fn (from, emit_thread_goal_updated_ordered, reconcile_thread_goal_rollout, state_db_for_materialized_thread, parse_thread_id_for_request, thread_state); called by 1 (thread_goal_set); 2 external calls (clone, Set).

async fn thread_goal_get_inner(
        &self,
        params: ThreadGoalGetParams,
    ) -> Result<ThreadGoalGetResponse, JSONRPCErrorError>

Purpose: Does the real work for reading a thread goal from persistent state.

Data flow: It receives client parameters. It checks that goals are enabled, parses the thread id, finds the state database for that saved thread, and asks the goal service for the stored goal. It converts any found goal into the API shape and returns it in a get response.

Call relations: thread_goal_get calls this. It relies on parse_thread_id_for_request and state_db_for_materialized_thread before asking the goal service for the stored data.

Call graph: calls 2 internal fn (state_db_for_materialized_thread, parse_thread_id_for_request); called by 1 (thread_goal_get).

async fn thread_goal_clear_inner(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadGoalClearParams,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Does the real work for clearing a thread goal and telling clients if something was actually removed.

Data flow: It receives a request id and clear parameters. It checks the feature flag, parses the thread id, finds the state database, reconciles rollout data, gets the listener channel, and asks the goal service to clear the goal. It sends a clear response with a boolean result. If a goal was cleared, it emits a cleared notification.

Call relations: thread_goal_clear calls this. It uses parse_thread_id_for_request, state_db_for_materialized_thread, reconcile_thread_goal_rollout, thread_state, and emit_thread_goal_cleared_ordered as the pieces of the clear-request flow.

Call graph: calls 5 internal fn (emit_thread_goal_cleared_ordered, reconcile_thread_goal_rollout, state_db_for_materialized_thread, parse_thread_id_for_request, thread_state); called by 1 (thread_goal_clear).

async fn state_db_for_materialized_thread(
        &self,
        thread_id: ThreadId,
    ) -> Result<StateDbHandle, JSONRPCErrorError>

Purpose: Finds the state database that can safely store or read goal data for a real saved thread. It rejects temporary threads because they do not have durable goal storage.

Data flow: It receives a thread id. If the thread is running, it checks that it has a rollout path and uses the thread’s own state database if present. If the thread is not running, it searches the Codex home directory for the saved thread. If all checks pass, it returns a state database handle; otherwise it returns a clear client or server error.

Call relations: emit_thread_goal_snapshot, thread_goal_clear_inner, thread_goal_get_inner, and thread_goal_set_inner all call this before touching goal state. It uses rollout lookup helpers such as find_thread_path_by_id_str when the thread is not already loaded.

Call graph: called by 4 (emit_thread_goal_snapshot, thread_goal_clear_inner, thread_goal_get_inner, thread_goal_set_inner); 3 external calls (find_thread_path_by_id_str, format!, to_string).

async fn reconcile_thread_goal_rollout(
        &self,
        thread_id: ThreadId,
        state_db: &StateDbHandle,
    ) -> Result<(), JSONRPCErrorError>

Purpose: Brings the saved rollout file for a thread into agreement with the state database before changing goal data. This helps avoid updating goals against stale or missing thread state.

Data flow: It receives a thread id and state database. It finds the thread’s rollout path from the running thread or by searching saved thread files. Then it calls the rollout reconciliation process with the database, rollout path, and current model provider information. It returns success after reconciliation has been requested.

Call relations: thread_goal_set_inner and thread_goal_clear_inner call this before mutating goal state. It uses find_thread_path_by_id_str when needed and hands the path to reconcile_rollout, which performs the storage synchronization.

Call graph: called by 2 (thread_goal_clear_inner, thread_goal_set_inner); 2 external calls (find_thread_path_by_id_str, to_string).

async fn emit_thread_goal_snapshot(&self, thread_id: ThreadId)

Purpose: Sends the current goal state for a thread to the client, usually while resuming a thread. It tries to preserve event ordering by sending through the thread listener first.

Data flow: It receives a thread id. It finds the state database; if that fails, it logs a warning and stops. It then looks up the thread listener channel. If the listener accepts a snapshot command, the function is done. If not, it logs a warning and sends the snapshot notification directly through the outgoing message sender.

Call relations: emit_resume_goal_snapshot_and_continue calls this during resume. It uses state_db_for_materialized_thread and thread_state, and falls back to send_thread_goal_snapshot_notification when the ordered listener path is unavailable.

Call graph: calls 2 internal fn (state_db_for_materialized_thread, thread_state); called by 1 (emit_resume_goal_snapshot_and_continue); 1 external calls (warn!).

async fn emit_thread_goal_updated_ordered(
        &self,
        thread_id: ThreadId,
        goal: ThreadGoal,
        listener_command_tx: Option<tokio::sync::mpsc::UnboundedSender<ThreadListenerCo

Purpose: Notifies clients that a thread goal was updated, while trying to keep the notification in the same order as other thread events.

Data flow: It receives a thread id, the updated goal, and an optional listener command channel. If the channel exists and accepts the update command, the listener will emit the notification later in order. If the channel is missing or closed, it sends the server notification directly with the thread id and goal.

Call relations: thread_goal_set_inner calls this after sending the direct set response. It uses the listener path when possible and otherwise sends a ThreadGoalUpdated notification itself.

Call graph: called by 1 (thread_goal_set_inner); 4 external calls (ThreadGoalUpdated, clone, to_string, warn!).

async fn emit_thread_goal_cleared_ordered(
        &self,
        thread_id: ThreadId,
        listener_command_tx: Option<tokio::sync::mpsc::UnboundedSender<ThreadListenerCommand>>,
    )

Purpose: Notifies clients that a thread goal was cleared, again trying to keep the message ordered with other thread events.

Data flow: It receives a thread id and an optional listener command channel. If the listener channel accepts the clear command, the listener owns the later notification. If the channel is unavailable, it sends a ThreadGoalCleared server notification directly.

Call relations: thread_goal_clear_inner calls this only when the goal service says a goal was actually cleared. It prefers the thread listener and falls back to outgoing notification if needed.

Call graph: called by 1 (thread_goal_clear_inner); 3 external calls (ThreadGoalCleared, to_string, warn!).

fn api_thread_goal_from_state(goal: codex_state::ThreadGoal) -> ThreadGoal

Purpose: Converts a stored thread-goal record into the API format sent to clients. This keeps database-oriented types from leaking directly into client messages.

Data flow: It receives a codex_state ThreadGoal. It copies the thread id, objective, budget, usage counts, and timestamps into the API ThreadGoal shape, and converts the status through api_thread_goal_status_from_state. It returns the client-facing goal object.

Call relations: Other parts of the request layer can use this helper when they need to present saved goal state through the API. It calls api_thread_goal_status_from_state for the status field.

Call graph: calls 1 internal fn (api_thread_goal_status_from_state).

fn api_thread_goal_status_from_state(status: codex_state::ThreadGoalStatus) -> ThreadGoalStatus

Purpose: Translates each stored goal status into the matching API status value.

Data flow: It receives a status from the state layer, such as Active, Paused, Blocked, or Complete. It matches that value one-for-one to the API enum and returns the API version.

Call relations: api_thread_goal_from_state calls this while building the client-facing ThreadGoal object.

Call graph: called by 1 (api_thread_goal_from_state).

fn goal_service_error(err: GoalServiceError) -> JSONRPCErrorError

Purpose: Turns errors from the goal service into JSON-RPC errors, the error format used for client requests.

Data flow: It receives a GoalServiceError. If the service says the request was invalid, it becomes an invalid-request error for the client. If the service reports an internal failure, it becomes an internal server error. The returned value can be sent through the normal JSON-RPC error path.

Call relations: The inner request functions use this mapping when goal-service calls fail, so service-layer errors are reported to clients in the server’s standard request format.

fn parse_thread_id_for_request(thread_id: &str) -> Result<ThreadId, JSONRPCErrorError>

Purpose: Checks that a thread id string from a client request is well formed and turns it into the internal ThreadId type.

Data flow: It receives the thread id as text. It asks ThreadId::from_string to parse it. On success it returns the parsed id; on failure it returns an invalid-request error that explains the id was not valid.

Call relations: thread_goal_set_inner, thread_goal_get_inner, and thread_goal_clear_inner call this before doing any storage work, so bad client input is rejected early.

Call graph: calls 1 internal fn (from_string); called by 3 (thread_goal_clear_inner, thread_goal_get_inner, thread_goal_set_inner).

async fn thread_delete(
        &self,
        request_id: ConnectionRequestId,
        params: ThreadDeleteParams,
    ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError>

Purpose: This is the top-level handler for a client’s thread/delete request. It coordinates the delete operation, sends the direct response, and then broadcasts deletion notifications.

Data flow: It receives a request id and delete parameters from the client. It creates an empty list that will later hold the deleted thread ids, takes a permit to safely work with shared thread-list state, and asks thread_delete_response to do the actual deletion. If that succeeds, it sends the response tied to the original request id and then sends notifications for every deleted thread; if it fails, it returns the error without sending success messages.

Call relations: This function is the entry point into this file’s workflow. It calls ThreadRequestProcessor::thread_delete_response to perform the deletion and fill in the list of deleted ids, then calls ThreadRequestProcessor::send_thread_deleted_notifications so other clients can update their views.

Call graph: calls 2 internal fn (send_thread_deleted_notifications, thread_delete_response); 2 external calls (new, clone).

async fn thread_delete_response(
        &self,
        params: ThreadDeleteParams,
        deleted_thread_ids: &mut Vec<String>,
    ) -> Result<ThreadDeleteResponse, JSONRPCErrorError>

Purpose: This function performs the real delete plan. It finds the target thread and its descendants, checks that deletion is allowed, prepares each thread, removes them from storage and app-server state, and builds the successful response.

Data flow: It receives the client parameters and a mutable list where it can record deleted thread ids. It turns the incoming thread id string into an internal ThreadId, gathers descendant thread ids from both the state database and the live thread manager, and removes duplicates. It validates the root thread, prepares every thread for deletion, deletes children before deleting the parent, cleans matching state database entries, appends the deleted ids as strings to the shared list, and returns an empty ThreadDeleteResponse on success. If parsing, validation, live-thread lookup, storage deletion, or state cleanup fails, it converts that problem into a JSON-RPC error.

Call relations: It is called by ThreadRequestProcessor::thread_delete after the outer request setup is complete. During its work it calls ThreadRequestProcessor::validate_root_thread_delete before making destructive changes, ThreadRequestProcessor::prepare_thread_for_delete before each removal, and thread_store_delete_error or core_thread_write_error when lower-level failures need to become client-facing errors.

Call graph: calls 5 internal fn (prepare_thread_for_delete, validate_root_thread_delete, thread_store_delete_error, core_thread_write_error, from_string); called by 1 (thread_delete); 1 external calls (warn!).

async fn send_thread_deleted_notifications(&self, deleted_thread_ids: Vec<String>)

Purpose: This function tells clients that specific threads were deleted. It sends one server notification for each deleted thread id.

Data flow: It receives a list of deleted thread id strings. For each id, it creates a ThreadDeletedNotification wrapped as a server notification and sends it through the outgoing connection channel. It does not return a value; its effect is that clients listening to server events are informed.

Call relations: It is called by ThreadRequestProcessor::thread_delete only after the delete response has been sent successfully. This ordering means the requester first gets confirmation, and then all interested clients can react to the thread-deleted events.

Call graph: called by 1 (thread_delete); 1 external calls (ThreadDeleted).

async fn validate_root_thread_delete(
        &self,
        thread_id: ThreadId,
        has_descendants: bool,
    ) -> Result<(), JSONRPCErrorError>

Purpose: This function decides whether the requested root thread is a valid delete target. It prevents deleting temporary live threads directly and checks that a missing root thread is still explainable by descendant or state records.

Data flow: It receives the root ThreadId and a flag saying whether descendants were found. First it checks the live thread manager: if the live thread exists and is persisted, deletion is allowed; if it is ephemeral, meaning temporary and not stored, deletion is rejected. If the live thread is not found, it checks persistent thread storage. If storage also says the thread is missing, it allows the operation only when descendants exist or when app-server state still contains the thread; otherwise it returns a “thread not found” style error. Other storage failures are converted into JSON-RPC errors.

Call relations: It is called by ThreadRequestProcessor::thread_delete_response before any deletion happens. When storage errors need to be reported consistently, it hands them to thread_store_delete_error so the client receives the same kind of error message as other delete failures.

Call graph: calls 1 internal fn (thread_store_delete_error); called by 1 (thread_delete_response); 1 external calls (format!).

async fn prepare_thread_for_delete(&self, thread_id: ThreadId)

Purpose: This function does last-minute cleanup before a thread is physically deleted. It gives the rest of the system a chance to stop or detach work tied to that thread, then flushes logs if a log database is present.

Data flow: It receives a ThreadId. It asks the broader thread processor to prepare that thread for removal with the reason label delete, then, if logging storage exists, flushes it so pending log data is written out before the thread disappears. It returns nothing; its result is a safer deletion state.

Call relations: It is called by ThreadRequestProcessor::thread_delete_response once for every thread that will be removed. It sits between validation and actual storage deletion, like clearing people out of a room before locking the door.

Call graph: called by 1 (thread_delete_response).

fn thread_store_delete_error(err: ThreadStoreError) -> JSONRPCErrorError

Purpose: This helper turns low-level thread storage errors into JSON-RPC errors that make sense to clients. It keeps delete-related error messages consistent and avoids exposing raw storage details unnecessarily.

Data flow: It receives a ThreadStoreError. If the thread was not found, it returns an invalid-request error saying so; if the request was invalid, it passes along the message; if the storage backend does not support the operation, it delegates to the shared unsupported-operation converter; otherwise it returns a general internal error saying deletion failed. The output is always a JSONRPCErrorError ready to send back through the request system.

Call relations: It is used by ThreadRequestProcessor::thread_delete_response when deletion from storage fails and by ThreadRequestProcessor::validate_root_thread_delete when validation discovers storage-related problems. It also calls unsupported_thread_store_operation for the special case where the backing store cannot perform the requested delete operation.

Call graph: calls 1 internal fn (unsupported_thread_store_operation); called by 2 (thread_delete_response, validate_root_thread_delete); 1 external calls (format!).

async fn on_call_response(
    call_id: String,
    receiver: oneshot::Receiver<ClientRequestResult>,
    conversation: Arc<CodexThread>,
)

Purpose: Waits for the client’s answer to a dynamic tool call, turns it into the core conversation format, and sends it back to the active conversation. It also protects the conversation from bad or missing client replies by creating a clear failure response instead.

Data flow: It receives a tool call id, a one-use receiver that will produce the client result, and the conversation thread to report back to. It waits for the receiver, then either decodes the JSON reply, ignores a reply that belongs to an old turn, or builds a fallback failure message. After that it converts the app-server response items into core response items and submits a DynamicToolResponse operation to the conversation; if that final submit fails, it logs the problem.

Call relations: This is called when bespoke event handling has arranged for a dynamic tool response to come back later. During that callback flow, it asks decode_response to understand successful JSON replies, uses fallback_response when the client or channel fails, checks turn-transition errors so stale responses are not sent, and finally hands the completed response to the conversation thread.

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

fn decode_response(value: serde_json::Value) -> (DynamicToolCallResponse, Option<String>)

Purpose: Turns raw JSON from the client into the structured dynamic tool response the app server expects. If the JSON does not match the expected shape, it creates a safe failure response instead of letting the bad data travel further.

Data flow: It takes a serde_json::Value, which is untyped JSON data. It tries to read that data as a DynamicToolCallResponse; on success, it returns the parsed response with no error message. On failure, it logs the decoding problem and returns a fallback response saying the dynamic tool response was invalid.

Call relations: on_call_response uses this after the client successfully sends back a value. If decoding fails, this function delegates to fallback_response, so the rest of the flow can still submit a normal-looking but unsuccessful tool response to the conversation.

Call graph: calls 1 internal fn (fallback_response); called by 1 (on_call_response); 1 external calls (error!).

fn fallback_response(message: &str) -> (DynamicToolCallResponse, Option<String>)

Purpose: Builds a standard unsuccessful dynamic tool response with a human-readable text message. It gives the rest of the system a consistent answer to send when the real tool response cannot be used.

Data flow: It receives a short message such as "dynamic tool request failed". It creates a DynamicToolCallResponse whose content contains that message as input text and whose success flag is false, and it also returns the same message separately as optional error text.

Call relations: on_call_response calls this when the client request fails or the reply channel closes. decode_response calls it when the client did reply, but the JSON was not a valid dynamic tool response. In both cases, this function supplies the replacement response that keeps the conversation from being left without an answer.

Call graph: called by 2 (decode_response, on_call_response); 1 external calls (vec!).

fn is_turn_transition_server_request_error(error: &JSONRPCErrorError) -> bool

Purpose: This function tells callers whether a JSON-RPC error means a pending request was resolved because the turn state changed. Callers use it to separate this expected, state-related cancellation from other failures.

Data flow: It receives a JSONRPCErrorError, reads its optional data field, looks for a JSON field called reason, and checks whether that value is the text turnTransition. It returns true only for that exact match; if the data is missing, the field is missing, the value is not text, or the text is different, it returns false.

Call relations: Several request-response paths call this helper when client-side results come back, including approval responses, user input responses, MCP elicitation responses, permission responses, and general call responses. In those flows, this function acts like a label reader: it tells the caller whether the error should be understood as the request becoming stale because the interaction moved on.

Call graph: called by 6 (mcp_server_elicitation_response_from_client_result, on_command_execution_request_approval_response, on_file_change_request_approval_response, on_request_user_input_response, request_permissions_response_from_client_result, on_call_response).

fn turn_transition_error_is_detected()

Purpose: This test proves that the helper recognizes the intended special error. It builds an error whose extra data says reason: turnTransition and checks that the result is true.

Data flow: The test creates a sample JSONRPCErrorError with a code, message, and JSON data containing the special reason. It passes that error into is_turn_transition_server_request_error, then compares the returned value with true.

Call relations: This test exercises the positive path for the helper. It uses JSON construction and an equality assertion to confirm that callers can rely on the helper to detect the turn-transition case.

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

fn unrelated_error_is_not_detected()

Purpose: This test proves that the helper does not treat every server error as a turn-transition error. It checks that an error with a different reason is rejected.

Data flow: The test creates a sample JSONRPCErrorError whose JSON data contains reason: other. It sends that error into is_turn_transition_server_request_error, then verifies that the returned value is false.

Call relations: This test exercises the negative path for the helper. It protects the callers from a dangerous mix-up where an unrelated failure might accidentally be treated as a harmless stale-request case.

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

async fn supported_models(
    thread_manager: Arc<ThreadManager>,
    include_hidden: bool,
) -> Vec<Model>

Purpose: This function returns the list of AI models that the app server should show or expose to a caller. It can either hide models that are not meant for normal selection, or include them for callers that need the full catalog.

Data flow: It receives a shared ThreadManager, which knows how to fetch the model catalog, and a include_hidden flag. It asks for the model list, filters each preset based on whether hidden models are allowed, converts each remaining preset into an app-server Model, and returns the resulting list.

Call relations: This is the public entry point in this file. When some app-server flow needs supported models, it calls this function; this function gets the raw presets from ThreadManager, then hands each preset to model_from_preset so the final answer is in the protocol shape expected by clients.

fn model_from_preset(preset: ModelPreset) -> Model

Purpose: This function converts one internal model preset into one client-facing model description. It exists so the rest of the app server does not have to know all the details of how preset fields map into protocol fields.

Data flow: It takes a ModelPreset as input. It copies basic information like IDs, names, descriptions, default status, input types, and service tiers; it reshapes upgrade details into ModelUpgradeInfo; it marks the model as hidden when it should not appear in the picker; and it converts reasoning effort presets into protocol options. The output is a complete Model ready to send to a client.

Call relations: supported_models calls this after it has chosen which presets to expose. During the conversion, this function calls reasoning_efforts_from_preset for the reasoning-effort part of the model, then combines that result with the rest of the copied model metadata.

Call graph: calls 1 internal fn (reasoning_efforts_from_preset).

fn reasoning_efforts_from_preset(
    efforts: Vec<ReasoningEffortPreset>,
) -> Vec<ReasoningEffortOption>

Purpose: This helper converts the internal descriptions of supported reasoning effort levels into the app-server protocol format. Reasoning effort is the setting that describes how much thinking work a model is allowed or expected to do.

Data flow: It receives a list of ReasoningEffortPreset values. For each one, it keeps the effort value and its human-readable description, wraps them in a ReasoningEffortOption, and returns the full converted list.

Call relations: This function is used only by model_from_preset. It handles one small piece of the larger model conversion so model_from_preset can assemble the full client-facing Model without embedding every detail inline.

Call graph: called by 1 (model_from_preset).

fn from_turn_context(
        turn_context: &TurnContext,
        params: ToolRouterParams<'_>,
        tool_search_handler_cache: &ToolSearchHandlerCache,
    ) -> Self

Purpose: Builds a ready-to-use tool router for one conversation turn. It uses the current turn settings and available tool sources to decide which tools exist and which ones the model should be shown.

Data flow: It receives the current turn context, a bundle of tool-related inputs such as MCP tools, extension executors, and dynamic tools, plus a tool search cache. It passes those ingredients to the tool-router builder. The result is a ToolRouter containing a registry for dispatching tools and a model-visible list of tool specifications.

Call relations: This is the main construction path used by turn-processing code and tests that need a realistic router. It delegates the actual assembly work to build_tool_router, keeping this file focused on the router interface rather than the detailed planning rules.

Call graph: calls 1 internal fn (build_tool_router); called by 11 (fatal_tool_error_stops_turn_and_reports_error, test_tool_runtime, built_tools, handle_output_item_done_returns_contributed_last_agent_message, extension_tool_executors_are_model_visible_and_dispatchable, mcp_parallel_support_uses_handler_data, parallel_support_does_not_match_namespaced_local_tool_names, specs_filter_deferred_dynamic_tools, tools_without_handlers_do_not_support_parallel, probe_with (+1 more)).

fn from_parts(registry: ToolRegistry, model_visible_specs: Vec<ToolSpec>) -> Self

Purpose: Creates a ToolRouter from an already-built registry and an already-chosen list of model-visible tool descriptions. It is useful when another part of the system has done the planning work already.

Data flow: It takes a ToolRegistry and a list of ToolSpec values. It stores both directly in a new ToolRouter. Nothing is looked up or changed.

Call relations: The builder code uses this as the final assembly step after deciding what tools to register and expose. Tests also use it to construct routers with precise behavior for cancellation and lifecycle scenarios.

Call graph: called by 3 (cancellation_after_handler_finishes_preserves_completed_lifecycle, cancellation_waiting_for_runtime_cleanup_emits_only_aborted_lifecycle, build_tool_router).

fn model_visible_specs(&self) -> Vec<ToolSpec>

Purpose: Returns the tool descriptions that should be sent to the model. These descriptions are the model’s menu of available actions.

Data flow: It reads the router’s stored list of ToolSpec values and returns a cloned copy. The router keeps its own copy unchanged, while the caller receives a list it can pass along or transform.

Call relations: Prompt-building code calls this when preparing the model request. Other conversion code also uses it when building a view of the router, so the model only sees the tools that were intentionally exposed.

Call graph: called by 2 (build_prompt, from_router).

fn registered_tool_names_for_test(&self) -> Vec<ToolName>

Purpose: Provides the names of tools registered inside the router for tests. This lets tests check that tool setup produced the expected internal directory.

Data flow: It asks the registry for its test-only list of tool names and returns that list. It does not affect runtime behavior.

Call relations: This is only compiled for tests. Test helper code calls it to verify that router construction registered the right tools, while the real application does not use it.

Call graph: calls 1 internal fn (tool_names_for_test); called by 1 (from_router).

fn tool_exposure_for_test(
        &self,
        name: &ToolName,
    ) -> Option<crate::tools::registry::ToolExposure>

Purpose: Reports how a particular tool is exposed, for tests. This helps verify whether a tool is visible to the model, hidden, or otherwise categorized by the registry.

Data flow: It receives a tool name, asks the registry for that tool’s exposure information, and returns the optional answer. If the tool is unknown, the result is empty.

Call relations: This is test-only inspection. It reaches into the registry through its public testing hook so tests can confirm exposure rules without duplicating router-building logic.

Call graph: calls 1 internal fn (tool_exposure).

fn create_diff_consumer(
        &self,
        tool_name: &ToolName,
    ) -> Option<Box<dyn ToolArgumentDiffConsumer>>

Purpose: Creates a helper that can consume incremental argument changes for a tool call, when that tool supports it. This is useful when the model streams tool-call arguments piece by piece instead of all at once.

Data flow: It receives a tool name and asks the registry whether that tool can provide a ToolArgumentDiffConsumer. If available, it returns the consumer boxed behind a common interface; otherwise it returns nothing.

Call relations: Streaming or turn-handling code can call this while a tool call is still being formed. The router does not interpret the diffs itself; it forwards the request to the registry, where each tool’s support is known.

Call graph: calls 1 internal fn (create_diff_consumer).

fn tool_supports_parallel(&self, call: &ToolCall) -> bool

Purpose: Answers whether a tool call is safe to run at the same time as other tool calls. This matters because some tools can run side by side, while others need to run alone to avoid conflicts.

Data flow: It reads the tool name from the ToolCall and asks the registry for that tool’s parallel-execution setting. If the registry has no answer, it returns false as the safe default.

Call relations: Scheduling code can use this before launching tool work. The router acts as a simple question-and-answer layer over the registry’s knowledge of each tool.

Call graph: calls 1 internal fn (supports_parallel_tool_calls).

fn tool_waits_for_runtime_cancellation(&self, call: &ToolCall) -> bool

Purpose: Answers whether a tool needs time to clean up after cancellation. This is important for tools such as runtime or shell-like operations that may need to stop a running process safely.

Data flow: It reads the tool name from the ToolCall and asks the registry whether that tool waits for runtime cancellation cleanup. If the registry has no information, it returns false.

Call relations: Cancellation-handling code can ask this before deciding how to report or wait on a stopped tool call. The router forwards the policy question to the registry, where tool-specific behavior is recorded.

Call graph: calls 1 internal fn (waits_for_runtime_cancellation).

fn build_tool_call(item: ResponseItem) -> Result<Option<ToolCall>, FunctionCallError>

Purpose: Converts a model response item into the project’s standard ToolCall format, if that response item is actually a tool request. It filters out response items that should not become local tool executions.

Data flow: It receives one ResponseItem from the model. For a normal function call, it combines the optional namespace and name into a ToolName and stores the raw arguments as a function payload. For a client-side tool search call, it parses the JSON arguments into SearchToolCallParams and creates a tool_search call. For a custom tool call, it stores the custom input. If the item is not a runnable tool request, it returns no call. If tool-search arguments cannot be parsed, it returns an error meant to be reported back to the model.

Call relations: Turn-processing code calls this when model output arrives. The ToolCall it returns is later passed into dispatch methods. It uses ToolName constructors to preserve namespacing, and serde JSON parsing for the structured tool-search arguments.

Call graph: calls 2 internal fn (new, plain); called by 5 (fatal_tool_error_stops_turn_and_reports_error, shell_tool_cancellation_waits_for_runtime_cleanup, handle_output_item_done, build_tool_call_uses_namespace_for_registry_name, extension_tool_executors_are_model_visible_and_dispatchable); 1 external calls (from_value).

async fn dispatch_tool_call_with_code_mode_result(
        &self,
        session: Arc<Session>,
        turn: Arc<TurnContext>,
        cancellation_token: CancellationToken,
        tracker: SharedT

Purpose: Runs a tool call and returns its result in the normal code-mode path. It packages the current session, turn, cancellation token, and tracking information around the tool request.

Data flow: It receives shared session and turn objects, a cancellation token, a tracker for turn changes, a ToolCall, and the source of the call. It forwards all of that to the shared inner dispatch function without a terminal-outcome flag. The output is either a tool result or an error from the call path.

Call relations: This is a convenience wrapper around the inner dispatcher. It is used when the caller does not need to coordinate with a separate flag saying that a final outcome has already been reached.

Call graph: calls 1 internal fn (dispatch_tool_call_with_code_mode_result_inner).

async fn dispatch_tool_call_with_terminal_outcome(
        &self,
        session: Arc<Session>,
        turn: Arc<TurnContext>,
        cancellation_token: CancellationToken,
        tracker: SharedT

Purpose: Runs a tool call while also sharing a flag that says whether a terminal outcome has been reached. This helps coordinate tool execution with flows where some event may already have ended the turn or made later results irrelevant.

Data flow: It receives the same information needed to run a tool call, plus an atomic boolean flag. An atomic boolean is a true-or-false value that can be safely read or changed by multiple tasks at once. It forwards everything to the shared inner dispatch function with that flag included. It returns the tool result or an error.

Call relations: This wrapper is used by code paths that need terminal-outcome coordination. Like the simpler dispatch wrapper, it hands the real work to dispatch_tool_call_with_code_mode_result_inner so both paths behave consistently.

Call graph: calls 1 internal fn (dispatch_tool_call_with_code_mode_result_inner).

async fn dispatch_tool_call_with_code_mode_result_inner(
        &self,
        session: Arc<Session>,
        turn: Arc<TurnContext>,
        cancellation_token: CancellationToken,
        tracker: S

Purpose: Performs the common dispatch setup for all router tool execution paths. It turns a plain ToolCall into a full ToolInvocation with all the context a tool needs, then asks the registry to run it.

Data flow: It takes session data, turn data, cancellation controls, a change tracker, a ToolCall, the call source, and optionally a terminal-outcome flag. It unpacks the ToolCall into tool name, call ID, and payload. It builds a ToolInvocation containing both the request and the surrounding runtime context. Then it passes that invocation to the registry, which runs the matching tool and returns the result or an error.

Call relations: Both public dispatch wrappers call this function. It is the bridge between the router’s simple ToolCall shape and the registry’s actual execution machinery, ending by calling dispatch_any_with_terminal_outcome on the registry.

Call graph: calls 1 internal fn (dispatch_any_with_terminal_outcome); called by 2 (dispatch_tool_call_with_code_mode_result, dispatch_tool_call_with_terminal_outcome).

fn extension_tool_executors(
    session: &Session,
) -> Vec<Arc<dyn ToolExecutor<ExtensionToolCall>>>

Purpose: Collects tool executors supplied by installed extensions for the current session. This lets outside extension code contribute tools that can be made visible to the model and dispatched like built-in tools.

Data flow: It reads the session’s extension services, asks each tool contributor for its tools using both session-level and thread-level extension data, and flattens all contributed executors into one list. The output is a vector of shared tool executor objects.

Call relations: Tool-building code calls this while assembling the available tools. The resulting executors are later included in router construction, so extension tools can appear in the model’s tool list and be run through the same dispatch path as other tools.

Call graph: called by 1 (built_tools).

fn matches_kind(&self, payload: &ToolPayload) -> bool

Purpose: Says whether this tool can accept the kind of request payload it was given. By default, core tools accept normal function calls and tool-search calls.

Data flow: It receives a tool payload, checks its variant, and returns true for supported payload kinds or false for anything else.

Call relations: During dispatch, the registry asks the selected tool this question before running it. If the answer is false, the registry stops the call and reports an incompatible payload instead of sending bad input to the tool.

Call graph: 1 external calls (matches!).

fn waits_for_runtime_cancellation(&self) -> bool

Purpose: Tells the host whether this tool wants time to clean up when cancellation happens. The default is no, meaning cancellation can return an aborted response without waiting for extra teardown.

Data flow: It takes no extra input beyond the tool itself and returns a boolean cancellation preference.

Call relations: Other parts of the tool system query this through the registry when deciding how to treat a cancelled tool call.

fn telemetry_tags(
        &'a self,
        _invocation: &'a ToolInvocation,
    ) -> BoxFuture<'a, ToolTelemetryTags>

Purpose: Provides optional extra labels for telemetry, which is the system's structured record of what happened. The default returns no extra labels.

Data flow: It receives the tool invocation and returns an asynchronous result containing a list of key-value tags.

Call relations: The registry calls this just before execution so tool-specific information can be added to timing, success, and failure records.

Call graph: 2 external calls (pin, new).

fn post_tool_use_payload(
        &self,
        invocation: &ToolInvocation,
        result: &dyn ToolOutput,
    ) -> Option<PostToolUsePayload>

Purpose: Builds the information sent to post-tool-use hooks after a function tool finishes. These hooks can inspect the tool name, input, and response before the model sees the result.

Data flow: It reads the invocation and the produced tool output. For function-call payloads, it creates a hook-facing package containing the hook tool name, tool-use id, input JSON, and response JSON; for unsupported payload kinds it returns nothing.

Call relations: handle_any_tool calls this after the tool has produced output. The registry later uses the returned payload to run post-tool-use hooks.

Call graph: calls 4 internal fn (function_hook_tool_name, post_tool_use_id, post_tool_use_input, post_tool_use_response); called by 1 (handle_any_tool).

fn pre_tool_use_payload(&self, invocation: &ToolInvocation) -> Option<PreToolUsePayload>

Purpose: Builds the information sent to pre-tool-use hooks before a function tool runs. These hooks can approve, block, or sometimes rewrite the input.

Data flow: It reads the invocation's function arguments, converts them into hook-friendly JSON, pairs them with a hook-facing tool name, and returns that package. Non-function payloads produce no hook payload.

Call relations: The registry calls this before executing a tool. If it returns a payload, the registry runs pre-tool-use hooks with that data.

Call graph: calls 2 internal fn (function_hook_tool_input, function_hook_tool_name).

fn with_updated_hook_input(
        &self,
        invocation: ToolInvocation,
        updated_input: Value,
    ) -> Result<ToolInvocation, FunctionCallError>

Purpose: Rebuilds a tool invocation after a pre-tool-use hook rewrites the input. The default behavior serializes the updated JSON back into function arguments.

Data flow: It receives an existing invocation and rewritten JSON input. If the invocation is a function call, it replaces the argument string and returns the updated invocation; otherwise, or if serialization fails, it returns an error to show the model.

Call relations: dispatch_any_with_terminal_outcome uses this when a pre-tool-use hook says to continue with changed input. Tools with special hook contracts can override it.

Call graph: 2 external calls (to_string, RespondToModel).

fn create_diff_consumer(&self) -> Option<Box<dyn ToolArgumentDiffConsumer>>

Purpose: Optionally creates an object that can read streamed argument changes while the model is still forming a tool call. The default says this tool does not support that feature.

Data flow: It takes no outside data and returns either a diff consumer or nothing.

Call relations: The registry exposes this so higher-level streaming code can ask a tool whether it wants partial argument updates.

fn finish(&mut self) -> Result<Option<EventMsg>, FunctionCallError>

Purpose: Lets a streamed argument consumer flush or finalize any partial input before the tool call completes. The default has nothing to finish.

Data flow: It receives the consumer's current internal state and returns either a final event, no event, or an error.

Call relations: Streaming tool-call code can call this after all argument diffs have been consumed. Implementations may override it when partial input needs a final protocol event.

fn into_response(self) -> ResponseInputItem

Purpose: Turns a completed tool result into the protocol item that can be sent back to the model. This is the normal model-facing response path.

Data flow: It consumes the stored call id, original payload, and tool output, then asks the output to format itself as a response item.

Call relations: Code that receives AnyToolResult from the registry uses this when it wants the ordinary conversation response.

fn code_mode_result(self) -> serde_json::Value

Purpose: Turns a completed tool result into the JSON value used by code-mode flows. This is separate from the usual model response format.

Data flow: It consumes the stored payload and output, then asks the output for its code-mode representation.

Call relations: Callers that dispatch tools for code-mode handling use this instead of into_response when they need a raw JSON-style result.

fn log_preview(&self) -> String

Purpose: Keeps logging based on the original tool output even if a post-tool hook changes what the model sees. This preserves an honest preview of what the tool actually produced.

Data flow: It reads the wrapped original output and returns that output's log preview text.

Call relations: This wrapper is created when a post-tool-use hook supplies feedback that should replace the model-visible answer.

fn success_for_logging(&self) -> bool

Purpose: Keeps the logged success or failure status from the original tool output. Hook feedback should not rewrite whether the tool itself succeeded.

Data flow: It asks the original output for its logging success flag and returns that value unchanged.

Call relations: The registry may wrap an output with PostToolUseFeedbackOutput after hooks run; telemetry still uses this original success signal.

fn to_response_item(&self, call_id: &str, payload: &ToolPayload) -> ResponseInputItem

Purpose: Shows the hook's feedback message to the model instead of the original tool output. This lets a post-tool hook steer what the model is allowed to see.

Data flow: It receives the call id and payload, then formats the stored feedback output as the response item.

Call relations: After a post-tool-use hook returns feedback, the registry wraps the original result so this method controls the model-visible response.

Call graph: calls 1 internal fn (to_response_item).

fn code_mode_result(&self, payload: &ToolPayload) -> Value

Purpose: Keeps code-mode output based on the original tool result, not the hook feedback text. This separates machine-oriented results from model-facing feedback.

Data flow: It receives the payload and returns the original output's code-mode JSON value.

Call relations: When the wrapped result is used in a code-mode path, this method prevents hook feedback from replacing the underlying structured result.

fn override_tool_exposure(
    handler: Arc<dyn CoreToolRuntime>,
    exposure: ToolExposure,
) -> Arc<dyn CoreToolRuntime>

Purpose: Returns a version of a tool with a different visibility setting. Visibility controls whether and how a tool is exposed to the model.

Data flow: It receives a tool runtime and the desired exposure. If the tool already has that exposure, it returns the same tool; otherwise it wraps the tool in an ExposureOverride.

Call relations: Tool-building code calls this when adding tools with a specific exposure policy, such as collaboration tools or tools added through an exposure override.

Call graph: called by 2 (add_with_exposure, add_collaboration_tools); 1 external calls (new).

fn tool_name(&self) -> ToolName

Purpose: Reports the wrapped tool's name unchanged. Changing exposure should not rename the tool.

Data flow: It asks the inner tool for its name and returns it.

Call relations: The registry and tool listing code can treat the wrapper like the original tool because this method delegates to the wrapped handler.

fn spec(&self) -> ToolSpec

Purpose: Reports the wrapped tool's specification unchanged. The specification describes the tool's inputs and meaning.

Data flow: It asks the inner tool for its spec and returns it.

Call relations: When model-visible tool specs are built, this wrapper preserves the original tool description while changing only exposure.

fn exposure(&self) -> ToolExposure

Purpose: Returns the overridden visibility setting instead of the wrapped tool's own setting.

Data flow: It reads the wrapper's stored exposure value and returns it.

Call relations: Tool registration and model-spec generation use this to apply caller-chosen exposure rules.

fn supports_parallel_tool_calls(&self) -> bool

Purpose: Says whether the wrapped tool can run in parallel, while preventing hidden tools from being treated as parallel-callable. Hidden tools are not exposed for normal model tool calling.

Data flow: It checks the override exposure. If hidden, it returns false; otherwise it returns the inner tool's parallel-support answer.

Call relations: The registry and model-facing tool machinery ask this when deciding whether simultaneous calls are allowed.

fn search_info(&self) -> Option<ToolSearchInfo>

Purpose: Returns the wrapped tool's search metadata unchanged. Search metadata helps tool-search features describe or find tools.

Data flow: It asks the inner tool for search information and returns it.

Call relations: Tool-search code can still discover the wrapped tool's search details even though exposure has been overridden.

fn handle(&self, invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'_>

Purpose: Runs the wrapped tool exactly as usual. The wrapper changes visibility, not execution.

Data flow: It receives a tool invocation and passes it to the inner tool's handle method, returning the same future result.

Call relations: When the registry dispatches to an exposure-overridden tool, actual work is handed straight to the original handler.

fn matches_kind(&self, payload: &ToolPayload) -> bool

Purpose: Uses the wrapped tool's payload compatibility check. Exposure does not affect what payload kinds the tool can understand.

Data flow: It receives a payload, forwards it to the inner tool, and returns the inner answer.

Call relations: The registry's compatibility check works the same for wrapped and unwrapped tools.

fn waits_for_runtime_cancellation(&self) -> bool

Purpose: Uses the wrapped tool's cancellation cleanup preference. Exposure does not change cancellation behavior.

Data flow: It asks the inner tool whether cancellation should wait for runtime cleanup and returns that value.

Call relations: Cancellation policy queries through the registry still reflect the original tool's needs.

fn pre_tool_use_payload(&self, invocation: &ToolInvocation) -> Option<PreToolUsePayload>

Purpose: Uses the wrapped tool's pre-hook payload. Exposure does not change what hooks see before execution.

Data flow: It receives an invocation, forwards it to the inner tool's pre-hook payload method, and returns the result.

Call relations: During dispatch, pre-tool-use hooks receive the same input they would have received without the exposure wrapper.

fn post_tool_use_payload(
        &self,
        invocation: &ToolInvocation,
        result: &dyn ToolOutput,
    ) -> Option<PostToolUsePayload>

Purpose: Uses the wrapped tool's post-hook payload. Exposure does not change what hooks see after execution.

Data flow: It receives the invocation and output, forwards both to the inner tool, and returns the inner post-hook payload if any.

Call relations: handle_any_tool can collect post-tool hook data from wrapped tools without special cases.

fn with_updated_hook_input(
        &self,
        invocation: ToolInvocation,
        updated_input: Value,
    ) -> Result<ToolInvocation, FunctionCallError>

Purpose: Lets the wrapped tool rebuild an invocation after a hook rewrites input. The wrapper does not know the tool's input contract, so it delegates.

Data flow: It receives the invocation and updated JSON input, passes both to the inner tool, and returns the updated invocation or error.

Call relations: When pre-tool hooks rewrite input, dispatch still uses the real tool's rewrite logic even through an exposure wrapper.

fn telemetry_tags(
        &'a self,
        invocation: &'a ToolInvocation,
    ) -> BoxFuture<'a, ToolTelemetryTags>

Purpose: Uses the wrapped tool's telemetry labels. Changing exposure should not remove tool-specific logging context.

Data flow: It receives the invocation, asks the inner tool for asynchronous telemetry tags, and returns them.

Call relations: The registry's telemetry flow gets the same extra tags whether or not exposure was overridden.

fn create_diff_consumer(&self) -> Option<Box<dyn ToolArgumentDiffConsumer>>

Purpose: Uses the wrapped tool's streamed-argument diff consumer, if it has one. Exposure does not change streaming behavior.

Data flow: It asks the inner tool to create a diff consumer and returns that optional object.

Call relations: Streaming argument code can request diff consumers through the registry without caring about the exposure wrapper.

fn new(tools: HashMap<ToolName, Arc<dyn CoreToolRuntime>>) -> Self

Purpose: Creates a registry from an already prepared map of tool names to tool runtimes. It is the basic constructor used by other setup helpers.

Data flow: It receives a name-to-tool map, stores it inside a ToolRegistry, and returns the registry.

Call relations: from_tools and test helpers build maps and then call this to create the final registry.

Call graph: called by 2 (dispatch_notifies_tool_lifecycle_contributors, handler_looks_up_namespaced_aliases_explicitly).

fn from_tools(tools: impl IntoIterator<Item = Arc<dyn CoreToolRuntime>>) -> Self

Purpose: Builds a registry from a list of tools while checking for duplicate names. Duplicate names would make lookup ambiguous, like two people at a front desk answering to the same badge number.

Data flow: It receives an iterable collection of tool runtimes, reads each tool's name, inserts each into a map, and reports an error or panic if the name is already present. It returns a registry containing the unique tools.

Call relations: Tool setup code calls this when assembling the model-visible tool set and runtime registry.

Call graph: calls 1 internal fn (error_or_panic); called by 3 (cancellation_after_handler_finishes_preserves_completed_lifecycle, cancellation_waiting_for_runtime_cleanup_emits_only_aborted_lifecycle, build_model_visible_specs_and_registry); 3 external calls (new, new, format!).

fn empty_for_test() -> Self

Purpose: Creates an empty registry for tests. This lets tests exercise missing-tool behavior without registering real tools.

Data flow: It creates an empty map and returns a registry around it.

Call relations: Test code uses this when it needs a registry that cannot find any requested tool.

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

fn with_handler_for_test(handler: Arc<T>) -> Self

Purpose: Creates a test registry containing exactly one tool handler. This is a convenient shortcut for focused dispatch tests.

Data flow: It receives a handler, reads its tool name, stores it in a one-entry map, and returns a registry.

Call relations: Tests use this to verify dispatch, tracing, payload compatibility, and waiting behavior with a controlled fake or test handler.

Call graph: called by 3 (dispatch_lifecycle_trace_records_direct_and_code_mode_requesters, dispatch_lifecycle_trace_records_incompatible_payload_failures, missing_code_mode_wait_traces_only_the_wait_tool_call); 2 external calls (from, new).

fn tool(&self, name: &ToolName) -> Option<Arc<dyn CoreToolRuntime>>

Purpose: Looks up a tool by name and returns a shared reference to it if registered. This is the registry's private lookup helper.

Data flow: It receives a tool name, searches the internal map, clones the shared Arc pointer if found, and returns either the tool or nothing.

Call relations: Dispatch and query methods call this before asking a tool about execution, parallel support, cancellation, or diff consumers.

Call graph: called by 4 (create_diff_consumer, dispatch_any_with_terminal_outcome, supports_parallel_tool_calls, waits_for_runtime_cancellation).

fn tool_names_for_test(&self) -> Vec<ToolName>

Purpose: Returns the registered tool names in sorted order for tests. Sorting makes test expectations stable.

Data flow: It reads all keys from the internal tool map, clones them into a list, sorts the list, and returns it.

Call relations: Test-only wrapper code calls this to check which tools were registered.

Call graph: called by 1 (registered_tool_names_for_test).

fn tool_exposure(&self, name: &ToolName) -> Option<ToolExposure>

Purpose: Returns a registered tool's exposure setting for tests. This helps tests confirm whether tools are visible, hidden, or otherwise exposed as expected.

Data flow: It receives a tool name, looks it up in the map, and returns its exposure if found.

Call relations: Test helper code calls this when verifying exposure decisions made during tool setup.

Call graph: called by 1 (tool_exposure_for_test).

fn create_diff_consumer(
        &self,
        name: &ToolName,
    ) -> Option<Box<dyn ToolArgumentDiffConsumer>>

Purpose: Asks a registered tool to create a streamed-argument diff consumer. If the tool is missing or does not support diffs, it returns nothing.

Data flow: It receives a tool name, looks up the tool, and asks that tool for an optional diff consumer.

Call relations: Higher-level streaming code calls into the registry here so it can route partial argument updates to the correct tool.

Call graph: calls 1 internal fn (tool); called by 1 (create_diff_consumer).

fn supports_parallel_tool_calls(&self, name: &ToolName) -> Option<bool>

Purpose: Reports whether a named tool supports being called in parallel with other tools. This helps the system avoid unsafe simultaneous work.

Data flow: It receives a tool name, looks up the tool, and returns the tool's parallel-support flag if found.

Call relations: Tool capability checks call this before allowing or advertising parallel tool calls.

Call graph: calls 1 internal fn (tool); called by 1 (tool_supports_parallel).

fn waits_for_runtime_cancellation(&self, name: &ToolName) -> Option<bool>

Purpose: Reports whether a named tool wants cancellation to wait for its cleanup. This is important for tools that must close resources or finish teardown safely.

Data flow: It receives a tool name, looks up the tool, and returns the tool's cancellation-wait preference if found.

Call relations: Cancellation orchestration code calls this when deciding whether to wait for a tool runtime after cancellation.

Call graph: calls 1 internal fn (tool); called by 1 (tool_waits_for_runtime_cancellation).

async fn dispatch_any(
        &self,
        invocation: ToolInvocation,
    ) -> Result<AnyToolResult, FunctionCallError>

Purpose: Runs a tool invocation through the full registry dispatch path without an external terminal-outcome flag. It is the simpler public entry point for normal dispatch.

Data flow: It receives a tool invocation, passes it to dispatch_any_with_terminal_outcome with no shared completion marker, awaits the result, and returns either a tool result or an error.

Call relations: Callers that do not need special lifecycle coordination use this convenience method.

Call graph: calls 1 internal fn (dispatch_any_with_terminal_outcome).

async fn dispatch_any_with_terminal_outcome(
        &self,
        mut invocation: ToolInvocation,
        terminal_outcome_reached: Option<Arc<AtomicBool>>,
    ) -> Result<AnyToolResult, FunctionCa

Purpose: Runs the complete tool-call lifecycle: lookup, validation, pre-hooks, execution, telemetry, post-hooks, lifecycle notifications, and final result shaping. This is the heart of the file.

Data flow: It receives a tool invocation and optionally a shared flag saying whether some other path has already claimed the terminal outcome. It records active-turn state and telemetry tags, finds the tool, rejects unknown or incompatible calls, runs pre-tool-use hooks that may block or rewrite input, executes the tool while logging timing and success, runs post-tool-use hooks on successful output, records extra context, sends the final lifecycle notification if not already claimed, and returns either the completed AnyToolResult or a FunctionCallError.

Call relations: dispatch_any and code-mode dispatch call this when a tool must actually run. Inside the flow it calls helper functions such as handle_any_tool, notify_tool_finish_if_unclaimed, hook runners, telemetry helpers, and payload-format helpers.

Call graph: calls 13 internal fn (record_additional_contexts, run_post_tool_use_hooks, run_pre_tool_use_hooks, emit_metric_for_tool_read, permission_profile_policy_tag, permission_profile_sandbox_tag, from_text, flat_tool_name, notify_tool_start, tool (+3 more)); called by 2 (dispatch_any, dispatch_tool_call_with_code_mode_result_inner); 9 external calls (new, new, with_capacity, clone, format!, matches!, new, Fatal, RespondToModel).

async fn notify_tool_finish_if_unclaimed(
    invocation: &ToolInvocation,
    terminal_outcome_reached: Option<&AtomicBool>,
    outcome: ToolCallOutcome,
) -> bool

Purpose: Sends a tool-finished lifecycle event only if no other part of the system has already sent the terminal outcome. This prevents duplicate final notifications.

Data flow: It receives the invocation, an optional atomic boolean flag, and the outcome to report. If the flag exists and was already set, it returns false; otherwise it marks the flag, sends the finish notification, and returns true.

Call relations: dispatch_any_with_terminal_outcome uses this after blocked, failed, or completed tool paths so lifecycle listeners get exactly one final event.

Call graph: calls 1 internal fn (notify_tool_finish); called by 1 (dispatch_any_with_terminal_outcome).

async fn handle_any_tool(
    tool: &dyn CoreToolRuntime,
    invocation: ToolInvocation,
) -> Result<AnyToolResult, FunctionCallError>

Purpose: Actually calls the selected tool handler and packages its output with the metadata needed later. It also marks memory state as polluted if the output brought in external context while that memory mode is disabled.

Data flow: It receives a tool runtime and invocation, copies the call id and payload, awaits the tool's handle method, optionally updates persistent thread memory state, builds post-tool-use hook payload from the output, and returns an AnyToolResult.

Call relations: dispatch_any_with_terminal_outcome calls this inside its telemetry wrapper. It is the bridge between orchestration and the individual tool's own execution.

Call graph: calls 2 internal fn (post_tool_use_payload, mark_thread_memory_mode_polluted); 2 external calls (clone, handle).

fn function_hook_tool_name(invocation: &ToolInvocation) -> HookToolName

Purpose: Converts an internal tool name into the name format used by hooks. It preserves a special friendly name for spawn_agent while flattening most names into a single string.

Data flow: It reads the invocation's tool name and namespace. For the recognized spawn_agent case it returns the special hook name; otherwise it returns a new hook name based on the flattened tool name.

Call relations: CoreToolRuntime::pre_tool_use_payload and CoreToolRuntime::post_tool_use_payload call this so hooks see stable, expected tool names.

Call graph: calls 3 internal fn (flat_tool_name, new, spawn_agent); called by 2 (post_tool_use_payload, pre_tool_use_payload); 1 external calls (matches!).

fn function_hook_tool_input(arguments: &str) -> Value

Purpose: Converts a function tool's raw argument string into the JSON value that hooks receive as tool_input. Empty input becomes an empty object, valid JSON stays structured, and invalid JSON becomes a plain string.

Data flow: It receives the argument text, trims and checks whether it is empty, then either returns an empty JSON object, parsed JSON, or a JSON string containing the original text.

Call relations: CoreToolRuntime::pre_tool_use_payload uses this when preparing pre-hook input. post_tool_use_payload may also use the same kind of hook-facing input through tool output helpers.

Call graph: called by 1 (pre_tool_use_payload); 3 external calls (Object, new, from_str).

fn unsupported_tool_call_message(payload: &ToolPayload, tool_name: &ToolName) -> String

Purpose: Creates the error message shown when the registry cannot find a requested tool. It gives a slightly different message for custom tool calls.

Data flow: It receives the payload and tool name, checks whether the payload is a custom call, and returns a formatted message string.

Call relations: dispatch_any_with_terminal_outcome calls this when tool lookup fails, then records the failure and returns the message to the model.

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

fn server_request_thread_id(request: &ServerRequest) -> Option<ThreadId>

Purpose: This function extracts the conversation thread ID from a server request when that request is meant for a specific thread. Callers use it to route approval prompts and user-input requests to the right conversation.

Data flow: It receives a ServerRequest. For request types that include a thread_id string, it tries to parse that string into a ThreadId, which is the program’s safe internal form of a thread identifier. If parsing succeeds, it returns that ID; if parsing fails or the request is not thread-specific, it returns nothing.

Call relations: When handle_server_request_event receives a request from the app server, it calls this helper before deciding where the request belongs. This function delegates the actual text-to-ID conversion to ThreadId::from_string, then hands the caller either a usable thread ID or a clear “no thread target” result.

Call graph: calls 1 internal fn (from_string); called by 1 (handle_server_request_event).

fn server_notification_thread_target(
    notification: &ServerNotification,
) -> ServerNotificationThreadTarget

Purpose: This function decides the target scope for a server notification: one thread, the whole app, all users/screens globally, or an invalid thread reference. It keeps notification routing consistent across many different notification types.

Data flow: It receives a ServerNotification. It first checks the notification kind and pulls out a thread ID string when that kind has one. If there is a thread ID, it tries to parse it into a ThreadId; a valid one becomes Thread, and a malformed one becomes InvalidThreadId. If there is no thread ID, most such notifications become Global, while MCP server status updates without a thread become AppScoped because they affect the app’s server setup rather than one conversation.

Call relations: During normal notification handling, handle_server_notification_event calls this function to decide where the update should be shown or applied. The test functions also call it with carefully chosen notifications to prove that warnings, guardian warnings, MCP status updates, and thread settings updates are routed as intended.

Call graph: calls 1 internal fn (from_string); called by 7 (guardian_warning_notifications_route_to_threads, mcp_startup_notifications_route_to_threads, mcp_startup_notifications_without_threads_are_app_scoped, thread_settings_updated_notifications_route_to_threads, warning_notifications_route_to_threads_when_thread_id_is_present, warning_notifications_without_threads_are_global, handle_server_notification_event); 2 external calls (InvalidThreadId, Thread).

fn test_thread_settings() -> ThreadSettings

Purpose: This test helper builds a realistic ThreadSettings value so tests can create a thread-settings notification without repeating a large block of setup data. It exists only to support the test case for thread settings updates.

Data flow: It creates a fake working directory, fills in model, approval, sandbox, collaboration, and reasoning settings, and returns the completed ThreadSettings object. It does not change outside state.

Call relations: The thread-settings routing test calls this helper when building a ThreadSettingsUpdated notification. It uses the test path helper to create a predictable absolute path for the fake thread settings.

Call graph: 1 external calls (test_path_buf).

fn warning_notifications_without_threads_are_global()

Purpose: This test checks that a warning notification with no thread ID is treated as a global notification. That matters because such warnings should not be attached to an arbitrary conversation.

Data flow: It creates a warning notification whose thread_id field is empty, sends it through server_notification_thread_target, and compares the result with the expected Global target.

Call relations: The Rust test runner invokes this test. The test exercises the same routing helper used by normal notification handling and confirms one important branch of its warning behavior.

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

fn warning_notifications_route_to_threads_when_thread_id_is_present()

Purpose: This test checks that a warning notification is routed to a specific thread when it includes a valid thread ID. It protects against accidentally treating all warnings as global.

Data flow: It creates a new thread ID, puts that ID into a warning notification, passes the notification to server_notification_thread_target, and checks that the returned target is exactly that thread.

Call relations: The Rust test runner invokes this test. It builds a warning, calls the production routing helper, and verifies that the helper parses and preserves the thread identity.

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

fn guardian_warning_notifications_route_to_threads()

Purpose: This test checks that guardian warning notifications always route to their stated thread. Guardian warnings are safety or review-related messages, so sending them to the right conversation is important.

Data flow: It creates a new thread ID, builds a guardian warning notification containing that ID, runs it through server_notification_thread_target, and expects a Thread target with the same ID.

Call relations: The Rust test runner invokes this test. It directly exercises the guardian-warning branch of the notification routing helper.

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

fn mcp_startup_notifications_route_to_threads()

Purpose: This test checks that an MCP server status update with a thread ID is routed to that thread. MCP means Model Context Protocol, a way external tools or services can connect to the app.

Data flow: It creates a new thread ID, builds an MCP server status notification that includes the ID and a failed startup state, passes it to server_notification_thread_target, and checks that the result points to the same thread.

Call relations: The Rust test runner invokes this test. It confirms the thread-specific path for MCP server status updates, matching what normal notification handling relies on.

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

fn mcp_startup_notifications_without_threads_are_app_scoped()

Purpose: This test checks the special case where an MCP server status update has no thread ID. Instead of being global, it should be app-scoped because it describes app-level tool-server state.

Data flow: It builds an MCP server status notification with no thread_id, sends it through server_notification_thread_target, and checks that the result is AppScoped.

Call relations: The Rust test runner invokes this test. It protects the special MCP routing rule inside the production helper, so callers can distinguish app-level server status from truly global notifications.

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

fn thread_settings_updated_notifications_route_to_threads()

Purpose: This test checks that thread settings update notifications are routed back to the thread whose settings changed. Without this, a settings change in one conversation could appear in the wrong place.

Data flow: It creates a new thread ID, builds realistic thread settings with test_thread_settings, wraps them in a ThreadSettingsUpdated notification, passes that notification to server_notification_thread_target, and expects the matching thread target.

Call relations: The Rust test runner invokes this test. It uses the shared test settings helper, then exercises the thread-settings branch of the notification routing helper.

Call graph: calls 2 internal fn (new, server_notification_thread_target); 3 external calls (ThreadSettingsUpdated, assert_eq!, test_thread_settings).

fn app_server_attestation_provider(
    outgoing: Arc<OutgoingMessageSender>,
    thread_state_manager: ThreadStateManager,
) -> Arc<dyn AttestationProvider>

Purpose: Creates the app server's attestation provider, which core code can use when it needs an attestation header. It stores access to the outgoing-message channel and the thread state lookup needed to find a suitable client connection.

Data flow: It receives a shared outgoing message sender and a thread state manager. It keeps only a weak reference to the sender, so this provider does not keep the whole messaging system alive by itself. It returns a shared AttestationProvider object ready for use by the core server.

Call relations: This is the construction point for the provider. Later, when core code asks that provider for a header, the provider's header_for_request method does the actual work.

Call graph: 2 external calls (downgrade, new).

fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result

Purpose: Provides a simple debug display for the provider. This is useful when logging or inspecting the provider without exposing internal fields.

Data flow: It receives a formatter, writes the struct name AppServerAttestationProvider into it, and returns whether formatting succeeded. It does not read or change the provider's stored connection data.

Call relations: This is called by Rust's debugging and logging machinery when the provider is printed with debug formatting. It does not participate in attestation generation itself.

Call graph: 1 external calls (debug_struct).

fn header_for_request(&self, context: AttestationContext) -> GenerateAttestationFuture<'_>

Purpose: Starts the process of getting an attestation header for a particular request context. It returns future work, meaning the actual waiting happens asynchronously instead of blocking the server thread.

Data flow: It receives an attestation context containing the thread id. It first tries to turn its weak outgoing-message reference back into a usable shared sender. If that sender no longer exists, it returns a future that produces no header. Otherwise, it clones the thread state manager and starts an asynchronous request for a header value. If a JSON header string comes back, it converts it into an HTTP header value; if that conversion fails, it returns no header.

Call relations: Core attestation code calls this through the AttestationProvider interface. This method delegates the real client request and timeout behavior to request_attestation_header_value_with_timeout.

Call graph: calls 1 internal fn (request_attestation_header_value_with_timeout); 3 external calls (pin, upgrade, clone).

async fn request_attestation_header_value_with_timeout(
    outgoing: Arc<OutgoingMessageSender>,
    thread_state_manager: ThreadStateManager,
    thread_id: codex_protocol::ThreadId,
    timeout_dur

Purpose: Asks an attestation-capable client connection to generate a token, but gives up quickly if it cannot get a usable answer. It turns success and several failure cases into the standard app-server attestation header JSON.

Data flow: It receives the outgoing-message sender, the thread state manager, a thread id, and a timeout length. It asks the thread state manager for the first connection on that thread that can generate attestations. If there is no such connection, it returns no header. If there is one, it sends an AttestationGenerate request to that connection and waits for the reply. A successful reply is decoded into an AttestationGenerateResponse, and its token is wrapped into a header envelope. A request failure, cancellation, timeout, or malformed reply is logged and turned into a header envelope with an error status and no token.

Call relations: AppServerAttestationProvider::header_for_request calls this when core code needs a header. This function hands off final JSON creation to app_server_attestation_header_value, and it relies on the thread state manager to choose the right connection before sending the request.

Call graph: calls 2 internal fn (app_server_attestation_header_value, first_attestation_capable_connection_for_thread); called by 1 (header_for_request); 3 external calls (AttestationGenerate, timeout, warn!).

fn code(self) -> u8

Purpose: Converts an attestation result status into the small numeric code stored in the header JSON. These compact codes let the receiver distinguish success from different app-server-side failures.

Data flow: It receives one status value, such as success, timeout, or malformed response. It returns the matching number: success is 0, and each failure type has its own nonzero code. It does not change any state.

Call relations: app_server_attestation_header_value calls this while building the JSON envelope. The codes produced here are what make the serialized header understandable to later readers.

Call graph: called by 1 (app_server_attestation_header_value).

fn app_server_attestation_header_value(
    status: AppServerAttestationStatus,
    token: Option<&str>,
) -> Option<String>

Purpose: Builds the actual string that can be placed into an attestation header. It wraps the status and optional token in a small versioned JSON object.

Data flow: It receives a status and, optionally, a token string. It creates an envelope with version 1, the numeric status code, and the token only when one is present. It serializes that envelope to JSON and returns the JSON string, or returns no value if serialization unexpectedly fails.

Call relations: request_attestation_header_value_with_timeout calls this for both successful and failed attestation attempts. It calls AppServerAttestationStatus::code to translate the status into the number stored in the header.

Call graph: calls 1 internal fn (code); called by 1 (request_attestation_header_value_with_timeout); 1 external calls (to_string).

fn app_server_attestation_header_value_wraps_opaque_client_payloads()

Purpose: Checks that a successful client token is preserved exactly inside the app-server header envelope. This protects against accidentally altering the token while wrapping it.

Data flow: It supplies the success status and a sample opaque token string to app_server_attestation_header_value. It compares the returned JSON string with the exact expected output, including the version, success code, and token field.

Call relations: This test exercises the header-building helper directly. It confirms the success path used by request_attestation_header_value_with_timeout after a valid client response.

Call graph: 1 external calls (assert_eq!).

fn app_server_attestation_header_value_reports_app_server_failures()

Purpose: Checks that each app-server-side failure is represented by the correct JSON status code and does not include a token. This helps ensure callers can reliably tell why attestation was missing.

Data flow: It calls app_server_attestation_header_value several times with timeout, request failed, request canceled, and malformed response statuses. For each one, it compares the output to the exact JSON string expected for that failure code.

Call relations: This test covers the failure envelopes produced by request_attestation_header_value_with_timeout. It guards the meaning of the numeric status codes defined by AppServerAttestationStatus::code.

Call graph: 1 external calls (assert_eq!).

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

Purpose: Creates a filesystem watch manager for normal server use. It tries to start the real file watcher, but if that fails it logs a warning and uses a harmless no-op watcher so the server can keep running.

Data flow: It receives the shared outgoing-message sender. It attempts to build a FileWatcher; on success it keeps that watcher, and on failure it creates a no-op replacement. It then passes the outgoing sender and chosen watcher into the internal constructor and returns a ready FsWatchManager.

Call relations: This is the public setup path used when the server needs a watch manager. It delegates the actual struct setup to FsWatchManager::new_with_file_watcher, which is also useful in tests because tests can inject a fake or no-op watcher.

Call graph: calls 2 internal fn (new, noop); called by 1 (new); 3 external calls (new, new_with_file_watcher, warn!).

fn new_with_file_watcher(
        outgoing: Arc<OutgoingMessageSender>,
        file_watcher: Arc<FileWatcher>,
    ) -> Self

Purpose: Builds a watch manager from an already chosen file watcher. This is the shared construction step used by normal startup and by tests that want predictable watcher behavior.

Data flow: It receives an outgoing-message sender and a file watcher. It stores both in shared references and creates an empty state map protected by an asynchronous mutex, which is a lock that can be safely waited on in async code. It returns the completed manager.

Call relations: FsWatchManager::new calls this after deciding whether to use a real or no-op watcher. The test helper manager_with_noop_watcher also calls it directly so tests do not depend on real operating-system file watching.

Call graph: called by 1 (manager_with_noop_watcher); 3 external calls (new, new, default).

async fn watch(
        &self,
        connection_id: ConnectionId,
        params: FsWatchParams,
    ) -> Result<FsWatchResponse, JSONRPCErrorError>

Purpose: Starts watching a requested path for one client connection. It records ownership of the watch, rejects duplicate watch IDs for the same connection, and starts a background listener that sends file-change notifications back to that client.

Data flow: It receives a connection ID and watch parameters containing a watch ID and path. It creates a key from the connection and watch ID, subscribes to file watcher events, registers the requested path, and stores a watch entry in the manager state. If that key already exists, it returns a JSON-RPC error saying the watch ID already exists. If registration succeeds, it spawns a task that receives debounced file events, converts changed relative paths into full paths under the watched root, sorts them, and sends an FsChanged notification to the same connection. The function returns a response echoing the watched path.

Call relations: This is called when the server receives a client watch request. It relies on the lower-level FileWatcher for raw filesystem events, wraps those events with DebouncedWatchReceiver to avoid noisy bursts, and hands finished notifications to OutgoingMessageSender so they reach the correct client connection.

Call graph: calls 2 internal fn (invalid_request, new); called by 1 (watch); 7 external calls (FsChanged, format!, channel, pin!, select!, spawn, vec!).

async fn unwatch(
        &self,
        connection_id: ConnectionId,
        params: FsUnwatchParams,
    ) -> Result<FsUnwatchResponse, JSONRPCErrorError>

Purpose: Stops a previously created watch for the requesting connection. It is intentionally scoped by connection, so a client cannot stop another client’s watch just by knowing its watch ID.

Data flow: It receives a connection ID and an unwatch request containing a watch ID. It builds the same ownership key used by watch, removes that entry from the state map if it exists, and asks the background task to terminate. If a task was found, it waits for confirmation that the task has stopped before returning, so no later notification can arrive after the unwatch response. It always returns an empty successful response.

Call relations: This runs when the server receives an unwatch request. It coordinates with the task started by FsWatchManager::watch through a one-time channel, which is a small pipe used to send a single shutdown signal and receive a single done signal.

Call graph: called by 1 (unwatch); 1 external calls (channel).

async fn connection_closed(&self, connection_id: ConnectionId)

Purpose: Cleans up watches owned by a connection that has gone away. This prevents abandoned watch records from staying in memory after a client disconnects.

Data flow: It receives the closed connection’s ID. It locks the watch state and removes every entry whose key belongs to that connection. It does not return data; the state map is left containing only watches owned by other connections.

Call relations: This is called as part of connection cleanup. It complements unwatch: unwatch removes one named watch during normal use, while connection_closed removes all watches for a disconnected client at once.

Call graph: called by 1 (connection_closed).

fn absolute_path(path: PathBuf) -> AbsolutePathBuf

Purpose: Creates an AbsolutePathBuf for tests and fails clearly if the test accidentally provides a relative path. This keeps test setup honest because watch requests require absolute paths.

Data flow: It receives a PathBuf. It checks that the path is absolute, converts it into the project’s absolute-path type, and returns that value. If the path is not absolute or cannot be converted, the test fails immediately.

Call relations: The filesystem-watch tests use this helper whenever they create watch parameters from temporary files. It keeps each test focused on watch behavior instead of repeating path-validation boilerplate.

Call graph: calls 1 internal fn (try_from); 1 external calls (assert!).

fn manager_with_noop_watcher() -> FsWatchManager

Purpose: Builds a FsWatchManager for tests that does not depend on real filesystem watching. This makes tests stable and focused on bookkeeping, ownership, and request behavior.

Data flow: It creates a small outgoing-message channel, creates an OutgoingMessageSender with analytics disabled, creates a no-op FileWatcher, and passes both into FsWatchManager::new_with_file_watcher. It returns the test-ready manager.

Call relations: The test cases call this helper before exercising watch, unwatch, and connection cleanup. By using the internal constructor, it bypasses normal watcher startup and gives tests a controlled environment.

Call graph: calls 4 internal fn (disabled, new_with_file_watcher, new, noop); 2 external calls (new, channel).