Skip to main content

muse_code_sdk/msp/view/item/object/
item.rs

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