Support attaching to existing realtime calls (#39876)

## Why

Clients that create and negotiate realtime calls themselves need Codex to join
those calls without creating another call or overwriting the client-owned
session configuration.

## What changed

- Add the `existingCall` transport to `thread/realtime/start`, accepting a
  client-provided `callId` and optional `realtimeSessionId`.
- Attach Codex over the call's sideband WebSocket without SDP negotiation or a
  session update, and reconnect that sideband while preserving transcript
  state.
- Default existing calls to realtime v1, support v1 and v3, and reject v2 or
  options that would reconfigure the client-owned session.
- Encode call IDs as a single URL path segment for v3 sideband connections.

## Testing

Add protocol, app-server, core, reconnection, authentication-header, and URL
encoding coverage for existing-call attachments.

GitOrigin-RevId: 2046b70566f98efa55381bb1e461ea3cc68256c5

codex-rs/codex-api/src/endpoint/realtime_websocket/methods.rs

@@ -767,6 +767,13 @@ pub struct RealtimeWebsocketClient {
     webrtc_sideband_base_url: String,
 }
 
+#[derive(Clone, Copy)]
+enum RealtimeSessionInitialization {
+    NewSession,
+    LegacyWebrtcSideband,
+    ExistingCall,
+}
+
 impl RealtimeWebsocketClient {
     pub fn new(provider: Provider) -> Self {
         Self {
@@ -799,7 +806,7 @@ impl RealtimeWebsocketClient {
             config,
             extra_headers,
             default_headers,
-            /*initialize_session*/ true,
+            RealtimeSessionInitialization::NewSession,
             RealtimeTranscriptState::default(),
         )
         .await
@@ -812,6 +819,46 @@ impl RealtimeWebsocketClient {
         extra_headers: HeaderMap,
         default_headers: HeaderMap,
         transcript_state: RealtimeTranscriptState,
+    ) -> Result<RealtimeWebsocketConnection, ApiError> {
+        self.connect_sideband(
+            config,
+            call_id,
+            extra_headers,
+            default_headers,
+            RealtimeSessionInitialization::LegacyWebrtcSideband,
+            transcript_state,
+        )
+        .await
+    }
+
+    /// Attaches to a client-created call without overwriting its session configuration.
+    pub async fn connect_existing_call_sideband(
+        &self,
+        config: RealtimeSessionConfig,
+        call_id: &str,
+        extra_headers: HeaderMap,
+        default_headers: HeaderMap,
+        transcript_state: RealtimeTranscriptState,
+    ) -> Result<RealtimeWebsocketConnection, ApiError> {
+        self.connect_sideband(
+            config,
+            call_id,
+            extra_headers,
+            default_headers,
+            RealtimeSessionInitialization::ExistingCall,
+            transcript_state,
+        )
+        .await
+    }
+
+    async fn connect_sideband(
+        &self,
+        config: RealtimeSessionConfig,
+        call_id: &str,
+        extra_headers: HeaderMap,
+        default_headers: HeaderMap,
+        session_initialization: RealtimeSessionInitialization,
+        transcript_state: RealtimeTranscriptState,
     ) -> Result<RealtimeWebsocketConnection, ApiError> {
         // The WebRTC call already exists; this loop only retries joining its sideband control
         // socket. Once joined, the returned connection is the same reader/writer state that the
@@ -823,6 +870,7 @@ impl RealtimeWebsocketClient {
                     call_id,
                     extra_headers.clone(),
                     default_headers.clone(),
+                    session_initialization,
                     transcript_state.clone(),
                 )
                 .await;
@@ -854,6 +902,7 @@ impl RealtimeWebsocketClient {
         call_id: &str,
         extra_headers: HeaderMap,
         default_headers: HeaderMap,
+        session_initialization: RealtimeSessionInitialization,
         transcript_state: RealtimeTranscriptState,
     ) -> Result<RealtimeWebsocketConnection, ApiError> {
         // Keep the parser/session query shaping from standalone realtime while replacing the model
@@ -864,7 +913,7 @@ impl RealtimeWebsocketClient {
             config,
             extra_headers,
             default_headers,
-            /*initialize_session*/ false,
+            session_initialization,
             transcript_state,
         )
         .await
@@ -891,7 +940,7 @@ impl RealtimeWebsocketClient {
         config: RealtimeSessionConfig,
         extra_headers: HeaderMap,
         default_headers: HeaderMap,
-        initialize_session: bool,
+        session_initialization: RealtimeSessionInitialization,
         transcript_state: RealtimeTranscriptState,
     ) -> Result<RealtimeWebsocketConnection, ApiError> {
         ensure_rustls_crypto_provider();
@@ -934,7 +983,14 @@ impl RealtimeWebsocketClient {
             config.event_parser,
             transcript_state,
         );
-        if initialize_session || config.event_parser != RealtimeEventParser::FramelessBidi {
+        let initialize_session = match session_initialization {
+            RealtimeSessionInitialization::NewSession => true,
+            RealtimeSessionInitialization::LegacyWebrtcSideband => {
+                config.event_parser != RealtimeEventParser::FramelessBidi
+            }
+            RealtimeSessionInitialization::ExistingCall => false,
+        };
+        if initialize_session {
             debug!(
                 session_id = config.session_id.as_deref().unwrap_or("<none>"),
                 "realtime websocket sending session.update"
@@ -951,7 +1007,11 @@ impl RealtimeWebsocketClient {
                 )
                 .await?;
         }
-        if initialize_session && config.event_parser == RealtimeEventParser::FramelessBidi {
+        if matches!(
+            session_initialization,
+            RealtimeSessionInitialization::NewSession
+        ) && config.event_parser == RealtimeEventParser::FramelessBidi
+        {
             connection.events.wait_for_session_started().await?;
         }
         Ok(connection)
@@ -1079,8 +1139,19 @@ fn websocket_url_from_api_url_for_call(
     )?;
     match event_parser {
         RealtimeEventParser::FramelessBidi => {
-            let path = format!("{}/{}", url.path().trim_end_matches('/'), call_id);
-            url.set_path(&path);
+            if matches!(call_id, "." | "..") {
+                return Err(ApiError::InvalidRequest {
+                    message: format!("invalid realtime call id: {call_id}"),
+                });
+            }
+            url.path_segments_mut()
+                .map_err(|()| {
+                    ApiError::Stream(
+                        "realtime sideband URL cannot contain path segments".to_string(),
+                    )
+                })?
+                .pop_if_empty()
+                .push(call_id);
         }
         RealtimeEventParser::V1 | RealtimeEventParser::RealtimeV2 => {
             url.query_pairs_mut().append_pair("call_id", call_id);
@@ -2051,6 +2122,43 @@ mod tests {
         );
     }
 
+    #[test]
+    fn frameless_websocket_url_encodes_call_id_as_one_path_segment() {
+        let url = websocket_url_from_api_url_for_call(
+            "https://example.com/proxy/v1/live?trace=1",
+            /*query_params*/ None,
+            RealtimeEventParser::FramelessBidi,
+            RealtimeSessionMode::Conversational,
+            "../../admin",
+        )
+        .expect("build existing-call websocket url");
+
+        assert_eq!(
+            url.as_str(),
+            "wss://example.com/proxy/v1/live/..%2F..%2Fadmin?trace=1"
+        );
+    }
+
+    #[test]
+    fn frameless_websocket_url_rejects_dot_only_call_ids() {
+        for call_id in [".", ".."] {
+            let error = websocket_url_from_api_url_for_call(
+                "https://example.com/v1/live",
+                /*query_params*/ None,
+                RealtimeEventParser::FramelessBidi,
+                RealtimeSessionMode::Conversational,
+                call_id,
+            )
+            .expect_err("dot-only call IDs must not target the parent sideband URL");
+
+            assert!(matches!(
+                error,
+                ApiError::InvalidRequest { message }
+                    if message == format!("invalid realtime call id: {call_id}")
+            ));
+        }
+    }
+
     #[test]
     fn webrtc_frameless_sideband_ignores_provider_base_url() {
         let client = RealtimeWebsocketClient::new(Provider {