Add typed item lifecycle events to the cloud client (#59066)

## What changed

Decode live item start and completion notifications as `TranscriptUpdate::ItemStarted` and `TranscriptUpdate::ItemCompleted`, with turn identity, lifecycle timestamps, and summaries for user messages, agent messages, reasoning, commands, and file changes.

Preserve structured agent questions even when message text is empty, optional command output and exit details, and command or patch status independently of lifecycle completion. Keep unsupported or incomplete items as opaque notifications and redact summary fields in debug output.

## Testing

Add fixtures covering lifecycle ordering alongside deltas, identity and timestamps, status and optional-field preservation, structured questions, opaque fallback, malformed payloads, thread ownership, and debug redaction.

GitOrigin-RevId: d6bf2d25ee85be17d895726c5072850a9851b55f
This commit is contained in:
Benjamin Carlsson
2026-11-03 05:43:27 +00:00
committed by copyberry
parent dbaead0106
commit 7ee5efad4a
9 changed files with 848 additions and 20 deletions
+264
View File
@@ -0,0 +1,264 @@
//! Selected item summaries for live start/completion events, without interpreting executor paths.
use crate::FileUpdate;
use crate::TranscriptUpdate;
use crate::item_wire as wire;
use crate::transcript::DecodeFailure;
use crate::transcript::ITEM_STARTED;
use crate::transcript::required;
use crate::transcript_wire::Envelope;
use crate::transcript_wire::SelectedMessages;
use crate::transcript_wire::merge_messages;
use std::fmt;
/// Lifecycle identity and timestamp for a typed item event.
#[derive(Clone, PartialEq, Eq)]
pub struct ItemLifecycle {
pub turn_id: String,
/// Start or completion time in Unix milliseconds, according to the event variant.
pub at_ms: i64,
pub item: ItemSummary,
}
/// Selected fields only; this is not a complete display model.
#[derive(Clone, PartialEq, Eq)]
pub enum ItemSummary {
UserMessage {
id: String,
client_id: Option<String>,
text: Vec<String>,
},
AgentMessage {
id: String,
text: String,
questions: Option<Vec<AgentQuestion>>,
},
Reasoning {
id: String,
summary: Vec<String>,
content: Vec<String>,
},
CommandExecution(CommandSummary),
FileChange {
id: String,
changes: Vec<FileUpdate>,
status: ItemStatus,
},
}
/// A structured question attached to an agent message.
#[derive(Clone, PartialEq, Eq)]
pub struct AgentQuestion {
pub title: String,
pub options: Option<Vec<String>>,
}
#[derive(Clone, PartialEq, Eq)]
pub struct CommandSummary {
pub id: String,
pub command: String,
/// Executor-native path. Do not interpret it as a path on the client machine.
pub cwd: String,
pub actions: Vec<CommandAction>,
pub source: CommandExecutionSource,
pub aggregated_output: Option<String>,
pub duration_ms: Option<i64>,
pub exit_code: Option<i64>,
pub status: ItemStatus,
}
#[derive(Clone, PartialEq, Eq)]
pub enum CommandAction {
Read {
command: String,
name: String,
path: String,
},
ListFiles {
command: String,
path: Option<String>,
},
Search {
command: String,
query: Option<String>,
path: Option<String>,
},
Unknown {
command: String,
},
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum CommandExecutionSource {
Agent,
UserShell,
UnifiedExecStartup,
UnifiedExecInteraction,
}
/// CommandExecutionStatus and PatchApplyStatus share these wire values.
/// Completion of the item lifecycle does not imply the command or patch succeeded.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ItemStatus {
InProgress,
Completed,
Failed,
Declined,
Unknown(i32),
}
impl From<i32> for ItemStatus {
fn from(value: i32) -> Self {
match value {
1 => Self::InProgress,
2 => Self::Completed,
3 => Self::Failed,
4 => Self::Declined,
value => Self::Unknown(value),
}
}
}
macro_rules! redacted_debug {
($($ty:ty),*) => {$(impl fmt::Debug for $ty {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(concat!(stringify!($ty), "([redacted])"))
}
})*};
}
redacted_debug!(
ItemLifecycle,
ItemSummary,
AgentQuestion,
CommandSummary,
CommandAction
);
pub(crate) fn decode(
tag: u32,
values: SelectedMessages<'_>,
) -> Result<Option<(String, Option<i64>, TranscriptUpdate)>, DecodeFailure> {
let (thread_id, turn_id, at_ms, item, emitted_at_ms) = if tag == ITEM_STARTED {
let envelope = merge_messages::<Envelope<wire::Started>>(values)?;
let params = required(envelope.params)?;
(
params.thread_id,
params.turn_id,
params.at_ms,
params.item,
envelope.emitted_at_ms,
)
} else {
let envelope = merge_messages::<Envelope<wire::Completed>>(values)?;
let params = required(envelope.params)?;
(
params.thread_id,
params.turn_id,
params.at_ms,
params.item,
envelope.emitted_at_ms,
)
};
let Some(item) = summary(required(item)?)? else {
return Ok(None);
};
let lifecycle = ItemLifecycle {
turn_id: required(turn_id)?,
at_ms: required(at_ms)?,
item,
};
let update = if tag == ITEM_STARTED {
TranscriptUpdate::ItemStarted(lifecycle)
} else {
TranscriptUpdate::ItemCompleted(lifecycle)
};
Ok(Some((required(thread_id)?, emitted_at_ms, update)))
}
pub(crate) fn summary(item: wire::Item) -> Result<Option<ItemSummary>, DecodeFailure> {
let summary = match item.value {
Some(wire::Value::UserMessage(value)) => {
let mut text = Vec::new();
for input in required(value.content)?.values {
let Some(crate::turns_wire::Value::Text(input)) = input.value else {
return Ok(None);
};
text.push(required(input.text)?);
}
ItemSummary::UserMessage {
id: required(value.id)?,
client_id: value.client_id,
text,
}
}
Some(wire::Value::AgentMessage(value)) => ItemSummary::AgentMessage {
id: required(value.id)?,
text: required(value.text)?,
questions: value
.questions
.map(|questions| {
questions
.values
.into_iter()
.map(|question| {
Ok(AgentQuestion {
title: required(question.title)?,
options: question.options.map(|options| options.values),
})
})
.collect::<Result<_, DecodeFailure>>()
})
.transpose()?,
},
Some(wire::Value::Reasoning(value)) => ItemSummary::Reasoning {
id: required(value.id)?,
summary: value.summary.map_or_else(Vec::new, |value| value.values),
content: value.content.map_or_else(Vec::new, |value| value.values),
},
Some(wire::Value::Command(value)) => ItemSummary::CommandExecution(CommandSummary {
id: required(value.id)?,
command: required(value.command)?,
cwd: required(value.cwd)?,
actions: required(value.actions)?
.values
.into_iter()
.map(command_action)
.collect::<Result<_, _>>()?,
source: match value.source {
None | Some(1) => CommandExecutionSource::Agent,
Some(2) => CommandExecutionSource::UserShell,
Some(3) => CommandExecutionSource::UnifiedExecStartup,
Some(4) => CommandExecutionSource::UnifiedExecInteraction,
Some(_) => return Err(DecodeFailure::UnsupportedCommandSource),
},
aggregated_output: value.output,
duration_ms: value.duration_ms,
exit_code: value.exit_code,
status: required(value.status)?.into(),
}),
Some(wire::Value::FileChange(value)) => ItemSummary::FileChange {
id: required(value.id)?,
changes: required(value.changes)?
.values
.into_iter()
.map(FileUpdate::try_from)
.collect::<Result<_, _>>()?,
status: required(value.status)?.into(),
},
_ => return Ok(None),
};
Ok(Some(summary))
}
fn command_action(action: wire::CommandAction) -> Result<CommandAction, DecodeFailure> {
Ok(match required(action.value)? {
wire::command_action::Value::Read(value) => CommandAction::Read {
command: required(value.command)?,
name: required(value.name)?,
path: required(value.path)?,
},
wire::command_action::Value::ListFiles(value) => CommandAction::ListFiles {
command: required(value.command)?,
path: value.path,
},
wire::command_action::Value::Search(value) => CommandAction::Search {
command: required(value.command)?,
query: value.query,
path: value.path,
},
wire::command_action::Value::Unknown(value) => CommandAction::Unknown {
command: required(value.command)?,
},
})
}