Skip to main content

agent_client_protocol/jsonrpc/
protocol_compat.rs

1/// The name and version substituted for a missing or malformed `info` when
2/// an agent selects protocol v2 for a client that requested a newer version.
3///
4/// `info` is required in v2, but a newer client's identity may not parse
5/// under v2. The request is accepted with this placeholder instead.
6#[cfg(feature = "unstable_protocol_v2")]
7pub(crate) const UNKNOWN_IMPLEMENTATION: &str = "unknown";
8
9/// Canonicalize a newer client's `initialize` parameters as a v2 request.
10///
11/// The agent selected v2 for a request written for a newer version, so it
12/// must ignore what it can't parse instead of rejecting the request. The
13/// result is the v2 request that remains: each capability that does not parse
14/// is dropped, `_meta` is dropped unless it is an object, fields v2 does not
15/// define are dropped, and a missing or malformed `info` is replaced by
16/// [`UNKNOWN_IMPLEMENTATION`] for both name and version. `protocolVersion` is
17/// set to v2.
18#[cfg(feature = "unstable_protocol_v2")]
19pub(crate) fn normalize_newer_v2_initialize_request(
20    params: &serde_json::Map<String, serde_json::Value>,
21) -> Result<serde_json::Map<String, serde_json::Value>, crate::Error> {
22    use crate::{schema::ProtocolVersion, v2::schema as v2};
23    use serde::Deserialize as _;
24
25    let mut params = params.clone();
26    let info_parses = params
27        .get("info")
28        .is_some_and(|info| v2::Implementation::deserialize(info).is_ok());
29    if !info_parses {
30        let unknown = v2::Implementation::new(UNKNOWN_IMPLEMENTATION, UNKNOWN_IMPLEMENTATION);
31        params.insert(
32            "info".into(),
33            serde_json::to_value(unknown).map_err(crate::Error::into_internal_error)?,
34        );
35    }
36    retain_parsable_capabilities::<v2::ClientCapabilities>(&mut params, "capabilities");
37    retain_object(&mut params, "_meta");
38    params.insert(
39        "protocolVersion".into(),
40        serde_json::to_value(ProtocolVersion::V2).map_err(crate::Error::into_internal_error)?,
41    );
42    let initialize: v2::InitializeRequest =
43        serde_json::from_value(serde_json::Value::Object(params))?;
44    let serde_json::Value::Object(normalized) =
45        serde_json::to_value(initialize).map_err(crate::Error::into_internal_error)?
46    else {
47        return Err(crate::util::internal_error(
48            "initialize params did not serialize to an object",
49        ));
50    };
51    Ok(normalized)
52}
53
54/// Drop each capability under `key` that does not parse as part of `T`, or
55/// the whole entry if it is not an object.
56fn retain_parsable_capabilities<T: serde::de::DeserializeOwned>(
57    params: &mut serde_json::Map<String, serde_json::Value>,
58    key: &str,
59) {
60    if !retain_object(params, key) {
61        return;
62    }
63    if let Some(serde_json::Value::Object(capabilities)) = params.get_mut(key) {
64        capabilities.retain(|name, value| {
65            let single = serde_json::Map::from_iter([(name.clone(), value.clone())]);
66            serde_json::from_value::<T>(serde_json::Value::Object(single)).is_ok()
67        });
68    }
69}
70
71/// Remove `key` unless it holds an object. Returns whether an object remains.
72fn retain_object(params: &mut serde_json::Map<String, serde_json::Value>, key: &str) -> bool {
73    match params.get(key) {
74        Some(serde_json::Value::Object(_)) => true,
75        Some(_) => {
76            params.remove(key);
77            false
78        }
79        None => false,
80    }
81}
82
83/// Normalize a newer peer's initialization into the stable v1 surface.
84///
85/// Only shared capabilities are carried across. In particular, unknown newer
86/// fields must never enable the v1 file-system or terminal-execution surfaces.
87///
88/// The request was written for a newer version, so parameters that don't
89/// parse under v1 are dropped instead of rejecting it: a missing or malformed
90/// `info` leaves v1's optional `clientInfo` unset, capabilities that don't
91/// parse are dropped, and `_meta` is dropped unless it is an object.
92pub(crate) fn normalize_v1_initialize_request(
93    params: &serde_json::Value,
94) -> Result<serde_json::Map<String, serde_json::Value>, crate::Error> {
95    use crate::{schema::ProtocolVersion, v1::schema as v1};
96    use serde::Deserialize as _;
97
98    let info = params
99        .get("info")
100        .and_then(|info| v1::Implementation::deserialize(info).ok());
101    let mut capabilities = serde_json::Map::new();
102    if let Some(source) = params
103        .get("capabilities")
104        .and_then(serde_json::Value::as_object)
105    {
106        for key in ["auth", "elicitation", "_meta"] {
107            if let Some(value) = source.get(key) {
108                capabilities.insert(key.into(), value.clone());
109            }
110        }
111    }
112    if let Some(auth) = capabilities
113        .get_mut("auth")
114        .and_then(serde_json::Value::as_object_mut)
115    {
116        let terminal = auth
117            .remove("terminal")
118            .is_some_and(|value| value.is_object());
119        auth.insert("terminal".into(), terminal.into());
120    }
121    capabilities.insert(
122        "session".into(),
123        serde_json::json!({ "configOptions": { "boolean": {} } }),
124    );
125    let mut target = serde_json::Map::from_iter([
126        (
127            "protocolVersion".to_owned(),
128            serde_json::to_value(ProtocolVersion::V1).map_err(crate::Error::into_internal_error)?,
129        ),
130        ("clientCapabilities".to_owned(), capabilities.into()),
131    ]);
132    if let Some(info) = info {
133        target.insert(
134            "clientInfo".into(),
135            serde_json::to_value(info).map_err(crate::Error::into_internal_error)?,
136        );
137    }
138    if let Some(meta) = params.get("_meta") {
139        target.insert("_meta".into(), meta.clone());
140    }
141    retain_parsable_capabilities::<v1::ClientCapabilities>(&mut target, "clientCapabilities");
142    retain_object(&mut target, "_meta");
143    let initialize: v1::InitializeRequest =
144        serde_json::from_value(serde_json::Value::Object(target))?;
145    let serde_json::Value::Object(normalized) =
146        serde_json::to_value(initialize).map_err(crate::Error::into_internal_error)?
147    else {
148        return Err(crate::util::internal_error(
149            "initialize params did not serialize to an object",
150        ));
151    };
152    Ok(normalized)
153}
154
155/// The outcome of a v2 client's [`send_initialize`](crate::v2::ConnectionTo::send_initialize).
156///
157/// A lower selection is reported with the crate-root
158/// [`InitializationVersionMismatch`](crate::InitializationVersionMismatch).
159///
160/// A v1-only agent may legitimately answer a v2 initialization attempt with a
161/// v1 response. That is a successful reply, not an error, so it is reported as
162/// [`InitializeOutcome::LowerVersion`]. Errors from the agent, malformed
163/// responses, and transport failures still resolve the request with an error.
164#[cfg(feature = "unstable_protocol_v2")]
165#[derive(Debug, Clone, PartialEq, Eq)]
166#[non_exhaustive]
167pub enum InitializeOutcome {
168    /// The agent selected v2 and the connection is ready for v2 traffic.
169    Initialized(Box<crate::v2::schema::InitializeResponse>),
170    /// The agent selected a lower protocol version.
171    ///
172    /// The connection stays uninitialized: a v2 connection cannot carry the
173    /// selected version's traffic, and the SDK never converts it. Fall back to
174    /// an implementation of the selected version if that is acceptable.
175    LowerVersion(InitializationVersionMismatch),
176}
177
178/// A successful `initialize` response that selected a lower protocol version
179/// than the local API requires.
180///
181/// Reported by [`v2::InitializeOutcome::LowerVersion`](crate::v2::InitializeOutcome::LowerVersion).
182/// This is not the `-32022` (`Unsupported protocol version`) error an agent
183/// returns when it supports no version at or below the requested one.
184///
185/// It lives at the crate root because it is not tied to one protocol
186/// version. `v2::ConnectionTo::send_initialize` reports a lower selection
187/// with it.
188#[cfg(feature = "unstable_protocol_v2")]
189#[derive(Debug, Clone, PartialEq, Eq)]
190#[non_exhaustive]
191pub struct InitializationVersionMismatch {
192    /// The protocol version the local connection requested.
193    pub requested: crate::schema::ProtocolVersion,
194    /// The peer's validated initialization response for the version it
195    /// selected. [`selected`](Self::selected) returns that version.
196    pub response: SelectedInitializeResponse,
197}
198
199#[cfg(feature = "unstable_protocol_v2")]
200impl InitializationVersionMismatch {
201    /// Describe a peer that answered a request for `requested` with
202    /// `response`, selecting the response's protocol version.
203    ///
204    /// Useful for exercising fallback paths in tests.
205    #[must_use]
206    pub fn new(
207        requested: crate::schema::ProtocolVersion,
208        response: SelectedInitializeResponse,
209    ) -> Self {
210        Self {
211            requested,
212            response,
213        }
214    }
215
216    /// The lower protocol version the peer selected: the version of
217    /// [`response`](Self::response).
218    #[must_use]
219    pub fn selected(&self) -> crate::schema::ProtocolVersion {
220        self.response.protocol_version()
221    }
222}
223
224#[cfg(feature = "unstable_protocol_v2")]
225impl std::fmt::Display for InitializationVersionMismatch {
226    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
227        write!(
228            f,
229            "requested ACP protocol version {} but peer selected {}",
230            self.requested,
231            self.selected(),
232        )
233    }
234}
235
236/// A peer's initialization response, typed by the protocol version it selected.
237///
238/// It lives at the crate root because it is not tied to one protocol
239/// version. A version is only ever selected below a higher requested one, so
240/// each variant is available with the feature of the next higher version:
241/// `V1` with `unstable_protocol_v2`. New variants are added as later protocol
242/// versions make more versions selectable below the one a client requests.
243#[cfg(feature = "unstable_protocol_v2")]
244#[derive(Debug, Clone, PartialEq, Eq)]
245#[non_exhaustive]
246pub enum SelectedInitializeResponse {
247    /// The peer selected ACP protocol v1.
248    V1(Box<crate::v1::schema::InitializeResponse>),
249}
250
251#[cfg(feature = "unstable_protocol_v2")]
252impl SelectedInitializeResponse {
253    /// The protocol version the response selects.
254    #[must_use]
255    pub fn protocol_version(&self) -> crate::schema::ProtocolVersion {
256        match self {
257            Self::V1(response) => response.protocol_version,
258        }
259    }
260}
261
262// The wire guard only validates this response. Box it only when returning it to the caller.
263#[cfg(feature = "unstable_protocol_v2")]
264fn parse_v1_selection(
265    version: crate::schema::ProtocolVersion,
266    value: serde_json::Value,
267) -> Option<crate::Result<crate::v1::schema::InitializeResponse>> {
268    (version == crate::schema::ProtocolVersion::V1).then(|| {
269        <crate::v1::schema::InitializeResponse as crate::JsonRpcResponse>::from_json(
270            "initialize",
271            value,
272        )
273    })
274}
275
276#[cfg(feature = "unstable_protocol_v2")]
277impl crate::JsonRpcResponse for InitializeOutcome {
278    fn into_json(self, method: &str) -> Result<serde_json::Value, crate::Error> {
279        match self {
280            Self::Initialized(response) => response.into_json(method),
281            Self::LowerVersion(mismatch) => match mismatch.response {
282                SelectedInitializeResponse::V1(response) => response.into_json(method),
283            },
284        }
285    }
286
287    fn from_json(method: &str, value: serde_json::Value) -> Result<Self, crate::Error> {
288        let selected: crate::schema::ProtocolVersion = value
289            .get("protocolVersion")
290            .cloned()
291            .map(serde_json::from_value)
292            .transpose()
293            .ok()
294            .flatten()
295            .ok_or_else(|| {
296                crate::Error::invalid_params()
297                    .data("initialize.protocolVersion must be a valid ACP protocol version")
298            })?;
299        let requested = crate::schema::ProtocolVersion::V2;
300        if selected == requested {
301            return crate::v2::schema::InitializeResponse::from_json(method, value)
302                .map(|response| Self::Initialized(Box::new(response)));
303        }
304        match parse_v1_selection(selected, value) {
305            Some(response) => Ok(Self::LowerVersion(InitializationVersionMismatch::new(
306                requested,
307                SelectedInitializeResponse::V1(Box::new(response?)),
308            ))),
309            None => Err(crate::Error::invalid_request().data(format!(
310                "unsupported ACP protocol version {selected} in initialize response",
311            ))),
312        }
313    }
314}
315
316/// The request sent by [`send_initialize`](crate::v2::ConnectionTo::send_initialize).
317///
318/// Its pending reply opts into receiving a lower-version response as a
319/// successful [`InitializeOutcome`] instead of the connection's local error.
320#[cfg(feature = "unstable_protocol_v2")]
321#[derive(Debug, Clone)]
322pub(crate) struct InitializeNegotiation(pub(crate) crate::v2::schema::InitializeRequest);
323
324#[cfg(feature = "unstable_protocol_v2")]
325impl crate::JsonRpcMessage for InitializeNegotiation {
326    fn matches_method(method: &str) -> bool {
327        crate::v2::schema::InitializeRequest::matches_method(method)
328    }
329
330    fn method(&self) -> &str {
331        self.0.method()
332    }
333
334    fn to_untyped_message(&self) -> Result<crate::UntypedMessage, crate::Error> {
335        self.0.to_untyped_message()
336    }
337
338    fn parse_message(method: &str, params: &serde_json::Value) -> Result<Self, crate::Error> {
339        crate::v2::schema::InitializeRequest::parse_message(method, params).map(Self)
340    }
341}
342
343#[cfg(feature = "unstable_protocol_v2")]
344impl crate::JsonRpcRequest for InitializeNegotiation {
345    type Response = InitializeOutcome;
346}
347
348mod imp {
349    use std::sync::{Arc, Mutex};
350
351    use crate::RawJsonRpcId;
352    use crate::schema::ProtocolVersion;
353    use crate::{UntypedMessage, role::RemoteStyle};
354
355    #[derive(Clone, Copy, Debug)]
356    pub(crate) enum ProtocolMode {
357        Disabled,
358        Acp(AcpProtocolMode),
359    }
360
361    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
362    pub(crate) struct AcpProtocolMode {
363        api: ProtocolVersionKind,
364        initialize_surface: InitializeSurface,
365        initialization_role: InitializationRole,
366        /// Reject incoming requests other than `initialize` until an
367        /// initialization has completed, without the rest of the peer
368        /// lifecycle. V1 agents with an initialize handler set this; v2
369        /// responders get it from [`InitializationRole::Responder`].
370        requires_initialize: bool,
371    }
372
373    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
374    enum InitializeSurface {
375        Peer,
376        Proxy,
377    }
378
379    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
380    #[cfg_attr(not(feature = "unstable_protocol_v2"), allow(dead_code))]
381    enum InitializationRole {
382        /// Preserve the v1 and proxy initialization behavior. A v2 proxy has
383        /// both an incoming predecessor initialization and an outgoing
384        /// successor initialization, so the peer lifecycle does not apply to
385        /// it.
386        Unchecked,
387        Initiator,
388        Responder,
389    }
390
391    impl AcpProtocolMode {
392        fn is_incoming_initialize_request(self, method: &str) -> bool {
393            match self.initialize_surface {
394                InitializeSurface::Peer => method == "initialize",
395                InitializeSurface::Proxy => method == "proxy/initialize",
396            }
397        }
398
399        fn is_incoming_initialize_response(method: &str) -> bool {
400            // Pending replies retain the logical method from before successor
401            // wrapping, so a proxy's downstream initialize response is also
402            // keyed by `initialize`.
403            method == "initialize"
404        }
405
406        fn is_outgoing_initialize_response(self, method: &str) -> bool {
407            match self.initialize_surface {
408                InitializeSurface::Peer => method == "initialize",
409                InitializeSurface::Proxy => method == "proxy/initialize",
410            }
411        }
412    }
413
414    impl ProtocolMode {
415        pub(crate) fn disabled() -> Self {
416            Self::Disabled
417        }
418
419        pub(crate) fn v1_agent() -> Self {
420            Self::Acp(AcpProtocolMode {
421                api: ProtocolVersionKind::V1,
422                initialize_surface: InitializeSurface::Peer,
423                initialization_role: InitializationRole::Unchecked,
424                requires_initialize: false,
425            })
426        }
427
428        /// Reject incoming requests other than `initialize` until an
429        /// initialization completes. Only applies to v1 peer modes; v2
430        /// responders already enforce the full lifecycle.
431        pub(crate) fn require_initialize(self) -> Self {
432            match self {
433                Self::Acp(mode)
434                    if mode.api == ProtocolVersionKind::V1
435                        && mode.initialize_surface == InitializeSurface::Peer =>
436                {
437                    Self::Acp(AcpProtocolMode {
438                        requires_initialize: true,
439                        ..mode
440                    })
441                }
442                mode => mode,
443            }
444        }
445
446        pub(crate) fn v1_client() -> Self {
447            Self::Acp(AcpProtocolMode {
448                api: ProtocolVersionKind::V1,
449                initialize_surface: InitializeSurface::Peer,
450                initialization_role: InitializationRole::Unchecked,
451                requires_initialize: false,
452            })
453        }
454
455        pub(crate) fn v1_proxy() -> Self {
456            Self::Acp(AcpProtocolMode {
457                api: ProtocolVersionKind::V1,
458                initialize_surface: InitializeSurface::Proxy,
459                initialization_role: InitializationRole::Unchecked,
460                requires_initialize: false,
461            })
462        }
463
464        #[cfg(feature = "unstable_protocol_v2")]
465        pub(crate) fn v2_agent() -> Self {
466            Self::Acp(AcpProtocolMode {
467                api: ProtocolVersionKind::V2,
468                initialize_surface: InitializeSurface::Peer,
469                initialization_role: InitializationRole::Responder,
470                requires_initialize: false,
471            })
472        }
473
474        #[cfg(feature = "unstable_protocol_v2")]
475        pub(crate) fn v2_client() -> Self {
476            Self::Acp(AcpProtocolMode {
477                api: ProtocolVersionKind::V2,
478                initialize_surface: InitializeSurface::Peer,
479                initialization_role: InitializationRole::Initiator,
480                requires_initialize: false,
481            })
482        }
483
484        #[cfg(feature = "unstable_protocol_v2")]
485        pub(crate) fn v2_proxy() -> Self {
486            Self::Acp(AcpProtocolMode {
487                api: ProtocolVersionKind::V2,
488                initialize_surface: InitializeSurface::Proxy,
489                initialization_role: InitializationRole::Unchecked,
490                requires_initialize: false,
491            })
492        }
493
494        pub(crate) fn merge(self, other: Self) -> Self {
495            match (self, other) {
496                (Self::Disabled, other) => other,
497                (this, Self::Disabled) => this,
498                (Self::Acp(this), Self::Acp(other)) => {
499                    assert_eq!(
500                        this.api, other.api,
501                        "cannot merge ACP builders with different API protocol versions; \
502                         handler chains share a single API surface",
503                    );
504                    assert_eq!(
505                        this.initialize_surface, other.initialize_surface,
506                        "cannot merge standard ACP and proxy ACP builders; \
507                         handler chains share one initialization surface",
508                    );
509                    assert_eq!(
510                        this.initialization_role, other.initialization_role,
511                        "cannot merge ACP builders with different initialization roles; \
512                         handler chains share one connection lifecycle",
513                    );
514                    Self::Acp(AcpProtocolMode {
515                        requires_initialize: this.requires_initialize || other.requires_initialize,
516                        ..this
517                    })
518                }
519            }
520        }
521
522        pub(crate) fn api_protocol_version(self) -> Option<ProtocolVersion> {
523            match self {
524                Self::Disabled => None,
525                Self::Acp(mode) => Some(mode.api.as_protocol_version()),
526            }
527        }
528    }
529
530    #[derive(Clone, Debug)]
531    pub(crate) struct ProtocolCompat {
532        mode: Option<AcpProtocolMode>,
533        state: Arc<Mutex<ProtocolState>>,
534    }
535
536    #[derive(Debug)]
537    struct ProtocolState {
538        negotiated: ProtocolVersionKind,
539        pending_initialize: Option<ProtocolVersionKind>,
540        incoming_initialize_id: Option<RawJsonRpcId>,
541        initialization: InitializationState,
542        /// Whether any initialization has completed on this connection.
543        initialized: bool,
544        /// Whether a completed handshake may still be repeated.
545        ///
546        /// A client may repeat `initialize` after the previous one completed
547        /// and before it sends any other request; the latest one is
548        /// authoritative. The first request the client sends closes this
549        /// window for the rest of the connection.
550        repeatable: bool,
551    }
552
553    #[derive(Clone, Copy, Debug, PartialEq, Eq)]
554    enum InitializationState {
555        Unchecked,
556        Uninitialized,
557        Initializing,
558        Ready,
559    }
560
561    /// How an initialize response that passed validation completes the
562    /// handshake.
563    enum InitializeResponseCheck {
564        Negotiated(ProtocolVersionKind),
565        /// A validated lower selection for a `send_initialize` request.
566        #[cfg_attr(not(feature = "unstable_protocol_v2"), allow(dead_code))]
567        LowerVersion,
568    }
569
570    #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
571    enum ProtocolVersionKind {
572        V1,
573        V2,
574    }
575
576    impl ProtocolVersionKind {
577        fn as_protocol_version(self) -> ProtocolVersion {
578            match self {
579                Self::V1 => ProtocolVersion::V1,
580                Self::V2 => ProtocolVersion::from(2_u16),
581            }
582        }
583
584        fn from_protocol_version(version: ProtocolVersion) -> Option<Self> {
585            if version == ProtocolVersion::V1 {
586                Some(Self::V1)
587            } else if version == ProtocolVersion::from(2_u16) {
588                Some(Self::V2)
589            } else {
590                None
591            }
592        }
593    }
594
595    impl ProtocolCompat {
596        pub(crate) fn new(mode: ProtocolMode) -> Self {
597            let mode = match mode {
598                ProtocolMode::Disabled => None,
599                ProtocolMode::Acp(mode) => Some(mode),
600            };
601            let negotiated = mode.map_or(ProtocolVersionKind::V1, |mode| mode.api);
602            let initialization = match mode.map(|mode| mode.initialization_role) {
603                Some(InitializationRole::Initiator | InitializationRole::Responder) => {
604                    InitializationState::Uninitialized
605                }
606                Some(InitializationRole::Unchecked) | None => InitializationState::Unchecked,
607            };
608
609            Self {
610                mode,
611                state: Arc::new(Mutex::new(ProtocolState {
612                    negotiated,
613                    pending_initialize: None,
614                    incoming_initialize_id: None,
615                    initialization,
616                    initialized: false,
617                    repeatable: false,
618                })),
619            }
620        }
621
622        #[cfg(all(test, feature = "unstable_protocol_v2"))]
623        pub(crate) fn incoming_message(
624            &self,
625            message: UntypedMessage,
626        ) -> Result<UntypedMessage, crate::Error> {
627            self.incoming_request(&RawJsonRpcId::Number(0), message)
628        }
629
630        pub(crate) fn incoming_request(
631            &self,
632            id: &RawJsonRpcId,
633            message: UntypedMessage,
634        ) -> Result<UntypedMessage, crate::Error> {
635            let Some(mode) = self.mode else {
636                return Ok(message);
637            };
638
639            // V2 request ids must be strings or integers. The rejection is
640            // still answered with `id: null`, as for any request whose id
641            // cannot be determined.
642            if mode.api == ProtocolVersionKind::V2 && *id == RawJsonRpcId::Null {
643                return Err(crate::jsonrpc::raw_id::null_v2_request_id());
644            }
645
646            if mode.is_incoming_initialize_request(message.method()) {
647                return self.incoming_initialize_request(mode, id, message);
648            }
649            if mode.initialize_surface == InitializeSurface::Proxy
650                && (message.method() == "initialize" || successor_encloses_initialize(&message))
651            {
652                return Err(invalid_proxy_initialize_direction());
653            }
654
655            if mode.requires_initialize && !self.has_initialized() {
656                return Err(initialization_required(message.method()));
657            }
658            self.ensure_initialized(message.method())?;
659            ensure_matching_protocol_version(
660                message.method(),
661                self.active_wire_version(),
662                mode.api,
663            )?;
664            if mode.initialization_role == InitializationRole::Responder {
665                self.close_repeat_window();
666            }
667            Ok(message)
668        }
669
670        pub(crate) fn outgoing_message(
671            &self,
672            mut message: UntypedMessage,
673            remote_style: RemoteStyle,
674        ) -> Result<UntypedMessage, crate::Error> {
675            let Some(mode) = self.mode else {
676                return Ok(message);
677            };
678
679            let wire_version = if let Some(params) =
680                outgoing_initialize_params(mode, remote_style, &mut message)?
681            {
682                prepare_initialize_request(mode, params)?;
683                self.begin_outgoing_initialize(mode)?;
684                mode.api
685            } else {
686                self.ensure_initialized(message.method())?;
687                self.active_wire_version()
688            };
689
690            ensure_matching_protocol_version(message.method(), mode.api, wire_version)?;
691            if mode.initialization_role == InitializationRole::Initiator {
692                self.close_repeat_window();
693            }
694            Ok(message)
695        }
696
697        pub(crate) fn incoming_notification(
698            &self,
699            message: UntypedMessage,
700        ) -> Result<Vec<UntypedMessage>, crate::Error> {
701            let Some(mode) = self.mode else {
702                return Ok(vec![message]);
703            };
704
705            self.ensure_notification_allowed(message.method())?;
706            ensure_matching_protocol_version(
707                message.method(),
708                self.active_wire_version(),
709                mode.api,
710            )?;
711            Ok(vec![message])
712        }
713
714        pub(crate) fn outgoing_notification(
715            &self,
716            message: UntypedMessage,
717        ) -> Result<Vec<UntypedMessage>, crate::Error> {
718            let Some(mode) = self.mode else {
719                return Ok(vec![message]);
720            };
721
722            self.ensure_notification_allowed(message.method())?;
723            ensure_matching_protocol_version(
724                message.method(),
725                mode.api,
726                self.active_wire_version(),
727            )?;
728            Ok(vec![message])
729        }
730
731        /// Check an incoming response against the protocol state.
732        ///
733        /// `accepts_lower_version` marks a pending
734        /// [`super::InitializeNegotiation`], which receives a validated
735        /// lower-version initialize response as a success.
736        pub(crate) fn incoming_response(
737            &self,
738            method: &str,
739            accepts_lower_version: bool,
740            result: Result<serde_json::Value, crate::Error>,
741        ) -> Result<serde_json::Value, crate::Error> {
742            let Some(mode) = self.mode else {
743                return result;
744            };
745
746            if AcpProtocolMode::is_incoming_initialize_response(method) {
747                return self.incoming_initialize_response(mode, accepts_lower_version, result);
748            }
749
750            let value = result?;
751            self.ensure_initialized(method)?;
752            ensure_matching_protocol_version(method, self.active_wire_version(), mode.api)?;
753            Ok(value)
754        }
755
756        #[cfg(all(test, feature = "unstable_protocol_v2"))]
757        pub(crate) fn outgoing_response(
758            &self,
759            method: &str,
760            result: Result<serde_json::Value, crate::Error>,
761        ) -> Result<serde_json::Value, crate::Error> {
762            self.outgoing_response_to(&RawJsonRpcId::Number(0), method, result)
763        }
764
765        pub(crate) fn outgoing_response_to(
766            &self,
767            id: &RawJsonRpcId,
768            method: &str,
769            result: Result<serde_json::Value, crate::Error>,
770        ) -> Result<serde_json::Value, crate::Error> {
771            let Some(mode) = self.mode else {
772                return result;
773            };
774
775            if mode.is_outgoing_initialize_response(method) {
776                match mode.initialization_role {
777                    InitializationRole::Initiator => {
778                        return result.and_then(|_| {
779                            Err(unexpected_initialize_response(mode.initialization_role))
780                        });
781                    }
782                    InitializationRole::Responder if !self.is_pending_incoming_initialize(id) => {
783                        return result.and_then(|_| {
784                            Err(unexpected_initialize_response(mode.initialization_role))
785                        });
786                    }
787                    InitializationRole::Unchecked | InitializationRole::Responder => {}
788                }
789                let mut value = match result {
790                    Ok(value) => value,
791                    Err(error) => {
792                        self.fail_initialize();
793                        return Err(error);
794                    }
795                };
796                let negotiated = self.pending_initialize().or_else(|| {
797                    (mode.initialization_role == InitializationRole::Unchecked).then_some(mode.api)
798                });
799                let negotiated = negotiated
800                    .ok_or_else(|| unexpected_initialize_response(mode.initialization_role))?;
801                if let Err(error) = ensure_matching_protocol_version(method, mode.api, negotiated)
802                    .and_then(|()| prepare_initialize_response(mode, &mut value))
803                {
804                    self.fail_initialize();
805                    return Err(error);
806                }
807                self.complete_initialize(negotiated)?;
808                return Ok(value);
809            }
810
811            let value = result?;
812            self.ensure_initialized(method)?;
813            let wire_version = self.active_wire_version();
814
815            ensure_matching_protocol_version(method, mode.api, wire_version)?;
816            Ok(value)
817        }
818
819        fn incoming_initialize_request(
820            &self,
821            mode: AcpProtocolMode,
822            id: &RawJsonRpcId,
823            mut message: UntypedMessage,
824        ) -> Result<UntypedMessage, crate::Error> {
825            let requested = required_protocol_version_from_value(message.params())?;
826            // A repeated initialize is negotiated like the first one, and an
827            // error returned here leaves the previous initialization in place.
828            //
829            // A proxy negotiates `proxy/initialize` exactly as an agent
830            // negotiates `initialize`. V1 retains its original
831            // fallback-to-latest bootstrap. Only v2 endpoints reject a version
832            // below their supported range, with `-32022`. That includes a
833            // repeat asking a v2 connection for v1: the connection cannot
834            // switch to another version's API, so v2 is the only version it
835            // supports.
836            #[cfg(feature = "unstable_protocol_v2")]
837            if mode.api == ProtocolVersionKind::V2 && requested < mode.api.as_protocol_version() {
838                return Err(crate::v2::schema::Error::unsupported_protocol_version(
839                    requested,
840                    &[mode.api.as_protocol_version()],
841                )
842                .into());
843            }
844            if mode.api == ProtocolVersionKind::V1 && requested > ProtocolVersion::V1 {
845                message.params = serde_json::Value::Object(super::normalize_v1_initialize_request(
846                    message.params(),
847                )?);
848            }
849            // A request for a newer version keeps what parses under v2. An
850            // exact v2 request is validated strictly below.
851            #[cfg(feature = "unstable_protocol_v2")]
852            if mode.api == ProtocolVersionKind::V2 && requested > mode.api.as_protocol_version() {
853                let serde_json::Value::Object(params) = message.params() else {
854                    return Err(invalid_initialize_protocol_version());
855                };
856                message.params = serde_json::Value::Object(
857                    super::normalize_newer_v2_initialize_request(params)?,
858                );
859            }
860
861            prepare_initialize_request(mode, &mut message.params)?;
862            self.begin_incoming_initialize(mode, id)?;
863            Ok(message)
864        }
865
866        fn incoming_initialize_response(
867            &self,
868            mode: AcpProtocolMode,
869            accepts_lower_version: bool,
870            result: Result<serde_json::Value, crate::Error>,
871        ) -> Result<serde_json::Value, crate::Error> {
872            let mut value = match result {
873                Ok(value) => value,
874                Err(error) => {
875                    self.fail_initialize();
876                    return Err(error);
877                }
878            };
879            let response = (|| {
880                let pending = self.pending_initialize().or_else(|| {
881                    (mode.initialization_role == InitializationRole::Unchecked).then_some(mode.api)
882                });
883                let pending = pending
884                    .ok_or_else(|| unexpected_initialize_response(mode.initialization_role))?;
885                let response_version = required_protocol_version_from_value(&value)?;
886                let wire_version = ProtocolVersionKind::from_protocol_version(response_version)
887                    .ok_or_else(|| unsupported_protocol_version(response_version, mode.api))?;
888                // Only a client's own handshake, sent by `send_initialize`,
889                // has a caller that can fall back. A proxy relays its
890                // successor's outcome: it initialized its successor with its
891                // own selected version, and cannot relay a lower one.
892                #[cfg(feature = "unstable_protocol_v2")]
893                if accepts_lower_version
894                    && mode.initialization_role == InitializationRole::Initiator
895                    && wire_version < mode.api
896                    && let Some(response) =
897                        super::parse_v1_selection(wire_version.as_protocol_version(), value.clone())
898                {
899                    response?;
900                    return Ok(InitializeResponseCheck::LowerVersion);
901                }
902                #[cfg(not(feature = "unstable_protocol_v2"))]
903                let _ = accepts_lower_version;
904                if wire_version != mode.api {
905                    return Err(required_protocol_version(mode.api, wire_version));
906                }
907                ensure_matching_protocol_version("initialize", pending, wire_version)?;
908                prepare_initialize_response(mode, &mut value)?;
909                Ok(InitializeResponseCheck::Negotiated(wire_version))
910            })();
911
912            match response {
913                Ok(InitializeResponseCheck::Negotiated(wire_version)) => {
914                    self.complete_initialize(wire_version)?;
915                    Ok(value)
916                }
917                // The caller sees the response, but this connection cannot
918                // use it.
919                Ok(InitializeResponseCheck::LowerVersion) => {
920                    self.fail_initialize();
921                    Ok(value)
922                }
923                Err(error) => {
924                    self.fail_initialize();
925                    Err(error)
926                }
927            }
928        }
929
930        fn begin_incoming_initialize(
931            &self,
932            mode: AcpProtocolMode,
933            id: &RawJsonRpcId,
934        ) -> Result<(), crate::Error> {
935            match mode.initialization_role {
936                InitializationRole::Initiator => return Err(invalid_initialize_direction()),
937                InitializationRole::Unchecked | InitializationRole::Responder => {}
938            }
939            self.begin_initialize(mode.api, Some(id))
940        }
941
942        fn begin_outgoing_initialize(&self, mode: AcpProtocolMode) -> Result<(), crate::Error> {
943            match mode.initialization_role {
944                InitializationRole::Responder => return Err(invalid_initialize_direction()),
945                InitializationRole::Unchecked | InitializationRole::Initiator => {}
946            }
947            self.begin_initialize(mode.api, None)
948        }
949
950        fn begin_initialize(
951            &self,
952            requested: ProtocolVersionKind,
953            incoming_id: Option<&RawJsonRpcId>,
954        ) -> Result<(), crate::Error> {
955            let mut state = self
956                .state
957                .lock()
958                .expect("protocol compatibility state mutex poisoned");
959            match state.initialization {
960                InitializationState::Unchecked => {
961                    state.pending_initialize = Some(requested);
962                    Ok(())
963                }
964                InitializationState::Uninitialized => {
965                    state.initialization = InitializationState::Initializing;
966                    state.pending_initialize = Some(requested);
967                    state.incoming_initialize_id = incoming_id.cloned();
968                    Ok(())
969                }
970                InitializationState::Initializing => Err(crate::Error::invalid_request()
971                    .data("ACP initialization is already in progress on this connection")),
972                // The client may repeat a completed handshake before its first
973                // other request. The repeat replaces the previous one.
974                InitializationState::Ready if state.repeatable => {
975                    state.initialization = InitializationState::Initializing;
976                    state.repeatable = false;
977                    state.pending_initialize = Some(requested);
978                    state.incoming_initialize_id = incoming_id.cloned();
979                    Ok(())
980                }
981                InitializationState::Ready => Err(crate::Error::invalid_request().data(
982                    "ACP initialization cannot be repeated after any other request; reconnect to initialize again",
983                )),
984            }
985        }
986
987        /// Record that the client sent a request other than `initialize`.
988        fn close_repeat_window(&self) {
989            self.state
990                .lock()
991                .expect("protocol compatibility state mutex poisoned")
992                .repeatable = false;
993        }
994
995        fn ensure_initialized(&self, method: &str) -> Result<(), crate::Error> {
996            let state = self
997                .state
998                .lock()
999                .expect("protocol compatibility state mutex poisoned")
1000                .initialization;
1001            match state {
1002                InitializationState::Unchecked | InitializationState::Ready => Ok(()),
1003                InitializationState::Uninitialized | InitializationState::Initializing => {
1004                    Err(initialization_required(method))
1005                }
1006            }
1007        }
1008
1009        fn ensure_notification_allowed(&self, method: &str) -> Result<(), crate::Error> {
1010            let initialization = self
1011                .state
1012                .lock()
1013                .expect("protocol compatibility state mutex poisoned")
1014                .initialization;
1015            if initialization == InitializationState::Initializing && method == "$/cancel_request" {
1016                return Ok(());
1017            }
1018            self.ensure_initialized(method)
1019        }
1020
1021        fn complete_initialize(&self, negotiated: ProtocolVersionKind) -> Result<(), crate::Error> {
1022            let mut state = self
1023                .state
1024                .lock()
1025                .expect("protocol compatibility state mutex poisoned");
1026            if state.pending_initialize.is_none()
1027                && state.initialization != InitializationState::Unchecked
1028            {
1029                return Err(unexpected_initialize_response(
1030                    self.mode
1031                        .expect("protocol initialization requires an ACP mode")
1032                        .initialization_role,
1033                ));
1034            }
1035            if !matches!(
1036                state.initialization,
1037                InitializationState::Unchecked | InitializationState::Initializing
1038            ) {
1039                return Err(unexpected_initialize_response(
1040                    self.mode
1041                        .expect("protocol initialization requires an ACP mode")
1042                        .initialization_role,
1043                ));
1044            }
1045            state.pending_initialize = None;
1046            state.incoming_initialize_id = None;
1047            state.negotiated = negotiated;
1048            state.initialized = true;
1049            if state.initialization == InitializationState::Initializing {
1050                state.initialization = InitializationState::Ready;
1051                state.repeatable = true;
1052            }
1053            Ok(())
1054        }
1055
1056        fn fail_initialize(&self) {
1057            let mut state = self
1058                .state
1059                .lock()
1060                .expect("protocol compatibility state mutex poisoned");
1061            state.pending_initialize = None;
1062            state.incoming_initialize_id = None;
1063            if state.initialization == InitializationState::Initializing {
1064                // A failed repeat keeps the previous initialization in place,
1065                // and the client may repeat again.
1066                if state.initialized {
1067                    state.initialization = InitializationState::Ready;
1068                    state.repeatable = true;
1069                } else {
1070                    state.initialization = InitializationState::Uninitialized;
1071                }
1072            }
1073        }
1074
1075        fn has_initialized(&self) -> bool {
1076            self.state
1077                .lock()
1078                .expect("protocol compatibility state mutex poisoned")
1079                .initialized
1080        }
1081
1082        fn is_pending_incoming_initialize(&self, id: &RawJsonRpcId) -> bool {
1083            self.state
1084                .lock()
1085                .expect("protocol compatibility state mutex poisoned")
1086                .incoming_initialize_id
1087                .as_ref()
1088                == Some(id)
1089        }
1090
1091        fn active_wire_version(&self) -> ProtocolVersionKind {
1092            let state = self
1093                .state
1094                .lock()
1095                .expect("protocol compatibility state mutex poisoned");
1096            state.pending_initialize.unwrap_or(state.negotiated)
1097        }
1098
1099        fn pending_initialize(&self) -> Option<ProtocolVersionKind> {
1100            self.state
1101                .lock()
1102                .expect("protocol compatibility state mutex poisoned")
1103                .pending_initialize
1104        }
1105    }
1106
1107    fn required_protocol_version_from_value(
1108        value: &serde_json::Value,
1109    ) -> Result<ProtocolVersion, crate::Error> {
1110        let Some(version) = value.get("protocolVersion") else {
1111            return Err(invalid_initialize_protocol_version());
1112        };
1113
1114        serde_json::from_value(version.clone()).map_err(|_| invalid_initialize_protocol_version())
1115    }
1116
1117    fn outgoing_initialize_params(
1118        mode: AcpProtocolMode,
1119        remote_style: RemoteStyle,
1120        message: &mut UntypedMessage,
1121    ) -> Result<Option<&mut serde_json::Value>, crate::Error> {
1122        if successor_encloses_initialize(message) {
1123            return Err(invalid_prewrapped_initialize());
1124        }
1125
1126        match mode.initialize_surface {
1127            InitializeSurface::Peer => {
1128                Ok((message.method() == "initialize").then_some(&mut message.params))
1129            }
1130            InitializeSurface::Proxy => {
1131                if message.method() == "initialize" {
1132                    if remote_style != RemoteStyle::Successor {
1133                        return Err(invalid_proxy_initialize_direction());
1134                    }
1135                    return Ok(Some(&mut message.params));
1136                }
1137                if message.method() == "proxy/initialize" {
1138                    return Err(invalid_proxy_initialize_direction());
1139                }
1140                Ok(None)
1141            }
1142        }
1143    }
1144
1145    fn successor_encloses_initialize(message: &UntypedMessage) -> bool {
1146        let mut method = message.method();
1147        let mut params = message.params();
1148        let mut wrapped = false;
1149
1150        while method == "proxy/successor" {
1151            wrapped = true;
1152            let Some(inner_method) = params.get("method").and_then(serde_json::Value::as_str)
1153            else {
1154                return false;
1155            };
1156            method = inner_method;
1157            if method == "proxy/successor" {
1158                let Some(inner_params) = params.get("params") else {
1159                    return false;
1160                };
1161                params = inner_params;
1162            }
1163        }
1164
1165        wrapped && matches!(method, "initialize" | "proxy/initialize")
1166    }
1167
1168    fn invalid_initialize_protocol_version() -> crate::Error {
1169        crate::Error::invalid_params()
1170            .data("initialize.protocolVersion must be a valid ACP protocol version")
1171    }
1172
1173    fn initialization_required(method: &str) -> crate::Error {
1174        crate::Error::invalid_request().data(format!(
1175            "ACP initialization must complete before `{method}` can be used",
1176        ))
1177    }
1178
1179    fn invalid_initialize_direction() -> crate::Error {
1180        crate::Error::invalid_request()
1181            .data("ACP clients send `initialize` requests and ACP agents respond to them")
1182    }
1183
1184    fn unexpected_initialize_response(role: InitializationRole) -> crate::Error {
1185        let detail = match role {
1186            InitializationRole::Initiator => "before an initialize request is pending",
1187            InitializationRole::Responder => "before an initialize request was received",
1188            InitializationRole::Unchecked => "without a pending initialize request",
1189        };
1190        crate::Error::invalid_request().data(format!("received an initialize response {detail}"))
1191    }
1192
1193    fn invalid_proxy_initialize_direction() -> crate::Error {
1194        crate::Error::invalid_request().data(
1195            "proxy initialization must arrive as `proxy/initialize`; outgoing `initialize` must target the successor so the connection can apply `proxy/successor`",
1196        )
1197    }
1198
1199    fn invalid_prewrapped_initialize() -> crate::Error {
1200        crate::Error::invalid_request().data(
1201            "initialize requests must be sent as a logical `initialize` message; `proxy/successor` wrapping is applied by connection routing",
1202        )
1203    }
1204
1205    fn set_protocol_version(
1206        value: &mut serde_json::Value,
1207        version: ProtocolVersionKind,
1208    ) -> Result<(), crate::Error> {
1209        let serde_json::Value::Object(object) = value else {
1210            return Err(invalid_initialize_protocol_version());
1211        };
1212        object.insert(
1213            "protocolVersion".into(),
1214            serde_json::to_value(version.as_protocol_version())
1215                .map_err(crate::Error::into_internal_error)?,
1216        );
1217        Ok(())
1218    }
1219
1220    fn prepare_initialize_request(
1221        mode: AcpProtocolMode,
1222        value: &mut serde_json::Value,
1223    ) -> Result<(), crate::Error> {
1224        set_protocol_version(value, mode.api)?;
1225        #[cfg(feature = "unstable_protocol_v2")]
1226        if mode.initialization_role != InitializationRole::Unchecked {
1227            <crate::v2::schema::InitializeRequest as crate::JsonRpcMessage>::parse_message(
1228                "initialize",
1229                value,
1230            )?;
1231        }
1232        Ok(())
1233    }
1234
1235    fn prepare_initialize_response(
1236        mode: AcpProtocolMode,
1237        value: &mut serde_json::Value,
1238    ) -> Result<(), crate::Error> {
1239        set_protocol_version(value, mode.api)?;
1240        #[cfg(feature = "unstable_protocol_v2")]
1241        if mode.initialization_role != InitializationRole::Unchecked {
1242            <crate::v2::schema::InitializeResponse as crate::JsonRpcResponse>::from_json(
1243                "initialize",
1244                value.clone(),
1245            )?;
1246        }
1247        Ok(())
1248    }
1249
1250    fn ensure_matching_protocol_version(
1251        method: &str,
1252        from: ProtocolVersionKind,
1253        to: ProtocolVersionKind,
1254    ) -> Result<(), crate::Error> {
1255        if from == to {
1256            return Ok(());
1257        }
1258
1259        Err(crate::Error::invalid_request().data(format!(
1260            "ACP protocol translation from {} to {} is not supported for `{method}`; register a handler for the negotiated protocol version",
1261            from.as_protocol_version(),
1262            to.as_protocol_version(),
1263        )))
1264    }
1265
1266    fn unsupported_protocol_version(
1267        version: ProtocolVersion,
1268        supported: ProtocolVersionKind,
1269    ) -> crate::Error {
1270        crate::Error::invalid_request().data(format!(
1271            "unsupported ACP protocol version {version}; this endpoint only supports ACP protocol version {}",
1272            supported.as_protocol_version(),
1273        ))
1274    }
1275
1276    fn required_protocol_version(
1277        required: ProtocolVersionKind,
1278        negotiated: ProtocolVersionKind,
1279    ) -> crate::Error {
1280        crate::Error::invalid_request().data(format!(
1281            "required ACP protocol version {} but peer negotiated {}; use a matching implementation for the negotiated protocol version",
1282            required.as_protocol_version(),
1283            negotiated.as_protocol_version(),
1284        ))
1285    }
1286
1287    #[cfg(all(test, feature = "unstable_protocol_v2"))]
1288    mod tests {
1289        use super::*;
1290        use agent_client_protocol_schema::v2;
1291
1292        fn negotiated(compat: &ProtocolCompat) -> ProtocolVersionKind {
1293            compat
1294                .state
1295                .lock()
1296                .expect("protocol compatibility state mutex poisoned")
1297                .negotiated
1298        }
1299
1300        fn pending_initialize(compat: &ProtocolCompat) -> Option<ProtocolVersionKind> {
1301            compat
1302                .state
1303                .lock()
1304                .expect("protocol compatibility state mutex poisoned")
1305                .pending_initialize
1306        }
1307
1308        fn initialization_state(compat: &ProtocolCompat) -> InitializationState {
1309            compat
1310                .state
1311                .lock()
1312                .expect("protocol compatibility state mutex poisoned")
1313                .initialization
1314        }
1315
1316        fn v2_implementation() -> v2::Implementation {
1317            v2::Implementation::new("protocol-compat-test", env!("CARGO_PKG_VERSION"))
1318        }
1319
1320        fn v2_initialize_request(protocol_version: ProtocolVersion) -> v2::InitializeRequest {
1321            v2::InitializeRequest::new(protocol_version, v2_implementation())
1322        }
1323
1324        fn v2_initialize_response(protocol_version: ProtocolVersion) -> v2::InitializeResponse {
1325            v2::InitializeResponse::new(protocol_version, v2_implementation())
1326        }
1327
1328        #[test]
1329        fn initialize_request_sets_active_wire_version_before_response() -> Result<(), crate::Error>
1330        {
1331            let compat = ProtocolCompat::new(ProtocolMode::v2_agent());
1332            assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1333            assert_eq!(
1334                initialization_state(&compat),
1335                InitializationState::Uninitialized
1336            );
1337
1338            compat.incoming_message(UntypedMessage::new(
1339                "initialize",
1340                v2_initialize_request(ProtocolVersion::V2),
1341            )?)?;
1342
1343            assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1344            assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1345            assert_eq!(
1346                initialization_state(&compat),
1347                InitializationState::Initializing
1348            );
1349
1350            compat.outgoing_response(
1351                "initialize",
1352                Ok(serde_json::to_value(v2_initialize_response(
1353                    ProtocolVersion::V2,
1354                ))?),
1355            )?;
1356
1357            assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1358            assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1359            assert_eq!(initialization_state(&compat), InitializationState::Ready);
1360            Ok(())
1361        }
1362
1363        #[test]
1364        fn outgoing_initialize_sets_active_wire_version_before_response() -> Result<(), crate::Error>
1365        {
1366            let compat = ProtocolCompat::new(ProtocolMode::v2_client());
1367            assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1368            assert_eq!(
1369                initialization_state(&compat),
1370                InitializationState::Uninitialized
1371            );
1372
1373            compat.outgoing_message(
1374                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V1))?,
1375                RemoteStyle::Counterpart,
1376            )?;
1377
1378            assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1379            assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1380            assert_eq!(
1381                initialization_state(&compat),
1382                InitializationState::Initializing
1383            );
1384
1385            compat.incoming_response(
1386                "initialize",
1387                false,
1388                Ok(serde_json::to_value(v2_initialize_response(
1389                    ProtocolVersion::V2,
1390                ))?),
1391            )?;
1392
1393            assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1394            assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1395            assert_eq!(initialization_state(&compat), InitializationState::Ready);
1396            Ok(())
1397        }
1398
1399        #[test]
1400        fn failed_incoming_initialize_response_clears_pending_wire_version()
1401        -> Result<(), crate::Error> {
1402            let compat = ProtocolCompat::new(ProtocolMode::v2_client());
1403            assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1404
1405            compat.outgoing_message(
1406                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V1))?,
1407                RemoteStyle::Counterpart,
1408            )?;
1409
1410            assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1411            assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1412
1413            let result = compat.incoming_response(
1414                "initialize",
1415                false,
1416                Err(crate::Error::invalid_request().data("initialize failed")),
1417            );
1418
1419            assert!(result.is_err());
1420            assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1421            assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1422            assert_eq!(
1423                initialization_state(&compat),
1424                InitializationState::Uninitialized
1425            );
1426            compat.outgoing_message(
1427                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1428                RemoteStyle::Counterpart,
1429            )?;
1430            assert_eq!(
1431                initialization_state(&compat),
1432                InitializationState::Initializing
1433            );
1434            Ok(())
1435        }
1436
1437        #[test]
1438        fn incoming_initialize_response_requires_protocol_version() -> Result<(), crate::Error> {
1439            for value in [
1440                serde_json::json!({}),
1441                serde_json::json!({ "protocolVersion": 100_000 }),
1442            ] {
1443                let compat = ProtocolCompat::new(ProtocolMode::v2_client());
1444                compat.outgoing_message(
1445                    UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V1))?,
1446                    RemoteStyle::Counterpart,
1447                )?;
1448
1449                let error = compat
1450                    .incoming_response("initialize", false, Ok(value))
1451                    .expect_err("initialize responses must declare an ACP protocol version");
1452                let data = error
1453                    .data
1454                    .as_ref()
1455                    .and_then(|data| data.as_str())
1456                    .unwrap_or_default();
1457                assert!(data.contains("protocolVersion"), "{error:?}");
1458                assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
1459                assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1460                assert_eq!(
1461                    initialization_state(&compat),
1462                    InitializationState::Uninitialized
1463                );
1464            }
1465
1466            Ok(())
1467        }
1468
1469        /// Send a v2 client's initialize, then deliver `response` to it.
1470        /// `negotiation` marks the request as sent by `send_initialize`.
1471        fn v2_client_receiving(
1472            negotiation: bool,
1473            response: Result<serde_json::Value, crate::Error>,
1474        ) -> Result<(ProtocolCompat, Result<serde_json::Value, crate::Error>), crate::Error>
1475        {
1476            let compat = ProtocolCompat::new(ProtocolMode::v2_client());
1477            compat.outgoing_message(
1478                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1479                RemoteStyle::Counterpart,
1480            )?;
1481            let result = compat.incoming_response("initialize", negotiation, response);
1482            Ok((compat, result))
1483        }
1484
1485        fn v1_initialize_response() -> crate::v1::schema::InitializeResponse {
1486            crate::v1::schema::InitializeResponse::new(ProtocolVersion::V1)
1487                .agent_info(crate::v1::schema::Implementation::new("v1-agent", "1.0.0"))
1488        }
1489
1490        #[test]
1491        fn plain_initialize_request_rejects_lower_version() -> Result<(), crate::Error> {
1492            let (compat, result) =
1493                v2_client_receiving(false, Ok(serde_json::to_value(v1_initialize_response())?))?;
1494            let error = result.expect_err("send_request keeps the local version guard");
1495            let data = error
1496                .data
1497                .as_ref()
1498                .and_then(|data| data.as_str())
1499                .unwrap_or_default();
1500            assert!(data.contains("peer negotiated 1"), "{error:?}");
1501            assert_eq!(
1502                initialization_state(&compat),
1503                InitializationState::Uninitialized
1504            );
1505            Ok(())
1506        }
1507
1508        #[test]
1509        fn initialize_negotiation_receives_lower_version_as_success() -> Result<(), crate::Error> {
1510            let v1_response = serde_json::to_value(v1_initialize_response())?;
1511            let (compat, result) = v2_client_receiving(true, Ok(v1_response.clone()))?;
1512            assert_eq!(result?, v1_response);
1513
1514            // The connection stays uninitialized rather than switching to v1.
1515            assert_eq!(
1516                initialization_state(&compat),
1517                InitializationState::Uninitialized
1518            );
1519            assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
1520            compat
1521                .outgoing_message(
1522                    UntypedMessage::new("session/new", serde_json::json!({}))?,
1523                    RemoteStyle::Counterpart,
1524                )
1525                .expect_err("v2 traffic still requires a v2 handshake");
1526            compat.outgoing_message(
1527                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1528                RemoteStyle::Counterpart,
1529            )?;
1530            Ok(())
1531        }
1532
1533        #[test]
1534        fn initialize_negotiation_keeps_failures_as_errors() -> Result<(), crate::Error> {
1535            let remote: crate::Error = crate::v2::schema::Error::unsupported_protocol_version(
1536                ProtocolVersion::V2,
1537                &[ProtocolVersion::V1],
1538            )
1539            .into();
1540            let (compat, result) = v2_client_receiving(true, Err(remote.clone()))?;
1541            assert_eq!(result, Err(remote));
1542            assert_eq!(
1543                initialization_state(&compat),
1544                InitializationState::Uninitialized
1545            );
1546
1547            for malformed in [
1548                serde_json::json!({}),
1549                serde_json::json!({ "protocolVersion": "one" }),
1550                serde_json::json!({ "protocolVersion": 0 }),
1551            ] {
1552                let (compat, result) = v2_client_receiving(true, Ok(malformed))?;
1553                result.expect_err("malformed initialize responses are errors");
1554                assert_eq!(
1555                    initialization_state(&compat),
1556                    InitializationState::Uninitialized
1557                );
1558            }
1559            Ok(())
1560        }
1561
1562        #[test]
1563        fn initialize_negotiation_does_not_change_proxies() -> Result<(), crate::Error> {
1564            let compat = ProtocolCompat::new(ProtocolMode::v2_proxy());
1565            compat.outgoing_message(
1566                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1567                RemoteStyle::Successor,
1568            )?;
1569            compat
1570                .incoming_response(
1571                    "initialize",
1572                    true,
1573                    Ok(serde_json::to_value(v1_initialize_response())?),
1574                )
1575                .expect_err("only a client's own handshake can report a lower version");
1576            Ok(())
1577        }
1578
1579        #[test]
1580        fn initialize_outcome_round_trips_by_selected_version() -> Result<(), crate::Error> {
1581            use super::super::{
1582                InitializationVersionMismatch, InitializeOutcome, SelectedInitializeResponse,
1583            };
1584            use crate::JsonRpcResponse as _;
1585
1586            let v2_response = v2_initialize_response(ProtocolVersion::V2);
1587            let wire = serde_json::to_value(&v2_response)?;
1588            let outcome = InitializeOutcome::from_json("initialize", wire.clone())?;
1589            assert_eq!(
1590                outcome,
1591                InitializeOutcome::Initialized(Box::new(v2_response))
1592            );
1593            assert_eq!(outcome.into_json("initialize")?, wire);
1594
1595            let v1_response = v1_initialize_response();
1596            let wire = serde_json::to_value(&v1_response)?;
1597            let outcome = InitializeOutcome::from_json("initialize", wire.clone())?;
1598            assert_eq!(
1599                outcome,
1600                InitializeOutcome::LowerVersion(InitializationVersionMismatch::new(
1601                    ProtocolVersion::V2,
1602                    SelectedInitializeResponse::V1(Box::new(v1_response)),
1603                ))
1604            );
1605            let InitializeOutcome::LowerVersion(mismatch) = &outcome else {
1606                unreachable!();
1607            };
1608            assert_eq!(mismatch.requested, ProtocolVersion::V2);
1609            assert_eq!(mismatch.selected(), ProtocolVersion::V1);
1610            assert_eq!(outcome.into_json("initialize")?, wire);
1611
1612            for value in [
1613                serde_json::json!({}),
1614                serde_json::json!({ "protocolVersion": 3 }),
1615            ] {
1616                InitializeOutcome::from_json("initialize", value)
1617                    .expect_err("only v2 and lower known versions are outcomes");
1618            }
1619            Ok(())
1620        }
1621
1622        #[test]
1623        fn malformed_v2_initialize_requests_do_not_begin_a_handshake() -> Result<(), crate::Error> {
1624            let malformed = serde_json::json!({ "protocolVersion": ProtocolVersion::V2 });
1625
1626            let client = ProtocolCompat::new(ProtocolMode::v2_client());
1627            client
1628                .outgoing_message(
1629                    UntypedMessage::new("initialize", malformed.clone())?,
1630                    RemoteStyle::Counterpart,
1631                )
1632                .expect_err("native v2 clients must send the complete initialize request shape");
1633            assert_eq!(
1634                initialization_state(&client),
1635                InitializationState::Uninitialized
1636            );
1637            client.outgoing_message(
1638                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1639                RemoteStyle::Counterpart,
1640            )?;
1641            assert_eq!(
1642                initialization_state(&client),
1643                InitializationState::Initializing
1644            );
1645
1646            let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
1647            agent
1648                .incoming_message(UntypedMessage::new("initialize", malformed)?)
1649                .expect_err("native v2 agents must receive the complete initialize request shape");
1650            assert_eq!(
1651                initialization_state(&agent),
1652                InitializationState::Uninitialized
1653            );
1654            agent.incoming_message(UntypedMessage::new(
1655                "initialize",
1656                v2_initialize_request(ProtocolVersion::V2),
1657            )?)?;
1658            assert_eq!(
1659                initialization_state(&agent),
1660                InitializationState::Initializing
1661            );
1662            Ok(())
1663        }
1664
1665        #[test]
1666        fn malformed_v2_initialize_success_leaves_client_uninitialized_for_retry()
1667        -> Result<(), crate::Error> {
1668            let compat = ProtocolCompat::new(ProtocolMode::v2_client());
1669            compat.outgoing_message(
1670                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1671                RemoteStyle::Counterpart,
1672            )?;
1673
1674            compat
1675                .incoming_response(
1676                    "initialize",
1677                    false,
1678                    Ok(serde_json::json!({ "protocolVersion": ProtocolVersion::V2 })),
1679                )
1680                .expect_err("initialize success must contain the complete v2 response shape");
1681            assert_eq!(
1682                initialization_state(&compat),
1683                InitializationState::Uninitialized
1684            );
1685            assert_eq!(pending_initialize(&compat), None);
1686
1687            compat.outgoing_message(
1688                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1689                RemoteStyle::Counterpart,
1690            )?;
1691            assert_eq!(
1692                initialization_state(&compat),
1693                InitializationState::Initializing
1694            );
1695            Ok(())
1696        }
1697
1698        #[test]
1699        fn malformed_v2_initialize_success_leaves_agent_uninitialized_for_retry()
1700        -> Result<(), crate::Error> {
1701            let compat = ProtocolCompat::new(ProtocolMode::v2_agent());
1702            compat.incoming_message(UntypedMessage::new(
1703                "initialize",
1704                v2_initialize_request(ProtocolVersion::V2),
1705            )?)?;
1706
1707            compat
1708                .outgoing_response(
1709                    "initialize",
1710                    Ok(serde_json::json!({ "protocolVersion": ProtocolVersion::V2 })),
1711                )
1712                .expect_err("initialize success must contain the complete v2 response shape");
1713            assert_eq!(
1714                initialization_state(&compat),
1715                InitializationState::Uninitialized
1716            );
1717            assert_eq!(pending_initialize(&compat), None);
1718
1719            compat.incoming_message(UntypedMessage::new(
1720                "initialize",
1721                v2_initialize_request(ProtocolVersion::V2),
1722            )?)?;
1723            assert_eq!(
1724                initialization_state(&compat),
1725                InitializationState::Initializing
1726            );
1727            Ok(())
1728        }
1729
1730        #[test]
1731        fn v2_peer_traffic_requires_completed_initialization() -> Result<(), crate::Error> {
1732            for compat in [
1733                ProtocolCompat::new(ProtocolMode::v2_agent()),
1734                ProtocolCompat::new(ProtocolMode::v2_client()),
1735            ] {
1736                for error in [
1737                    compat
1738                        .incoming_message(UntypedMessage::new(
1739                            "session/new",
1740                            serde_json::json!({}),
1741                        )?)
1742                        .expect_err("incoming requests must wait for initialization"),
1743                    compat
1744                        .outgoing_message(
1745                            UntypedMessage::new("session/new", serde_json::json!({}))?,
1746                            RemoteStyle::Counterpart,
1747                        )
1748                        .expect_err("outgoing requests must wait for initialization"),
1749                    compat
1750                        .incoming_notification(UntypedMessage::new(
1751                            "session/update",
1752                            serde_json::json!({}),
1753                        )?)
1754                        .expect_err("incoming notifications must wait for initialization"),
1755                    compat
1756                        .outgoing_notification(UntypedMessage::new(
1757                            "session/update",
1758                            serde_json::json!({}),
1759                        )?)
1760                        .expect_err("outgoing notifications must wait for initialization"),
1761                    compat
1762                        .incoming_response("session/new", false, Ok(serde_json::json!({})))
1763                        .expect_err("incoming responses must wait for initialization"),
1764                    compat
1765                        .outgoing_response("session/new", Ok(serde_json::json!({})))
1766                        .expect_err("outgoing responses must wait for initialization"),
1767                ] {
1768                    let data = error
1769                        .data
1770                        .as_ref()
1771                        .and_then(|data| data.as_str())
1772                        .unwrap_or_default();
1773                    assert!(data.contains("initialization must complete"), "{error:?}");
1774                }
1775            }
1776            Ok(())
1777        }
1778
1779        #[test]
1780        fn v2_initialization_allows_only_protocol_cancellation_notifications()
1781        -> Result<(), crate::Error> {
1782            let client = ProtocolCompat::new(ProtocolMode::v2_client());
1783            client.outgoing_message(
1784                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1785                RemoteStyle::Counterpart,
1786            )?;
1787            client.outgoing_notification(UntypedMessage::new(
1788                "$/cancel_request",
1789                serde_json::json!({ "requestId": 1 }),
1790            )?)?;
1791            client
1792                .outgoing_notification(UntypedMessage::new(
1793                    "session/update",
1794                    serde_json::json!({}),
1795                )?)
1796                .expect_err("ordinary notifications must wait for initialization");
1797
1798            let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
1799            agent.incoming_message(UntypedMessage::new(
1800                "initialize",
1801                v2_initialize_request(ProtocolVersion::V2),
1802            )?)?;
1803            agent.incoming_notification(UntypedMessage::new(
1804                "$/cancel_request",
1805                serde_json::json!({ "requestId": 1 }),
1806            )?)?;
1807            agent
1808                .incoming_notification(UntypedMessage::new(
1809                    "session/update",
1810                    serde_json::json!({}),
1811                )?)
1812                .expect_err("ordinary notifications must wait for initialization");
1813            Ok(())
1814        }
1815
1816        fn error_data(error: &crate::Error) -> &str {
1817            error
1818                .data
1819                .as_ref()
1820                .and_then(|data| data.as_str())
1821                .unwrap_or_default()
1822        }
1823
1824        #[test]
1825        fn v2_peer_initialization_has_one_direction() -> Result<(), crate::Error> {
1826            let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
1827            let error = agent
1828                .outgoing_message(
1829                    UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1830                    RemoteStyle::Counterpart,
1831                )
1832                .expect_err("agents must not initiate initialization");
1833            assert!(
1834                error_data(&error).contains("clients send `initialize`"),
1835                "{error:?}"
1836            );
1837            assert_eq!(
1838                initialization_state(&agent),
1839                InitializationState::Uninitialized
1840            );
1841
1842            let client = ProtocolCompat::new(ProtocolMode::v2_client());
1843            let error = client
1844                .incoming_message(UntypedMessage::new(
1845                    "initialize",
1846                    v2_initialize_request(ProtocolVersion::V2),
1847                )?)
1848                .expect_err("clients must not receive initialization requests");
1849            assert!(
1850                error_data(&error).contains("clients send `initialize`"),
1851                "{error:?}"
1852            );
1853            assert_eq!(
1854                initialization_state(&client),
1855                InitializationState::Uninitialized
1856            );
1857            Ok(())
1858        }
1859
1860        /// Drive an agent through one successful handshake.
1861        fn initialized_v2_agent() -> Result<ProtocolCompat, crate::Error> {
1862            let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
1863            agent.incoming_message(UntypedMessage::new(
1864                "initialize",
1865                v2_initialize_request(ProtocolVersion::V2),
1866            )?)?;
1867            agent.outgoing_response(
1868                "initialize",
1869                Ok(serde_json::to_value(v2_initialize_response(
1870                    ProtocolVersion::V2,
1871                ))?),
1872            )?;
1873            Ok(agent)
1874        }
1875
1876        /// Drive a client through one successful handshake.
1877        fn initialized_v2_client() -> Result<ProtocolCompat, crate::Error> {
1878            let client = ProtocolCompat::new(ProtocolMode::v2_client());
1879            client.outgoing_message(
1880                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
1881                RemoteStyle::Counterpart,
1882            )?;
1883            client.incoming_response(
1884                "initialize",
1885                false,
1886                Ok(serde_json::to_value(v2_initialize_response(
1887                    ProtocolVersion::V2,
1888                ))?),
1889            )?;
1890            Ok(client)
1891        }
1892
1893        #[test]
1894        fn v2_agent_accepts_repeated_initialize_before_other_requests() -> Result<(), crate::Error>
1895        {
1896            let agent = initialized_v2_agent()?;
1897            assert_eq!(initialization_state(&agent), InitializationState::Ready);
1898
1899            // Notifications do not close the window; only requests do.
1900            agent.incoming_notification(UntypedMessage::new(
1901                "$/cancel_request",
1902                serde_json::json!({ "requestId": 1 }),
1903            )?)?;
1904
1905            for _ in 0..2 {
1906                agent.incoming_message(UntypedMessage::new(
1907                    "initialize",
1908                    v2_initialize_request(ProtocolVersion::V2),
1909                )?)?;
1910                assert_eq!(
1911                    initialization_state(&agent),
1912                    InitializationState::Initializing
1913                );
1914                agent
1915                    .incoming_message(UntypedMessage::new("session/new", serde_json::json!({}))?)
1916                    .expect_err("requests must wait for the repeated initialize");
1917                agent.outgoing_response(
1918                    "initialize",
1919                    Ok(serde_json::to_value(v2_initialize_response(
1920                        ProtocolVersion::V2,
1921                    ))?),
1922                )?;
1923                assert_eq!(initialization_state(&agent), InitializationState::Ready);
1924                assert_eq!(negotiated(&agent), ProtocolVersionKind::V2);
1925            }
1926
1927            agent.incoming_message(UntypedMessage::new("session/new", serde_json::json!({}))?)?;
1928            let error = agent
1929                .incoming_message(UntypedMessage::new(
1930                    "initialize",
1931                    v2_initialize_request(ProtocolVersion::V2),
1932                )?)
1933                .expect_err("initialize must not be repeated after another request");
1934            assert_eq!(i32::from(error.code), -32600);
1935            assert!(
1936                error_data(&error).contains("cannot be repeated after any other request"),
1937                "{error:?}"
1938            );
1939            assert_eq!(initialization_state(&agent), InitializationState::Ready);
1940            Ok(())
1941        }
1942
1943        #[test]
1944        fn v2_agent_keeps_window_open_when_a_request_is_rejected() -> Result<(), crate::Error> {
1945            let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
1946            agent.incoming_message(UntypedMessage::new(
1947                "initialize",
1948                v2_initialize_request(ProtocolVersion::V2),
1949            )?)?;
1950            // Rejected while the handshake is in flight, so it does not count.
1951            agent
1952                .incoming_message(UntypedMessage::new("session/new", serde_json::json!({}))?)
1953                .expect_err("requests must wait for initialization");
1954            agent.outgoing_response(
1955                "initialize",
1956                Ok(serde_json::to_value(v2_initialize_response(
1957                    ProtocolVersion::V2,
1958                ))?),
1959            )?;
1960            agent.incoming_message(UntypedMessage::new(
1961                "initialize",
1962                v2_initialize_request(ProtocolVersion::V2),
1963            )?)?;
1964            assert_eq!(
1965                initialization_state(&agent),
1966                InitializationState::Initializing
1967            );
1968            Ok(())
1969        }
1970
1971        #[test]
1972        fn failed_repeated_initialize_keeps_previous_initialization() -> Result<(), crate::Error> {
1973            let agent = initialized_v2_agent()?;
1974            agent.incoming_message(UntypedMessage::new(
1975                "initialize",
1976                v2_initialize_request(ProtocolVersion::V2),
1977            )?)?;
1978            agent
1979                .outgoing_response(
1980                    "initialize",
1981                    Err(crate::Error::invalid_params().data("rejected")),
1982                )
1983                .expect_err("the handler's error is forwarded");
1984            assert_eq!(initialization_state(&agent), InitializationState::Ready);
1985
1986            // A malformed repeat is rejected before it begins.
1987            agent
1988                .incoming_message(UntypedMessage::new(
1989                    "initialize",
1990                    serde_json::json!({ "protocolVersion": 2 }),
1991                )?)
1992                .expect_err("an exact v2 repeat must be a valid v2 request");
1993            assert_eq!(initialization_state(&agent), InitializationState::Ready);
1994
1995            // The client may still repeat.
1996            agent.incoming_message(UntypedMessage::new(
1997                "initialize",
1998                v2_initialize_request(ProtocolVersion::V2),
1999            )?)?;
2000            agent.outgoing_response(
2001                "initialize",
2002                Ok(serde_json::to_value(v2_initialize_response(
2003                    ProtocolVersion::V2,
2004                ))?),
2005            )?;
2006            agent.incoming_message(UntypedMessage::new("session/new", serde_json::json!({}))?)?;
2007            Ok(())
2008        }
2009
2010        #[test]
2011        fn v2_agent_answers_lower_version_repeat_like_a_first_initialize()
2012        -> Result<(), crate::Error> {
2013            let agent = initialized_v2_agent()?;
2014            let error = agent
2015                .incoming_message(UntypedMessage::new(
2016                    "initialize",
2017                    serde_json::json!({ "protocolVersion": 1, "clientCapabilities": {} }),
2018                )?)
2019                .expect_err("a v2 agent supports no version at or below v1");
2020            // Handled like a first initialize: no supported version is at or
2021            // below v1, so the repeat gets -32022 with the supported versions.
2022            assert_eq!(i32::from(error.code), -32022);
2023            assert_eq!(
2024                error.data,
2025                Some(serde_json::json!({ "requested": 1, "supported": [2] }))
2026            );
2027            // The failed repeat leaves the previous initialization in effect.
2028            assert_eq!(initialization_state(&agent), InitializationState::Ready);
2029            assert_eq!(agent.active_wire_version(), ProtocolVersionKind::V2);
2030            agent.incoming_message(UntypedMessage::new(
2031                "initialize",
2032                v2_initialize_request(ProtocolVersion::V2),
2033            )?)?;
2034            Ok(())
2035        }
2036
2037        #[test]
2038        fn v2_client_may_repeat_initialize_before_other_requests() -> Result<(), crate::Error> {
2039            let client = initialized_v2_client()?;
2040            client.outgoing_message(
2041                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2042                RemoteStyle::Counterpart,
2043            )?;
2044            assert_eq!(
2045                initialization_state(&client),
2046                InitializationState::Initializing
2047            );
2048            client.incoming_response(
2049                "initialize",
2050                false,
2051                Ok(serde_json::to_value(v2_initialize_response(
2052                    ProtocolVersion::V2,
2053                ))?),
2054            )?;
2055            assert_eq!(initialization_state(&client), InitializationState::Ready);
2056
2057            // Requests from the agent do not close the client's window.
2058            client.incoming_message(UntypedMessage::new(
2059                "session/request_permission",
2060                serde_json::json!({}),
2061            )?)?;
2062            client.outgoing_message(
2063                UntypedMessage::new("session/new", serde_json::json!({}))?,
2064                RemoteStyle::Counterpart,
2065            )?;
2066            let error = client
2067                .outgoing_message(
2068                    UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2069                    RemoteStyle::Counterpart,
2070                )
2071                .expect_err("initialize must not be repeated after another request");
2072            assert!(
2073                error_data(&error).contains("cannot be repeated after any other request"),
2074                "{error:?}"
2075            );
2076            assert_eq!(initialization_state(&client), InitializationState::Ready);
2077            Ok(())
2078        }
2079
2080        #[test]
2081        fn concurrent_initialize_is_rejected_for_first_and_repeated_handshakes()
2082        -> Result<(), crate::Error> {
2083            for agent in [
2084                ProtocolCompat::new(ProtocolMode::v2_agent()),
2085                initialized_v2_agent()?,
2086            ] {
2087                agent.incoming_request(
2088                    &RawJsonRpcId::Number(1),
2089                    UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2090                )?;
2091                let error = agent
2092                    .incoming_request(
2093                        &RawJsonRpcId::Number(2),
2094                        UntypedMessage::new(
2095                            "initialize",
2096                            v2_initialize_request(ProtocolVersion::V2),
2097                        )?,
2098                    )
2099                    .expect_err("only one initialize may be in flight");
2100                assert_eq!(i32::from(error.code), -32600);
2101                assert!(error_data(&error).contains("in progress"), "{error:?}");
2102            }
2103            Ok(())
2104        }
2105
2106        #[test]
2107        fn v2_connections_reject_null_request_ids() -> Result<(), crate::Error> {
2108            for compat in [
2109                ProtocolCompat::new(ProtocolMode::v2_agent()),
2110                ProtocolCompat::new(ProtocolMode::v2_proxy()),
2111                initialized_v2_agent()?,
2112                initialized_v2_client()?,
2113            ] {
2114                for method in ["initialize", "proxy/initialize", "session/new"] {
2115                    let state = initialization_state(&compat);
2116                    let error = compat
2117                        .incoming_request(
2118                            &RawJsonRpcId::Null,
2119                            UntypedMessage::new(
2120                                method,
2121                                v2_initialize_request(ProtocolVersion::V2),
2122                            )?,
2123                        )
2124                        .expect_err("v2 request ids must not be null");
2125                    assert_eq!(i32::from(error.code), -32600);
2126                    assert!(error_data(&error).contains("not null"), "{error:?}");
2127                    assert_eq!(initialization_state(&compat), state);
2128                    assert_eq!(pending_initialize(&compat), None);
2129                }
2130            }
2131
2132            // V1 keeps accepting null ids.
2133            let v1_agent = ProtocolCompat::new(ProtocolMode::v1_agent());
2134            v1_agent.incoming_request(
2135                &RawJsonRpcId::Null,
2136                UntypedMessage::new(
2137                    "initialize",
2138                    serde_json::json!({ "protocolVersion": 1, "clientCapabilities": {} }),
2139                )?,
2140            )?;
2141            Ok(())
2142        }
2143
2144        #[test]
2145        fn newer_version_initialize_keeps_what_parses_under_v2() -> Result<(), crate::Error> {
2146            let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
2147            let request = agent.incoming_message(UntypedMessage::new(
2148                "initialize",
2149                serde_json::json!({
2150                    "protocolVersion": 3,
2151                    "info": { "name": "future-client" },
2152                    "capabilities": {
2153                        "auth": "malformed",
2154                        "elicitation": {},
2155                        "_futureCapability": { "dropped": true }
2156                    },
2157                    "_meta": "malformed",
2158                    "_futureField": true
2159                }),
2160            )?)?;
2161            let initialize: v2::InitializeRequest =
2162                serde_json::from_value(request.params().clone())?;
2163            assert_eq!(initialize.protocol_version, ProtocolVersion::V2);
2164            assert_eq!(
2165                initialize.info,
2166                v2::Implementation::new("unknown", "unknown")
2167            );
2168            assert_eq!(initialize.capabilities.auth, None);
2169            assert!(initialize.capabilities.elicitation.is_some());
2170            assert_eq!(initialize.meta, None);
2171            assert_eq!(request.params(), &serde_json::to_value(&initialize)?);
2172
2173            // A parsable `info` and `_meta` are kept, and capabilities that
2174            // are not an object are dropped as a whole.
2175            let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
2176            let request = agent.incoming_message(UntypedMessage::new(
2177                "initialize",
2178                serde_json::json!({
2179                    "protocolVersion": 3,
2180                    "info": { "name": "future-client", "version": "3.0.0" },
2181                    "capabilities": [],
2182                    "_meta": { "kept": true }
2183                }),
2184            )?)?;
2185            let initialize: v2::InitializeRequest =
2186                serde_json::from_value(request.params().clone())?;
2187            assert_eq!(
2188                initialize.info,
2189                v2::Implementation::new("future-client", "3.0.0")
2190            );
2191            assert_eq!(initialize.capabilities, v2::ClientCapabilities::new());
2192            assert_eq!(
2193                request.params()["_meta"],
2194                serde_json::json!({ "kept": true })
2195            );
2196            Ok(())
2197        }
2198
2199        #[test]
2200        fn exact_version_initialize_stays_strict() -> Result<(), crate::Error> {
2201            let agent = ProtocolCompat::new(ProtocolMode::v2_agent());
2202            let error = agent
2203                .incoming_message(UntypedMessage::new(
2204                    "initialize",
2205                    serde_json::json!({ "protocolVersion": 2, "info": { "name": "client" } }),
2206                )?)
2207                .expect_err("an exact v2 request must carry a valid `info`");
2208            assert_eq!(i32::from(error.code), -32602);
2209            assert_eq!(
2210                initialization_state(&agent),
2211                InitializationState::Uninitialized
2212            );
2213            Ok(())
2214        }
2215
2216        #[test]
2217        fn v1_downgrade_keeps_what_parses_under_v1() -> Result<(), crate::Error> {
2218            let agent = ProtocolCompat::new(ProtocolMode::v1_agent());
2219            let request = agent.incoming_message(UntypedMessage::new(
2220                "initialize",
2221                serde_json::json!({
2222                    "protocolVersion": 2,
2223                    "info": "malformed",
2224                    "capabilities": { "elicitation": {} },
2225                    "_meta": 7
2226                }),
2227            )?)?;
2228            let initialize: crate::v1::schema::InitializeRequest =
2229                serde_json::from_value(request.params().clone())?;
2230            assert_eq!(initialize.protocol_version, ProtocolVersion::V1);
2231            assert_eq!(initialize.client_info, None);
2232            assert!(initialize.client_capabilities.elicitation.is_some());
2233            assert_eq!(initialize.meta, None);
2234            assert!(request.params().get("clientInfo").is_none());
2235            assert!(request.params().get("_meta").is_none());
2236
2237            let agent = ProtocolCompat::new(ProtocolMode::v1_agent());
2238            let request = agent.incoming_message(UntypedMessage::new(
2239                "initialize",
2240                serde_json::json!({ "protocolVersion": 2 }),
2241            )?)?;
2242            let initialize: crate::v1::schema::InitializeRequest =
2243                serde_json::from_value(request.params().clone())?;
2244            assert_eq!(initialize.client_info, None);
2245            Ok(())
2246        }
2247
2248        #[test]
2249        fn rejected_concurrent_initialize_does_not_clear_the_active_handshake()
2250        -> Result<(), crate::Error> {
2251            let compat = ProtocolCompat::new(ProtocolMode::v2_agent());
2252            let accepted_id = RawJsonRpcId::Number(1);
2253            let rejected_id = RawJsonRpcId::Number(2);
2254
2255            compat.incoming_request(
2256                &accepted_id,
2257                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2258            )?;
2259            let duplicate_error = compat
2260                .incoming_request(
2261                    &rejected_id,
2262                    UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2263                )
2264                .expect_err("a second initialize request must be rejected while one is active");
2265            compat
2266                .outgoing_response_to(&rejected_id, "initialize", Err(duplicate_error))
2267                .expect_err("the rejected initialize receives its own error response");
2268
2269            assert_eq!(
2270                initialization_state(&compat),
2271                InitializationState::Initializing
2272            );
2273            assert_eq!(pending_initialize(&compat), Some(ProtocolVersionKind::V2));
2274
2275            compat.outgoing_response_to(
2276                &accepted_id,
2277                "initialize",
2278                Ok(serde_json::to_value(v2_initialize_response(
2279                    ProtocolVersion::V2,
2280                ))?),
2281            )?;
2282            assert_eq!(initialization_state(&compat), InitializationState::Ready);
2283            Ok(())
2284        }
2285
2286        #[test]
2287        fn rejected_wrong_direction_initialize_does_not_clear_client_handshake()
2288        -> Result<(), crate::Error> {
2289            let compat = ProtocolCompat::new(ProtocolMode::v2_client());
2290            compat.outgoing_message(
2291                UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2292                RemoteStyle::Counterpart,
2293            )?;
2294
2295            let wrong_direction_id = RawJsonRpcId::Number(2);
2296            let wrong_direction_error = compat
2297                .incoming_request(
2298                    &wrong_direction_id,
2299                    UntypedMessage::new("initialize", v2_initialize_request(ProtocolVersion::V2))?,
2300                )
2301                .expect_err("agents must not send initialize requests to clients");
2302            compat
2303                .outgoing_response_to(
2304                    &wrong_direction_id,
2305                    "initialize",
2306                    Err(wrong_direction_error),
2307                )
2308                .expect_err("the wrong-direction initialize receives its own error response");
2309
2310            assert_eq!(
2311                initialization_state(&compat),
2312                InitializationState::Initializing
2313            );
2314            assert_eq!(pending_initialize(&compat), Some(ProtocolVersionKind::V2));
2315
2316            compat.incoming_response(
2317                "initialize",
2318                false,
2319                Ok(serde_json::to_value(v2_initialize_response(
2320                    ProtocolVersion::V2,
2321                ))?),
2322            )?;
2323            assert_eq!(initialization_state(&compat), InitializationState::Ready);
2324            Ok(())
2325        }
2326
2327        #[test]
2328        fn incoming_initialize_request_negotiates_newer_protocol_versions()
2329        -> Result<(), crate::Error> {
2330            for requested in [2_u16, 3, u16::MAX] {
2331                let compat = ProtocolCompat::new(ProtocolMode::v2_agent());
2332                let request = compat.incoming_message(UntypedMessage::new(
2333                    "initialize",
2334                    v2_initialize_request(ProtocolVersion::from(requested)),
2335                )?)?;
2336                assert_eq!(request.params()["protocolVersion"], serde_json::json!(2));
2337                assert_eq!(pending_initialize(&compat), Some(ProtocolVersionKind::V2));
2338
2339                let response = compat.outgoing_response(
2340                    "initialize",
2341                    Ok(serde_json::to_value(v2_initialize_response(
2342                        ProtocolVersion::V2,
2343                    ))?),
2344                )?;
2345                assert_eq!(response["protocolVersion"], serde_json::json!(2));
2346                assert_eq!(initialization_state(&compat), InitializationState::Ready);
2347                assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
2348            }
2349            Ok(())
2350        }
2351
2352        #[test]
2353        fn incoming_initialize_request_rejects_unsupported_protocol_version()
2354        -> Result<(), crate::Error> {
2355            let compat = ProtocolCompat::new(ProtocolMode::v2_agent());
2356            let error = compat
2357                .incoming_message(UntypedMessage::new(
2358                    "initialize",
2359                    serde_json::json!({ "protocolVersion": 1, "clientCapabilities": {} }),
2360                )?)
2361                .expect_err("v2 agents should reject v1 initialization without a v1 handler");
2362            assert_eq!(i32::from(error.code), -32022);
2363            assert_eq!(
2364                error.data,
2365                Some(serde_json::json!({ "requested": 1, "supported": [2] }))
2366            );
2367            assert_eq!(negotiated(&compat), ProtocolVersionKind::V2);
2368            assert_eq!(compat.active_wire_version(), ProtocolVersionKind::V2);
2369            assert_eq!(
2370                initialization_state(&compat),
2371                InitializationState::Uninitialized
2372            );
2373
2374            Ok(())
2375        }
2376
2377        #[test]
2378        fn v1_proxy_negotiates_newer_proxy_initialize_down_to_v1() -> Result<(), crate::Error> {
2379            for requested in [2_u16, 3] {
2380                let compat = ProtocolCompat::new(ProtocolMode::v1_proxy());
2381                let request = compat.incoming_message(UntypedMessage::new(
2382                    "proxy/initialize",
2383                    serde_json::json!({
2384                        "protocolVersion": requested,
2385                        "info": { "name": "future-client", "version": "1.0.0" },
2386                        "capabilities": { "elicitation": {}, "_future": true },
2387                        "_futureField": true
2388                    }),
2389                )?)?;
2390                // The same normalization a v1 agent applies to `initialize`.
2391                let initialize: crate::v1::schema::InitializeRequest =
2392                    serde_json::from_value(request.params().clone())?;
2393                assert_eq!(initialize.protocol_version, ProtocolVersion::V1);
2394                assert_eq!(
2395                    initialize.client_info,
2396                    Some(crate::v1::schema::Implementation::new(
2397                        "future-client",
2398                        "1.0.0"
2399                    ))
2400                );
2401                assert!(initialize.client_capabilities.elicitation.is_some());
2402                assert!(request.params().get("_futureField").is_none());
2403                assert_eq!(pending_initialize(&compat), Some(ProtocolVersionKind::V1));
2404
2405                let response = compat.outgoing_response(
2406                    "proxy/initialize",
2407                    Ok(serde_json::to_value(v1_initialize_response())?),
2408                )?;
2409                assert_eq!(response["protocolVersion"], serde_json::json!(1));
2410            }
2411
2412            // Below v1, a v1 proxy keeps v1's fallback-to-latest rule.
2413            let compat = ProtocolCompat::new(ProtocolMode::v1_proxy());
2414            let request = compat.incoming_message(UntypedMessage::new(
2415                "proxy/initialize",
2416                serde_json::json!({ "protocolVersion": 0 }),
2417            )?)?;
2418            assert_eq!(request.params()["protocolVersion"], serde_json::json!(1));
2419            Ok(())
2420        }
2421
2422        #[test]
2423        fn v2_proxy_negotiates_proxy_initialize_like_a_v2_agent() -> Result<(), crate::Error> {
2424            let compat = ProtocolCompat::new(ProtocolMode::v2_proxy());
2425            let request = compat.incoming_message(UntypedMessage::new(
2426                "proxy/initialize",
2427                serde_json::json!({
2428                    "protocolVersion": 3,
2429                    "info": { "name": "future-client" },
2430                    "capabilities": { "elicitation": {}, "_future": { "dropped": true } },
2431                    "_futureField": true
2432                }),
2433            )?)?;
2434            let initialize: v2::InitializeRequest =
2435                serde_json::from_value(request.params().clone())?;
2436            assert_eq!(initialize.protocol_version, ProtocolVersion::V2);
2437            assert_eq!(
2438                initialize.info,
2439                v2::Implementation::new("unknown", "unknown")
2440            );
2441            assert!(initialize.capabilities.elicitation.is_some());
2442            assert_eq!(request.params(), &serde_json::to_value(&initialize)?);
2443            assert_eq!(pending_initialize(&compat), Some(ProtocolVersionKind::V2));
2444
2445            // A v2 proxy rejects a version below v2 as a v2 agent does.
2446            let compat = ProtocolCompat::new(ProtocolMode::v2_proxy());
2447            let error = compat
2448                .incoming_message(UntypedMessage::new(
2449                    "proxy/initialize",
2450                    serde_json::json!({ "protocolVersion": 1, "clientCapabilities": {} }),
2451                )?)
2452                .expect_err("a v2 proxy supports no version at or below v1");
2453            assert_eq!(i32::from(error.code), -32022);
2454            assert_eq!(
2455                error.data,
2456                Some(serde_json::json!({ "requested": 1, "supported": [2] }))
2457            );
2458            assert_eq!(pending_initialize(&compat), None);
2459            Ok(())
2460        }
2461
2462        #[test]
2463        fn exact_version_proxy_initialize_is_unchanged() -> Result<(), crate::Error> {
2464            let compat = ProtocolCompat::new(ProtocolMode::v1_proxy());
2465            let params = serde_json::json!({
2466                "protocolVersion": 1,
2467                "clientCapabilities": {},
2468                "_futureField": true
2469            });
2470            let request = compat
2471                .incoming_message(UntypedMessage::new("proxy/initialize", params.clone())?)?;
2472            assert_eq!(request.params(), &params);
2473
2474            let compat = ProtocolCompat::new(ProtocolMode::v2_proxy());
2475            let params = serde_json::to_value(v2_initialize_request(ProtocolVersion::V2))?;
2476            let request = compat
2477                .incoming_message(UntypedMessage::new("proxy/initialize", params.clone())?)?;
2478            assert_eq!(request.params(), &params);
2479            Ok(())
2480        }
2481
2482        #[test]
2483        fn proxy_initialize_requests_reject_wrong_directions_and_wrapping()
2484        -> Result<(), crate::Error> {
2485            for mode in [ProtocolMode::v1_proxy(), ProtocolMode::v2_proxy()] {
2486                let compat = ProtocolCompat::new(mode);
2487                for error in [
2488                    compat
2489                        .incoming_message(UntypedMessage::new(
2490                            "initialize",
2491                            serde_json::json!({ "protocolVersion": ProtocolVersion::V2 }),
2492                        )?)
2493                        .expect_err("proxy initialization must arrive through `proxy/initialize`"),
2494                    compat
2495                        .incoming_message(UntypedMessage::new(
2496                            "proxy/successor",
2497                            serde_json::json!({
2498                                "method": "initialize",
2499                                "params": { "protocolVersion": ProtocolVersion::V2 }
2500                            }),
2501                        )?)
2502                        .expect_err("successor traffic must not carry initialization"),
2503                    compat
2504                        .incoming_message(UntypedMessage::new(
2505                            "proxy/successor",
2506                            serde_json::json!({
2507                                "method": "proxy/successor",
2508                                "params": {
2509                                    "method": "proxy/initialize",
2510                                    "params": { "protocolVersion": ProtocolVersion::V2 }
2511                                }
2512                            }),
2513                        )?)
2514                        .expect_err("nested successor traffic must not carry initialization"),
2515                    compat
2516                        .outgoing_message(
2517                            UntypedMessage::new(
2518                                "initialize",
2519                                serde_json::json!({ "protocolVersion": ProtocolVersion::V2 }),
2520                            )?,
2521                            RemoteStyle::Predecessor,
2522                        )
2523                        .expect_err("downstream proxy initialization must use `proxy/successor`"),
2524                    compat
2525                        .outgoing_message(
2526                            UntypedMessage::new(
2527                                "proxy/initialize",
2528                                serde_json::json!({ "protocolVersion": ProtocolVersion::V2 }),
2529                            )?,
2530                            RemoteStyle::Successor,
2531                        )
2532                        .expect_err("a proxy must not send `proxy/initialize` downstream"),
2533                ] {
2534                    let data = error
2535                        .data
2536                        .as_ref()
2537                        .and_then(|data| data.as_str())
2538                        .unwrap_or_default();
2539                    assert!(data.contains("proxy/initialize"), "{error:?}");
2540                    assert!(data.contains("proxy/successor"), "{error:?}");
2541                }
2542                assert_eq!(pending_initialize(&compat), None);
2543            }
2544
2545            Ok(())
2546        }
2547
2548        #[test]
2549        fn outgoing_initialize_rejects_non_object_params() -> Result<(), crate::Error> {
2550            for (compat, message, remote_style) in [
2551                (
2552                    ProtocolCompat::new(ProtocolMode::v2_client()),
2553                    UntypedMessage::new("initialize", serde_json::Value::Null)?,
2554                    RemoteStyle::Counterpart,
2555                ),
2556                (
2557                    ProtocolCompat::new(ProtocolMode::v2_proxy()),
2558                    UntypedMessage::new("initialize", serde_json::Value::Null)?,
2559                    RemoteStyle::Successor,
2560                ),
2561            ] {
2562                let error = compat
2563                    .outgoing_message(message, remote_style)
2564                    .expect_err("initialize params must be an object");
2565                let data = error
2566                    .data
2567                    .as_ref()
2568                    .and_then(|data| data.as_str())
2569                    .unwrap_or_default();
2570                assert!(data.contains("protocolVersion"), "{error:?}");
2571                assert_eq!(pending_initialize(&compat), None);
2572            }
2573
2574            Ok(())
2575        }
2576
2577        #[test]
2578        fn outgoing_initialize_rejects_explicit_successor_wrapping() -> Result<(), crate::Error> {
2579            for message in [
2580                UntypedMessage::new(
2581                    "proxy/successor",
2582                    serde_json::json!({
2583                        "method": "initialize",
2584                        "params": { "protocolVersion": ProtocolVersion::V1 }
2585                    }),
2586                )?,
2587                UntypedMessage::new(
2588                    "proxy/successor",
2589                    serde_json::json!({
2590                        "method": "proxy/successor",
2591                        "params": {
2592                            "method": "initialize",
2593                            "params": { "protocolVersion": ProtocolVersion::V1 }
2594                        }
2595                    }),
2596                )?,
2597            ] {
2598                let compat = ProtocolCompat::new(ProtocolMode::v2_proxy());
2599                let error = compat
2600                    .outgoing_message(message, RemoteStyle::Successor)
2601                    .expect_err("connection routing must own successor wrapping");
2602                let data = error
2603                    .data
2604                    .as_ref()
2605                    .and_then(|data| data.as_str())
2606                    .unwrap_or_default();
2607                assert!(data.contains("logical `initialize`"), "{error:?}");
2608                assert!(data.contains("proxy/successor"), "{error:?}");
2609                assert_eq!(pending_initialize(&compat), None);
2610            }
2611
2612            Ok(())
2613        }
2614
2615        #[test]
2616        fn proxy_initialize_round_trip_uses_the_selected_protocol_version()
2617        -> Result<(), crate::Error> {
2618            for (mode, selected, selected_kind) in [
2619                (
2620                    ProtocolMode::v1_proxy(),
2621                    ProtocolVersion::V1,
2622                    ProtocolVersionKind::V1,
2623                ),
2624                (
2625                    ProtocolMode::v2_proxy(),
2626                    ProtocolVersion::V2,
2627                    ProtocolVersionKind::V2,
2628                ),
2629            ] {
2630                let compat = ProtocolCompat::new(mode);
2631                let request = compat.incoming_message(UntypedMessage::new(
2632                    "proxy/initialize",
2633                    serde_json::json!({ "protocolVersion": selected }),
2634                )?)?;
2635                assert_eq!(
2636                    required_protocol_version_from_value(request.params())?,
2637                    selected
2638                );
2639                assert_eq!(pending_initialize(&compat), Some(selected_kind));
2640
2641                let response = compat.outgoing_response(
2642                    "proxy/initialize",
2643                    Ok(serde_json::json!({ "protocolVersion": selected })),
2644                )?;
2645                assert_eq!(required_protocol_version_from_value(&response)?, selected);
2646                assert_eq!(negotiated(&compat), selected_kind);
2647                assert_eq!(pending_initialize(&compat), None);
2648                assert_eq!(compat.active_wire_version(), selected_kind);
2649            }
2650
2651            Ok(())
2652        }
2653
2654        #[test]
2655        fn proxy_initialize_response_rejects_the_wrong_version_and_clears_pending_state()
2656        -> Result<(), crate::Error> {
2657            for (mode, selected, unsupported, selected_kind) in [
2658                (
2659                    ProtocolMode::v1_proxy(),
2660                    ProtocolVersion::V1,
2661                    ProtocolVersion::V2,
2662                    ProtocolVersionKind::V1,
2663                ),
2664                (
2665                    ProtocolMode::v2_proxy(),
2666                    ProtocolVersion::V2,
2667                    ProtocolVersion::V1,
2668                    ProtocolVersionKind::V2,
2669                ),
2670            ] {
2671                let compat = ProtocolCompat::new(mode);
2672                let request = compat.outgoing_message(
2673                    UntypedMessage::new(
2674                        "initialize",
2675                        serde_json::json!({ "protocolVersion": unsupported }),
2676                    )?,
2677                    RemoteStyle::Successor,
2678                )?;
2679                assert_eq!(
2680                    required_protocol_version_from_value(request.params())?,
2681                    selected
2682                );
2683                assert_eq!(pending_initialize(&compat), Some(selected_kind));
2684
2685                let error = compat
2686                    .incoming_response(
2687                        "initialize",
2688                        false,
2689                        Ok(serde_json::json!({ "protocolVersion": unsupported })),
2690                    )
2691                    .expect_err("proxy initialization must reject a mismatched response version");
2692                let data = error
2693                    .data
2694                    .as_ref()
2695                    .and_then(|data| data.as_str())
2696                    .unwrap_or_default();
2697                assert!(
2698                    data.contains(&format!(
2699                        "required ACP protocol version {selected} but peer negotiated {unsupported}"
2700                    )),
2701                    "{error:?}"
2702                );
2703                assert_eq!(negotiated(&compat), selected_kind);
2704                assert_eq!(pending_initialize(&compat), None);
2705                assert_eq!(compat.active_wire_version(), selected_kind);
2706            }
2707
2708            Ok(())
2709        }
2710
2711        #[test]
2712        #[should_panic(expected = "cannot merge ACP builders with different API protocol versions")]
2713        fn merging_different_api_protocol_modes_panics() {
2714            let _ = ProtocolMode::v1_agent().merge(ProtocolMode::v2_agent());
2715        }
2716
2717        #[test]
2718        #[should_panic(expected = "cannot merge standard ACP and proxy ACP builders")]
2719        fn merging_standard_and_proxy_protocol_modes_panics() {
2720            let _ = ProtocolMode::v1_agent().merge(ProtocolMode::v1_proxy());
2721        }
2722    }
2723}
2724
2725pub(crate) use imp::{ProtocolCompat, ProtocolMode};