Lightweight coding agent that runs in your terminal
Rust
Distinguish retryable thread-store errors from unknown write outcomes (#54664)
Tom96eb400d1231
diff --git a/codex-rs/app-server/src/request_processors/thread_attachments.rs b/codex-rs/app-server/src/request_processors/thread_attachments.rsindex 2cdaaeca65..40d8850897 100644--- a/codex-rs/app-server/src/request_processors/thread_attachments.rs+++ b/codex-rs/app-server/src/request_processors/thread_attachments.rs@@ -284,7 +284,10 @@ fn thread_attachment_store_error(ThreadStoreError::ThreadNotFound { thread_id } => {invalid_params(format!("thread not found: {thread_id}"))}- error @ (ThreadStoreError::Conflict { .. } | ThreadStoreError::Internal { .. }) => {+ error @ (ThreadStoreError::Conflict { .. }+ | ThreadStoreError::Retryable { .. }+ | ThreadStoreError::OutcomeUnknown { .. }+ | ThreadStoreError::Internal { .. }) => {internal_error(format!("failed to process {operation}: {error}"))}}diff --git a/codex-rs/app-server/src/request_processors/thread_processor_tests.rs b/codex-rs/app-server/src/request_processors/thread_processor_tests.rsindex f1bd1bfe92..a42e06dc9d 100644--- a/codex-rs/app-server/src/request_processors/thread_processor_tests.rs+++ b/codex-rs/app-server/src/request_processors/thread_processor_tests.rs@@ -1,3 +1,44 @@+use codex_app_server_protocol::JSONRPCErrorError;+use codex_thread_store::ThreadStoreError;+use pretty_assertions::assert_eq;++#[test]+fn storage_failure_classification_does_not_change_mutation_error_policy() {+ for error in [+ ThreadStoreError::Internal {+ message: "retryable conflict; outcome unknown".to_owned(),+ },+ ThreadStoreError::Retryable {+ message: "store temporarily unavailable".to_owned(),+ },+ ThreadStoreError::OutcomeUnknown {+ message: "connection lost after write".to_owned(),+ },+ ] {+ let mapped = super::thread_store_mutation_error("archive", error.clone());+ let expected = JSONRPCErrorError {+ code: -32603,+ message: format!("failed to archive session: {error}"),+ data: None,+ };+ assert_eq!(mapped, expected);+ }++ assert_eq!(+ super::thread_store_mutation_error(+ "archive",+ ThreadStoreError::Conflict {+ message: "writer already active".to_owned(),+ },+ ),+ JSONRPCErrorError {+ code: -32600,+ message: "writer already active".to_owned(),+ data: None,+ },+ );+}+mod thread_list_cwd_filter_tests {use super::super::normalize_thread_list_cwd_filters;use codex_app_server_protocol::ThreadListCwdFilter;diff --git a/codex-rs/app-server/src/request_processors/thread_sections.rs b/codex-rs/app-server/src/request_processors/thread_sections.rsindex 6491b3bc78..31f5b3f7e4 100644--- a/codex-rs/app-server/src/request_processors/thread_sections.rs+++ b/codex-rs/app-server/src/request_processors/thread_sections.rs@@ -224,6 +224,8 @@ fn thread_section_store_error(ThreadStoreError::InvalidRequest { message } => invalid_params(message),error @ (ThreadStoreError::ThreadNotFound { .. }| ThreadStoreError::Conflict { .. }+ | ThreadStoreError::Retryable { .. }+ | ThreadStoreError::OutcomeUnknown { .. }| ThreadStoreError::Internal { .. }) => {let action = operation.strip_prefix("threadSection/")diff --git a/codex-rs/core/src/agent/control/runtime_tests.rs b/codex-rs/core/src/agent/control/runtime_tests.rsindex 2884575ab3..2fc7e07108 100644--- a/codex-rs/core/src/agent/control/runtime_tests.rs+++ b/codex-rs/core/src/agent/control/runtime_tests.rs@@ -91,13 +91,22 @@ async fn report_display_includes_safe_cause_without_raw_error_payload() {.expect("teardown should be admitted").into_teardown_guard("session_startup", Some(thread_id));let raw_payload = "sensitive thread-store error payload";- let error = ThreadStoreError::Internal {- message: raw_payload.to_owned(),- };- teardown.record_shutdown_failure(- "discard_persistence",- crate::thread_manager::thread_store_error_kind(&error),- );+ for error in [+ ThreadStoreError::Internal {+ message: raw_payload.to_owned(),+ },+ ThreadStoreError::Retryable {+ message: raw_payload.to_owned(),+ },+ ThreadStoreError::OutcomeUnknown {+ message: raw_payload.to_owned(),+ },+ ] {+ teardown.record_shutdown_failure(+ "discard_persistence",+ crate::thread_manager::thread_store_error_kind(&error),+ );+ }let shutdown = runtime.request_shutdown();teardown.complete();@@ -109,7 +118,7 @@ async fn report_display_includes_safe_cause_without_raw_error_payload() {assert_eq!(displayed,format!(- "agent tree shutdown did not complete cleanly: tree_id={}, failures=[{{operation=session_startup, phase=discard_persistence, thread_id={thread_id}, reason=operation_failed, error_kind=thread_store_internal}}]; omitted_failures=0",+ "agent tree shutdown did not complete cleanly: tree_id={}, failures=[{{operation=session_startup, phase=discard_persistence, thread_id={thread_id}, reason=operation_failed, error_kind=thread_store_internal}}, {{operation=session_startup, phase=discard_persistence, thread_id={thread_id}, reason=operation_failed, error_kind=thread_store_retryable}}, {{operation=session_startup, phase=discard_persistence, thread_id={thread_id}, reason=operation_failed, error_kind=thread_store_outcome_unknown}}]; omitted_failures=0",report.tree_id,));diff --git a/codex-rs/core/src/session_rollout_init_error.rs b/codex-rs/core/src/session_rollout_init_error.rsindex 7e62462add..68581e217d 100644--- a/codex-rs/core/src/session_rollout_init_error.rs+++ b/codex-rs/core/src/session_rollout_init_error.rs@@ -19,6 +19,8 @@ pub(crate) fn map_session_init_error(err: &anyhow::Error, codex_home: &Path) ->}ThreadStoreError::ThreadNotFound { .. }| ThreadStoreError::InvalidRequest { .. }+ | ThreadStoreError::Retryable { .. }+ | ThreadStoreError::OutcomeUnknown { .. }| ThreadStoreError::Internal { .. } => {}}}@@ -65,3 +67,7 @@ fn map_rollout_io_error(io_err: &std::io::Error, codex_home: &Path) -> Option<Co"{hint} (underlying error: {io_err})")))}++#[cfg(test)]+#[path = "session_rollout_init_error_tests.rs"]+mod tests;diff --git a/codex-rs/core/src/session_rollout_init_error_tests.rs b/codex-rs/core/src/session_rollout_init_error_tests.rsnew file mode 100644index 0000000000..f49993e5d5--- /dev/null+++ b/codex-rs/core/src/session_rollout_init_error_tests.rs@@ -0,0 +1,62 @@+//! Checks that storage classifications retain the existing session startup failure policy.++use super::map_session_init_error;+use codex_protocol::ThreadId;+use codex_protocol::error::CodexErrorDetails;+use codex_thread_store::ThreadStoreError;+use pretty_assertions::assert_eq;+use std::path::Path;++#[test]+fn storage_failures_remain_fatal_during_session_initialization() {+ for error in [+ ThreadStoreError::ThreadNotFound {+ thread_id: ThreadId::new(),+ },+ ThreadStoreError::InvalidRequest {+ message: "invalid request".to_owned(),+ },+ ThreadStoreError::Internal {+ message: "retryable conflict; outcome unknown".to_owned(),+ },+ ThreadStoreError::Retryable {+ message: "store temporarily unavailable".to_owned(),+ },+ ThreadStoreError::OutcomeUnknown {+ message: "connection lost after write".to_owned(),+ },+ ] {+ let wrapped = anyhow::Error::new(error.clone()).context("opening persistence");+ let mapped = map_session_init_error(&wrapped, Path::new("codex-home"));+ let CodexErrorDetails::Fatal(message) = mapped.details() else {+ panic!("storage failure must remain fatal during startup: {mapped}");+ };+ assert_eq!(+ message,+ &format!("Failed to initialize session: opening persistence: {error}")+ );+ }+}++#[test]+fn conflict_and_unsupported_keep_their_session_initialization_categories() {+ let conflict = anyhow::Error::new(ThreadStoreError::Conflict {+ message: "writer already active".to_owned(),+ })+ .context("opening persistence");+ let mapped = map_session_init_error(&conflict, Path::new("codex-home"));+ assert!(+ matches!(mapped.details(), CodexErrorDetails::InvalidRequest(message)+ if message == "writer already active")+ );++ let unsupported = anyhow::Error::new(ThreadStoreError::Unsupported {+ operation: "create_thread",+ })+ .context("opening persistence");+ let mapped = map_session_init_error(&unsupported, Path::new("codex-home"));+ assert!(+ matches!(mapped.details(), CodexErrorDetails::UnsupportedOperation(message)+ if message == "create_thread is not supported yet")+ );+}diff --git a/codex-rs/core/src/thread_manager/shutdown.rs b/codex-rs/core/src/thread_manager/shutdown.rsindex cfa4af1ca6..e622f41024 100644--- a/codex-rs/core/src/thread_manager/shutdown.rs+++ b/codex-rs/core/src/thread_manager/shutdown.rs@@ -17,6 +17,8 @@ pub(crate) fn thread_store_error_kind(error: &ThreadStoreError) -> &'static strThreadStoreError::InvalidRequest { .. } => "thread_store_invalid_request",ThreadStoreError::Conflict { .. } => "thread_store_conflict",ThreadStoreError::Unsupported { .. } => "thread_store_unsupported",+ ThreadStoreError::Retryable { .. } => "thread_store_retryable",+ ThreadStoreError::OutcomeUnknown { .. } => "thread_store_outcome_unknown",ThreadStoreError::Internal { .. } => "thread_store_internal",}}diff --git a/codex-rs/thread-store/src/error.rs b/codex-rs/thread-store/src/error.rsindex bc5e8ed7c4..d0ab6d8826 100644--- a/codex-rs/thread-store/src/error.rs+++ b/codex-rs/thread-store/src/error.rs@@ -16,7 +16,11 @@ pub(crate) fn reject_paginated_history_mode(}/// Error type shared by thread-store implementations.-#[derive(Debug, thiserror::Error)]+///+/// Implementations must explicitly distinguish known transient failures from writes whose+/// outcome is unknown. These categories carry information only: the operation owner decides+/// whether and how to recover, and no variant automatically triggers a retry.+#[derive(Clone, Debug, thiserror::Error)]pub enum ThreadStoreError {/// The requested thread does not exist in this store.#[error("thread {thread_id} not found")]@@ -32,7 +36,7 @@ pub enum ThreadStoreError {message: String,},- /// The operation conflicted with current store state.+ /// The operation conflicted with current store state. This alone does not imply retryability.#[error("thread-store conflict: {message}")]Conflict {/// User-facing explanation of the conflict.@@ -46,10 +50,37 @@ pub enum ThreadStoreError {operation: &'static str,},+ /// A transient failure for which retrying the operation is safe.+ ///+ /// For a write, the implementation must know the failed attempt did not commit. Otherwise+ /// use [`Self::OutcomeUnknown`]. Retry scheduling and limits belong to the operation owner.+ #[error("thread-store retryable error: {message}")]+ Retryable {+ /// User-facing explanation of the transient failure.+ message: String,+ },++ /// A write failed to report a definitive outcome and may already have committed.+ ///+ /// The operation owner must reconcile the stored state or use an idempotent replay strategy+ /// before retrying. This must not be treated as an ordinary retryable failure.+ #[error("thread-store write outcome unknown: {message}")]+ OutcomeUnknown {+ /// User-facing explanation of why the write outcome is uncertain.+ message: String,+ },+/// Catch-all for implementation failures that do not fit a more specific category.+ ///+ /// This includes unclassified failures: callers must not infer retryability or whether a+ /// write committed from this variant or its message.#[error("thread-store internal error: {message}")]Internal {/// User-facing explanation of the implementation failure.message: String,},}++#[cfg(test)]+#[path = "error_tests.rs"]+mod tests;diff --git a/codex-rs/thread-store/src/error_tests.rs b/codex-rs/thread-store/src/error_tests.rsnew file mode 100644index 0000000000..4b56fa89bc--- /dev/null+++ b/codex-rs/thread-store/src/error_tests.rs@@ -0,0 +1,23 @@+//! Verifies conservative classification at the shared storage error boundary.++use super::ThreadStoreError;+use pretty_assertions::assert_eq;++#[test]+fn unclassified_sqlx_failures_remain_internal() {+ for error in [+ sqlx::Error::PoolTimedOut,+ sqlx::Error::Io(std::io::Error::new(+ std::io::ErrorKind::ConnectionReset,+ "connection lost after write",+ )),+ sqlx::Error::Protocol("retryable conflict; outcome unknown".to_owned()),+ ] {+ let expected = format!("failed to access thread history: {error}");+ let error = ThreadStoreError::from(error);+ let ThreadStoreError::Internal { message } = error else {+ panic!("unclassified SQLx failure must remain internal: {error:?}");+ };+ assert_eq!(message, expected);+ }+}