Lightweight coding agent that runs in your terminal
Rust
Add experimental thread item lookup by ID (#52637)
Brent Traut47c063de5188
diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zstindex f409b73b9d..79aaee89b1 100644Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst differdiff --git a/codex-rs/app-server-protocol/src/protocol/common.rs b/codex-rs/app-server-protocol/src/protocol/common.rsindex ec94ae843d..e934ae7ad1 100644--- a/codex-rs/app-server-protocol/src/protocol/common.rs+++ b/codex-rs/app-server-protocol/src/protocol/common.rs@@ -878,6 +878,13 @@ client_request_definitions! {serialization: None,response: v2::ThreadItemsListResponse,},+ #[experimental("thread/items/read")]+ ThreadItemsRead => "thread/items/read" {+ params: v2::ThreadItemsReadParams,+ // Explicitly concurrent: this primarily reads append-only rollout storage.+ serialization: None,+ response: v2::ThreadItemsReadResponse,+ },/// Append raw Responses API items to the thread history without starting a user turn.ThreadInjectItems => "thread/inject_items" {params: v2::ThreadInjectItemsParams,diff --git a/codex-rs/app-server-protocol/src/protocol/v2/thread.rs b/codex-rs/app-server-protocol/src/protocol/v2/thread.rsindex a88c8608d6..1746ceb7bc 100644--- a/codex-rs/app-server-protocol/src/protocol/v2/thread.rs+++ b/codex-rs/app-server-protocol/src/protocol/v2/thread.rs@@ -1840,6 +1840,25 @@ pub struct ThreadItemsListResponse {pub backwards_cursor: Option<String>,}+/// EXPERIMENTAL - retrieve a bounded set of persisted items from one turn.+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]+#[serde(rename_all = "camelCase")]+#[ts(export_to = "v2/")]+pub struct ThreadItemsReadParams {+ pub thread_id: String,+ pub turn_id: String,+ /// Item IDs to retrieve. Supply 1 to 100 IDs.+ pub item_ids: Vec<String>,+}++/// EXPERIMENTAL - persisted items returned in canonical stored order.+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]+#[serde(rename_all = "camelCase")]+#[ts(export_to = "v2/")]+pub struct ThreadItemsReadResponse {+ pub data: Vec<ThreadItemEntry>,+}+/// EXPERIMENTAL - list ordinary and realtime thread history in rollout order.#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]#[serde(rename_all = "camelCase")]diff --git a/codex-rs/app-server/src/message_processor.rs b/codex-rs/app-server/src/message_processor.rsindex cf0e741882..c9858cd9d5 100644--- a/codex-rs/app-server/src/message_processor.rs+++ b/codex-rs/app-server/src/message_processor.rs@@ -1527,6 +1527,9 @@ impl MessageProcessor {ClientRequest::ThreadItemsList { params, .. } => {self.thread_processor.thread_items_list(params).await}+ ClientRequest::ThreadItemsRead { params, .. } => {+ self.thread_processor.thread_items_read(params).await+ }ClientRequest::ThreadShellCommand { params, .. } => {self.thread_processor.thread_shell_command(&request_id, params)diff --git a/codex-rs/app-server/src/request_processors.rs b/codex-rs/app-server/src/request_processors.rsindex 0edce83c3f..a40486e0d5 100644--- a/codex-rs/app-server/src/request_processors.rs+++ b/codex-rs/app-server/src/request_processors.rs@@ -233,6 +233,8 @@ use codex_app_server_protocol::ThreadItem;use codex_app_server_protocol::ThreadItemEntry;use codex_app_server_protocol::ThreadItemsListParams;use codex_app_server_protocol::ThreadItemsListResponse;+use codex_app_server_protocol::ThreadItemsReadParams;+use codex_app_server_protocol::ThreadItemsReadResponse;use codex_app_server_protocol::ThreadListCwdFilter;use codex_app_server_protocol::ThreadListParams;use codex_app_server_protocol::ThreadListResponse;diff --git a/codex-rs/app-server/src/request_processors/thread_processor.rs b/codex-rs/app-server/src/request_processors/thread_processor.rsindex 5af5b0126c..5b4801a0df 100644--- a/codex-rs/app-server/src/request_processors/thread_processor.rs+++ b/codex-rs/app-server/src/request_processors/thread_processor.rs@@ -902,6 +902,15 @@ impl ThreadRequestProcessor {.map(|response| Some(response.into()))}+ pub(crate) async fn thread_items_read(+ &self,+ params: ThreadItemsReadParams,+ ) -> Result<Option<ClientResponsePayload>, JSONRPCErrorError> {+ self.thread_items_read_response_inner(params)+ .await+ .map(|response| Some(response.into()))+ }+pub(crate) async fn thread_timeline_list(&self,params: ThreadTimelineListParams,@@ -3404,6 +3413,7 @@ impl ThreadRequestProcessor {let page = self.thread_store.list_items(StoreListItemsParams {+ item_ids: None,thread_id,turn_id: Some(turn_id.to_string()),include_archived: true,@@ -3520,6 +3530,7 @@ impl ThreadRequestProcessor {.map_err(paginated_history_list_error)?;let items_page = thread_store.list_items(StoreListItemsParams {+ item_ids: None,thread_id,turn_id: None,include_archived: true,@@ -3566,6 +3577,7 @@ impl ThreadRequestProcessor {let page = self.thread_store.list_items(StoreListItemsParams {+ item_ids: None,thread_id,turn_id,include_archived: true,@@ -3595,18 +3607,7 @@ impl ThreadRequestProcessor {let data = page.items.into_iter()- .map(|stored_item| {- let turn_id = stored_item.turn_id.clone();- let started_at_ms = stored_item.started_at_ms;- let completed_at_ms = stored_item.completed_at_ms;- let item = deserialize_stored_thread_item(stored_item)?;- Ok(ThreadItemEntry {- turn_id,- item,- started_at_ms,- completed_at_ms,- })- })+ .map(stored_thread_item_to_entry).collect::<Result<Vec<_>, _>>()?;Ok(ThreadItemsListResponse {@@ -3616,6 +3617,56 @@ impl ThreadRequestProcessor {})}+ async fn thread_items_read_response_inner(+ &self,+ params: ThreadItemsReadParams,+ ) -> Result<ThreadItemsReadResponse, JSONRPCErrorError> {+ if !(1..=100).contains(¶ms.item_ids.len()) {+ return Err(invalid_request(+ "itemIds must contain 1 to 100 IDs".to_string(),+ ));+ }+ let ThreadItemsReadParams {+ thread_id,+ turn_id,+ item_ids,+ } = params;+ let thread_id = ThreadId::from_string(&thread_id)+ .map_err(|err| invalid_request(format!("invalid thread id: {err}")))?;+ let page_size = item_ids.len();+ let page = self+ .thread_store+ .list_items(StoreListItemsParams {+ item_ids: Some(item_ids),+ thread_id,+ turn_id: Some(turn_id),+ include_archived: true,+ position: None,+ page_size,+ sort_direction: StoreSortDirection::Asc,+ sort_key: StoreItemSortKey::CreatedAtOrdinal,+ after_updated_at_ordinal: None,+ })+ .await+ .map_err(|err| match err {+ ThreadStoreError::InvalidRequest { message } => invalid_request(message),+ ThreadStoreError::Unsupported { .. } => {+ method_not_found("thread/items/read is not supported yet")+ }+ ThreadStoreError::ThreadNotFound { thread_id } => {+ invalid_request(format!("no rollout found for thread id {thread_id}"))+ }+ err => internal_error(format!("failed to read thread items: {err}")),+ })?;+ let data = page+ .items+ .into_iter()+ .map(stored_thread_item_to_entry)+ .collect::<Result<Vec<_>, _>>()?;++ Ok(ThreadItemsReadResponse { data })+ }+async fn load_thread_turns_list_history(&self,thread_id: ThreadId,@@ -6096,6 +6147,21 @@ fn deserialize_stored_thread_item(})}+fn stored_thread_item_to_entry(+ stored_item: codex_thread_store::StoredThreadItem,+) -> Result<ThreadItemEntry, JSONRPCErrorError> {+ let turn_id = stored_item.turn_id.clone();+ let started_at_ms = stored_item.started_at_ms;+ let completed_at_ms = stored_item.completed_at_ms;+ let item = deserialize_stored_thread_item(stored_item)?;+ Ok(ThreadItemEntry {+ turn_id,+ item,+ started_at_ms,+ completed_at_ms,+ })+}+fn stored_turn_to_api_turn(turn: StoredTurn,items_view: TurnItemsView,diff --git a/codex-rs/app-server/tests/common/test_app_server.rs b/codex-rs/app-server/tests/common/test_app_server.rsindex 51276510f2..1e688ae718 100644--- a/codex-rs/app-server/tests/common/test_app_server.rs+++ b/codex-rs/app-server/tests/common/test_app_server.rs@@ -92,6 +92,7 @@ use codex_app_server_protocol::ThreadDeleteParams;use codex_app_server_protocol::ThreadForkParams;use codex_app_server_protocol::ThreadInjectItemsParams;use codex_app_server_protocol::ThreadItemsListParams;+use codex_app_server_protocol::ThreadItemsReadParams;use codex_app_server_protocol::ThreadListParams;use codex_app_server_protocol::ThreadLoadedListParams;use codex_app_server_protocol::ThreadMemoryModeSetParams;@@ -723,6 +724,15 @@ impl TestAppServer {self.send_request("thread/items/list", params).await}+ /// Send a `thread/items/read` JSON-RPC request.+ pub async fn send_thread_items_read_request(+ &mut self,+ params: ThreadItemsReadParams,+ ) -> anyhow::Result<i64> {+ let params = Some(serde_json::to_value(params)?);+ self.send_request("thread/items/read", params).await+ }+/// Send a `model/list` JSON-RPC request.pub async fn send_list_models_request(&mut self,diff --git a/codex-rs/app-server/tests/suite/v2/experimental_api.rs b/codex-rs/app-server/tests/suite/v2/experimental_api.rsindex 1c119d04ba..b3b33bc385 100644--- a/codex-rs/app-server/tests/suite/v2/experimental_api.rs+++ b/codex-rs/app-server/tests/suite/v2/experimental_api.rs@@ -12,6 +12,7 @@ use codex_app_server_protocol::JSONRPCMessage;use codex_app_server_protocol::JSONRPCResponse;use codex_app_server_protocol::MockExperimentalMethodParams;use codex_app_server_protocol::RequestId;+use codex_app_server_protocol::ThreadItemsReadParams;use codex_app_server_protocol::ThreadMemoryMode;use codex_app_server_protocol::ThreadMemoryModeSetParams;use codex_app_server_protocol::ThreadRealtimeStartParams;@@ -65,6 +66,44 @@ async fn mock_experimental_method_requires_experimental_api_capability() -> ResuOk(())}+#[tokio::test]+async fn thread_items_read_requires_experimental_api_capability() -> Result<()> {+ let codex_home = TempDir::new()?;+ let mut mcp = TestAppServer::builder()+ .with_codex_home(codex_home.path())+ .without_auto_env()+ .build()+ .await?;++ let init = mcp+ .initialize_with_capabilities(+ default_client_info(),+ Some(InitializeCapabilities {+ experimental_api: false,+ ..Default::default()+ }),+ )+ .await?;+ let JSONRPCMessage::Response(_) = init else {+ anyhow::bail!("expected initialize response, got {init:?}");+ };++ let request_id = mcp+ .send_thread_items_read_request(ThreadItemsReadParams {+ thread_id: "thr_123".to_string(),+ turn_id: "turn_456".to_string(),+ item_ids: vec!["item_789".to_string()],+ })+ .await?;+ let error = timeout(+ DEFAULT_TIMEOUT,+ mcp.read_stream_until_error_message(RequestId::Integer(request_id)),+ )+ .await??;+ assert_experimental_capability_error(error, "thread/items/read");+ Ok(())+}+#[tokio::test]async fn realtime_conversation_start_requires_experimental_api_capability() -> Result<()> {let codex_home = TempDir::new()?;diff --git a/codex-rs/app-server/tests/suite/v2/thread_read.rs b/codex-rs/app-server/tests/suite/v2/thread_read.rsindex 00e65fee24..aac4fc1151 100644--- a/codex-rs/app-server/tests/suite/v2/thread_read.rs+++ b/codex-rs/app-server/tests/suite/v2/thread_read.rs@@ -29,6 +29,8 @@ use codex_app_server_protocol::ThreadItemsListAnchor;use codex_app_server_protocol::ThreadItemsListCursor;use codex_app_server_protocol::ThreadItemsListParams;use codex_app_server_protocol::ThreadItemsListResponse;+use codex_app_server_protocol::ThreadItemsReadParams;+use codex_app_server_protocol::ThreadItemsReadResponse;use codex_app_server_protocol::ThreadListParams;use codex_app_server_protocol::ThreadListResponse;use codex_app_server_protocol::ThreadNameUpdatedNotification;@@ -2204,6 +2206,48 @@ async fn paginated_history_lists_and_legacy_reads_use_projected_turns_and_items((-32602, message));}+ let read_id = mcp+ .send_thread_items_read_request(ThreadItemsReadParams {+ thread_id: thread_id.to_string(),+ item_ids: vec![+ "agent-1".to_string(),+ "steer-1".to_string(),+ "user-2".to_string(),+ "missing".to_string(),+ ],+ turn_id: "turn-1".to_string(),+ })+ .await?;+ let read: ThreadItemsReadResponse =+ timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(read_id)).await??;+ assert_eq!(+ read.data,+ vec![+ ThreadItemEntry {+ turn_id: "turn-1".to_string(),+ item: ThreadItem::UserMessage {+ id: "steer-1".to_string(),+ client_id: Some("updated-steer".to_string()),+ content: Vec::new(),+ },+ started_at_ms: Some(0),+ completed_at_ms: Some(1),+ },+ ThreadItemEntry {+ turn_id: "turn-1".to_string(),+ item: ThreadItem::AgentMessage {+ id: "agent-1".to_string(),+ text: "first".to_string(),+ phase: None,+ memory_citation: None,+ delivery: None,+ questions: None,+ },+ started_at_ms: Some(0),+ completed_at_ms: Some(1),+ },+ ]+ );let turn_start_id = mcp.send_turn_start_request(TurnStartParams {@@ -2244,7 +2288,7 @@ async fn paginated_history_lists_and_legacy_reads_use_projected_turns_and_items(}#[tokio::test]-async fn thread_items_list_returns_unsupported() -> Result<()> {+async fn thread_items_read_validates_ids_before_history_access() -> Result<()> {let server = create_mock_responses_server_repeating_assistant("Done").await;let codex_home = TempDir::new()?;MockResponsesConfig::new(&server.uri()).write(codex_home.path())?;@@ -2276,6 +2320,43 @@ async fn thread_items_list_returns_unsupported() -> Result<()> {"thread/items/list is not supported yet");+ let read = ThreadItemsReadParams {+ thread_id: "00000000-0000-4000-8000-000000000123".to_string(),+ item_ids: vec!["item".to_string()],+ turn_id: "turn".to_string(),+ };+ for item_ids in [+ Vec::new(),+ (0..101).map(|index| index.to_string()).collect(),+ ] {+ let id = mcp+ .send_thread_items_read_request(ThreadItemsReadParams {+ item_ids,+ ..read.clone()+ })+ .await?;+ let error: JSONRPCError = timeout(+ DEFAULT_READ_TIMEOUT,+ mcp.read_stream_until_error_message(RequestId::Integer(id)),+ )+ .await??;+ assert_eq!(error.error.code, -32600);+ assert_eq!(error.error.message, "itemIds must contain 1 to 100 IDs");+ }++ let max_read_id = mcp+ .send_thread_items_read_request(ThreadItemsReadParams {+ item_ids: (0..100).map(|index| index.to_string()).collect(),+ ..read+ })+ .await?;+ let max_read_error: JSONRPCError = timeout(+ DEFAULT_READ_TIMEOUT,+ mcp.read_stream_until_error_message(RequestId::Integer(max_read_id)),+ )+ .await??;+ assert_eq!(max_read_error.error.code, -32601);+Ok(())}diff --git a/codex-rs/thread-store/src/in_memory.rs b/codex-rs/thread-store/src/in_memory.rsindex 898e6fdfde..568596f675 100644--- a/codex-rs/thread-store/src/in_memory.rs+++ b/codex-rs/thread-store/src/in_memory.rs@@ -128,6 +128,7 @@ mod tests {let items_err = store.list_items(ListItemsParams {+ item_ids: None,thread_id,turn_id: None,include_archived: true,diff --git a/codex-rs/thread-store/src/local/rollout_migration_tests.rs b/codex-rs/thread-store/src/local/rollout_migration_tests.rsindex 61d8a6ae44..043ed572ea 100644--- a/codex-rs/thread-store/src/local/rollout_migration_tests.rs+++ b/codex-rs/thread-store/src/local/rollout_migration_tests.rs@@ -473,6 +473,7 @@ async fn migration_projects_explicit_and_implicit_legacy_completed_items() {assert_eq!(turns.turns[0].turn_id, "explicit");let items = store.list_items(ListItemsParams {+ item_ids: None,thread_id,turn_id: None,include_archived: false,@@ -625,6 +626,7 @@ async fn migration_keeps_late_completions_in_their_original_turn() {let items = store.list_items(ListItemsParams {+ item_ids: None,thread_id,turn_id: None,include_archived: false,@@ -1105,6 +1107,7 @@ async fn migration_keeps_late_completions_for_surviving_turns_across_rollback());let items = store.list_items(ListItemsParams {+ item_ids: None,thread_id,turn_id: None,include_archived: false,diff --git a/codex-rs/thread-store/src/local/thread_history/read.rs b/codex-rs/thread-store/src/local/thread_history/read.rsindex bbfe61fac2..5876992d3c 100644--- a/codex-rs/thread-store/src/local/thread_history/read.rs+++ b/codex-rs/thread-store/src/local/thread_history/read.rs@@ -162,7 +162,7 @@ pub(in crate::local) async fn list_turns(pub(in crate::local) async fn list_items(store: &LocalThreadStore,- params: ListItemsParams,+ mut params: ListItemsParams,) -> ThreadStoreResult<ItemPage> {validate_thread_for_paginated_reads(store,@@ -171,6 +171,21 @@ pub(in crate::local) async fn list_items("list_items",).await?;+ if let Some(ids) = ¶ms.item_ids {+ if params.turn_id.is_none()+ || params.position.is_some()+ || params.after_updated_at_ordinal.is_some()+ || params.sort_key != crate::ItemSortKey::CreatedAtOrdinal+ || !(1..=100).contains(&ids.len())+ {+ return Err(ThreadStoreError::InvalidRequest {+ message: "itemIds requires turnId, 1 to 100 IDs, and no cursor or update replay"+ .to_string(),+ });+ }+ params.page_size = ids.len();+ params.sort_direction = crate::SortDirection::Asc;+ }validate_page_size(params.page_size)?;let lineage = store.resolve_rollout_lineage(params.thread_id, /*initial_path*/ None)diff --git a/codex-rs/thread-store/src/local/thread_history/read_tests.rs b/codex-rs/thread-store/src/local/thread_history/read_tests.rsindex fb8ca3ee0c..116b5866d6 100644--- a/codex-rs/thread-store/src/local/thread_history/read_tests.rs+++ b/codex-rs/thread-store/src/local/thread_history/read_tests.rs@@ -1193,6 +1193,24 @@ async fn lineage_reads_page_across_parent_and_child_segments() {matches!(store.list_items(anchored).await, Err(ThreadStoreError::InvalidRequest { message }) if message == "cursor.itemId does not identify an item in the requested history scope"));+ let inherited_lookup =+ item_lookup_params(child_id, "root-1", &["root-agent", "root-user", "missing"]);+ let inherited_lookup = store+ .list_items(inherited_lookup)+ .await+ .expect("lookup inherited items");+ assert_eq!(item_ids(&inherited_lookup), vec!["root-user", "root-agent"]);++ let excluded_lookup = item_lookup_params(child_id, "excluded-root", &["excluded-item"]);+ assert!(+ store+ .list_items(excluded_lookup)+ .await+ .expect("exclude source item after fork cutoff")+ .items+ .is_empty()+ );+for sort_key in [ItemSortKey::CreatedAtOrdinal, ItemSortKey::UpdatedAtOrdinal] {let error = store.list_items(ListItemsParams {@@ -1712,6 +1730,7 @@ fn item_params(sort_direction: SortDirection,) -> ListItemsParams {ListItemsParams {+ item_ids: None,thread_id,turn_id: turn_id.map(str::to_owned),include_archived: false,@@ -1737,6 +1756,19 @@ fn updated_item_params(thread_id: ThreadId, after_updated_at_ordinal: u64) -> Li}}+fn item_lookup_params(thread_id: ThreadId, turn_id: &str, item_ids: &[&str]) -> ListItemsParams {+ ListItemsParams {+ item_ids: Some(item_ids.iter().map(ToString::to_string).collect()),+ ..item_params(+ thread_id,+ Some(turn_id),+ /*cursor*/ None,+ item_ids.len(),+ SortDirection::Asc,+ )+ }+}+fn expected_item(turn_id: &str, item_id: &str, rollout_ordinal: u64) -> StoredThreadItem {StoredThreadItem {turn_id: turn_id.to_string(),diff --git a/codex-rs/thread-store/src/local/thread_history/segment_paging.rs b/codex-rs/thread-store/src/local/thread_history/segment_paging.rsindex a87542bf89..7c647c4dcb 100644--- a/codex-rs/thread-store/src/local/thread_history/segment_paging.rs+++ b/codex-rs/thread-store/src/local/thread_history/segment_paging.rs@@ -306,6 +306,14 @@ WHERE thread_id =if let Some(turn_id) = params.turn_id.as_deref() {query.push(" AND turn_id = ").push_bind(turn_id);}+ if let Some(item_ids) = params.item_ids.as_deref() {+ query.push(" AND item_id IN (");+ let mut ids = query.separated(", ");+ for item_id in item_ids {+ ids.push_bind(item_id);+ }+ ids.push_unseparated(")");+ }push_cursor_clause(&mut query, params.sort_direction, segment_cursor)?;push_order_and_limit(&mut query, params.sort_direction, remaining);rows.extend(diff --git a/codex-rs/thread-store/src/types.rs b/codex-rs/thread-store/src/types.rsindex 1dd5b4e760..5b3dea3551 100644--- a/codex-rs/thread-store/src/types.rs+++ b/codex-rs/thread-store/src/types.rs@@ -494,6 +494,8 @@ pub enum ListItemsPosition {/// Parameters for listing persisted items within a thread.#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]pub struct ListItemsParams {+ /// Exact item lookup scoped to `turn_id`; incompatible with cursors and update replay.+ pub item_ids: Option<Vec<String>>,/// Thread id to read.pub thread_id: ThreadId,/// Optional turn id to filter by. When omitted, returns items across the thread.