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