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