Diagnostics & Quota Checking
Relevant source files
The following files were used as context for generating this wiki page:
Diagnostics & Quota Checking provides a unified system for monitoring provider availability, configuration status, and rate-limit consumption. The system centers on two CLI commands: doctor for system health and quota for usage tracking. These components interact with a local on-disk state to maintain usage snapshots and perform live network probes when data becomes stale.
Sources: packages/scoutline/src/commands/doctor.ts, packages/scoutline/src/commands/quota.ts
Quota Management System
The Quota system tracks remaining requests and tokens across multiple research providers. It normalizes disparate provider response shapes into a standard format consisting of named categories and standardized windows.
Quota Resolution Logic
When you request a quota report, the system follows a tiered resolution path. It attempts to read from a local snapshot before falling back to a live network probe.
The system considers a snapshot stale if the observedAt timestamp is older than 10 minutes (600,000ms).
Sources: packages/scoutline/src/lib/quota-store.ts:8-12, packages/scoutline/src/commands/quota.ts:79-110
Normalization and Window Building
The buildQuotaWindow function converts raw provider counts into normalized percentages. It ensures that remainingPercent is a finite number clamped between 0 and 100.
| Field | Type | Description |
|---|---|---|
used | number | Amount consumed in current window |
limit | number | Total capacity of current window |
remaining | number | Amount available |
remainingPercent | number | Percentage available (0-100) |
resetsAt | string | ISO-8601 timestamp of window reset |
Sources: packages/scoutline/src/capabilities/quota.ts:75-125
System Diagnostics (Doctor)
The doctor command performs health checks on the environment and provider connectivity. It generates a comprehensive report that includes Node.js compatibility, a capability matrix, and individual provider status.
Diagnostic Architecture
The diagnostics process aggregates metadata from provider descriptors and executes live connectivity probes.
Availability Classification
The system classifies provider availability into four distinct tiers based on probe outcomes and snapshot data.
| Class | Description |
|---|---|
ok | Configured and responding; sufficient quota remains |
exhausted | Fresh snapshot shows 0% remaining in a required category |
error | Probe failed (e.g., authentication failure, network error) |
unconfigured | Required environment variables or config keys are missing |
Sources: packages/scoutline/src/capabilities/diagnostics.ts:18-23
Quota Store and Persistence
The Quota Store manages state.json, which persists the latest observed quota data. This enables the CLI to report usage without making expensive network calls on every invocation.
Store Operations
- read(): Loads the
QuotaStatefrom the file system. It returns an empty state if the file is missing or corrupt. - writeObserved(id, data): Atomically updates a specific provider's snapshot. It preserves existing data for other providers.
- refreshQuotaSnapshots(): Orchestrates a parallel refresh of all configured providers. It ignores providers that are already fresh unless a force refresh is requested.
Sources: packages/scoutline/src/lib/quota-store.ts:98-150, packages/scoutline/src/lib/quota-store.ts:167-210
Data Structure: QuotaCategory
Each provider report consists of one or more QuotaCategory entries, typically "requests" or "tokens".
export interface QuotaCategory {
name: string;
unit: "requests" | "tokens" | "credits";
current: QuotaWindow;
weekly?: QuotaWindow;
toolUsage?: { tool: string; usage: number }[];
}
Sources: packages/scoutline/src/capabilities/quota.ts:25-32
Summary
The Diagnostics & Quota Checking system ensures research operations remain within limits while providing visibility into system health. By leveraging local persistence and standardized normalization, it offers high-performance tracking and actionable troubleshooting data for multi-provider investigative workflows.