[app-server] type client response payloads (#20050)

## Why

`pr17088` adds typed server-originated request/response plumbing, but
successful client responses are still erased into bare JSON-RPC `result`
values before app-server can make any typed decision about them.

This precursor PR keeps successful client responses typed until the
outgoing response seam. It is intentionally limited to
protocol/app-server plumbing so the analytics behavior change can review
separately on top.

## What changed

- Add `ClientResponsePayload` as the pre-serialization client response
body type.
- Route app-server successful response paths through the typed payload
seam while preserving existing handler-local analytics behavior.
- Keep `InterruptConversation` JSON-RPC-only because it has no
`ClientResponse` variant.
- Move the new payload conversion tests into a dedicated protocol test
module.

## Verification

- `cargo check -p codex-app-server`
- `cargo test -p codex-app-server-protocol`

codex-rs/app-server-protocol/src/protocol/common.rs

@@ -157,6 +157,7 @@ macro_rules! client_request_definitions {
                 params: $(#[$params_meta:meta])* $params:ty,
                 $(inspect_params: $inspect_params:tt,)?
                 serialization: $serialization:ident $( ( $($serialization_args:tt)* ) )?,
+                $(manual_payload_conversion: $manual_payload_conversion:ident,)?
                 response: $response:ty,
             }
         ),* $(,)?
@@ -243,8 +244,100 @@ macro_rules! client_request_definitions {
                     })
                     .unwrap_or_else(|| "<unknown>".to_string())
             }
+
+            pub fn into_jsonrpc_parts(
+                self,
+            ) -> std::result::Result<(RequestId, crate::Result), serde_json::Error> {
+                match self {
+                    $(
+                        Self::$variant { request_id, response } => {
+                            serde_json::to_value(response).map(|result| (request_id, result))
+                        }
+                    )*
+                }
+            }
         }
 
+        #[derive(Debug, Clone)]
+        #[allow(clippy::large_enum_variant)]
+        pub enum ClientResponsePayload {
+            $( $variant($response), )*
+            InterruptConversation(v1::InterruptConversationResponse),
+        }
+
+        impl ClientResponsePayload {
+            pub fn into_jsonrpc_parts_and_payload(
+                self,
+                request_id: RequestId,
+            ) -> std::result::Result<
+                (RequestId, crate::Result, Option<ClientResponsePayload>),
+                serde_json::Error,
+            > {
+                match self {
+                    $(
+                        Self::$variant(response) => {
+                            let result = serde_json::to_value(&response)?;
+                            Ok((request_id, result, Some(Self::$variant(response))))
+                        }
+                    )*
+                    Self::InterruptConversation(response) => {
+                        serde_json::to_value(response).map(|result| (request_id, result, None))
+                    }
+                }
+            }
+
+            pub fn into_client_response(self, request_id: RequestId) -> Option<ClientResponse> {
+                match self {
+                    $(
+                        Self::$variant(response) => {
+                            Some(ClientResponse::$variant {
+                                request_id,
+                                response,
+                            })
+                        }
+                    )*
+                    Self::InterruptConversation(_) => None,
+                }
+            }
+
+            pub fn into_jsonrpc_parts(
+                self,
+                request_id: RequestId,
+            ) -> std::result::Result<(RequestId, crate::Result), serde_json::Error> {
+                self.to_jsonrpc_parts(request_id)
+            }
+
+            pub fn to_jsonrpc_parts(
+                &self,
+                request_id: RequestId,
+            ) -> std::result::Result<(RequestId, crate::Result), serde_json::Error> {
+                match self {
+                    $(
+                        Self::$variant(response) => {
+                            serde_json::to_value(response).map(|result| (request_id, result))
+                        }
+                    )*
+                    Self::InterruptConversation(response) => {
+                        serde_json::to_value(response).map(|result| (request_id, result))
+                    }
+                }
+            }
+        }
+
+        impl From<v1::InterruptConversationResponse> for ClientResponsePayload {
+            fn from(response: v1::InterruptConversationResponse) -> Self {
+                Self::InterruptConversation(response)
+            }
+        }
+
+        $(
+            client_response_payload_from_impl!(
+                $variant,
+                $response
+                $(, $manual_payload_conversion)?
+            );
+        )*
+
         impl crate::experimental_api::ExperimentalApi for ClientRequest {
             fn experimental_reason(&self) -> Option<&'static str> {
                 match self {
@@ -317,6 +410,17 @@ macro_rules! client_request_definitions {
     };
 }
 
+macro_rules! client_response_payload_from_impl {
+    ($variant:ident, $response:ty) => {
+        impl From<$response> for ClientResponsePayload {
+            fn from(response: $response) -> Self {
+                Self::$variant(response)
+            }
+        }
+    };
+    ($variant:ident, $response:ty, manual) => {};
+}
+
 client_request_definitions! {
     Initialize {
         params: v1::InitializeParams,
@@ -789,11 +893,13 @@ client_request_definitions! {
     ConfigValueWrite => "config/value/write" {
         params: v2::ConfigValueWriteParams,
         serialization: global("config"),
+        manual_payload_conversion: manual,
         response: v2::ConfigWriteResponse,
     },
     ConfigBatchWrite => "config/batchWrite" {
         params: v2::ConfigBatchWriteParams,
         serialization: global("config"),
+        manual_payload_conversion: manual,
         response: v2::ConfigWriteResponse,
     },
 
@@ -2766,3 +2872,7 @@ mod tests {
         );
     }
 }
+
+#[cfg(test)]
+#[path = "common_tests.rs"]
+mod common_tests;

codex-rs/app-server-protocol/src/protocol/common_tests.rs

@@ -0,0 +1,44 @@
+use super::*;
+use anyhow::Result;
+use codex_protocol::protocol::TurnAbortReason;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+
+#[test]
+fn client_response_payload_returns_jsonrpc_parts_and_client_response() -> Result<()> {
+    let (request_id, result, payload) =
+        ClientResponsePayload::ThreadArchive(v2::ThreadArchiveResponse {})
+            .into_jsonrpc_parts_and_payload(RequestId::Integer(7))?;
+
+    assert_eq!(request_id, RequestId::Integer(7));
+    assert_eq!(result, json!({}));
+
+    let Some(ClientResponse::ThreadArchive {
+        request_id,
+        response: _,
+    }) = payload.and_then(|payload| payload.into_client_response(RequestId::Integer(7)))
+    else {
+        panic!("expected thread/archive client response");
+    };
+    assert_eq!(request_id, RequestId::Integer(7));
+    Ok(())
+}
+
+#[test]
+fn interrupt_conversation_payload_stays_jsonrpc_only() -> Result<()> {
+    let (request_id, result, payload) =
+        ClientResponsePayload::InterruptConversation(v1::InterruptConversationResponse {
+            abort_reason: TurnAbortReason::Interrupted,
+        })
+        .into_jsonrpc_parts_and_payload(RequestId::Integer(8))?;
+
+    assert_eq!(request_id, RequestId::Integer(8));
+    assert_eq!(
+        result,
+        json!({
+            "abortReason": "interrupted",
+        })
+    );
+    assert!(payload.is_none());
+    Ok(())
+}