1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
// @generated from the MSP stable schema and protocol sources; do not edit by hand.
use super::BodyCompletionMembers;
use super::NoticeOrigin;
use super::NoticeSeverity;
use super::NoticeSubject;
use super::ReplayHint;
use super::ScheduledFireMembers;
use super::SubagentMembers;
use super::ToolCallMembers;
use super::WebSearchMembers;
use super::WorkflowMembers;
use crate::msp::method::hook::HookEventName;
use crate::msp::view::item_content::BackgroundTerminalCompletion;
use crate::msp::view::item_content::CompactionOutcome;
use crate::msp::view::item_content::CompactionTrigger;
use crate::msp::view::item_content::DamagedRange;
use crate::msp::view::item_content::EarlierHistory;
use crate::msp::view::item_content::HookRunStatus;
use crate::msp::view::item_content::ItemKind;
use crate::msp::view::item_content::ItemStatus;
use crate::msp::view::item_content::MessageAttachment;
use crate::msp::view::item_content::PeerMessage;
use crate::msp::view::item_content::SubagentControlStatus;
use crate::msp::view::item_content::SubagentInputPhase;
use crate::msp::view::item_content::SubagentResult;
use crate::msp::view::item_content::SubagentResultStatus;
use crate::msp::view::message_phase::MessagePhase;
use crate::msp::view::message_phase::lenient_message_phase;
use crate::msp::view::state::TokenUsage;
use serde::Deserialize;
use serde::Serialize;
/// One transcript item at one revision. `item/started`, `item/updated`, and
/// `item/completed` carry the full object; `item/delta` appends to it by field
/// path.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct Item {
/// Bare UUIDv7; the item's identity across its whole lifecycle. Identity
/// rule: the task id for task-backed kinds (`toolCall`, `subagent`), the
/// pre-minted commit `message_id` for delta-streamed kinds (`agentMessage`,
/// `reasoning`), `EventId::derive` over the session id and the range's
/// starting sequence number for `damagedRange`, the same over the boundary
/// checkpoint's sequence number for `earlierHistory`, and the opening
/// durable record's event id for everything else. Opaque to clients.
pub item_id: String,
/// The item kind (open enum): clients MUST render unknown kinds generically
/// — kind name plus `status` plus `fallbackText`.
pub kind: ItemKind,
/// The owning turn. `null` for the kinds outside a turn: `userShell`
/// always, `hookRun` for session-boundary runs, `monitorFeed` always,
/// `sideChat` always, `damagedRange` always, `earlierHistory` always,
/// `systemNotice` when produced outside a turn.
pub turn_id: Option<String>,
/// Integer >= 1, strictly monotonic per item; apply rule is
/// replace-iff-higher. `item/delta` never bumps it.
pub revision: u64,
/// Open enum; terminal = anything other than `"inProgress"`. Unknown values
/// MUST be treated as terminal-unknown and rendered generically.
pub status: ItemStatus,
/// RFC3339 timestamp of the item's driving durable record. Absent on
/// ephemeral-opened items until first durable re-emission.
#[serde(skip_serializing_if = "Option::is_none")]
pub recorded_at: Option<String>,
/// Server-provided one-line human summary any kind MAY carry, for generic
/// rendering of kinds a client does not recognize; new kinds SHOULD carry
/// it during their first release cycle.
#[serde(skip_serializing_if = "Option::is_none")]
pub fallback_text: Option<String>,
/// `userMessage`: the prompt text as submitted. `agentMessage`: the
/// accumulated reply, streamed via `item/delta` field `"text"`.
/// `reasoning`: raw committed reasoning text where the provider exposes it.
#[serde(skip_serializing_if = "Option::is_none")]
pub text: Option<String>,
/// `userMessage`: presentation form; absent when the client sent none.
#[serde(skip_serializing_if = "Option::is_none")]
pub display_text: Option<String>,
/// `userMessage`/`userShell`: the submitting command — multi-client UIs
/// de-duplicate their local echo on it.
#[serde(skip_serializing_if = "Option::is_none")]
pub command_id: Option<String>,
/// `userMessage`: the client that sent the message or steer; absent when
/// unrecorded and on older logs.
#[serde(skip_serializing_if = "Option::is_none")]
pub by_client: Option<crate::msp::handshake::ClientInfo>,
/// `userMessage`: `true` when injected mid-turn via `turn/steer` or
/// `ifBusy: "steer"`; absent otherwise.
#[serde(skip_serializing_if = "Option::is_none")]
pub steered: Option<bool>,
/// `userMessage`: `true` after an accepted retract; re-emitted via
/// `item/updated`.
#[serde(skip_serializing_if = "Option::is_none")]
pub retracted: Option<bool>,
/// `userMessage`: image attachment metadata only — base64 payloads are not
/// echoed back on the view.
#[serde(skip_serializing_if = "Option::is_none")]
pub attachments: Option<Vec<MessageAttachment>>,
/// `true` when the server's per-surface text budget saturated a streamed
/// surface (`agentMessage.text`, `reasoning.summary[*]`,
/// `toolCall.visibleOutput`, `userShell.visibleOutput`), cut a `subagent`
/// surface (`objective`, `fallbackText`, `result.summary`, `result.text`),
/// or cut a `monitorFeed` surface (`text`, `fallbackText`,
/// `monitorDescription`), or cut a `systemNotice` surface. On a `subagent`
/// item the flag is item-level and never cleared: once any of those four is
/// cut, every later update keeps it, even when `result.text` arrives whole.
/// The durable full text remains in the log.
#[serde(skip_serializing_if = "Option::is_none")]
pub truncated: Option<bool>,
/// `agentMessage`: the phase the model declared; see [`MessagePhase`].
#[serde(default, deserialize_with = "lenient_message_phase")]
#[serde(skip_serializing_if = "Option::is_none")]
pub message_phase: Option<MessagePhase>,
/// `agentMessage`: the Monitor source descriptions for the wake turn's
/// first answer — stripped, bounded, one entry per arming drain in drain
/// order. Absent (or empty) means untagged: the row renders the ordinary
/// untagged shape. The client scrubs per part before joining.
#[serde(skip_serializing_if = "Option::is_none")]
pub wake_source_descriptions: Option<Vec<String>>,
/// `agentMessage`: `true` when the provider stream died mid-reply and the
/// run failed with this partial text committed — the wire mark for the
/// gate-off "incomplete response" rule. Absent otherwise; never cleared
/// once set.
#[serde(skip_serializing_if = "Option::is_none")]
pub cut_off: Option<bool>,
/// `reasoning`: one entry per summary part; part *n* streams via
/// `item/delta` field `"summary.n"` (part boundary = index change).
#[serde(skip_serializing_if = "Option::is_none")]
pub summary: Option<Vec<String>>,
/// `reasoning`: provider reasoning item id (e.g. `rs_...`), for
/// provider-side correlation.
#[serde(skip_serializing_if = "Option::is_none")]
pub provider_item_id: Option<String>,
/// `toolCall` members, flattened beside the other optional members.
#[serde(flatten)]
pub tool_call: ToolCallMembers,
/// `userShell`: the command text as submitted.
#[serde(skip_serializing_if = "Option::is_none")]
pub command_text: Option<String>,
/// `userShell`: the process exit code, when it exited by code.
#[serde(skip_serializing_if = "Option::is_none")]
pub exit_code: Option<i64>,
/// `userShell`: the terminating signal NUMBER, when signalled (e.g. 9) —
/// the durable payload verbatim; nothing maps numbers to names, and the
/// fold never invents one.
#[serde(skip_serializing_if = "Option::is_none")]
pub exit_signal: Option<i64>,
/// `userShell`/`subagent`: observed wall-clock duration. `workflow`: the
/// run's wall time from launch to reconciliation, set only on the settling
/// `item/completed` — never a sum of child durations. `toolCall`: the
/// Backgrounded row's duration — the open→update record delta in whole ms,
/// served on the `backgroundStatus` re-emission and frozen there; absent
/// otherwise.
#[serde(skip_serializing_if = "Option::is_none")]
pub duration_ms: Option<u64>,
/// `subagent`: durable child identity (`subagent_id`).
#[serde(skip_serializing_if = "Option::is_none")]
pub subagent_id: Option<String>,
/// `subagent`: agent definition path.
#[serde(skip_serializing_if = "Option::is_none")]
pub agent_path: Option<String>,
/// `subagent`: nesting depth.
#[serde(skip_serializing_if = "Option::is_none")]
pub depth: Option<u32>,
/// `subagent`: role as spawned.
#[serde(skip_serializing_if = "Option::is_none")]
pub role: Option<String>,
/// `subagent` members, flattened beside the other optional members.
#[serde(flatten)]
pub subagent: SubagentMembers,
/// `subagent`: objective as spawned, bounded on the wire at the 64 KiB
/// retained-text budget; a cut sets `truncated`. The durable record stays
/// verbatim.
#[serde(skip_serializing_if = "Option::is_none")]
pub objective: Option<String>,
/// `subagent`/`reminderChild`: the child's own session id, readable via
/// `session/read`/`view/page` — child transcript drill-down without a
/// second protocol.
#[serde(skip_serializing_if = "Option::is_none")]
pub child_session_id: Option<String>,
/// `subagent`: the `subagentId` of the subagent whose own session spawned
/// this child, by `subagent/list`'s `parentSubagentId` rule.
/// **Additive-optional**: absent for a child of the view's own session, or
/// when no open `subagent` item in this view owns the spawning session;
/// never guessed, never derived from `agentPath`.
#[serde(skip_serializing_if = "Option::is_none")]
pub parent_subagent_id: Option<String>,
/// `subagent`: camelCased `SubagentControlStatus` (open enum); `status`
/// stays the generic item vocabulary.
#[serde(skip_serializing_if = "Option::is_none")]
pub control_status: Option<SubagentControlStatus>,
/// `subagent`/`workflow`: the owning durable workflow run id (opaque
/// string — not a UUID family).
#[serde(skip_serializing_if = "Option::is_none")]
pub workflow_run_id: Option<String>,
/// `subagent`: **transitive** observed usage — the child and its own
/// descendants; updated in place, absent until first observation; never
/// folded into `session/tokenUsage.cumulative`.
#[serde(skip_serializing_if = "Option::is_none")]
pub usage: Option<TokenUsage>,
/// `subagent`: the result envelope from `ResultReady`.
#[serde(skip_serializing_if = "Option::is_none")]
pub result: Option<SubagentResult>,
/// `subagent`: the host could not read this live child's run records when
/// the parent resumed; a client says so once. A resume-time observation:
/// present only as `true`, absent otherwise, never `false`, and never
/// carried by a live notification.
#[serde(skip_serializing_if = "Option::is_none")]
pub history_unreadable: Option<bool>,
/// `workflow` members, flattened into the item row.
#[serde(flatten)]
pub workflow: WorkflowMembers,
/// `reminderChild`: the reminder agent's id.
#[serde(skip_serializing_if = "Option::is_none")]
pub reminder_agent_id: Option<String>,
/// `reminderChild`: the reminder generation.
#[serde(skip_serializing_if = "Option::is_none")]
pub generation_id: Option<u64>,
/// `reminderChild`: the linked task id. Unresolved `bodyCompletion` items
/// also set it.
#[serde(skip_serializing_if = "Option::is_none")]
pub task_id: Option<String>,
/// `reminderChild`: parent-session-dir-relative child log path; absent
/// when no filesystem log.
#[serde(skip_serializing_if = "Option::is_none")]
pub child_session_log_path: Option<String>,
/// `reminderChild`: `true` when this child is a blocking reminder (it holds
/// the turn open until it settles); absent otherwise, never `false`. The
/// status word stays off the wire; clients name the reminder from
/// `reminderAgentId`.
#[serde(skip_serializing_if = "Option::is_none")]
pub blocking: Option<bool>,
/// `sideChat`: the side's own session id, readable via
/// `session/read`/`view/page` — drill-down without a second protocol.
#[serde(skip_serializing_if = "Option::is_none")]
pub side_session_id: Option<String>,
/// `skillRead`: the read skill's catalog selector (matches the `skill/list`
/// row; the raw observed id when the read resolved to no catalog row). Set
/// on every `skillRead` item; old clients render it beside the kind name.
#[serde(skip_serializing_if = "Option::is_none")]
pub selector: Option<String>,
/// `skillRead`: the catalog source (matches the `skill/list` row); empty
/// when the host could not resolve the read to a catalog row (replay
/// without the tool result, context-only evidence). Set on every
/// `skillRead` item; each client composes the notice line from `selector` +
/// `source`.
#[serde(skip_serializing_if = "Option::is_none")]
pub source: Option<String>,
/// `compaction`: terminal only — folds installed/fallback status.
#[serde(skip_serializing_if = "Option::is_none")]
pub outcome: Option<CompactionOutcome>,
/// `compaction`: what initiated the compaction.
#[serde(skip_serializing_if = "Option::is_none")]
pub trigger: Option<CompactionTrigger>,
/// `compaction`: summarizer strategy (installed only).
#[serde(skip_serializing_if = "Option::is_none")]
pub strategy_id: Option<String>,
/// `compaction`: opaque provenance string naming the compaction boundary.
/// Also a compaction-anchored read anchor, accepted by `session/resume` and
/// `view/page`. Still opaque — clients relay it, never parse it.
#[serde(skip_serializing_if = "Option::is_none")]
pub summarized_through: Option<String>,
/// `compaction`: token budget snapshot before, when measured.
#[serde(skip_serializing_if = "Option::is_none")]
pub tokens_before: Option<u64>,
/// `compaction`: token budget snapshot after, when measured.
#[serde(skip_serializing_if = "Option::is_none")]
pub tokens_after: Option<u64>,
/// `compaction`: noop/failure reason, verbatim (snake_case durable
/// vocabulary, e.g. `"no_compactable_history"`). `hookRun`: terminal-only
/// capped terminal reason.
#[serde(skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
/// `hookRun`: the durable `hook_key`.
#[serde(skip_serializing_if = "Option::is_none")]
pub hook_key: Option<String>,
/// `hookRun`: the hook event in Q2 camelCase vocabulary.
#[serde(skip_serializing_if = "Option::is_none")]
pub event: Option<HookEventName>,
/// `hookRun`: terminal-only durable outcome; stays `blocked` when the item
/// settles `rejected`.
#[serde(skip_serializing_if = "Option::is_none")]
pub run_status: Option<HookRunStatus>,
/// `hookRun`: capped display label.
#[serde(skip_serializing_if = "Option::is_none")]
pub label: Option<String>,
/// `systemNotice`: the notice's level — `info` | `warning` | `error`, open.
/// Absent means the server classified no level.
#[serde(skip_serializing_if = "Option::is_none")]
pub notice_severity: Option<NoticeSeverity>,
/// `systemNotice`: an optional open machine code for what happened, minted
/// per origin by the slice that adds its producer; omitted for `monitor`
/// and for `hook`.
#[serde(skip_serializing_if = "Option::is_none")]
pub notice_kind: Option<String>,
/// `systemNotice`: the producing family, so a client routes a notice
/// without parsing its text. Absent means the server named no origin:
/// render generically, never infer one.
#[serde(skip_serializing_if = "Option::is_none")]
pub notice_origin: Option<NoticeOrigin>,
/// `systemNotice`: the durable thing the notice is about — for `hook`, the
/// hook run's item id and its bounded label.
#[serde(skip_serializing_if = "Option::is_none")]
pub notice_subject: Option<NoticeSubject>,
/// `webSearch` members, flattened into the item row.
#[serde(flatten)]
pub web_search: WebSearchMembers,
/// `monitorFeed`: the monitor task id — the same value as that monitor's
/// `toolCall` `itemId`.
#[serde(skip_serializing_if = "Option::is_none")]
pub monitor_id: Option<String>,
/// `monitorFeed`: the monitor's arm-time description with the durable
/// `"Monitor event: "` summary prefix stripped; model- controlled tool
/// input under the 64 KiB per-surface budget — sanitize before render.
#[serde(skip_serializing_if = "Option::is_none")]
pub monitor_description: Option<String>,
/// `damagedRange`: what the damaged range cost.
#[serde(skip_serializing_if = "Option::is_none")]
pub damaged_range: Option<DamagedRange>,
/// `backgroundTerminalCompletion`: the five facts the Finished cell
/// renders.
#[serde(skip_serializing_if = "Option::is_none")]
pub background_terminal_completion: Option<BackgroundTerminalCompletion>,
/// `bodyCompletion`: the facts one receipt row renders.
#[serde(skip_serializing_if = "Option::is_none")]
pub body_completion: Option<BodyCompletionMembers>,
/// `earlierHistory`: the boundary checkpoint's transcript tail.
#[serde(skip_serializing_if = "Option::is_none")]
pub earlier_history: Option<EarlierHistory>,
/// `peerMessage`: the four facts the consumed card renders.
#[serde(skip_serializing_if = "Option::is_none")]
pub peer_message: Option<PeerMessage>,
/// `scheduledFire` members, flattened beside the other optional members.
#[serde(flatten)]
pub scheduled_fire: ScheduledFireMembers,
/// `backgroundTerminalCompletion`, or a terminal `toolCall` that already
/// shows a Finished row: render before the target's whole coalesced region.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub terminal_row_before_item_id: Option<String>,
/// Terminal monitor `toolCall`, drained `subagent`,
/// `backgroundTerminalCompletion`, or Finished-row `toolCall`: render after
/// the target's logical rows.
#[serde(skip_serializing_if = "Option::is_none")]
pub terminal_row_after_item_id: Option<String>,
/// Monitor `toolCall`: the hint verdict plus anchor (`ReplayHint`); absent
/// means no hint.
#[serde(skip_serializing_if = "Option::is_none")]
pub replay_hint: Option<ReplayHint>,
/// `subagentInput`: the record the item stands for; see
/// [`SubagentInputPhase`].
#[serde(default, skip_serializing_if = "Option::is_none")]
pub input_phase: Option<SubagentInputPhase>,
/// `subagentInput` (`delivered`): `true` when the drain landed on its turn
/// before that turn's terminal, which ends the turn's final answer as
/// gate-off's drain record does; absent otherwise.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub delivered_before_turn_end: Option<bool>,
/// `subagentResult`: the consumed attempt's outcome; absent if unseen at
/// the drain.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub result_status: Option<SubagentResultStatus>,
}