[app-server] model list API

Author: owenlin0

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

@@ -106,6 +106,13 @@ client_request_definitions! {
         params: ListConversationsParams,
         response: ListConversationsResponse,
     },
+    #[serde(rename = "model/list")]
+    #[ts(rename = "model/list")]
+    /// List available Codex models along with display metadata.
+    ListModels {
+        params: ListModelsParams,
+        response: ListModelsResponse,
+    },
     /// Resume a recorded Codex conversation from a rollout file.
     ResumeConversation {
         params: ResumeConversationParams,
@@ -308,6 +315,40 @@ pub struct ListConversationsResponse {
     pub next_cursor: Option<String>,
 }
 
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+pub struct ListModelsParams {
+    /// Optional page size; defaults to a reasonable server-side value.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub page_size: Option<usize>,
+    /// Opaque pagination cursor returned by a previous call.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cursor: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+pub struct Model {
+    pub id: String,
+    pub slug: String,
+    pub display_name: String,
+    pub description: String,
+    pub supported_reasoning_efforts: Vec<ReasoningEffort>,
+    pub default_reasoning_effort: ReasoningEffort,
+    // Only one model should be marked as default.
+    pub is_default: bool,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+pub struct ListModelsResponse {
+    pub items: Vec<Model>,
+    /// Opaque cursor to pass to the next call to continue after the last item.
+    /// if None, there are no more items to return.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub next_cursor: Option<String>,
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
 #[serde(rename_all = "camelCase")]
 pub struct ResumeConversationParams {
@@ -999,4 +1040,21 @@ mod tests {
         );
         Ok(())
     }
+
+    #[test]
+    fn serialize_list_models() -> Result<()> {
+        let request = ClientRequest::ListModels {
+            request_id: RequestId::Integer(2),
+            params: ListModelsParams::default(),
+        };
+        assert_eq!(
+            json!({
+                "method": "model/list",
+                "id": 2,
+                "params": {}
+            }),
+            serde_json::to_value(&request)?,
+        );
+        Ok(())
+    }
 }

codex-rs/app-server/src/codex_message_processor.rs

@@ -1,6 +1,7 @@
 use crate::error_code::INTERNAL_ERROR_CODE;
 use crate::error_code::INVALID_REQUEST_ERROR_CODE;
 use crate::fuzzy_file_search::run_fuzzy_file_search;
+use crate::models::codex_models;
 use crate::outgoing_message::OutgoingMessageSender;
 use crate::outgoing_message::OutgoingNotification;
 use codex_app_server_protocol::AddConversationListenerParams;
@@ -29,6 +30,8 @@ use codex_app_server_protocol::InterruptConversationResponse;
 use codex_app_server_protocol::JSONRPCErrorError;
 use codex_app_server_protocol::ListConversationsParams;
 use codex_app_server_protocol::ListConversationsResponse;
+use codex_app_server_protocol::ListModelsParams;
+use codex_app_server_protocol::ListModelsResponse;
 use codex_app_server_protocol::LoginApiKeyParams;
 use codex_app_server_protocol::LoginApiKeyResponse;
 use codex_app_server_protocol::LoginChatGptCompleteNotification;
@@ -111,7 +114,6 @@ use uuid::Uuid;
 
 // Duration before a ChatGPT login attempt is abandoned.
 const LOGIN_CHATGPT_TIMEOUT: Duration = Duration::from_secs(10 * 60);
-
 struct ActiveLogin {
     shutdown_handle: ShutdownHandle,
     login_id: Uuid,
@@ -172,6 +174,9 @@ impl CodexMessageProcessor {
             ClientRequest::ListConversations { request_id, params } => {
                 self.handle_list_conversations(request_id, params).await;
             }
+            ClientRequest::ListModels { request_id, params } => {
+                self.list_models(request_id, params).await;
+            }
             ClientRequest::ResumeConversation { request_id, params } => {
                 self.handle_resume_conversation(request_id, params).await;
             }
@@ -831,6 +836,58 @@ impl CodexMessageProcessor {
         self.outgoing.send_response(request_id, response).await;
     }
 
+    async fn list_models(&self, request_id: RequestId, params: ListModelsParams) {
+        let ListModelsParams { page_size, cursor } = params;
+        let models = codex_models();
+        let total = models.len();
+
+        if total == 0 {
+            let response = ListModelsResponse {
+                items: Vec::new(),
+                next_cursor: None,
+            };
+            self.outgoing.send_response(request_id, response).await;
+            return;
+        }
+
+        let effective_page_size = page_size.unwrap_or(total).max(1).min(total);
+        let start = match cursor {
+            Some(cursor) => match cursor.parse::<usize>() {
+                Ok(idx) => idx,
+                Err(_) => {
+                    let error = JSONRPCErrorError {
+                        code: INVALID_REQUEST_ERROR_CODE,
+                        message: format!("invalid cursor: {cursor}"),
+                        data: None,
+                    };
+                    self.outgoing.send_error(request_id, error).await;
+                    return;
+                }
+            },
+            None => 0,
+        };
+
+        if start > total {
+            let error = JSONRPCErrorError {
+                code: INVALID_REQUEST_ERROR_CODE,
+                message: format!("cursor {start} exceeds total models {total}"),
+                data: None,
+            };
+            self.outgoing.send_error(request_id, error).await;
+            return;
+        }
+
+        let end = start.saturating_add(effective_page_size).min(total);
+        let items = models[start..end].to_vec();
+        let next_cursor = if end < total {
+            Some(end.to_string())
+        } else {
+            None
+        };
+        let response = ListModelsResponse { items, next_cursor };
+        self.outgoing.send_response(request_id, response).await;
+    }
+
     async fn handle_resume_conversation(
         &self,
         request_id: RequestId,

codex-rs/app-server/src/lib.rs

@@ -27,6 +27,7 @@ mod codex_message_processor;
 mod error_code;
 mod fuzzy_file_search;
 mod message_processor;
+mod models;
 mod outgoing_message;
 
 /// Size of the bounded channels used to communicate between tasks. The value

codex-rs/app-server/src/models.rs

@@ -0,0 +1,37 @@
+use codex_app_server_protocol::Model;
+use codex_protocol::config_types::ReasoningEffort;
+
+const DEFAULT_MODEL_SLUG: &str = "gpt-5-codex";
+pub const DEFAULT_REASONING_EFFORT: ReasoningEffort = ReasoningEffort::Medium;
+
+pub fn codex_models() -> Vec<Model> {
+    vec![
+        Model {
+            id: DEFAULT_MODEL_SLUG.to_string(),
+            slug: DEFAULT_MODEL_SLUG.to_string(),
+            display_name: "GPT-5 Codex".to_string(),
+            description: "Specialized GPT-5 variant optimized for Codex.".to_string(),
+            supported_reasoning_efforts: vec![
+                ReasoningEffort::Low,
+                ReasoningEffort::Medium,
+                ReasoningEffort::High,
+            ],
+            default_reasoning_effort: DEFAULT_REASONING_EFFORT,
+            is_default: true,
+        },
+        Model {
+            id: "gpt-5".to_string(),
+            slug: "gpt-5".to_string(),
+            display_name: "GPT-5".to_string(),
+            description: "General-purpose GPT-5 model.".to_string(),
+            supported_reasoning_efforts: vec![
+                ReasoningEffort::Minimal,
+                ReasoningEffort::Low,
+                ReasoningEffort::Medium,
+                ReasoningEffort::High,
+            ],
+            default_reasoning_effort: DEFAULT_REASONING_EFFORT,
+            is_default: false,
+        },
+    ]
+}

codex-rs/app-server/tests/common/mcp_process.rs

@@ -21,6 +21,7 @@ use codex_app_server_protocol::GetAuthStatusParams;
 use codex_app_server_protocol::InitializeParams;
 use codex_app_server_protocol::InterruptConversationParams;
 use codex_app_server_protocol::ListConversationsParams;
+use codex_app_server_protocol::ListModelsParams;
 use codex_app_server_protocol::LoginApiKeyParams;
 use codex_app_server_protocol::NewConversationParams;
 use codex_app_server_protocol::RemoveConversationListenerParams;
@@ -264,6 +265,15 @@ impl McpProcess {
         self.send_request("listConversations", params).await
     }
 
+    /// Send a `model/list` JSON-RPC request.
+    pub async fn send_list_models_request(
+        &mut self,
+        params: ListModelsParams,
+    ) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("model/list", params).await
+    }
+
     /// Send a `resumeConversation` JSON-RPC request.
     pub async fn send_resume_conversation_request(
         &mut self,

codex-rs/app-server/tests/suite/mod.rs

@@ -7,6 +7,7 @@ mod fuzzy_file_search;
 mod interrupt;
 mod list_resume;
 mod login;
+mod model_list;
 mod rate_limits;
 mod send_message;
 mod set_default_model;