Expose resumable misalignment details through app server (#40952)

## Why

App-server clients need the explanation and steering instruction returned with a
misalignment policy violation to offer a user-confirmed continuation. Missing or
incomplete details must continue to behave as a terminal block.

## What changed

- Parse optional misalignment classification, explanation, and steering details
  from streamed and HTTP Responses errors and propagate them through core errors.
- Include the details in live app-server `error` and `turn/completed` payloads and
  export the corresponding protocol schemas and TypeScript types.
- Keep explanations and steering messages out of serialized rollout events and
  redact them from debug output.
- Document how clients can resume with `turn/start` after user confirmation.

## Testing

- Cover streamed, HTTP, and WebSocket-wrapped errors, including malformed and
  classification-only details.
- Verify live app-server notifications expose resumable details without writing
  the explanation or steering message to the rollout.

GitOrigin-RevId: 329258a444c2cd91d0c57ab1720830b33ddcfac5
This commit is contained in:
Francis Chalissery authored and copyberry committed 2026-08-26 18:42:44 +00:00
1 parent 0e9a2bae52
commit 7276d67081
63 files changed
+1604 -15

No files matched your search

@@ -1192,6 +1192,7 @@ impl ThreadHistoryBuilder {
let changed_turn = if let Some(turn) = self.current_turn.as_mut() {
turn.status = TurnStatus::Failed;
turn.error = Some(V2TurnError {
misalignment: payload.misalignment.clone().map(Into::into),
message: payload.message.clone(),
codex_error_info: payload.codex_error_info.clone().map(Into::into),
additional_details: None,
@@ -1250,6 +1251,7 @@ impl ThreadHistoryBuilder {
fn handle_turn_complete(&mut self, payload: &TurnCompleteEvent) {
let terminal_error = payload.error.as_ref().map(|error| V2TurnError {
misalignment: error.misalignment.clone().map(Into::into),
message: error.message.clone(),
codex_error_info: error.codex_error_info.clone().map(Into::into),
additional_details: None,
@@ -3821,6 +3823,7 @@ mod tests {
started_at: Some(10),
last_agent_message: None,
error: Some(ErrorEvent {
misalignment: None,
message: "Selected model is at capacity. Please try a different model.".into(),
codex_error_info: Some(CodexErrorInfo::ServerOverloaded),
}),
@@ -3851,6 +3854,7 @@ mod tests {
}],
status: TurnStatus::Failed,
error: Some(TurnError {
misalignment: None,
message: "Selected model is at capacity. Please try a different model."
.into(),
codex_error_info: Some(
@@ -4203,6 +4207,7 @@ mod tests {
delivery: None,
}),
EventMsg::Error(ErrorEvent {
misalignment: None,
message: "rollback failed".into(),
codex_error_info: Some(CodexErrorInfo::ThreadRollbackFailed),
}),
@@ -4246,6 +4251,7 @@ mod tests {
time_to_first_token_ms: None,
}),
EventMsg::Error(ErrorEvent {
misalignment: None,
message: "request-level failure".into(),
codex_error_info: Some(CodexErrorInfo::BadRequest),
}),
@@ -4298,6 +4304,7 @@ mod tests {
..Default::default()
}),
EventMsg::Error(ErrorEvent {
misalignment: None,
message: "stream failure".into(),
codex_error_info: Some(CodexErrorInfo::ResponseStreamDisconnected {
http_status_code: Some(502),
@@ -4325,6 +4332,7 @@ mod tests {
assert_eq!(
turns[0].error,
Some(TurnError {
misalignment: None,
message: "stream failure".into(),
codex_error_info: Some(
crate::protocol::v2::CodexErrorInfo::ResponseStreamDisconnected {
@@ -4359,6 +4367,7 @@ mod tests {
started_at: Some(10),
last_agent_message: None,
error: Some(ErrorEvent {
misalignment: None,
message: "Selected model is at capacity. Please try a different model.".into(),
codex_error_info: Some(CodexErrorInfo::ServerOverloaded),
}),
@@ -4388,6 +4397,7 @@ mod tests {
}],
status: TurnStatus::Failed,
error: Some(TurnError {
misalignment: None,
message: "Selected model is at capacity. Please try a different model.".into(),
codex_error_info: Some(crate::protocol::v2::CodexErrorInfo::ServerOverloaded),
additional_details: None,
@@ -40,6 +40,7 @@ pub fn project_rollout_line(line: &RolloutLine) -> ThreadHistoryChangeSet {
TurnStatus::Completed
},
error: event.error.as_ref().map(|error| TurnError {
misalignment: error.misalignment.clone().map(Into::into),
message: error.message.clone(),
codex_error_info: error.codex_error_info.clone().map(Into::into),
additional_details: None,
@@ -68,6 +68,7 @@ fn projects_turn_lifecycle_without_prior_builder_state() {
#[test]
fn projects_failed_turn_completion_as_snapshot() {
let error = ErrorEvent {
misalignment: None,
message: "request failed".to_string(),
codex_error_info: None,
};
@@ -91,6 +92,7 @@ fn projects_failed_turn_completion_as_snapshot() {
turn_id: "turn-1".to_string(),
status: TurnStatus::Failed,
error: Some(TurnError {
misalignment: None,
message: "request failed".to_string(),
codex_error_info: None,
additional_details: None,
@@ -5,6 +5,8 @@ use super::TurnStatus;
use crate::JsonSchema;
use crate::TS;
use codex_experimental_api_macros::ExperimentalApi;
use codex_protocol::protocol::MisalignmentErrorDetails as CoreMisalignmentErrorDetails;
use codex_protocol::protocol::MisalignmentSteer as CoreMisalignmentSteer;
use codex_protocol::protocol::SessionSource as CoreSessionSource;
use codex_protocol::protocol::SubAgentSource as CoreSubAgentSource;
use codex_protocol::protocol::ThreadHistoryMode as CoreThreadHistoryMode;
@@ -16,6 +18,7 @@ use schemars::r#gen::SchemaGenerator;
use schemars::schema::Schema;
use serde::Deserialize;
use serde::Serialize;
use std::fmt;
use std::path::PathBuf;
use thiserror::Error;
@@ -393,4 +396,67 @@ pub struct TurnError {
pub codex_error_info: Option<CodexErrorInfo>,
#[serde(default)]
pub additional_details: Option<String>,
/// Optional public explanation and continuation instruction for a misalignment block.
#[serde(default)]
pub misalignment: Option<MisalignmentErrorDetails>,
}
#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct MisalignmentErrorDetails {
/// Open-ended classification; clients must accept categories added by Responses.
pub error_type: Option<String>,
/// A substantive localized explanation is required before offering continuation.
pub detailed_explanation: Option<String>,
/// Instruction to submit as the next turn's user input if continuation is confirmed.
pub steer: Option<MisalignmentSteer>,
}
impl fmt::Debug for MisalignmentErrorDetails {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("MisalignmentErrorDetails")
.field("error_type", &self.error_type)
.field(
"has_detailed_explanation",
&self.detailed_explanation.is_some(),
)
.field("has_steer", &self.steer.is_some())
.finish()
}
}
impl From<CoreMisalignmentErrorDetails> for MisalignmentErrorDetails {
fn from(value: CoreMisalignmentErrorDetails) -> Self {
Self {
error_type: value.error_type,
detailed_explanation: value.detailed_explanation,
steer: value.steer.map(Into::into),
}
}
}
#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct MisalignmentSteer {
pub message: String,
}
impl fmt::Debug for MisalignmentSteer {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("MisalignmentSteer")
.field("message", &"[REDACTED]")
.finish()
}
}
impl From<CoreMisalignmentSteer> for MisalignmentSteer {
fn from(value: CoreMisalignmentSteer) -> Self {
Self {
message: value.message,
}
}
}