Skip to main content

cpa_exec/
xai_ws.rs

1//! xAI upstream Responses WebSocket (xai_websockets_executor.go): the transport a
2//! downstream Responses WebSocket turn uses when its credential sets `websockets`
3//! (`XAIAutoExecutor`).
4//!
5//! Sockets live in the Codex executor's pool type ([`codex_ws::Pool`]), as Go shares
6//! `codexWebsocketSession` between both executors; xAI keeps its own pool instance. On top
7//! of that, every session has an [`IdState`] (`xaiWebsocketIDState`): xAI reuses response
8//! IDs and loses upstream state when the socket's target changes, so downstream response
9//! IDs are rewritten to stay unique, the conversation transcript is kept to replay it on a
10//! fresh target, and a `compaction_trigger` turn compacts that transcript over HTTP.
11// ponytail: Go's branch for a WebSocket turn without a downstream WebSocket (SSE encoding
12// and client translation) is unreachable through `XAIAutoExecutor` and not ported, nor
13// are the sessionless ephemeral sockets or `CloseXAIWebsocketSessionsForAuthID`.
14
15use std::collections::{HashMap, VecDeque};
16use std::sync::{Arc, Mutex};
17use std::time::{Duration, SystemTime};
18
19use bytes::Bytes;
20use cpa_common::json::{self as gj, GoValue, Kind};
21use cpa_core::config::Config;
22use cpa_core::credential::Credential;
23use cpa_core::exec::{
24    CaptureEvent, CaptureSink, ExecError, ExecRequest, ExecResponse, ExecSession, FailureScope, ResponseBody,
25    UpstreamRequest,
26};
27use cpa_core::format::Format;
28use futures_util::StreamExt;
29use http::{HeaderMap, HeaderName, HeaderValue};
30use tokio::sync::{OwnedMutexGuard, mpsc};
31
32use crate::codex_ws::{self, Pool, Read, Session, Target, Upstream};
33use crate::openai_compat::status_err;
34use crate::openai_compat_payload::ensure_responses_usage_details;
35use crate::xai::{XaiExecutor, apply_patch_error, compaction_frames, compaction_item, compaction_response_id, creds};
36use crate::xai_auth::DEFAULT_API_BASE_URL;
37use crate::xai_replay::{self as replay, ReplayScope};
38use crate::xai_request as request;
39use crate::xai_response::{self as response, NamespaceRestorer, OutputItems, XSearchFilter, text};
40use cpa_translate::apply_patch_responses as apply_patch;
41
42/// The terminal events whose usage Go's WebSocket turn observes (completed and done).
43const WS_USAGE_EVENTS: [&str; 2] = ["response.completed", "response.done"];
44
45/// `codexResponsesWebsocketHandshakeTO`.
46const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(30);
47/// Bound on a handshake rejection body.
48const MAX_HANDSHAKE_BODY: usize = 64 * 1024;
49/// `buildXAIWebsocketWarmupCompletedPayload`'s empty usage.
50const EMPTY_USAGE: &str = r#"{"input_tokens":0,"input_tokens_details":{"cached_tokens":0},"output_tokens":0,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":0}"#;
51
52/// Go reads xAI sockets without a deadline (only the Codex reader sets one); the shared
53/// reader's deadline is set past any session.
54const NO_READ_DEADLINE: Duration = Duration::from_secs(10 * 365 * 24 * 3600);
55
56/// The executor's sockets and per-session ID state (`globalXAIWebsocketSessionStore`,
57/// `globalXAIWebsocketIDStates`).
58pub(crate) struct Ws {
59    pool: Pool,
60    states: Mutex<HashMap<String, Arc<IdState>>>,
61    /// Test hook: the next turn signals once it holds its session and waits before it
62    /// takes the ID state.
63    #[cfg(test)]
64    pause: Mutex<Option<(tokio::sync::oneshot::Sender<()>, tokio::sync::oneshot::Receiver<()>)>>,
65}
66
67impl Default for Ws {
68    fn default() -> Self {
69        let mut pool = Pool::default();
70        pool.idle = NO_READ_DEADLINE;
71        Self {
72            pool,
73            states: Mutex::default(),
74            #[cfg(test)]
75            pause: Mutex::default(),
76        }
77    }
78}
79
80impl Ws {
81    /// `getXAIWebsocketIDState`.
82    fn state(&self, id: &str) -> Option<Arc<IdState>> {
83        let id = id.trim();
84        if id.is_empty() {
85            return None;
86        }
87        let mut states = self.states.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
88        Some(states.entry(id.to_owned()).or_default().clone())
89    }
90
91    /// `CloseExecutionSession`: the downstream connection ended.
92    pub(crate) fn close(&self, id: &str) {
93        let id = id.trim();
94        self.pool.close(id);
95        self.states
96            .lock()
97            .unwrap_or_else(std::sync::PoisonError::into_inner)
98            .remove(id);
99    }
100
101    /// `closeXAIWebsocketSessionsInStoreForAuthID`: ends a removed credential's sessions
102    /// and drops their ID state.
103    pub(crate) fn close_credential(&self, credential: &str) {
104        self.pool.close_credential_with(credential, |id| {
105            self.states
106                .lock()
107                .unwrap_or_else(std::sync::PoisonError::into_inner)
108                .remove(id);
109        });
110    }
111
112    #[cfg(test)]
113    async fn paused(&self) {
114        let pause = self
115            .pause
116            .lock()
117            .unwrap_or_else(std::sync::PoisonError::into_inner)
118            .take();
119        if let Some((reached, resume)) = pause {
120            let _ = reached.send(());
121            let _ = resume.await;
122        }
123    }
124
125    /// `UpstreamDisconnectChan`.
126    pub(crate) fn closed(&self, id: &str) -> impl std::future::Future<Output = ExecError> + Send + 'static {
127        self.pool.closed(id.trim())
128    }
129}
130
131// --- per-session ID state (xaiWebsocketIDState) --------------------------------------------
132
133#[derive(Default)]
134struct IdState(Mutex<IdInner>);
135
136#[derive(Default)]
137struct IdInner {
138    downstream_to_upstream: HashMap<String, String>,
139    sequence: u64,
140    transcript: Vec<Vec<u8>>,
141    replay_compacted_on_reset: bool,
142    /// The target of the session's last socket (Go keeps `sess.authID`, `wsURL` and
143    /// `proxyURL` after the socket is gone).
144    last_target: Option<Target>,
145}
146
147impl IdState {
148    fn lock(&self) -> std::sync::MutexGuard<'_, IdInner> {
149        self.0.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
150    }
151
152    /// `upstreamIDForDownstream`.
153    fn upstream_id(&self, downstream: &str) -> String {
154        let downstream = downstream.trim();
155        if downstream.is_empty() {
156            return String::new();
157        }
158        match self.lock().downstream_to_upstream.get(downstream) {
159            Some(upstream) => upstream.trim().to_owned(),
160            None => downstream.to_owned(),
161        }
162    }
163
164    /// `mapDownstreamToUpstream`.
165    fn map(&self, downstream: &str, upstream: &str) {
166        let downstream = downstream.trim();
167        if downstream.is_empty() {
168            return;
169        }
170        self.lock()
171            .downstream_to_upstream
172            .insert(downstream.to_owned(), upstream.trim().to_owned());
173    }
174
175    /// `snapshotTranscriptInput`.
176    fn snapshot(&self) -> Option<Vec<u8>> {
177        let inner = self.lock();
178        (!inner.transcript.is_empty()).then(|| raw_array(&inner.transcript))
179    }
180
181    /// The transcript prepended to `payload`'s input.
182    fn prepend(&self, payload: Vec<u8>, only_compacted: bool) -> (Vec<u8>, bool) {
183        let prefix = {
184            let inner = self.lock();
185            if only_compacted && !inner.replay_compacted_on_reset {
186                return (payload, false);
187            }
188            inner.transcript.clone()
189        };
190        if prefix.is_empty() {
191            return (payload, false);
192        }
193        let mut merged = prefix;
194        merged.extend(raw_items(&gj::get(&payload, "input")));
195        let mut out = payload;
196        gj::set_raw(&mut out, "input", raw_array(&merged));
197        (out, true)
198    }
199
200    /// `recordTranscriptTurn`.
201    fn record(&self, request: &[u8], completed: &[u8], reset: bool) {
202        if request.is_empty() || completed.is_empty() {
203            return;
204        }
205        let input = raw_items(&gj::get(request, "input"));
206        let output = raw_items(&gj::get(completed, "response.output"));
207        let mut inner = self.lock();
208        if reset {
209            inner.transcript.clear();
210            inner.replay_compacted_on_reset = false;
211        }
212        inner.transcript.extend(input);
213        inner.transcript.extend(output);
214    }
215
216    /// `replaceTranscriptWithItems`.
217    fn replace(&self, items: &[&[u8]]) {
218        let next: Vec<Vec<u8>> = items
219            .iter()
220            .map(|item| cpa_common::gostr::trim_space(item))
221            .filter(|item| !item.is_empty() && gj::std_valid(item))
222            .map(<[u8]>::to_vec)
223            .collect();
224        let mut inner = self.lock();
225        inner.replay_compacted_on_reset = !next.is_empty();
226        inner.transcript = next;
227    }
228
229    /// `websocketSessionTargetChanged`; `live` when the session's socket for the same
230    /// credential is still open, which keeps its dial-time global proxy (`effectiveConfig`).
231    fn target_changed(&self, target: &Target, live: bool) -> bool {
232        self.lock()
233            .last_target
234            .as_ref()
235            .is_some_and(|last| !if live { last.serves(target) } else { last.same(target) })
236    }
237
238    fn set_target(&self, target: &Target) {
239        self.lock().last_target = Some(target.clone());
240    }
241}
242
243/// `xaiJSONRawMessages`: the valid elements of an array, trimmed.
244fn raw_items(value: &gj::Res<'_>) -> Vec<Vec<u8>> {
245    if !value.exists() || !value.is_array() {
246        return Vec::new();
247    }
248    value
249        .array()
250        .iter()
251        .map(|item| cpa_common::gostr::trim_space(item.raw()).to_vec())
252        .filter(|raw| !raw.is_empty() && gj::std_valid(raw))
253        .collect()
254}
255
256/// `xaiMarshalRawMessages`.
257fn raw_array(items: &[Vec<u8>]) -> Vec<u8> {
258    let mut out = vec![b'['];
259    for (i, item) in items.iter().enumerate() {
260        if i > 0 {
261            out.push(b',');
262        }
263        out.extend_from_slice(cpa_common::gostr::trim_space(item));
264    }
265    out.push(b']');
266    out
267}
268
269/// `xaiWebsocketRequestIDMapper`: one turn's view of the session's ID mapping.
270struct IdMapper {
271    state: Arc<IdState>,
272    downstream_previous: String,
273    upstream_previous: String,
274    upstream_response: String,
275    downstream_response: String,
276    replayed_compacted: bool,
277}
278
279impl IdMapper {
280    /// `newXAIWebsocketRequestIDMapper`.
281    fn new(state: Arc<IdState>, downstream_request: &[u8]) -> Self {
282        let downstream_previous = text(&gj::get(downstream_request, "previous_response_id"))
283            .trim()
284            .to_owned();
285        let upstream_previous = if downstream_previous.is_empty() {
286            String::new()
287        } else {
288            state.upstream_id(&downstream_previous)
289        };
290        Self {
291            state,
292            downstream_previous,
293            upstream_previous,
294            upstream_response: String::new(),
295            downstream_response: String::new(),
296            replayed_compacted: false,
297        }
298    }
299
300    /// `upstreamRequestPayload`.
301    fn upstream_request(&mut self, payload: Vec<u8>) -> Vec<u8> {
302        if payload.is_empty() {
303            return payload;
304        }
305        if self.downstream_previous == self.upstream_previous {
306            let request_type = text(&gj::get(&payload, "type"));
307            if self.downstream_previous.is_empty() && request_type.trim() == "response.append" {
308                let (out, replayed) = self.state.prepend(payload, true);
309                self.replayed_compacted = replayed;
310                return out;
311            }
312            return payload;
313        }
314        let mut out = payload;
315        if self.upstream_previous.is_empty() {
316            gj::delete(&mut out, "previous_response_id");
317            if !self.downstream_previous.is_empty() {
318                out = self.state.prepend(out, false).0;
319                self.replayed_compacted = true;
320            }
321            return out;
322        }
323        gj::set_str(&mut out, "previous_response_id", &self.upstream_previous);
324        out
325    }
326
327    /// `downstreamResponsePayload`.
328    fn downstream_response(&mut self, payload: Vec<u8>) -> Vec<u8> {
329        if payload.is_empty() {
330            return payload;
331        }
332        let upstream = text(&gj::get(&payload, "response.id")).trim().to_owned();
333        let downstream = self.downstream_id(&upstream);
334        if downstream.is_empty() {
335            return payload;
336        }
337        rewrite_ids(
338            payload,
339            &self.upstream_response,
340            &downstream,
341            &self.upstream_previous,
342            &self.downstream_previous,
343        )
344    }
345
346    /// `downstreamIDForUpstreamResponse`: a response ID xAI repeats gets a `-xai-N` suffix
347    /// downstream.
348    fn downstream_id(&mut self, upstream: &str) -> String {
349        if !self.upstream_response.is_empty() {
350            return self.downstream_response.clone();
351        }
352        if upstream.is_empty() {
353            return String::new();
354        }
355        let mut inner = self.state.lock();
356        self.upstream_response = upstream.to_owned();
357        self.downstream_response = upstream.to_owned();
358        let seen = inner.downstream_to_upstream.contains_key(upstream);
359        if (!self.downstream_previous.is_empty()
360            && !self.upstream_previous.is_empty()
361            && upstream == self.upstream_previous)
362            || seen
363        {
364            inner.sequence += 1;
365            self.downstream_response = format!("{upstream}-xai-{}", inner.sequence);
366        }
367        inner
368            .downstream_to_upstream
369            .insert(upstream.to_owned(), upstream.to_owned());
370        inner
371            .downstream_to_upstream
372            .insert(self.downstream_response.clone(), upstream.to_owned());
373        self.downstream_response.clone()
374    }
375}
376
377/// `rewriteXAIWebsocketDownstreamIDs`: `id`/`item_id` strings containing the upstream
378/// response ID and an exact `previous_response_id`, re-marshalled like Go's
379/// `map[string]any` (sorted keys) when anything changed.
380fn rewrite_ids(
381    payload: Vec<u8>,
382    upstream: &str,
383    downstream: &str,
384    upstream_previous: &str,
385    downstream_previous: &str,
386) -> Vec<u8> {
387    let (upstream, downstream) = (upstream.trim(), downstream.trim());
388    let (upstream_previous, downstream_previous) = (upstream_previous.trim(), downstream_previous.trim());
389    if upstream == downstream && upstream_previous == downstream_previous {
390        return payload;
391    }
392    let Some(mut value) = GoValue::parse(&payload) else {
393        return payload;
394    };
395    let ids = Ids {
396        upstream,
397        downstream,
398        upstream_previous,
399        downstream_previous,
400    };
401    if !ids.rewrite(&mut value) {
402        return payload;
403    }
404    value.marshal()
405}
406
407struct Ids<'a> {
408    upstream: &'a str,
409    downstream: &'a str,
410    upstream_previous: &'a str,
411    downstream_previous: &'a str,
412}
413
414impl Ids<'_> {
415    fn rewrite(&self, value: &mut GoValue) -> bool {
416        match value {
417            GoValue::Object(map) => {
418                let mut changed = false;
419                for (key, child) in map.iter_mut() {
420                    if let GoValue::String(s) = child {
421                        if let Some(replaced) = self.string(key, s) {
422                            *s = replaced;
423                            changed = true;
424                        }
425                        continue;
426                    }
427                    changed |= self.rewrite(child);
428                }
429                changed
430            }
431            GoValue::Array(items) => {
432                let mut changed = false;
433                for item in items {
434                    changed |= self.rewrite(item);
435                }
436                changed
437            }
438            _ => false,
439        }
440    }
441
442    /// `rewriteXAIWebsocketDownstreamIDString`; `None` when unchanged.
443    fn string(&self, key: &str, value: &str) -> Option<String> {
444        match key {
445            "id" | "item_id"
446                if !self.upstream.is_empty()
447                    && !self.downstream.is_empty()
448                    && self.downstream != self.upstream
449                    && value.contains(self.upstream) =>
450            {
451                Some(value.replace(self.upstream, self.downstream)).filter(|r| r != value)
452            }
453            "previous_response_id"
454                if !self.upstream_previous.is_empty()
455                    && !self.downstream_previous.is_empty()
456                    && value == self.upstream_previous
457                    && self.downstream_previous != value =>
458            {
459                Some(self.downstream_previous.to_owned())
460            }
461            _ => None,
462        }
463    }
464}
465
466// --- request and frame helpers ----------------------------------------------------------
467
468/// `xaiWebsocketsEnabled` (and Go's identical `authWebsocketsEnabled`): the
469/// `websockets` attribute when it parses, else the metadata value (a bool, or a string
470/// that parses).
471pub fn websockets_enabled(credential: &Credential) -> bool {
472    if let Some(parsed) = credential
473        .attributes
474        .get("websockets")
475        .map(|v| v.trim())
476        .filter(|v| !v.is_empty())
477        .and_then(crate::xai::parse_bool)
478    {
479        return parsed;
480    }
481    match credential.metadata.get("websockets") {
482        Some(serde_json::Value::Bool(b)) => *b,
483        Some(serde_json::Value::String(s)) => crate::xai::parse_bool(s.trim()).unwrap_or(false),
484        _ => false,
485    }
486}
487
488/// A plain Go error (`fmt.Errorf`), as the manager sees it.
489fn plain(message: impl Into<String>) -> ExecError {
490    crate::openai_compat::plain_err(message.into())
491}
492
493/// `buildXAIResponsesWebsocketURL`.
494fn ws_url(http_url: &str) -> Result<String, ExecError> {
495    let raw = http_url.trim();
496    let mut parsed = crate::xai_url::parse(raw).map_err(|e| crate::xai_url::url_error(raw, &e))?;
497    parsed.scheme = match parsed.scheme.as_str() {
498        "http" => "ws".to_owned(),
499        "https" => "wss".to_owned(),
500        "ws" | "wss" => parsed.scheme.clone(),
501        other => {
502            return Err(crate::xai_url::statusless(format!(
503                "xai websockets executor: unsupported responses websocket URL scheme {}",
504                cpa_common::gostr::quote(other)
505            )));
506        }
507    };
508    if parsed.host.trim().is_empty() {
509        return Err(crate::xai_url::statusless(
510            "xai websockets executor: responses websocket URL host is empty",
511        ));
512    }
513    Ok(crate::xai_url::string(&parsed))
514}
515
516/// `buildXAIWebsocketRequestBody`: every turn is a stored `response.create`; the
517/// payload rules (`finalize`) see the WebSocket fields, then the type is fixed again.
518fn request_frame(body: &[u8], finalize: impl FnOnce(Vec<u8>) -> Vec<u8>) -> Vec<u8> {
519    if body.is_empty() {
520        return Vec::new();
521    }
522    let mut out = body.to_vec();
523    gj::set_str(&mut out, "type", "response.create");
524    for key in ["stream", "stream_options", "background"] {
525        gj::delete(&mut out, key);
526    }
527    gj::set_bool(&mut out, "store", true);
528    if !text(&gj::get(&out, "previous_response_id")).trim().is_empty() {
529        gj::delete(&mut out, "instructions");
530    }
531    let mut out = finalize(out);
532    gj::set_str(&mut out, "type", "response.create");
533    out
534}
535
536/// `xaiWebsocketGenerateFalse`: a warmup turn.
537fn generate_false(payload: &[u8]) -> bool {
538    let generate = gj::get(payload, "generate");
539    generate.exists() && !generate.bool()
540}
541
542/// `buildXAIWebsocketWarmupCompletedPayload`: the `response.completed` a warmup turn
543/// never receives, built from its `response.created`.
544fn warmup_completed(created: &[u8]) -> Vec<u8> {
545    let mut completed =
546        format!(r#"{{"type":"response.completed","response":{{"output":[],"usage":{EMPTY_USAGE}}}}}"#).into_bytes();
547    let sequence = gj::get(created, "sequence_number");
548    if sequence.exists() {
549        gj::set_int(&mut completed, "sequence_number", sequence.int() + 1);
550    }
551    let response = gj::get(created, "response");
552    if response.exists() && response.is_object() {
553        let mut inner = response.raw().to_vec();
554        gj::set_str(&mut inner, "status", "completed");
555        if !gj::get(&inner, "output").exists() {
556            gj::set_raw(&mut inner, "output", "[]");
557        }
558        if !gj::get(&inner, "usage").exists() {
559            gj::set_raw(&mut inner, "usage", EMPTY_USAGE);
560        }
561        gj::set_raw(&mut completed, "response", inner);
562    }
563    ensure_responses_usage_details(&completed)
564}
565
566/// `parseXAIWebsocketError`: an `error` frame classified like Codex's, then remapped by
567/// `xaiStatusErr` (403 bad credentials to 401, the free-usage retry hint); a bare frame
568/// with an `error` field takes its status from the frame.
569fn ws_error(payload: &[u8]) -> Option<ExecError> {
570    let text_payload = String::from_utf8_lossy(payload);
571    if let Some(mut error) = codex_ws::ws_error(&text_payload, false) {
572        let xai = response::status_error(error.status, payload);
573        error.status = xai.status;
574        if xai.retry_after.is_some() {
575            error.retry_after = xai.retry_after;
576        }
577        return Some(error);
578    }
579    if payload.is_empty() || !gj::get(payload, "error").exists() {
580        return None;
581    }
582    let mut status = gj::get(payload, "status").int();
583    if status <= 0 {
584        status = gj::get(payload, "status_code").int();
585    }
586    if status <= 0 {
587        status = bare_error_status(payload);
588    }
589    let mut out = b"{}".to_vec();
590    gj::set_str(&mut out, "type", "error");
591    gj::set_int(&mut out, "status", status);
592    let node = gj::get(payload, "error");
593    if node.exists() {
594        gj::set_raw(&mut out, "error", node.raw());
595    }
596    // Go keeps any int status; ExecError carries u16 (a larger code reads as 500).
597    Some(response::status_error(u16::try_from(status).unwrap_or(500), &out))
598}
599
600/// `xaiBareWebsocketErrorStatus`.
601fn bare_error_status(payload: &[u8]) -> i64 {
602    for path in ["error.code", "error.status", "code"] {
603        let raw = text(&gj::get(payload, path)).trim().to_owned();
604        if raw.is_empty() {
605            continue;
606        }
607        if let Some(status) = go_atoi(&raw).filter(|s| *s > 0) {
608            return status;
609        }
610    }
611    let message = text(&gj::get(payload, "error.message"));
612    if message.contains(r#""code":"400""#) || message.contains("Request validation error") {
613        return 400;
614    }
615    500
616}
617
618/// `strconv.Atoi`.
619fn go_atoi(s: &str) -> Option<i64> {
620    let digits = s.strip_prefix(['+', '-']).unwrap_or(s);
621    if digits.is_empty() || !digits.bytes().all(|b| b.is_ascii_digit()) {
622        return None;
623    }
624    s.parse().ok()
625}
626
627/// A socket failure from the shared pool, as Go's xAI executor reports it: a close 1009
628/// is the request-scoped 413 with `mapCodexWebsocketReadError`'s fixed body, and every
629/// other read or write failure is a plain Go error (500) under the xAI executor's name.
630// ponytail: Go's message for other closes is gorilla's ("websocket: close 1011 (internal
631// server error): internal"); the shared reader keeps no close details, so the text is
632// the pool's.
633fn pool_error(mut error: ExecError) -> ExecError {
634    const CODEX: &[u8] = b"codex websockets executor: ";
635    if error.status == 413 && error.scope == FailureScope::Request {
636        error.body = Bytes::from_static(
637            br#"{"error":{"message":"upstream websocket message too big","type":"invalid_request_error","code":"message_too_big"}}"#,
638        );
639        return error;
640    }
641    if error.body.starts_with(CODEX) {
642        error.body = Bytes::from([&b"xai websockets executor: "[..], &error.body[CODEX.len()..]].concat());
643    }
644    if error.scope == FailureScope::Transport {
645        error.status = 500;
646    }
647    error
648}
649
650/// `shouldRetryXAIWebsocketSend`: a request-scoped failure (413) never retries.
651fn should_retry_send(error: &ExecError) -> bool {
652    error.scope != FailureScope::Request
653}
654
655/// `applyXAIWebsocketHeaders`.
656fn handshake_headers(credential: &Credential, token: &str, session_id: &str, req: &ExecRequest) -> HeaderMap {
657    let mut headers = HeaderMap::new();
658    let mut set = |name: &str, value: &str| {
659        if let (Ok(name), Ok(value)) = (HeaderName::from_bytes(name.as_bytes()), HeaderValue::from_str(value)) {
660            headers.insert(name, value);
661        }
662    };
663    set("content-type", "application/json");
664    if !token.trim().is_empty() {
665        set("authorization", &format!("Bearer {token}"));
666    }
667    if !session_id.is_empty() {
668        set("x-grok-conv-id", session_id);
669    }
670    let session = cpa_common::session::cpa_session_id(req.session.as_deref());
671    for (name, value) in cpa_common::headers::custom_headers(&credential.attributes, &req.headers, session.as_deref()) {
672        set(&name, &value);
673    }
674    headers
675}
676
677// --- compaction (executeCompactionTriggerFromWebsocketContext) ---------------------------
678
679/// `buildXAIWebsocketCompactionPayload`.
680fn compaction_payload(payload: &[u8], transcript: &[u8]) -> Vec<u8> {
681    let mut out = if payload.is_empty() {
682        b"{}".to_vec()
683    } else {
684        payload.to_vec()
685    };
686    gj::set_raw(
687        &mut out,
688        "input",
689        if transcript.is_empty() { &b"[]"[..] } else { transcript },
690    );
691    gj::delete(&mut out, "previous_response_id");
692    out
693}
694
695/// `validateXAIWebsocketCompactionResponse`: the normalized response ID and the
696/// compaction item to keep as the transcript.
697fn validate_compaction(data: &[u8]) -> Result<(String, Vec<u8>), ExecError> {
698    let missing = || status_err(502, "xai websocket compaction response is missing compacted state");
699    if data.is_empty() || !gj::std_valid(data) {
700        return Err(status_err(502, "xai websocket compaction returned invalid JSON"));
701    }
702    let id = gj::get(data, "id");
703    let output = gj::get(data, "output");
704    if id.kind != Kind::String || id.str().trim().is_empty() || !output.exists() || !output.is_array() {
705        return Err(missing());
706    }
707    let items = output.array();
708    let Some(item) = items.first() else {
709        return Err(missing());
710    };
711    let item_type = item.get("type");
712    let encrypted = item.get("encrypted_content");
713    if item.kind != Kind::Json
714        || item_type.kind != Kind::String
715        || item_type.str().trim() != "compaction"
716        || encrypted.kind != Kind::String
717        || encrypted.str().trim().is_empty()
718    {
719        return Err(missing());
720    }
721    let response_id = compaction_response_id(data, SystemTime::now());
722    let item = compaction_item(data, &response_id);
723    Ok((response_id, item))
724}
725
726// --- capture (RecordAPIWebsocket*) ------------------------------------------------------
727
728/// The upstream WebSocket's capture: the request log Go builds once per turn (`wsReqLog`)
729/// and the events of its socket. A no-op without an observer.
730struct WsCapture {
731    sink: CaptureSink,
732    /// Go `EmitWebSocketResponseEvent`, called with every `AppendAPIWebsocketResponse`.
733    websocket: Option<cpa_core::exec::WebSocketEmitter>,
734    url: String,
735    headers: Vec<(String, String)>,
736    frame: Vec<u8>,
737    auth_id: String,
738    auth_label: String,
739    auth_type: &'static str,
740    auth_value: String,
741}
742
743impl WsCapture {
744    fn new(req: &ExecRequest, credential: &Credential, url: &str, headers: &HeaderMap, frame: &[u8]) -> Self {
745        let sink = req.capture().clone();
746        let websocket = req.websocket_emitter(crate::xai::PROVIDER, credential);
747        if !sink.enabled() {
748            // Nothing reads the fields without an observer: keep no copy of the frame.
749            return Self {
750                sink,
751                websocket,
752                url: String::new(),
753                headers: Vec::new(),
754                frame: Vec::new(),
755                auth_id: String::new(),
756                auth_label: String::new(),
757                auth_type: "",
758                auth_value: String::new(),
759            };
760        }
761        let (auth_type, auth_value) = cpa_core::registry::dynamic::account_info(credential);
762        Self {
763            headers: crate::openai_compat_http::header_pairs(headers),
764            sink,
765            websocket,
766            url: url.to_owned(),
767            frame: frame.to_vec(),
768            auth_id: credential.id.clone(),
769            auth_label: credential.label.clone(),
770            auth_type,
771            auth_value,
772        }
773    }
774
775    fn log<'a>(
776        &'a self,
777        url: &'a str,
778        method: &'a str,
779        headers: &'a [(String, String)],
780        body: &'a [u8],
781    ) -> UpstreamRequest<'a> {
782        UpstreamRequest {
783            url,
784            method,
785            headers,
786            body,
787            provider: crate::xai::PROVIDER,
788            auth_id: &self.auth_id,
789            auth_label: &self.auth_label,
790            auth_type: self.auth_type,
791            auth_value: &self.auth_value,
792        }
793    }
794
795    /// `RecordAPIWebsocketRequest`.
796    fn request(&self) {
797        if self.sink.enabled() {
798            self.sink.record(CaptureEvent::WebsocketRequest(self.log(
799                &self.url,
800                "WEBSOCKET",
801                &self.headers,
802                &self.frame,
803            )));
804        }
805    }
806
807    /// `RecordAPIWebsocketUpgradeRejection`: an HTTP attempt (`websocketUpgradeRequestLog`:
808    /// GET on the http(s) URL, no body, Connection and Upgrade defaulted).
809    fn rejection(&self, status: u16, headers: &HeaderMap, body: &[u8]) {
810        if !self.sink.enabled() {
811            return;
812        }
813        let url = upgrade_url(&self.url);
814        let mut request_headers = self.headers.clone();
815        for (name, value) in [("Connection", "Upgrade"), ("Upgrade", "websocket")] {
816            if !request_headers.iter().any(|(n, v)| n == name && !v.trim().is_empty()) {
817                request_headers.retain(|(n, _)| n != name);
818                request_headers.push((name.to_owned(), value.to_owned()));
819            }
820        }
821        self.sink
822            .record(CaptureEvent::Request(self.log(&url, "GET", &request_headers, &[])));
823        let response_headers = crate::openai_compat_http::header_pairs(headers);
824        self.sink
825            .record(CaptureEvent::ResponseMetadata(status, &response_headers));
826        self.sink.record(CaptureEvent::ResponseChunk(body));
827    }
828
829    /// `recordAPIWebsocketHandshake` for a newly dialed socket.
830    fn handshake(&self, headers: &HeaderMap) {
831        if self.sink.enabled() {
832            let pairs = crate::openai_compat_http::header_pairs(headers);
833            self.sink.record(CaptureEvent::WebsocketHandshake(101, &pairs));
834        }
835    }
836
837    /// `RecordAPIWebsocketError`.
838    fn error(&self, stage: &str, error: &ExecError) {
839        if self.sink.enabled() {
840            self.sink.record(CaptureEvent::WebsocketError {
841                stage,
842                error: &String::from_utf8_lossy(&error.body),
843            });
844        }
845    }
846
847    /// `AppendAPIWebsocketResponse`.
848    /// Records the message and returns its observation, if any.
849    fn response(&self, payload: &[u8]) -> Option<futures_util::future::BoxFuture<'static, ()>> {
850        self.sink.record(CaptureEvent::WebsocketResponse(payload));
851        let websocket = self.websocket.clone()?;
852        let payload = payload.to_vec();
853        Some(Box::pin(async move { websocket.emit(&payload).await }))
854    }
855}
856
857/// `helps.WebsocketUpgradeRequestURL`: ws to http, wss to https.
858fn upgrade_url(raw: &str) -> String {
859    let raw = raw.trim();
860    match raw.find(':') {
861        Some(i) if raw[..i].eq_ignore_ascii_case("ws") => format!("http{}", &raw[i..]),
862        Some(i) if raw[..i].eq_ignore_ascii_case("wss") => format!("https{}", &raw[i..]),
863        _ => raw.to_owned(),
864    }
865}
866
867// --- the turn --------------------------------------------------------------------------
868
869/// One turn on the session's socket, as a stream of downstream payloads. Dropping it
870/// releases the turn lock and the reader.
871struct Turn {
872    rx: mpsc::Receiver<Read>,
873    conn: Arc<Upstream>,
874    session: Arc<Session>,
875    _turn: Option<OwnedMutexGuard<()>>,
876    /// The observation of the message being read, while it runs.
877    observing: Option<crate::ws_observation::Observation>,
878    apply_patch: apply_patch::State,
879    restorer: NamespaceRestorer,
880    filter: XSearchFilter,
881    alias: String,
882    items: OutputItems,
883    store: Arc<replay::Store>,
884    scope: ReplayScope,
885    mapper: Option<IdMapper>,
886    /// The frame sent upstream, recorded in the transcript.
887    frame: Vec<u8>,
888    transcript_reset: bool,
889    warmup: bool,
890    recorded: bool,
891    usage: cpa_core::exec::UsageSink,
892    /// A completed or done event carried usage (`StreamUsageBuffer.ok`).
893    usage_seen: bool,
894    capture: Arc<WsCapture>,
895    ready: VecDeque<Result<Bytes, ExecError>>,
896    done: bool,
897}
898
899impl Drop for Turn {
900    fn drop(&mut self) {
901        // An abandoned turn keeps its session until an observation it started returns,
902        // as Go's executor holds the session lock through the synchronous observer.
903        let conn = self.conn.clone();
904        crate::ws_observation::release_after(self.observing.take(), self._turn.take(), move || conn.deactivate());
905    }
906}
907
908impl Turn {
909    /// The validation that ends the upstream attempt before delivery or reuse
910    /// (`invalidatePatchAttempt`).
911    fn fail_patch(&mut self, events: Vec<Vec<u8>>) {
912        let error = apply_patch_error();
913        crate::openai_compat_http::publish_failure(&self.usage, &error);
914        self.session.invalidate(&self.conn, &error, false);
915        self.ready.extend(events.into_iter().map(|e| Ok(Bytes::from(e))));
916        self.ready.push_back(Err(error));
917        self.done = true;
918    }
919
920    fn record(&mut self, completed: &[u8]) {
921        if self.recorded {
922            return;
923        }
924        if let Some(mapper) = &self.mapper {
925            mapper.state.record(&self.frame, completed, self.transcript_reset);
926            self.recorded = true;
927        }
928    }
929
930    /// The socket failed: a pending apply_patch call fails first.
931    fn read_failed(&mut self, error: ExecError) {
932        if let Err(finish) = self.apply_patch.finish() {
933            let (events, _) = self.apply_patch.bridge.fail(&finish);
934            return self.fail_patch(events);
935        }
936        let error = pool_error(error);
937        // Every socket here has a session, whose reader hands a binary message over as a
938        // read error: Go logs it at the `read` stage (`unexpected_binary` is its
939        // sessionless reader's).
940        self.capture.error("read", &error);
941        crate::openai_compat_http::publish_failure(&self.usage, &error);
942        self.ready.push_back(Err(error));
943        self.done = true;
944    }
945
946    /// One upstream text message.
947    async fn message(&mut self, message: &str) {
948        let payload = cpa_common::gostr::trim_space(message.as_bytes());
949        if payload.is_empty() {
950            return;
951        }
952        self.usage.first_byte();
953        crate::ws_observation::observe(&mut self.observing, self.capture.response(payload)).await;
954        if let Some(error) = ws_error(payload) {
955            self.capture.error("upstream_error", &error);
956            crate::openai_compat_http::publish_failure(&self.usage, &error);
957            self.session.invalidate(&self.conn, &error, false);
958            self.ready.push_back(Err(error));
959            self.done = true;
960            return;
961        }
962        for event in response::normalize_summary_data_events(payload.to_vec()) {
963            self.apply_patch.remember_dispatcher_event(&event);
964            let mut event = self.restorer.restore(event);
965            if !self.alias.is_empty() {
966                event = response::restore_web_search_name(event, &self.alias);
967            }
968            let Some(event) = self.filter.apply(event).filter(|e| !e.is_empty()) else {
969                continue;
970            };
971            let (events, bridge_error) = self.apply_patch.transform(&event);
972            if bridge_error.is_some() {
973                return self.fail_patch(events);
974            }
975            for event in events {
976                if self.event(event) {
977                    self.done = true;
978                    // The goroutine's deferred `streamUsage.Publish`.
979                    if self.usage_seen {
980                        self.usage.publish();
981                    }
982                    return;
983                }
984            }
985        }
986    }
987
988    /// One event for the client; true ends the turn.
989    fn event(&mut self, mut event: Vec<u8>) -> bool {
990        let kind = text(&gj::get(&event, "type"));
991        let patch_terminal =
992            self.apply_patch.active() && matches!(kind.as_str(), "response.incomplete" | "response.failed");
993        let terminal = matches!(kind.as_str(), "response.completed" | "response.done" | "error") || patch_terminal;
994        if self.usage.enabled() {
995            // ObserveResponseModel, and StreamUsageBuffer.Observe on completed and done.
996            self.usage
997                .response_line(Format::Codex, &response::usage_line(&event, &WS_USAGE_EVENTS));
998            if WS_USAGE_EVENTS.contains(&kind.as_str()) && response::codex_usage_ok(&event) {
999                self.usage_seen = true;
1000            }
1001        }
1002        let mut warmup_completed_event = None;
1003        match kind.as_str() {
1004            "response.created" if self.warmup => {
1005                let completed = warmup_completed(&event);
1006                self.record(&completed);
1007                warmup_completed_event = Some(completed);
1008            }
1009            "response.output_item.done" => self.items.collect(&event),
1010            "response.completed" => {
1011                event = response::normalize_summary_data(self.items.patch(&event));
1012                replay::cache_completed(&self.store, &self.scope, &event);
1013                if !self.warmup {
1014                    self.record(&event);
1015                }
1016            }
1017            "response.done" if !self.warmup => self.record(&event),
1018            _ => {}
1019        }
1020        let mut downstream = ensure_responses_usage_details(&event);
1021        if let Some(mapper) = &mut self.mapper {
1022            downstream = mapper.downstream_response(downstream);
1023        }
1024        self.ready.push_back(Ok(Bytes::from(downstream)));
1025        if let Some(completed) = warmup_completed_event {
1026            let mut completed = ensure_responses_usage_details(&completed);
1027            if let Some(mapper) = &mut self.mapper {
1028                completed = mapper.downstream_response(completed);
1029            }
1030            self.ready.push_back(Ok(Bytes::from(completed)));
1031            return true;
1032        }
1033        terminal
1034    }
1035
1036    async fn next(&mut self) -> Option<Result<Bytes, ExecError>> {
1037        loop {
1038            if let Some(item) = self.ready.pop_front() {
1039                if item.is_err() {
1040                    self.ready.clear();
1041                    self.done = true;
1042                }
1043                return Some(item);
1044            }
1045            if self.done {
1046                return None;
1047            }
1048            match self.rx.recv().await {
1049                Some(Read::Text(message)) => self.message(&message).await,
1050                Some(Read::Failed(error)) => self.read_failed(error),
1051                // The reader's terminal error did not fit a full queue (Go's
1052                // `sendTerminalWebsocketRead` waits for room); it is kept on the socket.
1053                None => {
1054                    let lost = self.conn.link.lock().expect("link").lost.clone();
1055                    self.read_failed(
1056                        lost.unwrap_or_else(|| plain("xai websockets executor: session read channel closed")),
1057                    );
1058                }
1059            }
1060        }
1061    }
1062}
1063
1064impl XaiExecutor {
1065    /// `XAIAutoExecutor.ExecuteStream` for a downstream WebSocket turn: the upstream
1066    /// socket when the credential enables `websockets`, else HTTP (which cannot continue
1067    /// upstream state).
1068    pub async fn execute_in_session(
1069        &self,
1070        credential: &Credential,
1071        req: ExecRequest,
1072        cfg: &Config,
1073        session: &ExecSession,
1074    ) -> Result<ExecResponse, ExecError> {
1075        if websockets_enabled(credential) {
1076            let cfg = crate::xai::scoped(credential, cfg);
1077            return self.stream_ws(credential, req, cfg.as_ref(), session).await;
1078        }
1079        if session.continuation {
1080            // Go's auto executor answers before any reporter exists.
1081            req.usage.discard();
1082            return Err(ExecError::replay_required());
1083        }
1084        self.execute(credential, req, cfg, true).await
1085    }
1086
1087    /// Whether this credential keeps upstream state on the session's socket.
1088    pub fn session_upstream(credential: &Credential) -> bool {
1089        websockets_enabled(credential)
1090    }
1091
1092    pub fn session_closed(&self, id: &str) -> impl std::future::Future<Output = ExecError> + Send + 'static {
1093        self.ws.closed(id)
1094    }
1095
1096    pub fn close_session(&self, id: &str) {
1097        self.ws.close(id);
1098    }
1099
1100    /// `XAIWebsocketsExecutor.ExecuteStream`.
1101    async fn stream_ws(
1102        &self,
1103        credential: &Credential,
1104        req: ExecRequest,
1105        cfg: &Config,
1106        exec_session: &ExecSession,
1107    ) -> Result<ExecResponse, ExecError> {
1108        if req.alt.as_deref() == Some(crate::xai::COMPACT_ALT) {
1109            req.usage.discard();
1110            return Err(status_err(400, "streaming not supported for /responses/compact"));
1111        }
1112        let exec_id = exec_session.id.trim().to_owned();
1113        let mut state_id = request::execution_session_id(&req);
1114        if state_id.is_empty() {
1115            state_id.clone_from(&exec_id);
1116        }
1117        // The ID state is taken after the session and its turn lock, as Go builds the
1118        // mapper: a credential removal drops both together, so a replacement session
1119        // never shares a state that was already dropped.
1120        if crate::xai::input_has_item_type(&req.body, "compaction_trigger") {
1121            if exec_session.continuation {
1122                req.usage.discard();
1123                return Err(ExecError::replay_required());
1124            }
1125            let session = self.ws.pool.session(&exec_id);
1126            let _turn = session.turn.clone().lock_owned().await;
1127            let mapper = self.ws.state(&state_id).map(|s| IdMapper::new(s, &req.body));
1128            return self.ws_compaction(credential, &req, cfg, mapper).await;
1129        }
1130
1131        // The official API (or an explicit base_url): cli-chat-proxy refuses upgrades.
1132        let (token, mut base) = creds(credential);
1133        if base.is_empty() {
1134            base = DEFAULT_API_BASE_URL.to_owned();
1135        }
1136        let mut prepared = crate::xai::before_reporter(
1137            &req.usage,
1138            request::prepare(&req, cfg, true, Format::Codex, &self.replay, true).await,
1139        )?;
1140        let previous = text(&gj::get(&req.body, "previous_response_id")).trim().to_owned();
1141        if !previous.is_empty() {
1142            gj::set_str(&mut prepared.body, "previous_response_id", &previous);
1143        }
1144        let http_url = format!("{}/responses", base.strip_suffix('/').unwrap_or(&base));
1145        let target = Target::new(credential, self.url(ws_url(&http_url)?), cfg);
1146
1147        let session = self.ws.pool.session(&exec_id);
1148        let guard = session.turn.clone().lock_owned().await;
1149        #[cfg(test)]
1150        self.ws.paused().await;
1151        let state = self.ws.state(&state_id);
1152        let mut mapper = state.clone().map(|s| IdMapper::new(s, &req.body));
1153        if let Some(m) = &mut mapper {
1154            let live = session
1155                .current()
1156                .is_some_and(|c| c.target.credential == target.credential);
1157            if m.state.target_changed(&target, live) {
1158                m.upstream_previous.clear();
1159            }
1160            prepared.body = m.upstream_request(std::mem::take(&mut prepared.body));
1161        }
1162        // The turn publishes only usage it parsed (no EnsurePublished).
1163        req.usage.usage_required();
1164        req.usage.request_for(crate::xai::PROVIDER, &prepared.body);
1165        let headers = handshake_headers(credential, &token, &prepared.session_id, &req);
1166        let frame = request_frame(&prepared.body, |b| prepared.finalize(cfg, &req, b));
1167        let request_type = text(&gj::get(&req.body, "type"));
1168        let transcript_reset = text(&gj::get(&frame, "previous_response_id")).trim().is_empty()
1169            && (request_type.trim() != "response.append" || mapper.as_ref().is_some_and(|m| m.replayed_compacted));
1170        let warmup = generate_false(&frame);
1171        let message = String::from_utf8_lossy(&frame).into_owned();
1172        let capture = Arc::new(WsCapture::new(&req, credential, &target.url, &headers, &frame));
1173        capture.request();
1174
1175        let (mut conn, mut handshake) = if exec_session.continuation {
1176            match session.current().filter(|c| c.target.serves(&target)) {
1177                Some(conn) => (conn, None),
1178                None => return Err(ExecError::replay_required()),
1179            }
1180        } else {
1181            self.ws_ensure(
1182                &session,
1183                &target,
1184                &headers,
1185                cfg,
1186                credential,
1187                state.as_deref(),
1188                &capture,
1189                false,
1190            )
1191            .await?
1192        };
1193        if let Some(handshake) = &handshake {
1194            capture.handshake(handshake);
1195        }
1196        conn.bind(&session, exec_session.lease.as_ref())?;
1197        req.usage.round_trip_started();
1198        let mut rx = conn.activate();
1199        if let Err(error) = conn.send(message.clone()).await {
1200            let error = pool_error(error);
1201            capture.error("send", &error);
1202            // `shouldRetryCodexWebsocketSend`: a request-scoped failure (413) never retries.
1203            let retry = should_retry_send(&error);
1204            if exec_session.continuation {
1205                session.invalidate(&conn, &error, false);
1206                return Err(if retry { ExecError::replay_required() } else { error });
1207            }
1208            session.invalidate(&conn, &error, true);
1209            if !retry {
1210                return Err(error);
1211            }
1212            let (fresh, fresh_handshake) = self
1213                .ws_ensure(
1214                    &session,
1215                    &target,
1216                    &headers,
1217                    cfg,
1218                    credential,
1219                    state.as_deref(),
1220                    &capture,
1221                    true,
1222                )
1223                .await?;
1224            capture.request();
1225            if let Some(handshake) = &fresh_handshake {
1226                capture.handshake(handshake);
1227            }
1228            fresh.bind(&session, exec_session.lease.as_ref())?;
1229            req.usage.round_trip_started();
1230            rx = fresh.activate();
1231            if let Err(error) = fresh.send(message).await {
1232                let error = pool_error(error);
1233                capture.error("send_retry", &error);
1234                session.invalidate(&fresh, &error, true);
1235                return Err(error);
1236            }
1237            conn = fresh;
1238            handshake = fresh_handshake;
1239        }
1240
1241        let turn = Turn {
1242            rx,
1243            conn,
1244            session,
1245            _turn: Some(guard),
1246            observing: None,
1247            apply_patch: prepared.apply_patch,
1248            restorer: NamespaceRestorer::new(prepared.namespace_tools),
1249            filter: XSearchFilter::new(prepared.filter_internal_x_search, prepared.client_declared_tools),
1250            alias: prepared.web_search_alias,
1251            items: OutputItems::default(),
1252            store: self.replay.clone(),
1253            scope: prepared.replay_scope.clone(),
1254            mapper,
1255            frame,
1256            transcript_reset,
1257            warmup,
1258            recorded: false,
1259            usage: req.usage.clone(),
1260            usage_seen: false,
1261            capture,
1262            ready: VecDeque::new(),
1263            done: false,
1264        };
1265        let stream = futures_util::stream::unfold(turn, |mut turn| async move {
1266            let item = turn.next().await?;
1267            Some((item, turn))
1268        })
1269        .boxed();
1270        Ok(ExecResponse {
1271            status: 200,
1272            headers: handshake.unwrap_or_default(),
1273            body: ResponseBody::Stream(prepared.replay_scope.writes.gate(stream)),
1274        })
1275    }
1276
1277    /// `ensureUpstreamConn`: the session's socket for `target`, dialing a new one (and
1278    /// closing one for another target) when needed. Returns the handshake headers of a
1279    /// new socket.
1280    #[allow(clippy::too_many_arguments)]
1281    async fn ws_ensure(
1282        &self,
1283        session: &Arc<Session>,
1284        target: &Target,
1285        headers: &HeaderMap,
1286        cfg: &Config,
1287        credential: &Credential,
1288        state: Option<&IdState>,
1289        capture: &WsCapture,
1290        retry: bool,
1291    ) -> Result<(Arc<Upstream>, Option<HeaderMap>), ExecError> {
1292        if let Some(current) = session.current() {
1293            if current.target.serves(target) {
1294                return Ok((current, None));
1295            }
1296            // target_changed: another credential, URL or proxy now serves this session.
1297            let mut slot = session.conn.lock().expect("session conn");
1298            if slot.as_ref().is_some_and(|c| Arc::ptr_eq(c, &current)) {
1299                *slot = None;
1300            }
1301            drop(slot);
1302            current.shutdown();
1303        }
1304        let client = self.clients.for_credential(credential, cfg);
1305        let (socket, handshake) = dial(&client, target, headers, capture, retry).await?;
1306        let (sink, stream) = socket.split();
1307        let conn = Upstream::new(target.clone(), sink, self.ws.pool.write);
1308        // Publish before the reader runs, as the Codex executor does.
1309        let mut reader = conn.reader.lock().expect("reader handle");
1310        session.publish(conn.clone());
1311        let task = tokio::spawn(codex_ws::read_loop(
1312            stream,
1313            Arc::downgrade(session),
1314            conn.clone(),
1315            self.ws.pool.idle,
1316        ));
1317        *reader = Some(task.abort_handle());
1318        drop(reader);
1319        if let Some(state) = state {
1320            state.set_target(target);
1321        }
1322        Ok((conn, Some(handshake)))
1323    }
1324}
1325
1326/// `dialXAIWebsocket`: a rejected upgrade is `xaiStatusErr(status, body)`.
1327///
1328/// Capture: the first dial records a rejected upgrade (any handshake response, including
1329/// a 101 gorilla refuses) as an HTTP attempt and any other failure as a `dial` error; a
1330/// retry dial records every failure as `dial_retry`, with gorilla's text for a rejection.
1331// ponytail: Go returns `xaiStatusErr(101, body)` for a 101 gorilla refuses; this keeps the
1332// plain handshake error, since a 101 status error has no sensible client response.
1333async fn dial(
1334    client: &wreq::Client,
1335    target: &Target,
1336    headers: &HeaderMap,
1337    capture: &WsCapture,
1338    retry: bool,
1339) -> Result<(codex_ws::WebSocket, HeaderMap), ExecError> {
1340    let stage = if retry { "dial_retry" } else { "dial" };
1341    match dial_once(client, target, headers).await {
1342        Ok(socket) => Ok(socket),
1343        Err(Dial::Rejected(rejected)) => {
1344            let Rejection {
1345                error,
1346                status,
1347                headers,
1348                body,
1349                reason,
1350            } = *rejected;
1351            if retry {
1352                capture.error(stage, &plain(reason));
1353            } else {
1354                capture.rejection(status, &headers, &body);
1355            }
1356            Err(error)
1357        }
1358        Err(Dial::Failed(error)) => {
1359            capture.error(stage, &error);
1360            Err(error)
1361        }
1362    }
1363}
1364
1365/// A failed dial: a handshake response gorilla rejects, or any other failure.
1366enum Dial {
1367    Rejected(Box<Rejection>),
1368    Failed(ExecError),
1369}
1370
1371/// A handshake response gorilla rejects: the returned error, the response, and gorilla's
1372/// error text.
1373struct Rejection {
1374    error: ExecError,
1375    status: u16,
1376    headers: HeaderMap,
1377    body: Vec<u8>,
1378    reason: &'static str,
1379}
1380
1381const BAD_HANDSHAKE: &str = "websocket: bad handshake";
1382
1383async fn dial_once(
1384    client: &wreq::Client,
1385    target: &Target,
1386    headers: &HeaderMap,
1387) -> Result<(codex_ws::WebSocket, HeaderMap), Dial> {
1388    // Go's xAI dialer is gorilla's with `EnableCompression`, like the Codex one, and the
1389    // socket joins the same pool type, so both dial through codex_ws's upgrade.
1390    let mut headers = headers.clone();
1391    let key = codex_ws::offer_compression(&mut headers);
1392    let builder = client.websocket(&target.url).headers(headers).accept_key(key.clone());
1393    let attempt = async {
1394        let mut res = builder
1395            .send()
1396            .await
1397            // wreq's error text includes the URL, and a configured base-url can carry a
1398            // key in its query; the error reaches the client and the request log.
1399            .map_err(|e| {
1400                Dial::Failed(plain(format!(
1401                    "xai websockets executor: dial failed: {}",
1402                    e.without_uri()
1403                )))
1404            })?;
1405        let status = res.status().as_u16();
1406        let handshake = res.headers().clone();
1407        if status != 101 {
1408            let inner = std::mem::replace(&mut *res, wreq::Response::from(http::Response::new(Vec::<u8>::new())));
1409            let mut body = Vec::new();
1410            let mut stream = inner.bytes_stream();
1411            while let Some(Ok(chunk)) = stream.next().await {
1412                body.extend_from_slice(&chunk[..chunk.len().min(MAX_HANDSHAKE_BODY - body.len())]);
1413                if body.len() >= MAX_HANDSHAKE_BODY {
1414                    break;
1415                }
1416            }
1417            // Go marks the upstream attempt on a dial error; here the upstream headers do
1418            // (the server's `upstream_attempted`).
1419            let mut error = response::status_error(status, &body);
1420            error.headers = Box::new(handshake.clone());
1421            return Err(Dial::Rejected(Box::new(Rejection {
1422                error,
1423                status,
1424                headers: handshake,
1425                body,
1426                reason: BAD_HANDSHAKE,
1427            })));
1428        }
1429        let socket = codex_ws::upgrade(&mut res, &key, &handshake).await.map_err(|e| {
1430            let (error, reason) = match e {
1431                codex_ws::UpgradeError::Handshake => (
1432                    plain("xai websockets executor: websocket handshake failed"),
1433                    BAD_HANDSHAKE,
1434                ),
1435                codex_ws::UpgradeError::Compression => (
1436                    plain("xai websockets executor: websocket: invalid compression negotiation"),
1437                    "websocket: invalid compression negotiation",
1438                ),
1439            };
1440            Dial::Rejected(Box::new(Rejection {
1441                error,
1442                status,
1443                headers: handshake.clone(),
1444                body: Vec::new(),
1445                reason,
1446            }))
1447        })?;
1448        Ok((socket, handshake))
1449    };
1450    tokio::time::timeout(HANDSHAKE_TIMEOUT, attempt)
1451        .await
1452        .unwrap_or_else(|_| Err(Dial::Failed(plain("xai websockets executor: handshake timed out"))))
1453}
1454
1455impl XaiExecutor {
1456    /// `executeCompactionTriggerFromWebsocketContext`: compacts the recorded transcript
1457    /// (or the turn's own input, or its previous response) over HTTP and keeps only the
1458    /// compaction item as the transcript.
1459    async fn ws_compaction(
1460        &self,
1461        credential: &Credential,
1462        req: &ExecRequest,
1463        cfg: &Config,
1464        mapper: Option<IdMapper>,
1465    ) -> Result<ExecResponse, ExecError> {
1466        // Go's context errors come before executeCompactRequest creates its reporter.
1467        let Some(mapper) = mapper else {
1468            req.usage.discard();
1469            return Err(status_err(400, "xai websocket compaction context is unavailable"));
1470        };
1471        let payload = match mapper.state.snapshot() {
1472            Some(transcript) => compaction_payload(&req.body, &transcript),
1473            None => {
1474                let filtered = crate::xai::remove_input_items(req.body.to_vec(), "compaction_trigger");
1475                let input = gj::get(&filtered, "input");
1476                if input.is_array() && !input.array().is_empty() {
1477                    let raw = input.raw().to_vec();
1478                    compaction_payload(&filtered, &raw)
1479                } else {
1480                    let mut previous = mapper.upstream_previous.clone();
1481                    if previous.is_empty() {
1482                        previous = text(&gj::get(&req.body, "previous_response_id")).trim().to_owned();
1483                    }
1484                    if previous.is_empty() {
1485                        req.usage.discard();
1486                        return Err(status_err(400, "xai websocket compaction context is empty"));
1487                    }
1488                    let mut out = crate::xai::remove_input_items(req.body.to_vec(), "compaction_trigger");
1489                    gj::set_str(&mut out, "previous_response_id", &previous);
1490                    out
1491                }
1492            }
1493        };
1494        let mut compact = req.clone();
1495        compact.body = Bytes::from(payload);
1496        let (prepared, data, mut headers) = self.compact_request(credential, &compact, cfg, true).await?;
1497        let (response_id, item) = validate_compaction(&data)?;
1498        // Publish(ParseOpenAIUsage(data)): the compact body compact_request reported.
1499        compact.usage.publish();
1500        mapper.state.replace(&[&item]);
1501        mapper.state.map(&response_id, "");
1502        headers.insert(
1503            http::header::CONTENT_TYPE,
1504            HeaderValue::from_static("text/event-stream"),
1505        );
1506        let frames: Vec<Result<Bytes, ExecError>> = compaction_frames(&prepared, &data, SystemTime::now())
1507            .into_iter()
1508            .map(|f| Ok(Bytes::from(f)))
1509            .collect();
1510        Ok(ExecResponse {
1511            status: 200,
1512            headers,
1513            body: ResponseBody::Stream(futures_util::stream::iter(frames).boxed()),
1514        })
1515    }
1516}
1517
1518#[cfg(test)]
1519#[path = "xai_ws_tests.rs"]
1520mod tests;