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//! [`TurnEvent::Usage`]: lash_core::TurnEvent::Usage
21//! [`TurnEvent::ChildUsage`]: lash_core::TurnEvent::ChildUsage
22//! [`TurnResult::usage`]: crate::TurnResult::usage
23//! [`TurnResult::children_usage`]: crate::TurnResult::children_usage
24//! [`TurnResult::total_usage`]: crate::TurnResult::total_usage
25
26pub use lash_core::{
27    SessionUsageReport, TokenLedgerEntry, TokenUsage, UsageReportRow, UsageTotals,
28    diff_token_ledger, diff_usage_reports,
29};
30
31/// Well-known source labels used by the runtime and first-party plugins.
32///
33/// The `source` field on [`TokenLedgerEntry`] and `ChildUsage` events is a
34/// free-form string; the runtime does not interpret the value. Plugins may
35/// use additional labels of their own.
36pub mod sources {
37    /// Parent's own LLM calls.
38    pub const TURN: &str = "turn";
39    /// Spawned subagent sessions.
40    pub const SUBAGENT: &str = "subagent";
41    /// Rolling-history compaction passes.
42    pub const COMPACTION: &str = "compaction";
43    /// Async observational-memory observer runs.
44    pub const OBSERVER: &str = "observer";
45    /// Async observational-memory reflector runs.
46    pub const REFLECTOR: &str = "reflector";
47    /// Default fallback when no `usage_source` is set on a child session.
48    pub const CHILD: &str = "child";
49}
lash/usage.rs

lash/
usage.rs
