Skip to main content

agent_client_protocol/
jsonrpc.rs

1//! Core JSON-RPC server support.
2
3use agent_client_protocol_schema::v1::{JsonRpcMessage as VersionedJsonRpcMessage, SessionId};
4
5// Types re-exported from crate root
6use serde::{Deserialize, Serialize};
7use std::any::TypeId;
8use std::collections::HashMap;
9use std::fmt::Debug;
10use std::marker::PhantomData;
11use std::panic::Location;
12use std::pin::pin;
13use std::sync::{
14    Arc, Mutex, Weak,
15    atomic::{AtomicBool, AtomicU8, Ordering},
16};
17use uuid::Uuid;
18
19use futures::FutureExt;
20use futures::channel::{mpsc, oneshot};
21use futures::future::{self, BoxFuture, Either};
22use futures::{AsyncRead, AsyncWrite, StreamExt};
23
24pub(crate) mod close;
25mod dynamic_handler;
26pub(crate) mod handlers;
27mod incoming_actor;
28mod outgoing_actor;
29#[cfg(test)]
30mod prepared_request_tests;
31pub(crate) mod protocol;
32mod protocol_compat;
33mod raw_error;
34pub(crate) mod raw_id;
35pub(crate) mod run;
36mod task_actor;
37mod termination;
38mod transport_actor;
39pub(crate) mod v1_connection;
40#[cfg(feature = "unstable_protocol_v2")]
41pub(crate) mod v2_connection;
42
43use crate::jsonrpc::close::{ChainedClose, CloseCallback};
44pub use crate::jsonrpc::close::{HandleConnectionClose, NullClose};
45use crate::jsonrpc::dynamic_handler::DynamicHandlerMessage;
46pub use crate::jsonrpc::handlers::NullHandler;
47use crate::jsonrpc::handlers::{ChainedHandler, NamedHandler};
48use crate::jsonrpc::handlers::{MessageHandler, NotificationHandler, RequestHandler};
49use crate::jsonrpc::outgoing_actor::{OutgoingMessageTx, send_raw_message};
50use crate::jsonrpc::protocol::HandleId;
51#[cfg(feature = "unstable_protocol_v2")]
52pub use crate::jsonrpc::protocol::V2;
53
54#[cfg(feature = "unstable_mcp_over_acp")]
55use crate::Client;
56pub use crate::jsonrpc::protocol::{Protocol, Raw, V1};
57#[cfg(feature = "unstable_protocol_v2")]
58pub(crate) use crate::jsonrpc::protocol_compat::normalize_newer_v2_initialize_request;
59pub(crate) use crate::jsonrpc::protocol_compat::normalize_v1_initialize_request;
60#[cfg(feature = "unstable_protocol_v2")]
61pub use crate::jsonrpc::protocol_compat::{
62    InitializationVersionMismatch, InitializeOutcome, SelectedInitializeResponse,
63};
64use crate::jsonrpc::protocol_compat::{ProtocolCompat, ProtocolMode};
65pub use crate::jsonrpc::raw_error::{RawJsonRpcError, RawJsonRpcResponse};
66pub use crate::jsonrpc::raw_id::RawJsonRpcId;
67use crate::jsonrpc::run::SpawnedRun;
68use crate::jsonrpc::run::{ChainRun, NullRun, RunWithConnectionTo};
69use crate::jsonrpc::task_actor::{Task, TaskTx};
70pub use crate::jsonrpc::termination::{
71    CONNECTION_TERMINATED_REASON, ConnectionTermination, is_connection_terminated,
72};
73use crate::jsonrpc::termination::{
74    TerminationSource, TerminationSources, connection_terminated_error,
75};
76#[cfg(feature = "unstable_mcp_over_acp")]
77use crate::mcp_server::McpServer;
78use crate::role::{HasPeer, RemoteStyle, Role};
79use crate::{Agent, ConnectTo, RoleId};
80
81/// One valid JSON-RPC message carried inside a [`TransportFrame`].
82///
83/// Raw messages are the same for every ACP protocol version: IDs are
84/// [`RawJsonRpcId`]s, and method params and response errors are not
85/// interpreted at the transport boundary.
86///
87/// Serializing adds the `"jsonrpc": "2.0"` member, and deserializing requires
88/// it. Requests and notifications keep only `id`, `method` and `params`:
89/// other members of the envelope are dropped. Error responses keep unknown
90/// members of the error object in [`RawJsonRpcError::extra`].
91#[derive(Debug, Clone, PartialEq, Eq)]
92pub enum RawJsonRpcMessage {
93    /// A JSON-RPC request with an id and expected response.
94    Request(RawJsonRpcRequest),
95    /// A JSON-RPC notification without a response.
96    Notification(RawJsonRpcNotification),
97    /// A JSON-RPC response to a prior request.
98    Response(RawJsonRpcResponse),
99}
100
101/// A JSON-RPC frame exchanged between protocol components and transports.
102///
103/// A frame is one JSON-RPC wire value. Malformed wire input, including a
104/// JSON-RPC batch array, which the SDK does not support, is represented
105/// explicitly; transport failures are reported by the future that drives the
106/// transport rather than sent through a [`Channel`].
107#[derive(Clone, Debug)]
108#[non_exhaustive]
109pub enum TransportFrame {
110    /// One valid JSON-RPC message.
111    Single(RawJsonRpcMessage),
112    /// One malformed or invalid wire value retained for relays.
113    Malformed {
114        /// The original wire representation.
115        raw: String,
116        /// The JSON-RPC error associated with the malformed value.
117        error: crate::Error,
118    },
119}
120
121pub(crate) fn is_response_only_shape(value: &serde_json::Value) -> bool {
122    value.as_object().is_some_and(|object| {
123        !object.contains_key("method")
124            && (object.contains_key("result") || object.contains_key("error"))
125    })
126}
127
128pub(crate) fn raw_is_response_only_shape(raw: &str) -> bool {
129    serde_json::from_str(raw).is_ok_and(|value| is_response_only_shape(&value))
130}
131
132impl TransportFrame {
133    fn inspect_messages(
134        &self,
135        observer: &mut impl FnMut(&RawJsonRpcMessage) -> Result<(), crate::Error>,
136    ) -> Result<(), crate::Error> {
137        match self {
138            Self::Single(message) => observer(message),
139            Self::Malformed { .. } => Ok(()),
140        }
141    }
142}
143
144/// A JSON-RPC request with uninterpreted params.
145///
146/// This is the request without the `jsonrpc` member, which
147/// [`RawJsonRpcMessage`] adds and checks. Other members of the request object
148/// are not kept: a relay that parses and re-serializes a request drops them.
149#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
150pub struct RawJsonRpcRequest {
151    /// The ID the response must carry.
152    pub id: RawJsonRpcId,
153    /// The method to invoke.
154    pub method: Arc<str>,
155    /// The params, if any. `None` omits the member.
156    #[serde(default, skip_serializing_if = "Option::is_none")]
157    pub params: Option<RawJsonRpcParams>,
158}
159
160/// A JSON-RPC notification with uninterpreted params.
161///
162/// This is the notification without the `jsonrpc` member, which
163/// [`RawJsonRpcMessage`] adds and checks. Other members of the notification
164/// object are not kept: a relay that parses and re-serializes a notification
165/// drops them.
166#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
167pub struct RawJsonRpcNotification {
168    /// The notification method.
169    pub method: Arc<str>,
170    /// The params, if any. `None` omits the member.
171    #[serde(default, skip_serializing_if = "Option::is_none")]
172    pub params: Option<RawJsonRpcParams>,
173}
174
175impl From<RawJsonRpcRequest> for RawJsonRpcMessage {
176    fn from(request: RawJsonRpcRequest) -> Self {
177        Self::Request(request)
178    }
179}
180
181impl From<RawJsonRpcNotification> for RawJsonRpcMessage {
182    fn from(notification: RawJsonRpcNotification) -> Self {
183        Self::Notification(notification)
184    }
185}
186
187impl From<RawJsonRpcResponse> for RawJsonRpcMessage {
188    fn from(response: RawJsonRpcResponse) -> Self {
189        Self::Response(response)
190    }
191}
192
193/// Raw JSON-RPC request or notification parameters.
194///
195/// JSON-RPC params, when present, must be either an array or an object.
196#[derive(Debug, Clone, PartialEq, Eq)]
197pub enum RawJsonRpcParams {
198    /// Positional JSON-RPC params.
199    Array(Vec<serde_json::Value>),
200    /// Named JSON-RPC params.
201    Object(serde_json::Map<String, serde_json::Value>),
202}
203
204impl RawJsonRpcParams {
205    /// Convert a JSON value into JSON-RPC params. JSON `null` means no params.
206    ///
207    /// # Errors
208    ///
209    /// Returns Invalid params (`-32602`) for strings, numbers, and booleans.
210    pub fn from_value(value: serde_json::Value) -> Result<Option<Self>, crate::Error> {
211        match value {
212            serde_json::Value::Null => Ok(None),
213            serde_json::Value::Array(array) => Ok(Some(Self::Array(array))),
214            serde_json::Value::Object(object) => Ok(Some(Self::Object(object))),
215            _ => {
216                Err(crate::Error::invalid_params()
217                    .data("JSON-RPC params must be an object or array"))
218            }
219        }
220    }
221
222    /// Convert params back into a JSON value.
223    #[must_use]
224    pub fn into_value(self) -> serde_json::Value {
225        match self {
226            Self::Array(array) => serde_json::Value::Array(array),
227            Self::Object(object) => serde_json::Value::Object(object),
228        }
229    }
230}
231
232impl Serialize for RawJsonRpcParams {
233    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
234    where
235        S: serde::Serializer,
236    {
237        match self {
238            Self::Array(array) => array.serialize(serializer),
239            Self::Object(object) => object.serialize(serializer),
240        }
241    }
242}
243
244impl<'de> Deserialize<'de> for RawJsonRpcParams {
245    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
246    where
247        D: serde::Deserializer<'de>,
248    {
249        let value = serde_json::Value::deserialize(deserializer)?;
250        match value {
251            serde_json::Value::Array(array) => Ok(Self::Array(array)),
252            serde_json::Value::Object(object) => Ok(Self::Object(object)),
253            _ => Err(serde::de::Error::custom(
254                "JSON-RPC params must be an object or array",
255            )),
256        }
257    }
258}
259
260impl RawJsonRpcMessage {
261    /// Build a raw JSON-RPC request message.
262    ///
263    /// # Errors
264    ///
265    /// Returns Invalid params (`-32602`) if `params` is not an object, an array, or `null`.
266    pub fn request(
267        method: String,
268        params: serde_json::Value,
269        id: impl Into<RawJsonRpcId>,
270    ) -> Result<Self, crate::Error> {
271        Ok(Self::Request(RawJsonRpcRequest {
272            id: id.into(),
273            method: Arc::from(method),
274            params: RawJsonRpcParams::from_value(params)?,
275        }))
276    }
277
278    /// Build a raw JSON-RPC notification message.
279    ///
280    /// # Errors
281    ///
282    /// Returns Invalid params (`-32602`) if `params` is not an object, an array, or `null`.
283    pub fn notification(method: String, params: serde_json::Value) -> Result<Self, crate::Error> {
284        Ok(Self::Notification(RawJsonRpcNotification {
285            method: Arc::from(method),
286            params: RawJsonRpcParams::from_value(params)?,
287        }))
288    }
289
290    /// Build a JSON-RPC response from an ACP result.
291    ///
292    /// For other protocols, construct [`RawJsonRpcResponse`] directly so error
293    /// codes and fields are not interpreted as ACP.
294    #[must_use]
295    pub fn response(
296        id: impl Into<RawJsonRpcId>,
297        response: Result<serde_json::Value, crate::Error>,
298    ) -> Self {
299        Self::Response(RawJsonRpcResponse::new(
300            id,
301            response.map_err(|error| Box::new(error.into())),
302        ))
303    }
304
305    /// The response id, if this is a response.
306    #[must_use]
307    pub fn response_id(&self) -> Option<&RawJsonRpcId> {
308        match self {
309            Self::Response(
310                RawJsonRpcResponse::Result { id, .. } | RawJsonRpcResponse::Error { id, .. },
311            ) => Some(id),
312            Self::Request(_) | Self::Notification(_) => None,
313        }
314    }
315}
316
317impl Serialize for RawJsonRpcMessage {
318    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
319    where
320        S: serde::Serializer,
321    {
322        match self {
323            Self::Request(request) => {
324                VersionedJsonRpcMessage::wrap(request.clone()).serialize(serializer)
325            }
326            Self::Notification(notification) => {
327                VersionedJsonRpcMessage::wrap(notification.clone()).serialize(serializer)
328            }
329            Self::Response(response) => {
330                VersionedJsonRpcMessage::wrap(response.clone()).serialize(serializer)
331            }
332        }
333    }
334}
335
336impl<'de> Deserialize<'de> for RawJsonRpcMessage {
337    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
338    where
339        D: serde::Deserializer<'de>,
340    {
341        let value = serde_json::Value::deserialize(deserializer)?;
342        let Some(object) = value.as_object() else {
343            return Err(serde::de::Error::custom("invalid JSON-RPC message"));
344        };
345
346        let has_method = object.contains_key("method");
347        let has_id = object.contains_key("id");
348        let has_result = object.contains_key("result");
349        let has_error = object.contains_key("error");
350
351        if has_method && !has_result && !has_error {
352            if has_id {
353                let request =
354                    serde_json::from_value::<VersionedJsonRpcMessage<RawJsonRpcRequest>>(value)
355                        .map_err(serde::de::Error::custom)?
356                        .into_inner();
357                Ok(Self::Request(request))
358            } else {
359                let notification = serde_json::from_value::<
360                    VersionedJsonRpcMessage<RawJsonRpcNotification>,
361                >(value)
362                .map_err(serde::de::Error::custom)?
363                .into_inner();
364                Ok(Self::Notification(notification))
365            }
366        } else if !has_method && has_id && has_result != has_error {
367            let response =
368                serde_json::from_value::<VersionedJsonRpcMessage<RawJsonRpcResponse>>(value)
369                    .map_err(serde::de::Error::custom)?
370                    .into_inner();
371            Ok(Self::Response(response))
372        } else {
373            Err(serde::de::Error::custom("invalid JSON-RPC message"))
374        }
375    }
376}
377
378fn params_from_transport(params: Option<RawJsonRpcParams>) -> serde_json::Value {
379    params.map_or(serde_json::Value::Null, RawJsonRpcParams::into_value)
380}
381
382/// Handlers process incoming JSON-RPC messages on a connection.
383///
384/// When messages arrive, they flow through a chain of handlers. Each handler can
385/// either **claim** the message (handle it) or **decline** it (pass to the next handler).
386///
387/// # Message Flow
388///
389/// Messages flow through three layers of handlers in order:
390///
391/// ```text
392/// ┌─────────────────────────────────────────────────────────────────┐
393/// │                     Incoming Message                            │
394/// └─────────────────────────────────────────────────────────────────┘
395///                              │
396///                              ▼
397/// ┌─────────────────────────────────────────────────────────────────┐
398/// │  1. User Handlers (registered via on_receive_request, etc.)     │
399/// │     - Tried in registration order                               │
400/// │     - First handler to return Handled::Yes claims the message   │
401/// └─────────────────────────────────────────────────────────────────┘
402///                              │ Handled::No
403///                              ▼
404/// ┌─────────────────────────────────────────────────────────────────┐
405/// │  2. Dynamic Handlers (added at runtime)                         │
406/// │     - Used for session-specific message handling                │
407/// │     - Added via ConnectionTo::add_dynamic_handler             │
408/// └─────────────────────────────────────────────────────────────────┘
409///                              │ Handled::No
410///                              ▼
411/// ┌─────────────────────────────────────────────────────────────────┐
412/// │  3. Role Default Handler                                        │
413/// │     - Fallback based on the connection's Role                   │
414/// │     - Handles protocol-level messages (e.g., proxy forwarding)  │
415/// └─────────────────────────────────────────────────────────────────┘
416///                              │ Handled::No
417///                              ▼
418/// ┌─────────────────────────────────────────────────────────────────┐
419/// │  Unhandled: requests error, notifications ignored               │
420/// └─────────────────────────────────────────────────────────────────┘
421/// ```
422///
423/// # The `Handled` Return Value
424///
425/// Each handler returns [`Handled`] to indicate whether it processed the message:
426///
427/// - **`Handled::Yes`** - Message was handled. No further handlers are invoked.
428/// - **`Handled::No { message, retry }`** - Message was not handled. The message
429///   (possibly modified) is passed to the next handler in the chain.
430///
431/// For convenience, handlers can return `()` which is equivalent to `Handled::Yes`.
432///
433/// # The Retry Mechanism
434///
435/// The `retry` flag in `Handled::No` controls what happens when no handler claims a message:
436///
437/// - **`retry: false`** (default) - Send a "method not found" error
438///   response immediately for requests, or ignore notifications.
439/// - **`retry: true`** - Queue the message and retry it when new dynamic handlers are added.
440///
441/// This mechanism exists because of a timing issue with sessions: when a `session/new`
442/// response is being processed, the dynamic handler for that session hasn't been registered
443/// yet, but `session/update` notifications for that session may already be arriving.
444/// By setting `retry: true`, these early notifications are queued until the session's
445/// dynamic handler is added.
446///
447/// The queue holds at most 1024 messages per connection. Queuing one more gives up on the
448/// oldest: a request gets the "method not found" error, a notification is dropped with a
449/// log, and a response goes to its awaiter.
450///
451/// On v1 and unguarded connections, a client's role also retries unhandled messages from
452/// the agent that carry a `sessionId`. Its notifications are queued as above. Its requests
453/// are queued only while a dropped dynamic handler's removal is still pending, which covers
454/// a session handler being replaced, and are answered with "method not found" once no such
455/// removal is left. Any other unhandled session request is answered right away, so the
456/// agent never waits for a handler that nobody registers.
457///
458/// # Handler Registration
459///
460/// Most users register handlers using the builder methods on [`Builder`]:
461///
462/// ```
463/// # use agent_client_protocol::{Agent, Client, ConnectTo};
464/// # use agent_client_protocol::v1::schema::{AgentCapabilities, InitializeRequest, InitializeResponse};
465/// # use agent_client_protocol_test::StatusUpdate;
466/// # async fn example(transport: impl ConnectTo<Agent>) -> Result<(), agent_client_protocol::Error> {
467/// Agent.v1()
468///     .on_receive_request(async |req: InitializeRequest, responder, cx| {
469///         responder.respond(
470///             InitializeResponse::new(req.protocol_version)
471///                 .agent_capabilities(AgentCapabilities::new()),
472///         )
473///     }, agent_client_protocol::on_receive_request!())
474///     .on_receive_notification(async |notif: StatusUpdate, cx| {
475///         // Process notification
476///         Ok(())
477///     }, agent_client_protocol::on_receive_notification!())
478///     .connect_to(transport)
479///     .await?;
480/// # Ok(())
481/// # }
482/// ```
483///
484/// The type parameter on the closure determines which messages are dispatched to it.
485/// Messages that don't match the type are automatically passed to the next handler.
486///
487/// # Implementing Custom Handlers
488///
489/// For advanced use cases, you can implement [`HandleDispatchFrom`] directly:
490///
491/// ```no_run
492/// use agent_client_protocol::{
493///     Client, ConnectionTo, Dispatch, Error, HandleDispatchFrom, Handled,
494/// };
495///
496/// struct MyHandler;
497///
498/// impl HandleDispatchFrom<Client> for MyHandler {
499///     async fn handle_dispatch_from(
500///         &mut self,
501///         message: Dispatch,
502///         _connection: ConnectionTo<Client>,
503///     ) -> Result<Handled<Dispatch>, Error> {
504///         if message.method() == "my/custom/method" {
505///             // Handle it
506///             Ok(Handled::Yes)
507///         } else {
508///             // Pass to next handler
509///             Ok(Handled::No { message, retry: false })
510///         }
511///     }
512///
513///     fn describe_chain(&self) -> impl std::fmt::Debug {
514///         "MyHandler"
515///     }
516/// }
517/// ```
518///
519/// # Important: Handlers Must Not Block
520///
521/// The connection processes messages on a single async task. While a handler is running,
522/// no other messages can be processed. For expensive operations, use [`ConnectionTo::spawn`]
523/// to run work concurrently:
524///
525/// ```
526/// # use agent_client_protocol::{Client, Agent, ConnectTo};
527/// # use agent_client_protocol_test::{expensive_operation, ProcessComplete};
528/// # async fn example(transport: impl ConnectTo<Client>) -> Result<(), agent_client_protocol::Error> {
529/// # Client.v1().connect_with(transport, async |cx| {
530/// cx.spawn({
531///     let connection = cx.clone();
532///     async move {
533///         let result = expensive_operation("data").await?;
534///         connection.send_notification(ProcessComplete { result })?;
535///         Ok(())
536///     }
537/// })?;
538/// # Ok(())
539/// # }).await?;
540/// # Ok(())
541/// # }
542/// ```
543#[allow(async_fn_in_trait)]
544/// A handler for incoming JSON-RPC messages.
545///
546/// This trait is implemented by types that can process incoming messages on a connection.
547/// Handlers are registered with a [`Builder`] and are called in order until
548/// one claims the message.
549///
550/// The type parameter is the counterpart role that messages arrive from and
551/// that the supplied [`ConnectionTo`] addresses. An agent handler therefore
552/// implements `HandleDispatchFrom<Client>`, while a client handler implements
553/// `HandleDispatchFrom<Agent>`.
554pub trait HandleDispatchFrom<Counterpart: Role>: Send {
555    /// Attempt to claim an incoming dispatch (request, notification, or response).
556    ///
557    /// # Important: do not block
558    ///
559    /// The server will not process new messages until this handler returns.
560    /// You should avoid blocking in this callback unless you wish to block the server (e.g., for rate limiting).
561    /// The recommended approach to manage expensive operations is to the [`ConnectionTo::spawn`] method available on the message context.
562    ///
563    /// # Parameters
564    ///
565    /// * `message` - The incoming message to handle.
566    /// * `connection` - The connection, used to send messages and access connection state.
567    ///
568    /// # Returns
569    ///
570    /// * `Ok(Handled::Yes)` if the message was claimed. It will not be propagated further.
571    /// * `Ok(Handled::No(message))` if not; the (possibly changed) message will be passed to the remaining handlers.
572    /// * `Err` if processing fails. Requests receive an Error Response, response
573    ///   errors are routed to the local request awaiter, and notification errors
574    ///   are logged without a wire reply.
575    fn handle_dispatch_from(
576        &mut self,
577        message: Dispatch,
578        connection: ConnectionTo<Counterpart>,
579    ) -> impl Future<Output = Result<Handled<Dispatch>, crate::Error>> + Send;
580
581    /// Returns a debug description of the registered handlers for diagnostics.
582    fn describe_chain(&self) -> impl std::fmt::Debug;
583}
584
585impl<Counterpart: Role, H> HandleDispatchFrom<Counterpart> for &mut H
586where
587    H: HandleDispatchFrom<Counterpart>,
588{
589    fn handle_dispatch_from(
590        &mut self,
591        message: Dispatch,
592        cx: ConnectionTo<Counterpart>,
593    ) -> impl Future<Output = Result<Handled<Dispatch>, crate::Error>> + Send {
594        H::handle_dispatch_from(self, message, cx)
595    }
596
597    fn describe_chain(&self) -> impl std::fmt::Debug {
598        H::describe_chain(self)
599    }
600}
601
602/// A JSON-RPC connection that can act as either a server, client, or both.
603///
604/// [`Builder`] provides a builder-style API for creating JSON-RPC servers and clients.
605/// You start with a versioned entry point such as `Client.v1()` or `Client.v2()`, then add message
606/// handlers, and finally drive the connection with either [`connect_to`](Builder::connect_to)
607/// or [`connect_with`](Builder::connect_with), providing a component implementation
608/// (e.g., [`ByteStreams`] for byte streams).
609///
610/// # JSON-RPC Primer
611///
612/// JSON-RPC 2.0 has two fundamental message types:
613///
614/// * **Requests** - Messages that expect a response. They have an `id` field that gets
615///   echoed back in the response so the sender can correlate them.
616/// * **Notifications** - Fire-and-forget messages with no `id` field. The sender doesn't
617///   expect or receive a response.
618///
619/// # Type-Driven Message Dispatch
620///
621/// The handler registration methods use Rust's type system to determine which messages
622/// to handle. The type parameter you provide controls what gets dispatched to your handler:
623///
624/// ## Single Message Types
625///
626/// The simplest case - handle one specific message type:
627///
628/// ```no_run
629/// # use agent_client_protocol_test::*;
630/// # use agent_client_protocol::v1::schema::{InitializeRequest, InitializeResponse, SessionNotification};
631/// # async fn example() -> Result<(), agent_client_protocol::Error> {
632/// # let connection = mock_connection();
633/// connection
634///     .on_receive_request(async |req: InitializeRequest, responder, cx| {
635///         // Handle only InitializeRequest messages
636///         responder.respond(InitializeResponse::make())
637///     }, agent_client_protocol::on_receive_request!())
638///     .on_receive_notification(async |notif: SessionNotification, cx| {
639///         // Handle only SessionUpdate notifications
640///         Ok(())
641///     }, agent_client_protocol::on_receive_notification!())
642/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
643/// # Ok(())
644/// # }
645/// ```
646///
647/// ## Enum Message Types
648///
649/// You can also handle multiple related messages with a single handler by defining an enum
650/// that implements the appropriate trait ([`JsonRpcRequest`] or [`JsonRpcNotification`]):
651///
652/// ```no_run
653/// # use agent_client_protocol_test::*;
654/// # use agent_client_protocol::{JsonRpcRequest, JsonRpcMessage, UntypedMessage};
655/// # use agent_client_protocol::v1::schema::{InitializeRequest, InitializeResponse, PromptRequest, PromptResponse};
656/// # async fn example() -> Result<(), agent_client_protocol::Error> {
657/// # let connection = mock_connection();
658/// // Define an enum for multiple request types
659/// #[derive(Debug, Clone)]
660/// enum MyRequests {
661///     Initialize(InitializeRequest),
662///     Prompt(PromptRequest),
663/// }
664///
665/// // Implement JsonRpcRequest for your enum
666/// # impl JsonRpcMessage for MyRequests {
667/// #     fn matches_method(_method: &str) -> bool { false }
668/// #     fn method(&self) -> &str { "myRequests" }
669/// #     fn to_untyped_message(&self) -> Result<UntypedMessage, agent_client_protocol::Error> { todo!() }
670/// #     fn parse_message(_method: &str, _params: &serde_json::Value) -> Result<Self, agent_client_protocol::Error> { Err(agent_client_protocol::Error::method_not_found()) }
671/// # }
672/// impl JsonRpcRequest for MyRequests { type Response = serde_json::Value; }
673///
674/// // Handle all variants in one place
675/// connection.on_receive_request(async |req: MyRequests, responder, cx| {
676///     match req {
677///         MyRequests::Initialize(init) => { responder.respond(serde_json::json!({})) }
678///         MyRequests::Prompt(prompt) => { responder.respond(serde_json::json!({})) }
679///     }
680/// }, agent_client_protocol::on_receive_request!())
681/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
682/// # Ok(())
683/// # }
684/// ```
685///
686/// ## Mixed Message Types
687///
688/// To handle requests, notifications, and responses in one callback, use
689/// [`on_receive_dispatch`](Self::on_receive_dispatch):
690///
691/// ```no_run
692/// # use agent_client_protocol_test::*;
693/// # use agent_client_protocol::v1::Dispatch;
694/// # use agent_client_protocol::v1::schema::{InitializeRequest, InitializeResponse, SessionNotification};
695/// # async fn example() -> Result<(), agent_client_protocol::Error> {
696/// # let connection = mock_connection();
697/// // on_receive_dispatch receives requests, notifications, and responses
698/// connection.on_receive_dispatch(async |msg: Dispatch<InitializeRequest, SessionNotification>, _cx| {
699///     match msg {
700///         Dispatch::Request(req, responder) => {
701///             responder.respond(InitializeResponse::make())
702///         }
703///         Dispatch::Notification(notif) => {
704///             Ok(())
705///         }
706///         Dispatch::Response(result, router) => {
707///             // Forward response to its destination
708///             router.route_with_result(result)
709///         }
710///     }
711/// }, agent_client_protocol::on_receive_dispatch!())
712/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
713/// # Ok(())
714/// # }
715/// ```
716///
717/// # Handler Registration
718///
719/// Register handlers using these methods (listed from most common to most flexible):
720///
721/// * [`on_receive_request`](Self::on_receive_request) - Handle JSON-RPC requests (messages expecting responses)
722/// * [`on_receive_notification`](Self::on_receive_notification) - Handle JSON-RPC notifications (fire-and-forget)
723/// * [`on_receive_dispatch`](Self::on_receive_dispatch) - Handle requests, notifications, and responses in one callback
724/// * [`with_handler`](Self::with_handler) - Low-level primitive for maximum flexibility
725///
726/// ## Handler Ordering
727///
728/// Handlers are tried in the order you register them. The first handler that claims a message
729/// (by matching its type) will process it. Subsequent handlers won't see that message:
730///
731/// ```no_run
732/// # use agent_client_protocol_test::*;
733/// # use agent_client_protocol::v1::schema::{InitializeRequest, InitializeResponse, PromptRequest, PromptResponse};
734/// # async fn example() -> Result<(), agent_client_protocol::Error> {
735/// # let connection = mock_connection();
736/// connection
737///     .on_receive_request(async |req: InitializeRequest, responder, cx| {
738///         // This runs first for InitializeRequest
739///         responder.respond(InitializeResponse::make())
740///     }, agent_client_protocol::on_receive_request!())
741///     .on_receive_request(async |req: PromptRequest, responder, cx| {
742///         // This runs first for PromptRequest
743///         responder.respond(PromptResponse::make())
744///     }, agent_client_protocol::on_receive_request!())
745///     // Unknown requests receive Method not found automatically; unhandled
746///     // notifications are ignored.
747/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
748/// # Ok(())
749/// # }
750/// ```
751///
752/// # Event Loop and Concurrency
753///
754/// Understanding the event loop is critical for writing correct handlers.
755///
756/// ## The Event Loop
757///
758/// [`Builder`] runs all handler callbacks on a single async task - the event loop.
759/// While a handler is running, **the server cannot receive new messages**. This means
760/// any blocking or expensive work in your handlers will stall the entire connection.
761///
762/// To avoid blocking the event loop, use [`ConnectionTo::spawn`] to offload serious
763/// work to concurrent tasks:
764///
765/// ```no_run
766/// # use agent_client_protocol_test::*;
767/// # async fn example() -> Result<(), agent_client_protocol::Error> {
768/// # let connection = mock_connection();
769/// connection.on_receive_request(async |req: AnalyzeRequest, responder, cx| {
770///     // Clone cx for the spawned task
771///     cx.spawn({
772///         let connection = cx.clone();
773///         async move {
774///             let result = expensive_analysis(&req.data).await?;
775///             connection.send_notification(AnalysisComplete { result })?;
776///             Ok(())
777///         }
778///     })?;
779///
780///     // Respond immediately without blocking
781///     responder.respond(AnalysisStarted { job_id: 42 })
782/// }, agent_client_protocol::on_receive_request!())
783/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
784/// # Ok(())
785/// # }
786/// ```
787///
788/// Note that the entire connection runs within one async task, so parallelism must be
789/// managed explicitly using [`spawn`](ConnectionTo::spawn).
790///
791/// ## The Connection Context
792///
793/// Handler callbacks receive a context object (`cx`) for interacting with the connection:
794///
795/// * **For request handlers** - [`Responder<R>`] provides [`respond`](Responder::respond)
796///   to send the response, plus methods to send other messages
797/// * **For notification handlers** - [`ConnectionTo`] provides methods to send messages
798///   and spawn tasks
799///
800/// Both context types support:
801/// * [`send_request`](ConnectionTo::send_request) - Send requests to the other side
802/// * [`send_notification`](ConnectionTo::send_notification) - Send notifications
803/// * [`spawn`](ConnectionTo::spawn) - Run tasks concurrently without blocking the event loop
804///
805/// The [`SentRequest`] returned by `send_request` provides methods like
806/// [`on_receiving_result`](SentRequest::on_receiving_result) that help you
807/// avoid accidentally blocking the event loop while waiting for responses.
808///
809/// # Driving the Connection
810///
811/// After adding handlers, you must drive the connection using one of two modes:
812///
813/// ## Server Mode: `connect_to()`
814///
815/// Use [`connect_to`](Self::connect_to) when you only need to respond to incoming messages:
816///
817/// ```no_run
818/// # use agent_client_protocol_test::*;
819/// # async fn example() -> Result<(), agent_client_protocol::Error> {
820/// # let connection = mock_connection();
821/// connection
822///     .on_receive_request(async |req: MyRequest, responder, cx| {
823///         responder.respond(MyResponse { status: "ok".into() })
824///     }, agent_client_protocol::on_receive_request!())
825///     .connect_to(MockTransport)  // Runs until connection closes or error occurs
826///     .await?;
827/// # Ok(())
828/// # }
829/// ```
830///
831/// The connection will process incoming messages and invoke your handlers until the
832/// connection is closed or an error occurs.
833///
834/// ## Client Mode: `connect_with()`
835///
836/// Use [`connect_with`](Self::connect_with) when you need to both handle incoming messages
837/// AND send your own requests/notifications:
838///
839/// ```no_run
840/// # use agent_client_protocol_test::*;
841/// # use agent_client_protocol::v1::schema::InitializeRequest;
842/// # async fn example() -> Result<(), agent_client_protocol::Error> {
843/// # let connection = mock_connection();
844/// connection
845///     .on_receive_request(async |req: MyRequest, responder, cx| {
846///         responder.respond(MyResponse { status: "ok".into() })
847///     }, agent_client_protocol::on_receive_request!())
848///     .connect_with(MockTransport, async |cx| {
849///         // You can send requests to the other side
850///         let response = cx.send_request(InitializeRequest::make())
851///             .block_task()
852///             .await?;
853///
854///         // And send notifications
855///         cx.send_notification(StatusUpdate { message: "ready".into() })?;
856///
857///         Ok(())
858///     })
859///     .await?;
860/// # Ok(())
861/// # }
862/// ```
863///
864/// The connection will serve incoming messages in the background while your client closure
865/// runs. When the closure returns, the connection shuts down.
866///
867/// # Example: Complete Agent
868///
869/// ```no_run
870/// # use agent_client_protocol::UntypedRole;
871/// # use agent_client_protocol::{Builder};
872/// # use agent_client_protocol::v1::schema::{InitializeRequest, InitializeResponse, PromptRequest, PromptResponse, SessionNotification};
873/// # async fn example(transport: impl agent_client_protocol::ConnectTo<UntypedRole>) -> Result<(), agent_client_protocol::Error> {
874///
875/// UntypedRole.builder()
876///     .name("my-agent")  // Optional: for debugging logs
877///     .on_receive_request(async |init: InitializeRequest, responder, cx| {
878///         let response: InitializeResponse = todo!();
879///         responder.respond(response)
880///     }, agent_client_protocol::on_receive_request!())
881///     .on_receive_request(async |prompt: PromptRequest, responder, cx| {
882///         // You can send notifications while processing a request
883///         let notif: SessionNotification = todo!();
884///         cx.send_notification(notif)?;
885///
886///         // Then respond to the request
887///         let response: PromptResponse = todo!();
888///         responder.respond(response)
889///     }, agent_client_protocol::on_receive_request!())
890///     .connect_to(transport)
891///     .await?;
892/// # Ok(())
893/// # }
894/// ```
895///
896/// # Protocol version
897///
898/// `P` is the [`Protocol`] marker of the request handles that typed handlers
899/// receive and of the connection type callbacks receive. `Client.v1()`,
900/// `Agent.v1()` and `Proxy.v1()` return [`V1`] builders
901/// ([`v1::Builder`](crate::v1::Builder)), the v2 builders use `V2`
902/// (`v2::Builder`), and [`Builder::new`] and other roles' builders use the
903/// version-neutral default, [`Raw`], with no protocol-version guard.
904#[must_use]
905#[derive(Debug)]
906pub struct Builder<Host: Role, Handler = NullHandler, Runner = NullRun, Close = NullClose, P = Raw>
907where
908    Handler: HandleDispatchFrom<Host::Counterpart>,
909    Runner: RunWithConnectionTo<Host::Counterpart>,
910    Close: HandleConnectionClose<Host::Counterpart>,
911    P: Protocol,
912{
913    /// My role.
914    host: Host,
915
916    /// Name of the connection, used in tracing logs.
917    name: Option<String>,
918
919    /// Handler for incoming messages.
920    handler: Handler,
921
922    /// Runner for background connection tasks.
923    runner: Runner,
924
925    /// Protocol version mode for the public API and wire compatibility layer.
926    protocol_mode: ProtocolMode,
927
928    /// Handler run when the incoming transport reaches clean EOF.
929    on_close: Close,
930
931    /// The protocol version of the callbacks: their connection type and the
932    /// request handles they receive.
933    protocol: PhantomData<fn() -> P>,
934}
935
936impl<Host: Role> Builder<Host, NullHandler, NullRun, NullClose> {
937    /// Create a new version-neutral connection builder for the given role.
938    /// This type follows a builder pattern; use other methods to configure and then invoke
939    /// [`Self::connect_to`] (to use as a server) or [`Self::connect_with`] to use as a client.
940    ///
941    /// The builder is raw: it applies no ACP protocol-version guard, even for
942    /// [`Client`](crate::Client), [`Agent`] and [`Proxy`](crate::Proxy), and
943    /// its callbacks receive [`Raw`] request handles. Messages are sent and received exactly as
944    /// handlers produce them. This suits protocol-routing infrastructure that
945    /// validates `initialize` itself and forwarders such as the conductor,
946    /// which leave version validation to the endpoints.
947    ///
948    /// Applications should use [`Client.v1()`](crate::Client::v1),
949    /// [`Agent.v1()`](crate::Agent::v1) or [`Proxy.v1()`](crate::Proxy::v1)
950    /// (or the `v2()` entry points with the `unstable_protocol_v2` feature),
951    /// which apply that version's wire guard.
952    pub fn new(role: Host) -> Self {
953        Self {
954            host: role,
955            name: None,
956            handler: NullHandler,
957            runner: NullRun,
958            protocol_mode: ProtocolMode::disabled(),
959            on_close: NullClose,
960            protocol: PhantomData,
961        }
962    }
963}
964
965impl<Host: Role, Handler> Builder<Host, Handler, NullRun, NullClose>
966where
967    Handler: HandleDispatchFrom<Host::Counterpart>,
968{
969    /// Create a new connection builder with the given handler.
970    ///
971    /// Like [`Builder::new`], the builder applies no protocol-version guard.
972    pub fn new_with(role: Host, handler: Handler) -> Self {
973        Self {
974            host: role,
975            name: None,
976            handler,
977            runner: NullRun,
978            protocol_mode: ProtocolMode::disabled(),
979            on_close: NullClose,
980            protocol: PhantomData,
981        }
982    }
983}
984
985impl<
986    Host: Role,
987    Handler: HandleDispatchFrom<Host::Counterpart>,
988    Runner: RunWithConnectionTo<Host::Counterpart>,
989    Close: HandleConnectionClose<Host::Counterpart>,
990    P: Protocol,
991> Builder<Host, Handler, Runner, Close, P>
992{
993    /// Set the "name" of this connection -- used only for debugging logs.
994    pub fn name(mut self, name: impl ToString) -> Self {
995        self.name = Some(name.to_string());
996        self
997    }
998
999    /// The same builder with callbacks for protocol `Q`. Handlers already
1000    /// registered keep their own protocol.
1001    pub(crate) fn into_protocol<Q: Protocol>(self) -> Builder<Host, Handler, Runner, Close, Q> {
1002        Builder {
1003            host: self.host,
1004            name: self.name,
1005            handler: self.handler,
1006            runner: self.runner,
1007            protocol_mode: self.protocol_mode,
1008            on_close: self.on_close,
1009            protocol: PhantomData,
1010        }
1011    }
1012
1013    #[cfg(feature = "unstable_protocol_v2")]
1014    pub(crate) fn v2_agent(self) -> Builder<Host, Handler, Runner, Close, V2> {
1015        let mut builder = self.into_protocol();
1016        builder.protocol_mode = ProtocolMode::v2_agent();
1017        builder
1018    }
1019
1020    #[cfg(feature = "unstable_protocol_v2")]
1021    pub(crate) fn v2_client(self) -> Builder<Host, Handler, Runner, Close, V2> {
1022        let mut builder = self.into_protocol();
1023        builder.protocol_mode = ProtocolMode::v2_client();
1024        builder
1025    }
1026
1027    #[cfg(feature = "unstable_protocol_v2")]
1028    pub(crate) fn v2_proxy(self) -> Builder<Host, Handler, Runner, Close, V2> {
1029        let mut builder = self.into_protocol();
1030        builder.protocol_mode = ProtocolMode::v2_proxy();
1031        builder
1032    }
1033
1034    pub(crate) fn v1_agent(self) -> Builder<Host, Handler, Runner, Close, V1> {
1035        let mut builder = self.into_protocol();
1036        builder.protocol_mode = ProtocolMode::v1_agent();
1037        builder
1038    }
1039
1040    pub(crate) fn v1_client(self) -> Builder<Host, Handler, Runner, Close, V1> {
1041        let mut builder = self.into_protocol();
1042        builder.protocol_mode = ProtocolMode::v1_client();
1043        builder
1044    }
1045
1046    pub(crate) fn v1_proxy(self) -> Builder<Host, Handler, Runner, Close, V1> {
1047        let mut builder = self.into_protocol();
1048        builder.protocol_mode = ProtocolMode::v1_proxy();
1049        builder
1050    }
1051
1052    /// Record a request handler of type `Req`.
1053    ///
1054    /// A v1 agent that handles `initialize` itself rejects other requests
1055    /// until initialization completes, as v1 agents SHOULD. Agents without
1056    /// such a handler, including those with only catch-all handlers, keep
1057    /// accepting requests without initialization, because they could not
1058    /// complete one.
1059    fn note_request_handler<Req: JsonRpcRequest>(mut self) -> Self {
1060        // A handler for every method is a catch-all, not an initialize handler.
1061        const UNRELATED_METHOD: &str = "\0acp-sdk/not-a-method";
1062        if TypeId::of::<Host>() == TypeId::of::<Agent>()
1063            && Req::matches_method("initialize")
1064            && !Req::matches_method(UNRELATED_METHOD)
1065        {
1066            self.protocol_mode = self.protocol_mode.require_initialize();
1067        }
1068        self
1069    }
1070
1071    /// Merge another [`Builder`] into this one.
1072    ///
1073    /// Prefer [`Self::on_receive_request`] or [`Self::on_receive_notification`].
1074    /// This is a low-level method that is not intended for general use.
1075    pub fn with_connection_builder(
1076        self,
1077        other: Builder<
1078            Host,
1079            impl HandleDispatchFrom<Host::Counterpart>,
1080            impl RunWithConnectionTo<Host::Counterpart>,
1081            impl HandleConnectionClose<Host::Counterpart>,
1082            P,
1083        >,
1084    ) -> Builder<
1085        Host,
1086        impl HandleDispatchFrom<Host::Counterpart>,
1087        impl RunWithConnectionTo<Host::Counterpart>,
1088        impl HandleConnectionClose<Host::Counterpart>,
1089        P,
1090    > {
1091        let Builder {
1092            name: other_name,
1093            handler: other_handler,
1094            runner: other_runner,
1095            protocol_mode: other_protocol_mode,
1096            on_close: other_on_close,
1097            protocol: _,
1098            host: _,
1099        } = other;
1100        Builder {
1101            host: self.host,
1102            name: self.name,
1103            handler: ChainedHandler::new(
1104                self.handler,
1105                NamedHandler::new(other_name, other_handler),
1106            ),
1107            runner: ChainRun::new(self.runner, other_runner),
1108            protocol_mode: self.protocol_mode.merge(other_protocol_mode),
1109            on_close: ChainedClose::new(self.on_close, other_on_close),
1110            protocol: PhantomData,
1111        }
1112    }
1113
1114    /// Add a new [`HandleDispatchFrom`] to the chain.
1115    ///
1116    /// Prefer [`Self::on_receive_request`] or [`Self::on_receive_notification`].
1117    /// This is a low-level method that is not intended for general use.
1118    pub fn with_handler(
1119        self,
1120        handler: impl HandleDispatchFrom<Host::Counterpart>,
1121    ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P> {
1122        Builder {
1123            host: self.host,
1124            name: self.name,
1125            handler: ChainedHandler::new(self.handler, handler),
1126            runner: self.runner,
1127            protocol_mode: self.protocol_mode,
1128            on_close: self.on_close,
1129            protocol: PhantomData,
1130        }
1131    }
1132
1133    /// Add a new [`RunWithConnectionTo`] to the chain.
1134    pub fn with_runner<Run1>(
1135        self,
1136        runner: Run1,
1137    ) -> Builder<Host, Handler, impl RunWithConnectionTo<Host::Counterpart>, Close, P>
1138    where
1139        Run1: RunWithConnectionTo<Host::Counterpart>,
1140    {
1141        Builder {
1142            host: self.host,
1143            name: self.name,
1144            handler: self.handler,
1145            runner: ChainRun::new(self.runner, runner),
1146            protocol_mode: self.protocol_mode,
1147            on_close: self.on_close,
1148            protocol: PhantomData,
1149        }
1150    }
1151
1152    /// Enqueue a task to run once the connection is actively serving traffic.
1153    #[track_caller]
1154    pub fn with_spawned<F, Fut>(
1155        self,
1156        task: F,
1157    ) -> Builder<Host, Handler, impl RunWithConnectionTo<Host::Counterpart>, Close, P>
1158    where
1159        F: FnOnce(P::Connection<Host::Counterpart>) -> Fut + Send,
1160        Fut: Future<Output = Result<(), crate::Error>> + Send,
1161    {
1162        let location = Location::caller();
1163        // Boxed for the same reason as `main_fn` in `connect_with`: the driver
1164        // would otherwise store the task's captured state once per layer.
1165        self.with_runner(SpawnedRun::<_, P>::new(location, Box::new(task)))
1166    }
1167
1168    /// Run a callback when the incoming transport reaches clean EOF.
1169    ///
1170    /// Each callback runs at most once and receives the connection context. A
1171    /// successful callback observes the close without otherwise changing the
1172    /// lifetime of [`connect_with`](Self::connect_with). Returning an error
1173    /// shuts down the connection and cancels a still-running `connect_with`
1174    /// future.
1175    ///
1176    /// Multiple callbacks run sequentially in registration order. All of them
1177    /// run even if an earlier callback fails, after which the first error is
1178    /// returned. Pending requests are failed before callbacks begin, while the
1179    /// selected connection context's `incoming_closed` future completes only
1180    /// after they finish. A callback must therefore not await that close
1181    /// future itself.
1182    ///
1183    /// This separation lets applications choose their cancellation policy. A
1184    /// callback can notify application-owned tasks and return `Ok(())` for
1185    /// graceful cleanup, or return an error to stop them immediately.
1186    ///
1187    /// Close callbacks do not run for transport or handler errors, foreground
1188    /// completion, or a dropped driver. Use [`ConnectionTo::terminated`] to
1189    /// observe every way the connection can end.
1190    ///
1191    /// ```
1192    /// # use agent_client_protocol::{Client, ConnectTo, Error};
1193    /// # async fn example(transport: impl ConnectTo<Client>) -> Result<(), Error> {
1194    /// Client.v1()
1195    ///     .on_close(async |_cx| {
1196    ///         Err(Error::internal_error().data("agent transport closed"))
1197    ///     })
1198    ///     .connect_with(transport, async |_cx| {
1199    ///         std::future::pending().await
1200    ///     })
1201    ///     .await?;
1202    /// # Ok(())
1203    /// # }
1204    /// ```
1205    pub fn on_close<F, Fut>(
1206        self,
1207        callback: F,
1208    ) -> Builder<Host, Handler, Runner, impl HandleConnectionClose<Host::Counterpart>, P>
1209    where
1210        F: FnOnce(P::Connection<Host::Counterpart>) -> Fut + Send,
1211        Fut: Future<Output = Result<(), crate::Error>> + Send,
1212    {
1213        Builder {
1214            host: self.host,
1215            name: self.name,
1216            handler: self.handler,
1217            runner: self.runner,
1218            protocol_mode: self.protocol_mode,
1219            on_close: ChainedClose::new(self.on_close, CloseCallback::<_, P>::new(callback)),
1220            protocol: PhantomData,
1221        }
1222    }
1223
1224    /// Register a handler for requests, notifications, and responses.
1225    ///
1226    /// Use this when you want to handle all JSON-RPC message kinds in one callback.
1227    /// Your handler receives a [`Dispatch<Req, Notif>`] with three variants:
1228    ///
1229    /// - `Dispatch::Request(request, responder)` - A request with its response context
1230    /// - `Dispatch::Notification(notification)` - A notification
1231    /// - `Dispatch::Response(result, router)` - A response to a request we sent
1232    ///
1233    /// # Example
1234    ///
1235    /// ```no_run
1236    /// # use agent_client_protocol_test::*;
1237    /// # use agent_client_protocol::v1::Dispatch;
1238    /// # async fn example() -> Result<(), agent_client_protocol::Error> {
1239    /// # let connection = mock_connection();
1240    /// connection.on_receive_dispatch(async |message: Dispatch<MyRequest, StatusUpdate>, _cx| {
1241    ///     match message {
1242    ///         Dispatch::Request(req, responder) => {
1243    ///             // Handle request and send response
1244    ///             responder.respond(MyResponse { status: "ok".into() })
1245    ///         }
1246    ///         Dispatch::Notification(notif) => {
1247    ///             // Handle notification (no response needed)
1248    ///             Ok(())
1249    ///         }
1250    ///         Dispatch::Response(result, router) => {
1251    ///             // Forward response to its destination
1252    ///             router.route_with_result(result)
1253    ///         }
1254    ///     }
1255    /// }, agent_client_protocol::on_receive_dispatch!())
1256    /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
1257    /// # Ok(())
1258    /// # }
1259    /// ```
1260    ///
1261    /// For most use cases, prefer [`on_receive_request`](Self::on_receive_request) or
1262    /// [`on_receive_notification`](Self::on_receive_notification) which provide cleaner APIs
1263    /// for handling requests or notifications separately.
1264    ///
1265    /// # Ordering
1266    ///
1267    /// This callback runs inside the dispatch loop and blocks further message processing
1268    /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1269    /// ordering guarantees and how to avoid deadlocks.
1270    pub fn on_receive_dispatch<Req, Notif, F, T, ToFut>(
1271        self,
1272        op: F,
1273        to_future_hack: ToFut,
1274    ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1275    where
1276        Host::Counterpart: HasPeer<Host::Counterpart>,
1277        Req: JsonRpcRequest,
1278        Notif: JsonRpcNotification,
1279        F: AsyncFnMut(
1280                Dispatch<Req, Notif, P>,
1281                P::Connection<Host::Counterpart>,
1282            ) -> Result<T, crate::Error>
1283            + Send,
1284        T: IntoHandled<Dispatch<Req, Notif, P>>,
1285        ToFut: Fn(
1286                &mut F,
1287                Dispatch<Req, Notif, P>,
1288                P::Connection<Host::Counterpart>,
1289            ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1290            + Send
1291            + Sync,
1292    {
1293        let handler = MessageHandler::<_, _, P, _, _, _, _>::new(
1294            self.host.counterpart(),
1295            self.host.counterpart(),
1296            op,
1297            to_future_hack,
1298        );
1299        self.note_request_handler::<Req>().with_handler(handler)
1300    }
1301
1302    /// Register a handler for JSON-RPC requests of type `Req`.
1303    ///
1304    /// Your handler receives three arguments:
1305    /// 1. The request (type `Req`)
1306    /// 2. A [`Responder<Req::Response, P>`] for sending the response
1307    /// 3. The builder-selected connection context for the peer that sent the
1308    ///    request (`ConnectionTo` by default, or `v2::ConnectionTo` for a
1309    ///    `v2::Builder`)
1310    ///
1311    /// The request context allows you to:
1312    /// - Send the response with [`Responder::respond`]
1313    /// - Send notifications to the client with the context's
1314    ///   `send_notification` method
1315    /// - Send requests to the client with the context's `send_request` method
1316    ///
1317    /// # Example
1318    ///
1319    /// ```no_run
1320    /// # use agent_client_protocol::{Agent, ConnectTo};
1321    /// # use agent_client_protocol::v1::schema::{PromptRequest, PromptResponse, SessionNotification};
1322    /// # async fn example(transport: impl ConnectTo<Agent>) -> Result<(), agent_client_protocol::Error> {
1323    /// Agent.v1().on_receive_request(async |request: PromptRequest, responder, cx| {
1324    ///     // Send a notification while processing
1325    ///     let notif: SessionNotification = todo!();
1326    ///     cx.send_notification(notif)?;
1327    ///
1328    ///     // Send the response
1329    ///     let response: PromptResponse = todo!();
1330    ///     responder.respond(response)
1331    /// }, agent_client_protocol::on_receive_request!())
1332    /// .connect_to(transport)
1333    /// .await
1334    /// # }
1335    /// ```
1336    ///
1337    /// # Type Parameter
1338    ///
1339    /// `Req` can be either a single request type or an enum of multiple request types.
1340    /// See the [type-driven dispatch](Self#type-driven-message-dispatch) section for details.
1341    ///
1342    /// # Ordering
1343    ///
1344    /// This callback runs inside the dispatch loop and blocks further message processing
1345    /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1346    /// ordering guarantees and how to avoid deadlocks.
1347    pub fn on_receive_request<Req: JsonRpcRequest, F, T, ToFut>(
1348        self,
1349        op: F,
1350        to_future_hack: ToFut,
1351    ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1352    where
1353        Host::Counterpart: HasPeer<Host::Counterpart>,
1354        F: AsyncFnMut(
1355                Req,
1356                Responder<Req::Response, P>,
1357                P::Connection<Host::Counterpart>,
1358            ) -> Result<T, crate::Error>
1359            + Send,
1360        T: IntoHandled<(Req, Responder<Req::Response, P>)>,
1361        ToFut: Fn(
1362                &mut F,
1363                Req,
1364                Responder<Req::Response, P>,
1365                P::Connection<Host::Counterpart>,
1366            ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1367            + Send
1368            + Sync,
1369    {
1370        let handler = RequestHandler::<_, _, P, _, _, _>::new(
1371            self.host.counterpart(),
1372            self.host.counterpart(),
1373            op,
1374            to_future_hack,
1375        );
1376        self.note_request_handler::<Req>().with_handler(handler)
1377    }
1378
1379    /// Register a handler for JSON-RPC notifications of type `Notif`.
1380    ///
1381    /// Notifications are fire-and-forget messages that don't expect a response.
1382    /// Your handler receives:
1383    /// 1. The notification (type `Notif`)
1384    /// 2. The builder-selected connection context for sending messages to the
1385    ///    other side
1386    ///
1387    /// Unlike request handlers, you cannot send a response (notifications don't have IDs),
1388    /// but you can still send your own requests and notifications using the context.
1389    ///
1390    /// # Example
1391    ///
1392    /// ```no_run
1393    /// # use agent_client_protocol_test::*;
1394    /// # async fn example() -> Result<(), agent_client_protocol::Error> {
1395    /// # let connection = mock_connection();
1396    /// connection.on_receive_notification(async |notif: SessionUpdate, cx| {
1397    ///     // Process the notification
1398    ///     update_session_state(&notif)?;
1399    ///
1400    ///     // Optionally send a notification back
1401    ///     cx.send_notification(StatusUpdate {
1402    ///         message: "Acknowledged".into(),
1403    ///     })?;
1404    ///
1405    ///     Ok(())
1406    /// }, agent_client_protocol::on_receive_notification!())
1407    /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
1408    /// # Ok(())
1409    /// # }
1410    /// ```
1411    ///
1412    /// # Type Parameter
1413    ///
1414    /// `Notif` can be either a single notification type or an enum of multiple notification types.
1415    /// See the [type-driven dispatch](Self#type-driven-message-dispatch) section for details.
1416    ///
1417    /// # Ordering
1418    ///
1419    /// This callback runs inside the dispatch loop and blocks further message processing
1420    /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1421    /// ordering guarantees and how to avoid deadlocks.
1422    pub fn on_receive_notification<Notif, F, T, ToFut>(
1423        self,
1424        op: F,
1425        to_future_hack: ToFut,
1426    ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1427    where
1428        Host::Counterpart: HasPeer<Host::Counterpart>,
1429        Notif: JsonRpcNotification,
1430        F: AsyncFnMut(Notif, P::Connection<Host::Counterpart>) -> Result<T, crate::Error> + Send,
1431        T: IntoHandled<(Notif, P::Connection<Host::Counterpart>)>,
1432        ToFut: Fn(
1433                &mut F,
1434                Notif,
1435                P::Connection<Host::Counterpart>,
1436            ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1437            + Send
1438            + Sync,
1439    {
1440        let handler = NotificationHandler::<_, _, P, _, _, _>::new(
1441            self.host.counterpart(),
1442            self.host.counterpart(),
1443            op,
1444            to_future_hack,
1445        );
1446        self.with_handler(handler)
1447    }
1448
1449    /// Register a handler for messages from a specific peer.
1450    ///
1451    /// This is similar to [`on_receive_dispatch`](Self::on_receive_dispatch), but allows
1452    /// specifying the source peer explicitly. This is useful when receiving messages
1453    /// from a peer that requires message transformation (e.g., unwrapping `SuccessorMessage`
1454    /// envelopes when receiving from an agent via a proxy).
1455    ///
1456    /// For the common case of receiving from the default counterpart, use
1457    /// [`on_receive_dispatch`](Self::on_receive_dispatch) instead.
1458    ///
1459    /// # Ordering
1460    ///
1461    /// This callback runs inside the dispatch loop and blocks further message processing
1462    /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1463    /// ordering guarantees and how to avoid deadlocks.
1464    pub fn on_receive_dispatch_from<
1465        Req: JsonRpcRequest,
1466        Notif: JsonRpcNotification,
1467        Peer: Role,
1468        F,
1469        T,
1470        ToFut,
1471    >(
1472        self,
1473        peer: Peer,
1474        op: F,
1475        to_future_hack: ToFut,
1476    ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1477    where
1478        Host::Counterpart: HasPeer<Peer>,
1479        F: AsyncFnMut(
1480                Dispatch<Req, Notif, P>,
1481                P::Connection<Host::Counterpart>,
1482            ) -> Result<T, crate::Error>
1483            + Send,
1484        T: IntoHandled<Dispatch<Req, Notif, P>>,
1485        ToFut: Fn(
1486                &mut F,
1487                Dispatch<Req, Notif, P>,
1488                P::Connection<Host::Counterpart>,
1489            ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1490            + Send
1491            + Sync,
1492    {
1493        let handler = MessageHandler::<_, _, P, _, _, _, _>::new(
1494            self.host.counterpart(),
1495            peer,
1496            op,
1497            to_future_hack,
1498        );
1499        self.note_request_handler::<Req>().with_handler(handler)
1500    }
1501
1502    /// Register a handler for JSON-RPC requests from a specific peer.
1503    ///
1504    /// This is similar to [`on_receive_request`](Self::on_receive_request), but allows
1505    /// specifying the source peer explicitly. This is useful when receiving messages
1506    /// from a peer that requires message transformation (e.g., unwrapping `SuccessorRequest`
1507    /// envelopes when receiving from an agent via a proxy).
1508    ///
1509    /// For the common case of receiving from the default counterpart, use
1510    /// [`on_receive_request`](Self::on_receive_request) instead.
1511    ///
1512    /// # Example
1513    ///
1514    /// ```ignore
1515    /// use agent_client_protocol::Agent;
1516    /// use agent_client_protocol::v1::schema::InitializeRequest;
1517    ///
1518    /// // Conductor receiving from agent direction - messages will be unwrapped from SuccessorMessage
1519    /// connection.on_receive_request_from(Agent, async |req: InitializeRequest, responder, cx| {
1520    ///     // Handle the request
1521    ///     responder.respond(InitializeResponse::make())
1522    /// })
1523    /// ```
1524    ///
1525    /// # Ordering
1526    ///
1527    /// This callback runs inside the dispatch loop and blocks further message processing
1528    /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1529    /// ordering guarantees and how to avoid deadlocks.
1530    pub fn on_receive_request_from<Req: JsonRpcRequest, Peer: Role, F, T, ToFut>(
1531        self,
1532        peer: Peer,
1533        op: F,
1534        to_future_hack: ToFut,
1535    ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1536    where
1537        Host::Counterpart: HasPeer<Peer>,
1538        F: AsyncFnMut(
1539                Req,
1540                Responder<Req::Response, P>,
1541                P::Connection<Host::Counterpart>,
1542            ) -> Result<T, crate::Error>
1543            + Send,
1544        T: IntoHandled<(Req, Responder<Req::Response, P>)>,
1545        ToFut: Fn(
1546                &mut F,
1547                Req,
1548                Responder<Req::Response, P>,
1549                P::Connection<Host::Counterpart>,
1550            ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1551            + Send
1552            + Sync,
1553    {
1554        let handler = RequestHandler::<_, _, P, _, _, _>::new(
1555            self.host.counterpart(),
1556            peer,
1557            op,
1558            to_future_hack,
1559        );
1560        self.note_request_handler::<Req>().with_handler(handler)
1561    }
1562
1563    /// Register a handler for JSON-RPC notifications from a specific peer.
1564    ///
1565    /// This is similar to [`on_receive_notification`](Self::on_receive_notification), but allows
1566    /// specifying the source peer explicitly. This is useful when receiving messages
1567    /// from a peer that requires message transformation (e.g., unwrapping `SuccessorNotification`
1568    /// envelopes when receiving from an agent via a proxy).
1569    ///
1570    /// For the common case of receiving from the default counterpart, use
1571    /// [`on_receive_notification`](Self::on_receive_notification) instead.
1572    ///
1573    /// # Ordering
1574    ///
1575    /// This callback runs inside the dispatch loop and blocks further message processing
1576    /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1577    /// ordering guarantees and how to avoid deadlocks.
1578    pub fn on_receive_notification_from<Notif: JsonRpcNotification, Peer: Role, F, T, ToFut>(
1579        self,
1580        peer: Peer,
1581        op: F,
1582        to_future_hack: ToFut,
1583    ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1584    where
1585        Host::Counterpart: HasPeer<Peer>,
1586        F: AsyncFnMut(Notif, P::Connection<Host::Counterpart>) -> Result<T, crate::Error> + Send,
1587        T: IntoHandled<(Notif, P::Connection<Host::Counterpart>)>,
1588        ToFut: Fn(
1589                &mut F,
1590                Notif,
1591                P::Connection<Host::Counterpart>,
1592            ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1593            + Send
1594            + Sync,
1595    {
1596        let handler = NotificationHandler::<_, _, P, _, _, _>::new(
1597            self.host.counterpart(),
1598            peer,
1599            op,
1600            to_future_hack,
1601        );
1602        self.with_handler(handler)
1603    }
1604
1605    /// Run in server mode with the provided transport.
1606    ///
1607    /// This drives the connection by continuously processing messages from the transport
1608    /// and dispatching them to your registered handlers. The connection will run until:
1609    /// - The transport closes (e.g., EOF on byte streams)
1610    /// - An error occurs
1611    ///
1612    /// Handler errors are normally contained: requests receive an Error Response,
1613    /// response-handler errors are routed to the pending local request, and
1614    /// notification errors are logged without a wire reply.
1615    ///
1616    /// On clean EOF, messages already accepted by the outgoing queue—including
1617    /// handler responses and close-callback notifications—are drained through
1618    /// the transport sink before this returns `Ok(())`.
1619    ///
1620    /// The transport boundary carries [`TransportFrame`] values. Physical stream adapters
1621    /// serialize and deserialize frames, while channel-based components relay them directly.
1622    ///
1623    /// Use this mode when you only need to respond to incoming messages and don't need
1624    /// to initiate your own requests. If you need to send requests to the other side,
1625    /// use [`connect_with`](Self::connect_with) instead.
1626    ///
1627    /// # Errors
1628    ///
1629    /// Returns errors from the transport, connection tasks, or close callbacks.
1630    /// An error sent to a peer in a response is not itself a connection failure.
1631    ///
1632    /// # Example: Byte Stream Transport
1633    ///
1634    /// ```no_run
1635    /// # use agent_client_protocol::UntypedRole;
1636    /// # use agent_client_protocol::{Builder};
1637    /// # use agent_client_protocol_test::*;
1638    /// # async fn example(transport: impl agent_client_protocol::ConnectTo<UntypedRole>) -> Result<(), agent_client_protocol::Error> {
1639    ///
1640    /// UntypedRole.builder()
1641    ///     .on_receive_request(async |req: MyRequest, responder, cx| {
1642    ///         responder.respond(MyResponse { status: "ok".into() })
1643    ///     }, agent_client_protocol::on_receive_request!())
1644    ///     .connect_to(transport)
1645    ///     .await?;
1646    /// # Ok(())
1647    /// # }
1648    /// ```
1649    pub async fn connect_to(
1650        self,
1651        transport: impl ConnectTo<Host> + 'static,
1652    ) -> Result<(), crate::Error> {
1653        let (_, future) = self.into_connection_and_future(transport, true, async move |cx| {
1654            cx.incoming_closed().await;
1655            Ok(())
1656        });
1657        future.await
1658    }
1659
1660    /// Run the connection until the provided closure completes.
1661    ///
1662    /// This drives the connection by:
1663    /// 1. Running your registered handlers in the background to process incoming messages
1664    /// 2. Executing your `main_fn` closure with the builder-selected connection
1665    ///    context for sending requests and notifications
1666    ///
1667    /// The connection stays active until your `main_fn` returns, then shuts down.
1668    /// Clean incoming EOF fails every pending request and makes future
1669    /// requests fail immediately. It does not cancel unrelated work in
1670    /// `main_fn`: that future may observe the context's `incoming_closed`
1671    /// future, or the builder can use [`on_close`](Self::on_close) to notify it
1672    /// or return an error and stop it.
1673    ///
1674    /// Use this mode when you need to initiate communication (send requests/notifications)
1675    /// in addition to responding to incoming messages. For server-only mode where you just
1676    /// respond to messages, use [`connect_to`](Self::connect_to) instead.
1677    ///
1678    /// # Example
1679    ///
1680    /// ```no_run
1681    /// # use agent_client_protocol::UntypedRole;
1682    /// # use agent_client_protocol::{Builder};
1683    /// # use agent_client_protocol::ByteStreams;
1684    /// # use agent_client_protocol::v1::schema::InitializeRequest;
1685    /// # use agent_client_protocol_test::*;
1686    /// # async fn example(transport: impl agent_client_protocol::ConnectTo<UntypedRole>) -> Result<(), agent_client_protocol::Error> {
1687    ///
1688    /// UntypedRole.builder()
1689    ///     .on_receive_request(async |req: MyRequest, responder, cx| {
1690    ///         // Handle incoming requests in the background
1691    ///         responder.respond(MyResponse { status: "ok".into() })
1692    ///     }, agent_client_protocol::on_receive_request!())
1693    ///     .connect_with(transport, async |cx| {
1694    ///         // Initialize the protocol
1695    ///         let init_response = cx.send_request(InitializeRequest::make())
1696    ///             .block_task()
1697    ///             .await?;
1698    ///
1699    ///         // Send more requests...
1700    ///         let result = cx.send_request(MyRequest {})
1701    ///             .block_task()
1702    ///             .await?;
1703    ///
1704    ///         // When this closure returns, the connection shuts down
1705    ///         Ok(())
1706    ///     })
1707    ///     .await?;
1708    /// # Ok(())
1709    /// # }
1710    /// ```
1711    ///
1712    /// # Parameters
1713    ///
1714    /// - `main_fn`: Your client logic. Receives the builder-selected connection
1715    ///   context for sending messages.
1716    ///
1717    /// # Errors
1718    ///
1719    /// Returns an error if a handler, background task, transport, or close
1720    /// callback fails, or if `main_fn` returns an error. Clean incoming EOF is
1721    /// observable through the context's `incoming_closed` future and is not
1722    /// itself an error in this mode.
1723    pub async fn connect_with<R>(
1724        self,
1725        transport: impl ConnectTo<Host> + 'static,
1726        main_fn: impl AsyncFnOnce(P::Connection<Host::Counterpart>) -> Result<R, crate::Error>,
1727    ) -> Result<R, crate::Error> {
1728        // The driver moves `main_fn` through several nested futures, and each
1729        // one reserves room for it. Box the closure and its future so that the
1730        // returned future holds the caller's captured state once instead of
1731        // once per layer. Otherwise a closure that captures a few kilobytes,
1732        // such as an `initialize` request and response, makes it very large.
1733        let main_fn = Box::new(main_fn);
1734        let (_, future) =
1735            self.into_connection_and_future(transport, false, async move |connection| {
1736                Box::pin(main_fn(protocol::connection_from_raw::<P, _>(connection))).await
1737            });
1738        future.await
1739    }
1740
1741    /// Helper that returns a [`ConnectionTo<R>`] and a future that runs this connection until `main_fn` returns.
1742    fn into_connection_and_future<R>(
1743        self,
1744        transport: impl ConnectTo<Host> + 'static,
1745        wait_owned_transport: bool,
1746        main_fn: impl AsyncFnOnce(ConnectionTo<Host::Counterpart>) -> Result<R, crate::Error>,
1747    ) -> (
1748        ConnectionTo<Host::Counterpart>,
1749        impl Future<Output = Result<R, crate::Error>>,
1750    ) {
1751        let Self {
1752            name,
1753            handler,
1754            runner,
1755            host: me,
1756            protocol_mode,
1757            on_close,
1758            protocol: _,
1759        } = self;
1760
1761        let (outgoing_tx, outgoing_rx) = mpsc::unbounded();
1762        let (new_task_tx, new_task_rx) = mpsc::unbounded();
1763        let (dynamic_handler_tx, dynamic_handler_rx) = mpsc::unbounded();
1764        let (foreground_succeeded_tx, foreground_succeeded) = completion_signal();
1765        let (foreground_done_tx, foreground_done) = completion_signal();
1766        let pending_replies = PendingReplies::default();
1767        let termination_sources = TerminationSources::default();
1768
1769        // Normalize the transport without losing ownership or finish metadata.
1770        let transport_component = crate::DynConnectTo::new(transport);
1771        let (transport_channel, mut transport_future) =
1772            transport_component.into_channel_and_future();
1773        let owned_transport = transport_future.is_some();
1774        let transport_finish = transport_future
1775            .as_mut()
1776            .and_then(crate::ConnectionDriver::take_finish);
1777        let (transport_completion_tx, transport_completion_rx) = oneshot::channel();
1778        let transport_completion = transport_completion_rx
1779            .map(|result| {
1780                result.unwrap_or_else(|error| {
1781                    Err(crate::util::internal_error(format!(
1782                        "transport task dropped before reporting completion: {error}"
1783                    )))
1784                })
1785            })
1786            .boxed()
1787            .shared();
1788
1789        let connection = ConnectionTo::new(
1790            me.counterpart(),
1791            outgoing_tx,
1792            new_task_tx,
1793            dynamic_handler_tx,
1794            transport_completion,
1795            pending_replies.registrar(),
1796            protocol_mode,
1797        );
1798        // Transport progress must outlive successful foreground completion.
1799        // Application tasks remain cancellable. The inherited close-callback
1800        // phase still polls them for cleanup, but physical drain alone does not.
1801        let transport_driver = if let Some(driver) = transport_future {
1802            let termination_sources = termination_sources.clone();
1803            async move {
1804                let result = driver.await;
1805                termination_sources.record(TerminationSource::Transport, &result);
1806                drop(transport_completion_tx.send(result.clone()));
1807                result
1808            }
1809            .boxed()
1810        } else {
1811            // Channel-only endpoints have no physical sink work to await.
1812            // Their protocol drain marker still orders accepted output.
1813            drop(transport_completion_tx.send(Ok(())));
1814            future::ready(Ok(())).boxed()
1815        };
1816
1817        // Destructure the channel endpoints
1818        let Channel {
1819            rx: mut transport_incoming_rx,
1820            tx: transport_outgoing_tx,
1821        } = transport_channel;
1822
1823        let transport_incoming = futures::stream::poll_fn({
1824            let mut completion = connection.transport_completion.clone();
1825            let mut completed = false;
1826            move |cx| {
1827                if owned_transport
1828                    && !completed
1829                    && let std::task::Poll::Ready(Ok(())) =
1830                        std::pin::Pin::new(&mut completion).poll(cx)
1831                {
1832                    // Owned completion closes the producer boundary, not the
1833                    // accepted buffer. The incoming actor still dispatches every
1834                    // accepted frame and completes its close callbacks in order.
1835                    transport_incoming_rx.close();
1836                    completed = true;
1837                }
1838                transport_incoming_rx.poll_next_unpin(cx)
1839            }
1840        });
1841
1842        let protocol_compat = ProtocolCompat::new(protocol_mode);
1843
1844        // Constructed outside the driver so dropping it unpolled still
1845        // publishes a termination.
1846        let termination_guard = TerminationGuard {
1847            incoming_closed: connection.incoming_closed.clone(),
1848            pending_replies: pending_replies.clone(),
1849        };
1850
1851        let future = crate::util::instrument_with_connection_name(name, {
1852            let connection = connection.clone();
1853            async move {
1854                let sources = &termination_sources;
1855                let driver = async {
1856                    let background = async {
1857                        let incoming = {
1858                            let pending_replies = pending_replies.clone();
1859                            let protocol_compat = protocol_compat.clone();
1860                            async {
1861                                let mut transport_incoming = std::pin::pin!(transport_incoming);
1862                                let incoming = incoming_actor::incoming_protocol_actor(
1863                                    me.counterpart(),
1864                                    &connection,
1865                                    transport_incoming.as_mut(),
1866                                    dynamic_handler_rx,
1867                                    pending_replies,
1868                                    incoming_actor::IncomingHandlers::new(
1869                                        handler,
1870                                        on_close,
1871                                        foreground_succeeded.clone(),
1872                                    ),
1873                                    protocol_compat,
1874                                );
1875                                // Success stops delivery, not physical I/O. An
1876                                // underway close callback finishes before sealing.
1877                                let result = run_incoming_until_foreground_succeeds(
1878                                    incoming,
1879                                    foreground_succeeded,
1880                                    connection.incoming_closed.clone(),
1881                                )
1882                                .await;
1883                                sources.record(TerminationSource::Handler, &result);
1884                                if result.is_err() {
1885                                    connection.request_shutdown();
1886                                }
1887                                result?;
1888                                // Keep the raw producer boundary alive while the
1889                                // physical driver drains. Discard without application
1890                                // delivery, rather than fail a late read-side send.
1891                                while transport_incoming.next().await.is_some() {}
1892                                Ok(())
1893                            }
1894                        };
1895                        let other_actors = async {
1896                            let result = futures::try_join!(
1897                                // A ready driver error is authoritative even if its
1898                                // closed channel would also make output forwarding fail.
1899                                transport_driver,
1900                                // Protocol layer: OutgoingMessage -> RawJsonRpcMessage
1901                                outgoing_actor::outgoing_protocol_actor(
1902                                    outgoing_rx,
1903                                    pending_replies,
1904                                    transport_outgoing_tx,
1905                                    protocol_compat,
1906                                    foreground_done,
1907                                )
1908                                .inspect(
1909                                    |result| sources.record(TerminationSource::Transport, result)
1910                                ),
1911                            );
1912                            // Signal before awaiting an underway close callback.
1913                            if result.is_err() {
1914                                connection.request_shutdown();
1915                            }
1916                            result?;
1917                            Ok(())
1918                        };
1919
1920                        // Keep close callbacks alive when another core actor fails.
1921                        // The outer coordination provides the same protection when
1922                        // EOF wakes an application task or the foreground.
1923                        run_until_connection_close(
1924                            incoming,
1925                            other_actors,
1926                            connection.incoming_closed.clone(),
1927                        )
1928                        .await
1929                    };
1930
1931                    run_until_connection_close(
1932                        finish_actor_error(background, &connection),
1933                        async {
1934                            let application = async {
1935                                futures::try_join!(
1936                                    finish_actor_error(
1937                                        task_actor::task_actor(new_task_rx, &connection)
1938                                            .inspect(|result| sources
1939                                                .record(TerminationSource::Handler, result),),
1940                                        &connection,
1941                                    ),
1942                                    finish_actor_error(
1943                                        runner
1944                                            .run_with_connection_to(connection.clone())
1945                                            .inspect(|result| sources
1946                                                .record(TerminationSource::Handler, result),),
1947                                        &connection,
1948                                    ),
1949                                )?;
1950                                Ok(())
1951                            };
1952                            let result = run_until_connection_close(
1953                                application,
1954                                async {
1955                                    let result = main_fn(connection.clone()).await;
1956                                    sources.record(TerminationSource::Foreground, &result);
1957                                    connection.request_shutdown();
1958                                    if result.is_ok() {
1959                                        // Stop new incoming delivery immediately,
1960                                        // including during the callback cleanup phase.
1961                                        let _ = foreground_succeeded_tx.send(());
1962                                    }
1963                                    // Shutdown cancels local consumers, not remote
1964                                    // requests. Do not add cancellation traffic while
1965                                    // dropping those consumers before the drain.
1966                                    connection.pending_replies.disarm_cancellations();
1967                                    // The application actor (including actual scoped
1968                                    // runners) remains polled while supervisors finish.
1969                                    // Only then may ordinary application tasks drop.
1970                                    connection.wait_protected_operations().await;
1971                                    result
1972                                },
1973                                connection.incoming_closed.clone(),
1974                            )
1975                            .await?;
1976                            let _ = foreground_done_tx.send(());
1977                            let drained = connection
1978                                .drain_outgoing(transport_finish, wait_owned_transport)
1979                                .await;
1980                            sources.record(TerminationSource::Transport, &drained);
1981                            drained?;
1982                            Ok(result)
1983                        },
1984                        connection.incoming_closed.clone(),
1985                    )
1986                    .await
1987                };
1988                // Every actor, handler, and task has completed or been
1989                // dropped by the time `driver` resolves.
1990                let result = driver.await;
1991                termination_guard.finish(match &result {
1992                    // A foreground that finishes after observing EOF still
1993                    // ended at a clean EOF boundary.
1994                    Ok(_) if connection.incoming_closed.is_closing() => {
1995                        ConnectionTermination::IncomingClosed
1996                    }
1997                    Ok(_) => ConnectionTermination::LocalShutdown,
1998                    Err(error) => sources.classify(error.clone()),
1999                });
2000                result
2001            }
2002        });
2003
2004        (connection, future)
2005    }
2006}
2007
2008/// Defer an actor error without dropping the other actors that drive owned
2009/// cleanup or an underway close callback. Physical output drain stays separate.
2010async fn finish_actor_error<R: Role>(
2011    actor: impl Future<Output = Result<(), crate::Error>>,
2012    connection: &ConnectionTo<R>,
2013) -> Result<(), crate::Error> {
2014    let result = actor.await;
2015    if result.is_err() {
2016        connection.request_shutdown();
2017        if connection.incoming_closed.is_closing() {
2018            connection.incoming_closed.closed().await;
2019        }
2020        connection.wait_protected_operations().await;
2021    }
2022    result
2023}
2024
2025#[cfg(feature = "unstable_mcp_over_acp")]
2026impl<
2027    Host: Role,
2028    Handler: HandleDispatchFrom<Host::Counterpart>,
2029    Runner: RunWithConnectionTo<Host::Counterpart>,
2030    Close: HandleConnectionClose<Host::Counterpart>,
2031> Builder<Host, Handler, Runner, Close, V1>
2032{
2033    /// Add an MCP server to protocol v1 session setup requests proxied through
2034    /// this connection.
2035    ///
2036    /// The same native MCP server declaration is added to new, load, and resume
2037    /// requests, plus fork requests when `unstable_session_fork` is enabled.
2038    /// Unrelated request fields are preserved exactly.
2039    ///
2040    /// Only applicable to proxies. Use the same method on `v2::Builder` to
2041    /// attach the server to protocol v2 setup requests.
2042    ///
2043    /// The declaration is an `acp` transport (`McpServer::Acp`). The agent must
2044    /// advertise `agentCapabilities.mcpCapabilities.acp`, or a compatibility
2045    /// proxy such as `McpOverAcpPolyfill` must sit between this proxy and the
2046    /// agent; otherwise a conforming agent rejects the setup request with
2047    /// `-32602`. This method does not check the agent's capabilities.
2048    pub fn with_mcp_server(
2049        self,
2050        mcp_server: McpServer<Host::Counterpart, impl RunWithConnectionTo<Host::Counterpart>>,
2051    ) -> Builder<
2052        Host,
2053        impl HandleDispatchFrom<Host::Counterpart>,
2054        impl RunWithConnectionTo<Host::Counterpart>,
2055        Close,
2056        V1,
2057    >
2058    where
2059        Host::Counterpart: HasPeer<Agent> + HasPeer<Client>,
2060    {
2061        let (handler, runner) = mcp_server.into_handler_and_runner();
2062        self.with_handler(handler).with_runner(runner)
2063    }
2064}
2065
2066#[cfg(all(feature = "unstable_mcp_over_acp", feature = "unstable_protocol_v2"))]
2067impl<
2068    Host: Role,
2069    Handler: HandleDispatchFrom<Host::Counterpart>,
2070    Runner: RunWithConnectionTo<Host::Counterpart>,
2071    Close: HandleConnectionClose<Host::Counterpart>,
2072> Builder<Host, Handler, Runner, Close, V2>
2073{
2074    /// Add an MCP server to protocol v2 session setup requests proxied through
2075    /// this connection.
2076    ///
2077    /// The same native MCP server declaration is added to new and resume
2078    /// requests, plus fork requests when `unstable_session_fork` is enabled.
2079    /// Unrelated request fields are preserved exactly.
2080    ///
2081    /// MCP server names must be unique within `mcpServers`. If a client's
2082    /// setup request already declares a server with this server's name, the
2083    /// proxy answers that request with `-32602` naming the conflicting server
2084    /// and does not forward it. The client's servers are never renamed or
2085    /// dropped.
2086    ///
2087    /// Only applicable to proxies.
2088    ///
2089    /// The declaration is an `acp` transport (`McpServer::Acp`). The downstream
2090    /// agent must advertise `session.mcp.acp`, or a compatibility proxy such as
2091    /// `McpOverAcpPolyfill` must sit between this proxy and the agent;
2092    /// otherwise a conforming agent rejects the setup request with `-32602`.
2093    /// This method does not check the agent's capabilities.
2094    pub fn with_mcp_server(
2095        self,
2096        mcp_server: McpServer<Host::Counterpart, impl RunWithConnectionTo<Host::Counterpart>>,
2097    ) -> Builder<
2098        Host,
2099        impl HandleDispatchFrom<Host::Counterpart>,
2100        impl RunWithConnectionTo<Host::Counterpart>,
2101        Close,
2102        V2,
2103    >
2104    where
2105        Host::Counterpart: HasPeer<Agent> + HasPeer<Client>,
2106    {
2107        let (handler, runner) = mcp_server.into_v2_handler_and_runner();
2108        self.with_handler(handler).with_runner(runner)
2109    }
2110}
2111
2112impl<R, H, Run, Close, P> ConnectTo<R::Counterpart> for Builder<R, H, Run, Close, P>
2113where
2114    R: Role,
2115    H: HandleDispatchFrom<R::Counterpart> + 'static,
2116    Run: RunWithConnectionTo<R::Counterpart> + 'static,
2117    Close: HandleConnectionClose<R::Counterpart> + 'static,
2118    P: Protocol,
2119{
2120    async fn connect_to(self, client: impl ConnectTo<R>) -> Result<(), crate::Error> {
2121        Builder::connect_to(self, client).await
2122    }
2123}
2124
2125/// The payload sent through the response oneshot channel.
2126///
2127/// Includes the response value and an optional ack channel for dispatch loop
2128/// synchronization.
2129pub(crate) struct ResponsePayload {
2130    /// The response result - either the JSON value or an error.
2131    pub(crate) result: Result<serde_json::Value, crate::Error>,
2132
2133    /// Optional acknowledgment channel for dispatch loop synchronization.
2134    ///
2135    /// When present, the receiver must send on this channel to signal that
2136    /// response processing is complete, allowing the dispatch loop to continue
2137    /// to the next message.
2138    ///
2139    /// This is present when ordered response consumption was selected before
2140    /// the response was routed during its original dispatch. Public callback
2141    /// consumption and framework-owned ordered blocking transforms can hold
2142    /// the dispatch loop; ordinary blocking consumers, local error paths, and
2143    /// responses routed later do not.
2144    pub(crate) ack_tx: Option<oneshot::Sender<()>>,
2145}
2146
2147type ResponseRouteHook =
2148    Box<dyn FnOnce(&str, &serde_json::Value) -> Result<(), crate::Error> + Send>;
2149
2150/// A prerequisite that must complete before an outgoing request is published
2151/// to the transport.
2152struct RequestReadiness {
2153    future: BoxFuture<'static, Result<(), crate::Error>>,
2154}
2155
2156impl RequestReadiness {
2157    fn new(future: impl Future<Output = Result<(), crate::Error>> + Send + 'static) -> Self {
2158        Self {
2159            future: future.boxed(),
2160        }
2161    }
2162}
2163
2164impl Future for RequestReadiness {
2165    type Output = Result<(), crate::Error>;
2166
2167    fn poll(
2168        mut self: std::pin::Pin<&mut Self>,
2169        cx: &mut std::task::Context<'_>,
2170    ) -> std::task::Poll<Self::Output> {
2171        self.future.as_mut().poll(cx)
2172    }
2173}
2174
2175impl Debug for RequestReadiness {
2176    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2177        formatter
2178            .debug_struct("RequestReadiness")
2179            .finish_non_exhaustive()
2180    }
2181}
2182
2183impl std::fmt::Debug for ResponsePayload {
2184    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2185        f.debug_struct("ResponsePayload")
2186            .field("result", &self.result)
2187            .field("ack_tx", &self.ack_tx.as_ref().map(|_| "..."))
2188            .finish()
2189    }
2190}
2191
2192#[derive(Clone, Debug, Default)]
2193struct ResponseOrdering {
2194    ordered: Arc<AtomicBool>,
2195}
2196
2197impl ResponseOrdering {
2198    fn mark_ordered(&self) {
2199        self.ordered.store(true, Ordering::Release);
2200    }
2201
2202    fn is_ordered(&self) -> bool {
2203        self.ordered.load(Ordering::Acquire)
2204    }
2205}
2206
2207struct PendingReply {
2208    id: RawJsonRpcId,
2209    method: String,
2210    role_id: RoleId,
2211    sender: oneshot::Sender<ResponsePayload>,
2212    cancellation_disarm: SentRequestCancellationDisarm,
2213    ordering: ResponseOrdering,
2214    response_route_hook: Option<ResponseRouteHook>,
2215    forwarded_from: Option<RequestOrigin>,
2216    /// Set only by `v2::ConnectionTo::send_initialize`, whose typed outcome
2217    /// reports a lower-version initialize response as a success.
2218    accepts_lower_initialize_version: bool,
2219}
2220
2221impl PendingReply {
2222    fn fail(self, error: crate::Error) {
2223        self.cancellation_disarm.disarm();
2224        if self
2225            .sender
2226            .send(ResponsePayload {
2227                result: Err(error),
2228                ack_tx: None,
2229            })
2230            .is_err()
2231        {
2232            tracing::trace!(method = %self.method, "Pending request was already dropped");
2233        }
2234    }
2235
2236    fn fail_incoming_closed(self) {
2237        let error = incoming_transport_closed_error(&self.method);
2238        self.fail(error);
2239    }
2240}
2241
2242#[derive(Default)]
2243struct PendingRepliesInner {
2244    incoming_closed: bool,
2245    termination: Option<ConnectionTermination>,
2246    replies: HashMap<RawJsonRpcId, PendingReply>,
2247}
2248
2249#[derive(Clone, Default)]
2250struct PendingReplies {
2251    inner: Arc<Mutex<PendingRepliesInner>>,
2252}
2253
2254impl PendingReplies {
2255    fn registrar(&self) -> PendingRepliesRegistrar {
2256        PendingRepliesRegistrar {
2257            inner: Arc::downgrade(&self.inner),
2258        }
2259    }
2260
2261    fn contains(&self, id: &RawJsonRpcId) -> bool {
2262        self.inner
2263            .lock()
2264            .expect("pending replies mutex poisoned")
2265            .replies
2266            .contains_key(id)
2267    }
2268
2269    fn remove(&self, id: &RawJsonRpcId) -> Option<PendingReply> {
2270        self.inner
2271            .lock()
2272            .expect("pending replies mutex poisoned")
2273            .replies
2274            .remove(id)
2275    }
2276
2277    /// Atomically reject new subscriptions and fail every existing one.
2278    fn close_incoming(&self) -> usize {
2279        let replies = {
2280            let mut inner = self.inner.lock().expect("pending replies mutex poisoned");
2281            inner.incoming_closed = true;
2282            std::mem::take(&mut inner.replies)
2283        };
2284        let count = replies.len();
2285        for (_, reply) in replies {
2286            reply.fail_incoming_closed();
2287        }
2288        count
2289    }
2290
2291    /// Atomically reject new subscriptions and fail every remaining one
2292    /// because the driver has terminated.
2293    fn terminate(&self, termination: &ConnectionTermination) -> usize {
2294        let replies = {
2295            let mut inner = self.inner.lock().expect("pending replies mutex poisoned");
2296            inner.termination = Some(termination.clone());
2297            std::mem::take(&mut inner.replies)
2298        };
2299        let count = replies.len();
2300        for (_, reply) in replies {
2301            let error = connection_terminated_error(&reply.method, termination);
2302            reply.fail(error);
2303        }
2304        count
2305    }
2306}
2307
2308/// A non-owning handle used to register a request before it enters the
2309/// outgoing queue. Keeping this weak prevents escaped [`ConnectionTo`] clones
2310/// from extending the lifetime of response senders after the driver stops.
2311#[derive(Clone)]
2312struct PendingRepliesRegistrar {
2313    inner: Weak<Mutex<PendingRepliesInner>>,
2314}
2315
2316impl PendingRepliesRegistrar {
2317    fn disarm_cancellations(&self) {
2318        if let Some(inner) = self.inner.upgrade() {
2319            let inner = inner.lock().expect("pending replies mutex poisoned");
2320            for reply in inner.replies.values() {
2321                reply.cancellation_disarm.disarm();
2322            }
2323        }
2324    }
2325
2326    /// Register a response destination before the request becomes observable.
2327    ///
2328    /// Returns an error after failing `reply` when EOF has already made a
2329    /// response impossible or the connection driver is no longer running.
2330    fn subscribe(
2331        &self,
2332        id: RawJsonRpcId,
2333        reply: PendingReply,
2334        incoming_closed: &IncomingClosed,
2335    ) -> Result<(), crate::Error> {
2336        let Some(inner) = self.inner.upgrade() else {
2337            let error = if incoming_closed.is_closing() {
2338                incoming_transport_closed_error(&reply.method)
2339            } else if let Some(termination) = incoming_closed.termination() {
2340                connection_terminated_error(&reply.method, &termination)
2341            } else {
2342                crate::util::internal_error(format!(
2343                    "failed to send outgoing request `{}`: connection is no longer running",
2344                    reply.method
2345                ))
2346            };
2347            reply.fail(error.clone());
2348            return Err(error);
2349        };
2350
2351        let result = {
2352            let mut inner = inner.lock().expect("pending replies mutex poisoned");
2353            if inner.incoming_closed {
2354                Err((reply, None))
2355            } else if let Some(termination) = &inner.termination {
2356                Err((reply, Some(termination.clone())))
2357            } else {
2358                Ok(inner.replies.insert(id, reply))
2359            }
2360        };
2361
2362        match result {
2363            Err((rejected, termination)) => {
2364                let error = match termination {
2365                    Some(termination) => {
2366                        connection_terminated_error(&rejected.method, &termination)
2367                    }
2368                    None => incoming_transport_closed_error(&rejected.method),
2369                };
2370                rejected.fail(error.clone());
2371                Err(error)
2372            }
2373            Ok(replaced) => {
2374                if let Some(replaced) = replaced {
2375                    replaced.fail(
2376                        crate::Error::internal_error()
2377                            .data("outgoing request ID was reused before its response arrived"),
2378                    );
2379                }
2380                Ok(())
2381            }
2382        }
2383    }
2384
2385    fn set_origin(&self, id: &RawJsonRpcId, origin: RequestOrigin) {
2386        if let Some(inner) = self.inner.upgrade()
2387            && let Some(reply) = inner
2388                .lock()
2389                .expect("pending replies mutex poisoned")
2390                .replies
2391                .get_mut(id)
2392        {
2393            reply.forwarded_from = Some(origin);
2394        }
2395    }
2396
2397    fn forwarded_origin(&self, peer: RoleId, id: &RawJsonRpcId) -> Option<RequestOrigin> {
2398        let inner = self.inner.upgrade()?;
2399        let inner = inner.lock().expect("pending replies mutex poisoned");
2400        let reply = inner.replies.get(id)?;
2401        // A conductor sends requests to the same physical proxy in both
2402        // directions. The explicit successor envelope is a request *from*
2403        // its successor, not a client request the proxy can elicit against.
2404        if reply.role_id != peer
2405            || reply.method == crate::v1::schema::PROXY_METHOD_NAMES.proxy_successor
2406            || reply.cancellation_disarm.is_disarmed()
2407        {
2408            return None;
2409        }
2410        reply.forwarded_from.clone()
2411    }
2412
2413    /// Rewrite only the ACP request-scope field. Don't deserialize the whole
2414    /// request: proxies must preserve fields their SDK doesn't know.
2415    fn translate_elicitation(
2416        &self,
2417        peer: RoleId,
2418        request: &mut UntypedMessage,
2419        accepts_origin: impl FnOnce(&RequestOrigin) -> bool,
2420    ) -> Result<(), crate::Error> {
2421        if !crate::v1::schema::CreateElicitationRequest::matches_method(request.method()) {
2422            return Ok(());
2423        }
2424        let has_session_scope = request.params.get("sessionId").is_some();
2425        let Some(reference) = request.params.get_mut("requestId") else {
2426            return Ok(());
2427        };
2428        // V1 and v2 parsers can interpret a double scope differently. Never
2429        // pass an unresolved requestId through on the strength of a sessionId.
2430        if has_session_scope {
2431            return Err(crate::Error::invalid_params().data("Ambiguous elicitation scope"));
2432        }
2433        let id =
2434            RawJsonRpcId::deserialize(&*reference).map_err(|_| crate::Error::invalid_params())?;
2435        let id = self
2436            .forwarded_origin(peer, &id)
2437            .filter(accepts_origin)
2438            .and_then(RequestOrigin::live_id)
2439            .ok_or_else(|| crate::Error::invalid_params().data("Unknown forwarded request ID"))?;
2440        *reference = serde_json::to_value(id).expect("a JSON-RPC ID is JSON serializable");
2441        Ok(())
2442    }
2443
2444    fn remove(&self, id: &RawJsonRpcId) -> Option<PendingReply> {
2445        self.inner
2446            .upgrade()?
2447            .lock()
2448            .expect("pending replies mutex poisoned")
2449            .replies
2450            .remove(id)
2451    }
2452}
2453
2454impl Debug for PendingRepliesRegistrar {
2455    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2456        formatter
2457            .debug_struct("PendingRepliesRegistrar")
2458            .field("is_connected", &(self.inner.strong_count() > 0))
2459            .finish()
2460    }
2461}
2462
2463/// A request-local marker that is set when the peer asks to cancel the request.
2464///
2465/// Request handlers can get this handle from [`Responder::cancellation`] and
2466/// use it from spawned work to stop long-running request processing
2467/// cooperatively.
2468#[derive(Clone)]
2469pub struct RequestCancellation {
2470    state: Arc<RequestCancellationState>,
2471}
2472
2473struct RequestCancellationState {
2474    cancelled: AtomicBool,
2475    signal_tx: Mutex<Option<oneshot::Sender<()>>>,
2476    signal_rx: future::Shared<BoxFuture<'static, ()>>,
2477}
2478
2479impl RequestCancellation {
2480    fn new() -> Self {
2481        let (signal_tx, signal_rx) = oneshot::channel();
2482        let signal_rx = signal_rx.map(|_| ()).boxed().shared();
2483        Self {
2484            state: Arc::new(RequestCancellationState {
2485                cancelled: AtomicBool::new(false),
2486                signal_tx: Mutex::new(Some(signal_tx)),
2487                signal_rx,
2488            }),
2489        }
2490    }
2491
2492    /// Wait until the peer sends `$/cancel_request` for this request.
2493    ///
2494    /// If cancellation was already requested, this returns immediately.
2495    pub async fn cancelled(&self) {
2496        self.state.signal_rx.clone().await;
2497    }
2498
2499    /// Run request work until it completes or the peer asks to cancel it.
2500    ///
2501    /// When cancellation wins, `future` is dropped: work stops at its next
2502    /// await point, partial results are lost, and any cleanup must happen in
2503    /// `Drop` implementations. Handlers that need to flush partial results or
2504    /// run async cleanup should instead watch [`cancelled`](Self::cancelled)
2505    /// or poll [`is_cancelled`](Self::is_cancelled) from inside the work.
2506    ///
2507    /// # Errors
2508    ///
2509    /// Returns [`Error::request_cancelled`] if cancellation wins, or the
2510    /// future's own error if it finishes first.
2511    ///
2512    /// [`Error::request_cancelled`]: crate::Error::request_cancelled
2513    pub async fn run_until_cancelled<T>(
2514        &self,
2515        future: impl std::future::Future<Output = Result<T, crate::Error>>,
2516    ) -> Result<T, crate::Error> {
2517        if self.is_cancelled() {
2518            return Err(crate::Error::request_cancelled());
2519        }
2520
2521        match future::select(pin!(future), pin!(self.cancelled())).await {
2522            Either::Left((result, _)) => result,
2523            Either::Right(((), _)) => Err(crate::Error::request_cancelled()),
2524        }
2525    }
2526
2527    /// Returns whether the peer has already requested cancellation.
2528    #[must_use]
2529    pub fn is_cancelled(&self) -> bool {
2530        self.state.cancelled.load(Ordering::Acquire)
2531    }
2532
2533    fn cancel(&self) {
2534        if self.state.cancelled.swap(true, Ordering::AcqRel) {
2535            return;
2536        }
2537
2538        let signal_tx = self
2539            .state
2540            .signal_tx
2541            .lock()
2542            .expect("request cancellation signal mutex poisoned")
2543            .take();
2544
2545        // Complete the oneshot outside the lock: it wakes waiters, and
2546        // arbitrary waker code must not observe the lock held.
2547        if let Some(signal_tx) = signal_tx {
2548            let _ = signal_tx.send(());
2549        }
2550    }
2551}
2552
2553impl Debug for RequestCancellation {
2554    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2555        formatter
2556            .debug_struct("RequestCancellation")
2557            .field("is_cancelled", &self.is_cancelled())
2558            .finish_non_exhaustive()
2559    }
2560}
2561
2562/// Per-request cancellation state tracked by [`RequestCancellationRegistry`].
2563///
2564/// The full [`RequestCancellation`] marker (with its wakeup machinery) is only
2565/// allocated once a handler asks for it via [`Responder::cancellation`]; until
2566/// then an incoming `$/cancel_request` just flips the entry to `Cancelled`.
2567/// This keeps the per-request cost of the registry to a single map entry.
2568#[derive(Debug)]
2569enum RequestCancellationEntry {
2570    /// The request is in flight; no marker handed out, no cancellation yet.
2571    Armed,
2572    /// `$/cancel_request` arrived before a marker was handed out.
2573    Cancelled,
2574    /// A marker was handed out via [`Responder::cancellation`].
2575    Marker(RequestCancellation),
2576}
2577
2578/// A registered request's cancellation state, tagged with the generation of
2579/// its registration.
2580///
2581/// The generation distinguishes a registration from earlier ones that used
2582/// the same request ID, so that when a (protocol-violating) peer reuses the
2583/// ID of a request that is still in flight, the stale request's responder can
2584/// neither remove nor observe the cancellation state of the newer request.
2585#[derive(Debug)]
2586struct RequestCancellationSlot {
2587    generation: u64,
2588    entry: RequestCancellationEntry,
2589}
2590
2591#[derive(Debug, Default)]
2592struct RequestCancellationRegistryInner {
2593    slots: HashMap<RawJsonRpcId, RequestCancellationSlot>,
2594    next_generation: u64,
2595}
2596
2597#[derive(Clone, Debug, Default)]
2598struct RequestCancellationRegistry {
2599    inner: Arc<Mutex<RequestCancellationRegistryInner>>,
2600}
2601
2602#[derive(Debug)]
2603struct ResponderCancellation {
2604    id: RawJsonRpcId,
2605    generation: u64,
2606    registry: RequestCancellationRegistry,
2607}
2608
2609/// A non-owning reference to one incoming request, not just its wire ID.
2610/// Reusing an upstream ID must never transfer an old callback to its new owner.
2611#[derive(Clone)]
2612struct RequestOrigin {
2613    id: RawJsonRpcId,
2614    generation: u64,
2615    registry: Weak<Mutex<RequestCancellationRegistryInner>>,
2616    /// For a proxy forwarding on the same connection, which logical peer
2617    /// supplied the request. `None` for requests from another connection.
2618    local_peer: Option<RemoteStyle>,
2619}
2620
2621impl RequestOrigin {
2622    fn live_id(self) -> Option<RawJsonRpcId> {
2623        let registry = self.registry.upgrade()?;
2624        let inner = registry
2625            .lock()
2626            .expect("request cancellation registry mutex poisoned");
2627        let slot = inner.slots.get(&self.id)?;
2628        (slot.generation == self.generation && !slot.entry.is_cancelled()).then_some(self.id)
2629    }
2630}
2631
2632impl RequestCancellationEntry {
2633    fn is_cancelled(&self) -> bool {
2634        match self {
2635            Self::Armed => false,
2636            Self::Cancelled => true,
2637            Self::Marker(marker) => marker.is_cancelled(),
2638        }
2639    }
2640}
2641
2642impl RequestCancellationRegistry {
2643    fn new() -> Self {
2644        Self::default()
2645    }
2646
2647    fn register(&self, id: &RawJsonRpcId) -> ResponderCancellation {
2648        let generation = {
2649            let mut inner = self
2650                .inner
2651                .lock()
2652                .expect("request cancellation registry mutex poisoned");
2653            let generation = inner.next_generation;
2654            inner.next_generation += 1;
2655            if inner
2656                .slots
2657                .insert(
2658                    id.clone(),
2659                    RequestCancellationSlot {
2660                        generation,
2661                        entry: RequestCancellationEntry::Armed,
2662                    },
2663                )
2664                .is_some()
2665            {
2666                tracing::debug!(
2667                    ?id,
2668                    "peer reused the ID of a request that is still in flight"
2669                );
2670            }
2671            generation
2672        };
2673        ResponderCancellation {
2674            id: id.clone(),
2675            generation,
2676            registry: self.clone(),
2677        }
2678    }
2679
2680    /// Get the cancellation marker for a registered request, creating it on
2681    /// first use. Repeated calls return markers that share the same state.
2682    ///
2683    /// Exception: when the registration is stale (a protocol-violating peer
2684    /// reused this request ID and the slot now belongs to a newer request, or
2685    /// was already removed by it), every call returns a fresh *detached*
2686    /// marker. Detached markers can never fire, and detached markers from
2687    /// repeated calls do not share state with each other.
2688    fn marker(&self, id: &RawJsonRpcId, generation: u64) -> RequestCancellation {
2689        let mut inner = self
2690            .inner
2691            .lock()
2692            .expect("request cancellation registry mutex poisoned");
2693        let Some(slot) = inner.slots.get_mut(id) else {
2694            // The slot lives as long as the responder that owns it, so this
2695            // is only reachable if the peer reused this request ID and the
2696            // newer request's responder already removed the replacement slot.
2697            // Hand out a detached marker rather than panicking.
2698            return RequestCancellation::new();
2699        };
2700        if slot.generation != generation {
2701            // The peer reused this request ID while the request was still in
2702            // flight, and the slot now belongs to the newer request. Hand the
2703            // stale responder a detached marker instead of cross-wiring the
2704            // two requests' cancellation states.
2705            return RequestCancellation::new();
2706        }
2707        let entry = &mut slot.entry;
2708        match entry {
2709            RequestCancellationEntry::Marker(marker) => marker.clone(),
2710            RequestCancellationEntry::Armed => {
2711                let marker = RequestCancellation::new();
2712                *entry = RequestCancellationEntry::Marker(marker.clone());
2713                marker
2714            }
2715            RequestCancellationEntry::Cancelled => {
2716                // No one can be waiting on a marker that did not exist yet,
2717                // so firing it while holding the registry lock is fine.
2718                let marker = RequestCancellation::new();
2719                marker.cancel();
2720                *entry = RequestCancellationEntry::Marker(marker.clone());
2721                marker
2722            }
2723        }
2724    }
2725
2726    fn cancel_if_requested(&self, dispatch: &Dispatch) -> Result<bool, crate::Error> {
2727        let Some(request_id) = cancellation_request_id(dispatch)? else {
2728            return Ok(false);
2729        };
2730        Ok(self.cancel(&request_id))
2731    }
2732
2733    /// Mark whichever request currently owns `request_id` as cancelled.
2734    fn cancel(&self, request_id: &RawJsonRpcId) -> bool {
2735        let marker = {
2736            let mut inner = self
2737                .inner
2738                .lock()
2739                .expect("request cancellation registry mutex poisoned");
2740            let Some(slot) = inner.slots.get_mut(request_id) else {
2741                return false;
2742            };
2743            let entry = &mut slot.entry;
2744            match entry {
2745                RequestCancellationEntry::Marker(marker) => marker.clone(),
2746                RequestCancellationEntry::Cancelled => return true,
2747                RequestCancellationEntry::Armed => {
2748                    *entry = RequestCancellationEntry::Cancelled;
2749                    return true;
2750                }
2751            }
2752        };
2753
2754        // Fire the marker outside the registry lock: waking waiters runs
2755        // arbitrary waker code that must not observe the lock held.
2756        marker.cancel();
2757        true
2758    }
2759
2760    /// Remove the slot for `request_id`, but only if it still belongs to the
2761    /// registration identified by `generation`.
2762    fn remove(&self, request_id: &RawJsonRpcId, generation: u64) {
2763        let mut inner = self
2764            .inner
2765            .lock()
2766            .expect("request cancellation registry mutex poisoned");
2767        if inner
2768            .slots
2769            .get(request_id)
2770            .is_some_and(|slot| slot.generation == generation)
2771        {
2772            inner.slots.remove(request_id);
2773        }
2774    }
2775}
2776
2777impl ResponderCancellation {
2778    fn cancellation(&self) -> RequestCancellation {
2779        self.registry.marker(&self.id, self.generation)
2780    }
2781
2782    /// Whether the peer has cancelled this request, without allocating a
2783    /// marker.
2784    fn is_cancelled(&self) -> bool {
2785        let inner = self
2786            .registry
2787            .inner
2788            .lock()
2789            .expect("request cancellation registry mutex poisoned");
2790        let Some(slot) = inner.slots.get(&self.id) else {
2791            return false;
2792        };
2793        if slot.generation != self.generation {
2794            return false;
2795        }
2796        slot.entry.is_cancelled()
2797    }
2798}
2799
2800impl Drop for ResponderCancellation {
2801    fn drop(&mut self) {
2802        self.registry.remove(&self.id, self.generation);
2803    }
2804}
2805
2806fn cancellation_request_id(dispatch: &Dispatch) -> Result<Option<RawJsonRpcId>, crate::Error> {
2807    let Dispatch::Notification(message) = dispatch else {
2808        return Ok(None);
2809    };
2810    cancellation_request_id_from_message(message)
2811}
2812
2813fn cancellation_request_id_from_message(
2814    message: &UntypedMessage,
2815) -> Result<Option<RawJsonRpcId>, crate::Error> {
2816    let (method, params) = peel_successor_envelopes(&message.method, &message.params);
2817    if !crate::v1::schema::CancelRequestNotification::matches_method(method) {
2818        return Ok(None);
2819    }
2820
2821    let notification = crate::v1::schema::CancelRequestNotification::parse_message(method, params)?;
2822    Ok(Some(notification.request_id.into()))
2823}
2824
2825/// Peel any [`SuccessorMessage`] envelopes off a notification by reference,
2826/// returning the innermost method and params.
2827///
2828/// This only peeks at the envelope's `method`/`params` fields instead of
2829/// deserializing the envelope, for two reasons:
2830///
2831/// - It avoids deep-cloning the params of every wrapped notification on the
2832///   hot dispatch path just to inspect the inner method name.
2833/// - It is deliberately lenient: a malformed envelope is left as-is here and
2834///   flows on to the handler chain, which is responsible for reporting it.
2835///
2836/// [`SuccessorMessage`]: crate::schema::SuccessorMessage
2837fn peel_successor_envelopes<'message>(
2838    mut method: &'message str,
2839    mut params: &'message serde_json::Value,
2840) -> (&'message str, &'message serde_json::Value) {
2841    while crate::schema::SuccessorMessage::<UntypedMessage>::matches_method(method) {
2842        let Some(inner_method) = params.get("method").and_then(serde_json::Value::as_str) else {
2843            break;
2844        };
2845        method = inner_method;
2846        params = params.get("params").unwrap_or(&serde_json::Value::Null);
2847    }
2848    (method, params)
2849}
2850
2851/// Whether a notification is a `$/cancel_request`, even when it is still
2852/// wrapped in `proxy/successor` envelopes.
2853///
2854/// `$/cancel_request` is connection-scoped: its `requestId` was allocated on
2855/// the connection the notification arrived over and means nothing on any
2856/// other connection. Generic forwarding code (such as
2857/// [`ConnectionTo::send_proxied_message_to`]) uses this check to drop the raw
2858/// notification instead of tunneling it across a hop; the cancellation still
2859/// propagates because [`forward_response_to`](SentRequest::forward_response_to)
2860/// re-issues it with the forwarded request's own ID.
2861///
2862/// Checking a notification whose method is not the successor envelope is a
2863/// plain method-name comparison. Only successor-wrapped notifications pay for
2864/// a serialization to peel the envelope.
2865#[must_use]
2866pub fn is_cancel_request_notification<N: JsonRpcNotification>(notification: &N) -> bool {
2867    let method = notification.method();
2868    if crate::v1::schema::CancelRequestNotification::matches_method(method) {
2869        return true;
2870    }
2871    if !crate::schema::SuccessorMessage::<UntypedMessage>::matches_method(method) {
2872        return false;
2873    }
2874
2875    match notification.to_untyped_message() {
2876        Ok(untyped) => {
2877            let (method, _params) = peel_successor_envelopes(&untyped.method, &untyped.params);
2878            crate::v1::schema::CancelRequestNotification::matches_method(method)
2879        }
2880        Err(error) => {
2881            tracing::debug!(
2882                error = ?crate::util::redacted_error(error.code),
2883                "failed to inspect successor-wrapped notification for cancellation"
2884            );
2885            false
2886        }
2887    }
2888}
2889
2890/// Where the response to an incoming request is sent.
2891///
2892/// A request is answered at most once; a duplicate completion is ignored.
2893///
2894/// While a handler attempt for the request is running (see
2895/// [`begin_handler_attempt`](Self::begin_handler_attempt)), the automatic
2896/// error for a dropped [`Responder`] is held back: if the handler then
2897/// returns an error, that error is the response, not the generic fallback.
2898#[derive(Clone, Debug, Default)]
2899struct ResponseDestination {
2900    state: Arc<ResponseDestinationState>,
2901}
2902
2903#[derive(Debug, Default)]
2904struct ResponseDestinationState {
2905    completed: AtomicBool,
2906    attempts: Mutex<HandlerAttempts>,
2907}
2908
2909#[derive(Debug, Default)]
2910struct HandlerAttempts {
2911    active: usize,
2912    deferred: Option<AbandonedResponse>,
2913}
2914
2915/// The automatic error response for a [`Responder`] dropped without replying.
2916#[derive(Debug)]
2917struct AbandonedResponse {
2918    message_tx: OutgoingMessageTx,
2919    connection_state: IncomingClosed,
2920    message: OutgoingMessage,
2921}
2922
2923impl AbandonedResponse {
2924    fn send(self) {
2925        // Re-check: shutdown may have begun while the response was deferred.
2926        if self.connection_state.is_shutting_down() {
2927            tracing::debug!("not answering dropped responder: connection is shutting down");
2928            return;
2929        }
2930        if let Err(error) = send_raw_message(&self.message_tx, self.message) {
2931            tracing::debug!(
2932                error = ?crate::util::redacted_error(error.code),
2933                "could not answer request whose responder was dropped"
2934            );
2935        }
2936    }
2937}
2938
2939/// A running handler attempt for one request; see [`ResponseDestination`].
2940struct HandlerAttempt {
2941    destination: ResponseDestination,
2942}
2943
2944impl Drop for HandlerAttempt {
2945    fn drop(&mut self) {
2946        let deferred = {
2947            let mut attempts = self.destination.attempts();
2948            attempts.active -= 1;
2949            if attempts.active == 0 {
2950                attempts.deferred.take()
2951            } else {
2952                None
2953            }
2954        };
2955        if let Some(deferred) = deferred {
2956            deferred.send();
2957        }
2958    }
2959}
2960
2961impl ResponseDestination {
2962    fn individual() -> Self {
2963        Self::default()
2964    }
2965
2966    fn attempts(&self) -> std::sync::MutexGuard<'_, HandlerAttempts> {
2967        self.state
2968            .attempts
2969            .lock()
2970            .expect("response destination mutex poisoned")
2971    }
2972
2973    fn is_completed(&self) -> bool {
2974        self.state.completed.load(Ordering::Acquire)
2975    }
2976
2977    fn complete(self, response: RawJsonRpcMessage) -> Option<TransportFrame> {
2978        if self.state.completed.swap(true, Ordering::AcqRel) {
2979            tracing::warn!("Ignoring duplicate completion of JSON-RPC request");
2980            return None;
2981        }
2982
2983        Some(TransportFrame::Single(response))
2984    }
2985
2986    fn begin_handler_attempt(&self) -> HandlerAttempt {
2987        self.attempts().active += 1;
2988        HandlerAttempt {
2989            destination: self.clone(),
2990        }
2991    }
2992
2993    /// Send, or defer until the running handler attempt ends, the automatic
2994    /// error for a dropped responder.
2995    fn abandon(&self, response: AbandonedResponse) {
2996        {
2997            let mut attempts = self.attempts();
2998            if attempts.active > 0 {
2999                attempts.deferred = Some(response);
3000                return;
3001            }
3002        }
3003        response.send();
3004    }
3005
3006    /// A handler error answers the request; drop any deferred fallback.
3007    fn discard_abandoned(&self) {
3008        self.attempts().deferred = None;
3009    }
3010}
3011
3012#[derive(Clone, Debug)]
3013struct RequestReplyTarget {
3014    id: RawJsonRpcId,
3015    method: String,
3016    destination: ResponseDestination,
3017}
3018
3019#[derive(Clone)]
3020struct ResponseReplyTarget {
3021    id: RawJsonRpcId,
3022    method: String,
3023    sender: Arc<Mutex<Option<oneshot::Sender<ResponsePayload>>>>,
3024    ordering: ResponseOrdering,
3025    dispatch: ResponseDispatch,
3026}
3027
3028impl ResponseReplyTarget {
3029    fn route(self, result: Result<serde_json::Value, crate::Error>) {
3030        let sender = self
3031            .sender
3032            .lock()
3033            .expect("response reply mutex poisoned")
3034            .take();
3035        let Some(sender) = sender else {
3036            tracing::debug!(
3037                method = %self.method,
3038                id = ?self.id,
3039                "response was already routed to its local awaiter"
3040            );
3041            return;
3042        };
3043
3044        let ack_tx = self.dispatch.acknowledgment(&self.ordering);
3045        if sender.send(ResponsePayload { result, ack_tx }).is_err() {
3046            tracing::debug!(
3047                method = %self.method,
3048                id = ?self.id,
3049                "dropped response because local receiver was gone"
3050            );
3051        }
3052    }
3053}
3054
3055#[derive(Clone, Default)]
3056struct ResponseDispatch {
3057    state: Arc<Mutex<ResponseDispatchState>>,
3058}
3059
3060#[derive(Default)]
3061struct ResponseDispatchState {
3062    complete: bool,
3063    ack_rx: Option<oneshot::Receiver<()>>,
3064}
3065
3066impl ResponseDispatch {
3067    fn acknowledgment(&self, ordering: &ResponseOrdering) -> Option<oneshot::Sender<()>> {
3068        if !ordering.is_ordered() {
3069            return None;
3070        }
3071
3072        let mut state = self.state.lock().expect("response dispatch mutex poisoned");
3073        if state.complete {
3074            return None;
3075        }
3076
3077        let (ack_tx, ack_rx) = oneshot::channel();
3078        let previous_ack = state.ack_rx.replace(ack_rx);
3079        debug_assert!(
3080            previous_ack.is_none(),
3081            "a response dispatch can only be routed once"
3082        );
3083        Some(ack_tx)
3084    }
3085
3086    fn complete(&self) -> Option<oneshot::Receiver<()>> {
3087        let mut state = self.state.lock().expect("response dispatch mutex poisoned");
3088        state.complete = true;
3089        state.ack_rx.take()
3090    }
3091}
3092
3093enum HandlerErrorTarget {
3094    Request(RequestReplyTarget),
3095    Response(ResponseReplyTarget),
3096}
3097
3098impl HandlerErrorTarget {
3099    fn begin_handler_attempt(&self) -> Option<HandlerAttempt> {
3100        match self {
3101            Self::Request(target) => Some(target.destination.begin_handler_attempt()),
3102            Self::Response(_) => None,
3103        }
3104    }
3105}
3106
3107#[derive(Debug)]
3108enum OutgoingMessage {
3109    /// Close the outgoing application queue and acknowledge after every
3110    /// already-accepted message has entered the raw transport queue.
3111    CloseAfterDraining { done: oneshot::Sender<()> },
3112
3113    /// Send a request to the server.
3114    Request {
3115        /// id assigned to this request (generated by sender)
3116        id: RawJsonRpcId,
3117
3118        /// the original method
3119        method: String,
3120
3121        /// The logical message before peer-direction wrapping.
3122        untyped: UntypedMessage,
3123
3124        /// How to transform the logical message for its target peer.
3125        remote_style: crate::role::RemoteStyle,
3126
3127        /// Optional prerequisite that must finish before the request becomes
3128        /// visible on the transport.
3129        readiness: Option<RequestReadiness>,
3130    },
3131
3132    /// Send a notification to the server.
3133    Notification {
3134        /// the message to send; this may have a distinct method
3135        /// depending on the peer
3136        untyped: UntypedMessage,
3137    },
3138
3139    /// Send a response to a message from the server
3140    Response {
3141        id: RawJsonRpcId,
3142
3143        /// Method of the incoming request this response completes.
3144        method: String,
3145
3146        response: Result<serde_json::Value, crate::Error>,
3147
3148        destination: ResponseDestination,
3149    },
3150
3151    /// Send an Error Response that cannot be correlated to a request ID.
3152    UncorrelatedErrorResponse {
3153        error: crate::Error,
3154        destination: ResponseDestination,
3155    },
3156}
3157
3158impl OutgoingMessage {
3159    /// Kind, method, and ID only; params, results, and errors can carry
3160    /// credentials and must not appear in ordinary logs.
3161    fn log_summary(&self) -> (&'static str, Option<&str>, Option<&RawJsonRpcId>) {
3162        match self {
3163            Self::CloseAfterDraining { .. } => ("close_after_draining", None, None),
3164            Self::Request { id, method, .. } => ("request", Some(method), Some(id)),
3165            Self::Notification { untyped } => ("notification", Some(&untyped.method), None),
3166            Self::Response { id, method, .. } => ("response", Some(method), Some(id)),
3167            Self::UncorrelatedErrorResponse { .. } => ("uncorrelated_error_response", None, None),
3168        }
3169    }
3170}
3171
3172/// Whether a dispatch handler handled a message or passed it on.
3173#[must_use]
3174#[derive(Debug)]
3175pub enum Handled<T> {
3176    /// The message was handled
3177    Yes,
3178
3179    /// The message was not handled; returns the original value.
3180    ///
3181    /// If `retry` is true,
3182    No {
3183        /// The message to be passed to subsequent handlers
3184        /// (typically the original message, but it may have been
3185        /// mutated.)
3186        message: T,
3187
3188        /// If true, request the message to be queued and retried with
3189        /// dynamic handlers as they are added.
3190        ///
3191        /// This is used for managing session updates since the dynamic
3192        /// handler for a session cannot be added until the response to the
3193        /// new session request has been processed and there may be updates
3194        /// that get processed at the same time.
3195        retry: bool,
3196    },
3197}
3198
3199/// Trait for converting handler return values into [`Handled`].
3200///
3201/// This trait allows handlers to return either `()` (which becomes `Handled::Yes`)
3202/// or an explicit `Handled<T>` value for more control over handler propagation.
3203pub trait IntoHandled<T> {
3204    /// Convert this value into a `Handled<T>`.
3205    fn into_handled(self) -> Handled<T>;
3206}
3207
3208impl<T> IntoHandled<T> for () {
3209    fn into_handled(self) -> Handled<T> {
3210        Handled::Yes
3211    }
3212}
3213
3214impl<T> IntoHandled<T> for Handled<T> {
3215    fn into_handled(self) -> Handled<T> {
3216        self
3217    }
3218}
3219
3220/// Connection context for sending messages and spawning tasks.
3221///
3222/// This is the primary handle for interacting with the JSON-RPC connection from
3223/// within handler callbacks. You can use it to:
3224///
3225/// * Send requests and notifications to the other side
3226/// * Spawn concurrent tasks that run alongside the connection
3227/// * Respond to requests (via [`Responder`] which wraps this)
3228///
3229/// # Cloning
3230///
3231/// `ConnectionTo` is cheaply cloneable - all clones refer to the same underlying connection.
3232/// This makes it easy to share across async tasks.
3233///
3234/// # Event Loop and Concurrency
3235///
3236/// Handler callbacks run on the event loop, which means the connection cannot process new
3237/// messages while your handler is running. Use [`spawn`](Self::spawn) to offload any
3238/// expensive or blocking work to concurrent tasks.
3239///
3240/// See the [Event Loop and Concurrency](Builder#event-loop-and-concurrency) section
3241/// for more details.
3242#[derive(Clone, Debug)]
3243pub struct ConnectionTo<Counterpart: Role> {
3244    counterpart: Counterpart,
3245    message_tx: OutgoingMessageTx,
3246    task_tx: TaskTx,
3247    dynamic_handler_tx: mpsc::UnboundedSender<DynamicHandlerMessage<Counterpart>>,
3248    transport_completion: SharedTransportCompletion,
3249    pending_replies: PendingRepliesRegistrar,
3250    protocol_mode: ProtocolMode,
3251    incoming_closed: IncomingClosed,
3252    protected_operations: Arc<Mutex<ProtectedOperations>>,
3253    runner_error_scope: Option<run::RunnerErrorScope>,
3254}
3255
3256type SharedTransportCompletion = future::Shared<BoxFuture<'static, Result<(), crate::Error>>>;
3257
3258type SharedCompletionSignal = future::Shared<BoxFuture<'static, ()>>;
3259
3260#[derive(Default)]
3261struct ProtectedOperations {
3262    pending: Vec<oneshot::Receiver<()>>,
3263    joining: Option<SharedCompletionSignal>,
3264}
3265
3266impl Debug for ProtectedOperations {
3267    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3268        formatter
3269            .debug_struct("ProtectedOperations")
3270            .field("pending", &self.pending.len())
3271            .field("joining", &self.joining.is_some())
3272            .finish_non_exhaustive()
3273    }
3274}
3275
3276fn completion_signal() -> (oneshot::Sender<()>, SharedCompletionSignal) {
3277    let (tx, rx) = oneshot::channel();
3278    let signal = async move {
3279        // Dropping a sender (e.g. foreground failure) is not success.
3280        if rx.await.is_err() {
3281            future::pending::<()>().await;
3282        }
3283    }
3284    .boxed()
3285    .shared();
3286    (tx, signal)
3287}
3288
3289#[derive(Clone)]
3290struct IncomingClosed {
3291    state: Arc<IncomingClosedState>,
3292}
3293
3294struct IncomingClosedState {
3295    closing: AtomicBool,
3296    closed: AtomicBool,
3297    signal_tx: Mutex<Option<oneshot::Sender<()>>>,
3298    signal_rx: future::Shared<BoxFuture<'static, ()>>,
3299    shutdown_tx: Mutex<Option<oneshot::Sender<()>>>,
3300    #[cfg(any(feature = "unstable_mcp_over_acp", test))]
3301    shutdown_rx: SharedCompletionSignal,
3302    termination: Mutex<Option<ConnectionTermination>>,
3303    terminated_tx: Mutex<Option<oneshot::Sender<()>>>,
3304    terminated_rx: SharedCompletionSignal,
3305}
3306
3307impl IncomingClosed {
3308    fn new() -> Self {
3309        let (signal_tx, signal_rx) = oneshot::channel();
3310        let (shutdown_tx, shutdown_rx) = oneshot::channel();
3311        #[cfg(not(any(feature = "unstable_mcp_over_acp", test)))]
3312        drop(shutdown_rx);
3313        let (terminated_tx, terminated_rx) = oneshot::channel();
3314        Self {
3315            state: Arc::new(IncomingClosedState {
3316                closing: AtomicBool::new(false),
3317                closed: AtomicBool::new(false),
3318                signal_tx: Mutex::new(Some(signal_tx)),
3319                signal_rx: signal_rx.map(|_| ()).boxed().shared(),
3320                shutdown_tx: Mutex::new(Some(shutdown_tx)),
3321                #[cfg(any(feature = "unstable_mcp_over_acp", test))]
3322                shutdown_rx: shutdown_rx.map(|_| ()).boxed().shared(),
3323                termination: Mutex::new(None),
3324                terminated_tx: Mutex::new(Some(terminated_tx)),
3325                terminated_rx: terminated_rx.map(|_| ()).boxed().shared(),
3326            }),
3327        }
3328    }
3329
3330    fn begin_close(&self) {
3331        self.state.closing.store(true, Ordering::Release);
3332        self.request_shutdown();
3333    }
3334
3335    fn request_shutdown(&self) {
3336        if let Some(tx) = self
3337            .state
3338            .shutdown_tx
3339            .lock()
3340            .expect("shutdown signal mutex poisoned")
3341            .take()
3342        {
3343            let _ = tx.send(());
3344        }
3345    }
3346
3347    /// Whether the connection has begun shutting down (incoming EOF, a
3348    /// finished foreground, an actor error) or has already terminated.
3349    fn is_shutting_down(&self) -> bool {
3350        self.state
3351            .shutdown_tx
3352            .lock()
3353            .expect("shutdown signal mutex poisoned")
3354            .is_none()
3355            || self.termination().is_some()
3356    }
3357
3358    fn finish_close(&self) {
3359        self.state.closed.store(true, Ordering::Release);
3360        let signal_tx = self
3361            .state
3362            .signal_tx
3363            .lock()
3364            .expect("incoming-close signal mutex poisoned")
3365            .take();
3366
3367        if let Some(signal_tx) = signal_tx {
3368            let _ = signal_tx.send(());
3369        }
3370    }
3371
3372    async fn closed(&self) {
3373        self.state.signal_rx.clone().await;
3374    }
3375
3376    fn is_closed(&self) -> bool {
3377        self.state.closed.load(Ordering::Acquire)
3378    }
3379
3380    fn is_closing(&self) -> bool {
3381        self.state.closing.load(Ordering::Acquire)
3382    }
3383
3384    /// Record the termination reason. Returns `false` if one was already set.
3385    fn set_termination(&self, termination: ConnectionTermination) -> bool {
3386        let mut slot = self
3387            .state
3388            .termination
3389            .lock()
3390            .expect("termination mutex poisoned");
3391        if slot.is_some() {
3392            return false;
3393        }
3394        *slot = Some(termination);
3395        true
3396    }
3397
3398    fn signal_terminated(&self) {
3399        if let Some(tx) = self
3400            .state
3401            .terminated_tx
3402            .lock()
3403            .expect("terminated signal mutex poisoned")
3404            .take()
3405        {
3406            let _ = tx.send(());
3407        }
3408    }
3409
3410    fn termination(&self) -> Option<ConnectionTermination> {
3411        self.state
3412            .termination
3413            .lock()
3414            .expect("termination mutex poisoned")
3415            .clone()
3416    }
3417
3418    async fn terminated(&self) -> ConnectionTermination {
3419        self.state.terminated_rx.clone().await;
3420        self.termination()
3421            .expect("termination is recorded before it is signalled")
3422    }
3423}
3424
3425/// Publishes the connection's termination exactly once: when the driver
3426/// completes via [`Self::finish`], or synchronously when the driver future is
3427/// dropped first.
3428struct TerminationGuard {
3429    incoming_closed: IncomingClosed,
3430    pending_replies: PendingReplies,
3431}
3432
3433impl TerminationGuard {
3434    fn finish(self, termination: ConnectionTermination) {
3435        self.publish(termination);
3436    }
3437
3438    fn publish(&self, termination: ConnectionTermination) {
3439        if !self.incoming_closed.set_termination(termination.clone()) {
3440            return;
3441        }
3442        // Record first, so a requester woken by its failure observes the
3443        // termination; then fail requests before waking `terminated()`.
3444        let pending_reply_count = self.pending_replies.terminate(&termination);
3445        tracing::debug!(
3446            termination = termination.kind(),
3447            pending_reply_count,
3448            "Connection terminated"
3449        );
3450        self.incoming_closed.signal_terminated();
3451    }
3452}
3453
3454impl Drop for TerminationGuard {
3455    fn drop(&mut self) {
3456        // No-op after `finish`.
3457        self.publish(ConnectionTermination::Dropped);
3458    }
3459}
3460
3461impl Debug for IncomingClosed {
3462    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3463        formatter
3464            .debug_struct("IncomingClosed")
3465            .field("is_closing", &self.is_closing())
3466            .field("is_closed", &self.is_closed())
3467            .finish_non_exhaustive()
3468    }
3469}
3470
3471/// Stable discriminator stored in the `data.reason` field of errors produced
3472/// when the incoming transport reaches clean EOF before a request receives its
3473/// response.
3474///
3475/// The `data` field is informational. Use [`is_incoming_transport_closed`] to
3476/// detect these errors: a peer can send this value in its own error data.
3477pub const INCOMING_TRANSPORT_CLOSED_REASON: &str = "incoming_transport_closed";
3478
3479/// Return whether `error` reports that the incoming transport reached clean
3480/// EOF before a request received its response.
3481///
3482/// Only errors the SDK produced for its own connection match. An error
3483/// response received from a peer never does, even when its `data.reason` is
3484/// [`INCOMING_TRANSPORT_CLOSED_REASON`], and neither does an error built from
3485/// the same code, message, and data.
3486#[must_use]
3487pub fn is_incoming_transport_closed(error: &crate::Error) -> bool {
3488    error.origin == crate::error::ErrorOrigin::IncomingTransportClosed
3489}
3490
3491fn incoming_transport_closed_error(method: &str) -> crate::Error {
3492    let mut error = crate::Error::internal_error();
3493    error.message = "Incoming transport closed".to_string();
3494    error.origin = crate::error::ErrorOrigin::IncomingTransportClosed;
3495    error.data(serde_json::json!({
3496        "reason": INCOMING_TRANSPORT_CLOSED_REASON,
3497        "method": method,
3498    }))
3499}
3500
3501/// Unlike the cleanup coordinator below, check success before polling delivery:
3502/// an already-ready success must not resume a message handler into another
3503/// dispatch.
3504fn run_incoming_until_foreground_succeeds(
3505    incoming: impl Future<Output = Result<(), crate::Error>>,
3506    foreground_succeeded: SharedCompletionSignal,
3507    incoming_closed: IncomingClosed,
3508) -> impl Future<Output = Result<(), crate::Error>> {
3509    let mut incoming = Box::pin(incoming);
3510    future::poll_fn(move |cx| {
3511        if foreground_succeeded.clone().poll_unpin(cx).is_ready() && !incoming_closed.is_closing() {
3512            return std::task::Poll::Ready(Ok(()));
3513        }
3514        // A close callback already underway is protected. Its result is polled
3515        // before stopping, so callback errors retain their existing precedence.
3516        incoming.as_mut().poll(cx)
3517    })
3518}
3519
3520/// Run the connection background alongside its foreground while ensuring that
3521/// a foreground woken by incoming EOF cannot cancel close callbacks midway.
3522fn run_until_connection_close<R>(
3523    background: impl Future<Output = Result<(), crate::Error>>,
3524    foreground: impl Future<Output = Result<R, crate::Error>>,
3525    incoming_closed: IncomingClosed,
3526) -> impl Future<Output = Result<R, crate::Error>> {
3527    // Box these before constructing the returned future. Keeping the generic
3528    // connection actors directly in this async state would substantially grow
3529    // every `connect_*` future.
3530    let background = Box::pin(background);
3531    let foreground = Box::pin(foreground);
3532
3533    async move {
3534        match future::select(background, foreground).await {
3535            Either::Left((background_result, foreground)) => {
3536                background_result?;
3537                foreground.await
3538            }
3539            Either::Right((foreground_result, background)) => {
3540                if !incoming_closed.is_closing() {
3541                    return foreground_result;
3542                }
3543
3544                match future::select(background, Box::pin(incoming_closed.closed())).await {
3545                    Either::Left((background_result, _)) => {
3546                        background_result?;
3547                        foreground_result
3548                    }
3549                    Either::Right(((), background)) => {
3550                        // Poll the background first once more so an error returned
3551                        // by the just-finished close callback wins over the ready
3552                        // foreground result.
3553                        crate::util::run_until(background, future::ready(foreground_result)).await
3554                    }
3555                }
3556            }
3557        }
3558    }
3559}
3560
3561impl<Counterpart: Role> ConnectionTo<Counterpart> {
3562    fn new(
3563        counterpart: Counterpart,
3564        message_tx: mpsc::UnboundedSender<OutgoingMessage>,
3565        task_tx: mpsc::UnboundedSender<Task>,
3566        dynamic_handler_tx: mpsc::UnboundedSender<DynamicHandlerMessage<Counterpart>>,
3567        transport_completion: SharedTransportCompletion,
3568        pending_replies: PendingRepliesRegistrar,
3569        protocol_mode: ProtocolMode,
3570    ) -> Self {
3571        Self {
3572            counterpart,
3573            message_tx,
3574            task_tx,
3575            dynamic_handler_tx,
3576            transport_completion,
3577            pending_replies,
3578            protocol_mode,
3579            incoming_closed: IncomingClosed::new(),
3580            protected_operations: Arc::default(),
3581            runner_error_scope: None,
3582        }
3583    }
3584
3585    pub(crate) fn with_runner_error_scope(mut self, scope: run::RunnerErrorScope) -> Self {
3586        self.runner_error_scope = Some(scope);
3587        self
3588    }
3589
3590    pub(crate) fn finish_runner_error(
3591        &self,
3592        error: crate::Error,
3593    ) -> impl Future<Output = ()> + Send + '_ {
3594        if let Some(scope) = &self.runner_error_scope {
3595            Either::Left(scope.finish(error))
3596        } else {
3597            // Unscoped runners belong to the connection itself.
3598            self.request_shutdown();
3599            Either::Right(self.wait_protected_operations())
3600        }
3601    }
3602
3603    /// Spawn only a connection-owned supervisor whose async cleanup must finish
3604    /// before the driver returns. Ordinary application work must use `spawn`.
3605    #[cfg(any(feature = "unstable_mcp_over_acp", test))]
3606    #[track_caller]
3607    pub(crate) fn spawn_protected(
3608        &self,
3609        task: impl IntoFuture<Output = Result<(), crate::Error>, IntoFuture: Send + 'static>,
3610    ) -> Result<(), crate::Error> {
3611        let mut state = self
3612            .protected_operations
3613            .lock()
3614            .expect("protected operations mutex poisoned");
3615        if state.joining.is_some() {
3616            return Err(crate::Error::request_cancelled());
3617        }
3618        // Reap completed acknowledgments at admission, rather than retaining
3619        // every operation for the entire lifetime of the connection.
3620        state
3621            .pending
3622            .retain_mut(|done| matches!(done.try_recv(), Ok(None)));
3623        let (done_tx, done_rx) = oneshot::channel();
3624        let task = task.into_future();
3625        self.spawn(async move {
3626            let result = task.await;
3627            let _ = done_tx.send(());
3628            result
3629        })?;
3630        state.pending.push(done_rx);
3631        Ok(())
3632    }
3633
3634    pub(crate) async fn wait_protected_operations(&self) {
3635        let joining = {
3636            let mut state = self
3637                .protected_operations
3638                .lock()
3639                .expect("protected operations mutex poisoned");
3640            if state.joining.is_none() {
3641                let operations = std::mem::take(&mut state.pending);
3642                state.joining = Some(
3643                    async move {
3644                        for operation in operations {
3645                            let _ = operation.await;
3646                        }
3647                    }
3648                    .boxed()
3649                    .shared(),
3650                );
3651            }
3652            state.joining.as_ref().expect("join initialized").clone()
3653        };
3654        joining.await;
3655    }
3656
3657    pub(crate) fn request_shutdown(&self) {
3658        self.incoming_closed.request_shutdown();
3659    }
3660
3661    /// Early cancellation for owned native work, before close callbacks or drain.
3662    #[cfg(any(feature = "unstable_mcp_over_acp", test))]
3663    pub(crate) async fn shutdown_requested(&self) {
3664        self.incoming_closed.state.shutdown_rx.clone().await;
3665    }
3666
3667    /// Return the counterpart role this connection is talking to.
3668    pub fn counterpart(&self) -> Counterpart {
3669        self.counterpart.clone()
3670    }
3671
3672    /// Wait until the incoming transport reaches clean EOF.
3673    ///
3674    /// Transport closure means that no more messages or responses can arrive.
3675    /// Pending requests are failed first; this completes after registered
3676    /// [`Builder::on_close`] callbacks finish.
3677    /// It does not automatically cancel the future passed to
3678    /// [`Builder::connect_with`]; use [`Builder::on_close`] when the connection
3679    /// should run application-specific cleanup or terminate that future.
3680    ///
3681    /// This never completes if the connection ends some other way; use
3682    /// [`terminated`](Self::terminated) to observe every termination.
3683    pub async fn incoming_closed(&self) {
3684        self.incoming_closed.closed().await;
3685    }
3686
3687    /// Return whether clean incoming-EOF processing has completed.
3688    ///
3689    /// This remains `false` while [`Builder::on_close`] callbacks are running.
3690    #[must_use]
3691    pub fn is_incoming_closed(&self) -> bool {
3692        self.incoming_closed.is_closed()
3693    }
3694
3695    /// Wait until the connection driver has terminated, for any reason.
3696    ///
3697    /// This is the universal terminal event for a connection driven by
3698    /// [`Builder::connect_to`] or [`Builder::connect_with`]. Unlike
3699    /// [`incoming_closed`](Self::incoming_closed), it also completes after
3700    /// transport errors, handler or close-callback errors, foreground
3701    /// completion, and a dropped driver future.
3702    ///
3703    /// The termination is published once, synchronously, as the driver future
3704    /// returns (or is dropped). At that point:
3705    ///
3706    /// - No further handler, close callback, runner, or
3707    ///   [`spawn`](Self::spawn)ed task of this connection will run; each has
3708    ///   completed or been dropped.
3709    /// - Every request still awaiting a response has been failed. Requests
3710    ///   failed earlier by clean incoming EOF satisfy
3711    ///   [`is_incoming_transport_closed`](crate::is_incoming_transport_closed);
3712    ///   the rest satisfy [`is_connection_terminated`](crate::is_connection_terminated),
3713    ///   as do requests sent afterwards.
3714    ///
3715    /// Do not await this from inside the connection's own handlers, close
3716    /// callbacks, or tasks: termination happens only after they finish.
3717    ///
3718    /// Termination does not reap child processes owned by the transport, nor
3719    /// drain application-owned queues.
3720    pub async fn terminated(&self) -> ConnectionTermination {
3721        self.incoming_closed.terminated().await
3722    }
3723
3724    /// Return the termination reason if the connection driver has terminated.
3725    ///
3726    /// See [`terminated`](Self::terminated).
3727    #[must_use]
3728    pub fn termination(&self) -> Option<ConnectionTermination> {
3729        self.incoming_closed.termination()
3730    }
3731
3732    /// Stop accepting outgoing messages, drain routable output through the
3733    /// protocol actor, and finish cooperative physical sinks. Reactive serving also
3734    /// joins owned transport work after incoming EOF.
3735    async fn drain_outgoing(
3736        &self,
3737        finish: Option<crate::component::FinishControl>,
3738        wait_owned_transport: bool,
3739    ) -> Result<(), crate::Error> {
3740        let (done_tx, done_rx) = oneshot::channel();
3741        let marker_result = send_raw_message(
3742            &self.message_tx,
3743            OutgoingMessage::CloseAfterDraining { done: done_tx },
3744        );
3745        let marker_result = match marker_result {
3746            Ok(()) => done_rx.await.map_err(|error| {
3747                crate::util::internal_error(format!(
3748                    "outgoing drain marker was dropped before completion: {error}"
3749                ))
3750            }),
3751            Err(error) => Err(error),
3752        };
3753
3754        let physical_finish = finish.is_some();
3755        if let Some(mut finish) = finish {
3756            // Only finish the physical sink after the protocol actor has handed
3757            // off its accepted output. Closing it earlier races the drain.
3758            finish.request();
3759        }
3760        if physical_finish || wait_owned_transport {
3761            // Cooperative completion proves physical sink drain. Reactive serving
3762            // also waits for owned work after EOF (e.g. child exit status).
3763            self.transport_completion.clone().await?;
3764        }
3765        // Opaque application drivers have no physical finish contract. Keep
3766        // polling their errors in the background, but do not globally join work
3767        // which may intentionally run forever after the foreground returns.
3768        marker_result
3769    }
3770
3771    fn is_incoming_closing(&self) -> bool {
3772        self.incoming_closed.is_closing()
3773    }
3774
3775    pub(super) fn begin_incoming_close(&self) {
3776        self.incoming_closed.begin_close();
3777    }
3778
3779    pub(super) fn finish_incoming_close(&self) {
3780        self.incoming_closed.finish_close();
3781    }
3782
3783    /// Spawns a task that will run so long as the JSON-RPC connection is being served.
3784    ///
3785    /// This is the primary mechanism for offloading expensive work from handler callbacks
3786    /// to avoid blocking the event loop. Spawned tasks run concurrently with the connection,
3787    /// allowing the server to continue processing messages.
3788    ///
3789    /// # Event Loop
3790    ///
3791    /// Handler callbacks run on the event loop, which cannot process new messages while
3792    /// your handler is running. Use `spawn` for any expensive operations:
3793    ///
3794    /// ```no_run
3795    /// # use agent_client_protocol_test::*;
3796    /// # async fn example() -> Result<(), agent_client_protocol::Error> {
3797    /// # let connection = mock_connection();
3798    /// connection.on_receive_request(async |req: ProcessRequest, responder, cx| {
3799    ///     // Clone cx for the spawned task
3800    ///     cx.spawn({
3801    ///         let connection = cx.clone();
3802    ///         async move {
3803    ///             let result = expensive_operation(&req.data).await?;
3804    ///             connection.send_notification(ProcessComplete { result })?;
3805    ///             Ok(())
3806    ///         }
3807    ///     })?;
3808    ///
3809    ///     // Respond immediately
3810    ///     responder.respond(ProcessResponse { result: "started".into() })
3811    /// }, agent_client_protocol::on_receive_request!())
3812    /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
3813    /// # Ok(())
3814    /// # }
3815    /// ```
3816    ///
3817    /// # Errors
3818    ///
3819    /// Returns an error if the connection's task queue is closed. An error
3820    /// returned later by the spawned task shuts down the connection.
3821    #[track_caller]
3822    pub fn spawn(
3823        &self,
3824        task: impl IntoFuture<Output = Result<(), crate::Error>, IntoFuture: Send + 'static>,
3825    ) -> Result<(), crate::Error> {
3826        let location = std::panic::Location::caller();
3827        let task = task.into_future();
3828        Task::new(location, task).spawn(&self.task_tx)
3829    }
3830
3831    /// Spawn a JSON-RPC connection in the background and return the
3832    /// connection context its builder selects.
3833    ///
3834    /// This is useful for creating multiple connections that communicate with each other,
3835    /// such as implementing proxy patterns or connecting to multiple backend services.
3836    ///
3837    /// # Arguments
3838    ///
3839    /// - `builder`: The connection builder with handlers configured
3840    /// - `transport`: The transport component to connect to
3841    ///
3842    /// # Returns
3843    ///
3844    /// The connection type that `builder`'s callbacks receive: a raw
3845    /// [`ConnectionTo`] for a [`Raw`] builder such as [`Builder::new`], a
3846    /// [`v1::ConnectionTo`](crate::v1::ConnectionTo) for
3847    /// [`Client.v1()`](crate::Client::v1), and a `v2::ConnectionTo` for
3848    /// `Client.v2()`. Convert a typed connection back with `into_raw`.
3849    ///
3850    /// # Errors
3851    ///
3852    /// Returns an error if the parent connection cannot queue the child
3853    /// connection's task. It does not wait for the child to connect.
3854    ///
3855    /// # Example: Proxying to a backend connection
3856    ///
3857    /// ```
3858    /// # use agent_client_protocol::UntypedRole;
3859    /// # use agent_client_protocol::{Builder, ConnectionTo};
3860    /// # use agent_client_protocol_test::*;
3861    /// # async fn example(cx: ConnectionTo<UntypedRole>) -> Result<(), agent_client_protocol::Error> {
3862    /// // Set up a backend connection builder
3863    /// let backend = UntypedRole.builder()
3864    ///     .on_receive_request(async |req: MyRequest, responder, _cx| {
3865    ///         responder.respond(MyResponse { status: "ok".into() })
3866    ///     }, agent_client_protocol::on_receive_request!());
3867    ///
3868    /// // Spawn it and get a context to send requests to it
3869    /// let backend_connection = cx.spawn_connection(backend, MockTransport)?;
3870    ///
3871    /// // Now you can forward requests to the backend
3872    /// let response = backend_connection.send_request(MyRequest {}).block_task().await?;
3873    /// # Ok(())
3874    /// # }
3875    /// ```
3876    ///
3877    /// # Example: Spawning a v1 client
3878    ///
3879    /// ```no_run
3880    /// # use agent_client_protocol::{
3881    /// #     Agent, Client, ConnectTo, ConnectionTo, Error, UntypedRole, v1,
3882    /// # };
3883    /// # fn example(
3884    /// #     connection: ConnectionTo<UntypedRole>,
3885    /// #     transport: impl ConnectTo<Client> + 'static,
3886    /// # ) -> Result<(), Error> {
3887    /// let child: v1::ConnectionTo<Agent> = connection.spawn_connection(Client.v1(), transport)?;
3888    /// # drop(child);
3889    /// # Ok(())
3890    /// # }
3891    /// ```
3892    #[track_caller]
3893    pub fn spawn_connection<R: Role, P: Protocol>(
3894        &self,
3895        builder: Builder<
3896            R,
3897            impl HandleDispatchFrom<R::Counterpart> + 'static,
3898            impl RunWithConnectionTo<R::Counterpart> + 'static,
3899            impl HandleConnectionClose<R::Counterpart> + 'static,
3900            P,
3901        >,
3902        transport: impl ConnectTo<R> + 'static,
3903    ) -> Result<P::Connection<R::Counterpart>, crate::Error> {
3904        let (connection, future) =
3905            builder.into_connection_and_future(transport, false, |_| std::future::pending());
3906        Task::new(std::panic::Location::caller(), future).spawn(&self.task_tx)?;
3907        Ok(protocol::connection_from_raw::<P, _>(connection))
3908    }
3909
3910    /// The ACP protocol version of this connection's wire guard, or `None`
3911    /// when its builder applies no guard, as with [`Builder::new`].
3912    ///
3913    /// `Client.v1()`, `Agent.v1()` and `Proxy.v1()` connections report
3914    /// [`ProtocolVersion::V1`](crate::schema::ProtocolVersion::V1), and the
3915    /// `v2()` entry points report `ProtocolVersion::V2`.
3916    #[must_use]
3917    pub fn protocol_version(&self) -> Option<crate::schema::ProtocolVersion> {
3918        self.protocol_mode.api_protocol_version()
3919    }
3920
3921    /// The same connection, typed for protocol `P`.
3922    ///
3923    /// `into_protocol::<V1>()` returns a [`v1::ConnectionTo`](crate::v1::ConnectionTo)
3924    /// (and, with `unstable_protocol_v2`, `into_protocol::<V2>()` a
3925    /// `v2::ConnectionTo`), whose sends return request handles typed for that
3926    /// version and which carries that version's session helpers. Only the
3927    /// Rust API changes: the connection's wire guard is the one its builder
3928    /// selected. The versioned connections convert back with `into_raw`.
3929    ///
3930    /// # Errors
3931    ///
3932    /// Returns an Internal error (`-32603`) when the builder's guard selected
3933    /// a different version than `P`, for example `into_protocol::<V2>()` on a
3934    /// connection from `Client.v1()`. The mismatch is a local programming
3935    /// error, not a malformed message from the peer. A
3936    /// connection whose builder applies no guard (see
3937    /// [`protocol_version`](Self::protocol_version)) converts to every
3938    /// protocol, and `into_protocol::<Raw>()` never fails.
3939    ///
3940    /// ```
3941    /// # use agent_client_protocol::{Agent, ConnectionTo, Error, V1, v1};
3942    /// fn sessions(connection: ConnectionTo<Agent>) -> Result<v1::ConnectionTo<Agent>, Error> {
3943    ///     connection.into_protocol::<V1>()
3944    /// }
3945    /// ```
3946    pub fn into_protocol<P: Protocol>(self) -> Result<P::Connection<Counterpart>, crate::Error> {
3947        if let (Some(guard), Some(requested)) =
3948            (self.protocol_version(), protocol::protocol_version::<P>())
3949            && guard != requested
3950        {
3951            return Err(crate::Error::internal_error().data(format!(
3952                "cannot use a connection guarded for ACP protocol version {guard} \
3953                 as a protocol version {requested} connection",
3954            )));
3955        }
3956        Ok(protocol::connection_from_raw::<P, _>(self))
3957    }
3958
3959    /// Send a request/notification and forward the response appropriately.
3960    ///
3961    /// The request context's response type matches the request's response type,
3962    /// enabling type-safe message forwarding.
3963    ///
3964    /// # Errors
3965    ///
3966    /// Returns the forwarding error from [`send_proxied_message_to`](Self::send_proxied_message_to).
3967    pub fn send_proxied_message<
3968        Req: JsonRpcRequest<Response: Send>,
3969        Notif: JsonRpcNotification,
3970        Q: Protocol,
3971    >(
3972        &self,
3973        message: Dispatch<Req, Notif, Q>,
3974    ) -> Result<(), crate::Error>
3975    where
3976        Counterpart: HasPeer<Counterpart>,
3977    {
3978        self.send_proxied_message_to(self.counterpart(), message)
3979    }
3980
3981    /// Send a request/notification and forward the response appropriately.
3982    ///
3983    /// The request context's response type matches the request's response type,
3984    /// enabling type-safe message forwarding.
3985    ///
3986    /// `$/cancel_request` notifications are *not* forwarded: their `requestId`
3987    /// refers to a request on the connection they arrived over and would be
3988    /// meaningless to `peer`. Cancellation instead propagates hop by hop,
3989    /// because the responders passed to
3990    /// [`forward_response_to`](SentRequest::forward_response_to) observe it
3991    /// and re-issue the cancellation with the forwarded request's own ID.
3992    /// A proxy forwarding an `elicitation/create` from its successor to its
3993    /// client also translates `params.requestId` back to that client's ID.
3994    ///
3995    /// # Errors
3996    ///
3997    /// Returns an error if a notification cannot be encoded or queued, or if
3998    /// response forwarding cannot be scheduled for a request. A downstream
3999    /// request error is sent to the upstream responder, not returned here.
4000    pub fn send_proxied_message_to<
4001        Peer: Role,
4002        Req: JsonRpcRequest<Response: Send>,
4003        Notif: JsonRpcNotification,
4004        Q: Protocol,
4005    >(
4006        &self,
4007        peer: Peer,
4008        message: Dispatch<Req, Notif, Q>,
4009    ) -> Result<(), crate::Error>
4010    where
4011        Counterpart: HasPeer<Peer>,
4012    {
4013        match message {
4014            Dispatch::Request(request, responder) => self
4015                .prepare_request_to(peer, request)
4016                .forward_response_to(responder),
4017            Dispatch::Notification(notification) => {
4018                // `$/cancel_request` is connection-scoped: its `requestId` was
4019                // allocated on the connection the notification arrived over
4020                // and means nothing to `peer`. The cancellation has already
4021                // been recorded on this connection's responder markers, and
4022                // `forward_response_to` re-issues it for the forwarded request
4023                // with the correct per-hop ID, so drop the raw notification
4024                // instead of tunneling a meaningless ID across the hop.
4025                if is_cancel_request_notification(&notification) {
4026                    tracing::debug!(
4027                        "not forwarding hop-scoped `$/cancel_request` notification across proxy hop"
4028                    );
4029                    return Ok(());
4030                }
4031                self.send_notification_to(peer, notification)
4032            }
4033            Dispatch::Response(result, router) => {
4034                // Responses are forwarded directly to their destination
4035                router.route_with_result(result)
4036            }
4037        }
4038    }
4039
4040    /// Restore the originator's ID in a request-scoped elicitation received from this peer.
4041    ///
4042    /// Used by the conductor on ingress, before enqueueing a dispatch for its
4043    /// fixed predecessor. Reading a later response can retire the association.
4044    /// A reference that cannot be resolved on this hop is invalid. Forwarding
4045    /// it unchanged could accidentally match an unrelated upstream request.
4046    #[doc(hidden)]
4047    pub fn translate_elicitation_request_id<Peer: Role>(
4048        &self,
4049        peer: Peer,
4050        message: &mut Dispatch,
4051    ) -> Result<(), crate::Error>
4052    where
4053        Counterpart: HasPeer<Peer>,
4054    {
4055        let Dispatch::Request(request, _) = message else {
4056            return Ok(());
4057        };
4058        // The conductor owns these routes: each component has a fixed predecessor.
4059        self.pending_replies
4060            .translate_elicitation(peer.role_id(), request, |_| true)
4061    }
4062
4063    /// Send an outgoing request and return a [`SentRequest`] for handling the reply.
4064    ///
4065    /// The returned [`SentRequest`] makes the response-consumption mode explicit:
4066    ///
4067    /// * [`on_receiving_result`](SentRequest::on_receiving_result) - Register a callback and
4068    ///   return immediately. If registered before the response is routed during its original
4069    ///   dispatch, the loop waits for the callback to complete.
4070    /// * [`block_task`](SentRequest::block_task) - Wait on the current task until the response
4071    ///   arrives. This is only safe when that task already runs outside the dispatch loop.
4072    ///
4073    /// For callback ordering selected before publication, use
4074    /// [`prepare_request`](Self::prepare_request) instead. Even an immediately
4075    /// chained callback can race with a fast response on a concurrent connection.
4076    ///
4077    /// # Anti-Footgun Design
4078    ///
4079    /// The API intentionally makes it difficult to block on the result directly to prevent
4080    /// the common mistake of blocking the event loop while waiting for a response:
4081    ///
4082    /// ```compile_fail
4083    /// # use agent_client_protocol_test::*;
4084    /// # async fn example(cx: agent_client_protocol::ConnectionTo<agent_client_protocol::UntypedRole>) -> Result<(), agent_client_protocol::Error> {
4085    /// // ❌ This doesn't compile - prevents blocking the event loop
4086    /// let response = cx.send_request(MyRequest {}).await?;
4087    /// # Ok(())
4088    /// # }
4089    /// ```
4090    ///
4091    /// ```no_run
4092    /// # use agent_client_protocol_test::*;
4093    /// # async fn example(cx: agent_client_protocol::ConnectionTo<agent_client_protocol::UntypedRole>) -> Result<(), agent_client_protocol::Error> {
4094    /// // ✅ Option 1: Register an ordered callback (safe in handlers)
4095    /// cx.send_request(MyRequest {})
4096    ///     .on_receiving_result(async |result| {
4097    ///         // Handle the response
4098    ///         Ok(())
4099    ///     })?;
4100    ///
4101    /// // ✅ Option 2: Block in spawned task (safe because task is concurrent)
4102    /// cx.spawn({
4103    ///     let cx = cx.clone();
4104    ///     async move {
4105    ///         let response = cx.send_request(MyRequest {})
4106    ///             .block_task()
4107    ///             .await?;
4108    ///         // Process response...
4109    ///         Ok(())
4110    ///     }
4111    /// })?;
4112    /// # Ok(())
4113    /// # }
4114    /// ```
4115    /// Send an outgoing request to the default counterpart peer.
4116    ///
4117    /// This is a convenience method that sends to the counterpart role `R`.
4118    /// For explicit control over the target peer, use [`send_request_to`](Self::send_request_to).
4119    pub fn send_request<Req: JsonRpcRequest>(&self, request: Req) -> SentRequest<Req::Response>
4120    where
4121        Counterpart: HasPeer<Counterpart>,
4122    {
4123        self.send_request_to(self.counterpart.clone(), request)
4124    }
4125
4126    /// Send an outgoing request to a specific peer.
4127    ///
4128    /// The message will be transformed according to the [`HasPeer`](crate::role::HasPeer)
4129    /// implementation before being sent.
4130    pub fn send_request_to<Peer: Role, Req: JsonRpcRequest>(
4131        &self,
4132        peer: Peer,
4133        request: Req,
4134    ) -> SentRequest<Req::Response>
4135    where
4136        Counterpart: HasPeer<Peer>,
4137    {
4138        self.send_request_to_with_options(peer, request, false, None, None)
4139    }
4140
4141    /// Prepare a request without sending it until response handling is selected.
4142    ///
4143    /// Unlike [`send_request`](Self::send_request), this does not register a
4144    /// pending reply or enqueue the request. A consuming method on the returned
4145    /// [`PreparedRequest`] publishes it synchronously. Callback-style methods
4146    /// select ordered consumption before publication, closing the race with a
4147    /// fast peer response even when the connection runs on another task.
4148    ///
4149    /// Dropping the prepared request sends nothing. See [`PreparedRequest`] for
4150    /// the available consumption modes and their error and cancellation behavior.
4151    ///
4152    /// # Examples
4153    ///
4154    /// ```no_run
4155    /// # use agent_client_protocol::{ConnectionTo, Error, UntypedRole};
4156    /// # use agent_client_protocol_test::MyRequest;
4157    /// # fn example(connection: ConnectionTo<UntypedRole>) -> Result<(), Error> {
4158    /// connection.prepare_request(MyRequest {}).on_receiving_result(async |result| {
4159    ///     let response = result?;
4160    ///     // Apply bounded response work before later inbound messages.
4161    ///     Ok(())
4162    /// })?;
4163    /// # Ok(())
4164    /// # }
4165    /// ```
4166    pub fn prepare_request<Req: JsonRpcRequest>(
4167        &self,
4168        request: Req,
4169    ) -> PreparedRequest<Req::Response>
4170    where
4171        Counterpart: HasPeer<Counterpart>,
4172    {
4173        self.prepare_request_to(self.counterpart.clone(), request)
4174    }
4175
4176    /// Prepare a request to a specific peer without sending it.
4177    ///
4178    /// The request is serialized now. A consuming method synchronously registers
4179    /// its pending reply and enqueues the request; peer transformation and
4180    /// transmission happen later in the connection driver.
4181    /// See [`prepare_request`](Self::prepare_request).
4182    pub fn prepare_request_to<Peer: Role, Req: JsonRpcRequest>(
4183        &self,
4184        peer: Peer,
4185        request: Req,
4186    ) -> PreparedRequest<Req::Response>
4187    where
4188        Counterpart: HasPeer<Peer>,
4189    {
4190        self.prepare_request_to_with_options(peer, request, None, None)
4191    }
4192
4193    /// Prepare a request and run a synchronous side effect when its valid success
4194    /// response is routed, after `before_send` completes and independently
4195    /// from how the returned request is eventually consumed.
4196    #[cfg(feature = "unstable_protocol_v2")]
4197    pub(crate) fn prepare_request_to_with_response_hook_after<
4198        P: Protocol,
4199        Peer: Role,
4200        Req: JsonRpcRequest,
4201        BeforeSend: Future<Output = Result<(), crate::Error>> + Send + 'static,
4202    >(
4203        &self,
4204        peer: Peer,
4205        request: Req,
4206        before_send: BeforeSend,
4207        response_hook: impl FnOnce(&Req::Response) -> Result<(), crate::Error> + Send + 'static,
4208    ) -> PreparedRequest<Req::Response, P>
4209    where
4210        Counterpart: HasPeer<Peer>,
4211    {
4212        let hook: ResponseRouteHook = Box::new(move |method, value| {
4213            let response = Req::Response::from_json(method, value.clone())?;
4214            response_hook(&response)
4215        });
4216        self.prepare_request_to_with_options(
4217            peer,
4218            request,
4219            Some(RequestReadiness::new(before_send)),
4220            Some(hook),
4221        )
4222    }
4223
4224    /// Send a request whose callback must run before later inbound messages.
4225    ///
4226    /// The ordering marker is installed before the request enters the outgoing
4227    /// queue, closing the race between a fast peer response and the immediate
4228    /// [`SentRequest::on_receiving_result`] call. Callers must consume the
4229    /// returned request with a callback-style method without yielding.
4230    pub(crate) fn send_ordered_request_to<P: Protocol, Peer: Role, Req: JsonRpcRequest>(
4231        &self,
4232        peer: Peer,
4233        request: Req,
4234    ) -> SentRequest<Req::Response, P>
4235    where
4236        Counterpart: HasPeer<Peer>,
4237    {
4238        self.send_request_to_with_options(peer, request, true, None, None)
4239    }
4240
4241    /// Send an ordered request after `before_send` completes successfully.
4242    ///
4243    /// The ordering marker and readiness prerequisite are both registered
4244    /// before the request enters the outgoing queue. This is used by framework
4245    /// setup paths that must acknowledge local routing before the peer can
4246    /// observe the request.
4247    pub(crate) fn send_ordered_request_to_after<
4248        P: Protocol,
4249        Peer: Role,
4250        Req: JsonRpcRequest,
4251        BeforeSend: Future<Output = Result<(), crate::Error>> + Send + 'static,
4252    >(
4253        &self,
4254        peer: Peer,
4255        request: Req,
4256        before_send: BeforeSend,
4257    ) -> SentRequest<Req::Response, P>
4258    where
4259        Counterpart: HasPeer<Peer>,
4260    {
4261        self.send_request_to_with_options(
4262            peer,
4263            request,
4264            true,
4265            Some(RequestReadiness::new(before_send)),
4266            None,
4267        )
4268    }
4269
4270    fn send_request_to_with_options<P: Protocol, Peer: Role, Req: JsonRpcRequest>(
4271        &self,
4272        peer: Peer,
4273        request: Req,
4274        ordered: bool,
4275        readiness: Option<RequestReadiness>,
4276        response_route_hook: Option<ResponseRouteHook>,
4277    ) -> SentRequest<Req::Response, P>
4278    where
4279        Counterpart: HasPeer<Peer>,
4280    {
4281        self.prepare_request_to_with_options(peer, request, readiness, response_route_hook)
4282            .into_sent_request(ordered)
4283    }
4284
4285    fn prepare_request_to_with_options<P: Protocol, Peer: Role, Req: JsonRpcRequest>(
4286        &self,
4287        peer: Peer,
4288        request: Req,
4289        readiness: Option<RequestReadiness>,
4290        response_route_hook: Option<ResponseRouteHook>,
4291    ) -> PreparedRequest<Req::Response, P>
4292    where
4293        Counterpart: HasPeer<Peer>,
4294    {
4295        let method = request.method().to_string();
4296        let id = HandleId::<P>::generated(Uuid::new_v4().to_string());
4297        let (response_tx, response_rx) = oneshot::channel();
4298        let response_ordering = ResponseOrdering::default();
4299        let role_id = peer.role_id();
4300        let remote_style = self.counterpart.remote_style(peer);
4301        let cancellation = SentRequestCancellation::new(self.message_tx.clone(), id.raw().clone());
4302        let pending_reply = PendingReply {
4303            id: id.raw().clone(),
4304            method: method.clone(),
4305            role_id,
4306            sender: response_tx,
4307            cancellation_disarm: cancellation.disarm_handle(),
4308            ordering: response_ordering.clone(),
4309            response_route_hook,
4310            forwarded_from: None,
4311            accepts_lower_initialize_version: false,
4312        };
4313        let message = if self.is_incoming_closing() {
4314            Err(incoming_transport_closed_error(&method))
4315        } else {
4316            request
4317                .to_untyped_message()
4318                .map(|untyped| OutgoingMessage::Request {
4319                    id: id.raw().clone(),
4320                    method: method.clone(),
4321                    untyped,
4322                    remote_style,
4323                    readiness,
4324                })
4325                .map_err(|error| {
4326                    crate::util::internal_error(format!(
4327                        "failed to create untyped request for `{method}`: {error}"
4328                    ))
4329                })
4330        };
4331        let sent = SentRequest::new(
4332            id,
4333            method.clone(),
4334            self.task_tx.clone(),
4335            self.pending_replies.clone(),
4336            response_rx,
4337            cancellation,
4338            response_ordering,
4339        )
4340        .map(move |json| <Req::Response>::from_json(&method, json));
4341        PreparedRequest {
4342            sent,
4343            publication: RequestPublication {
4344                message,
4345                pending_reply,
4346                message_tx: self.message_tx.clone(),
4347                pending_replies: self.pending_replies.clone(),
4348                incoming_closed: self.incoming_closed.clone(),
4349            },
4350        }
4351    }
4352
4353    /// Send an outgoing notification to the default counterpart peer (no reply expected).
4354    ///
4355    /// Notifications are fire-and-forget messages that don't have IDs and don't expect responses.
4356    /// This method sends the notification immediately and returns.
4357    ///
4358    /// This is a convenience method that sends to the counterpart role `R`.
4359    /// For explicit control over the target peer, use [`send_notification_to`](Self::send_notification_to).
4360    ///
4361    /// # Errors
4362    ///
4363    /// Returns an error if the notification cannot be encoded or queued.
4364    ///
4365    /// ```no_run
4366    /// # use agent_client_protocol_test::*;
4367    /// # async fn example(cx: agent_client_protocol::ConnectionTo<agent_client_protocol::Agent>) -> Result<(), agent_client_protocol::Error> {
4368    /// cx.send_notification(StatusUpdate {
4369    ///     message: "Processing...".into(),
4370    /// })?;
4371    /// # Ok(())
4372    /// # }
4373    /// ```
4374    pub fn send_notification<N: JsonRpcNotification>(
4375        &self,
4376        notification: N,
4377    ) -> Result<(), crate::Error>
4378    where
4379        Counterpart: HasPeer<Counterpart>,
4380    {
4381        self.send_notification_to(self.counterpart.clone(), notification)
4382    }
4383
4384    /// Send an outgoing notification to a specific peer (no reply expected).
4385    ///
4386    /// The message will be transformed according to the [`HasPeer`](crate::role::HasPeer)
4387    /// implementation before being sent.
4388    ///
4389    /// # Errors
4390    ///
4391    /// Returns an error if the notification cannot be encoded for the peer or
4392    /// the outgoing queue is closed. This does not wait for wire delivery.
4393    pub fn send_notification_to<Peer: Role, N: JsonRpcNotification>(
4394        &self,
4395        peer: Peer,
4396        notification: N,
4397    ) -> Result<(), crate::Error>
4398    where
4399        Counterpart: HasPeer<Peer>,
4400    {
4401        let remote_style = self.counterpart.remote_style(peer);
4402        tracing::debug!(
4403            role = std::any::type_name::<Counterpart>(),
4404            peer = std::any::type_name::<Peer>(),
4405            notification_type = std::any::type_name::<N>(),
4406            ?remote_style,
4407            original_method = notification.method(),
4408            "send_notification_to"
4409        );
4410        let transformed = remote_style.transform_outgoing_message(notification)?;
4411        tracing::debug!(
4412            transformed_method = %transformed.method,
4413            "send_notification_to transformed"
4414        );
4415        send_raw_message(
4416            &self.message_tx,
4417            OutgoingMessage::Notification {
4418                untyped: transformed,
4419            },
4420        )
4421    }
4422
4423    /// Send a `$/cancel_request` notification for an arbitrary request ID to
4424    /// the default counterpart peer.
4425    ///
4426    /// Prefer [`SentRequest::cancel`] when you have the request handle: it
4427    /// already knows the correct request ID. Use this low-level method only
4428    /// when implementing custom routing with a request ID that is valid on
4429    /// this connection.
4430    ///
4431    /// # Errors
4432    ///
4433    /// Returns an error if the cancellation notification cannot be encoded or queued.
4434    pub fn send_cancel_request(
4435        &self,
4436        request_id: impl Into<RawJsonRpcId>,
4437    ) -> Result<(), crate::Error>
4438    where
4439        Counterpart: HasPeer<Counterpart>,
4440    {
4441        self.send_cancel_request_to(self.counterpart.clone(), request_id)
4442    }
4443
4444    /// Send a `$/cancel_request` notification for an arbitrary request ID to a
4445    /// specific peer.
4446    ///
4447    /// `$/cancel_request` is hop-local, so the notification is always sent
4448    /// plain, never wrapped in `proxy/successor`, even to a proxy's
4449    /// successor. To cancel a request sent to a successor, pass the ID of the
4450    /// `proxy/successor` request on this connection.
4451    ///
4452    /// Prefer [`SentRequest::cancel`] when you have the request handle: it
4453    /// already knows the correct request ID. Use this low-level method only
4454    /// when implementing custom routing with a request ID that is valid on
4455    /// this connection.
4456    ///
4457    /// # Errors
4458    ///
4459    /// Returns an error if the cancellation notification cannot be encoded or queued.
4460    /// It does not check whether the peer still has a pending request with this ID.
4461    pub fn send_cancel_request_to<Peer: Role>(
4462        &self,
4463        _peer: Peer,
4464        request_id: impl Into<RawJsonRpcId>,
4465    ) -> Result<(), crate::Error>
4466    where
4467        Counterpart: HasPeer<Peer>,
4468    {
4469        let untyped = crate::v1::schema::CancelRequestNotification::new(
4470            crate::v1::schema::RequestId::from(request_id.into()),
4471        )
4472        .to_untyped_message()?;
4473        send_raw_message(&self.message_tx, OutgoingMessage::Notification { untyped })
4474    }
4475
4476    /// Register a dynamic message handler, used to intercept messages specific to a particular session
4477    /// or some similar modal thing.
4478    ///
4479    /// Dynamic message handlers run after the handlers registered on [`Builder`] and before the
4480    /// role's default handler. They receive messages that the builder handlers decline.
4481    ///
4482    /// The handler will stay registered until the returned registration guard is dropped.
4483    ///
4484    /// # Errors
4485    ///
4486    /// Returns an error if the connection no longer accepts handler registrations.
4487    pub fn add_dynamic_handler(
4488        &self,
4489        handler: impl HandleDispatchFrom<Counterpart> + 'static,
4490    ) -> Result<DynamicHandlerGuard<Counterpart>, crate::Error> {
4491        let uuid = Uuid::new_v4();
4492        let active = Arc::new(AtomicBool::new(true));
4493        self.dynamic_handler_tx
4494            .unbounded_send(DynamicHandlerMessage::AddDynamicHandler(
4495                uuid,
4496                Box::new(GuardedDynamicHandler {
4497                    active: active.clone(),
4498                    handler,
4499                }),
4500                active.clone(),
4501            ))
4502            .map_err(crate::util::internal_error)?;
4503
4504        Ok(DynamicHandlerGuard::new(uuid, active, self.clone()))
4505    }
4506
4507    /// Wait until every dynamic-handler update queued before this call has
4508    /// been applied by the incoming protocol actor.
4509    pub(crate) fn dynamic_handler_barrier(&self) -> BoxFuture<'static, Result<(), crate::Error>> {
4510        let (acknowledgment_tx, acknowledgment_rx) = oneshot::channel();
4511        if let Err(error) =
4512            self.dynamic_handler_tx
4513                .unbounded_send(DynamicHandlerMessage::AcknowledgedBarrier(
4514                    acknowledgment_tx,
4515                ))
4516        {
4517            return future::ready(Err(crate::Error::into_internal_error(error))).boxed();
4518        }
4519
4520        async move {
4521            acknowledgment_rx.await.map_err(|error| {
4522                crate::util::internal_error(format!(
4523                    "dynamic-handler barrier was dropped before acknowledgment: {error}"
4524                ))
4525            })
4526        }
4527        .boxed()
4528    }
4529
4530    fn remove_dynamic_handler(&self, uuid: Uuid) {
4531        // Ignore errors
4532        drop(
4533            self.dynamic_handler_tx
4534                .unbounded_send(DynamicHandlerMessage::RemoveDynamicHandler(uuid)),
4535        );
4536    }
4537}
4538
4539struct GuardedDynamicHandler<Handler> {
4540    active: Arc<AtomicBool>,
4541    handler: Handler,
4542}
4543
4544impl<Counterpart, Handler> HandleDispatchFrom<Counterpart> for GuardedDynamicHandler<Handler>
4545where
4546    Counterpart: Role,
4547    Handler: HandleDispatchFrom<Counterpart>,
4548{
4549    async fn handle_dispatch_from(
4550        &mut self,
4551        message: Dispatch,
4552        connection: ConnectionTo<Counterpart>,
4553    ) -> Result<Handled<Dispatch>, crate::Error> {
4554        if !self.active.load(Ordering::Acquire) {
4555            return Ok(Handled::No {
4556                message,
4557                retry: false,
4558            });
4559        }
4560        self.handler.handle_dispatch_from(message, connection).await
4561    }
4562
4563    fn describe_chain(&self) -> impl Debug {
4564        self.handler.describe_chain()
4565    }
4566}
4567
4568/// A guard that keeps a dynamic message handler registered.
4569///
4570/// Dropping the guard immediately deactivates the handler and queues its
4571/// removal from the connection. Use [`detach`](Self::detach) to keep the
4572/// handler registered for the remaining lifetime of the connection.
4573#[must_use = "dropping this guard unregisters the dynamic handler"]
4574#[derive(Debug)]
4575pub struct DynamicHandlerGuard<R: Role> {
4576    uuid: Option<Uuid>,
4577    active: Arc<AtomicBool>,
4578    cx: ConnectionTo<R>,
4579    cleanup: Option<Arc<dyn DynamicHandlerCleanup>>,
4580}
4581
4582/// Private registration-local cleanup, independent of connection task admission.
4583pub(crate) trait DynamicHandlerCleanup: std::fmt::Debug + Send + Sync {
4584    fn close(&self);
4585    fn wait(&self) -> futures::future::BoxFuture<'static, ()>;
4586}
4587
4588impl<R: Role> DynamicHandlerGuard<R> {
4589    fn new(uuid: Uuid, active: Arc<AtomicBool>, cx: ConnectionTo<R>) -> Self {
4590        Self {
4591            uuid: Some(uuid),
4592            active,
4593            cx,
4594            cleanup: None,
4595        }
4596    }
4597
4598    #[cfg(feature = "unstable_mcp_over_acp")]
4599    pub(crate) fn with_cleanup(mut self, cleanup: Arc<dyn DynamicHandlerCleanup>) -> Self {
4600        self.cleanup = Some(cleanup);
4601        self
4602    }
4603
4604    pub(crate) fn cleanup(&self) -> Option<Arc<dyn DynamicHandlerCleanup>> {
4605        self.cleanup.clone()
4606    }
4607
4608    /// Stop the handler from claiming messages without queuing its removal.
4609    ///
4610    /// Until the guard is dropped, the incoming actor keeps unclaimed session
4611    /// requests parked for a replacement handler.
4612    pub(crate) fn deactivate(&self) {
4613        self.active.store(false, Ordering::Release);
4614    }
4615
4616    /// Keep the dynamic handler registered after this guard is dropped.
4617    ///
4618    /// The handler remains registered until the connection itself shuts down.
4619    /// Unlike leaking the guard, detaching does not retain an extra
4620    /// [`ConnectionTo`] handle.
4621    pub fn detach(mut self) {
4622        self.uuid = None;
4623    }
4624}
4625
4626impl<R: Role> Drop for DynamicHandlerGuard<R> {
4627    fn drop(&mut self) {
4628        if let Some(uuid) = self.uuid {
4629            self.active.store(false, Ordering::Release);
4630            if let Some(cleanup) = &self.cleanup {
4631                cleanup.close();
4632            }
4633            self.cx.remove_dynamic_handler(uuid);
4634        }
4635    }
4636}
4637
4638/// The context to respond to an incoming request.
4639///
4640/// This context is provided to request handlers and serves a dual role:
4641///
4642/// 1. **Respond to the request** - Use [`respond`](Self::respond) or
4643///    [`respond_with_result`](Self::respond_with_result) to send the response
4644/// 2. **Send other messages** - Use the [`ConnectionTo`] parameter passed to your
4645///    handler, which provides [`send_request`](`ConnectionTo::send_request`),
4646///    [`send_notification`](`ConnectionTo::send_notification`), and
4647///    [`spawn`](`ConnectionTo::spawn`)
4648///
4649/// # Example
4650///
4651/// ```no_run
4652/// # use agent_client_protocol_test::*;
4653/// # async fn example() -> Result<(), agent_client_protocol::Error> {
4654/// # let connection = mock_connection();
4655/// connection.on_receive_request(async |req: ProcessRequest, responder, cx| {
4656///     // Send a notification while processing
4657///     cx.send_notification(StatusUpdate {
4658///         message: "processing".into(),
4659///     })?;
4660///
4661///     // Do some work...
4662///     let result = process(&req.data)?;
4663///
4664///     // Respond to the request
4665///     responder.respond(ProcessResponse { result })
4666/// }, agent_client_protocol::on_receive_request!())
4667/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
4668/// # Ok(())
4669/// # }
4670/// ```
4671///
4672/// # Event Loop Considerations
4673///
4674/// Like all handlers, request handlers run on the event loop. Use
4675/// [`spawn`](ConnectionTo::spawn) for expensive operations to avoid blocking
4676/// the connection.
4677///
4678/// See the [Event Loop and Concurrency](Builder#event-loop-and-concurrency)
4679/// section for more details.
4680///
4681/// # Drop behavior
4682///
4683/// A request must be answered. If a responder for a request is dropped
4684/// without a response having been sent through it, the SDK answers the
4685/// request itself with an error, so the peer is never left waiting:
4686///
4687/// - `-32800` ([`Error::request_cancelled`]) if the peer had cancelled the
4688///   request with `$/cancel_request`;
4689/// - otherwise `-32603` ([`Error::internal_error`]), with data naming the
4690///   method whose responder was dropped.
4691///
4692/// No automatic response is sent when:
4693///
4694/// - a response was already sent through the responder (any of the
4695///   `respond*` methods), or the responder was handed to something that
4696///   answers through it (such as
4697///   [`SentRequest::forward_response_to`]) — only dropping the responder
4698///   itself without responding triggers the fallback;
4699/// - the responder was moved into another owner (another task, a wrapped
4700///   responder from [`cast`](Self::cast) or [`wrap_params`](Self::wrap_params),
4701///   a retried [`Dispatch`]); that owner's eventual drop is what counts;
4702/// - the connection is shutting down or has terminated.
4703///
4704/// When a handler drops the responder and then returns an error, that error
4705/// is the response instead of the generic fallback.
4706///
4707/// The automatic error is an ordinary error response: for example, a dropped
4708/// `initialize` responder fails initialization just as an explicit error
4709/// would.
4710///
4711/// # Protocol version
4712///
4713/// `P` is the [`Protocol`] marker and selects the type [`id`](Self::id)
4714/// returns. Typed handlers on `Client.v1()`, `Agent.v1()` and
4715/// `Proxy.v1()` receive [`V1`] responders and those on the v2 builders
4716/// receive `V2` responders. The version-neutral raw dispatch layer
4717/// ([`HandleDispatchFrom`], [`MatchDispatch`](crate::util::MatchDispatch))
4718/// uses the default, [`Raw`]. [`raw_id`](Self::raw_id) returns the wire ID
4719/// whatever the marker; [`into_protocol`](Responder::into_protocol) and
4720/// [`into_raw`](Self::into_raw) convert between markers.
4721///
4722/// [`Error::request_cancelled`]: crate::Error::request_cancelled
4723/// [`Error::internal_error`]: crate::Error::internal_error
4724#[must_use]
4725pub struct Responder<T: JsonRpcResponse = serde_json::Value, P: Protocol = Raw> {
4726    /// The method of the request.
4727    method: String,
4728
4729    /// The `id` of the message we are replying to.
4730    id: HandleId<P>,
4731
4732    /// Where the response is sent; it is completed at most once.
4733    destination: ResponseDestination,
4734
4735    /// Function to send the response to its destination.
4736    ///
4737    /// For incoming requests: serializes to JSON and sends over the wire.
4738    /// For incoming responses: sends to the waiting oneshot channel.
4739    send_fn: ResponseFn<T, ()>,
4740
4741    /// Answers the request with an error if no response is sent. Owns the
4742    /// request-local cancellation state, so it can still observe a
4743    /// cancellation when it fires.
4744    drop_guard: ResponderDropGuard,
4745}
4746
4747type ResponseFn<T, U> = Box<dyn FnOnce(crate::Result<T>) -> crate::Result<U> + Send>;
4748
4749pub(crate) type RequestWithResponder<R> = (R, Responder<<R as JsonRpcRequest>::Response>);
4750
4751/// Sends the automatic error for a [`Responder`] dropped without responding.
4752struct ResponderDropGuard {
4753    message_tx: OutgoingMessageTx,
4754    connection_state: IncomingClosed,
4755    /// The method of the request as received, used to route the response.
4756    wire_method: String,
4757    id: RawJsonRpcId,
4758    destination: ResponseDestination,
4759    /// Request-local cancellation state.
4760    cancellation: ResponderCancellation,
4761    armed: bool,
4762}
4763
4764impl ResponderDropGuard {
4765    fn disarm(&mut self) {
4766        self.armed = false;
4767    }
4768}
4769
4770impl Drop for ResponderDropGuard {
4771    fn drop(&mut self) {
4772        if !self.armed || self.destination.is_completed() {
4773            return;
4774        }
4775        if self.connection_state.is_shutting_down() {
4776            tracing::debug!(
4777                id = ?self.id,
4778                method = %self.wire_method,
4779                "responder dropped while the connection is shutting down; not answering"
4780            );
4781            return;
4782        }
4783
4784        let error = if self.cancellation.is_cancelled() {
4785            crate::Error::request_cancelled()
4786        } else {
4787            crate::Error::internal_error().data(format!(
4788                "request handler dropped its responder for `{}` without responding",
4789                self.wire_method
4790            ))
4791        };
4792        tracing::warn!(
4793            id = ?self.id,
4794            method = %self.wire_method,
4795            code = ?error.code,
4796            "Responder dropped without responding; answering with an error"
4797        );
4798        self.destination.abandon(AbandonedResponse {
4799            message_tx: self.message_tx.clone(),
4800            connection_state: self.connection_state.clone(),
4801            message: OutgoingMessage::Response {
4802                id: self.id.clone(),
4803                method: self.wire_method.clone(),
4804                response: Err(error),
4805                destination: self.destination.clone(),
4806            },
4807        });
4808    }
4809}
4810
4811impl<T: JsonRpcResponse, P: Protocol> std::fmt::Debug for Responder<T, P> {
4812    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
4813        f.debug_struct("Responder")
4814            .field("method", &self.method)
4815            .field("id", &self.id)
4816            .field("response_type", &std::any::type_name::<T>())
4817            .finish_non_exhaustive()
4818    }
4819}
4820
4821impl Responder<serde_json::Value, Raw> {
4822    /// Create a new request context for an incoming request.
4823    ///
4824    /// The response will be serialized to JSON and sent over the wire.
4825    fn new(
4826        message_tx: OutgoingMessageTx,
4827        connection_state: IncomingClosed,
4828        method: String,
4829        id: RawJsonRpcId,
4830        cancellation_registry: &RequestCancellationRegistry,
4831        destination: ResponseDestination,
4832    ) -> Self {
4833        let id_clone = id.clone();
4834        let method_clone = method.clone();
4835        let cancellation = cancellation_registry.register(&id);
4836        let send_destination = destination.clone();
4837        let drop_guard = ResponderDropGuard {
4838            message_tx: message_tx.clone(),
4839            connection_state,
4840            wire_method: method.clone(),
4841            id: id.clone(),
4842            destination: destination.clone(),
4843            cancellation,
4844            armed: true,
4845        };
4846        Self {
4847            method,
4848            id: HandleId::raw_layer(id),
4849            destination,
4850            send_fn: Box::new(move |response: Result<serde_json::Value, crate::Error>| {
4851                send_raw_message(
4852                    &message_tx,
4853                    OutgoingMessage::Response {
4854                        id: id_clone,
4855                        method: method_clone,
4856                        response,
4857                        destination: send_destination,
4858                    },
4859                )
4860            }),
4861            drop_guard,
4862        }
4863    }
4864}
4865
4866impl<P: Protocol> Responder<serde_json::Value, P> {
4867    /// Cast this request context to a different response type.
4868    ///
4869    /// The provided type `T` will be serialized to JSON before sending.
4870    pub fn cast<T: JsonRpcResponse>(self) -> Responder<T, P> {
4871        self.wrap_params(move |method, value| match value {
4872            Ok(value) => T::into_json(value, method),
4873            Err(e) => Err(e),
4874        })
4875    }
4876}
4877
4878impl<T: JsonRpcResponse, P: Protocol> Responder<T, P> {
4879    fn origin_for_forwarding(&self, outgoing: &OutgoingMessageTx) -> RequestOrigin {
4880        let guard = &self.drop_guard;
4881        RequestOrigin {
4882            id: self.raw_id().clone(),
4883            generation: guard.cancellation.generation,
4884            registry: Arc::downgrade(&guard.cancellation.registry.inner),
4885            local_peer: outgoing.same_receiver(&guard.message_tx).then(|| {
4886                if guard.wire_method == crate::v1::schema::PROXY_METHOD_NAMES.proxy_successor {
4887                    RemoteStyle::Successor
4888                } else {
4889                    RemoteStyle::Predecessor
4890                }
4891            }),
4892        }
4893    }
4894
4895    /// Method of the incoming request
4896    #[must_use]
4897    pub fn method(&self) -> &str {
4898        &self.method
4899    }
4900
4901    /// ID of the incoming request, as this responder's protocol version
4902    /// types it.
4903    ///
4904    /// On a [`V2`](crate::Protocol) responder this is never `null`: the SDK
4905    /// rejects v2 requests with a `null` ID before dispatch.
4906    #[must_use]
4907    pub fn id(&self) -> &P::RequestId {
4908        self.id.typed()
4909    }
4910
4911    /// ID of the incoming request exactly as it appeared on the wire.
4912    ///
4913    /// This is the same ID as [`id`](Self::id), in the version-neutral form
4914    /// used by routers, forwarders and tracing.
4915    #[must_use]
4916    pub fn raw_id(&self) -> &RawJsonRpcId {
4917        self.id.raw()
4918    }
4919
4920    /// Returns the cancellation marker for this request.
4921    ///
4922    /// The marker is set when the peer sends `$/cancel_request` for this
4923    /// request's JSON-RPC ID. Cancellation is cooperative: handlers should use
4924    /// the marker to stop long-running work and then respond. Unless the
4925    /// method defines a successful response for cancellation (for example a
4926    /// permission request's `cancelled` outcome), that response is
4927    /// [`Error::request_cancelled`] (`-32800`) rather than partial data.
4928    /// Dropping the responder of a cancelled request sends that error
4929    /// automatically.
4930    ///
4931    /// [`Error::request_cancelled`]: crate::Error::request_cancelled
4932    #[must_use]
4933    pub fn cancellation(&self) -> RequestCancellation {
4934        self.drop_guard.cancellation.cancellation()
4935    }
4936
4937    /// Convert to a `Responder` that expects a JSON value
4938    /// and which checks (dynamically) that the JSON value it receives
4939    /// can be converted to `T`.
4940    pub fn erase_to_json(self) -> Responder<serde_json::Value, P> {
4941        self.wrap_params(|method, value| T::from_json(method, value?))
4942    }
4943
4944    /// Return a new Responder with a different method name.
4945    pub fn wrap_method(self, method: String) -> Responder<T, P> {
4946        Responder {
4947            method,
4948            id: self.id,
4949            destination: self.destination,
4950            send_fn: self.send_fn,
4951            drop_guard: self.drop_guard,
4952        }
4953    }
4954
4955    /// Return a new Responder that expects a response of type U.
4956    ///
4957    /// `wrap_fn` will be invoked with the method name and the result to transform
4958    /// type `U` into type `T` before sending.
4959    pub fn wrap_params<U: JsonRpcResponse>(
4960        self,
4961        wrap_fn: impl FnOnce(&str, Result<U, crate::Error>) -> Result<T, crate::Error> + Send + 'static,
4962    ) -> Responder<U, P> {
4963        let method = self.method.clone();
4964        let send_fn = self.send_fn;
4965        Responder {
4966            method: self.method,
4967            id: self.id,
4968            destination: self.destination,
4969            send_fn: Box::new(move |input: Result<U, crate::Error>| {
4970                let t_value = wrap_fn(&method, input);
4971                send_fn(t_value)
4972            }),
4973            drop_guard: self.drop_guard,
4974        }
4975    }
4976
4977    /// Respond to the JSON-RPC request with either a value (`Ok`) or an error (`Err`).
4978    ///
4979    /// # Errors
4980    ///
4981    /// Returns an error if the response cannot be queued. An `Err` in
4982    /// `response`, including a conversion error from a wrapped responder,
4983    /// is sent to the peer rather than returned here.
4984    pub fn respond_with_result(
4985        mut self,
4986        response: Result<T, crate::Error>,
4987    ) -> Result<(), crate::Error> {
4988        tracing::debug!(id = ?self.id, "respond called");
4989        self.drop_guard.disarm();
4990        (self.send_fn)(response)
4991    }
4992
4993    /// Respond to the JSON-RPC request with a value.
4994    ///
4995    /// # Errors
4996    ///
4997    /// Returns an error if the response cannot be queued.
4998    pub fn respond(self, response: T) -> Result<(), crate::Error> {
4999        self.respond_with_result(Ok(response))
5000    }
5001
5002    /// Respond to the JSON-RPC request with an internal error containing a message.
5003    ///
5004    /// # Errors
5005    ///
5006    /// Returns an error if the error response cannot be queued.
5007    pub fn respond_with_internal_error(self, message: impl ToString) -> Result<(), crate::Error> {
5008        self.respond_with_error(crate::util::internal_error(message))
5009    }
5010
5011    /// Respond to the JSON-RPC request with an error.
5012    ///
5013    /// # Errors
5014    ///
5015    /// Returns an error if the error response cannot be queued. `error` is
5016    /// the payload for the peer, not the return value.
5017    pub fn respond_with_error(self, error: crate::Error) -> Result<(), crate::Error> {
5018        tracing::debug!(id = ?self.id, error = ?crate::util::redacted_error(error.code), "respond_with_error called");
5019        self.respond_with_result(Err(error))
5020    }
5021
5022    /// The same responder for protocol `Q`. Fails only if the request ID is
5023    /// `null` and `Q` does not allow it, which cannot happen for requests
5024    /// received on a connection that speaks `Q`.
5025    pub(crate) fn retag<Q: Protocol>(self) -> Result<Responder<T, Q>, crate::Error> {
5026        Ok(Responder {
5027            method: self.method,
5028            id: self.id.into_protocol()?,
5029            destination: self.destination,
5030            send_fn: self.send_fn,
5031            drop_guard: self.drop_guard,
5032        })
5033    }
5034
5035    /// The same responder with a version-neutral [`Raw`] request ID, for
5036    /// code that is not tied to one protocol version, such as a
5037    /// [`HandleDispatchFrom`] implementation. This never fails.
5038    pub fn into_raw(self) -> Responder<T, Raw> {
5039        Responder {
5040            method: self.method,
5041            id: self.id.into_raw(),
5042            destination: self.destination,
5043            send_fn: self.send_fn,
5044            drop_guard: self.drop_guard,
5045        }
5046    }
5047
5048    fn reply_target(&self) -> RequestReplyTarget {
5049        RequestReplyTarget {
5050            id: self.id.raw().clone(),
5051            method: self.method.clone(),
5052            destination: self.destination.clone(),
5053        }
5054    }
5055}
5056
5057impl<T: JsonRpcResponse> Responder<T, Raw> {
5058    /// Convert this version-neutral responder to protocol `Q`'s responder,
5059    /// for example to pass a responder from a [`HandleDispatchFrom`] or
5060    /// [`MatchDispatch`](crate::util::MatchDispatch) handler to a v2 session
5061    /// helper.
5062    ///
5063    /// Only the request ID's type changes.
5064    ///
5065    /// # Errors
5066    ///
5067    /// Returns Invalid request (`-32600`) if the ID is `null` and `Q` is v2.
5068    /// A v2 connection rejects such requests before dispatch. On conversion
5069    /// failure the responder is dropped, which answers the request with an error.
5070    ///
5071    /// ```
5072    /// # use agent_client_protocol::{Error, Responder, V1, v1::schema};
5073    /// # fn example(responder: Responder<schema::PromptResponse>) -> Result<(), Error> {
5074    /// let responder: agent_client_protocol::v1::Responder<schema::PromptResponse> =
5075    ///     responder.into_protocol::<V1>()?;
5076    /// let id: &schema::RequestId = responder.id();
5077    /// # let _ = id;
5078    /// # Ok(())
5079    /// # }
5080    /// ```
5081    pub fn into_protocol<Q: Protocol>(self) -> Result<Responder<T, Q>, crate::Error> {
5082        self.retag()
5083    }
5084}
5085
5086/// Context for handling an incoming JSON-RPC response.
5087///
5088/// This is the response-side counterpart to [`Responder`]. While `Responder` handles
5089/// incoming requests (where you send a response over the wire), `ResponseRouter` handles
5090/// incoming responses (where you route the response to a local task waiting for it).
5091///
5092/// Both are fundamentally "sinks" that push the message through a `send_fn`, but they
5093/// represent different points in the message lifecycle and carry different metadata.
5094///
5095/// # Drop Behavior
5096///
5097/// Dropping a `ResponseRouter` without routing the response (for example, from a
5098/// dispatch handler that claims a [`Dispatch::Response`]) discards the
5099/// response: the local awaiter observes the response as never received. The
5100/// request still counts as settled: routing a response this far disarms the
5101/// originating [`SentRequest`]'s drop-time auto-cancellation even if the router
5102/// is never invoked, since the peer has already answered.
5103///
5104/// `P` is the [`Protocol`] marker that types [`id`](Self::id); see
5105/// [`Responder`].
5106#[must_use]
5107pub struct ResponseRouter<T: JsonRpcResponse = serde_json::Value, P: Protocol = Raw> {
5108    /// The method of the original request.
5109    method: String,
5110
5111    /// The `id` of the original request.
5112    id: HandleId<P>,
5113
5114    /// The [`RoleId`] to which the original request was sent
5115    /// (and hence from which the reply is expected).
5116    role_id: RoleId,
5117
5118    /// Function to send the response to the waiting task.
5119    send_fn: ResponseFn<T, ()>,
5120
5121    /// Shared route used to deliver a dispatch-handler error to the same waiter.
5122    reply_target: ResponseReplyTarget,
5123}
5124
5125impl<T: JsonRpcResponse, P: Protocol> std::fmt::Debug for ResponseRouter<T, P> {
5126    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
5127        f.debug_struct("ResponseRouter")
5128            .field("method", &self.method)
5129            .field("id", &self.id)
5130            .field("response_type", &std::any::type_name::<T>())
5131            .finish_non_exhaustive()
5132    }
5133}
5134
5135impl ResponseRouter<serde_json::Value> {
5136    /// Create a new response context for routing a response to a local awaiter.
5137    ///
5138    /// When [`route_with_result`](Self::route_with_result) is called, the response is sent through the oneshot
5139    /// channel to the code that originally sent the request. If that receiver was
5140    /// dropped, the response is discarded because there is no local awaiter left.
5141    fn new(pending_reply: PendingReply, dispatch: ResponseDispatch) -> Self {
5142        let PendingReply {
5143            id,
5144            method,
5145            role_id,
5146            sender,
5147            cancellation_disarm,
5148            ordering,
5149            response_route_hook,
5150            forwarded_from: _,
5151            accepts_lower_initialize_version: _,
5152        } = pending_reply;
5153        let reply_target = ResponseReplyTarget {
5154            id: id.clone(),
5155            method: method.clone(),
5156            sender: Arc::new(Mutex::new(Some(sender))),
5157            ordering,
5158            dispatch,
5159        };
5160        let send_target = reply_target.clone();
5161        // A response for the request reached this router, so the request is
5162        // settled from the peer's perspective and a `$/cancel_request` could
5163        // only ever be redundant. Disarm immediately so handlers may retain
5164        // the router without leaving auto-cancellation armed.
5165        cancellation_disarm.disarm();
5166        let hook_method = method.clone();
5167        Self {
5168            method,
5169            id: HandleId::raw_layer(id),
5170            role_id,
5171            send_fn: Box::new(move |response: Result<serde_json::Value, crate::Error>| {
5172                let response = match response {
5173                    Ok(value) => match response_route_hook {
5174                        Some(hook) => hook(&hook_method, &value).map(|()| value),
5175                        None => Ok(value),
5176                    },
5177                    Err(error) => Err(error),
5178                };
5179                send_target.route(response);
5180                Ok(())
5181            }),
5182            reply_target,
5183        }
5184    }
5185}
5186
5187impl<P: Protocol> ResponseRouter<serde_json::Value, P> {
5188    /// Cast this response context to a different response type.
5189    ///
5190    /// The provided type `T` will be serialized to JSON before sending.
5191    pub fn cast<T: JsonRpcResponse>(self) -> ResponseRouter<T, P> {
5192        self.wrap_params(move |method, value| match value {
5193            Ok(value) => T::into_json(value, method),
5194            Err(e) => Err(e),
5195        })
5196    }
5197}
5198
5199impl<T: JsonRpcResponse, P: Protocol> ResponseRouter<T, P> {
5200    /// Method of the original request
5201    #[must_use]
5202    pub fn method(&self) -> &str {
5203        &self.method
5204    }
5205
5206    /// ID of the original request, as this router's protocol version types
5207    /// it.
5208    #[must_use]
5209    pub fn id(&self) -> &P::RequestId {
5210        self.id.typed()
5211    }
5212
5213    /// ID of the original request exactly as it was sent on the wire.
5214    ///
5215    /// This is the same ID as [`id`](Self::id), in the version-neutral form
5216    /// used by routers, forwarders and tracing.
5217    #[must_use]
5218    pub fn raw_id(&self) -> &RawJsonRpcId {
5219        self.id.raw()
5220    }
5221
5222    /// The peer to which the original request was sent.
5223    ///
5224    /// This is the peer from which we expect to receive the response.
5225    #[must_use]
5226    pub fn role_id(&self) -> RoleId {
5227        self.role_id.clone()
5228    }
5229
5230    /// Convert to a `ResponseRouter` that expects a JSON value
5231    /// and which checks (dynamically) that the JSON value it receives
5232    /// can be converted to `T`.
5233    pub fn erase_to_json(self) -> ResponseRouter<serde_json::Value, P> {
5234        self.wrap_params(|method, value| T::from_json(method, value?))
5235    }
5236
5237    /// The same router for protocol `Q`. Fails only if the request ID is not
5238    /// allowed by `Q`, which cannot happen because the SDK never assigns
5239    /// `null` to requests it sends.
5240    pub(crate) fn retag<Q: Protocol>(self) -> Result<ResponseRouter<T, Q>, crate::Error> {
5241        Ok(ResponseRouter {
5242            method: self.method,
5243            id: self.id.into_protocol()?,
5244            role_id: self.role_id,
5245            send_fn: self.send_fn,
5246            reply_target: self.reply_target,
5247        })
5248    }
5249
5250    /// The same router with a version-neutral [`Raw`] request ID. This never
5251    /// fails.
5252    pub fn into_raw(self) -> ResponseRouter<T, Raw> {
5253        ResponseRouter {
5254            method: self.method,
5255            id: self.id.into_raw(),
5256            role_id: self.role_id,
5257            send_fn: self.send_fn,
5258            reply_target: self.reply_target,
5259        }
5260    }
5261
5262    /// Return a new [`ResponseRouter`] that expects a response of type `U`.
5263    ///
5264    /// `wrap_fn` will be invoked with the method name and the result to transform
5265    /// type `U` into type `T` before sending.
5266    fn wrap_params<U: JsonRpcResponse>(
5267        self,
5268        wrap_fn: impl FnOnce(&str, Result<U, crate::Error>) -> Result<T, crate::Error> + Send + 'static,
5269    ) -> ResponseRouter<U, P> {
5270        let method = self.method.clone();
5271        ResponseRouter {
5272            method: self.method,
5273            id: self.id,
5274            role_id: self.role_id,
5275            send_fn: Box::new(move |input: Result<U, crate::Error>| {
5276                let t_value = wrap_fn(&method, input);
5277                (self.send_fn)(t_value)
5278            }),
5279            reply_target: self.reply_target,
5280        }
5281    }
5282
5283    /// Route the response result to the waiting task.
5284    ///
5285    /// # Errors
5286    ///
5287    /// Response and conversion errors are delivered to the waiter. Routing
5288    /// itself currently returns `Ok(())`, even if the waiter has been dropped.
5289    pub fn route_with_result(self, response: Result<T, crate::Error>) -> Result<(), crate::Error> {
5290        tracing::debug!(id = ?self.id, "response routed to awaiter");
5291        (self.send_fn)(response)
5292    }
5293
5294    /// Route a successful response value to the waiting task.
5295    ///
5296    /// # Errors
5297    ///
5298    /// Conversion errors go to the waiter, as in [`route_with_result`](Self::route_with_result).
5299    pub fn route(self, response: T) -> Result<(), crate::Error> {
5300        self.route_with_result(Ok(response))
5301    }
5302
5303    /// Route an internal error to the waiting task.
5304    ///
5305    /// # Errors
5306    ///
5307    /// The internal error goes to the waiter, not to the caller of this method.
5308    pub fn route_with_internal_error(self, message: impl ToString) -> Result<(), crate::Error> {
5309        self.route_with_error(crate::util::internal_error(message))
5310    }
5311
5312    /// Route an error response to the waiting task.
5313    ///
5314    /// # Errors
5315    ///
5316    /// The supplied error goes to the waiter, not to the caller of this method.
5317    pub fn route_with_error(self, error: crate::Error) -> Result<(), crate::Error> {
5318        tracing::debug!(id = ?self.id, error = ?crate::util::redacted_error(error.code), "error routed to awaiter");
5319        self.route_with_result(Err(error))
5320    }
5321}
5322
5323impl<T: JsonRpcResponse> ResponseRouter<T, Raw> {
5324    /// Convert this version-neutral router to protocol `Q`'s router.
5325    ///
5326    /// # Errors
5327    ///
5328    /// Fails only for an ID that `Q` rejects. The SDK never assigns `null`
5329    /// to outgoing requests, so its routers convert to every protocol marker.
5330    pub fn into_protocol<Q: Protocol>(self) -> Result<ResponseRouter<T, Q>, crate::Error> {
5331        self.retag()
5332    }
5333}
5334
5335/// Common bounds for any JSON-RPC message.
5336///
5337/// # Derive Macro
5338///
5339/// For simple message types, you can use the `JsonRpcRequest` or `JsonRpcNotification` derive macros
5340/// which will implement both `JsonRpcMessage` and the respective trait. See [`JsonRpcRequest`] and
5341/// [`JsonRpcNotification`] for examples.
5342pub trait JsonRpcMessage: 'static + Debug + Sized + Send + Clone {
5343    /// Check if this message type matches the given method name.
5344    fn matches_method(method: &str) -> bool;
5345
5346    /// The method name for the message.
5347    fn method(&self) -> &str;
5348
5349    /// Convert this message into an untyped message.
5350    ///
5351    /// # Errors
5352    ///
5353    /// Returns an error if the message's params cannot be encoded as JSON.
5354    fn to_untyped_message(&self) -> Result<UntypedMessage, crate::Error>;
5355
5356    /// Parse this type from a method name and the message's JSON `params`.
5357    ///
5358    /// Callers should use `matches_method` first to check if this type handles the method.
5359    /// A message without `params` is parsed from [`serde_json::Value::Null`].
5360    ///
5361    /// # Errors
5362    ///
5363    /// Returns an error if the method doesn't match or its params cannot be decoded.
5364    fn parse_message(method: &str, params: &serde_json::Value) -> Result<Self, crate::Error>;
5365}
5366
5367/// Defines the "payload" of a successful response to a JSON-RPC request.
5368///
5369/// # Derive Macro
5370///
5371/// Use `#[derive(JsonRpcResponse)]` to automatically implement this trait:
5372///
5373/// ```ignore
5374/// use agent_client_protocol::JsonRpcResponse;
5375/// use serde::{Serialize, Deserialize};
5376///
5377/// #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
5378/// struct HelloResponse {
5379///     greeting: String,
5380/// }
5381/// ```
5382pub trait JsonRpcResponse: 'static + Debug + Sized + Send + Clone {
5383    /// Convert this message into a JSON value.
5384    ///
5385    /// # Errors
5386    ///
5387    /// Returns an error if the response cannot be encoded for `method`.
5388    fn into_json(self, method: &str) -> Result<serde_json::Value, crate::Error>;
5389
5390    /// Parse a JSON value into the response type.
5391    ///
5392    /// # Errors
5393    ///
5394    /// Returns an error if `value` cannot be decoded as the response to `method`.
5395    fn from_json(method: &str, value: serde_json::Value) -> Result<Self, crate::Error>;
5396}
5397
5398impl JsonRpcResponse for serde_json::Value {
5399    fn from_json(_method: &str, value: serde_json::Value) -> Result<Self, crate::Error> {
5400        Ok(value)
5401    }
5402
5403    fn into_json(self, _method: &str) -> Result<serde_json::Value, crate::Error> {
5404        Ok(self)
5405    }
5406}
5407
5408/// A struct that represents a notification (JSON-RPC message that does not expect a response).
5409///
5410/// # Derive Macro
5411///
5412/// Use `#[derive(JsonRpcNotification)]` to automatically implement both `JsonRpcMessage` and `JsonRpcNotification`:
5413///
5414/// ```ignore
5415/// use agent_client_protocol::JsonRpcNotification;
5416/// use serde::{Serialize, Deserialize};
5417///
5418/// #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcNotification)]
5419/// #[notification(method = "_ping")]
5420/// struct PingNotification {
5421///     timestamp: u64,
5422/// }
5423/// ```
5424pub trait JsonRpcNotification: JsonRpcMessage {}
5425
5426/// A struct that represents a request (JSON-RPC message expecting a response).
5427///
5428/// # Derive Macro
5429///
5430/// Use `#[derive(JsonRpcRequest)]` to automatically implement both `JsonRpcMessage` and `JsonRpcRequest`:
5431///
5432/// ```ignore
5433/// use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
5434/// use serde::{Serialize, Deserialize};
5435///
5436/// #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
5437/// #[request(method = "_hello", response = HelloResponse)]
5438/// struct HelloRequest {
5439///     name: String,
5440/// }
5441///
5442/// #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
5443/// struct HelloResponse {
5444///     greeting: String,
5445/// }
5446/// ```
5447pub trait JsonRpcRequest: JsonRpcMessage {
5448    /// The type of data expected in response.
5449    type Response: JsonRpcResponse;
5450}
5451
5452/// An incoming request, notification, or response being dispatched through handlers.
5453/// Requests include the context used to answer them; responses include the context
5454/// used to route them to the local requester.
5455///
5456/// Type parameters allow specifying the concrete request and notification types.
5457/// By default, both are `UntypedMessage` for dynamic dispatch.
5458/// The request context's response type matches the request's response type.
5459///
5460/// `P` is the [`Protocol`] marker of the request handles. Typed handlers on
5461/// v1 builders receive `Dispatch<Req, Notif, V1>` and those on v2 builders
5462/// `Dispatch<Req, Notif, V2>`. The version-neutral [`HandleDispatchFrom`]
5463/// layer uses the default, [`Raw`], whose `id()` is the wire ID.
5464#[derive(Debug)]
5465pub enum Dispatch<
5466    Req: JsonRpcRequest = UntypedMessage,
5467    Notif: JsonRpcNotification = UntypedMessage,
5468    P: Protocol = Raw,
5469> {
5470    /// Incoming request and the context where the response should be sent.
5471    Request(Req, Responder<Req::Response, P>),
5472
5473    /// Incoming notification.
5474    Notification(Notif),
5475
5476    /// Incoming response to a request we sent.
5477    ///
5478    /// The first field is the response result (success or error from the remote).
5479    /// The second field is the context for forwarding the response to its destination
5480    /// (typically a waiting oneshot channel).
5481    Response(
5482        Result<Req::Response, crate::Error>,
5483        ResponseRouter<Req::Response, P>,
5484    ),
5485}
5486
5487impl<Req: JsonRpcRequest, Notif: JsonRpcNotification, P: Protocol> Dispatch<Req, Notif, P> {
5488    /// Map the request and notification types to new types.
5489    ///
5490    /// Note: Response variants are passed through unchanged since they don't
5491    /// contain a parseable message payload.
5492    pub fn map<Req1, Notif1>(
5493        self,
5494        map_request: impl FnOnce(
5495            Req,
5496            Responder<Req::Response, P>,
5497        ) -> (Req1, Responder<Req1::Response, P>),
5498        map_notification: impl FnOnce(Notif) -> Notif1,
5499    ) -> Dispatch<Req1, Notif1, P>
5500    where
5501        Req1: JsonRpcRequest<Response = Req::Response>,
5502        Notif1: JsonRpcNotification,
5503    {
5504        match self {
5505            Dispatch::Request(request, responder) => {
5506                let (new_request, new_responder) = map_request(request, responder);
5507                Dispatch::Request(new_request, new_responder)
5508            }
5509            Dispatch::Notification(notification) => {
5510                let new_notification = map_notification(notification);
5511                Dispatch::Notification(new_notification)
5512            }
5513            Dispatch::Response(result, router) => Dispatch::Response(result, router),
5514        }
5515    }
5516
5517    /// Convert the request or notification to an untyped message.
5518    ///
5519    /// # Errors
5520    ///
5521    /// Returns an error for a response, which has no method params, or if
5522    /// the request or notification cannot encode its params.
5523    pub fn to_untyped_message(&self) -> Result<UntypedMessage, crate::Error> {
5524        match self {
5525            Dispatch::Request(request, _) => request.to_untyped_message(),
5526            Dispatch::Notification(notification) => notification.to_untyped_message(),
5527            Dispatch::Response(_, _) => Err(crate::util::internal_error(
5528                "Response variant has no untyped message representation",
5529            )),
5530        }
5531    }
5532
5533    /// Convert self to an untyped message context.
5534    ///
5535    /// # Errors
5536    ///
5537    /// Returns an error for a response, or if the request or notification
5538    /// cannot encode its params.
5539    pub fn into_untyped_dispatch(
5540        self,
5541    ) -> Result<Dispatch<UntypedMessage, UntypedMessage, P>, crate::Error> {
5542        match self {
5543            Dispatch::Request(request, responder) => Ok(Dispatch::Request(
5544                request.to_untyped_message()?,
5545                responder.erase_to_json(),
5546            )),
5547            Dispatch::Notification(notification) => {
5548                Ok(Dispatch::Notification(notification.to_untyped_message()?))
5549            }
5550            Dispatch::Response(_, _) => Err(crate::util::internal_error(
5551                "cannot convert Response variant to untyped message context",
5552            )),
5553        }
5554    }
5555
5556    /// Returns the request ID if this is a request or response, None if notification.
5557    ///
5558    /// See [`Responder::id`] and [`ResponseRouter::id`].
5559    pub fn id(&self) -> Option<&P::RequestId> {
5560        match self {
5561            Dispatch::Request(_, cx) => Some(cx.id()),
5562            Dispatch::Notification(_) => None,
5563            Dispatch::Response(_, cx) => Some(cx.id()),
5564        }
5565    }
5566
5567    /// Returns the request ID exactly as it appears on the wire if this is a
5568    /// request or response, None if notification.
5569    ///
5570    /// See [`Responder::raw_id`] and [`ResponseRouter::raw_id`].
5571    #[must_use]
5572    pub fn raw_id(&self) -> Option<&RawJsonRpcId> {
5573        match self {
5574            Dispatch::Request(_, cx) => Some(cx.raw_id()),
5575            Dispatch::Notification(_) => None,
5576            Dispatch::Response(_, cx) => Some(cx.raw_id()),
5577        }
5578    }
5579
5580    /// The same dispatch with request handles for protocol `Q`.
5581    ///
5582    /// Fails only for a request whose `null` ID `Q` does not allow, which
5583    /// cannot happen for a message received on a connection that speaks `Q`.
5584    pub(crate) fn retag<Q: Protocol>(self) -> Result<Dispatch<Req, Notif, Q>, crate::Error> {
5585        Ok(match self {
5586            Dispatch::Request(request, responder) => Dispatch::Request(request, responder.retag()?),
5587            Dispatch::Notification(notification) => Dispatch::Notification(notification),
5588            Dispatch::Response(result, router) => Dispatch::Response(result, router.retag()?),
5589        })
5590    }
5591
5592    /// The same dispatch with version-neutral [`Raw`] request handles, for
5593    /// example to hand a typed dispatch to a [`HandleDispatchFrom`]
5594    /// implementation. This never fails.
5595    pub fn into_raw(self) -> Dispatch<Req, Notif, Raw> {
5596        match self {
5597            Dispatch::Request(request, responder) => {
5598                Dispatch::Request(request, responder.into_raw())
5599            }
5600            Dispatch::Notification(notification) => Dispatch::Notification(notification),
5601            Dispatch::Response(result, router) => Dispatch::Response(result, router.into_raw()),
5602        }
5603    }
5604
5605    fn handler_error_target(&self) -> Option<HandlerErrorTarget> {
5606        match self {
5607            Dispatch::Request(_, responder) => {
5608                Some(HandlerErrorTarget::Request(responder.reply_target()))
5609            }
5610            Dispatch::Notification(_) => None,
5611            Dispatch::Response(_, router) => {
5612                Some(HandlerErrorTarget::Response(router.reply_target.clone()))
5613            }
5614        }
5615    }
5616
5617    /// Returns the method of the message.
5618    ///
5619    /// For requests and notifications, this is the method from the message payload.
5620    /// For responses, this is the method of the original request.
5621    pub fn method(&self) -> &str {
5622        match self {
5623            Dispatch::Request(msg, _) => msg.method(),
5624            Dispatch::Notification(msg) => msg.method(),
5625            Dispatch::Response(_, cx) => cx.method(),
5626        }
5627    }
5628}
5629
5630impl<Req: JsonRpcRequest, Notif: JsonRpcNotification> Dispatch<Req, Notif, Raw> {
5631    /// Convert this version-neutral dispatch to protocol `Q`'s request
5632    /// handles.
5633    ///
5634    /// # Errors
5635    ///
5636    /// See [`Responder::into_protocol`]: this fails only for a request whose
5637    /// `null` ID `Q` does not allow, with the Invalid Request error
5638    /// (`-32600`).
5639    pub fn into_protocol<Q: Protocol>(self) -> Result<Dispatch<Req, Notif, Q>, crate::Error> {
5640        self.retag()
5641    }
5642}
5643
5644impl Dispatch {
5645    /// Attempts to parse `self` into a typed message context.
5646    ///
5647    /// # Returns
5648    ///
5649    /// * `Ok(Ok(typed))` if this dispatch matches the requested type for its variant
5650    /// * `Ok(Err(self))` if it does not match the requested type for its variant
5651    /// * `Err` if its method matches the requested type but parsing fails
5652    #[tracing::instrument(skip(self), fields(Request = ?std::any::type_name::<Req>(), Notif = ?std::any::type_name::<Notif>()), level = "trace", ret)]
5653    pub(crate) fn into_typed_dispatch<Req: JsonRpcRequest, Notif: JsonRpcNotification>(
5654        self,
5655    ) -> Result<Result<Dispatch<Req, Notif>, Dispatch>, crate::Error> {
5656        tracing::debug!(
5657            method = self.method(),
5658            id = ?self.raw_id(),
5659            "into_typed_dispatch"
5660        );
5661        match self {
5662            Dispatch::Request(message, responder) => {
5663                if Req::matches_method(&message.method) {
5664                    match Req::parse_message(&message.method, &message.params) {
5665                        Ok(req) => {
5666                            tracing::trace!("parsed ok");
5667                            Ok(Ok(Dispatch::Request(req, responder.cast())))
5668                        }
5669                        Err(err) => {
5670                            tracing::trace!(err = ?crate::util::redacted_error(err.code), "parse error");
5671                            Err(err)
5672                        }
5673                    }
5674                } else {
5675                    tracing::trace!("method doesn't match");
5676                    Ok(Err(Dispatch::Request(message, responder)))
5677                }
5678            }
5679
5680            Dispatch::Notification(message) => {
5681                if Notif::matches_method(&message.method) {
5682                    match Notif::parse_message(&message.method, &message.params) {
5683                        Ok(notif) => {
5684                            tracing::trace!("parse ok");
5685                            Ok(Ok(Dispatch::Notification(notif)))
5686                        }
5687                        Err(err) => {
5688                            tracing::trace!(err = ?crate::util::redacted_error(err.code), "parse error");
5689                            Err(err)
5690                        }
5691                    }
5692                } else {
5693                    tracing::trace!("method doesn't match");
5694                    Ok(Err(Dispatch::Notification(message)))
5695                }
5696            }
5697
5698            Dispatch::Response(result, cx) => {
5699                let method = cx.method();
5700                if Req::matches_method(method) {
5701                    // Parse the response result
5702                    let typed_result = match result {
5703                        Ok(value) => {
5704                            match <Req::Response as JsonRpcResponse>::from_json(method, value) {
5705                                Ok(parsed) => {
5706                                    tracing::trace!("parse ok");
5707                                    Ok(parsed)
5708                                }
5709                                Err(err) => {
5710                                    tracing::trace!(err = ?crate::util::redacted_error(err.code), "parse error");
5711                                    return Err(err);
5712                                }
5713                            }
5714                        }
5715                        Err(err) => {
5716                            tracing::trace!("error, passthrough");
5717                            Err(err)
5718                        }
5719                    };
5720                    Ok(Ok(Dispatch::Response(typed_result, cx.cast())))
5721                } else {
5722                    tracing::trace!("method doesn't match");
5723                    Ok(Err(Dispatch::Response(result, cx)))
5724                }
5725            }
5726        }
5727    }
5728
5729    /// True if this message has a field with the given name.
5730    ///
5731    /// Returns `false` for Response variants.
5732    #[must_use]
5733    pub fn has_field(&self, field_name: &str) -> bool {
5734        self.message()
5735            .and_then(|m| m.params().get(field_name))
5736            .is_some()
5737    }
5738
5739    /// Returns true if this message has a session-id field.
5740    ///
5741    /// Returns `false` for Response variants.
5742    pub(crate) fn has_session_id(&self) -> bool {
5743        self.has_field("sessionId")
5744    }
5745
5746    /// Extract the ACP session-id from this message (if any).
5747    ///
5748    /// Returns `Ok(None)` for Response variants.
5749    pub(crate) fn get_session_id(&self) -> Result<Option<SessionId>, crate::Error> {
5750        let Some(message) = self.message() else {
5751            return Ok(None);
5752        };
5753        let Some(value) = message.params().get("sessionId") else {
5754            return Ok(None);
5755        };
5756        let session_id = serde_json::from_value(value.clone())?;
5757        Ok(Some(session_id))
5758    }
5759
5760    /// Try to parse this as a notification of the given type.
5761    ///
5762    /// # Returns
5763    ///
5764    /// * `Ok(Ok(typed))` if this is a notification of the requested type
5765    /// * `Ok(Err(self))` if this is not a matching notification
5766    ///
5767    /// # Errors
5768    ///
5769    /// Returns the parsing error if the method matches but its params cannot be decoded.
5770    pub fn into_notification<N: JsonRpcNotification>(
5771        self,
5772    ) -> Result<Result<N, Dispatch>, crate::Error> {
5773        match self {
5774            Dispatch::Notification(msg) => {
5775                if !N::matches_method(&msg.method) {
5776                    return Ok(Err(Dispatch::Notification(msg)));
5777                }
5778                match N::parse_message(&msg.method, &msg.params) {
5779                    Ok(n) => Ok(Ok(n)),
5780                    Err(err) => Err(err),
5781                }
5782            }
5783            Dispatch::Request(..) | Dispatch::Response(..) => Ok(Err(self)),
5784        }
5785    }
5786
5787    /// Try to parse this as a request of the given type.
5788    ///
5789    /// # Returns
5790    ///
5791    /// * `Ok(Ok(typed))` if this is a request of the requested type
5792    /// * `Ok(Err(self))` if this is not a matching request
5793    ///
5794    /// # Errors
5795    ///
5796    /// Returns the parsing error if the method matches but its params cannot be decoded.
5797    pub fn into_request<Req: JsonRpcRequest>(
5798        self,
5799    ) -> crate::Result<Result<RequestWithResponder<Req>, Dispatch>> {
5800        match self {
5801            Dispatch::Request(msg, responder) => {
5802                if !Req::matches_method(&msg.method) {
5803                    return Ok(Err(Dispatch::Request(msg, responder)));
5804                }
5805                match Req::parse_message(&msg.method, &msg.params) {
5806                    Ok(req) => Ok(Ok((req, responder.cast()))),
5807                    Err(err) => Err(err),
5808                }
5809            }
5810            Dispatch::Notification(..) | Dispatch::Response(..) => Ok(Err(self)),
5811        }
5812    }
5813}
5814
5815impl<M: JsonRpcRequest + JsonRpcNotification> Dispatch<M, M> {
5816    /// Returns the message payload for requests and notifications.
5817    ///
5818    /// Returns `None` for Response variants since they don't contain a message payload.
5819    pub fn message(&self) -> Option<&M> {
5820        match self {
5821            Dispatch::Request(msg, _) | Dispatch::Notification(msg) => Some(msg),
5822            Dispatch::Response(_, _) => None,
5823        }
5824    }
5825
5826    /// Map the request/notification message.
5827    ///
5828    /// Response variants pass through unchanged.
5829    pub(crate) fn try_map_message(
5830        self,
5831        map_message: impl FnOnce(M) -> Result<M, crate::Error>,
5832    ) -> Result<Dispatch<M, M>, crate::Error> {
5833        match self {
5834            Dispatch::Request(request, cx) => Ok(Dispatch::Request(map_message(request)?, cx)),
5835            Dispatch::Notification(notification) => {
5836                Ok(Dispatch::<M, M>::Notification(map_message(notification)?))
5837            }
5838            Dispatch::Response(result, cx) => Ok(Dispatch::Response(result, cx)),
5839        }
5840    }
5841}
5842
5843/// An incoming JSON message without any typing. Can be a request or a notification.
5844#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
5845pub struct UntypedMessage {
5846    /// The JSON-RPC method name
5847    pub method: String,
5848    /// The JSON-RPC parameters as a raw JSON value
5849    pub params: serde_json::Value,
5850}
5851
5852impl UntypedMessage {
5853    /// Returns an untyped message with the given method and parameters.
5854    ///
5855    /// # Errors
5856    ///
5857    /// Returns an error if `params` cannot be serialized as JSON.
5858    pub fn new(method: &str, params: impl Serialize) -> Result<Self, crate::Error> {
5859        let params = serde_json::to_value(params)?;
5860        Ok(Self {
5861            method: method.to_string(),
5862            params,
5863        })
5864    }
5865
5866    /// Returns the method name
5867    #[must_use]
5868    pub fn method(&self) -> &str {
5869        &self.method
5870    }
5871
5872    /// Returns the parameters as a JSON value
5873    #[must_use]
5874    pub fn params(&self) -> &serde_json::Value {
5875        &self.params
5876    }
5877
5878    /// Consumes this message and returns the method and params
5879    #[must_use]
5880    pub fn into_parts(self) -> (String, serde_json::Value) {
5881        (self.method, self.params)
5882    }
5883
5884    /// Convert `self` to a raw JSON-RPC message.
5885    pub(crate) fn into_raw_jsonrpc_message(
5886        self,
5887        id: Option<RawJsonRpcId>,
5888    ) -> Result<RawJsonRpcMessage, crate::Error> {
5889        let Self { method, params } = self;
5890        match id {
5891            Some(id) => RawJsonRpcMessage::request(method, params, id),
5892            None => RawJsonRpcMessage::notification(method, params),
5893        }
5894    }
5895}
5896
5897impl JsonRpcMessage for UntypedMessage {
5898    fn matches_method(_method: &str) -> bool {
5899        // UntypedMessage matches any method - it's the untyped fallback
5900        true
5901    }
5902
5903    fn method(&self) -> &str {
5904        &self.method
5905    }
5906
5907    fn to_untyped_message(&self) -> Result<UntypedMessage, crate::Error> {
5908        Ok(self.clone())
5909    }
5910
5911    fn parse_message(method: &str, params: &serde_json::Value) -> Result<Self, crate::Error> {
5912        UntypedMessage::new(method, params)
5913    }
5914}
5915
5916impl JsonRpcRequest for UntypedMessage {
5917    type Response = serde_json::Value;
5918}
5919
5920impl JsonRpcNotification for UntypedMessage {}
5921
5922/// Represents a pending response of type `R` from an outgoing request.
5923///
5924/// Returned by [`ConnectionTo::send_request`], this type provides explicit response-consumption
5925/// modes. The API is intentionally designed to make it difficult to accidentally wait for a
5926/// response inside the dispatch loop.
5927///
5928/// # Anti-Footgun Design
5929///
5930/// You cannot directly `.await` a `SentRequest`. Instead, you must choose how to handle
5931/// the response:
5932///
5933/// ## Option 1: Register an Ordered Callback (Safe in Handlers)
5934///
5935/// Calling [`on_receiving_result`](Self::on_receiving_result) registers the callback and returns
5936/// immediately. When ordered consumption is selected before the response is routed during its
5937/// original dispatch, the loop waits for the callback to complete before processing the next
5938/// message:
5939///
5940/// ```no_run
5941/// # use agent_client_protocol_test::*;
5942/// # async fn example(cx: agent_client_protocol::ConnectionTo<agent_client_protocol::UntypedRole>) -> Result<(), agent_client_protocol::Error> {
5943/// cx.send_request(MyRequest {})
5944///     .on_receiving_result(async |result| {
5945///         match result {
5946///             Ok(response) => {
5947///                 // Handle successful response
5948///                 Ok(())
5949///             }
5950///             Err(error) => {
5951///                 // Handle error
5952///                 Err(error)
5953///             }
5954///         }
5955///     })?;
5956/// # Ok(())
5957/// # }
5958/// ```
5959///
5960/// ## Option 2: Wait Outside the Dispatch Loop
5961///
5962/// Use [`block_task`](Self::block_task) only when the current task already runs outside the
5963/// dispatch loop—for example, in the foreground future passed to `connect_with` or in a task
5964/// created with [`ConnectionTo::spawn`]. Never await it in a handler:
5965///
5966/// ```no_run
5967/// # use agent_client_protocol_test::*;
5968/// # async fn example(cx: agent_client_protocol::ConnectionTo<agent_client_protocol::UntypedRole>) -> Result<(), agent_client_protocol::Error> {
5969/// // ✅ Safe: Spawned task runs concurrently
5970/// cx.spawn({
5971///     let cx = cx.clone();
5972///     async move {
5973///         let response = cx.send_request(MyRequest {})
5974///             .block_task()
5975///             .await?;
5976///         // Process response...
5977///         Ok(())
5978///     }
5979/// })?;
5980/// # Ok(())
5981/// # }
5982/// ```
5983///
5984/// ```no_run
5985/// # use agent_client_protocol_test::*;
5986/// # async fn example() -> Result<(), agent_client_protocol::Error> {
5987/// # let connection = mock_connection();
5988/// // ❌ NEVER do this in a handler - blocks the event loop!
5989/// connection.on_receive_request(async |req: MyRequest, responder, cx| {
5990///     let response = cx.send_request(MyRequest {})
5991///         .block_task()  // This will deadlock!
5992///         .await?;
5993///     responder.respond(response)
5994/// }, agent_client_protocol::on_receive_request!())
5995/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
5996/// # Ok(())
5997/// # }
5998/// ```
5999///
6000/// # Why This Design?
6001///
6002/// If you block the event loop while waiting for a response, the connection cannot process
6003/// the incoming response message, creating a deadlock. This API design prevents that footgun
6004/// by making blocking explicit and encouraging non-blocking patterns.
6005///
6006/// # Drop Behavior
6007///
6008/// By default, dropping a `SentRequest` before the SDK has received the
6009/// response sends a `$/cancel_request` notification asking the peer to cancel
6010/// the request, then discards the response when it arrives. Requests whose
6011/// eventual response should be ignored, but which should keep running on the
6012/// peer, should use [`detach`](Self::detach) instead.
6013///
6014/// # Incoming Transport EOF
6015///
6016/// If the incoming transport reaches clean EOF before the response arrives, every
6017/// consumption mode receives an error with the message `Incoming transport
6018/// closed` and data containing
6019/// `{"reason":"incoming_transport_closed","method":"..."}`. Requests made
6020/// after incoming EOF fail immediately with the same error. Use
6021/// [`is_incoming_transport_closed`] to identify it.
6022///
6023/// # Protocol version
6024///
6025/// `P` is the [`Protocol`] marker of the connection handle that sent the
6026/// request: [`Raw`] for the version-neutral [`ConnectionTo`], `V2` for
6027/// `v2::ConnectionTo`. It selects the type [`id`](Self::id) returns.
6028#[must_use = "dropping a SentRequest asks the peer to cancel the request and \
6029              discards the response; consume it with `block_task`, \
6030              `on_receiving_result`, `forward_response_to`, or `detach`"]
6031pub struct SentRequest<T, P: Protocol = Raw> {
6032    id: HandleId<P>,
6033    method: String,
6034    task_tx: TaskTx,
6035    pending_replies: PendingRepliesRegistrar,
6036    response_rx: oneshot::Receiver<ResponsePayload>,
6037    /// Converts the raw response into the typed result. It receives error
6038    /// responses too, so [`SentRequest::recover_error`] can map an error to a
6039    /// success.
6040    to_result: ResponseFn<serde_json::Value, T>,
6041    cancellation: SentRequestCancellation,
6042    response_ordering: ResponseOrdering,
6043    /// Cancellation markers of other (incoming) requests whose cancellation
6044    /// should be forwarded to this request. See
6045    /// [`forward_cancellation_from`](Self::forward_cancellation_from).
6046    cancellation_sources: Vec<RequestCancellation>,
6047}
6048
6049/// A request that has not been published to its connection.
6050///
6051/// Created by [`ConnectionTo::prepare_request`] or
6052/// [`ConnectionTo::prepare_request_to`]. Preparation serializes the request but
6053/// does not register a pending reply or enqueue outgoing traffic. Dropping this
6054/// value sends neither the request nor a cancellation notification.
6055///
6056/// A consuming method publishes the request synchronously:
6057///
6058/// - [`on_receiving_result`](Self::on_receiving_result),
6059///   [`on_receiving_ok_result`](Self::on_receiving_ok_result), and
6060///   [`forward_response_to`](Self::forward_response_to) register ordered response
6061///   handling before publication. When a peer response is routed during its
6062///   original dispatch, later inbound messages wait for that handling to finish.
6063/// - [`block_task`](Self::block_task) publishes immediately and returns an
6064///   unordered response future. Publication does not wait for its first poll.
6065/// - [`detach`](Self::detach) publishes immediately and discards the response.
6066///
6067/// Ordered callbacks must do bounded work and must not await later inbound
6068/// traffic on the same connection. EOF failures and responses routed through a
6069/// retained [`ResponseRouter`] after their original dispatch have no ordering
6070/// barrier. See [`crate::concepts::ordering`].
6071///
6072/// # Errors
6073///
6074/// Preparation and publication failures are delivered to the selected response
6075/// consumer. Callback-style methods return an error if their task cannot be
6076/// registered; in that case the request is not published. [`detach`](Self::detach)
6077/// returns preparation or publication errors directly because it has no response
6078/// consumer. A callback returning an error terminates the connection.
6079///
6080/// `P` is the [`Protocol`] marker that types [`id`](Self::id); see
6081/// [`SentRequest`].
6082#[must_use = "a prepared request is not sent until consumed with `block_task`, \
6083              `on_receiving_result`, `forward_response_to`, or `detach`"]
6084pub struct PreparedRequest<T, P: Protocol = Raw> {
6085    sent: SentRequest<T, P>,
6086    publication: RequestPublication,
6087}
6088
6089struct RequestPublication {
6090    message: Result<OutgoingMessage, crate::Error>,
6091    pending_reply: PendingReply,
6092    message_tx: OutgoingMessageTx,
6093    pending_replies: PendingRepliesRegistrar,
6094    incoming_closed: IncomingClosed,
6095}
6096
6097impl RequestPublication {
6098    /// Both logical peers of an SDK proxy share a connection. When forwarding
6099    /// a callback, translate its parent ID exactly once, at publication.
6100    fn translate_proxied_elicitation(&mut self) -> Result<(), crate::Error> {
6101        let Some(callback) = &self.pending_reply.forwarded_from else {
6102            // A locally authored request is already in the destination's namespace.
6103            return Ok(());
6104        };
6105        let Ok(OutgoingMessage::Request {
6106            remote_style: RemoteStyle::Predecessor,
6107            untyped,
6108            ..
6109        }) = &mut self.message
6110        else {
6111            return Ok(());
6112        };
6113        if self.pending_reply.role_id != crate::Client.role_id() {
6114            return Ok(());
6115        }
6116        self.pending_replies
6117            .translate_elicitation(Agent.role_id(), untyped, |origin| {
6118                callback.local_peer == Some(RemoteStyle::Successor)
6119                    && origin.local_peer == Some(RemoteStyle::Predecessor)
6120            })
6121    }
6122
6123    fn publish(mut self) -> Result<(), crate::Error> {
6124        let message = if self.incoming_closed.is_closing() {
6125            Err(incoming_transport_closed_error(&self.pending_reply.method))
6126        } else {
6127            self.translate_proxied_elicitation().and(self.message)
6128        };
6129        let message = match message {
6130            Ok(message) => message,
6131            Err(error) => {
6132                self.pending_reply.fail(error.clone());
6133                return Err(error);
6134            }
6135        };
6136        let OutgoingMessage::Request { id, method, .. } = &message else {
6137            unreachable!();
6138        };
6139        let id = id.clone();
6140        let method = method.clone();
6141        let cancellation_disarm = self.pending_reply.cancellation_disarm.clone();
6142        // Register before enqueueing so incoming EOF can fail every observable
6143        // request before close callbacks begin. The outgoing actor checks that
6144        // the registration still exists before sending the request.
6145        self.pending_replies
6146            .subscribe(id.clone(), self.pending_reply, &self.incoming_closed)?;
6147        if self.message_tx.unbounded_send(message).is_err() {
6148            let error = if self.incoming_closed.is_closing() {
6149                incoming_transport_closed_error(&method)
6150            } else {
6151                crate::util::internal_error(format!("failed to send outgoing request `{method}`"))
6152            };
6153            if let Some(pending_reply) = self.pending_replies.remove(&id) {
6154                pending_reply.fail(error.clone());
6155            }
6156            return Err(error);
6157        }
6158        // An escaped cancellation handle must not enqueue cancellation before
6159        // the request. A fast response or EOF may already have disarmed it.
6160        cancellation_disarm.arm();
6161        Ok(())
6162    }
6163}
6164
6165impl<T: Debug, P: Protocol> Debug for PreparedRequest<T, P> {
6166    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
6167        formatter
6168            .debug_struct("PreparedRequest")
6169            .field("request", &self.sent)
6170            .finish_non_exhaustive()
6171    }
6172}
6173
6174impl<T, P: Protocol> PreparedRequest<T, P> {
6175    /// The same prepared request with a version-neutral [`Raw`] request ID,
6176    /// for code that is not tied to one protocol version. This never fails
6177    /// and does not publish the request.
6178    pub fn into_raw(self) -> PreparedRequest<T, Raw> {
6179        PreparedRequest {
6180            sent: self.sent.into_raw(),
6181            publication: self.publication,
6182        }
6183    }
6184}
6185
6186impl<T> PreparedRequest<T, Raw> {
6187    /// Convert this version-neutral prepared request to protocol `Q`'s
6188    /// handle without publishing it.
6189    ///
6190    /// # Errors
6191    ///
6192    /// Fails only for an ID that `Q` rejects. IDs reserved by the SDK are
6193    /// never `null` and convert to every protocol marker.
6194    pub fn into_protocol<Q: Protocol>(self) -> Result<PreparedRequest<T, Q>, crate::Error> {
6195        Ok(PreparedRequest {
6196            sent: self.sent.into_protocol()?,
6197            publication: self.publication,
6198        })
6199    }
6200}
6201
6202impl<T, P: Protocol> PreparedRequest<T, P> {
6203    /// The ID reserved for this request, which has not been sent yet, as
6204    /// this request's protocol version types it.
6205    ///
6206    /// It is the ID written to the wire when the request is published. The
6207    /// SDK never assigns `null`.
6208    #[must_use]
6209    pub fn id(&self) -> &P::RequestId {
6210        self.sent.id()
6211    }
6212
6213    /// The ID reserved for this request in the version-neutral form used by
6214    /// routers, forwarders and tracing. It is the same ID as
6215    /// [`id`](Self::id).
6216    #[must_use]
6217    pub fn raw_id(&self) -> &RawJsonRpcId {
6218        self.sent.raw_id()
6219    }
6220
6221    /// The method of the prepared request.
6222    #[must_use]
6223    pub fn method(&self) -> &str {
6224        self.sent.method()
6225    }
6226
6227    /// Retain explicit cancellation control without publishing this request.
6228    ///
6229    /// The handle can outlive consumption of this request by an ordered callback
6230    /// or response future. Calling it before publication is a no-op, not a
6231    /// cancellation to apply when the request is later published. Dropping the
6232    /// handle does not cancel. See [`RequestCancellationHandle`].
6233    #[must_use]
6234    pub fn cancellation_handle(&self) -> RequestCancellationHandle {
6235        self.sent.cancellation_handle()
6236    }
6237
6238    /// Map a successful response without publishing the request.
6239    ///
6240    /// The mapper has the same contract as [`SentRequest::map`].
6241    pub fn map<U>(
6242        self,
6243        map_fn: impl FnOnce(T) -> Result<U, crate::Error> + 'static + Send,
6244    ) -> PreparedRequest<U, P>
6245    where
6246        T: 'static,
6247    {
6248        PreparedRequest {
6249            sent: self.sent.map(map_fn),
6250            publication: self.publication,
6251        }
6252    }
6253
6254    /// Register a cancellation source without publishing the request.
6255    ///
6256    /// After publication, cancellation is forwarded while awaiting the response,
6257    /// as described by [`SentRequest::forward_cancellation_from`].
6258    pub fn forward_cancellation_from(mut self, source: RequestCancellation) -> Self {
6259        self.sent = self.sent.forward_cancellation_from(source);
6260        self
6261    }
6262
6263    /// Associate this outgoing request with the incoming request being forwarded.
6264    ///
6265    /// Use this when transforming the response in a custom proxy callback.
6266    /// The association lets default ACP forwarding translate request-scoped
6267    /// elicitations and propagates cancellation from `responder`. Merely
6268    /// sharing a cancellation source does not establish request identity.
6269    /// If this request is itself an elicitation forwarded to the client,
6270    /// its request-scope ID is translated before sending.
6271    /// [`forward_response_to`](Self::forward_response_to) does this automatically.
6272    pub fn forwarded_from<Q: Protocol>(mut self, responder: &Responder<T, Q>) -> Self
6273    where
6274        T: JsonRpcResponse,
6275    {
6276        self.publication.pending_reply.forwarded_from =
6277            Some(responder.origin_for_forwarding(&self.publication.message_tx));
6278        self.forward_cancellation_from(responder.cancellation())
6279    }
6280
6281    /// Publish now and return an unordered future for the response.
6282    ///
6283    /// The request is enqueued during this call, not when the future is first
6284    /// polled. Dropping that future asks the peer to cancel a still-outstanding
6285    /// request. Await it only outside the dispatch loop; awaiting it in an
6286    /// incoming handler deadlocks just like [`SentRequest::block_task`].
6287    ///
6288    /// # Errors
6289    ///
6290    /// The returned future delivers preparation, publication, and response errors.
6291    pub fn block_task(self) -> impl Future<Output = Result<T, crate::Error>> {
6292        self.into_sent_request(false).block_task()
6293    }
6294
6295    /// Publish now and discard the eventual response without cancelling.
6296    ///
6297    /// # Errors
6298    ///
6299    /// Returns immediate preparation or enqueue failures. Later local
6300    /// transformation errors and peer response errors are discarded along with
6301    /// successful responses. Transport failures still propagate through the
6302    /// connection future. Retained [`RequestCancellationHandle`] values can
6303    /// still explicitly cancel the request while it remains pending.
6304    pub fn detach(self) -> Result<(), crate::Error> {
6305        let result = self.publication.publish();
6306        self.sent.detach();
6307        result
6308    }
6309
6310    /// Register an ordered callback, then publish the request.
6311    ///
6312    /// Ordering is selected before publication, even when the connection runs
6313    /// concurrently. See [`PreparedRequest`] for barrier limits and deadlock risks.
6314    ///
6315    /// # Errors
6316    ///
6317    /// Returns an error if the callback task cannot be registered, without
6318    /// publishing the request. Preparation and publication errors are delivered
6319    /// to the callback. Returning an error from the callback ends the connection.
6320    #[track_caller]
6321    pub fn on_receiving_result<F>(
6322        self,
6323        task: impl FnOnce(Result<T, crate::Error>) -> F + 'static + Send,
6324    ) -> Result<(), crate::Error>
6325    where
6326        T: 'static,
6327        F: Future<Output = Result<(), crate::Error>> + 'static + Send,
6328    {
6329        self.consume_with(move |response| match response {
6330            Ok(result) => Either::Left(task(result)),
6331            Err(error) => Either::Right(future::ready(Err(error))),
6332        })
6333    }
6334
6335    /// Register an ordered success callback, then publish the request.
6336    ///
6337    /// Errors are forwarded to `responder`, as with
6338    /// [`SentRequest::on_receiving_ok_result`].
6339    ///
6340    /// # Errors
6341    ///
6342    /// Returns a task-registration error without publishing the request.
6343    /// Preparation, publication, and response errors are forwarded to `responder`.
6344    /// Returning an error from the callback ends the connection.
6345    #[track_caller]
6346    pub fn on_receiving_ok_result<F, Q: Protocol>(
6347        self,
6348        responder: Responder<T, Q>,
6349        task: impl FnOnce(T, Responder<T, Q>) -> F + 'static + Send,
6350    ) -> Result<(), crate::Error>
6351    where
6352        T: JsonRpcResponse,
6353        F: Future<Output = Result<(), crate::Error>> + 'static + Send,
6354    {
6355        self.on_receiving_result(async move |result| match result {
6356            Ok(value) => task(value, responder).await,
6357            Err(error) => responder.respond_with_error(error),
6358        })
6359    }
6360
6361    /// Register ordered response forwarding, then publish the request.
6362    ///
6363    /// The upstream request ID is recorded before publication, so even an
6364    /// immediate request-scoped elicitation can be translated on its way back.
6365    /// Cancellation and response errors propagate as with [`SentRequest::forward_response_to`].
6366    ///
6367    /// # Errors
6368    ///
6369    /// Returns a task-registration error without publishing the request.
6370    /// Preparation, publication, and response errors are forwarded to `responder`.
6371    #[track_caller]
6372    pub fn forward_response_to<Q: Protocol>(
6373        self,
6374        responder: Responder<T, Q>,
6375    ) -> Result<(), crate::Error>
6376    where
6377        T: JsonRpcResponse,
6378    {
6379        self.forwarded_from(&responder)
6380            .consume_with(async move |response| {
6381                responder.respond_with_result(response.unwrap_or_else(Err))
6382            })
6383    }
6384
6385    pub(crate) fn into_sent_request(self, ordered: bool) -> SentRequest<T, P> {
6386        if ordered {
6387            self.sent.response_ordering.mark_ordered();
6388        }
6389        // Publication errors also settle the response channel.
6390        drop(self.publication.publish());
6391        self.sent
6392    }
6393
6394    #[track_caller]
6395    fn consume_with<F>(
6396        self,
6397        handle: impl FnOnce(Result<Result<T, crate::Error>, crate::Error>) -> F + 'static + Send,
6398    ) -> Result<(), crate::Error>
6399    where
6400        T: 'static,
6401        F: Future<Output = Result<(), crate::Error>> + 'static + Send,
6402    {
6403        let published_tx = self.register_consumer(handle)?;
6404        drop(self.publication.publish());
6405        // Keep the cancellation guard here until publication completes. Even
6406        // destruction of the registered task cannot cancel before enqueueing.
6407        drop(published_tx.send(self.sent));
6408        Ok(())
6409    }
6410
6411    #[track_caller]
6412    fn register_consumer<F>(
6413        &self,
6414        handle: impl FnOnce(Result<Result<T, crate::Error>, crate::Error>) -> F + 'static + Send,
6415    ) -> Result<oneshot::Sender<SentRequest<T, P>>, crate::Error>
6416    where
6417        T: 'static,
6418        F: Future<Output = Result<(), crate::Error>> + 'static + Send,
6419    {
6420        self.sent.response_ordering.mark_ordered();
6421        let (published_tx, published_rx) = oneshot::channel::<SentRequest<T, P>>();
6422        Task::new(Location::caller(), async move {
6423            match published_rx.await {
6424                Ok(sent) => sent.handle_response(handle).await,
6425                // Publication was abandoned before the consumer took ownership.
6426                Err(_) => Ok(()),
6427            }
6428        })
6429        .spawn(&self.sent.task_tx)?;
6430        Ok(published_tx)
6431    }
6432}
6433
6434#[derive(Clone, Debug)]
6435pub(crate) struct SentRequestCancellationDisarm {
6436    state: Arc<AtomicU8>,
6437}
6438
6439#[repr(u8)]
6440enum OutgoingCancellationState {
6441    Unpublished,
6442    Armed,
6443    Disarmed,
6444}
6445
6446impl SentRequestCancellationDisarm {
6447    fn new() -> Self {
6448        Self {
6449            state: Arc::new(AtomicU8::new(OutgoingCancellationState::Unpublished as u8)),
6450        }
6451    }
6452
6453    fn disarm(&self) {
6454        self.state
6455            .store(OutgoingCancellationState::Disarmed as u8, Ordering::Release);
6456    }
6457
6458    fn arm(&self) -> bool {
6459        self.state
6460            .compare_exchange(
6461                OutgoingCancellationState::Unpublished as u8,
6462                OutgoingCancellationState::Armed as u8,
6463                Ordering::AcqRel,
6464                Ordering::Acquire,
6465            )
6466            .is_ok()
6467    }
6468
6469    fn take_armed(&self) -> bool {
6470        self.state
6471            .compare_exchange(
6472                OutgoingCancellationState::Armed as u8,
6473                OutgoingCancellationState::Disarmed as u8,
6474                Ordering::AcqRel,
6475                Ordering::Acquire,
6476            )
6477            .is_ok()
6478    }
6479
6480    fn is_armed(&self) -> bool {
6481        self.state.load(Ordering::Acquire) == OutgoingCancellationState::Armed as u8
6482    }
6483
6484    fn is_disarmed(&self) -> bool {
6485        self.state.load(Ordering::Acquire) == OutgoingCancellationState::Disarmed as u8
6486    }
6487}
6488
6489/// Explicit cancellation control for one outgoing request.
6490///
6491/// Obtain this handle from [`PreparedRequest::cancellation_handle`] or
6492/// [`SentRequest::cancellation_handle`] before consuming the request. It retains
6493/// neither the response consumer nor application callback, so cancellation can
6494/// be requested without discarding the eventual response. It does not keep the
6495/// connection driver or response consumer alive, or abort local callback work.
6496///
6497/// Clones share the request's cancellation state with [`SentRequest::cancel`],
6498/// forwarded cancellation, and request-drop automatic cancellation. At most one
6499/// cancellation notification is attempted, on the original request's
6500/// connection. It is a plain `$/cancel_request`, even for a request sent to a
6501/// successor in a `proxy/successor` envelope. Dropping this handle neither cancels the request nor disables its
6502/// automatic cancellation.
6503///
6504/// Cancellation before publication is a no-op and is not remembered for later
6505/// publication. A call racing publication may also be a no-op; call after the
6506/// publishing method returns to target a pending request. Once the SDK routes a
6507/// response or fails the request, subsequent cancellation calls are no-ops,
6508/// even if its callback has not yet run. Detaching the request suppresses only
6509/// automatic cancellation; retained handles can still explicitly cancel it.
6510///
6511/// This controls outgoing requests, unlike [`RequestCancellation`], which
6512/// observes a peer's cancellation of an incoming request.
6513#[derive(Clone)]
6514pub struct RequestCancellationHandle {
6515    message_tx: OutgoingMessageTx,
6516    request_id: RawJsonRpcId,
6517    disarm: SentRequestCancellationDisarm,
6518}
6519
6520impl RequestCancellationHandle {
6521    /// Ask the peer to cancel this request without discarding its response.
6522    ///
6523    /// Cancellation is cooperative: the peer may respond normally or with a
6524    /// cancellation error. Repeated calls, including calls through other clones
6525    /// or the original request, return `Ok(())` without sending another
6526    /// notification. Calls before publication or after settlement are no-ops.
6527    /// An attempt begun before settlement may still enqueue afterward.
6528    ///
6529    /// `Ok(())` means this call encountered no immediate error, not that a
6530    /// notification was sent or the peer stopped work. This method does not
6531    /// wait for transmission or acknowledgment.
6532    ///
6533    /// # Errors
6534    ///
6535    /// Only the call that attempts to send reports serialization or enqueue
6536    /// failure. A failed send is not retried by later cancellation calls.
6537    pub fn cancel(&self) -> Result<(), crate::Error> {
6538        if !self.disarm.take_armed() {
6539            return Ok(());
6540        }
6541
6542        // Build the notification lazily: most requests are never cancelled,
6543        // so this avoids serializing a notification per outgoing request.
6544        //
6545        // `$/cancel_request` is hop-local and always sent plain, even for a
6546        // request sent to a successor: its `requestId` names the
6547        // `proxy/successor` request on this connection.
6548        let untyped = crate::v1::schema::CancelRequestNotification::new(self.request_id.clone())
6549            .to_untyped_message()?;
6550
6551        send_raw_message(&self.message_tx, OutgoingMessage::Notification { untyped })
6552    }
6553}
6554
6555impl Debug for RequestCancellationHandle {
6556    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
6557        formatter
6558            .debug_struct("RequestCancellationHandle")
6559            .field("request_id", &self.request_id)
6560            .field("armed", &self.disarm.is_armed())
6561            .finish_non_exhaustive()
6562    }
6563}
6564
6565#[derive(Debug)]
6566struct SentRequestCancellation {
6567    handle: RequestCancellationHandle,
6568    cancel_on_drop: bool,
6569}
6570
6571impl SentRequestCancellation {
6572    fn new(message_tx: OutgoingMessageTx, request_id: RawJsonRpcId) -> Self {
6573        Self {
6574            handle: RequestCancellationHandle {
6575                message_tx,
6576                request_id,
6577                disarm: SentRequestCancellationDisarm::new(),
6578            },
6579            cancel_on_drop: true,
6580        }
6581    }
6582
6583    fn disarm(&self) {
6584        self.handle.disarm.disarm();
6585    }
6586
6587    fn disarm_handle(&self) -> SentRequestCancellationDisarm {
6588        self.handle.disarm.clone()
6589    }
6590
6591    fn send(&self) -> Result<(), crate::Error> {
6592        self.handle.cancel()
6593    }
6594}
6595
6596impl Drop for SentRequestCancellation {
6597    fn drop(&mut self) {
6598        if !self.cancel_on_drop {
6599            return;
6600        }
6601        if let Err(error) = self.send() {
6602            tracing::debug!(
6603                error = ?crate::util::redacted_error(error.code),
6604                "failed to auto-cancel dropped request"
6605            );
6606        }
6607    }
6608}
6609
6610/// Await the response payload for an outgoing request, watching `sources` for
6611/// cancellation of the upstream requests it was registered with.
6612///
6613/// When any source reports cancellation, a `$/cancel_request` is forwarded to
6614/// the outgoing request (at most once, shared with [`SentRequest::cancel`] and
6615/// drop-time auto-cancellation), and the response is *still* awaited: the peer
6616/// always answers, with normal data or a cancellation error.
6617///
6618/// Watching is deliberately bounded by response arrival so that completed
6619/// requests do not leak waiters on markers that will never fire.
6620async fn await_response_forwarding_cancellation(
6621    response_rx: oneshot::Receiver<ResponsePayload>,
6622    cancellation: &SentRequestCancellation,
6623    sources: &[RequestCancellation],
6624) -> Result<ResponsePayload, oneshot::Canceled> {
6625    // Failing to forward the cancellation must not abort the wait: the
6626    // response (normal data or a cancellation error) may still arrive and
6627    // must still be processed.
6628    let forward_cancellation = || {
6629        if let Err(error) = cancellation.send() {
6630            tracing::debug!(
6631                error = ?crate::util::redacted_error(error.code),
6632                "failed to forward cancellation to downstream request"
6633            );
6634        }
6635    };
6636
6637    let response = if sources.is_empty() {
6638        response_rx.await
6639    } else if sources.iter().any(RequestCancellation::is_cancelled) {
6640        forward_cancellation();
6641        response_rx.await
6642    } else {
6643        let cancelled = sources.iter().map(|source| source.state.signal_rx.clone());
6644        match future::select(future::select_all(cancelled), response_rx).await {
6645            Either::Left((_, response_rx)) => {
6646                forward_cancellation();
6647                response_rx.await
6648            }
6649            Either::Right((response, _)) => response,
6650        }
6651    };
6652
6653    cancellation.disarm();
6654    response
6655}
6656
6657impl<T: Debug, P: Protocol> Debug for SentRequest<T, P> {
6658    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
6659        let mut debug = f.debug_struct("SentRequest");
6660        debug
6661            .field("id", &self.id)
6662            .field("method", &self.method)
6663            .field("task_tx", &self.task_tx)
6664            .field("response_rx", &self.response_rx);
6665        debug
6666            .field("cancellation", &self.cancellation)
6667            .field("cancellation_sources", &self.cancellation_sources);
6668        debug.finish_non_exhaustive()
6669    }
6670}
6671
6672impl<P: Protocol> SentRequest<serde_json::Value, P> {
6673    fn new(
6674        id: HandleId<P>,
6675        method: String,
6676        task_tx: mpsc::UnboundedSender<Task>,
6677        pending_replies: PendingRepliesRegistrar,
6678        response_rx: oneshot::Receiver<ResponsePayload>,
6679        cancellation: SentRequestCancellation,
6680        response_ordering: ResponseOrdering,
6681    ) -> Self {
6682        Self {
6683            id,
6684            method,
6685            response_rx,
6686            task_tx,
6687            pending_replies,
6688            to_result: Box::new(|result| result),
6689            cancellation,
6690            response_ordering,
6691            cancellation_sources: Vec::new(),
6692        }
6693    }
6694}
6695
6696impl<T, P: Protocol> SentRequest<T, P> {
6697    /// Detach this request handle without waiting for its response.
6698    ///
6699    /// The response will be discarded when it arrives. This also disables the
6700    /// drop-time automatic cancellation described in
6701    /// [Drop Behavior](Self#drop-behavior), so use it for requests whose
6702    /// eventual response should be ignored, but which should keep running on
6703    /// the peer. The peer is still expected to answer the JSON-RPC request
6704    /// eventually; use a notification instead when no response is expected at
6705    /// all.
6706    ///
6707    /// To ask the peer to stop the request, call `cancel` instead, or drop the
6708    /// handle while automatic cancellation is enabled. A retained
6709    /// [`RequestCancellationHandle`] can still explicitly cancel the detached
6710    /// request until the SDK receives its response or fails it.
6711    pub fn detach(mut self) {
6712        self.cancellation.cancel_on_drop = false;
6713    }
6714
6715    /// Send a `$/cancel_request` notification for this outgoing request.
6716    ///
6717    /// The notification goes over the connection the original request used,
6718    /// with that request's ID, so this is the preferred way to cancel a
6719    /// [`SentRequest`] when the request handle is still available. It is sent
6720    /// plain, never wrapped in `proxy/successor`: for a request sent to a
6721    /// successor, the ID names the `proxy/successor` request on this
6722    /// connection, as the proxy chains RFD specifies.
6723    ///
6724    /// At most one cancellation attempt is made per request, shared with
6725    /// retained handles, forwarded cancellation, and automatic cancellation
6726    /// described in [Drop Behavior](Self#drop-behavior). Later calls return
6727    /// `Ok(())` without another attempt, including when the first attempt failed.
6728    /// Once the SDK has routed the response, a new call is a no-op; an attempt
6729    /// begun before settlement may still enqueue afterward.
6730    ///
6731    /// `Ok(())` means this call encountered no immediate error, not that a
6732    /// notification was sent or the peer stopped work.
6733    ///
6734    /// # Errors
6735    ///
6736    /// Only the call that attempts to send reports a failure to encode or
6737    /// queue the notification. See [`RequestCancellationHandle::cancel`].
6738    pub fn cancel(&self) -> Result<(), crate::Error> {
6739        self.cancellation.send()
6740    }
6741
6742    /// Obtain a handle that remains usable after this request is consumed.
6743    ///
6744    /// The handle shares the once-only cancellation state used by
6745    /// [`cancel`](Self::cancel), response routing, and automatic request-drop
6746    /// cancellation, but has no cancel-on-drop behavior of its own.
6747    #[must_use]
6748    pub fn cancellation_handle(&self) -> RequestCancellationHandle {
6749        self.cancellation.handle.clone()
6750    }
6751
6752    /// Forward cancellation of another request to this one.
6753    ///
6754    /// When the request that `source` belongs to is cancelled by its peer,
6755    /// a `$/cancel_request` for *this* request is sent to its peer, plain and
6756    /// with this request's ID, as [`cancel`](Self::cancel) sends it. The response is still awaited
6757    /// and delivered as usual (normal data or a cancellation error), so this
6758    /// composes with [`block_task`](Self::block_task) and
6759    /// [`on_receiving_result`](Self::on_receiving_result).
6760    ///
6761    /// This is the building block for proxies that forward a request with
6762    /// custom logic instead of [`forward_response_to`](Self::forward_response_to)
6763    /// (which wires this up automatically from its responder). Without it,
6764    /// custom forwarding *absorbs* cancellation: the upstream marker is still
6765    /// set, but nothing is sent downstream.
6766    ///
6767    /// ```
6768    /// # use agent_client_protocol::{ConnectionTo, Error, Responder, UntypedRole};
6769    /// # use agent_client_protocol_test::{MyRequest, MyResponse};
6770    /// # async fn example(request: MyRequest, responder: Responder<MyResponse>, backend: ConnectionTo<UntypedRole>) -> Result<(), Error> {
6771    /// backend
6772    ///     .send_request(request)
6773    ///     .forward_cancellation_from(responder.cancellation())
6774    ///     .on_receiving_result(async move |result| {
6775    ///         // Custom result handling, e.g. bookkeeping or rewriting.
6776    ///         responder.respond_with_result(result)
6777    ///     })?;
6778    /// # Ok(())
6779    /// # }
6780    /// ```
6781    ///
6782    /// May be called multiple times; cancellation of any registered source
6783    /// triggers the forwarding (at most one `$/cancel_request` is ever sent
6784    /// per request). Sources are observed while the response is being
6785    /// awaited — that is, once the handle is consumed with
6786    /// [`block_task`](Self::block_task),
6787    /// [`on_receiving_result`](Self::on_receiving_result), or
6788    /// [`forward_response_to`](Self::forward_response_to); a source that was
6789    /// already cancelled by then is honored immediately.
6790    pub fn forward_cancellation_from(mut self, source: RequestCancellation) -> Self {
6791        self.cancellation_sources.push(source);
6792        self
6793    }
6794}
6795
6796impl<T, P: Protocol> SentRequest<T, P> {
6797    /// The same request handle with a version-neutral [`Raw`] request ID, for
6798    /// code that is not tied to one protocol version. This never fails.
6799    pub fn into_raw(self) -> SentRequest<T, Raw> {
6800        self.retag_id(HandleId::into_raw)
6801    }
6802
6803    fn retag_id<Q: Protocol>(
6804        self,
6805        retag: impl FnOnce(HandleId<P>) -> HandleId<Q>,
6806    ) -> SentRequest<T, Q> {
6807        SentRequest {
6808            id: retag(self.id),
6809            method: self.method,
6810            task_tx: self.task_tx,
6811            pending_replies: self.pending_replies,
6812            response_rx: self.response_rx,
6813            to_result: self.to_result,
6814            cancellation: self.cancellation,
6815            response_ordering: self.response_ordering,
6816            cancellation_sources: self.cancellation_sources,
6817        }
6818    }
6819}
6820
6821impl<T> SentRequest<T, Raw> {
6822    /// Convert this version-neutral request handle to protocol `Q`'s handle.
6823    ///
6824    /// # Errors
6825    ///
6826    /// Fails only for an ID that `Q` rejects. The SDK never assigns `null`
6827    /// to outgoing requests, so its request handles convert to every marker.
6828    pub fn into_protocol<Q: Protocol>(self) -> Result<SentRequest<T, Q>, crate::Error> {
6829        let id = self.id.clone().into_protocol()?;
6830        Ok(self.retag_id(|_| id))
6831    }
6832}
6833
6834impl<T, P: Protocol> SentRequest<T, P> {
6835    /// The id of the outgoing request, as this request's protocol version
6836    /// types it. It is the ID written to the wire; the SDK never assigns
6837    /// `null`.
6838    #[must_use]
6839    pub fn id(&self) -> &P::RequestId {
6840        self.id.typed()
6841    }
6842
6843    /// The id of the outgoing request in the version-neutral form used by
6844    /// routers, forwarders and tracing. It is the same ID as
6845    /// [`id`](Self::id).
6846    #[must_use]
6847    pub fn raw_id(&self) -> &RawJsonRpcId {
6848        self.id.raw()
6849    }
6850
6851    /// The method of the request this is in response to.
6852    #[must_use]
6853    pub fn method(&self) -> &str {
6854        &self.method
6855    }
6856
6857    /// Map a JSON-RPC error response to a result of the same type.
6858    ///
6859    /// The recovery function only sees error responses from the peer, not
6860    /// local failures to decode a successful response. Return `Ok` to treat
6861    /// the error as success, or `Err` to keep failing.
6862    #[cfg_attr(not(feature = "unstable_protocol_v2"), allow(dead_code))]
6863    pub(crate) fn recover_error(
6864        self,
6865        recover: impl FnOnce(crate::Error) -> Result<T, crate::Error> + 'static + Send,
6866    ) -> SentRequest<T, P>
6867    where
6868        T: 'static,
6869    {
6870        let to_result = self.to_result;
6871        SentRequest {
6872            to_result: Box::new(move |result| match result {
6873                Ok(value) => to_result(Ok(value)),
6874                Err(error) => recover(error),
6875            }),
6876            ..self
6877        }
6878    }
6879
6880    /// Map a successful JSON-RPC response into an application type.
6881    ///
6882    /// The mapped type does not need to implement [`JsonRpcResponse`]. The
6883    /// mapper runs at most once and may consume captured state. JSON-RPC error
6884    /// responses bypass the mapper. The mapped type may carry a non-`'static`
6885    /// lifetime when it is consumed with [`block_task`](Self::block_task);
6886    /// callback-style consumption still requires a `'static` mapped type
6887    /// because its work is spawned onto the connection.
6888    pub fn map<U>(
6889        self,
6890        map_fn: impl FnOnce(T) -> Result<U, crate::Error> + 'static + Send,
6891    ) -> SentRequest<U, P>
6892    where
6893        T: 'static,
6894    {
6895        SentRequest {
6896            id: self.id,
6897            method: self.method,
6898            response_rx: self.response_rx,
6899            task_tx: self.task_tx,
6900            pending_replies: self.pending_replies,
6901            to_result: Box::new(move |result| map_fn((self.to_result)(result)?)),
6902            cancellation: self.cancellation,
6903            response_ordering: self.response_ordering,
6904            cancellation_sources: self.cancellation_sources,
6905        }
6906    }
6907
6908    /// Forward the response (success or error) to a request context when it arrives.
6909    ///
6910    /// This is a convenience method for proxying messages between connections. When the
6911    /// response arrives, it will be automatically sent to the provided request context,
6912    /// whether it's a successful response or an error.
6913    ///
6914    /// This also records the upstream ID for request-scoped elicitations.
6915    /// When the peer can run concurrently, use [`PreparedRequest::forward_response_to`]
6916    /// to install that association before the outgoing request is observable.
6917    /// Use the prepared form when relaying an elicitation back to the client:
6918    /// an eager send can no longer change the callback's `params.requestId`.
6919    ///
6920    /// # Example: Proxying requests
6921    ///
6922    /// ```
6923    /// # use agent_client_protocol::UntypedRole;
6924    /// # use agent_client_protocol::{Builder, ConnectionTo};
6925    /// # use agent_client_protocol_test::*;
6926    /// # async fn example(cx: ConnectionTo<UntypedRole>) -> Result<(), agent_client_protocol::Error> {
6927    /// // Set up backend connection builder
6928    /// let backend = UntypedRole.builder()
6929    ///     .on_receive_request(async |req: MyRequest, responder, cx| {
6930    ///         responder.respond(MyResponse { status: "ok".into() })
6931    ///     }, agent_client_protocol::on_receive_request!());
6932    ///
6933    /// // Spawn backend and get a context to send to it
6934    /// let backend_connection = cx.spawn_connection(backend, MockTransport)?;
6935    ///
6936    /// // Set up proxy that forwards requests to backend
6937    /// UntypedRole.builder()
6938    ///     .on_receive_request({
6939    ///         let backend_connection = backend_connection.clone();
6940    ///         async move |req: MyRequest, responder, cx| {
6941    ///             // Forward the request to backend and proxy the response back
6942    ///             backend_connection.send_request(req)
6943    ///                 .forward_response_to(responder)?;
6944    ///             Ok(())
6945    ///         }
6946    ///     }, agent_client_protocol::on_receive_request!());
6947    /// # Ok(())
6948    /// # }
6949    /// ```
6950    ///
6951    /// # Type Safety
6952    ///
6953    /// The request context's response type must match the request's response type,
6954    /// ensuring type-safe message forwarding.
6955    ///
6956    /// # When to Use
6957    ///
6958    /// Use this when:
6959    /// - You're implementing a proxy or gateway pattern
6960    /// - You want to forward responses without processing them
6961    /// - The response types match between the outgoing request and incoming request
6962    ///
6963    /// This is equivalent to calling `on_receiving_result` and manually forwarding
6964    /// the result, with two proxy-specific additions:
6965    ///
6966    /// - If the pending response cannot be delivered, the incoming request is
6967    ///   answered with an internal error instead of being left unanswered.
6968    ///   Known clean incoming EOF is delivered like any other response
6969    ///   error; an unexpected response-channel loss is forwarded as an outer
6970    ///   consumption error.
6971    /// - When the peer cancels the incoming request, the cancellation is
6972    ///   forwarded to the outgoing request, and the downstream response
6973    ///   (normal data or a cancellation error) is still forwarded back. This is
6974    ///   equivalent to registering the responder's marker with
6975    ///   `forward_cancellation_from`.
6976    ///
6977    /// # Errors
6978    ///
6979    /// Returns an error if the connection cannot queue the forwarding task.
6980    /// A failure to receive or decode the response is forwarded to `responder`.
6981    #[track_caller]
6982    pub fn forward_response_to<Q: Protocol>(
6983        self,
6984        responder: Responder<T, Q>,
6985    ) -> Result<(), crate::Error>
6986    where
6987        T: JsonRpcResponse,
6988    {
6989        self.pending_replies.set_origin(
6990            self.raw_id(),
6991            responder.origin_for_forwarding(&self.cancellation.handle.message_tx),
6992        );
6993        let this = self.forward_cancellation_from(responder.cancellation());
6994
6995        this.consume_with(async move |response| {
6996            // An unexpected response-channel loss (outer `Err`) is forwarded
6997            // as an error: the incoming request must not be left unanswered.
6998            responder.respond_with_result(response.unwrap_or_else(Err))
6999        })
7000    }
7001
7002    /// Spawn the response-consumption task shared by
7003    /// [`on_receiving_result`](Self::on_receiving_result) and
7004    /// [`forward_response_to`](Self::forward_response_to).
7005    ///
7006    /// The task awaits the response (forwarding cancellation from registered
7007    /// sources while waiting, converts the payload, and invokes `handle` with
7008    /// the typed result (`Ok(Result<T, _>)`). The dispatch loop's ack, if any,
7009    /// is sent after `handle` completes.
7010    ///
7011    /// Clean incoming EOF is delivered as `Ok(Err(error))`, just like
7012    /// a peer response error, so callback-style consumers still run. If the
7013    /// response channel disappears for another reason, `handle` receives an
7014    /// outer `Err` describing that unexpected loss; there is no ack then.
7015    #[track_caller]
7016    fn consume_with<F>(
7017        self,
7018        handle: impl FnOnce(Result<Result<T, crate::Error>, crate::Error>) -> F + 'static + Send,
7019    ) -> Result<(), crate::Error>
7020    where
7021        T: 'static,
7022        F: Future<Output = Result<(), crate::Error>> + 'static + Send,
7023    {
7024        self.response_ordering.mark_ordered();
7025        let task_tx = self.task_tx.clone();
7026        Task::new(Location::caller(), self.handle_response(handle)).spawn(&task_tx)
7027    }
7028
7029    fn handle_response<F>(
7030        self,
7031        handle: impl FnOnce(Result<Result<T, crate::Error>, crate::Error>) -> F + 'static + Send,
7032    ) -> impl Future<Output = Result<(), crate::Error>> + Send
7033    where
7034        T: 'static,
7035        F: Future<Output = Result<(), crate::Error>> + 'static + Send,
7036    {
7037        let method = self.method;
7038        let response_rx = self.response_rx;
7039        let to_result = self.to_result;
7040        let cancellation = self.cancellation;
7041        let cancellation_sources = self.cancellation_sources;
7042        async move {
7043            let response = await_response_forwarding_cancellation(
7044                response_rx,
7045                &cancellation,
7046                &cancellation_sources,
7047            )
7048            .await;
7049
7050            match response {
7051                Ok(ResponsePayload { result, ack_tx }) => {
7052                    let typed_result = to_result(result);
7053
7054                    let outcome = handle(Ok(typed_result)).await;
7055
7056                    // Ack AFTER the handler completes - this is the key
7057                    // difference from block_task. The dispatch loop waits for
7058                    // this ack.
7059                    if let Some(tx) = ack_tx {
7060                        let _ = tx.send(());
7061                    }
7062
7063                    outcome
7064                }
7065                Err(err) => {
7066                    handle(Err(crate::util::internal_error(format!(
7067                        "response to `{method}` never received: {err}"
7068                    ))))
7069                    .await
7070                }
7071            }
7072        }
7073    }
7074
7075    /// Block the current task until the response is received.
7076    ///
7077    /// **Warning:** This method blocks the current async task. It is safe only when that task
7078    /// already runs outside the dispatch loop, such as the foreground future passed to
7079    /// `connect_with` or a task created with [`ConnectionTo::spawn`]. Using it directly in a
7080    /// handler callback will deadlock the connection.
7081    ///
7082    /// # Safe Usage (outside the dispatch loop)
7083    ///
7084    /// ```no_run
7085    /// # use agent_client_protocol_test::*;
7086    /// # async fn example() -> Result<(), agent_client_protocol::Error> {
7087    /// # let connection = mock_connection();
7088    /// connection.on_receive_request(async |req: MyRequest, responder, cx| {
7089    ///     // Spawn a task to handle the request
7090    ///     cx.spawn({
7091    ///         let connection = cx.clone();
7092    ///         async move {
7093    ///             // Safe: We're in a spawned task, not blocking the event loop
7094    ///             let response = connection.send_request(OtherRequest {})
7095    ///                 .block_task()
7096    ///                 .await?;
7097    ///
7098    ///             // Process the response...
7099    ///             Ok(())
7100    ///         }
7101    ///     })?;
7102    ///
7103    ///     // Respond immediately
7104    ///     responder.respond(MyResponse { status: "ok".into() })
7105    /// }, agent_client_protocol::on_receive_request!())
7106    /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
7107    /// # Ok(())
7108    /// # }
7109    /// ```
7110    ///
7111    /// # Unsafe Usage (in handlers - will deadlock!)
7112    ///
7113    /// ```no_run
7114    /// # use agent_client_protocol_test::*;
7115    /// # async fn example() -> Result<(), agent_client_protocol::Error> {
7116    /// # let connection = mock_connection();
7117    /// connection.on_receive_request(async |req: MyRequest, responder, cx| {
7118    ///     // ❌ DEADLOCK: Handler blocks event loop, which can't process the response
7119    ///     let response = cx.send_request(OtherRequest {})
7120    ///         .block_task()
7121    ///         .await?;
7122    ///
7123    ///     responder.respond(MyResponse { status: response.value })
7124    /// }, agent_client_protocol::on_receive_request!())
7125    /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
7126    /// # Ok(())
7127    /// # }
7128    /// ```
7129    ///
7130    /// # When to Use
7131    ///
7132    /// Use this method when:
7133    /// - Your current task already runs outside the dispatch loop
7134    /// - You need the response value to proceed with your logic
7135    /// - Linear control flow is more natural than callbacks
7136    ///
7137    /// For handler callbacks, use [`on_receiving_result`](Self::on_receiving_result) instead.
7138    ///
7139    /// # Errors
7140    ///
7141    /// Returns a request or peer response error, an error decoding or mapping
7142    /// the response, or an error if the connection closes before the reply arrives.
7143    pub async fn block_task(self) -> Result<T, crate::Error> {
7144        let response = await_response_forwarding_cancellation(
7145            self.response_rx,
7146            &self.cancellation,
7147            &self.cancellation_sources,
7148        )
7149        .await;
7150
7151        match response {
7152            Ok(ResponsePayload { result, ack_tx }) => {
7153                // Blocking consumers ack before converting or returning the
7154                // value, so dispatch can continue while the caller processes it.
7155                if let Some(tx) = ack_tx {
7156                    let _ = tx.send(());
7157                }
7158                (self.to_result)(result)
7159            }
7160            Err(err) => Err(crate::util::internal_error(format!(
7161                "response to `{}` never received: {}",
7162                self.method, err
7163            ))),
7164        }
7165    }
7166
7167    /// Block the current task and transform the typed result before releasing
7168    /// the ordered-response barrier.
7169    ///
7170    /// Framework lifecycle code uses this when success transfers local state
7171    /// to the returned value while an error must drop that state before later
7172    /// messages from the same transport frame are dispatched. The synchronous
7173    /// transform must not wait for additional connection traffic.
7174    pub(crate) async fn block_task_with_ordered_result<U>(
7175        self,
7176        transform: impl FnOnce(Result<T, crate::Error>) -> Result<U, crate::Error>,
7177    ) -> Result<U, crate::Error> {
7178        let response = await_response_forwarding_cancellation(
7179            self.response_rx,
7180            &self.cancellation,
7181            &self.cancellation_sources,
7182        )
7183        .await;
7184
7185        let (result, ack_tx) = match response {
7186            Ok(ResponsePayload { result, ack_tx }) => ((self.to_result)(result), ack_tx),
7187            Err(error) => (
7188                Err(crate::util::internal_error(format!(
7189                    "response to `{}` never received: {error}",
7190                    self.method
7191                ))),
7192                None,
7193            ),
7194        };
7195
7196        let outcome = transform(result);
7197        if let Some(acknowledgment) = ack_tx {
7198            let _ = acknowledgment.send(());
7199        }
7200        outcome
7201    }
7202
7203    /// Schedule an async task to run when a successful response is received.
7204    ///
7205    /// This is a convenience wrapper around [`on_receiving_result`](Self::on_receiving_result)
7206    /// for the common pattern of forwarding errors to a request context while only processing
7207    /// successful responses.
7208    ///
7209    /// # Behavior
7210    ///
7211    /// - If the response is `Ok(value)`, your task receives the value and the request context
7212    /// - If the response is `Err(error)`, the error is automatically sent to `responder`
7213    ///   and your task is not called
7214    ///
7215    /// # Example: Chaining requests
7216    ///
7217    /// ```no_run
7218    /// # use agent_client_protocol_test::*;
7219    /// # async fn example() -> Result<(), agent_client_protocol::Error> {
7220    /// # let connection = mock_connection();
7221    /// connection.on_receive_request(async |req: ValidateRequest, responder, cx| {
7222    ///     // Send initial request
7223    ///     cx.send_request(ValidateRequest { data: req.data.clone() })
7224    ///         .on_receiving_ok_result(responder, async |validation, responder| {
7225    ///             // Only runs if validation succeeded
7226    ///             if validation.is_valid {
7227    ///                 // Respond to original request
7228    ///                 responder.respond(ValidateResponse { is_valid: true, error: None })
7229    ///             } else {
7230    ///                 responder.respond_with_error(agent_client_protocol::Error::internal_error().data("validation failed"))
7231    ///             }
7232    ///         })?;
7233    ///
7234    ///     Ok(())
7235    /// }, agent_client_protocol::on_receive_request!())
7236    /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
7237    /// # Ok(())
7238    /// # }
7239    /// ```
7240    ///
7241    /// # Ordering
7242    ///
7243    /// Like [`on_receiving_result`](Self::on_receiving_result), response handling holds the
7244    /// dispatch loop through callback completion when ordered consumption is selected before a
7245    /// peer response is routed during its original dispatch. Pending-request failures delivered
7246    /// without an incoming response and delayed routes do not carry that barrier. The callback
7247    /// must not await later inbound traffic on the same connection. See the
7248    /// [`ordering`](crate::concepts::ordering) module for details.
7249    ///
7250    /// # When to Use
7251    ///
7252    /// Use this when:
7253    /// - You need to respond to a request based on another request's result
7254    /// - You want errors to automatically propagate to the request context
7255    /// - You only care about the success case
7256    ///
7257    /// For more control over error handling, use [`on_receiving_result`](Self::on_receiving_result).
7258    ///
7259    /// # Errors
7260    ///
7261    /// Returns an error if the callback task cannot be queued. A request
7262    /// error is sent to `responder` instead of invoking the success callback.
7263    #[track_caller]
7264    pub fn on_receiving_ok_result<F, Q: Protocol>(
7265        self,
7266        responder: Responder<T, Q>,
7267        task: impl FnOnce(T, Responder<T, Q>) -> F + 'static + Send,
7268    ) -> Result<(), crate::Error>
7269    where
7270        F: Future<Output = Result<(), crate::Error>> + 'static + Send,
7271        T: JsonRpcResponse,
7272    {
7273        self.on_receiving_result(async move |result| match result {
7274            Ok(value) => task(value, responder).await,
7275            Err(err) => responder.respond_with_error(err),
7276        })
7277    }
7278
7279    /// Register an async callback to run when the response is received.
7280    ///
7281    /// This is the recommended way to select response handling from inside a handler because
7282    /// registration returns immediately. The response-consumption task waits concurrently for
7283    /// the response; once the response is dispatched, the ordered callback may hold the dispatch
7284    /// loop until it completes.
7285    ///
7286    /// # Example: Handle response in callback
7287    ///
7288    /// ```no_run
7289    /// # use agent_client_protocol_test::*;
7290    /// # async fn example() -> Result<(), agent_client_protocol::Error> {
7291    /// # let connection = mock_connection();
7292    /// connection.on_receive_request(async |req: MyRequest, responder, cx| {
7293    ///     // Send a request and schedule a callback for the response
7294    ///     cx.send_request(QueryRequest { id: 22 })
7295    ///         .on_receiving_result({
7296    ///             let connection = cx.clone();
7297    ///             async move |result| {
7298    ///                 match result {
7299    ///                     Ok(response) => {
7300    ///                         println!("Got response: {:?}", response);
7301    ///                         // Can send more messages here
7302    ///                         connection.send_notification(QueryComplete {})?;
7303    ///                         Ok(())
7304    ///                 }
7305    ///                     Err(error) => {
7306    ///                         eprintln!("Request failed: {}", error);
7307    ///                         Err(error)
7308    ///                     }
7309    ///                 }
7310    ///             }
7311    ///         })?;
7312    ///
7313    ///     // Handler continues immediately after registering the callback
7314    ///     responder.respond(MyResponse { status: "processing".into() })
7315    /// }, agent_client_protocol::on_receive_request!())
7316    /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
7317    /// # Ok(())
7318    /// # }
7319    /// ```
7320    ///
7321    /// # Ordering
7322    ///
7323    /// When ordered consumption is selected before a peer response is routed during its original
7324    /// dispatch, the callback runs in a connection-managed task and the dispatch loop waits for
7325    /// it to complete before processing the next message.
7326    ///
7327    /// The barrier does not apply when the pending request is failed without an incoming response,
7328    /// such as on EOF. If the response was already routed, or an interceptor routes a retained
7329    /// [`ResponseRouter`] after its original dispatch, the callback still runs but cannot
7330    /// retroactively block messages that were already released.
7331    ///
7332    /// While the barrier is held, the callback must not await a later response, notification, or
7333    /// other inbound traffic on the same connection: that traffic cannot be dispatched until the
7334    /// callback completes. Spawn follow-up work with [`ConnectionTo::spawn`] and return, or use
7335    /// [`block_task`](Self::block_task) from a task already outside the dispatch loop.
7336    ///
7337    /// This differs from [`block_task`](Self::block_task), which does not select ordered
7338    /// consumption: dispatch remains free while the caller processes the delivered response.
7339    ///
7340    /// See the [`ordering`](crate::concepts::ordering) module for details on ordering guarantees
7341    /// and how to avoid deadlocks.
7342    ///
7343    /// # Errors
7344    ///
7345    /// Returns an error if the callback task cannot be queued. Peer errors
7346    /// and response decoding errors are passed to the callback. An error
7347    /// returned by the callback shuts down the connection.
7348    ///
7349    /// # When to Use
7350    ///
7351    /// Use this method when:
7352    /// - You need to register response handling from a handler callback
7353    /// - You want a peer response callback to complete before later messages are dispatched
7354    /// - The callback performs bounded work that does not depend on later inbound traffic
7355    ///
7356    /// When already outside the dispatch loop and you do not need ordering guarantees, consider
7357    /// [`block_task`](Self::block_task).
7358    #[track_caller]
7359    pub fn on_receiving_result<F>(
7360        self,
7361        task: impl FnOnce(Result<T, crate::Error>) -> F + 'static + Send,
7362    ) -> Result<(), crate::Error>
7363    where
7364        T: 'static,
7365        F: Future<Output = Result<(), crate::Error>> + 'static + Send,
7366    {
7367        self.consume_with(move |response| match response {
7368            // Invoke the callback before constructing its future so the
7369            // response value does not need to be `Send` across an await.
7370            Ok(result) => Either::Left(task(result)),
7371            // A response that was never delivered fails the consuming
7372            // task instead of invoking the callback.
7373            Err(err) => Either::Right(future::ready(Err(err))),
7374        })
7375    }
7376}
7377
7378// ============================================================================
7379// IntoJrConnectionTransport Implementations
7380// ============================================================================
7381
7382/// A component that communicates over line streams.
7383///
7384/// `Lines` implements the [`ConnectTo`] trait for any pair of line-based streams
7385/// (a `Stream<Item = io::Result<String>>` for incoming and a `Sink<String>` for outgoing),
7386/// handling serialization of JSON-RPC messages to/from newline-delimited JSON.
7387/// Each line carries one JSON-RPC message. JSON-RPC batch arrays are not supported: an
7388/// incoming array is answered with a single invalid-request (`-32600`) error with `id: null`.
7389///
7390/// This is a lower-level primitive than [`ByteStreams`] that enables interception and
7391/// transformation of individual lines before they are parsed or after they are serialized.
7392/// This is particularly useful for debugging, logging, or implementing custom line-based
7393/// protocols.
7394///
7395/// An `Err` from the incoming stream ends the connection. A stream that decodes bytes itself
7396/// should replace invalid UTF-8, as [`ByteStreams`] does, instead of yielding an error for it.
7397///
7398/// # Use Cases
7399///
7400/// - **Line-by-line logging**: Intercept and log each line before parsing
7401/// - **Custom protocols**: Transform lines before/after JSON-RPC processing
7402/// - **Debugging**: Inspect raw message strings
7403/// - **Line filtering**: Skip or modify specific messages
7404///
7405/// Most users should use [`ByteStreams`] instead, which provides a simpler interface
7406/// for byte-based I/O.
7407///
7408/// [`ConnectTo`]: crate::ConnectTo
7409#[derive(Debug)]
7410pub struct Lines<OutgoingSink, IncomingStream> {
7411    outgoing: OutgoingSink,
7412    incoming: IncomingStream,
7413}
7414
7415impl<OutgoingSink, IncomingStream> Lines<OutgoingSink, IncomingStream>
7416where
7417    OutgoingSink: futures::Sink<String, Error = std::io::Error> + Send + 'static,
7418    IncomingStream: futures::Stream<Item = std::io::Result<String>> + Send + 'static,
7419{
7420    /// Create a new line stream transport.
7421    pub fn new(outgoing: OutgoingSink, incoming: IncomingStream) -> Self {
7422        Self { outgoing, incoming }
7423    }
7424
7425    fn into_channel_transport(self) -> (Channel, crate::ConnectionDriver) {
7426        let Self { outgoing, incoming } = self;
7427        let (channel_for_caller, channel_for_lines) = Channel::duplex();
7428        let Channel { mut rx, tx } = channel_for_lines;
7429        let (finish_tx, finish_rx) = oneshot::channel();
7430        let finish = async move {
7431            // Losing a finish handle is not a shutdown request.
7432            if finish_rx.await.is_err() {
7433                future::pending::<()>().await;
7434            }
7435        }
7436        .boxed()
7437        .shared();
7438        let outgoing_frames = futures::stream::poll_fn({
7439            let mut finish = finish.clone();
7440            let mut finishing = false;
7441            move |cx| {
7442                if !finishing && std::pin::Pin::new(&mut finish).poll(cx).is_ready() {
7443                    rx.close();
7444                    finishing = true;
7445                }
7446                rx.poll_next_unpin(cx)
7447            }
7448        });
7449        let discard_incoming = Arc::new(AtomicBool::new(false));
7450        let incoming = incoming.filter_map({
7451            let discard_incoming = discard_incoming.clone();
7452            move |item| {
7453                let discard = discard_incoming.load(Ordering::Acquire);
7454                future::ready((!discard || item.is_err()).then_some(item))
7455            }
7456        });
7457        let outgoing = transport_actor::transport_outgoing_lines_actor(outgoing_frames, outgoing)
7458            .boxed()
7459            .shared();
7460        let serve_self = Box::pin({
7461            let outgoing = outgoing.clone();
7462            async move {
7463                futures::try_join!(
7464                    outgoing,
7465                    transport_actor::transport_incoming_lines_actor(incoming, tx),
7466                )?;
7467                Ok(())
7468            }
7469        });
7470        let server_future = crate::ConnectionDriver::with_finish(
7471            async move {
7472                match future::select(finish, serve_self).await {
7473                    Either::Left(((), serve_self)) => {
7474                        discard_incoming.store(true, Ordering::Release);
7475                        // Keep reading while flushing, but do not require remote
7476                        // read EOF. Poll incoming errors before clean sink drain.
7477                        match future::select(serve_self, outgoing).await {
7478                            Either::Left((result, _)) | Either::Right((result, _)) => result,
7479                        }
7480                    }
7481                    Either::Right((result, _)) => result,
7482                }
7483            },
7484            move || {
7485                let _ = finish_tx.send(());
7486            },
7487        );
7488
7489        (channel_for_caller, server_future)
7490    }
7491}
7492
7493impl<OutgoingSink, IncomingStream, R: Role> ConnectTo<R> for Lines<OutgoingSink, IncomingStream>
7494where
7495    OutgoingSink: futures::Sink<String, Error = std::io::Error> + Send + 'static,
7496    IncomingStream: futures::Stream<Item = std::io::Result<String>> + Send + 'static,
7497{
7498    async fn connect_to(self, client: impl ConnectTo<R::Counterpart>) -> Result<(), crate::Error> {
7499        let (channel, mut serve_self) = self.into_channel_transport();
7500        let mut finish = serve_self
7501            .take_finish()
7502            .expect("built-in Lines transport supports explicit finishing");
7503        let client_future = Box::pin(ConnectTo::<R>::connect_to(channel, client));
7504
7505        match futures::future::select(client_future, serve_self).await {
7506            Either::Left((result, serve_self)) => {
7507                result?;
7508                // The local bridge has transferred all accepted client output.
7509                // Finish the physical sink without waiting for remote read EOF.
7510                finish.request();
7511                serve_self.await
7512            }
7513            Either::Right((result, _)) => result,
7514        }
7515    }
7516
7517    fn into_channel_and_future(self) -> (Channel, Option<crate::ConnectionDriver>) {
7518        let (channel, driver) = self.into_channel_transport();
7519        (channel, Some(driver))
7520    }
7521}
7522
7523/// A component that communicates over byte streams (stdin/stdout, sockets, pipes, etc.).
7524///
7525/// `ByteStreams` implements the [`ConnectTo`] trait for any pair of `AsyncRead` and `AsyncWrite`
7526/// streams, handling serialization of JSON-RPC messages to/from newline-delimited JSON.
7527/// This is the standard way to communicate with external processes or network connections.
7528///
7529/// Incoming bytes that are not valid UTF-8 are replaced with U+FFFD, so a line that contains
7530/// them is parsed like any other and does not end the connection.
7531///
7532/// # Use Cases
7533///
7534/// - **Stdio communication**: Connect to agents or proxies via stdin/stdout
7535/// - **Network sockets**: TCP, Unix domain sockets, or other stream-based protocols
7536/// - **Named pipes**: Cross-process communication on the same machine
7537/// - **File I/O**: Reading from and writing to file descriptors
7538///
7539/// # Example
7540///
7541/// Connecting to an agent via stdio:
7542///
7543/// ```no_run
7544/// use agent_client_protocol::UntypedRole;
7545/// # use agent_client_protocol::{ByteStreams};
7546/// use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
7547///
7548/// # async fn example() -> Result<(), agent_client_protocol::Error> {
7549/// let component = ByteStreams::new(
7550///     tokio::io::stdout().compat_write(),
7551///     tokio::io::stdin().compat(),
7552/// );
7553///
7554/// // Use as a component in a connection
7555/// agent_client_protocol::UntypedRole.builder()
7556///     .name("my-client")
7557///     .connect_to(component)
7558///     .await?;
7559/// # Ok(())
7560/// # }
7561/// ```
7562///
7563/// [`ConnectTo`]: crate::ConnectTo
7564#[derive(Debug)]
7565pub struct ByteStreams<OB, IB> {
7566    outgoing: OB,
7567    incoming: IB,
7568}
7569
7570impl<OB, IB> ByteStreams<OB, IB>
7571where
7572    OB: AsyncWrite + Send + 'static,
7573    IB: AsyncRead + Send + 'static,
7574{
7575    /// Create a new byte stream transport.
7576    pub fn new(outgoing: OB, incoming: IB) -> Self {
7577        Self { outgoing, incoming }
7578    }
7579
7580    fn into_lines(
7581        self,
7582    ) -> Lines<
7583        impl futures::Sink<String, Error = std::io::Error> + Send + 'static,
7584        impl futures::Stream<Item = std::io::Result<String>> + Send + 'static,
7585    > {
7586        let Self { outgoing, incoming } = self;
7587
7588        let incoming_lines = Box::pin(lossy_lines(incoming));
7589        let outgoing_lines = transport_actor::LineWriter::new(outgoing);
7590
7591        Lines::new(outgoing_lines, incoming_lines)
7592    }
7593}
7594
7595/// Splits `reader` into lines, without their `\n` or `\r\n` endings.
7596///
7597/// Bytes that are not valid UTF-8 are replaced with U+FFFD. Reporting them as
7598/// a read error would end the connection over one message. A line that is
7599/// JSON after the replacement is delivered, for example one with such a byte
7600/// inside a string. Any other line is a [`TransportFrame::Malformed`].
7601pub(crate) fn lossy_lines<R>(
7602    reader: R,
7603) -> impl futures::Stream<Item = std::io::Result<String>> + Send + 'static
7604where
7605    R: AsyncRead + Send + 'static,
7606{
7607    use futures::AsyncBufReadExt as _;
7608
7609    let reader = Box::pin(futures::io::BufReader::new(reader));
7610    futures::stream::try_unfold(reader, async |mut reader| {
7611        let mut line = Vec::new();
7612        if reader.read_until(b'\n', &mut line).await? == 0 {
7613            return Ok::<_, std::io::Error>(None);
7614        }
7615        if line.ends_with(b"\n") {
7616            line.pop();
7617            if line.ends_with(b"\r") {
7618                line.pop();
7619            }
7620        }
7621        let line = String::from_utf8(line).unwrap_or_else(|error| {
7622            // The line's content may be private, so it is not logged.
7623            tracing::debug!("Replaced invalid UTF-8 in an incoming line");
7624            String::from_utf8_lossy(error.as_bytes()).into_owned()
7625        });
7626        Ok(Some((line, reader)))
7627    })
7628}
7629
7630#[cfg(any(
7631    all(
7632        any(feature = "process", feature = "stdio"),
7633        not(target_family = "wasm")
7634    ),
7635    test
7636))]
7637pub(crate) async fn write_line<W>(writer: &mut W, line: String) -> std::io::Result<()>
7638where
7639    W: AsyncWrite + Unpin + ?Sized,
7640{
7641    use futures::AsyncWriteExt as _;
7642
7643    let mut bytes = line.into_bytes();
7644    bytes.push(b'\n');
7645    writer.write_all(&bytes).await?;
7646    writer.flush().await
7647}
7648
7649impl<OB, IB, R: Role> ConnectTo<R> for ByteStreams<OB, IB>
7650where
7651    OB: AsyncWrite + Send + 'static,
7652    IB: AsyncRead + Send + 'static,
7653{
7654    async fn connect_to(self, client: impl ConnectTo<R::Counterpart>) -> Result<(), crate::Error> {
7655        ConnectTo::<R>::connect_to(self.into_lines(), client).await
7656    }
7657
7658    fn into_channel_and_future(self) -> (Channel, Option<crate::ConnectionDriver>) {
7659        ConnectTo::<R>::into_channel_and_future(self.into_lines())
7660    }
7661}
7662
7663/// A channel endpoint representing one side of a bidirectional JSON-RPC transport.
7664///
7665/// A channel carries complete [`TransportFrame`] values across in-process components and
7666/// transport adapters. Malformed wire input is an
7667/// explicit frame; failures while driving a physical transport are returned by that
7668/// transport's future.
7669///
7670/// The unbounded [`futures::channel::mpsc`] pair is the intended contract:
7671/// frames are never dropped and sends never wait, so the transport or
7672/// component on each side applies its own backpressure. Build a channel from
7673/// an existing pair with [`Channel::new`] and take it apart with
7674/// [`Channel::into_parts`] or by destructuring with `..`.
7675///
7676/// # Example
7677///
7678/// ```no_run
7679/// # use agent_client_protocol::UntypedRole;
7680/// # use agent_client_protocol::Channel;
7681/// # async fn example() -> Result<(), agent_client_protocol::Error> {
7682/// let (channel_a, _channel_b) = Channel::duplex();
7683///
7684/// UntypedRole.builder()
7685///     .name("connection-a")
7686///     .connect_to(channel_a)
7687///     .await?;
7688/// # Ok(())
7689/// # }
7690/// ```
7691#[derive(Debug)]
7692#[non_exhaustive]
7693pub struct Channel {
7694    /// Receives frames from the counterpart.
7695    pub rx: mpsc::UnboundedReceiver<TransportFrame>,
7696    /// Sends frames to the counterpart.
7697    pub tx: mpsc::UnboundedSender<TransportFrame>,
7698}
7699
7700impl Channel {
7701    /// Create a channel endpoint that receives frames on `rx` and sends them
7702    /// on `tx`.
7703    #[must_use]
7704    pub fn new(
7705        rx: mpsc::UnboundedReceiver<TransportFrame>,
7706        tx: mpsc::UnboundedSender<TransportFrame>,
7707    ) -> Self {
7708        Self { rx, tx }
7709    }
7710
7711    /// Split this endpoint into its receiving and sending halves, `(rx, tx)`.
7712    #[must_use]
7713    pub fn into_parts(
7714        self,
7715    ) -> (
7716        mpsc::UnboundedReceiver<TransportFrame>,
7717        mpsc::UnboundedSender<TransportFrame>,
7718    ) {
7719        (self.rx, self.tx)
7720    }
7721
7722    /// Create a pair of connected channel endpoints.
7723    ///
7724    /// Frames sent through either endpoint are received by the other endpoint.
7725    #[must_use]
7726    pub fn duplex() -> (Self, Self) {
7727        let (a_tx, b_rx) = mpsc::unbounded();
7728        let (b_tx, a_rx) = mpsc::unbounded();
7729
7730        (Self { rx: a_rx, tx: a_tx }, Self { rx: b_rx, tx: b_tx })
7731    }
7732
7733    /// Copy frames from `rx` to `tx` until the input closes.
7734    ///
7735    /// # Errors
7736    ///
7737    /// Returns an error if the receiving endpoint closes before the input.
7738    pub(crate) async fn copy(mut self) -> Result<(), crate::Error> {
7739        while let Some(frame) = self.rx.next().await {
7740            self.tx
7741                .unbounded_send(frame)
7742                .map_err(crate::util::internal_error)?;
7743        }
7744        Ok(())
7745    }
7746
7747    /// Copy output concurrently with its owning driver, then drain accepted frames.
7748    /// Passive endpoints instead retain the channel's independent half-close lifetime.
7749    pub(crate) async fn copy_with_driver(
7750        self,
7751        driver: Option<crate::ConnectionDriver>,
7752    ) -> Result<(), crate::Error> {
7753        self.copy_with_driver_until(driver, future::pending()).await
7754    }
7755
7756    /// After the destination's owned foreground finishes, keep driving source
7757    /// errors and sink work, but never deliver queued or new input to it.
7758    pub(crate) async fn copy_with_driver_until(
7759        mut self,
7760        mut driver: Option<crate::ConnectionDriver>,
7761        stop_delivery: impl Future<Output = ()>,
7762    ) -> Result<(), crate::Error> {
7763        let mut stop_delivery = pin!(stop_delivery);
7764        let mut delivering = true;
7765        let mut done = false;
7766        loop {
7767            let event = future::poll_fn(|cx| {
7768                if delivering && stop_delivery.as_mut().poll(cx).is_ready() {
7769                    delivering = false;
7770                }
7771                // Driver errors remain authoritative even when stop or EOF is ready.
7772                if !done
7773                    && let Some(driver) = driver.as_mut()
7774                    && let std::task::Poll::Ready(result) = std::pin::Pin::new(driver).poll(cx)
7775                {
7776                    return std::task::Poll::Ready(Either::Left(result));
7777                }
7778                if !delivering && driver.is_none() {
7779                    return std::task::Poll::Ready(Either::Right(None));
7780                }
7781                self.rx.poll_next_unpin(cx).map(Either::Right)
7782            })
7783            .await;
7784            let frame = match event {
7785                Either::Left(result) => {
7786                    result?;
7787                    done = true;
7788                    self.rx.close();
7789                    continue;
7790                }
7791                Either::Right(frame) => frame,
7792            };
7793            let Some(frame) = frame else {
7794                break;
7795            };
7796            if delivering {
7797                self.tx
7798                    .unbounded_send(frame)
7799                    .map_err(crate::util::internal_error)?;
7800            }
7801        }
7802        // Propagate this half-close before waiting for a still-running driver.
7803        drop(self);
7804        if !done && let Some(driver) = driver {
7805            driver.await?;
7806        }
7807        Ok(())
7808    }
7809
7810    /// Bridge two endpoints while inspecting every valid message.
7811    ///
7812    /// Observers are invoked in source order for each valid message. The
7813    /// original frame is forwarded unchanged after inspection.
7814    ///
7815    /// # Errors
7816    ///
7817    /// Returns an observer error or an error if a destination closes before its
7818    /// source.
7819    pub async fn bridge_with_inspection(
7820        left: Self,
7821        right: Self,
7822        mut left_to_right: impl FnMut(&RawJsonRpcMessage) -> Result<(), crate::Error> + Send,
7823        mut right_to_left: impl FnMut(&RawJsonRpcMessage) -> Result<(), crate::Error> + Send,
7824    ) -> Result<(), crate::Error> {
7825        let Self {
7826            rx: mut left_rx,
7827            tx: left_tx,
7828        } = left;
7829        let Self {
7830            rx: mut right_rx,
7831            tx: right_tx,
7832        } = right;
7833
7834        let left_to_right = async move {
7835            while let Some(frame) = left_rx.next().await {
7836                frame.inspect_messages(&mut left_to_right)?;
7837                right_tx
7838                    .unbounded_send(frame)
7839                    .map_err(crate::util::internal_error)?;
7840            }
7841            Ok::<(), crate::Error>(())
7842        };
7843        let right_to_left = async move {
7844            while let Some(frame) = right_rx.next().await {
7845                frame.inspect_messages(&mut right_to_left)?;
7846                left_tx
7847                    .unbounded_send(frame)
7848                    .map_err(crate::util::internal_error)?;
7849            }
7850            Ok::<(), crate::Error>(())
7851        };
7852
7853        futures::try_join!(left_to_right, right_to_left)?;
7854        Ok(())
7855    }
7856}
7857
7858impl<R: Role> ConnectTo<R> for Channel {
7859    async fn connect_to(self, client: impl ConnectTo<R::Counterpart>) -> Result<(), crate::Error> {
7860        let (client_channel, client_future) = client.into_channel_and_future();
7861
7862        let passive = client_future.is_none();
7863        let outgoing = Box::pin(
7864            Channel {
7865                rx: client_channel.rx,
7866                tx: self.tx,
7867            }
7868            .copy_with_driver(client_future),
7869        );
7870        let incoming = Box::pin(
7871            Channel {
7872                rx: self.rx,
7873                tx: client_channel.tx,
7874            }
7875            .copy(),
7876        );
7877        if passive {
7878            futures::try_join!(outgoing, incoming)?;
7879            return Ok(());
7880        }
7881
7882        match future::select(outgoing, incoming).await {
7883            Either::Left((result, _)) => result,
7884            Either::Right((result, outgoing)) => {
7885                result?;
7886                outgoing.await
7887            }
7888        }
7889    }
7890
7891    fn into_channel_and_future(self) -> (Channel, Option<crate::ConnectionDriver>) {
7892        (self, None)
7893    }
7894}
7895
7896#[cfg(test)]
7897mod tests {
7898    use super::*;
7899    use crate::Client;
7900    #[cfg(feature = "unstable_protocol_v2")]
7901    use crate::Proxy;
7902
7903    #[test]
7904    fn raw_notification_round_trips_and_drops_unknown_envelope_members() {
7905        let message: RawJsonRpcMessage = serde_json::from_value(serde_json::json!({
7906            "jsonrpc": "2.0",
7907            "method": "_vendor/ping",
7908            "params": { "n": 1 },
7909            "extra": true,
7910        }))
7911        .unwrap();
7912        let mut params = serde_json::Map::new();
7913        params.insert("n".into(), 1.into());
7914        assert_eq!(
7915            message,
7916            RawJsonRpcMessage::Notification(RawJsonRpcNotification {
7917                method: "_vendor/ping".into(),
7918                params: Some(RawJsonRpcParams::Object(params)),
7919            })
7920        );
7921        assert_eq!(
7922            serde_json::to_value(&message).unwrap(),
7923            serde_json::json!({
7924                "jsonrpc": "2.0",
7925                "method": "_vendor/ping",
7926                "params": { "n": 1 },
7927            })
7928        );
7929
7930        let without_params =
7931            RawJsonRpcMessage::notification("ping".into(), serde_json::Value::Null).unwrap();
7932        assert_eq!(
7933            serde_json::to_value(&without_params).unwrap(),
7934            serde_json::json!({ "jsonrpc": "2.0", "method": "ping" })
7935        );
7936    }
7937
7938    #[test]
7939    fn protected_cleanup_keeps_scoped_runners_polled_on_every_shutdown_path() {
7940        #[derive(Clone, Copy, Debug)]
7941        enum Stop {
7942            ForegroundSuccess,
7943            ForegroundError,
7944            InputEof,
7945            TransportError,
7946            TaskError,
7947            RunnerError,
7948            SupervisorError,
7949        }
7950
7951        struct Dropped(Arc<AtomicBool>);
7952        impl Drop for Dropped {
7953            fn drop(&mut self) {
7954                self.0.store(true, Ordering::Release);
7955            }
7956        }
7957
7958        for stop in [
7959            Stop::ForegroundSuccess,
7960            Stop::ForegroundError,
7961            Stop::InputEof,
7962            Stop::TransportError,
7963            Stop::TaskError,
7964            Stop::RunnerError,
7965            Stop::SupervisorError,
7966        ] {
7967            let cleaned = Arc::new(AtomicBool::new(false));
7968            let disposable_dropped = Arc::new(AtomicBool::new(false));
7969            let close_finished = Arc::new(AtomicBool::new(false));
7970            let (cleanup_tx, cleanup_rx) = oneshot::channel::<()>();
7971            let (scoped_done_tx, scoped_done_rx) = completion_signal();
7972            let (stop_tx, stop_rx) = oneshot::channel::<()>();
7973            let stop_signal = stop_rx.map(|_| ()).boxed().shared();
7974            let (incoming_tx, incoming_rx) = mpsc::unbounded();
7975            let outgoing = futures::sink::unfold((), |(), _line: String| {
7976                future::ready(Ok::<_, std::io::Error>(()))
7977            });
7978            let builder = Client
7979                .v1()
7980                .with_spawned({
7981                    let cleaned = cleaned.clone();
7982                    async move |cx: crate::v1::ConnectionTo<Agent>| {
7983                        cx.raw_connection().shutdown_requested().await;
7984                        // This stands in for the actual scoped native operation:
7985                        // its async cleanup only advances if this runner is polled.
7986                        cleanup_rx.await.unwrap();
7987                        cleaned.store(true, Ordering::Release);
7988                        let _ = scoped_done_tx.send(());
7989                        Ok(())
7990                    }
7991                })
7992                .with_spawned({
7993                    let stop_signal = stop_signal.clone();
7994                    async move |_cx| {
7995                        stop_signal.await;
7996                        if matches!(stop, Stop::RunnerError) {
7997                            Err(crate::Error::internal_error().data("runner failure"))
7998                        } else {
7999                            future::pending().await
8000                        }
8001                    }
8002                })
8003                .on_close({
8004                    let close_finished = close_finished.clone();
8005                    let scoped_done = scoped_done_rx.clone();
8006                    async move |cx: crate::v1::ConnectionTo<Agent>| {
8007                        // EOF cancellation must precede, not await, close callbacks.
8008                        cx.raw_connection().shutdown_requested().await;
8009                        assert!(!cx.is_incoming_closed());
8010                        scoped_done.await;
8011                        close_finished.store(true, Ordering::Release);
8012                        Ok(())
8013                    }
8014                });
8015            let (connection, driver) =
8016                builder.into_connection_and_future(Lines::new(outgoing, incoming_rx), false, {
8017                    let stop_signal = stop_signal.clone();
8018                    async move |cx| {
8019                        if matches!(stop, Stop::InputEof) {
8020                            cx.incoming_closed().await;
8021                            return Ok(());
8022                        }
8023                        stop_signal.await;
8024                        match stop {
8025                            Stop::ForegroundSuccess | Stop::SupervisorError => Ok(()),
8026                            Stop::ForegroundError => {
8027                                Err(crate::Error::internal_error().data("foreground failure"))
8028                            }
8029                            _ => future::pending().await,
8030                        }
8031                    }
8032                });
8033            let disposable = Dropped(disposable_dropped.clone());
8034            connection
8035                .spawn(async move {
8036                    let _disposable = disposable;
8037                    future::pending().await
8038                })
8039                .unwrap();
8040            connection
8041                .spawn({
8042                    let stop_signal = stop_signal.clone();
8043                    async move {
8044                        stop_signal.await;
8045                        if matches!(stop, Stop::TaskError) {
8046                            Err(crate::Error::internal_error().data("task failure"))
8047                        } else {
8048                            future::pending().await
8049                        }
8050                    }
8051                })
8052                .unwrap();
8053            connection
8054                .spawn_protected({
8055                    let connection = connection.clone();
8056                    async move {
8057                        connection.shutdown_requested().await;
8058                        scoped_done_rx.await;
8059                        if matches!(stop, Stop::SupervisorError) {
8060                            Err(crate::Error::internal_error().data("supervisor failure"))
8061                        } else {
8062                            Ok(())
8063                        }
8064                    }
8065                })
8066                .unwrap();
8067            let mut driver = Box::pin(driver);
8068            assert!(driver.as_mut().now_or_never().is_none(), "{stop:?}");
8069            assert!(connection.shutdown_requested().now_or_never().is_none());
8070            let _ = stop_tx.send(());
8071            let incoming_tx = match stop {
8072                Stop::InputEof => {
8073                    drop(incoming_tx);
8074                    None
8075                }
8076                Stop::TransportError => {
8077                    incoming_tx
8078                        .unbounded_send(Err(std::io::Error::other("transport failure")))
8079                        .unwrap();
8080                    Some(incoming_tx)
8081                }
8082                _ => Some(incoming_tx),
8083            };
8084            for _ in 0..10 {
8085                assert!(driver.as_mut().now_or_never().is_none(), "{stop:?}");
8086                if connection.shutdown_requested().now_or_never().is_some() {
8087                    break;
8088                }
8089            }
8090            assert!(
8091                connection.shutdown_requested().now_or_never().is_some(),
8092                "{stop:?}"
8093            );
8094            assert!(!cleaned.load(Ordering::Acquire), "{stop:?}");
8095            assert!(!disposable_dropped.load(Ordering::Acquire), "{stop:?}");
8096            cleanup_tx.send(()).unwrap();
8097            // Task acknowledgments may wake an actor already polled in this turn.
8098            // Bound the probe so a broken scoped-runner join fails, not hangs.
8099            let mut result = None;
8100            for _ in 0..10 {
8101                result = driver.as_mut().now_or_never();
8102                if result.is_some() {
8103                    break;
8104                }
8105            }
8106            let result =
8107                result.unwrap_or_else(|| panic!("driver did not finish owned cleanup: {stop:?}"));
8108            match stop {
8109                Stop::ForegroundSuccess | Stop::InputEof => result.unwrap(),
8110                _ => {
8111                    let error = result.expect_err("shutdown must preserve the first error");
8112                    let expected = match stop {
8113                        Stop::ForegroundError => "foreground failure",
8114                        Stop::TransportError => "transport failure",
8115                        Stop::TaskError => "task failure",
8116                        Stop::RunnerError => "runner failure",
8117                        Stop::SupervisorError => "supervisor failure",
8118                        _ => unreachable!(),
8119                    };
8120                    assert!(
8121                        error.data.unwrap().to_string().contains(expected),
8122                        "{stop:?}"
8123                    );
8124                }
8125            }
8126            assert!(cleaned.load(Ordering::Acquire), "{stop:?}");
8127            assert!(disposable_dropped.load(Ordering::Acquire), "{stop:?}");
8128            assert_eq!(
8129                close_finished.load(Ordering::Acquire),
8130                matches!(stop, Stop::InputEof),
8131                "{stop:?}",
8132            );
8133            assert!(connection.spawn_protected(async { Ok(()) }).is_err());
8134            drop(incoming_tx);
8135        }
8136    }
8137
8138    #[test]
8139    fn protected_operation_acknowledgments_are_reaped_and_join_seals_registration() {
8140        let (connection, _message_rx, _pending_replies) = connection_for_response_hook_tests();
8141        // The helper drops its task receiver, so use a live receiver for this probe.
8142        let (task_tx, mut task_rx) = mpsc::unbounded();
8143        let connection = ConnectionTo {
8144            task_tx,
8145            ..connection
8146        };
8147        for _ in 0..100 {
8148            connection.spawn_protected(async { Ok(()) }).unwrap();
8149            assert_eq!(
8150                connection
8151                    .protected_operations
8152                    .lock()
8153                    .unwrap()
8154                    .pending
8155                    .len(),
8156                1
8157            );
8158            let task = task_rx.next().now_or_never().unwrap().unwrap();
8159            futures::executor::block_on(task.run_for_test()).unwrap();
8160        }
8161        assert!(
8162            connection
8163                .wait_protected_operations()
8164                .now_or_never()
8165                .is_some()
8166        );
8167        assert!(
8168            connection
8169                .wait_protected_operations()
8170                .now_or_never()
8171                .is_some()
8172        );
8173        assert!(
8174            connection
8175                .protected_operations
8176                .lock()
8177                .unwrap()
8178                .pending
8179                .is_empty()
8180        );
8181        assert!(connection.spawn_protected(async { Ok(()) }).is_err());
8182        assert!(task_rx.next().now_or_never().is_none());
8183    }
8184
8185    #[test]
8186    fn dropping_unused_finish_signal_preserves_physical_half_closes() {
8187        let outgoing = futures::sink::unfold((), |(), _line: String| {
8188            future::ready(Ok::<_, std::io::Error>(()))
8189        });
8190        let (incoming_tx, incoming_rx) = mpsc::unbounded();
8191        let (Channel { mut rx, tx }, mut driver) =
8192            Lines::new(outgoing, incoming_rx).into_channel_transport();
8193
8194        drop(
8195            driver
8196                .take_finish()
8197                .expect("built-in Lines driver is finishable"),
8198        );
8199        drop(tx);
8200        assert!((&mut driver).now_or_never().is_none());
8201        incoming_tx
8202            .unbounded_send(Ok(
8203                r#"{"jsonrpc":"2.0","method":"test/after-output-eof"}"#.into()
8204            ))
8205            .unwrap();
8206        assert!((&mut driver).now_or_never().is_none());
8207        assert!(rx.next().now_or_never().unwrap().is_some());
8208
8209        drop(incoming_tx);
8210        futures::executor::block_on(driver).unwrap();
8211        assert!(rx.next().now_or_never().unwrap().is_none());
8212    }
8213
8214    #[test]
8215    fn explicit_physical_finish_does_not_hide_a_ready_read_error() {
8216        let outgoing = futures::sink::unfold((), |(), _line: String| {
8217            future::ready(Ok::<_, std::io::Error>(()))
8218        });
8219        let incoming = futures::stream::iter([Err(std::io::Error::other("finish read failed"))]);
8220        let (_channel, mut driver) = Lines::new(outgoing, incoming).into_channel_transport();
8221        assert!(driver.request_finish());
8222
8223        let error = futures::executor::block_on(driver).unwrap_err();
8224        assert_eq!(
8225            error
8226                .data
8227                .and_then(|value| value.as_str().map(str::to_owned)),
8228            Some("finish read failed".into())
8229        );
8230    }
8231
8232    #[cfg(feature = "unstable_protocol_v2")]
8233    fn connection_with_task_receiver() -> (
8234        ConnectionTo<crate::role::UntypedRole>,
8235        mpsc::UnboundedReceiver<Task>,
8236    ) {
8237        let (message_tx, _message_rx) = mpsc::unbounded();
8238        let (task_tx, task_rx) = mpsc::unbounded();
8239        let (dynamic_handler_tx, _dynamic_handler_rx) = mpsc::unbounded();
8240        let transport_completion: SharedTransportCompletion =
8241            future::ready(Ok::<(), crate::Error>(())).boxed().shared();
8242        let pending_replies = PendingReplies::default();
8243
8244        (
8245            ConnectionTo::new(
8246                crate::role::UntypedRole,
8247                message_tx,
8248                task_tx,
8249                dynamic_handler_tx,
8250                transport_completion,
8251                pending_replies.registrar(),
8252                ProtocolMode::disabled(),
8253            ),
8254            task_rx,
8255        )
8256    }
8257
8258    #[cfg(feature = "unstable_protocol_v2")]
8259    #[test]
8260    fn v2_builder_exposes_typed_context_to_user_callbacks() {
8261        fn assert_v2_context(_connection: &crate::v2::ConnectionTo<Agent>) {}
8262
8263        let _builder = Client
8264            .v2()
8265            .on_receive_request(
8266                async |_request: UntypedMessage, _responder, connection| {
8267                    assert_v2_context(&connection);
8268                    Ok(())
8269                },
8270                crate::on_receive_request!(),
8271            )
8272            .on_receive_notification(
8273                async |_notification: UntypedMessage, connection| {
8274                    assert_v2_context(&connection);
8275                    Ok(())
8276                },
8277                crate::on_receive_notification!(),
8278            )
8279            .on_receive_dispatch(
8280                async |_dispatch: Dispatch<UntypedMessage, UntypedMessage, V2>, connection| {
8281                    assert_v2_context(&connection);
8282                    Ok(())
8283                },
8284                crate::on_receive_dispatch!(),
8285            )
8286            .on_receive_request_from(
8287                Agent,
8288                async |_request: UntypedMessage, _responder, connection| {
8289                    assert_v2_context(&connection);
8290                    Ok(())
8291                },
8292                crate::on_receive_request!(),
8293            )
8294            .on_receive_notification_from(
8295                Agent,
8296                async |_notification: UntypedMessage, connection| {
8297                    assert_v2_context(&connection);
8298                    Ok(())
8299                },
8300                crate::on_receive_notification!(),
8301            )
8302            .on_receive_dispatch_from(
8303                Agent,
8304                async |_dispatch: Dispatch<UntypedMessage, UntypedMessage, V2>, connection| {
8305                    assert_v2_context(&connection);
8306                    Ok(())
8307                },
8308                crate::on_receive_dispatch!(),
8309            )
8310            .with_spawned(async |connection| {
8311                assert_v2_context(&connection);
8312                Ok(())
8313            })
8314            .on_close(async |connection| {
8315                assert_v2_context(&connection);
8316                Ok(())
8317            });
8318    }
8319
8320    #[cfg(feature = "unstable_protocol_v2")]
8321    #[test]
8322    fn proxy_builders_negotiate_proxy_initialize_like_agents() -> Result<(), crate::Error> {
8323        use crate::schema::ProtocolVersion;
8324
8325        // A v1 proxy selects v1 for a newer request.
8326        let mode = Proxy.v1().protocol_mode;
8327        assert_eq!(mode.api_protocol_version(), Some(ProtocolVersion::V1));
8328        let request = ProtocolCompat::new(mode).incoming_message(UntypedMessage::new(
8329            "proxy/initialize",
8330            serde_json::json!({ "protocolVersion": ProtocolVersion::V2 }),
8331        )?)?;
8332        assert_eq!(request.params()["protocolVersion"], serde_json::json!(1));
8333
8334        // A v2 proxy supports no version at or below v1.
8335        let mode = Proxy.v2().protocol_mode;
8336        assert_eq!(mode.api_protocol_version(), Some(ProtocolVersion::V2));
8337        let error = ProtocolCompat::new(mode)
8338            .incoming_message(UntypedMessage::new(
8339                "proxy/initialize",
8340                serde_json::json!({ "protocolVersion": ProtocolVersion::V1 }),
8341            )?)
8342            .expect_err("a v2 proxy builder must reject v1");
8343        assert_eq!(i32::from(error.code), -32022);
8344
8345        Ok(())
8346    }
8347
8348    #[cfg(feature = "unstable_protocol_v2")]
8349    #[test]
8350    fn v2_proxy_rejects_explicitly_prewrapped_initialize_request() {
8351        let (message_tx, message_rx) = mpsc::unbounded();
8352        let (task_tx, _task_rx) = mpsc::unbounded();
8353        let (dynamic_handler_tx, _dynamic_handler_rx) = mpsc::unbounded();
8354        let transport_completion: SharedTransportCompletion =
8355            future::ready(Ok::<(), crate::Error>(())).boxed().shared();
8356        let pending_replies = PendingReplies::default();
8357        let connection = ConnectionTo::new(
8358            crate::Conductor,
8359            message_tx,
8360            task_tx,
8361            dynamic_handler_tx,
8362            transport_completion,
8363            pending_replies.registrar(),
8364            ProtocolMode::v2_proxy(),
8365        );
8366
8367        let request = crate::schema::SuccessorMessage::new(
8368            UntypedMessage::new(
8369                "initialize",
8370                serde_json::json!({ "protocolVersion": crate::schema::ProtocolVersion::V1 }),
8371            )
8372            .expect("test initialize request should serialize"),
8373        );
8374        let sent = connection.send_request_to(Agent, request);
8375
8376        let (transport_tx, mut transport_rx) = mpsc::unbounded();
8377        let mut actor = Box::pin(outgoing_actor::outgoing_protocol_actor(
8378            message_rx,
8379            pending_replies,
8380            transport_tx,
8381            ProtocolCompat::new(ProtocolMode::v2_proxy()),
8382            future::pending::<()>().boxed().shared(),
8383        ));
8384        assert!(
8385            actor.as_mut().now_or_never().is_none(),
8386            "the outgoing actor should continue after rejecting the request"
8387        );
8388        assert!(
8389            transport_rx.next().now_or_never().is_none(),
8390            "an explicitly prewrapped initialize must not reach the transport"
8391        );
8392
8393        let error = futures::executor::block_on(sent.block_task())
8394            .expect_err("connection routing must own successor wrapping");
8395        let data = error
8396            .data
8397            .as_ref()
8398            .and_then(|data| data.as_str())
8399            .unwrap_or_default();
8400        assert!(data.contains("logical `initialize`"), "{error:?}");
8401        assert!(data.contains("proxy/successor"), "{error:?}");
8402    }
8403
8404    #[cfg(feature = "unstable_protocol_v2")]
8405    #[test]
8406    fn v2_proxy_builder_exposes_typed_context_to_user_callbacks() {
8407        fn assert_v2_context(_connection: &crate::v2::ConnectionTo<crate::Conductor>) {}
8408
8409        let _builder = Proxy
8410            .v2()
8411            .on_receive_request_from(
8412                Client,
8413                async |_request: UntypedMessage, _responder, connection| {
8414                    assert_v2_context(&connection);
8415                    Ok(())
8416                },
8417                crate::on_receive_request!(),
8418            )
8419            .on_receive_notification_from(
8420                Agent,
8421                async |_notification: UntypedMessage, connection| {
8422                    assert_v2_context(&connection);
8423                    Ok(())
8424                },
8425                crate::on_receive_notification!(),
8426            )
8427            .on_receive_dispatch_from(
8428                Client,
8429                async |_dispatch: Dispatch<UntypedMessage, UntypedMessage, V2>, connection| {
8430                    assert_v2_context(&connection);
8431                    Ok(())
8432                },
8433                crate::on_receive_dispatch!(),
8434            )
8435            .with_spawned(async |connection| {
8436                assert_v2_context(&connection);
8437                Ok(())
8438            })
8439            .on_close(async |connection| {
8440                assert_v2_context(&connection);
8441                Ok(())
8442            });
8443    }
8444
8445    #[cfg(feature = "unstable_protocol_v2")]
8446    #[test]
8447    fn raw_connection_spawns_v2_builder_with_typed_child_callback() {
8448        let (parent, mut task_rx) = connection_with_task_receiver();
8449        let (transport, _peer) = Channel::duplex();
8450        let (callback_tx, callback_rx) = oneshot::channel();
8451
8452        let child: crate::v2::ConnectionTo<Agent> = parent
8453            .spawn_connection(
8454                Client.v2().with_spawned(
8455                    async move |_connection: crate::v2::ConnectionTo<Agent>| {
8456                        callback_tx.send(()).map_err(|()| {
8457                            crate::util::internal_error("typed child callback receiver was dropped")
8458                        })
8459                    },
8460                ),
8461                transport,
8462            )
8463            .expect("v2 child connection should be spawned");
8464
8465        let task = futures::FutureExt::now_or_never(futures::StreamExt::next(&mut task_rx))
8466            .expect("child connection task should already be queued")
8467            .expect("parent task queue should remain open");
8468        futures::executor::block_on(async {
8469            match future::select(Box::pin(task.run_for_test()), Box::pin(callback_rx)).await {
8470                Either::Right((Ok(()), child_task)) => drop(child_task),
8471                Either::Right((Err(error), _)) => {
8472                    panic!("typed child callback sender was dropped: {error}")
8473                }
8474                Either::Left((result, _)) => {
8475                    panic!("child connection stopped before its typed callback ran: {result:?}")
8476                }
8477            }
8478        });
8479
8480        drop(child);
8481    }
8482
8483    #[cfg(feature = "unstable_protocol_v2")]
8484    #[test]
8485    fn raw_connection_returns_raw_context_for_raw_builder() {
8486        let (parent, mut task_rx) = connection_with_task_receiver();
8487        let (transport, _peer) = Channel::duplex();
8488
8489        let child: ConnectionTo<Agent> = parent
8490            .spawn_connection(Builder::new(Client), transport)
8491            .expect("raw child connection should be spawned");
8492        assert_eq!(child.protocol_version(), None);
8493
8494        let child_task = futures::FutureExt::now_or_never(futures::StreamExt::next(&mut task_rx))
8495            .expect("child connection task should already be queued")
8496            .expect("parent task queue should remain open");
8497
8498        drop((child, child_task));
8499    }
8500
8501    fn connection_with_dynamic_handler_receiver() -> (
8502        ConnectionTo<crate::role::UntypedRole>,
8503        mpsc::UnboundedReceiver<DynamicHandlerMessage<crate::role::UntypedRole>>,
8504    ) {
8505        let (message_tx, _message_rx) = mpsc::unbounded();
8506        let (task_tx, _task_rx) = mpsc::unbounded();
8507        let (dynamic_handler_tx, dynamic_handler_rx) = mpsc::unbounded();
8508        let transport_completion: SharedTransportCompletion =
8509            future::ready(Ok::<(), crate::Error>(())).boxed().shared();
8510        let pending_replies = PendingReplies::default();
8511
8512        (
8513            ConnectionTo::new(
8514                crate::role::UntypedRole,
8515                message_tx,
8516                task_tx,
8517                dynamic_handler_tx,
8518                transport_completion,
8519                pending_replies.registrar(),
8520                ProtocolMode::disabled(),
8521            ),
8522            dynamic_handler_rx,
8523        )
8524    }
8525
8526    struct ClaimingDynamicHandler;
8527
8528    impl HandleDispatchFrom<crate::role::UntypedRole> for ClaimingDynamicHandler {
8529        fn handle_dispatch_from(
8530            &mut self,
8531            _message: Dispatch,
8532            _connection: ConnectionTo<crate::role::UntypedRole>,
8533        ) -> impl Future<Output = Result<Handled<Dispatch>, crate::Error>> + Send {
8534            future::ready(Ok(Handled::Yes))
8535        }
8536
8537        fn describe_chain(&self) -> impl Debug {
8538            "ClaimingDynamicHandler"
8539        }
8540    }
8541
8542    fn connection_for_response_hook_tests() -> (
8543        ConnectionTo<crate::role::UntypedRole>,
8544        mpsc::UnboundedReceiver<OutgoingMessage>,
8545        PendingReplies,
8546    ) {
8547        let (message_tx, message_rx) = mpsc::unbounded();
8548        let (task_tx, _task_rx) = mpsc::unbounded();
8549        let (dynamic_handler_tx, _dynamic_handler_rx) = mpsc::unbounded();
8550        let transport_completion: SharedTransportCompletion =
8551            future::ready(Ok::<(), crate::Error>(())).boxed().shared();
8552        let pending_replies = PendingReplies::default();
8553
8554        (
8555            ConnectionTo::new(
8556                crate::role::UntypedRole,
8557                message_tx,
8558                task_tx,
8559                dynamic_handler_tx,
8560                transport_completion,
8561                pending_replies.registrar(),
8562                ProtocolMode::disabled(),
8563            ),
8564            message_rx,
8565            pending_replies,
8566        )
8567    }
8568
8569    #[cfg(feature = "unstable_protocol_v2")]
8570    fn route_test_response(
8571        request_id: RawJsonRpcId,
8572        pending_replies: &PendingReplies,
8573        result: Result<serde_json::Value, crate::Error>,
8574    ) {
8575        let pending_reply = pending_replies
8576            .remove(&request_id)
8577            .expect("the request should have a pending reply");
8578        let (dispatch, _) = incoming_actor::dispatch_from_response(pending_reply, result);
8579        let Dispatch::Response(result, router) = dispatch else {
8580            panic!("expected a response dispatch");
8581        };
8582        router
8583            .route_with_result(result)
8584            .expect("response should route to the pending request");
8585    }
8586
8587    #[cfg(feature = "unstable_protocol_v2")]
8588    #[test]
8589    fn handle_ids_are_typed_by_protocol_and_match_the_wire_id() {
8590        let (connection, _message_rx, pending_replies) = connection_for_response_hook_tests();
8591        let raw_sent = connection.send_request_to(
8592            crate::role::UntypedRole,
8593            UntypedMessage::new("probe", serde_json::json!({}))
8594                .expect("test request should serialize"),
8595        );
8596        let raw_sent_id: &RawJsonRpcId = raw_sent.id();
8597        assert_eq!(raw_sent_id, raw_sent.raw_id());
8598        raw_sent.detach();
8599
8600        let v2_connection = crate::v2::ConnectionTo { inner: connection };
8601        let sent = v2_connection.send_request_to(
8602            crate::role::UntypedRole,
8603            UntypedMessage::new("probe", serde_json::json!({}))
8604                .expect("test request should serialize"),
8605        );
8606        let v2_id: crate::v2::schema::RequestId = sent.id().clone();
8607        let raw_id = sent.raw_id().clone();
8608        assert_eq!(
8609            serde_json::to_value(&v2_id).expect("v2 id should serialize"),
8610            serde_json::to_value(&raw_id).expect("raw id should serialize"),
8611        );
8612
8613        let pending_reply = pending_replies
8614            .remove(&raw_id)
8615            .expect("the request should have a pending reply");
8616        let (dispatch, _) =
8617            incoming_actor::dispatch_from_response(pending_reply, Ok(serde_json::json!({})));
8618        assert_eq!(dispatch.raw_id(), Some(&raw_id));
8619        let dispatch = dispatch
8620            .into_protocol::<V2>()
8621            .expect("SDK-assigned ids are valid v2 ids");
8622        assert_eq!(dispatch.id(), Some(&v2_id));
8623        let Dispatch::Response(_, router) = dispatch else {
8624            panic!("expected a response dispatch");
8625        };
8626        assert_eq!(router.id(), &v2_id);
8627        assert_eq!(router.raw_id(), &raw_id);
8628        sent.detach();
8629    }
8630
8631    #[cfg(feature = "unstable_protocol_v2")]
8632    #[test]
8633    fn response_hook_runs_when_success_is_routed_before_consumption() {
8634        let (connection, _message_rx, pending_replies) = connection_for_response_hook_tests();
8635        let hook_ran = Arc::new(AtomicBool::new(false));
8636        let sent = connection
8637            .prepare_request_to_with_response_hook_after::<Raw, _, _, _>(
8638                crate::role::UntypedRole,
8639                UntypedMessage::new("hooked", serde_json::json!({}))
8640                    .expect("test request should serialize"),
8641                future::ready(Ok(())),
8642                {
8643                    let hook_ran = hook_ran.clone();
8644                    move |response| {
8645                        assert_eq!(response, &serde_json::json!({"ok": true}));
8646                        hook_ran.store(true, Ordering::Release);
8647                        Ok(())
8648                    }
8649                },
8650            )
8651            .into_sent_request(false);
8652        let request_id = sent.raw_id().clone();
8653
8654        route_test_response(
8655            request_id,
8656            &pending_replies,
8657            Ok(serde_json::json!({"ok": true})),
8658        );
8659
8660        assert!(hook_ran.load(Ordering::Acquire));
8661        assert_eq!(
8662            futures::executor::block_on(sent.block_task())
8663                .expect("routed response should remain consumable"),
8664            serde_json::json!({"ok": true})
8665        );
8666    }
8667
8668    #[cfg(feature = "unstable_protocol_v2")]
8669    #[test]
8670    fn response_hook_skips_errors_but_outlives_a_dropped_consumer() {
8671        let (connection, _message_rx, pending_replies) = connection_for_response_hook_tests();
8672        let peer_error_hook_ran = Arc::new(AtomicBool::new(false));
8673        let peer_error = connection
8674            .prepare_request_to_with_response_hook_after::<Raw, _, _, _>(
8675                crate::role::UntypedRole,
8676                UntypedMessage::new("peer-error", serde_json::json!({}))
8677                    .expect("test request should serialize"),
8678                future::ready(Ok(())),
8679                {
8680                    let hook_ran = peer_error_hook_ran.clone();
8681                    move |_| {
8682                        hook_ran.store(true, Ordering::Release);
8683                        Ok(())
8684                    }
8685                },
8686            )
8687            .into_sent_request(false);
8688        let peer_error_id = peer_error.raw_id().clone();
8689        route_test_response(
8690            peer_error_id,
8691            &pending_replies,
8692            Err(crate::Error::invalid_request()),
8693        );
8694        assert!(
8695            futures::executor::block_on(peer_error.block_task()).is_err(),
8696            "the peer error should reach the consumer"
8697        );
8698        assert!(!peer_error_hook_ran.load(Ordering::Acquire));
8699
8700        let dropped_hook_ran = Arc::new(AtomicBool::new(false));
8701        let dropped = connection
8702            .prepare_request_to_with_response_hook_after::<Raw, _, _, _>(
8703                crate::role::UntypedRole,
8704                UntypedMessage::new("dropped", serde_json::json!({}))
8705                    .expect("test request should serialize"),
8706                future::ready(Ok(())),
8707                {
8708                    let hook_ran = dropped_hook_ran.clone();
8709                    move |_| {
8710                        hook_ran.store(true, Ordering::Release);
8711                        Ok(())
8712                    }
8713                },
8714            )
8715            .into_sent_request(false);
8716        let dropped_id = dropped.raw_id().clone();
8717        drop(dropped);
8718        route_test_response(
8719            dropped_id,
8720            &pending_replies,
8721            Ok(serde_json::json!({"ok": true})),
8722        );
8723        assert!(dropped_hook_ran.load(Ordering::Acquire));
8724    }
8725
8726    #[cfg(feature = "unstable_protocol_v2")]
8727    #[test]
8728    fn response_hook_failure_replaces_the_success_result() {
8729        let (connection, _message_rx, pending_replies) = connection_for_response_hook_tests();
8730        let sent = connection
8731            .prepare_request_to_with_response_hook_after::<Raw, _, _, _>(
8732                crate::role::UntypedRole,
8733                UntypedMessage::new("hook-failure", serde_json::json!({}))
8734                    .expect("test request should serialize"),
8735                future::ready(Ok(())),
8736                |_| Err(crate::Error::internal_error().data("response hook failed")),
8737            )
8738            .into_sent_request(false);
8739        let request_id = sent.raw_id().clone();
8740        route_test_response(
8741            request_id,
8742            &pending_replies,
8743            Ok(serde_json::json!({"ok": true})),
8744        );
8745
8746        let error = futures::executor::block_on(sent.block_task())
8747            .expect_err("the hook failure should replace the successful response");
8748        assert_eq!(error.code, crate::ErrorCode::INTERNAL_ERROR);
8749        assert_eq!(error.data, Some(serde_json::json!("response hook failed")));
8750    }
8751
8752    #[test]
8753    fn ordered_request_waits_for_readiness_before_publication() {
8754        let (connection, message_rx, pending_replies) = connection_for_response_hook_tests();
8755        let (ready_tx, ready_rx) = oneshot::channel();
8756        let sent = connection.send_ordered_request_to_after::<Raw, _, _, _>(
8757            crate::role::UntypedRole,
8758            UntypedMessage::new("after-ready", serde_json::json!({}))
8759                .expect("test request should serialize"),
8760            async move { ready_rx.await.map_err(crate::Error::into_internal_error) },
8761        );
8762
8763        let (transport_tx, mut transport_rx) = mpsc::unbounded();
8764        let mut actor = Box::pin(outgoing_actor::outgoing_protocol_actor(
8765            message_rx,
8766            pending_replies,
8767            transport_tx,
8768            ProtocolCompat::new(ProtocolMode::disabled()),
8769            future::pending::<()>().boxed().shared(),
8770        ));
8771
8772        assert!(
8773            actor.as_mut().now_or_never().is_none(),
8774            "the outgoing actor should wait for readiness"
8775        );
8776        assert!(
8777            transport_rx.next().now_or_never().is_none(),
8778            "the request must not be published before readiness"
8779        );
8780
8781        ready_tx
8782            .send(())
8783            .expect("the readiness receiver should remain active");
8784        assert!(
8785            actor.as_mut().now_or_never().is_none(),
8786            "the outgoing actor should continue serving after publication"
8787        );
8788        let frame = transport_rx
8789            .next()
8790            .now_or_never()
8791            .expect("the ready request should be published")
8792            .expect("the transport queue should remain open");
8793        assert!(matches!(
8794            frame,
8795            TransportFrame::Single(RawJsonRpcMessage::Request(_))
8796        ));
8797
8798        drop(sent);
8799    }
8800
8801    #[test]
8802    fn foreground_finish_settles_unready_requests_and_preserves_ready_output_fifo() {
8803        let (connection, message_rx, pending_replies) = connection_for_response_hook_tests();
8804        let unready = connection.send_ordered_request_to_after::<Raw, _, _, _>(
8805            crate::role::UntypedRole,
8806            UntypedMessage::new("unready", serde_json::json!({})).unwrap(),
8807            future::pending(),
8808        );
8809        let unready_id = unready.raw_id().clone();
8810        send_raw_message(
8811            &connection.message_tx,
8812            OutgoingMessage::Notification {
8813                untyped: UntypedMessage::new("first", serde_json::json!({})).unwrap(),
8814            },
8815        )
8816        .unwrap();
8817        let ready = connection.send_ordered_request_to_after::<Raw, _, _, _>(
8818            crate::role::UntypedRole,
8819            UntypedMessage::new("ready", serde_json::json!({})).unwrap(),
8820            future::ready(Ok(())),
8821        );
8822        let unready_after = connection.send_ordered_request_to_after::<Raw, _, _, _>(
8823            crate::role::UntypedRole,
8824            UntypedMessage::new("unready-after", serde_json::json!({})).unwrap(),
8825            future::pending(),
8826        );
8827        let unready_after_id = unready_after.raw_id().clone();
8828        send_raw_message(
8829            &connection.message_tx,
8830            OutgoingMessage::Notification {
8831                untyped: UntypedMessage::new("last", serde_json::json!({})).unwrap(),
8832            },
8833        )
8834        .unwrap();
8835        let (done_tx, done_rx) = oneshot::channel();
8836        send_raw_message(
8837            &connection.message_tx,
8838            OutgoingMessage::CloseAfterDraining { done: done_tx },
8839        )
8840        .unwrap();
8841        let (transport_tx, transport_rx) = mpsc::unbounded();
8842        futures::executor::block_on(outgoing_actor::outgoing_protocol_actor(
8843            message_rx,
8844            pending_replies.clone(),
8845            transport_tx,
8846            ProtocolCompat::new(ProtocolMode::disabled()),
8847            future::ready(()).boxed().shared(),
8848        ))
8849        .unwrap();
8850        futures::executor::block_on(done_rx).unwrap();
8851        let error = futures::executor::block_on(unready.block_task())
8852            .expect_err("an unresolved gate must explicitly fail its consumer");
8853        assert!(
8854            error
8855                .data
8856                .unwrap()
8857                .to_string()
8858                .contains("foreground completed before outgoing request readiness")
8859        );
8860        assert!(!pending_replies.contains(&unready_id));
8861        let error = futures::executor::block_on(unready_after.block_task())
8862            .expect_err("each unresolved gate must fail without repolling a consumed signal");
8863        assert!(
8864            error
8865                .data
8866                .unwrap()
8867                .to_string()
8868                .contains("foreground completed before outgoing request readiness")
8869        );
8870        assert!(!pending_replies.contains(&unready_after_id));
8871        assert!(pending_replies.contains(ready.raw_id()));
8872        let frames = futures::executor::block_on(transport_rx.collect::<Vec<_>>());
8873        let methods = frames
8874            .into_iter()
8875            .map(|frame| match frame {
8876                TransportFrame::Single(RawJsonRpcMessage::Notification(message)) => {
8877                    message.method.to_string()
8878                }
8879                TransportFrame::Single(RawJsonRpcMessage::Request(message)) => {
8880                    message.method.to_string()
8881                }
8882                _ => panic!("expected ready request/notification output"),
8883            })
8884            .collect::<Vec<_>>();
8885        assert_eq!(methods, ["first", "ready", "last"]);
8886    }
8887
8888    #[test]
8889    fn ordered_blocking_transform_precedes_response_acknowledgment() {
8890        let (connection, _message_rx, pending_replies) = connection_for_response_hook_tests();
8891        let sent = connection.send_ordered_request_to::<Raw, _, _>(
8892            crate::role::UntypedRole,
8893            UntypedMessage::new("ordered-transform", serde_json::json!({}))
8894                .expect("test request should serialize"),
8895        );
8896        let request_id = sent.raw_id().clone();
8897        let pending_reply = pending_replies
8898            .remove(&request_id)
8899            .expect("the request should have a pending reply");
8900        let (dispatch, response_dispatch) = incoming_actor::dispatch_from_response(
8901            pending_reply,
8902            Err(crate::Error::invalid_params()),
8903        );
8904        let Dispatch::Response(result, router) = dispatch else {
8905            panic!("expected a response dispatch");
8906        };
8907        router
8908            .route_with_result(result)
8909            .expect("response should route to the pending request");
8910        let acknowledgment = response_dispatch
8911            .complete()
8912            .expect("an ordered response should wait for acknowledgment");
8913        let acknowledgment = Arc::new(Mutex::new(Some(acknowledgment)));
8914        let acknowledgment_probe = acknowledgment.clone();
8915
8916        let error =
8917            futures::executor::block_on(sent.block_task_with_ordered_result(move |result| {
8918                assert_eq!(
8919                    acknowledgment_probe
8920                        .lock()
8921                        .expect("acknowledgment mutex poisoned")
8922                        .as_mut()
8923                        .expect("acknowledgment receiver should remain available")
8924                        .try_recv()
8925                        .expect("acknowledgment sender should remain open"),
8926                    None,
8927                    "the ordered response was acknowledged before its transform"
8928                );
8929                result
8930            }))
8931            .expect_err("the peer error should survive the ordered transform");
8932        assert_eq!(error.code, crate::ErrorCode::INVALID_PARAMS);
8933
8934        let acknowledgment = acknowledgment
8935            .lock()
8936            .expect("acknowledgment mutex poisoned")
8937            .take()
8938            .expect("acknowledgment receiver should remain available");
8939        futures::executor::block_on(acknowledgment)
8940            .expect("the transform should release the ordered response");
8941    }
8942
8943    #[cfg(feature = "unstable_protocol_v2")]
8944    #[test]
8945    fn outgoing_request_readiness_failure_rejects_without_publication() {
8946        let (connection, message_rx, pending_replies) = connection_for_response_hook_tests();
8947        let hook_ran = Arc::new(AtomicBool::new(false));
8948        let sent = connection.prepare_request_to_with_response_hook_after::<Raw, _, _, _>(
8949            crate::role::UntypedRole,
8950            UntypedMessage::new("never-published", serde_json::json!({}))
8951                .expect("test request should serialize"),
8952            future::ready(Err(crate::Error::internal_error().data("readiness failed"))),
8953            {
8954                let hook_ran = hook_ran.clone();
8955                move |_| {
8956                    hook_ran.store(true, Ordering::Release);
8957                    Ok(())
8958                }
8959            },
8960        );
8961        let sent = sent.into_sent_request(false);
8962
8963        let (transport_tx, mut transport_rx) = mpsc::unbounded();
8964        let mut actor = Box::pin(outgoing_actor::outgoing_protocol_actor(
8965            message_rx,
8966            pending_replies,
8967            transport_tx,
8968            ProtocolCompat::new(ProtocolMode::disabled()),
8969            future::pending::<()>().boxed().shared(),
8970        ));
8971
8972        assert!(
8973            actor.as_mut().now_or_never().is_none(),
8974            "the outgoing actor should continue serving after rejecting the request"
8975        );
8976        assert!(
8977            transport_rx.next().now_or_never().is_none(),
8978            "a request whose readiness failed must not be published"
8979        );
8980        let error = futures::executor::block_on(sent.block_task())
8981            .expect_err("the readiness error should reach the request consumer");
8982        assert_eq!(error.code, crate::ErrorCode::INTERNAL_ERROR);
8983        assert_eq!(error.data, Some(serde_json::json!("readiness failed")));
8984        assert!(!hook_ran.load(Ordering::Acquire));
8985    }
8986
8987    #[test]
8988    fn ordered_request_is_marked_before_entering_outgoing_queue() {
8989        let (message_tx, mut message_rx) = mpsc::unbounded();
8990        let (task_tx, mut task_rx) = mpsc::unbounded();
8991        let (dynamic_handler_tx, _dynamic_handler_rx) = mpsc::unbounded();
8992        let transport_completion: SharedTransportCompletion =
8993            future::ready(Ok::<(), crate::Error>(())).boxed().shared();
8994        let pending_replies = PendingReplies::default();
8995        let connection = ConnectionTo::new(
8996            crate::role::UntypedRole,
8997            message_tx,
8998            task_tx,
8999            dynamic_handler_tx,
9000            transport_completion,
9001            pending_replies.registrar(),
9002            ProtocolMode::disabled(),
9003        );
9004
9005        let sent = connection.send_ordered_request_to::<Raw, _, _>(
9006            crate::role::UntypedRole,
9007            UntypedMessage::new("ordered", serde_json::json!({}))
9008                .expect("test request should serialize"),
9009        );
9010        let request_id = sent.raw_id().clone();
9011        let message = futures::FutureExt::now_or_never(futures::StreamExt::next(&mut message_rx))
9012            .expect("outgoing request should already be queued")
9013            .expect("outgoing request queue should remain open");
9014        let OutgoingMessage::Request { id, .. } = message else {
9015            panic!("expected an outgoing request");
9016        };
9017        assert_eq!(id, request_id);
9018
9019        let pending_reply = pending_replies
9020            .remove(&request_id)
9021            .expect("the request should have a pending reply");
9022        assert!(
9023            pending_reply.ordering.is_ordered(),
9024            "the response ordering barrier must be installed before publication"
9025        );
9026
9027        // Route the response before the callback is registered. The pre-set
9028        // ordering marker must hold dispatch until the callback task is
9029        // subsequently installed and completes.
9030        let (dispatch, response_dispatch) = incoming_actor::dispatch_from_response(
9031            pending_reply,
9032            Ok(serde_json::json!({"ok": true})),
9033        );
9034        let Dispatch::Response(result, router) = dispatch else {
9035            panic!("expected a response dispatch");
9036        };
9037        router
9038            .route_with_result(result)
9039            .expect("response should route to the pending request");
9040        let acknowledgment = response_dispatch
9041            .complete()
9042            .expect("an ordered response should require acknowledgment");
9043
9044        let callback_ran = Arc::new(AtomicBool::new(false));
9045        sent.on_receiving_result({
9046            let callback_ran = callback_ran.clone();
9047            async move |result| {
9048                assert_eq!(result?, serde_json::json!({"ok": true}));
9049                callback_ran.store(true, Ordering::Release);
9050                Ok(())
9051            }
9052        })
9053        .expect("ordered callback should be scheduled");
9054
9055        let task = futures::FutureExt::now_or_never(futures::StreamExt::next(&mut task_rx))
9056            .expect("callback task should already be queued")
9057            .expect("callback task queue should remain open");
9058        futures::executor::block_on(task.run_for_test()).expect("callback task should succeed");
9059        futures::executor::block_on(acknowledgment)
9060            .expect("callback completion should acknowledge dispatch");
9061        assert!(callback_ran.load(Ordering::Acquire));
9062    }
9063
9064    fn next_dynamic_handler_message<Counterpart: Role>(
9065        receiver: &mut mpsc::UnboundedReceiver<DynamicHandlerMessage<Counterpart>>,
9066    ) -> Option<DynamicHandlerMessage<Counterpart>> {
9067        futures::FutureExt::now_or_never(futures::StreamExt::next(receiver))
9068            .expect("dynamic-handler receiver should be ready")
9069    }
9070
9071    #[cfg(feature = "unstable_protocol_v2")]
9072    #[test]
9073    fn v2_dynamic_handler_guard_registers_and_removes_handler() {
9074        let (message_tx, _message_rx) = mpsc::unbounded();
9075        let (task_tx, _task_rx) = mpsc::unbounded();
9076        let (dynamic_handler_tx, mut dynamic_handler_rx) = mpsc::unbounded();
9077        let transport_completion: SharedTransportCompletion =
9078            future::ready(Ok::<(), crate::Error>(())).boxed().shared();
9079        let pending_replies = PendingReplies::default();
9080        let connection = crate::v2::ConnectionTo {
9081            inner: ConnectionTo::new(
9082                Agent,
9083                message_tx,
9084                task_tx,
9085                dynamic_handler_tx,
9086                transport_completion,
9087                pending_replies.registrar(),
9088                ProtocolMode::v2_client(),
9089            ),
9090        };
9091
9092        let guard = connection
9093            .add_dynamic_handler(NullHandler)
9094            .expect("v2 dynamic handler should register");
9095        let added_uuid = match next_dynamic_handler_message(&mut dynamic_handler_rx) {
9096            Some(DynamicHandlerMessage::AddDynamicHandler(uuid, _, _)) => uuid,
9097            other => panic!("expected v2 handler registration, got {other:?}"),
9098        };
9099
9100        drop(guard);
9101
9102        match next_dynamic_handler_message(&mut dynamic_handler_rx) {
9103            Some(DynamicHandlerMessage::RemoveDynamicHandler(uuid)) => {
9104                assert_eq!(uuid, added_uuid);
9105            }
9106            other => panic!("expected v2 handler removal, got {other:?}"),
9107        }
9108    }
9109
9110    #[test]
9111    fn dropping_dynamic_handler_guard_unregisters_handler() {
9112        let (connection, mut receiver) = connection_with_dynamic_handler_receiver();
9113        let guard = connection.add_dynamic_handler(NullHandler).unwrap();
9114
9115        let added_uuid = match next_dynamic_handler_message(&mut receiver) {
9116            Some(DynamicHandlerMessage::AddDynamicHandler(uuid, _, _)) => uuid,
9117            other => panic!("expected handler registration, got {other:?}"),
9118        };
9119
9120        drop(guard);
9121
9122        match next_dynamic_handler_message(&mut receiver) {
9123            Some(DynamicHandlerMessage::RemoveDynamicHandler(uuid)) => {
9124                assert_eq!(uuid, added_uuid);
9125            }
9126            other => panic!("expected handler removal, got {other:?}"),
9127        }
9128    }
9129
9130    #[test]
9131    fn dropping_dynamic_handler_guard_deactivates_queued_handler_immediately() {
9132        let (connection, mut receiver) = connection_with_dynamic_handler_receiver();
9133        let guard = connection
9134            .add_dynamic_handler(ClaimingDynamicHandler)
9135            .expect("dynamic handler should register");
9136        let mut handler = match next_dynamic_handler_message(&mut receiver) {
9137            Some(DynamicHandlerMessage::AddDynamicHandler(_, handler, _)) => handler,
9138            other => panic!("expected handler registration, got {other:?}"),
9139        };
9140
9141        drop(guard);
9142
9143        let message = Dispatch::Notification(
9144            UntypedMessage::new("stale", serde_json::json!({}))
9145                .expect("test notification should serialize"),
9146        );
9147        let outcome =
9148            futures::executor::block_on(handler.dyn_handle_dispatch_from(message, connection))
9149                .expect("inactive handler should decline cleanly");
9150        assert!(matches!(outcome, Handled::No { retry: false, .. }));
9151    }
9152
9153    #[test]
9154    fn dynamic_handler_barrier_acknowledges_prior_messages() {
9155        let (connection, mut receiver) = connection_with_dynamic_handler_receiver();
9156        let _guard = connection.add_dynamic_handler(NullHandler).unwrap();
9157        let mut barrier = Box::pin(connection.dynamic_handler_barrier());
9158
9159        assert!(matches!(
9160            next_dynamic_handler_message(&mut receiver),
9161            Some(DynamicHandlerMessage::AddDynamicHandler(_, _, _))
9162        ));
9163        assert!(
9164            barrier.as_mut().now_or_never().is_none(),
9165            "the barrier must wait for the incoming actor"
9166        );
9167
9168        let acknowledgment = match next_dynamic_handler_message(&mut receiver) {
9169            Some(DynamicHandlerMessage::AcknowledgedBarrier(acknowledgment)) => acknowledgment,
9170            other => panic!("expected acknowledged barrier, got {other:?}"),
9171        };
9172        acknowledgment
9173            .send(())
9174            .expect("the barrier receiver should remain active");
9175        futures::executor::block_on(barrier)
9176            .expect("the acknowledged dynamic-handler barrier should complete");
9177    }
9178
9179    #[test]
9180    fn detaching_dynamic_handler_guard_does_not_leak_connection() {
9181        let (connection, mut receiver) = connection_with_dynamic_handler_receiver();
9182        let guard = connection.add_dynamic_handler(NullHandler).unwrap();
9183
9184        assert!(matches!(
9185            next_dynamic_handler_message(&mut receiver),
9186            Some(DynamicHandlerMessage::AddDynamicHandler(_, _, _))
9187        ));
9188
9189        drop(connection);
9190        guard.detach();
9191
9192        assert!(
9193            next_dynamic_handler_message(&mut receiver).is_none(),
9194            "detach should retain the handler without retaining a connection sender"
9195        );
9196    }
9197
9198    #[tokio::test]
9199    async fn write_line_flushes_buffered_writers() {
9200        let mut writer =
9201            futures::io::BufWriter::with_capacity(4096, futures::io::Cursor::new(Vec::new()));
9202
9203        write_line(&mut writer, "message".into()).await.unwrap();
9204
9205        assert_eq!(writer.into_inner().into_inner(), b"message\n");
9206    }
9207
9208    #[tokio::test]
9209    async fn lossy_lines_strip_line_endings_and_replace_invalid_utf8() {
9210        use futures::TryStreamExt as _;
9211
9212        let reader = futures::io::Cursor::new(b"crlf\r\n\ninva\xfflid\nno ending".to_vec());
9213
9214        let lines: Vec<String> = lossy_lines(reader).try_collect().await.unwrap();
9215
9216        assert_eq!(lines, ["crlf", "", "inva\u{FFFD}lid", "no ending"]);
9217    }
9218
9219    #[test]
9220    fn peel_successor_envelopes_returns_plain_messages_unchanged() {
9221        let params = serde_json::json!({ "key": "value" });
9222        let (method, peeled) = peel_successor_envelopes("session/update", &params);
9223        assert_eq!(method, "session/update");
9224        assert_eq!(peeled, &params);
9225    }
9226
9227    #[test]
9228    fn peel_successor_envelopes_unwraps_nested_envelopes() {
9229        let params = serde_json::json!({
9230            "method": "proxy/successor",
9231            "params": {
9232                "method": "$/cancel_request",
9233                "params": { "requestId": "req-1" }
9234            }
9235        });
9236        let (method, peeled) = peel_successor_envelopes("proxy/successor", &params);
9237        assert_eq!(method, "$/cancel_request");
9238        assert_eq!(peeled, &serde_json::json!({ "requestId": "req-1" }));
9239    }
9240
9241    #[test]
9242    fn peel_successor_envelopes_leaves_malformed_envelopes_intact() {
9243        // No string `method` field: the envelope cannot be peeled, so the
9244        // message is returned as-is for the handler chain to deal with.
9245        let params = serde_json::json!({ "unexpected": true });
9246        let (method, peeled) = peel_successor_envelopes("proxy/successor", &params);
9247        assert_eq!(method, "proxy/successor");
9248        assert_eq!(peeled, &params);
9249    }
9250
9251    mod cancel_request {
9252        use super::super::*;
9253
9254        fn notification(method: &str, params: serde_json::Value) -> UntypedMessage {
9255            UntypedMessage::new(method, params).expect("well-formed JSON")
9256        }
9257
9258        #[test]
9259        fn cancellation_request_id_is_extracted_from_wrapped_notifications() {
9260            let message = notification(
9261                "proxy/successor",
9262                serde_json::json!({
9263                    "method": "$/cancel_request",
9264                    "params": { "requestId": "req-1" }
9265                }),
9266            );
9267            let request_id = cancellation_request_id_from_message(&message)
9268                .expect("wrapped cancel should parse");
9269            assert_eq!(request_id, Some(RawJsonRpcId::Str("req-1".into())));
9270        }
9271
9272        #[test]
9273        fn malformed_successor_envelope_is_not_treated_as_cancellation() {
9274            // The envelope cannot be peeled; the message must flow on to the
9275            // handler chain instead of erroring the dispatch.
9276            let message = notification("proxy/successor", serde_json::json!({ "bogus": true }));
9277            let request_id = cancellation_request_id_from_message(&message)
9278                .expect("malformed envelope should be left to the handler chain");
9279            assert_eq!(request_id, None);
9280        }
9281
9282        #[test]
9283        fn cancel_request_notifications_are_detected_even_when_wrapped() {
9284            let plain = notification("$/cancel_request", serde_json::json!({ "requestId": 1 }));
9285            assert!(is_cancel_request_notification(&plain));
9286
9287            let wrapped = notification(
9288                "proxy/successor",
9289                serde_json::json!({
9290                    "method": "$/cancel_request",
9291                    "params": { "requestId": 1 }
9292                }),
9293            );
9294            assert!(is_cancel_request_notification(&wrapped));
9295
9296            let other_wrapped = notification(
9297                "proxy/successor",
9298                serde_json::json!({
9299                    "method": "session/update",
9300                    "params": {}
9301                }),
9302            );
9303            assert!(!is_cancel_request_notification(&other_wrapped));
9304
9305            let malformed_envelope =
9306                notification("proxy/successor", serde_json::json!({ "bogus": true }));
9307            assert!(!is_cancel_request_notification(&malformed_envelope));
9308        }
9309
9310        #[test]
9311        fn malformed_cancel_request_params_error() {
9312            let message = notification(
9313                "$/cancel_request",
9314                serde_json::json!({ "requestId": { "not": "an id" } }),
9315            );
9316            cancellation_request_id_from_message(&message)
9317                .expect_err("malformed cancel params should error");
9318        }
9319
9320        #[test]
9321        fn registry_marks_and_removes_requests() {
9322            let registry = RequestCancellationRegistry::new();
9323            let id = RawJsonRpcId::Str("req-1".into());
9324
9325            let responder_cancellation = registry.register(&id);
9326            let marker = responder_cancellation.cancellation();
9327            assert!(!marker.is_cancelled());
9328
9329            assert!(registry.cancel(&id));
9330            assert!(marker.is_cancelled());
9331            assert!(responder_cancellation.cancellation().is_cancelled());
9332
9333            drop(responder_cancellation);
9334            assert!(!registry.cancel(&id), "slot should be removed on drop");
9335        }
9336
9337        #[test]
9338        fn reused_request_id_does_not_cross_wire_cancellation_state() {
9339            let registry = RequestCancellationRegistry::new();
9340            let id = RawJsonRpcId::Str("dup".into());
9341
9342            // A protocol-violating peer reuses an in-flight request ID.
9343            let first = registry.register(&id);
9344            let first_marker = first.cancellation();
9345            let second = registry.register(&id);
9346            let second_marker = second.cancellation();
9347
9348            // A cancellation targets whichever request currently owns the ID.
9349            assert!(registry.cancel(&id));
9350            assert!(second_marker.is_cancelled());
9351            assert!(
9352                !first_marker.is_cancelled(),
9353                "the stale request must not observe the newer request's cancellation"
9354            );
9355
9356            // The stale responder must hand out detached markers, not the
9357            // newer request's marker.
9358            assert!(!first.cancellation().is_cancelled());
9359
9360            // Dropping the stale responder must not remove the newer
9361            // request's slot.
9362            drop(first);
9363            assert!(registry.cancel(&id), "newer slot should still be present");
9364
9365            drop(second);
9366            assert!(!registry.cancel(&id), "slot should be removed on drop");
9367        }
9368    }
9369}