feat(acp)!: answer dropped request responders with an error (#462)

A request handler that dropped its `Responder` without responding left the
peer waiting forever. On a v2 connection, dropping the `initialize`
responder also left the connection stuck initializing, so a retry was
rejected as "already in progress".

The SDK now answers such a request itself: with -32800 (Request cancelled)
if the peer had cancelled it via `$/cancel_request`, and otherwise with
-32603 (Internal error) whose data names the method. Nothing is sent when a
response was already sent or handed off (e.g. `forward_response_to`), while
another owner still holds the responder, or once the connection is shutting
down or terminated. If the handler that dropped the responder returns an
error, that error is the response instead of the fallback.

The fallback goes through the normal response path, so a dropped
`initialize` responder fails initialization like any other error: a first
`initialize` leaves the connection uninitialized and can be retried, and a
failed repeat keeps the previous initialization.

BREAKING CHANGE: dropping a `Responder` without responding now sends an
error response for the request (-32603, or -32800 if the peer cancelled the
request) instead of sending nothing. Handlers that intentionally dropped a
responder and answered the request some other way must now keep the
responder and respond through it.

Co-authored-by: Claude <noreply@anthropic.com>

Author: benbrandt

md/request-cancellation.md

@@ -43,6 +43,29 @@ an unknown or already-completed request ID is silently ignored. A
 not a string, number, or null) is logged and ignored without a reply, like any
 other malformed notification.
 
+## Unanswered Requests
+
+The SDK makes sure a request it received is always answered, even when the
+handler never responds. If a `Responder` is dropped without a response having
+been sent through it, the SDK sends an error response for the request:
+
+- `-32800` (Request cancelled) if the peer had cancelled the request with
+  `$/cancel_request`, as ACP requires for a cancelled request whose method
+  defines no cancellation result;
+- otherwise `-32603` (Internal error), with data naming the method.
+
+If the handler that dropped the responder returns an error, that error is the
+response instead. No automatic response is sent when a response was already
+sent or handed off (for example with `forward_response_to`), when the
+responder was moved into another task or wrapper that still owns it, or when
+the connection is shutting down or has terminated. Notifications have no
+responder and never get a reply.
+
+The automatic error is an ordinary error response. A dropped `initialize`
+responder fails initialization like any other `initialize` error: a first
+`initialize` leaves the connection uninitialized, so the client can retry, and
+a failed repeat keeps the previous initialization.
+
 ## Interoperability
 
 Protocol-level (`$/`-prefixed) notifications are optional by design. The SDK

md/transport-architecture.md

@@ -178,8 +178,9 @@ protocol v2 removed batches, and v1 support was experimental and best-effort.
 Since the removal, `TransportFrame` has only the `Single` and `Malformed`
 variants, and `TransportBatch` and `TransportBatchEntry` no longer exist. Code
 that matched `TransportFrame::Batch` or built batches should send each message
-as its own `TransportFrame::Single`. Dropping a `Responder` never sends an
-automatic reply.
+as its own `TransportFrame::Single`. A dropped `Responder` is answered with an
+automatic error; see
+[Request Cancellation](./request-cancellation.md#unanswered-requests).
 
 Lifecycle-sensitive routing is unaffected: `ProxyProtocolRouter` requires an
 exact v1 or v2 `proxy/initialize` match and preserves the initial frame without

src/agent-client-protocol/src/concepts/callbacks.rs

@@ -86,7 +86,8 @@
 //!
 //! Send at most one response per request. If a handler responds and then
 //! returns an error, the first response wins and the duplicate completion is
-//! ignored. Dropping a responder sends no response.
+//! ignored. Dropping a responder without responding answers the request with
+//! an error; see [error handling](super::error_handling#dropped-responders).
 //!
 //! # Multiple Handlers
 //!

src/agent-client-protocol/src/concepts/error_handling.rs

@@ -46,6 +46,20 @@
 //! Malformed JSON and invalid request envelopes are handled at the SDK's transport
 //! boundary. Applications do not need to construct uncorrelated Error Responses.
 //!
+//! # Dropped Responders
+//!
+//! Every request gets a response. If a [`Responder`][crate::Responder] is
+//! dropped without responding (and was not moved somewhere that responds,
+//! such as [`SentRequest::forward_response_to`][crate::SentRequest::forward_response_to]),
+//! the SDK answers the request with `-32603` (Internal error), with data naming
+//! the method, or with `-32800` (Request cancelled) if the peer had cancelled
+//! the request with `$/cancel_request`. If the handler that dropped the
+//! responder returns an error, that error is sent instead. Nothing is sent if
+//! a response was already sent or the connection is shutting down.
+//!
+//! The automatic error is an ordinary error response: a dropped `initialize`
+//! responder fails initialization, so the client can retry.
+//!
 //! # The `into_internal_error` Helper
 //!
 //! When working with external libraries that return their own error types,