Lightweight coding agent that runs in your terminal
Rust
Expose experimental durable thread read state in the app server (#52350)
Brent Traut0ada5d8806cd
diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.jsonindex bc34bb89dd..01986e2001 100644--- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json+++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json@@ -23435,6 +23435,28 @@"title": "ThreadReadResponse","type": "object"},+ "ThreadReadState": {+ "description": "The first unread position in a durable local thread. A null position means read. The opaque revision guards edits against activity or marks the caller has not seen.",+ "properties": {+ "firstUnread": {+ "anyOf": [+ {+ "$ref": "#/definitions/v2/ThreadUnreadPosition"+ },+ {+ "type": "null"+ }+ ]+ },+ "revision": {+ "type": "string"+ }+ },+ "required": [+ "revision"+ ],+ "type": "object"+ },"ThreadRealtimeAudioChunk": {"description": "EXPERIMENTAL - thread realtime audio chunk.","properties": {@@ -25340,6 +25362,48 @@"title": "ThreadUnarchivedNotification","type": "object"},+ "ThreadUnreadPosition": {+ "oneOf": [+ {+ "description": "Explicitly marked unread, including when the thread has no turns.",+ "properties": {+ "type": {+ "enum": [+ "threadStart"+ ],+ "title": "ThreadStartThreadUnreadPositionType",+ "type": "string"+ }+ },+ "required": [+ "type"+ ],+ "title": "ThreadStartThreadUnreadPosition",+ "type": "object"+ },+ {+ "description": "The earliest completed result needing attention.",+ "properties": {+ "turnId": {+ "type": "string"+ },+ "type": {+ "enum": [+ "turn"+ ],+ "title": "TurnThreadUnreadPositionType",+ "type": "string"+ }+ },+ "required": [+ "turnId",+ "type"+ ],+ "title": "TurnThreadUnreadPosition",+ "type": "object"+ }+ ]+ },"ThreadUnsubscribeParams": {"$schema": "http://json-schema.org/draft-07/schema#","properties": {diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.jsonindex 61aac9999f..95ffa2fe63 100644--- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json+++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json@@ -21149,6 +21149,28 @@"title": "ThreadReadResponse","type": "object"},+ "ThreadReadState": {+ "description": "The first unread position in a durable local thread. A null position means read. The opaque revision guards edits against activity or marks the caller has not seen.",+ "properties": {+ "firstUnread": {+ "anyOf": [+ {+ "$ref": "#/definitions/ThreadUnreadPosition"+ },+ {+ "type": "null"+ }+ ]+ },+ "revision": {+ "type": "string"+ }+ },+ "required": [+ "revision"+ ],+ "type": "object"+ },"ThreadRealtimeAudioChunk": {"description": "EXPERIMENTAL - thread realtime audio chunk.","properties": {@@ -23054,6 +23076,48 @@"title": "ThreadUnarchivedNotification","type": "object"},+ "ThreadUnreadPosition": {+ "oneOf": [+ {+ "description": "Explicitly marked unread, including when the thread has no turns.",+ "properties": {+ "type": {+ "enum": [+ "threadStart"+ ],+ "title": "ThreadStartThreadUnreadPositionType",+ "type": "string"+ }+ },+ "required": [+ "type"+ ],+ "title": "ThreadStartThreadUnreadPosition",+ "type": "object"+ },+ {+ "description": "The earliest completed result needing attention.",+ "properties": {+ "turnId": {+ "type": "string"+ },+ "type": {+ "enum": [+ "turn"+ ],+ "title": "TurnThreadUnreadPositionType",+ "type": "string"+ }+ },+ "required": [+ "turnId",+ "type"+ ],+ "title": "TurnThreadUnreadPosition",+ "type": "object"+ }+ ]+ },"ThreadUnsubscribeParams": {"$schema": "http://json-schema.org/draft-07/schema#","properties": {diff --git a/codex-rs/app-server-protocol/schema/json/v2/ThreadListResponse.json b/codex-rs/app-server-protocol/schema/json/v2/ThreadListResponse.jsonindex ab43908fbe..bbf8ed7d34 100644--- a/codex-rs/app-server-protocol/schema/json/v2/ThreadListResponse.json+++ b/codex-rs/app-server-protocol/schema/json/v2/ThreadListResponse.json@@ -2262,6 +2262,28 @@}]},+ "ThreadReadState": {+ "description": "The first unread position in a durable local thread. A null position means read. The opaque revision guards edits against activity or marks the caller has not seen.",+ "properties": {+ "firstUnread": {+ "anyOf": [+ {+ "$ref": "#/definitions/ThreadUnreadPosition"+ },+ {+ "type": "null"+ }+ ]+ },+ "revision": {+ "type": "string"+ }+ },+ "required": [+ "revision"+ ],+ "type": "object"+ },"ThreadSection": {"description": "An independently persisted, user-visible thread section.","properties": {@@ -2388,6 +2410,48 @@}]},+ "ThreadUnreadPosition": {+ "oneOf": [+ {+ "description": "Explicitly marked unread, including when the thread has no turns.",+ "properties": {+ "type": {+ "enum": [+ "threadStart"+ ],+ "title": "ThreadStartThreadUnreadPositionType",+ "type": "string"+ }+ },+ "required": [+ "type"+ ],+ "title": "ThreadStartThreadUnreadPosition",+ "type": "object"+ },+ {+ "description": "The earliest completed result needing attention.",+ "properties": {+ "turnId": {+ "type": "string"+ },+ "type": {+ "enum": [+ "turn"+ ],+ "title": "TurnThreadUnreadPositionType",+ "type": "string"+ }+ },+ "required": [+ "turnId",+ "type"+ ],+ "title": "TurnThreadUnreadPosition",+ "type": "object"+ }+ ]+ },"Turn": {"properties": {"completedAt": {diff --git a/codex-rs/app-server-protocol/schema/json/v2/ThreadReadResponse.json b/codex-rs/app-server-protocol/schema/json/v2/ThreadReadResponse.jsonindex d824e57036..9c4975d2ba 100644--- a/codex-rs/app-server-protocol/schema/json/v2/ThreadReadResponse.json+++ b/codex-rs/app-server-protocol/schema/json/v2/ThreadReadResponse.json@@ -2262,6 +2262,28 @@}]},+ "ThreadReadState": {+ "description": "The first unread position in a durable local thread. A null position means read. The opaque revision guards edits against activity or marks the caller has not seen.",+ "properties": {+ "firstUnread": {+ "anyOf": [+ {+ "$ref": "#/definitions/ThreadUnreadPosition"+ },+ {+ "type": "null"+ }+ ]+ },+ "revision": {+ "type": "string"+ }+ },+ "required": [+ "revision"+ ],+ "type": "object"+ },"ThreadSection": {"description": "An independently persisted, user-visible thread section.","properties": {@@ -2388,6 +2410,48 @@}]},+ "ThreadUnreadPosition": {+ "oneOf": [+ {+ "description": "Explicitly marked unread, including when the thread has no turns.",+ "properties": {+ "type": {+ "enum": [+ "threadStart"+ ],+ "title": "ThreadStartThreadUnreadPositionType",+ "type": "string"+ }+ },+ "required": [+ "type"+ ],+ "title": "ThreadStartThreadUnreadPosition",+ "type": "object"+ },+ {+ "description": "The earliest completed result needing attention.",+ "properties": {+ "turnId": {+ "type": "string"+ },+ "type": {+ "enum": [+ "turn"+ ],+ "title": "TurnThreadUnreadPositionType",+ "type": "string"+ }+ },+ "required": [+ "turnId",+ "type"+ ],+ "title": "TurnThreadUnreadPosition",+ "type": "object"+ }+ ]+ },"Turn": {"properties": {"completedAt": {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 c9b39369e9..2571775b78 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/schema/precomputed/app-server-exports-stable.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zstindex 6644afa894..9e9b36b47c 100644Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst differdiff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadListResponse.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadListResponse.tsindex 51757e24c3..71a34fdb34 100644--- a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadListResponse.ts+++ b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadListResponse.ts@@ -3,16 +3,14 @@// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.import type { Thread } from "./Thread";-export type ThreadListResponse = { data: Array<Thread>,-/**+export type ThreadListResponse = {data: Array<Thread>, /*** Opaque cursor to pass to the next call to continue after the last item.* if None, there are no more items to return.*/-nextCursor: string | null,-/**+nextCursor: string | null, /*** Opaque cursor to pass as `cursor` when reversing `sortDirection`.* This is only populated when the page contains at least one thread.* Use it with the opposite `sortDirection`; for timestamp sorts it anchors* at the start of the page timestamp so same-second updates are not skipped.*/-backwardsCursor: string | null, };+backwardsCursor: string | null};diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadReadResponse.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadReadResponse.tsindex a6da50649c..e3ecf38f5d 100644--- a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadReadResponse.ts+++ b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadReadResponse.ts@@ -3,4 +3,4 @@// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.import type { Thread } from "./Thread";-export type ThreadReadResponse = { thread: Thread, };+export type ThreadReadResponse = {thread: Thread};diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadReadState.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadReadState.tsnew file mode 100644index 0000000000..8324a78a75--- /dev/null+++ b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadReadState.ts@@ -0,0 +1,10 @@+// GENERATED CODE! DO NOT MODIFY BY HAND!++// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.+import type { ThreadUnreadPosition } from "./ThreadUnreadPosition";++/**+ * The first unread position in a durable local thread. A null position means read.+ * The opaque revision guards edits against activity or marks the caller has not seen.+ */+export type ThreadReadState = { firstUnread: ThreadUnreadPosition | null, revision: string, };diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ThreadUnreadPosition.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadUnreadPosition.tsnew file mode 100644index 0000000000..da5d8b24dc--- /dev/null+++ b/codex-rs/app-server-protocol/schema/typescript/v2/ThreadUnreadPosition.ts@@ -0,0 +1,5 @@+// GENERATED CODE! DO NOT MODIFY BY HAND!++// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.++export type ThreadUnreadPosition = { "type": "threadStart" } | { "type": "turn", turnId: string, };diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/index.ts b/codex-rs/app-server-protocol/schema/typescript/v2/index.tsindex a90d0548a3..acc4e3c9e8 100644--- a/codex-rs/app-server-protocol/schema/typescript/v2/index.ts+++ b/codex-rs/app-server-protocol/schema/typescript/v2/index.ts@@ -539,6 +539,7 @@ export type { ThreadProjectUpdatedNotification } from "./ThreadProjectUpdatedNotexport type { ThreadQueueChangedNotification } from "./ThreadQueueChangedNotification";export type { ThreadReadParams } from "./ThreadReadParams";export type { ThreadReadResponse } from "./ThreadReadResponse";+export type { ThreadReadState } from "./ThreadReadState";export type { ThreadRealtimeAudioChunk } from "./ThreadRealtimeAudioChunk";export type { ThreadRealtimeBemItemPresentation } from "./ThreadRealtimeBemItemPresentation";export type { ThreadRealtimeClosedNotification } from "./ThreadRealtimeClosedNotification";@@ -600,6 +601,7 @@ export type { ThreadTurnsListResponse } from "./ThreadTurnsListResponse";export type { ThreadUnarchiveParams } from "./ThreadUnarchiveParams";export type { ThreadUnarchiveResponse } from "./ThreadUnarchiveResponse";export type { ThreadUnarchivedNotification } from "./ThreadUnarchivedNotification";+export type { ThreadUnreadPosition } from "./ThreadUnreadPosition";export type { ThreadUnsubscribeParams } from "./ThreadUnsubscribeParams";export type { ThreadUnsubscribeResponse } from "./ThreadUnsubscribeResponse";export type { ThreadUnsubscribeStatus } from "./ThreadUnsubscribeStatus";diff --git a/codex-rs/app-server-protocol/src/protocol/v2/thread.rs b/codex-rs/app-server-protocol/src/protocol/v2/thread.rsindex 120bf66ff9..609e266a07 100644--- a/codex-rs/app-server-protocol/src/protocol/v2/thread.rs+++ b/codex-rs/app-server-protocol/src/protocol/v2/thread.rs@@ -1559,11 +1559,15 @@ pub enum SortDirection {Desc,}-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS, ExperimentalApi)]#[serde(rename_all = "camelCase")]#[ts(export_to = "v2/")]pub struct ThreadListResponse {pub data: Vec<Thread>,+ /// Local receipts for eligible threads on this page, keyed by thread ID.+ /// Null means durable read state is unavailable; an absent key means that row is ineligible.+ #[experimental("thread/list.readStates")]+ pub read_states: Option<HashMap<String, ThreadReadState>>,/// Opaque cursor to pass to the next call to continue after the last item./// if None, there are no more items to return.pub next_cursor: Option<String>,@@ -1708,11 +1712,14 @@ pub struct ThreadReadParams {pub include_turns: bool,}-#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS, ExperimentalApi)]#[serde(rename_all = "camelCase")]#[ts(export_to = "v2/")]pub struct ThreadReadResponse {pub thread: Thread,+ /// Local receipt. Null means this thread's durable read state is unavailable.+ #[experimental("thread/read.readState")]+ pub read_state: Option<ThreadReadState>,}#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]@@ -2011,6 +2018,30 @@ pub struct ThreadStatusChangedNotification {pub status: ThreadStatus,}+/// The first unread position in a durable local thread. A null position means read.+/// The opaque revision guards edits against activity or marks the caller has not seen.+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]+#[serde(rename_all = "camelCase")]+#[ts(export_to = "v2/")]+pub struct ThreadReadState {+ pub first_unread: Option<ThreadUnreadPosition>,+ pub revision: String,+}++#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]+#[serde(tag = "type", rename_all = "camelCase")]+#[ts(tag = "type", rename_all = "camelCase", export_to = "v2/")]+pub enum ThreadUnreadPosition {+ /// Explicitly marked unread, including when the thread has no turns.+ ThreadStart,+ /// The earliest completed result needing attention.+ Turn {+ #[serde(rename = "turnId")]+ #[ts(rename = "turnId")]+ turn_id: String,+ },+}+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]#[serde(rename_all = "camelCase")]#[ts(export_to = "v2/")]diff --git a/codex-rs/app-server/README.md b/codex-rs/app-server/README.mdindex 1852530983..b88d0c87ff 100644--- a/codex-rs/app-server/README.md+++ b/codex-rs/app-server/README.md@@ -19,6 +19,29 @@ These errors are not evidence that history is exhausted; callers can retry.A successful response with `nextCursor: null` still indicates exhaustion.Default scan-and-repair requests retain their filesystem fallback.+# Thread read state (experimental)++Local durable ordinary user threads expose a `readState` on the+`thread/read` response. `thread/list` returns `readStates`, a map from eligible+thread IDs on the returned page to their receipts. Null (or absent on older servers)+means durable read state is unavailable; a missing map entry means that row is+ineligible. Ephemeral, not-yet-persisted, service and product-owned threads are+ineligible. Shared `Thread` objects, including search and lifecycle responses,+carry no receipts. After start, resume or fork, refresh with `thread/read`.+Each local thread has one receipt, with the same storage ownership as the thread.++A read state is `{firstUnread, revision}`. `firstUnread` is null when read,+`{type:"threadStart"}` for an explicit unread mark (even for an empty thread),+or `{type:"turn", turnId}` for the earliest eligible completed result.+`revision` is an opaque string, scoped to this thread.++Only newly delivered, durable, visible terminal results advance read state,+before `turn/completed`. Every new result changes the revision, even when an+older turn remains the first unread position. Reverting a paginated thread+clears a removed position; explicit thread-start marks survive. Loading snapshots+never acknowledges activity; empty threads start read and forked history does+not publish inherited turns as new results.+# Guardian circuit-breaker errorsSet `auto_review.circuit_break_action = "strict"` to include `TooManyDenials` indiff --git a/codex-rs/app-server/src/request_processors.rs b/codex-rs/app-server/src/request_processors.rsindex 22249329ed..0edce83c3f 100644--- a/codex-rs/app-server/src/request_processors.rs+++ b/codex-rs/app-server/src/request_processors.rs@@ -570,6 +570,7 @@ mod thread_fork_goal;mod thread_input;mod thread_processor;mod thread_queue_processor;+mod thread_read_state;mod thread_sections;mod token_usage_replay;mod turn_processor;diff --git a/codex-rs/app-server/src/request_processors/thread_lifecycle.rs b/codex-rs/app-server/src/request_processors/thread_lifecycle.rsindex 4418577ee6..2b455908cc 100644--- a/codex-rs/app-server/src/request_processors/thread_lifecycle.rs+++ b/codex-rs/app-server/src/request_processors/thread_lifecycle.rs@@ -341,10 +341,12 @@ pub(super) async fn ensure_listener_task_running(// Track the event before emitting any typed translations// so thread-local state such as raw event opt-in stays// synchronized with the conversation.- let raw_events_enabled = {+ let (raw_events_enabled, terminal_summary) = {let mut thread_state = thread_state.lock().await;thread_state.track_current_turn_event(&event.id, &event.msg);- thread_state.experimental_raw_events+ let terminal = matches!(event.msg, EventMsg::TurnComplete(_) | EventMsg::TurnAborted(_))+ .then(|| thread_state.turn_summary.clone());+ (thread_state.experimental_raw_events, terminal)};if matches!(&event.msg,@@ -362,6 +364,12 @@ pub(super) async fn ensure_listener_task_running(conversation_id,);+ // Make reads after turn/completed reflect the committed frontier.+ if let Some(summary) = terminal_summary {+ super::thread_read_state::publish(+ &event, conversation_id, &conversation, &summary,+ ).await;+ }apply_bespoke_event_handling(event.clone(),conversation_id,diff --git a/codex-rs/app-server/src/request_processors/thread_processor.rs b/codex-rs/app-server/src/request_processors/thread_processor.rsindex abc2daf877..d9ba44f647 100644--- a/codex-rs/app-server/src/request_processors/thread_processor.rs+++ b/codex-rs/app-server/src/request_processors/thread_processor.rs@@ -2218,6 +2218,53 @@ impl ThreadRequestProcessor {thread_state.lock().await.take_shutdown_drain_waiter();return Err(err);}+ // The listener is drained: even an interrupted turn is durable now. Inspect only the+ // suffix being reverted and remember the revision, not a collection of turn IDs.+ let receipt_to_retire = async {+ let Some(db) = self.state_db.as_ref() else {+ return anyhow::Ok(None);+ };+ let Some(state) = db+ .thread_read_states(&[thread_id])+ .await?+ .remove(&thread_id)+ else {+ return Ok(None);+ };+ let Some(turn_id) = state.first_unread_turn.as_ref().filter(|id| !id.is_empty()) else {+ return Ok(None);+ };+ let mut cursor = None;+ loop {+ let page = self+ .thread_store+ .list_turns(codex_thread_store::ListTurnsParams {+ thread_id,+ include_archived: false,+ cursor: cursor.clone(),+ page_size: THREAD_TURNS_MAX_LIMIT,+ sort_direction: codex_thread_store::SortDirection::Desc,+ items_view: codex_thread_store::StoredTurnItemsView::NotLoaded,+ })+ .await?;+ for turn in page.turns {+ if turn.turn_id == *turn_id {+ return Ok(Some(state.revision));+ }+ if turn.turn_id == before_turn_id {+ return Ok(None);+ }+ }+ let Some(next) = page.next_cursor else {+ return Ok(None);+ };+ if cursor.as_ref() == Some(&next) {+ anyhow::bail!("thread/revert turn cursor did not advance");+ }+ cursor = Some(next);+ }+ }+ .await;if self.thread_manager.remove_thread(&thread_id)@@ -2243,6 +2290,27 @@ impl ThreadRequestProcessor {}).await.map_err(|err| thread_store_mutation_error("revert", err));+ // Receipt lookup or update errors cannot prevent reload or misreport a committed revert.+ // A concurrent mark wins over this cleanup, even while the thread was being truncated.+ if revert_result.is_ok()+ && let Some(db) = self.state_db.as_ref()+ {+ let retirement = match receipt_to_retire {+ Ok(Some(revision)) => db+ .update_thread_read_state(+ thread_id,+ &revision,+ codex_state::ReadStateOperation::Read,+ )+ .await+ .map(|_| ()),+ Ok(None) => Ok(()),+ Err(err) => Err(err),+ };+ if let Err(err) = retirement {+ tracing::warn!("reverted history but could not update unread position: {err}")+ }+ }let response = self.reload_paginated_thread(request_id,@@ -2662,8 +2730,10 @@ impl ThreadRequestProcessor {|thread| thread,).await;+ let read_states = super::thread_read_state::snapshots(self.state_db.as_ref(), &data).await;Ok(ThreadListResponse {data,+ read_states,next_cursor,backwards_cursor,})@@ -2854,7 +2924,13 @@ impl ThreadRequestProcessor {.read_thread_view(thread_uuid, include_turns).await.map_err(thread_read_view_error)?;- Ok(ThreadReadResponse { thread })+ let read_state = super::thread_read_state::snapshots(+ self.state_db.as_ref(),+ std::slice::from_ref(&thread),+ )+ .await+ .and_then(|mut states| states.remove(&thread.id));+ Ok(ThreadReadResponse { thread, read_state })}/// Builds the API view for `thread/read` from persisted metadata plus optional live state.diff --git a/codex-rs/app-server/src/request_processors/thread_read_state.rs b/codex-rs/app-server/src/request_processors/thread_read_state.rsnew file mode 100644index 0000000000..5f3d8aeadf--- /dev/null+++ b/codex-rs/app-server/src/request_processors/thread_read_state.rs@@ -0,0 +1,122 @@+//! Read state for durable local threads returned by the thread store.++use super::*;+use codex_app_server_protocol::ThreadReadState;+use codex_app_server_protocol::ThreadUnreadPosition;++// These scopes have product notification policy the local server cannot resolve.+// Do not advertise read state for them until their policy reaches this publisher.+fn eligible(thread: &Thread) -> bool {+ !thread.ephemeral+ && !matches!(+ thread.source,+ codex_app_server_protocol::SessionSource::SubAgent(_)+ | codex_app_server_protocol::SessionSource::Unknown+ )+ && matches!(+ thread.thread_source,+ None | Some(codex_app_server_protocol::ThreadSource::User)+ )+}++fn to_api(state: codex_state::ThreadReadState) -> ThreadReadState {+ ThreadReadState {+ first_unread: state.first_unread_turn.map(|turn_id| {+ if turn_id.is_empty() {+ ThreadUnreadPosition::ThreadStart+ } else {+ ThreadUnreadPosition::Turn { turn_id }+ }+ }),+ revision: state.revision,+ }+}++/// Read receipts only for the local store's list/read results, in one bounded batch.+pub(super) async fn snapshots(+ db: Option<&StateDbHandle>,+ threads: &[Thread],+) -> Option<HashMap<String, ThreadReadState>> {+ let db = db?;+ let ids = threads+ .iter()+ .filter(|t| eligible(t))+ .filter_map(|t| ThreadId::from_string(&t.id).ok())+ .collect::<Vec<_>>();+ match db.thread_read_states(&ids).await {+ Ok(states) => Some(+ states+ .into_iter()+ .map(|(id, state)| (id.to_string(), to_api(state)))+ .collect(),+ ),+ Err(err) => {+ tracing::warn!("thread read state unavailable: {err}");+ None+ }+ }+}++/// Runs only on newly delivered Core events, never on history decoding or replay.+pub(super) async fn publish(+ event: &codex_protocol::protocol::Event,+ id: ThreadId,+ conversation: &Arc<CodexThread>,+ summary: &crate::thread_state::TurnSummary,+) -> Option<StateDbHandle> {+ let db = conversation.state_db()?;+ let config = conversation.config_snapshot().await;+ if config.ephemeral+ || matches!(+ config.session_source,+ codex_protocol::protocol::SessionSource::SubAgent(_)+ | codex_protocol::protocol::SessionSource::Internal(_)+ | codex_protocol::protocol::SessionSource::Unknown+ )+ || !matches!(+ config.thread_source,+ None | Some(codex_protocol::protocol::ThreadSource::User)+ )+ {+ return None;+ }+ let has_error = summary.last_error.is_some();+ let final_text = match &summary.last_agent_message {+ Some(ThreadItem::AgentMessage { text, .. }) => Some(text.as_str()),+ _ => None,+ };+ let visible = match &event.msg {+ EventMsg::TurnComplete(_) if has_error => true,+ EventMsg::TurnComplete(_) => {+ let text = final_text?;+ if text.contains("<decision>DONT_NOTIFY</decision>") {+ return None;+ }+ // An unfinished goal will resume automatically; it is not a terminal result.+ match db.thread_goals().get_thread_goal(id).await {+ Ok(Some(goal)) if goal.status == codex_state::ThreadGoalStatus::Active => false,+ Ok(_) => !text.trim().is_empty(),+ Err(err) => {+ tracing::warn!("could not resolve terminal attention policy: {err}");+ return None;+ }+ }+ }+ EventMsg::TurnAborted(aborted) => {+ aborted.error.is_some() || has_error || final_text.is_some()+ }+ _ => false,+ };+ if visible {+ if let Err(err) = conversation.flush_rollout().await {+ tracing::warn!("cannot publish attention before the terminal result is durable: {err}");+ return None;+ }+ match db.publish_thread_attention(id, &event.id).await {+ Ok(true) => return Some(db),+ Ok(false) => {}+ Err(err) => tracing::warn!("failed to publish terminal attention: {err}"),+ }+ }+ None+}diff --git a/codex-rs/app-server/tests/suite/v2/mod.rs b/codex-rs/app-server/tests/suite/v2/mod.rsindex 9166598de5..68167089eb 100644--- a/codex-rs/app-server/tests/suite/v2/mod.rs+++ b/codex-rs/app-server/tests/suite/v2/mod.rs@@ -149,6 +149,7 @@ mod thread_name_persistence;mod thread_name_websocket;mod thread_queue;mod thread_read;+mod thread_read_state;mod thread_resume;mod thread_revert;mod thread_sections;diff --git a/codex-rs/app-server/tests/suite/v2/rollout_migration.rs b/codex-rs/app-server/tests/suite/v2/rollout_migration.rsindex da20bdbea8..a9fb5aa9c3 100644--- a/codex-rs/app-server/tests/suite/v2/rollout_migration.rs+++ b/codex-rs/app-server/tests/suite/v2/rollout_migration.rs@@ -91,7 +91,7 @@ async fn runtime_enabled_legacy_migration_preserves_cold_resume_model_context()include_turns: false,}).await?;- let ThreadReadResponse { thread: read } = secondary.read_response(read_id).await?;+ let ThreadReadResponse { thread: read, .. } = secondary.read_response(read_id).await?;if read.history_mode == ThreadHistoryMode::Paginated {return Ok::<(), anyhow::Error>(());}diff --git a/codex-rs/app-server/tests/suite/v2/thread_archive.rs b/codex-rs/app-server/tests/suite/v2/thread_archive.rsindex b11ff57b5b..e17c4a9a0a 100644--- a/codex-rs/app-server/tests/suite/v2/thread_archive.rs+++ b/codex-rs/app-server/tests/suite/v2/thread_archive.rs@@ -353,7 +353,9 @@ async fn thread_archive_without_turns(history_mode: ThreadHistoryMode) -> Result.await??;assert_eq!(archived_notification.thread_id, thread.id);- let ThreadReadResponse { thread: archived } = mcp+ let ThreadReadResponse {+ thread: archived, ..+ } = mcp.request(|request_id| ClientRequest::ThreadRead {request_id,params: ThreadReadParams {diff --git a/codex-rs/app-server/tests/suite/v2/thread_fork.rs b/codex-rs/app-server/tests/suite/v2/thread_fork.rsindex 03835a08bd..d0c9e1a80c 100644--- a/codex-rs/app-server/tests/suite/v2/thread_fork.rs+++ b/codex-rs/app-server/tests/suite/v2/thread_fork.rs@@ -1292,6 +1292,7 @@ async fn thread_fork_can_cut_before_unfinished_stored_turn() -> Result<()> {.await?;let ThreadReadResponse {thread: source_thread,+ ..} = timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(read_id)).await??;assert_eq!(source_thread.turns.len(), 2);assert_eq!(source_thread.turns[1].id, unfinished_turn_id);diff --git a/codex-rs/app-server/tests/suite/v2/thread_list.rs b/codex-rs/app-server/tests/suite/v2/thread_list.rsindex 35dcb81241..f697f9e141 100644--- a/codex-rs/app-server/tests/suite/v2/thread_list.rs+++ b/codex-rs/app-server/tests/suite/v2/thread_list.rs@@ -1005,7 +1005,7 @@ async fn thread_search_returns_content_matches() -> Result<()> {include_turns: false,}).await?;- let ThreadReadResponse { thread } =+ let ThreadReadResponse { thread, .. } =timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(request_id)).await??;pinned_threads.push(thread);}@@ -1245,6 +1245,7 @@ async fn thread_list_db_only_errors_distinguish_unavailable_database_from_empty_page,ThreadListResponse {data: vec![],+ read_states: Some(HashMap::new()),next_cursor: None,backwards_cursor: None}diff --git a/codex-rs/app-server/tests/suite/v2/thread_read.rs b/codex-rs/app-server/tests/suite/v2/thread_read.rsindex a79255bfdb..00e65fee24 100644--- a/codex-rs/app-server/tests/suite/v2/thread_read.rs+++ b/codex-rs/app-server/tests/suite/v2/thread_read.rs@@ -291,6 +291,7 @@ async fn thread_read_preserves_file_id_and_root_from_completed_turn(.await?;let ThreadReadResponse {thread: loaded_thread,+ ..} = timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(read_id)).await??;let ThreadItem::UserMessage { content, .. } = &loaded_thread.turns[0].items[0] else {panic!("expected completed turn to start with a user message");@@ -316,6 +317,7 @@ async fn thread_read_preserves_file_id_and_root_from_completed_turn(.await?;let ThreadReadResponse {thread: restarted_thread,+ ..} = timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(read_id)).await??;let ThreadItem::UserMessage { content, .. } = &restarted_thread.turns[0].items[0] else {panic!("expected persisted turn to start with a user message");@@ -370,7 +372,7 @@ async fn paginated_stored_thread_routes_projected_turns() -> Result<()> {include_turns: false,}).await?;- let ThreadReadResponse { thread } =+ let ThreadReadResponse { thread, .. } =timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(read_id)).await??;assert_eq!(thread.history_mode, ThreadHistoryMode::Paginated);assert!(thread.turns.is_empty());@@ -1202,7 +1204,7 @@ async fn thread_read_can_return_archived_threads_by_id() -> Result<()> {include_turns: false,}).await?;- let ThreadReadResponse { thread } =+ let ThreadReadResponse { thread, .. } =timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(read_id)).await??;assert_eq!(thread.id, conversation_id);@@ -1874,6 +1876,7 @@ async fn paginated_history_lists_and_legacy_reads_use_projected_turns_and_items(.await?;let ThreadReadResponse {thread: unloaded_thread,+ ..} = timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(read_id)).await??;assert_eq!(unloaded_thread.turns, expected_full_turns);@@ -2229,6 +2232,7 @@ async fn paginated_history_lists_and_legacy_reads_use_projected_turns_and_items(.await?;let ThreadReadResponse {thread: loaded_thread,+ ..} = timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(read_id)).await??;assert_eq!(&loaded_thread.turns[..2], expected_full_turns);assert_eq!(diff --git a/codex-rs/app-server/tests/suite/v2/thread_read_state.rs b/codex-rs/app-server/tests/suite/v2/thread_read_state.rsnew file mode 100644index 0000000000..ccc01fef0b--- /dev/null+++ b/codex-rs/app-server/tests/suite/v2/thread_read_state.rs@@ -0,0 +1,121 @@+use anyhow::Context;+use anyhow::Result;+use app_test_support::MockResponsesConfig;+use app_test_support::TestAppServer;+use app_test_support::create_mock_responses_server_repeating_assistant;+use codex_app_server_protocol::ClientRequest;+use codex_app_server_protocol::ThreadHistoryMode;+use codex_app_server_protocol::ThreadListResponse;+use codex_app_server_protocol::ThreadReadParams;+use codex_app_server_protocol::ThreadReadResponse;+use codex_app_server_protocol::ThreadRevertParams;+use codex_app_server_protocol::ThreadRevertResponse;+use codex_app_server_protocol::ThreadStartParams;+use codex_app_server_protocol::TurnStartParams;+use codex_app_server_protocol::UserInput;+use codex_features::Feature;+use pretty_assertions::assert_eq;+use serde_json::json;+use tempfile::TempDir;+use tokio::time::Duration;+use tokio::time::timeout;++const TIMEOUT: Duration = Duration::from_secs(15);++#[tokio::test]+async fn read_state_tracks_terminal_activity_and_reverted_history() -> Result<()> {+ let responses = create_mock_responses_server_repeating_assistant("Ready").await;+ let codex_home = TempDir::new()?;+ MockResponsesConfig::new(&responses.uri())+ .enable_feature(Feature::Sqlite)+ .write(codex_home.path())?;+ let mut server = TestAppServer::builder()+ .with_codex_home(codex_home.path())+ .build_initialized()+ .await?;+ let started = server+ .start_thread(ThreadStartParams {+ model: Some("mock-model".into()),+ history_mode: Some(ThreadHistoryMode::Paginated),+ ..Default::default()+ })+ .await?;+ let thread_id = started.thread.id;+ let completed = timeout(+ TIMEOUT,+ server.start_turn_and_wait_for_completion(TurnStartParams {+ thread_id: thread_id.clone(),+ input: vec![UserInput::Text {+ text: "Finish this task.".into(),+ text_elements: vec![],+ }],+ ..Default::default()+ }),+ )+ .await??;+ let loaded: ThreadReadResponse = server+ .request(|request_id| ClientRequest::ThreadRead {+ request_id,+ params: ThreadReadParams {+ thread_id: thread_id.clone(),+ include_turns: false,+ },+ })+ .await?;+ let first = loaded+ .read_state+ .context("durable completed user thread should have read state")?;+ assert_eq!(+ first.first_unread,+ Some(codex_app_server_protocol::ThreadUnreadPosition::Turn {+ turn_id: completed.turn.id.clone()+ })+ );++ let reloaded: ThreadReadResponse = server+ .request(|request_id| ClientRequest::ThreadRead {+ request_id,+ params: ThreadReadParams {+ thread_id: thread_id.clone(),+ include_turns: false,+ },+ })+ .await?;+ assert_eq!(+ reloaded.read_state,+ Some(first.clone()),+ "loading a snapshot must never acknowledge the activity"+ );++ let id = server+ .send_raw_request("thread/list", Some(json!({"limit": 1})))+ .await?;+ let listed: ThreadListResponse = timeout(TIMEOUT, server.read_response(id)).await??;+ let receipts = listed.read_states.context("durable list receipts")?;+ assert_eq!(listed.data.len(), 1);+ assert_eq!(listed.data[0].id, thread_id);+ assert_eq!(receipts, [(thread_id.clone(), first.clone())].into());++ let _: ThreadRevertResponse = server+ .request(|request_id| ClientRequest::ThreadRevert {+ request_id,+ params: ThreadRevertParams {+ thread_id: thread_id.clone(),+ before_turn_id: completed.turn.id,+ },+ })+ .await?;+ let reverted: ThreadReadResponse = server+ .request(|request_id| ClientRequest::ThreadRead {+ request_id,+ params: ThreadReadParams {+ thread_id,+ include_turns: false,+ },+ })+ .await?;+ let after = reverted.read_state.context("reverted snapshot")?;+ assert_eq!(after.first_unread, None);+ assert_ne!(after.revision, first.revision);+ Ok(())+}diff --git a/codex-rs/app-server/tests/suite/v2/thread_resume.rs b/codex-rs/app-server/tests/suite/v2/thread_resume.rsindex 1413da3b7e..0c005f7dab 100644--- a/codex-rs/app-server/tests/suite/v2/thread_resume.rs+++ b/codex-rs/app-server/tests/suite/v2/thread_resume.rs@@ -1421,7 +1421,7 @@ async fn thread_resume_preserves_acknowledged_model_effort_and_approvals_revieweinclude_turns: false,}).await?;- let ThreadReadResponse { thread: read } =+ let ThreadReadResponse { thread: read, .. } =timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(read_id)).await??;assert_eq!(read.cwd.as_path(), persisted_cwd);diff --git a/codex-rs/app-server/tests/suite/v2/thread_unarchive.rs b/codex-rs/app-server/tests/suite/v2/thread_unarchive.rsindex fcc328d28b..50041ea975 100644--- a/codex-rs/app-server/tests/suite/v2/thread_unarchive.rs+++ b/codex-rs/app-server/tests/suite/v2/thread_unarchive.rs@@ -124,6 +124,7 @@ async fn thread_unarchive_moves_rollout_back_into_sessions_directory() -> Result.await?;let ThreadReadResponse {thread: pinned_thread,+ ..} = timeout(DEFAULT_READ_TIMEOUT, mcp.read_response(read_id)).await??;assert_eq!(pinned_thread.section, Some(pinned_section.clone()));let pinned_entered_at = pinned_threaddiff --git a/codex-rs/state/migrations/0060_thread_read_state.sql b/codex-rs/state/migrations/0061_thread_read_state.sqlsimilarity index 100%rename from codex-rs/state/migrations/0060_thread_read_state.sqlrename to codex-rs/state/migrations/0061_thread_read_state.sqldiff --git a/codex-rs/tui/src/app_server_session/thread_list_tests.rs b/codex-rs/tui/src/app_server_session/thread_list_tests.rsindex 7ce2c5509a..fe1ae9ee02 100644--- a/codex-rs/tui/src/app_server_session/thread_list_tests.rs+++ b/codex-rs/tui/src/app_server_session/thread_list_tests.rs@@ -65,7 +65,7 @@ async fn thread_list_preserves_filters_and_retries_only_legacy_cwd_errors() -> Rif code == 0 || retry {assert_eq!(serde_json::to_value(result?)?,- json!({"data": [], "nextCursor": "next", "backwardsCursor": null})+ json!({"data": [], "readStates": null, "nextCursor": "next", "backwardsCursor": null}));} else {assert!(format!("{:#}", result.unwrap_err()).contains(message));diff --git a/sdk/python/src/openai_codex/generated/v2_all.py b/sdk/python/src/openai_codex/generated/v2_all.pyindex 0a8d8fa442..beba74ebd6 100644--- a/sdk/python/src/openai_codex/generated/v2_all.py+++ b/sdk/python/src/openai_codex/generated/v2_all.py@@ -6297,6 +6297,28 @@ class ThreadUnarchivedNotification(BaseModel):thread_id: Annotated[str, Field(alias="threadId")]+class ThreadStartThreadUnreadPosition(BaseModel):+ model_config = ConfigDict(+ populate_by_name=True,+ )+ type: Annotated[Literal["threadStart"], Field(title="ThreadStartThreadUnreadPositionType")]+++class TurnThreadUnreadPosition(BaseModel):+ model_config = ConfigDict(+ populate_by_name=True,+ )+ turn_id: Annotated[str, Field(alias="turnId")]+ type: Annotated[Literal["turn"], Field(title="TurnThreadUnreadPositionType")]+++class ThreadUnreadPosition(RootModel[ThreadStartThreadUnreadPosition | TurnThreadUnreadPosition]):+ model_config = ConfigDict(+ populate_by_name=True,+ )+ root: ThreadStartThreadUnreadPosition | TurnThreadUnreadPosition++class ThreadUnsubscribeParams(BaseModel):model_config = ConfigDict(populate_by_name=True,@@ -10202,6 +10224,14 @@ class ThreadListParams(BaseModel):] = None+class ThreadReadState(BaseModel):+ model_config = ConfigDict(+ populate_by_name=True,+ )+ first_unread: Annotated[ThreadUnreadPosition | None, Field(alias="firstUnread")] = None+ revision: str++class TranscriptSegmentThreadRealtimeItem(BaseModel):model_config = ConfigDict(populate_by_name=True,