Owen Lin

This commit introduces a **new capability** by exposing the legacy `McpStartupUpdateEvent` as a standardized **API v2 notification** named `mcpServer/startupStatus/updated`. This enables clients to receive real-time updates on the startup status of MCP servers, including states like `Starting`, `Ready`, `Failed`, or `Cancelled`. The `app-server-protocol` module gains new JSON and TypeScript schemas for `McpServerStatusUpdatedNotification` and `McpServerStartupState`, while the `app-server` now converts and emits these notifications via `apply_bespoke_event_handling`. Consequently, the `tui_app_server` is updated to handle and display these critical status updates, significantly improving **observability** and **user feedback** during server startup.

This commit **enhances the `app-server` tracing infrastructure** by introducing a `turn.id` tag to relevant spans. It updates the `app_server_request_span_template` and implements the recording of `turn_id` within the **`turn/start`, `turn/steer`, and `turn/interrupt` API handlers**. This **new feature** provides **improved observability**, allowing developers to easily find and filter spans by `turn.id` for better debugging and analysis of user interactions. Helper methods like `record_turn_id` are added to `RequestContext` and `OutgoingMessageSender` to facilitate this tagging, ensuring comprehensive coverage.

This commit introduces a **new capability** to propagate **W3C trace context** over persistent **WebSocket connections** within the `codex-rs` ecosystem, specifically for `response.create` requests. It **fixes** a limitation where tracing was only set at connection time, ensuring that each turn's request now carries its tracing context for holistic end-to-end observability. This is achieved by adding special `ws_request_header_traceparent` and `ws_request_header_tracestate` keys to the `client_metadata` parameter in the **`codex-api`** and modifying the **`core` client's** WebSocket streaming logic. The change significantly improves the ability to trace individual turns in the `codex app-server -> codex-backend -> responsesapi` flow, with new tests validating the propagation.

This commit **fixes a critical hanging issue** in the `app-server`'s **core turn processing** where initial `turn/start` operations could block for extended periods due to websocket prewarm failures. It introduces a **configurable 15-second timeout** (`websocket_connect_timeout_ms`) for websocket startup, ensuring that `turn/started` events are emitted immediately and turns can be interrupted even if the websocket is still connecting. This **enhances client responsiveness** and prevents the server from appearing unresponsive during startup, significantly improving the **user experience** for external clients by providing timely feedback and control over turns. The change involves **refactoring** the `session startup prewarm` mechanism and updating **configuration** and **metrics** within the `codex-rs/core` module.

This commit significantly **expands tracing coverage** across key components, including **`app-server` thread startup**, **`core` session initialization**, and the **`Responses` transport layer** in `codex-api`. It also **refactors `core` dispatch spans** to use stable, operation-specific names, replacing generic `submission_dispatch` entries for clearer trace analysis. Furthermore, this **feature enhancement** introduces `fmt::Display` implementations for various types like `RequestId` and `ConnectionId`, ensuring that trace data is serialized as human-readable strings rather than Rust type representations, greatly improving **observability and debugging** within the system.

This commit provides a **bug fix** and **refactoring** for the **tracing tests** within the `codex-rs/app-server` module, specifically addressing flakiness in the `turn_start_jsonrpc_span_parents_core_turn_spans` test. The test logic is now **refactored** to assert core tracing invariants, ensuring that the `turn/start` span has the correct remote parent and that a representative core turn span descends from it. This change avoids brittle assertions on internal, asynchronously exported spans, making the test more robust and less sensitive to timing or future internal implementation details. The overall impact is improved reliability and maintainability of the **tracing infrastructure**'s test suite.

