feat(tui): migrate cli surfaces to in-process app-server

[fcoury]

Problem

TUI and exec both embed app-server logic but did so through ad-hoc wiring: each surface duplicated initialize handshake logic, session-source selection, event dispatch, server-request resolution, and shutdown sequencing. This made it easy for in-process behavior to drift from app-server semantics and across surfaces.

Mental model

There are now three layers between a CLI surface and MessageProcessor:

1. codex_app_server::in_process — low-level runtime host. Owns the MessageProcessor, outbound routing task, and bounded typed channels. Performs the initialize/initialized handshake before returning an InProcessClientHandle. Speaks the same JSON-RPC result envelope as stdio/websocket transports.

2. codex-app-server-client — shared facade crate. Wraps the low-level handle behind a worker task with async mpsc channels, adds surface identity (ClientSurface → SessionSource), typed request helpers, backpressure-aware event forwarding, and bounded shutdown with abort fallback.

3. Surface (TUI / exec) — consumes events from the facade and maps them into surface-specific state. No longer performs initialize, session-source selection, or shutdown directly.

graph LR
    subgraph "AFTER: App-server protocol"
        direction TB
        A_SURFACE["Surface<br/>(TUI / Exec)"]
        A_FACADE["InProcessAppServerClient<br/>(bounded channels + worker)"]
        A_RUNTIME["InProcessClientHandle<br/>(runtime task)"]
        A_MP["MessageProcessor<br/>(JSON-RPC)"]

        A_SURFACE <-->|"ClientRequest / InProcessServerEvent<br/>(typed app-server protocol)"| A_FACADE
        A_FACADE <-->|"InProcessClientMessage<br/>(bounded + try_send)"| A_RUNTIME
        A_RUNTIME <-->|"process_client_request()<br/>OutgoingMessage"| A_MP
    end

    subgraph "BEFORE: Direct coupling"
        direction TB
        B_SURFACE["Surface<br/>(TUI / Exec)"]
        B_THREAD["Arc&lt;CodexThread&gt;<br/>.submit(Op) / .next_event()"]
        B_CODEX["Codex<br/>(internal channels)"]
        B_AGENT["Agent Loop"]

        B_SURFACE <-->|"Op / Event<br/>(no protocol boundary)"| B_THREAD
        B_THREAD <--> B_CODEX
        B_CODEX <--> B_AGENT
    end

    style B_THREAD fill:#c94040,color:#fff
    style B_CODEX fill:#c94040,color:#fff
    style A_FACADE fill:#1565c0,color:#fff
    style A_RUNTIME fill:#7b1fa2,color:#fff
    style A_MP fill:#2e7d32,color:#fff

Loading

Non-goals

• No new app-server protocol methods; all existing JSON-RPC methods and events are unchanged.
• No changes to socket/stdio transport behavior; the in-process path is additive.
• The legacy codex_protocol::Event bridge is preserved (surfaces still consume it today); removing it is a separate follow-up.

Migration boundaries

The following actions and notifications were intentionally not migrated to the app-server RPC/notification surface. They remain local to the TUI/exec surface or flow through the legacy codex_protocol::Event bridge.

Actions kept local in TUI

Handled locally (no app-server RPC needed):

• AddToHistory, GetHistoryEntryRequest, ListCustomPrompts, ReloadUserConfig

Deferred (emit local warnings today):

• Undo, OverrideTurnContext, DropMemories, UpdateMemories, RunUserShellCommand, ListMcpTools

Shutdown is intentionally not a dedicated RPC — it maps to thread/unsubscribe plus local completion handling.

Notifications staying on the legacy event bridge

These notifications are not added to the app-server typed path:

• warning, backgroundEvent, turn/streamError
• thread/undo/started, thread/undo/completed, thread/shutdown/completed
• mcpServer/startup/updated, mcpServer/startup/completed
• skills/updated

In TUI, only two server notifications use the typed app-server path today:

• ServerNotification::ItemStarted (file-change caching)
• ServerNotification::ServerRequestResolved (MCP elicitation cleanup)

Everything else in TUI flows through the legacy LegacyNotification → EventMsg bridge, including realtime event consumption (realtime requests were migrated, but event consumption was not). exec also consumes ServerNotification::Error directly on the typed path for fatal-error tracking.

Other non-migrated pieces

• account/chatgptAuthTokens/refresh remains a local server-request adapter in both TUI and exec rather than a deeper app-server-owned flow.

Tradeoffs

• JSON-RPC result envelope preserved on the in-process path. Typed requests still receive serde_json::Value results rather than directly typed structs, because MessageProcessor produces that shape internally. This trades some deserialization cost for behavioral parity with socket transports, reducing the risk of subtle execution differences.

• Bounded channels with overload rejection. Full queues reject server requests with -32001 (overloaded) instead of blocking or growing unbounded. This means a slow consumer can cause approval flows to be rejected rather than queued, which is intentional: hanging approvals are worse than explicit rejection.

• ClientSurface::Tui maps to SessionSource::Cli. The TUI is the interactive CLI from the server's perspective, so this mapping is correct even though the names look asymmetric.

Architecture

New crates / modules:

• codex-rs/app-server-client/ — the facade crate
• codex-rs/app-server/src/in_process.rs — low-level runtime host
• codex-rs/app-server/src/app_server_tracing.rs — tracing helpers shared across transports

Modified:

• codex-rs/app-server/src/message_processor.rs — extracted handle_client_request + process_client_notification so both JSON-RPC and typed paths share the same request handler. session_source is now passed through MessageProcessorArgs instead of being hardcoded.
• codex-rs/exec/src/lib.rs — migrated to use InProcessAppServerClient facade.
• codex-rs/tui/src/chatwidget/agent.rs — migrated to use InProcessAppServerClient facade.

