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}