Struct GoalAccounting 

pub struct GoalAccounting { /* private fields */ }

Per-turn token accounting service for the active long-horizon goal.

Wraps GoalStore with an in-memory cache of the active goal ID so that turns without an active goal incur no database round-trips.

Invariant (G4)

on_turn_complete is fire-and-forget. A DB write failure logs WARN and never aborts the turn. Budget exhaustion auto-pauses the goal via a best-effort background task.

Implementations

impl GoalAccounting

pub fn new(store: Arc<GoalStore>) -> Self

Create a new GoalAccounting backed by store.

pub async fn refresh(&self) -> Result<(), GoalError>

Refresh the in-memory cache from the database.

Call this after every /goal command to ensure the cache reflects the latest state before the next turn.

Errors

Returns GoalError if the database query fails.

pub fn snapshot(&self) -> Option<GoalSnapshot>

Build a lightweight snapshot of the cached active goal, if any.

Returns None when no goal is active (the goal was cleared, completed, paused, or never created).

pub fn on_turn_complete( &self, turn_tokens: u64, spawn_bg: impl FnOnce(Pin<Box<dyn Future<Output = ()> + Send + 'static>>), )

Notify the accounting service that a turn completed, consuming turn_tokens tokens.

If no active goal is cached, this is a cheap no-op (no DB access).

When a token budget is set and exceeded, the goal is auto-paused via a best-effort background task.

Background tasks are spawned via the provided closure so the caller controls how they are tracked (typically via the agent supervisor).

pub async fn get_active(&self) -> Result<Option<Goal>, GoalError>

Return a full Goal from the store for a given id.

Used by the /goal status handler to show live details.

Errors

Returns GoalError if the database query fails.

pub fn get_store(&self) -> Arc<GoalStore>

Return a reference to the underlying store for direct queries.