hematite/agent/
economics.rs

1// ── Session Economics Tracking ───────────────────────────────────────────────
2
3use serde::Serialize;
4
5// ── Per-turn context budget ledger ────────────────────────────────────────────
6
7/// Token cost of a single tool result within a turn.
8#[derive(Debug, Clone)]
9pub struct ToolCost {
10    pub name: String,
11    /// Estimated tokens (result_chars / 4).
12    pub tokens: usize,
13}
14
15/// Per-turn breakdown of context consumed.
16/// Populated at turn end and surfaced in the SPECULAR panel.
17#[derive(Debug, Clone)]
18pub struct TurnBudget {
19    /// Actual input tokens charged this turn (precise — from API usage delta).
20    pub input_tokens: usize,
21    /// Actual output tokens generated this turn (precise — from API usage delta).
22    pub output_tokens: usize,
23    /// Estimated prior-history tokens (chars / 4) — context already present before this turn.
24    pub history_est: usize,
25    /// Per-tool result costs (estimated tokens from result length).
26    pub tool_costs: Vec<ToolCost>,
27    /// Context window fill percentage at turn end.
28    pub context_pct: u8,
29}
30
31impl TurnBudget {
32    /// Compact ledger string for the SPECULAR panel and /budget command.
33    pub fn render(&self) -> String {
34        let total = self.input_tokens + self.output_tokens;
35        let mut parts = Vec::new();
36
37        if self.history_est > 0 {
38            parts.push(format!("prior hist ~{}t", self.history_est));
39        }
40        for tc in &self.tool_costs {
41            parts.push(format!("{} ~{}t", tc.name, tc.tokens));
42        }
43        if self.output_tokens > 0 {
44            parts.push(format!("model out {}t", self.output_tokens));
45        }
46
47        let breakdown = if parts.is_empty() {
48            String::new()
49        } else {
50            format!("\n  {}", parts.join("  |  "))
51        };
52
53        format!(
54            "Context budget: +{}t this turn  ({}% ctx){}\n  \
55             Tip: large tool results are the most common cause of context pressure.",
56            total, self.context_pct, breakdown
57        )
58    }
59}
60
61/// Tracks token usage and tool calls for a session.
62pub struct SessionEconomics {
63    /// Input tokens accumulated across all calls.
64    pub input_tokens: usize,
65    /// Output tokens accumulated across all calls.
66    pub output_tokens: usize,
67    /// List of tool calls with name and success/fail status.
68    pub tools_used: Vec<ToolRecord>,
69}
70
71impl SessionEconomics {
72    /// Create a new empty economics tracker.
73    pub fn new() -> Self {
74        Self {
75            input_tokens: 0,
76            output_tokens: 0,
77            tools_used: Vec::new(),
78        }
79    }
80
81    /// Record a tool call.
82    pub fn record_tool(&mut self, name: &str, success: bool) {
83        self.tools_used.push(ToolRecord {
84            name: name.to_string(),
85            success,
86        });
87    }
88}
89
90impl Default for SessionEconomics {
91    fn default() -> Self {
92        Self {
93            input_tokens: 0,
94            output_tokens: 0,
95            tools_used: Vec::new(),
96        }
97    }
98}
99
100/// A record of a tool call.
101#[derive(Serialize, Clone, Debug)]
102pub struct ToolRecord {
103    pub name: String,
104    pub success: bool,
105}
106
107// ── Pricing constants ─────────────────────────────────────────────────────────
108
109/// Input token price: $0.002 per 1K tokens.
110pub const INPUT_PRICE_PER_1K: f64 = 0.002;
111
112/// Output token price: $0.006 per 1K tokens.
113pub const OUTPUT_PRICE_PER_1K: f64 = 0.006;
114
115// ── Report generation ────────────────────────────────────────────────────────
116
117impl SessionEconomics {
118    /// Calculate simulated cost based on token usage.
119    pub fn simulated_cost(&self) -> f64 {
120        let input_cost = (self.input_tokens as f64 / 1000.0) * INPUT_PRICE_PER_1K;
121        let output_cost = (self.output_tokens as f64 / 1000.0) * OUTPUT_PRICE_PER_1K;
122        input_cost + output_cost
123    }
124
125    /// Generate a JSON report of the session economics.
126    pub fn to_json(&self) -> String {
127        use serde_json::json;
128        json!({
129            "session_economics": {
130                "input_tokens": self.input_tokens,
131                "output_tokens": self.output_tokens,
132                "total_tokens": self.input_tokens + self.output_tokens,
133                "tools_used": self.tools_used.iter().map(|t| {
134                    json!({
135                        "name": t.name,
136                        "success": t.success
137                    })
138                }).collect::<Vec<_>>(),
139                "simulated_cost_usd": self.simulated_cost()
140            }
141        })
142        .to_string()
143    }
144}
hematite/agent/economics.rs

hematite/agent/
economics.rs