chore(app-server): stop exporting EventMsg schemas (#14478)

This commit introduces a **new capability** for **end-to-end distributed tracing** within the `app-server` and `core` modules, ensuring that the trace context from an incoming RPC request is propagated across all subsequent asynchronous tasks and core operations. It maintains the request-scoped trace lineage through detached background work, such as `thread/start` operations, and passes it to downstream `core` operations like thread creation, resume/fork flows, and turn submissions. This **enhances observability** by providing a complete view of an RPC's lifecycle, even when work is handed off to background tasks, and includes **refactoring** of request processing and **fixes** for graceful shutdown of background tasks and threads. New tracing tests verify the preservation of W3C trace context and correct span hierarchy.

This commit performs **maintenance** and **refactoring** within the `app-server-protocol` crate by **deleting unused RPC methods and types** from its `v1` module. It removes dead code from `protocol/v1.rs` and replaces a blanket re-export in `lib.rs` with an explicit list of only the v1 types still actively used by downstream consumers, such as the Codex app. This cleanup clarifies the legacy protocol surface, making it easier to identify intentional compatibility paths and paving the way for future, safer removal of remaining legacy components. The change ensures that the crate only exposes necessary v1 types, improving the maintainability and understanding of the API.

This commit **refactors** the **`app-server`** to **stop emitting legacy `codex/event/*` notifications** over **external stdio and websocket transports**. This **maintenance** task cleans up the public API contract, ensuring external clients no longer receive these deprecated notifications. Crucially, **in-process clients** (e.g., `codex exec`) are explicitly *not* affected and will continue to receive these notifications. The change includes **documentation updates** across `app-server-protocol` schemas and `README.md`, along with **test updates** to reflect the new notification expectations for external connections.

This commit **introduces a new CI check** to prevent large binary files from being committed to the repository, enhancing overall repository hygiene. It adds a **GitHub Actions workflow** (`.github/workflows/blob-size-policy.yml`) that leverages a new **Python script** (`scripts/check_blob_size.py`) to enforce a maximum binary size limit of 500KB. This **new capability** helps manage repository size and prevents accidental large file additions by flagging changes in pull requests. An **allowlist** (`.github/blob-size-allowlist.txt`) is also provided for specific, intentional exceptions to this policy, ensuring controlled growth and maintainability.

This commit **fixes a critical reliability issue** with **OTLP HTTP trace export** within the `codex_otel` module, particularly in **app-server** and various **Tokio runtime environments**. It introduces a **runtime-aware HTTP client** and an **async export path** to ensure traces are consistently sent, and implements **force flushing during provider shutdown** to prevent data loss. Additionally, it **removes a deprecated `otel_provider` compatibility shim**, updating all references to the canonical `OtelProvider`, and adds **robust loopback tests** to validate trace export across different runtime configurations. This significantly **improves the robustness of OpenTelemetry tracing** throughout the application.

This commit **refactors** the **web search tool configuration** within the **`codex-core`** module to enhance maintainability and clarity. It introduces **dedicated `Responses-API` payload structs**, `ResponsesApiWebSearchFilters` and `ResponsesApiWebSearchUserLocation`, replacing shared config types and custom serializers. This change establishes a clearer boundary between internal configuration schemas and the external OpenAI Responses API wire format, making serialization behavior explicit via `From` trait implementations. The **`build_specs`** function is updated to utilize these new types, preventing potential drift and future issues in the **web search tool's interaction with the Responses API**. This improves the robustness and understanding of the data flow for web search parameters.

This commit **refactors** the OpenTelemetry (OTEL) integration by **centralizing metric names and shared tag builders** within the **`codex-otel`** crate. It moves duplicated metric names, particularly for turn and thread-related metrics, into a canonical `codex-otel::metrics::names` module and introduces a new `codex-otel::metrics::tags` module for common tag keys and session tag construction. The **`codex-core`** crate is updated to consume these new shared constants and tag helpers, reducing duplication and ensuring consistent metric reporting for features like TTFT/TTFM and various task durations. This change significantly **improves the maintainability and consistency** of the telemetry system, making future instrumentation efforts more streamlined and less prone to drift.

This commit implements a **bug fix** and **refactoring** within the **`app-server-protocol`'s JSON schema exporter** to resolve critical naming conflicts for `WebSearchAction` types. It **renames** the upstream Responses API's `WebSearchAction` to `ResponsesApiWebSearchAction` across the generated **v2 API schemas** and updates all internal references, preventing silent overwrites of schema definitions. Additionally, the `export.rs` module is enhanced to **detect and explicitly fail** on future schema definition collisions, improving the robustness of schema generation. This ensures clients generate correct code, particularly for **web search actions** in extended thread history, by providing accurate and unambiguous schema definitions.

This commit performs a **mechanical refactoring** by **renaming** the `OtelManager` struct to `SessionTelemetry` across the codebase. This change, primarily affecting the **`codex-rs/core`** and **`codex-rs/otel`** crates, along with related `state` and `tui` components, aims to better convey that the struct handles **session-scoped telemetry** rather than global OpenTelemetry management. It involves updating all references in imports, struct fields, function parameters, and call sites, significantly improving the **clarity and maintainability** of the telemetry boundary. There is **no change in behavior** or functionality as a result of this rename.

This commit performs a **significant internal refactoring** of the **`codex-otel` crate** to improve its modularity and clarify ownership boundaries. It **reorganizes core OpenTelemetry components**, moving the `OtelProvider` implementation to `src/provider.rs` and centralizing `OtelManager` and session-scoped event emission into `src/events/otel_manager.rs`. This **structural cleanup** separates concerns like provider setup, event emission, and trace context handling, making the codebase easier to understand and maintain for future development. While there is **no intended behavior change**, a compatibility shim in `src/otel_provider.rs` helps minimize immediate downstream churn for existing imports.

This commit introduces **new turn-level latency metrics** within the **`codex-core`** module to enhance performance observability. It adds tracking for **Time To First Token (TTFT)**, which measures the duration until the first model output signal, and **Time To First Message (TTFM)**, which measures the duration until the first agent message finishes streaming. These **new capabilities** are consistently recorded across all clients (CLI, TUI, app-server) via the new `turn_timing` module. The metrics, named `codex.turn.ttft.duration_ms` and `codex.turn.ttfm.duration_ms`, are integrated into the **OpenTelemetry (OTEL)** runtime metrics summary, providing critical insights into agent responsiveness for performance analysis and optimization.

This commit **fixes a flaky test** `turn_start_shell_zsh_fork_executes_command_v2` within the **`app-server`** module. The flakiness was caused by a race condition where an interrupt path could send an additional "no-op" response, leading to unexpected test failures. To resolve this, the test's mock server setup in `codex-rs/app-server/tests/suite/v2/turn_start_zsh_fork.rs` has been modified to **allow for this extra no-op response**, accommodating the race condition. This **maintenance fix** improves the reliability of the **`app-server`** test suite by ensuring the test accurately verifies the correct execution of zsh-forked commands.

This commit introduces **safe OpenTelemetry tracing** by fundamentally separating the routing and filtering policies for log and trace exporters within the **telemetry subsystem**. It **refactors the `otel_provider`** (`otel_provider.rs`) to ensure sensitive data, such as raw user prompts or tool arguments, is **redacted from exported traces** while remaining available in content-rich logs for security and IT purposes. The **`otel_manager`** (`otel_manager.rs`) now uses distinct event emission patterns and new macros to direct detailed information to logs and summarized, performance-relevant data to traces. This **security enhancement** prevents accidental data leakage, making trace export safe to enable for performance analysis without compromising data privacy.