lash-runtime 0.1.0-alpha.63

Durable agent runtime for Rust: sessions, turns, tools, plugins. Embeddable facade over lash-core.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

//! Token usage tracking surfaces.
//!
//! Four channels, finest granularity to coarsest:
//!
//! - **`TraceSink`**: every provider call across every session in the
//!   runtime. Right for billing, audit, off-line analysis. Heavier than
//!   necessary if you only want totals. See [`crate::tracing`].
//! - **[`TurnEvent::Usage`] / [`TurnEvent::ChildUsage`]**: live during a
//!   turn, one event per LLM iteration. `Usage` is the parent's own
//!   model call; `ChildUsage` carries `session_id` + `source` so a UI can
//!   group child traffic (e.g. by subagent). Right for live counters.
//! - **[`TurnResult::usage`] / [`TurnResult::children_usage`]**: per-turn
//!   snapshot at completion. `usage` is parent-only; `children_usage` is a
//!   per-`(source, model)` breakdown. [`TurnResult::total_usage`] sums both.
//!   Right for "what did this message cost."
//! - **[`SessionUsageReport`]** (`session.usage_report()`): aggregate
//!   across the whole session, broken down by `source` × `model`. Right for
//!   dashboards and "session so far."
//!
//! [`TurnEvent::Usage`]: lash_core::TurnEvent::Usage
//! [`TurnEvent::ChildUsage`]: lash_core::TurnEvent::ChildUsage
//! [`TurnResult::usage`]: crate::TurnResult::usage
//! [`TurnResult::children_usage`]: crate::TurnResult::children_usage
//! [`TurnResult::total_usage`]: crate::TurnResult::total_usage

pub use lash_core::{
    SessionUsageReport, TokenLedgerEntry, TokenUsage, UsageReportRow, UsageTotals,
    diff_token_ledger, diff_usage_reports,
};

/// Well-known source labels used by the runtime and first-party plugins.
///
/// The `source` field on [`TokenLedgerEntry`] and `ChildUsage` events is a
/// free-form string; the runtime does not interpret the value. Plugins may
/// use additional labels of their own.
pub mod sources {
    /// Parent's own LLM calls.
    pub const TURN: &str = "turn";
    /// Spawned subagent sessions.
    pub const SUBAGENT: &str = "subagent";
    /// Rolling-history compaction passes.
    pub const COMPACTION: &str = "compaction";
    /// Async observational-memory observer runs.
    pub const OBSERVER: &str = "observer";
    /// Async observational-memory reflector runs.
    pub const REFLECTOR: &str = "reflector";
    /// Default fallback when no `usage_source` is set on a child session.
    pub const CHILD: &str = "child";
}