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