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