Architecture & Billing

Credits Tracking & Exhaustion Hard Interception

Decrypting agent/credits_tracker.py credit initialization, overspend cutoff & synthesized prompt mechanism
Core Decision Flow
📊 Figure 1-2-1: AIAgent Core Decision & Session Loop Control Flow

💳 1. Credits Initialization & Local Cache

To ensure user API consumption safety, a local balance alignment mechanism is implemented in agent/credits_tracker.py:

At session startup, seed_credits_at_session_start(agent) executes, fetching the latest balance via server-side OAuth authentication and writing it into SessionDB, preventing billing inaccuracies caused by cold-start network fluctuations.

Billing Backoff
📊 Figure 1-2-2: Billing Exception Validation, 429 Rate Limiting & Backoff Delay Sequence

🚫 2. Credit Exhaustion Hard Interception & User Prompt

When the local billing counter exceeds the available balance limit, credits_tracker intercepts before entering the LLM session loop:

  1. Forcibly raise BillingError with highlighted console indication.
  2. Graceful degradation prompt: Guide the user to switch back to a free local fallback model provider via /model, preventing the session from getting stuck in a loop.