Skip to main content

muse_code_sdk/msp/view/item/
object.rs

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