muse_code_sdk/msp/view/state/usage.rs
1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use crate::msp::view::SourceRange;
4use serde::Deserialize;
5use serde::Serialize;
6
7mod catch_all;
8
9/// `session/tokenUsage` params: one per model completion that reports usage.
10/// Carries the raw counters verbatim plus the server-derived counted-once
11/// `promptTokens`/`totalTokens` and the session `cumulative` block.
12/// Accumulate-only: `cumulative` never goes backward.
13#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
14#[serde(rename_all = "camelCase")]
15#[non_exhaustive]
16pub struct SessionTokenUsageParams {
17 /// The owning session.
18 pub session_id: String,
19 /// Opaque, strictly monotonic view cursor.
20 pub view_cursor: String,
21 /// The durable records this event folded from.
22 pub source_range: SourceRange,
23 /// The turn whose model call completed.
24 pub turn_id: String,
25 /// The effective model that produced this usage; `null` on pre-schema
26 /// records — never back-filled, an unpriced leg.
27 pub model_id: Option<String>,
28 /// Raw counters verbatim from the durable record.
29 pub usage: TokenUsage,
30 /// Prompt tokens counted exactly once under the provider's cache
31 /// convention. Server-derived; deterministic — the provider is in the log.
32 pub prompt_tokens: u64,
33 /// `promptTokens + outputTokens` — the honest per-completion total.
34 pub total_tokens: u64,
35 /// Provider finish reason when reported (open vocabulary, verbatim).
36 #[serde(skip_serializing_if = "Option::is_none")]
37 pub finish_reason: Option<String>,
38 /// Model-call wall time, when measured.
39 #[serde(skip_serializing_if = "Option::is_none")]
40 pub duration_ms: Option<u64>,
41 /// Session running totals at this cursor; the fold owns the accumulation.
42 /// Subagent/workflow-child usage is never folded in — it rides the owning
43 /// items.
44 pub cumulative: CumulativeTokenUsage,
45}
46
47/// Raw token counters, verbatim from the durable record. Not directly summable
48/// across providers — sum the counted-once derivations instead.
49#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
50#[serde(rename_all = "camelCase")]
51#[non_exhaustive]
52pub struct TokenUsage {
53 /// Provider-reported input tokens.
54 pub input_tokens: u64,
55 /// Provider-reported output tokens.
56 pub output_tokens: u64,
57 /// Provider-reported cache tokens (inside or beside `inputTokens`,
58 /// provider-convention-dependent — the reason `promptTokens` exists).
59 pub cached_tokens: u64,
60 /// Cache write tokens, only when the provider distinguishes
61 /// writes/reads.
62 #[serde(skip_serializing_if = "Option::is_none")]
63 pub cache_write_tokens: Option<u64>,
64 /// Cache read tokens, only when the provider distinguishes writes/reads.
65 #[serde(skip_serializing_if = "Option::is_none")]
66 pub cache_read_tokens: Option<u64>,
67 /// Output tokens spent on reasoning, when the provider reports it.
68 pub reasoning_tokens: u64,
69}
70
71/// Session running totals of counted-once usage.
72///
73/// Amendment a tracked change: the cache splits and server-computed `cost` join
74/// the counters. The counters stay accumulate-only; `cost` is the documented
75/// exception — it may move either way on price re-adoption and is labeled
76/// estimate. `Copy` was dropped for the `cost` member.
77#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
78#[serde(rename_all = "camelCase")]
79#[non_exhaustive]
80pub struct CumulativeTokenUsage {
81 /// Counted-once prompt tokens, session total.
82 pub prompt_tokens: u64,
83 /// Output tokens, session total.
84 pub output_tokens: u64,
85 /// Counted-once totals, session total.
86 pub total_tokens: u64,
87 /// Cache-read tokens, session total: saturating sum of the per-completion
88 /// splits; an absent split contributes 0. Additive-optional: absent on the
89 /// wire reads as 0 and zero totals are omitted, so pre-feature bytes decode
90 /// and re-encode identically.
91 #[serde(default, skip_serializing_if = "is_zero")]
92 pub cache_read_tokens: u64,
93 /// Cache-write tokens, session total. Additive-optional like the read
94 /// split.
95 #[serde(default, skip_serializing_if = "is_zero")]
96 pub cache_write_tokens: u64,
97 /// Server-computed session cost: `None` (wire-absent) when no leg is priced
98 /// — clients omit the row. Additive-optional: absent reads as unpriced.
99 #[serde(default, skip_serializing_if = "Option::is_none")]
100 pub cost: Option<CumulativeCost>,
101}
102
103fn is_zero(value: &u64) -> bool {
104 *value == 0
105}
106
107/// Server-computed session cost member of [`CumulativeTokenUsage`].
108#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
109#[serde(rename_all = "camelCase")]
110#[non_exhaustive]
111pub struct CumulativeCost {
112 /// Estimated USD total, finite and non-negative.
113 pub usd: f64,
114 /// True when at least one leg lacked price data — clients render
115 /// `(partial)`.
116 pub partial: bool,
117}
118
119/// `session/contextUsage` params: context-window pressure — the counted-once
120/// occupancy at the latest provider-reported durable fact, joined with the
121/// host's pressure basis. Replace wholesale; emitted only when the
122/// `(windowTokens, usedTokens, pressure)` triple changes value (identical
123/// adoptions emit nothing).
124#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
125#[serde(rename_all = "camelCase")]
126#[non_exhaustive]
127pub struct SessionContextUsageParams {
128 /// The owning session.
129 pub session_id: String,
130 /// Opaque, strictly monotonic view cursor.
131 pub view_cursor: String,
132 /// The durable records this event folded from.
133 pub source_range: SourceRange,
134 /// The effective context-window size from the host's pressure basis; absent
135 /// when the basis has no limit — the limit part is omitted, never invented.
136 #[serde(skip_serializing_if = "Option::is_none")]
137 pub window_tokens: Option<u64>,
138 /// Counted-once prompt tokens plus output tokens of the driving record,
139 /// saturating — the honest occupancy floor.
140 pub used_tokens: u64,
141 /// Server-computed pressure level over the basis thresholds.
142 pub pressure: ContextPressureLevel,
143}
144
145/// Context pressure level: hard threshold first, both inclusive `>=`. Open.
146#[derive(Debug, Clone, PartialEq, Eq)]
147#[non_exhaustive]
148pub enum ContextPressureLevel {
149 /// No threshold reached.
150 Normal,
151 /// At or above the soft threshold.
152 Warning,
153 /// At or above the hard threshold.
154 Blocked,
155 /// A value from a newer host, kept verbatim so an older client decodes the
156 /// rest of the message. Never construct it with a known word.
157 Unknown(String),
158}
159
160/// The snapshot `contextUsage` block: the latest `(windowTokens, usedTokens,
161/// pressure)` triple; the snapshot member is `null` until the fold's generation
162/// chain holds a tracked anchor AND the current basis is present (absent is
163/// never fabricated).
164#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
165#[serde(rename_all = "camelCase")]
166#[non_exhaustive]
167pub struct ContextUsage {
168 /// The effective context-window size; absent when the basis has no limit.
169 #[serde(skip_serializing_if = "Option::is_none")]
170 pub window_tokens: Option<u64>,
171 /// Counted-once occupancy at the latest provider-reported fact.
172 pub used_tokens: u64,
173 /// Server-computed pressure level.
174 pub pressure: ContextPressureLevel,
175}