LLM/BrowserOS
1
0
Fork 0
mirror of https://github.com/browseros-ai/BrowserOS.git synced 2026-05-13 15:46:22 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
8548bcf50aaeae3560954716d1af7cad88c68f0e
BrowserOS/packages/browseros-agent/docs/plans/2026-03-19-credits-tracking-ui-design.md
shivammittal274 8548bcf50a feat: credit-based tracking for BrowserOS provider (#489) 
* feat: add credit-based tracking for BrowserOS provider

Send X-BrowserOS-ID header on all LLM requests through the BrowserOS
gateway for per-installation credit tracking. Handle 429 CREDITS_EXHAUSTED
as non-retryable. Add GET/PUT /credits endpoints to check and manage
credit balance.

* docs: add credits tracking UI design

Design for showing credit balance in side panel chat header (color-coded
badge) and a dedicated Usage & Billing settings page. Credits refresh
after each completed message turn or on exhaustion error.

* docs: add credits tracking UI implementation plan

8-task plan covering useCredits hook, CreditBadge component, ChatHeader
integration, message completion refresh, ChatError CREDITS_EXHAUSTED
handling, Usage & Billing settings page, and route/sidebar registration.

* feat: add useCredits React Query hook

* feat: add CreditBadge component with color thresholds

* feat: show credit badge in chat header for BrowserOS provider

* feat: refresh credits after chat message completion and on error

* feat: handle CREDITS_EXHAUSTED error in chat

* feat: add Usage & Billing settings page

* feat: register usage page route and sidebar entry

* fix: lint and formatting fixes for credit tracking UI

* fix: separate credits exhausted from Kimi rate limit in ChatError, redesign Usage page

* chore: remove PUT /credits endpoint and setCredits function

* fix: extract shared credit colors, add error state to UsagePage, use dailyLimit from gateway

* fix: make dailyLimit required in CreditsInfo (gateway always returns it)

* feat: gate credits UI behind CREDITS_SUPPORT feature flag (server >= 0.0.78)
2026-03-20 22:49:00 +05:30

2.3 KiB
Raw Blame History

Credits Tracking UI Design

Overview

Surface credit balance to users across two locations: a compact badge in the side panel chat header, and a dedicated Usage & Billing settings page. Credits refresh after each completed message turn or on error.

1. Side Panel — Credit Badge

Location: Chat header, next to provider selector. Only visible when provider is browseros.

Display:

  • Coin/credit icon + remaining count (e.g., "87")
  • Color-coded by threshold:
    • Green: >30 credits
    • Yellow/orange: 1–30 credits
    • Red: 0 credits
  • Clicking the badge navigates to the Usage & Billing settings page

Update triggers:

  • Message turn completes successfully (agent finishes all tool calls and responds)
  • CREDITS_EXHAUSTED error mid-turn (badge syncs to 0, error shown in chat)

2. Settings — Usage & Billing Page

Sidebar entry: "Usage & Billing" in the "Other" section (icon: CreditCard or Coins).

Route: /settings/usage

Content:

  • Credits card: large display of remaining credits (e.g., "87 / 100") with color-coded progress bar
  • Reset info: "Resets daily at midnight UTC" with last reset date
  • Credit cost: "1 credit per request"
  • Placeholder section: "Need more credits?" with disabled "Add Credits" button (future payment/recharge)

3. Data Flow

Hook: useCredits() — React Query hook fetching GET /credits from the agent server.

Refresh strategy:

  • Refetch after each completed message turn (onFinish callback in chat session)
  • Refetch on CREDITS_EXHAUSTED error
  • Refetch on window focus (React Query default)
  • No aggressive polling

State sharing: Credits query is global (React Query cache). Both side panel badge and settings page read from the same cache key.

4. Error Handling (0 credits)

When credits are exhausted mid-conversation:

  • Chat stream shows error via existing ChatError.tsx pattern: "Daily credits exhausted. Resets at midnight UTC." with link to Usage & Billing page
  • Header badge turns red (0 credits)
  • Chat input stays enabled — user can switch to a different provider

5. Future Hooks

  • "Add Credits" button on Usage & Billing page (currently disabled placeholder)
  • Payment integration will live entirely within the Usage & Billing page
  • Credit badge could show a "+" icon when balance is low, linking to recharge