1. 1//! Spend-admission seam (docs/design/15-reliability.md). The agent loop asks the
2. 2//! gate before every paid dispatch and reports settled usage after; the
3. 3//! implementation lives above (vak-core) where the ledger, caps, and
4. 4//! pricing config exist. Budget denial is a typed Ask through the normal
5. 5//! approver channel — unattended surfaces auto-deny, silence means no.
6. 6
7. 7use vak_llm::Usage;
8. 8
9. 9pub struct SpendCheck<'a> {
10. 10 pub model: &'a str,
11. 11 /// Serving provider of the current frozen-ladder leg. Empty when the
12. 12 /// caller cannot know it (legacy fixtures).
13. 13 pub provider: &'a str,
14. 14 pub session_id: &'a str,
15. 15 /// Planning estimate of the next call's input size.
16. 16 pub est_input_tokens: u64,
17. 17 /// Reserved completion size (context policy max output).
18. 18 pub planned_output_tokens: u64,
19. 19}
20. 20
21. 21#[async_trait::async_trait]
22. 22pub trait SpendGate: Send + Sync {
23. 23 /// Err(reason) denies the dispatch. Denial routes through the approver
24. 24 /// once as a budget Ask before the run fails closed.
25. 25 async fn authorize(&self, check: &SpendCheck<'_>) -> Result<(), String>;
26. 26
27. 27 /// A settled dispatch: record it against run/day windows. `provider`
28. 28 /// attributes the spend to the serving leg for per-provider FinOps
29. 29 /// rollups.
30. 30 fn record_settled(&self, provider: &str, model: &str, session_id: &str, usage: &Usage);
31. 31
32. 32 fn record_settled_with_latency(
33. 33 &self,
34. 34 provider: &str,
35. 35 model: &str,
36. 36 session_id: &str,
37. 37 usage: &Usage,
38. 38 _latency_ms: u64,
39. 39 ) {
40. 40 self.record_settled(provider, model, session_id, usage);
41. 41 }
42. 42
43. 43 /// The approver accepted the budget Ask: lift the cap for the REST of
44. 44 /// this run (raise-cap-once semantics, docs/design/15-reliability.md). Default no-op
45. 45 /// for gates without run state.
46. 46 fn on_budget_approved(&self) {}
47. 47}
48. 48