Observability

• In-process requests emit app_server.request spans with rpc.transport = "in-process", making them distinguishable from stdio/websocket spans in traces.
• Queue saturation warnings are logged via tracing::warn when events are dropped or server requests are rejected due to backpressure.

Tests

• codex-app-server-client has integration tests for typed request roundtrips, JSON-RPC error propagation, surface-to-session-source mapping, minimum channel capacity, error source chaining, and lagged-event markers.
• codex_app_server::in_process has integration tests for initialize handshake, session source propagation, and zero-capacity clamping.

[Copilot]

Pull request overview

This PR migrates CLI surfaces (codex-tui and codex-exec) to run against an in-process app-server instead of talking to the core runtime directly. It introduces a new codex-app-server-client crate as the shared facade, adds a new AgentCommand abstraction in the TUI layer, and expands the v2 protocol surface with new request/response/notification types.

Changes:

• Introduces codex-app-server-client as a new crate that wraps the in-process app-server with worker-task lifecycle management, backpressure, and shutdown handling.
• Adds AgentCommand enum in the TUI to decouple UI events from raw Op construction, replacing direct AppEvent::CodexOp/AppEvent::SubmitThreadOp usage.
• Expands the v2 app-server protocol with new API types (MCP elicitation, undo, shutdown, memory, history, shell command, etc.) and their JSON/TypeScript schema artifacts.

Reviewed changes

Copilot reviewed 118 out of 119 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
codex-rs/app-server-client/src/lib.rs	New crate: in-process app-server client facade with worker task, backpressure, and typed request helpers
codex-rs/app-server-client/Cargo.toml	Cargo manifest for the new client crate
codex-rs/app-server-client/README.md	Documentation for the new client crate
codex-rs/tui/src/agent_command.rs	New AgentCommand enum bridging TUI events and protocol Op values
codex-rs/tui/src/app_event.rs	Adds AgentCommand, SubmitThreadAgentCommand, and ThreadCreated event variants
codex-rs/tui/src/app_event_sender.rs	Excludes AgentCommand events from session log double-logging
codex-rs/tui/src/chatwidget.rs	Removes ThreadManager dependency, exposes new agent lifecycle helpers
codex-rs/tui/src/chatwidget/tests.rs	Updates tests to use new models_manager construction and AgentCommand event patterns
codex-rs/tui/src/bottom_pane/mod.rs	Updates test assertions to use new AgentCommand::Interrupt variant
codex-rs/tui/src/bottom_pane/approval_overlay.rs	Switches approval sends to SubmitThreadAgentCommand with AgentCommand variants
codex-rs/tui/src/status_indicator_widget.rs	Uses AgentCommand::Interrupt instead of Op::Interrupt
codex-rs/tui/src/lib.rs	Registers new agent_command module
codex-rs/tui/Cargo.toml	Adds codex-app-server-client dependency
codex-rs/exec/Cargo.toml	Adds codex-app-server-client and codex-app-server-protocol dependencies
codex-rs/app-server/src/lib.rs	Exposes in_process module, passes SessionSource::VSCode for network transport
codex-rs/app-server/src/message_processor.rs	Adds session_source field, introduces process_client_request for typed in-process path, refactors handle_client_request
codex-rs/app-server/src/transport.rs	Replaces OutgoingNotification with typed CoreEvent, updates serialization and tests
codex-rs/app-server/src/outgoing_message.rs	Replaces OutgoingNotification with CoreEvent variant, adds legacy_event_method
codex-rs/app-server/src/bespoke_event_handling.rs	Adds V2 notification handling for new event types
codex-rs/app-server/src/thread_state.rs	Adds module-level documentation
codex-rs/app-server/src/app_server_tracing.rs	Adds typed_request_span for in-process requests
codex-rs/core/src/lib.rs	Adds lookup_global_history_entry public function
codex-rs/app-server/README.md	Documents in-process transport and new v2 API methods
codex-rs/app-server-protocol/src/protocol/v2.rs	Adds new protocol types for MCP elicitation, undo, shutdown, memory, history, shell commands, etc.
Schema files (JSON/TypeScript)	Generated artifacts for new v2 protocol types
codex-rs/Cargo.toml	Adds app-server-client to workspace and registry
codex-rs/README.md	Documents new crate structure

Comments suppressed due to low confidence (2)

codex-rs/app-server-protocol/schema/typescript/v2/ThreadTurnContextSetParams.ts:1

• The generated TypeScript types for serviceTier and effort contain a doubled | null | null. This is generated from the Option<Option<T>> Rust types with double-option serde helpers, but the resulting TypeScript type is incorrect — ServiceTier | null | null and ReasoningEffort | null | null are redundant. This should be ServiceTier | null and ReasoningEffort | null respectively. The source Rust struct in v2.rs uses Option<Option<ServiceTier>> and Option<Option<ReasoningEffort>>, so the ts-rs codegen output needs adjustment (e.g. via a #[ts(type = "ServiceTier | null")] override) to avoid confusing API consumers.
  codex-rs/app-server/src/app_server_tracing.rs:1
• The else block contains a nested if chain that could be flattened using if let Some(...) = ... { ... } directly inside the else, which is idiomatic Rust. More importantly, the outer else branch with two separate if let blocks is the idiomatic pattern and is fine, but the inner blocks could use else if to be consistent with the surrounding style. This is a minor style point, but the else { if ... { } if ... { } } pattern (rather than two top-level if lets) is slightly non-idiomatic when each branch is independent.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[fcoury]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ab1c02fd73

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".