Skip to content

armgit / codex

Public Imported from GitHub
0

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.zst
index f409b73b9d..79aaee89b1 100644
Binary 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 differ
diff --git a/codex-rs/app-server-protocol/src/protocol/common.rs b/codex-rs/app-server-protocol/src/protocol/common.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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(&params.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.rs
index 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.rs
index 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() -> Resu
Ok(())
}
+#[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.rs
index 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.rs
index 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.rs
index 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.rs
index 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) = &params.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.rs
index 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.rs
index 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.rs
index 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.