Account State Tracking

Relevant source files

The following files were used as context for generating this wiki page:

• src/account-state-store.ts
• dashboard/views/overview/accounts/sections.ts
• README.md
• src/AGENTS.md
• test/suites/entries/smoke/parts/billing/source/copy-sweep.ts
• README_EN.md

Account State Tracking maintains the persistence and classification of Freebuff account data within the proxy. It monitors account health, usage statistics, and quota availability to drive the scheduling engine. The system records metrics such as request counts, cooldown states, and Freebucks balances to ensure efficient multi-account pooling.

The tracking logic persists data to /data/account-state.json, allowing account states to survive service restarts. This historical data informs the web console's overview and guides the scheduler in picking accounts that are not banned or rate-limited.

Sources: src/account-state-store.ts:8-17, README.md:92-100, src/AGENTS.md:61-68

Data Persistence Architecture

The AccountStateStore class manages the lifecycle of the account ledger. It uses an atomic, debounced write mechanism to save data without blocking request forwarding.

Storage Mechanics

• Debounced Writes: The store aggregates multiple state changes and writes to disk after a 800ms delay to reduce I/O overhead.
• Atomic Saves: Files are saved using a temporary file and renamed (tmp + rename) with 0o600 permissions to prevent data corruption.
• Initialization: Upon startup, the system loads the JSON ledger and populates the in-memory state. If the file is corrupt, it initializes an empty ledger to ensure the service remains operational.

Sources: src/account-state-store.ts:28-50, src/account-state-store.ts:182-200, src/account-state-store.ts:203-222

Account State Schema

The ledger tracks several critical fields for each account:

Field	Description
email	The account identifier.
firstSeenAt	ISO timestamp of when the account was first added.
bannedAt	Timestamp of when the account was detected as banned.
requests	Cumulative number of successful requests handled by the account.
scheduledMs	Total duration in milliseconds the account has spent in active sessions.
cooldowns	A map of model-specific or account-wide cooling states with expiry times.
freebucks	Real-time balance and pricing information returned from the upstream.

Sources: src/account-state-store.ts:10-16, src/account-state-store.ts:90-110

Account Lifecycle and Scheduling State

The system updates account records based on real-time feedback from upstream requests and session management.

Key State Transitions

1. Creation: When a new account key is detected (e.g., via browser login callback), account() initializes the record and sets importedAt.
2. Scheduling Update: recordScheduling() accumulates scheduledMs when a session concludes, distinguishing between high-frequency short requests and long-running sessions.
3. Credential Update: recordCredentialUpdate() tracks when tokens are refreshed without resetting the account's original importedAt timestamp.
4. Pruning: prune() removes records for accounts no longer present in the credentials directory, migrating historical data (like firstSeenAt) to new keys if the email matches.

Sources: src/account-state-store.ts:83-112, src/account-state-store.ts:121-131, src/account-state-store.ts:145-171

Frontend Classification and Health Mapping

The web console categorizes accounts based on their current state stored in the ledger. This classification determines which UI section an account appears in.

Classification Logic

The classifyAccount function evaluates account health in a "worst-first" priority:

1. Banned: Accounts with a bannedAt timestamp or an upstream banned error code.
2. Exhausted: Accounts where the daily Freebucks limit is reached or the balance is lower than the model price.
3. Low Balance: A warning state where the balance is below the lowBalanceThreshold (default 15 FB) but still sufficient for the current model.
4. Warning: Accounts currently in a cooldown period or having failed the last probe.
5. Active: Accounts with live sessions, in-flight requests, or successful historical usage.
6. Fresh: Newly added accounts with no usage history.

Sources: dashboard/views/overview/accounts/sections.ts:57-113

Quota and Billing Protections

Account tracking integrates with Freebucks billing logic. Since one admission buys a whole hour, the system marks accounts as "Active" even if the balance is zero, provided they are within a Paid Window (expiresAt > Date.now()). This prevents the UI from incorrectly labeling functional accounts as "Exhausted" during their prepaid hour.

Sources: dashboard/views/overview/accounts/sections.ts:77-90, test/suites/entries/smoke/parts/billing/source/copy-sweep.ts:147-160

API and Integration

The Account State is exposed via specific API endpoints for the dashboard and external monitoring.

Endpoint	Method	Purpose
/v1/freebuff/status	GET	Returns a snapshot of account health and session states.
/v1/freebuff/accounts	GET	Lists detailed account ledger data including cooldowns.
/api/overview	GET	Provides the dashboard with categorized account groups.

Sources: README_EN.md:121-125, dashboard/views/overview/accounts/sections.ts:223-228

Conclusion

Account State Tracking provides the data foundation for the proxy's reliability. By persisting historical performance and real-time quota data, it allows the scheduler to avoid unreliable accounts and enables the dashboard to provide clear visibility into account pool health. The use of paid-window detection ensures that billing semantics are accurately reflected in the tracking state.

Sources: src/account-state-store.ts:215-220, test/suites/entries/smoke/parts/billing/source/copy-sweep.ts:16-25