Skip to main content

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/// The cache splits and server-computed `cost` join the counters. The counters
74/// stay accumulate-only; `cost` is the documented exception — it may move
75/// either way on price re-adoption and is labeled estimate. `Copy` was dropped
76/// 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}