lash/
usage.rs

1//! Token usage tracking surfaces.
2//!
3//! Four channels, finest granularity to coarsest:
4//!
5//! - **`TraceSink`**: every provider call across every session in the
6//!   runtime. Right for billing, audit, off-line analysis. Heavier than
7//!   necessary if you only want totals. See [`crate::tracing`].
8//! - **[`TurnEvent::Usage`] / [`TurnEvent::ChildUsage`]**: live during a
9//!   turn, one event per LLM iteration. `Usage` is the parent's own
10//!   model call; `ChildUsage` carries `session_id` + `source` so a UI can
11//!   group child traffic (e.g. by subagent). Right for live counters.
12//! - **[`TurnResult::usage`] / [`TurnResult::children_usage`]**: per-turn
13//!   snapshot at completion. `usage` is parent-only; `children_usage` is a
14//!   per-`(source, model)` breakdown. [`TurnResult::total_usage`] sums both.
15//!   Right for "what did this message cost."
16//! - **[`SessionUsageReport`]** (`session.usage_report()`): aggregate
17//!   across the whole session, broken down by `source` × `model`. Right for
18//!   dashboards and "session so far."
19//!
20//! Usage buckets are provider-normalized before they reach these surfaces:
21//! `input_tokens` is uncached ordinary input, `cache_read_input_tokens` is
22//! cached prompt input read from the provider cache, `cache_write_input_tokens`
23//! is prompt input written to the provider cache, and `output_tokens` is total
24//! generated output. `reasoning_output_tokens` is a subset of output tokens,
25//! not an extra total component. `TokenUsage::total()` therefore sums ordinary
26//! input, output, cache reads, and cache writes.
27//!
28//! [`TurnEvent::Usage`]: lash_core::TurnEvent::Usage
29//! [`TurnEvent::ChildUsage`]: lash_core::TurnEvent::ChildUsage
30//! [`TurnResult::usage`]: crate::TurnResult::usage
31//! [`TurnResult::children_usage`]: crate::TurnResult::children_usage
32//! [`TurnResult::total_usage`]: crate::TurnResult::total_usage
33
34pub use lash_core::{
35    SessionUsageReport, TokenLedgerEntry, TokenUsage, UsageReportRow, UsageTotals,
36    diff_token_ledger, diff_usage_reports,
37};
38
39/// Well-known source labels used by the runtime and first-party plugins.
40///
41/// The `source` field on [`TokenLedgerEntry`] and `ChildUsage` events is a
42/// free-form string; the runtime does not interpret the value. Plugins may
43/// use additional labels of their own.
44pub mod sources {
45    /// Parent's own LLM calls.
46    pub const TURN: &str = "turn";
47    /// Spawned subagent sessions.
48    pub const SUBAGENT: &str = "subagent";
49    /// Rolling-history compaction passes.
50    pub const COMPACTION: &str = "compaction";
51    /// Async observational-memory observer runs.
52    pub const OBSERVER: &str = "observer";
53    /// Async observational-memory reflector runs.
54    pub const REFLECTOR: &str = "reflector";
55    /// Default fallback when no `usage_source` is set on a child session.
56    pub const CHILD: &str = "child";
57}
lash/usage.rs

lash/
usage.rs
