7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
quota observability (#344)
Ashutosh Sahoo4ab13001e88b
diff --git a/client/src/pages/KeysPage.tsx b/client/src/pages/KeysPage.tsxindex 96282f9f..d29e9b1f 100644--- a/client/src/pages/KeysPage.tsx+++ b/client/src/pages/KeysPage.tsx@@ -8,7 +8,7 @@ import { Label } from '@/components/ui/label'import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'import { Switch } from '@/components/ui/switch'import { PageHeader } from '@/components/page-header'-import type { ApiKey, Platform } from '../../../shared/types'+import type { ApiKey, Platform, ProviderQuotaState } from '../../../shared/types'import { Pencil, ExternalLink, Globe } from 'lucide-react'import { formatSqliteUtcToLocalTime } from '@/lib/utils'import { useI18n } from '@/i18n'@@ -109,6 +109,55 @@ interface HealthPlatform {interface HealthData {platforms: HealthPlatform[]keys: { id: number; platform: string; status: string; lastCheckedAt: string | null }[]+ quotaStates: ProviderQuotaState[]+}++function formatQuotaNumber(value: number | null): string {+ return value == null ? '—' : new Intl.NumberFormat().format(value)+}++function formatResetAt(value: string | null): string {+ if (!value) return '—'+ const date = new Date(value)+ return Number.isNaN(date.getTime()) ? '—' : date.toLocaleString()+}++function QuotaSignalsSection({ states }: { states: ProviderQuotaState[] }) {+ return (+ <section>+ <h2 className="text-sm font-medium mb-3">Quota signals</h2>+ {states.length === 0 ? (+ <div className="rounded-3xl border border-dashed p-6 text-sm text-muted-foreground bg-card">+ No quota observations yet. The dashboard will fill in after providers return headers, quota errors, or validation signals.+ </div>+ ) : (+ <div className="rounded-3xl border divide-y bg-card overflow-hidden">+ {states.map((state) => (+ <div key={`${state.platform}:${state.keyId}:${state.quotaPoolKey}:${state.metric}`} className="px-4 py-3.5 text-sm">+ <div className="flex flex-wrap items-center gap-x-3 gap-y-1">+ <span className="font-medium">{state.platform}</span>+ <span className="text-muted-foreground">key #{state.keyId}</span>+ <span className="text-muted-foreground">pool {state.quotaPoolKey}</span>+ <span className="text-xs px-2 py-0.5 rounded-full bg-muted text-muted-foreground">{state.metric}</span>+ <span className="ml-auto text-xs text-muted-foreground">+ {state.source} · {Math.round(state.confidence * 100)}%+ </span>+ </div>+ <div className="mt-2 grid gap-2 text-xs text-muted-foreground sm:grid-cols-2 lg:grid-cols-4">+ <div><span className="text-foreground">Limit</span> {formatQuotaNumber(state.limit)}</div>+ <div><span className="text-foreground">Remaining</span> {formatQuotaNumber(state.remaining)}</div>+ <div><span className="text-foreground">Reset</span> {formatResetAt(state.resetAt)}</div>+ <div><span className="text-foreground">Observed</span> {formatSqliteUtcToLocalTime(state.observedAt, { hour: '2-digit', minute: '2-digit' })}</div>+ </div>+ {state.notes && (+ <p className="mt-2 text-xs text-muted-foreground">{state.notes}</p>+ )}+ </div>+ ))}+ </div>+ )}+ </section>+ )}function UnifiedKeySection() {@@ -672,6 +721,8 @@ export default function KeysPage() {{tab === 'providers' && (<>+ <QuotaSignalsSection states={(healthData?.quotaStates ?? []).slice(0, 24)} />+<section><h2 className="text-sm font-medium mb-3">{t('keys.addProvider')}</h2><form onSubmit={handleSubmit} className="flex flex-wrap gap-3 rounded-3xl border p-4 bg-card">diff --git a/package-lock.json b/package-lock.jsonindex 06a1c725..665ef193 100644--- a/package-lock.json+++ b/package-lock.json@@ -1238,7 +1238,6 @@"os": ["aix"],- "peer": true,"engines": {"node": ">=18"}@@ -1255,7 +1254,6 @@"os": ["android"],- "peer": true,"engines": {"node": ">=18"}@@ -1272,7 +1270,6 @@"os": ["android"],- "peer": true,"engines": {"node": ">=18"}@@ -1289,7 +1286,6 @@"os": ["android"],- "peer": true,"engines": {"node": ">=18"}@@ -1306,7 +1302,6 @@"os": ["darwin"],- "peer": true,"engines": {"node": ">=18"}@@ -1323,7 +1318,6 @@"os": ["darwin"],- "peer": true,"engines": {"node": ">=18"}@@ -1340,7 +1334,6 @@"os": ["freebsd"],- "peer": true,"engines": {"node": ">=18"}@@ -1357,7 +1350,6 @@"os": ["freebsd"],- "peer": true,"engines": {"node": ">=18"}@@ -1374,7 +1366,6 @@"os": ["linux"],- "peer": true,"engines": {"node": ">=18"}@@ -1391,7 +1382,6 @@"os": ["linux"],- "peer": true,"engines": {"node": ">=18"}@@ -1408,7 +1398,6 @@"os": ["linux"],- "peer": true,"engines": {"node": ">=18"}@@ -1425,7 +1414,6 @@"os": ["linux"],- "peer": true,"engines": {"node": ">=18"}@@ -1442,7 +1430,6 @@"os": ["linux"],- "peer": true,"engines": {"node": ">=18"}@@ -1459,7 +1446,6 @@"os": ["linux"],- "peer": true,"engines": {"node": ">=18"}@@ -1476,7 +1462,6 @@"os": ["linux"],- "peer": true,"engines": {"node": ">=18"}@@ -1493,7 +1478,6 @@"os": ["linux"],- "peer": true,"engines": {"node": ">=18"}@@ -1510,7 +1494,6 @@"os": ["linux"],- "peer": true,"engines": {"node": ">=18"}@@ -1527,7 +1510,6 @@"os": ["netbsd"],- "peer": true,"engines": {"node": ">=18"}@@ -1544,7 +1526,6 @@"os": ["netbsd"],- "peer": true,"engines": {"node": ">=18"}@@ -1561,7 +1542,6 @@"os": ["openbsd"],- "peer": true,"engines": {"node": ">=18"}@@ -1578,7 +1558,6 @@"os": ["openbsd"],- "peer": true,"engines": {"node": ">=18"}@@ -1595,7 +1574,6 @@"os": ["openharmony"],- "peer": true,"engines": {"node": ">=18"}@@ -1612,7 +1590,6 @@"os": ["sunos"],- "peer": true,"engines": {"node": ">=18"}@@ -1629,7 +1606,6 @@"os": ["win32"],- "peer": true,"engines": {"node": ">=18"}@@ -1646,7 +1622,6 @@"os": ["win32"],- "peer": true,"engines": {"node": ">=18"}@@ -1663,7 +1638,6 @@"os": ["win32"],- "peer": true,"engines": {"node": ">=18"}diff --git a/server/src/db/migrations.ts b/server/src/db/migrations.tsindex 0f659aba..abee479f 100644--- a/server/src/db/migrations.ts+++ b/server/src/db/migrations.ts@@ -173,6 +173,50 @@ function createTables(db: Database.Database) {CREATE INDEX IF NOT EXISTS idx_rate_limit_usage_lookup ON rate_limit_usage(platform, model_id, key_id, kind, created_at_ms);CREATE INDEX IF NOT EXISTS idx_rate_limit_cooldowns_expires ON rate_limit_cooldowns(expires_at_ms);CREATE INDEX IF NOT EXISTS idx_api_keys_platform ON api_keys(platform);++ CREATE TABLE IF NOT EXISTS provider_quota_state (+ platform TEXT NOT NULL,+ key_id INTEGER NOT NULL,+ quota_pool_key TEXT NOT NULL,+ metric TEXT NOT NULL,+ limit_value INTEGER,+ remaining_value INTEGER,+ reset_at TEXT,+ reset_strategy TEXT NOT NULL DEFAULT 'unknown',+ source TEXT NOT NULL DEFAULT 'probe',+ confidence REAL NOT NULL DEFAULT 0,+ notes TEXT,+ observed_at TEXT NOT NULL DEFAULT (datetime('now')),+ updated_at TEXT NOT NULL DEFAULT (datetime('now')),+ PRIMARY KEY (platform, key_id, quota_pool_key, metric)+ );+ CREATE INDEX IF NOT EXISTS idx_provider_quota_state_platform ON provider_quota_state(platform, key_id, updated_at);+ CREATE INDEX IF NOT EXISTS idx_provider_quota_state_reset_at ON provider_quota_state(reset_at);++ CREATE TABLE IF NOT EXISTS provider_quota_observations (+ id TEXT PRIMARY KEY,+ platform TEXT NOT NULL,+ key_id INTEGER NOT NULL,+ provider_account_id TEXT,+ model_id TEXT,+ quota_pool_key TEXT NOT NULL,+ metric TEXT NOT NULL,+ status_code INTEGER,+ limit_value INTEGER,+ remaining_value INTEGER,+ reset_at TEXT,+ retry_after_ms INTEGER,+ reset_strategy TEXT NOT NULL DEFAULT 'unknown',+ source TEXT NOT NULL DEFAULT 'probe',+ confidence REAL NOT NULL DEFAULT 0,+ notes TEXT,+ raw_json TEXT,+ endpoint TEXT,+ observed_at TEXT NOT NULL DEFAULT (datetime('now')),+ created_at TEXT NOT NULL DEFAULT (datetime('now'))+ );+ CREATE INDEX IF NOT EXISTS idx_provider_quota_observations_platform ON provider_quota_observations(platform, key_id, observed_at);+ CREATE INDEX IF NOT EXISTS idx_provider_quota_observations_reset_at ON provider_quota_observations(reset_at);`);ensureRequestKeyIdColumn(db);diff --git a/server/src/providers/base.ts b/server/src/providers/base.tsindex 85cc638c..104ac13c 100644--- a/server/src/providers/base.ts+++ b/server/src/providers/base.ts@@ -6,6 +6,7 @@ import type {ChatToolChoice,Platform,} from '@freellmapi/shared/types.js';+import type { QuotaObservationContext } from '../services/provider-quota.js';import { proxyFetch } from '../lib/proxy.js';/** A provider HTTP error carrying the upstream status and, when the response@@ -66,6 +67,7 @@ export abstract class BaseProvider {messages: ChatMessage[],modelId: string,options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,): Promise<ChatCompletionResponse>;abstract streamChatCompletion(@@ -73,9 +75,10 @@ export abstract class BaseProvider {messages: ChatMessage[],modelId: string,options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,): AsyncGenerator<ChatCompletionChunk>;- abstract validateKey(apiKey: string): Promise<boolean>;+ abstract validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean>;protected async fetchWithTimeout(url: string,diff --git a/server/src/providers/cloudflare.ts b/server/src/providers/cloudflare.tsindex 94f0a0b0..cf1eabdc 100644--- a/server/src/providers/cloudflare.ts+++ b/server/src/providers/cloudflare.ts@@ -5,6 +5,7 @@ import type {} from '@freellmapi/shared/types.js';import { BaseProvider, providerHttpError, type CompletionOptions } from './base.js';import { contentToString } from '../lib/content.js';+import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';/*** Cloudflare Workers AI provider.@@ -34,6 +35,7 @@ export class CloudflareProvider extends BaseProvider {messages: ChatMessage[],modelId: string,options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,): Promise<ChatCompletionResponse> {const { accountId, token } = this.parseKey(apiKey);const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1/chat/completions`;@@ -55,6 +57,14 @@ export class CloudflareProvider extends BaseProvider {parallel_tool_calls: options?.parallel_tool_calls,}),});+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'chat/completions',+ });if (!res.ok) {const err = await res.json().catch(() => ({}));@@ -71,6 +81,7 @@ export class CloudflareProvider extends BaseProvider {messages: ChatMessage[],modelId: string,options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,): AsyncGenerator<ChatCompletionChunk> {const { accountId, token } = this.parseKey(apiKey);const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1/chat/completions`;@@ -93,6 +104,14 @@ export class CloudflareProvider extends BaseProvider {stream: true,}),});+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'chat/completions',+ });if (!res.ok) {const err = await res.json().catch(() => ({}));@@ -102,7 +121,7 @@ export class CloudflareProvider extends BaseProvider {yield* this.readSseStream(res);}- async validateKey(apiKey: string): Promise<boolean> {+ async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean> {// Transport errors propagate — health.ts marks status='error' without// counting toward auto-disable. Only confirmed bad/inactive tokens disable.const { accountId, token } = this.parseKey(apiKey);@@ -114,12 +133,14 @@ export class CloudflareProvider extends BaseProvider {const userResult = await this.verifyAt('https://api.cloudflare.com/client/v4/user/tokens/verify',token,+ quotaContext,);if (userResult !== 'auth-failed') return userResult;const accountResult = await this.verifyAt(`https://api.cloudflare.com/client/v4/accounts/${accountId}/tokens/verify`,token,+ quotaContext,);if (accountResult === 'auth-failed') return false;return accountResult;@@ -128,12 +149,20 @@ export class CloudflareProvider extends BaseProvider {// Hits a Cloudflare token-verify endpoint. Returns true/false for a definitive// active/inactive verdict, or 'auth-failed' when the token lacks access to// THIS endpoint (401/403) so the caller can try the other scope.- private async verifyAt(url: string, token: string): Promise<boolean | 'auth-failed'> {+ private async verifyAt(url: string, token: string, quotaContext?: QuotaObservationContext): Promise<boolean | 'auth-failed'> {const res = await this.fetchWithTimeout(url,{ method: 'GET', headers: { 'Authorization': `Bearer ${token}` } },10000,);+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId: quotaContext?.modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'tokens/verify',+ });if (res.status === 401 || res.status === 403) return 'auth-failed';if (!res.ok) return true; // unexpected non-2xx that isn't auth — don't disableconst data = await res.json() as any;diff --git a/server/src/providers/cohere.ts b/server/src/providers/cohere.tsindex b5903d06..ab1728e6 100644--- a/server/src/providers/cohere.ts+++ b/server/src/providers/cohere.ts@@ -6,6 +6,7 @@ import type {} from '@freellmapi/shared/types.js';import { BaseProvider, providerHttpError, type CompletionOptions } from './base.js';import { flattenMessageContent } from '../lib/content.js';+import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';import { stripSchemaKeys } from '../lib/tool-args.js';const API_BASE = 'https://api.cohere.ai/compatibility/v1';@@ -36,6 +37,7 @@ export class CohereProvider extends BaseProvider {messages: ChatMessage[],modelId: string,options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,): Promise<ChatCompletionResponse> {const body: Record<string, unknown> = {model: modelId,@@ -55,6 +57,14 @@ export class CohereProvider extends BaseProvider {},body: JSON.stringify(body),});+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'chat/completions',+ });if (!res.ok) {const err = await res.json().catch(() => ({}));@@ -71,6 +81,7 @@ export class CohereProvider extends BaseProvider {messages: ChatMessage[],modelId: string,options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,): AsyncGenerator<ChatCompletionChunk> {const body: Record<string, unknown> = {model: modelId,@@ -91,6 +102,14 @@ export class CohereProvider extends BaseProvider {},body: JSON.stringify(body),});+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'chat/completions',+ });if (!res.ok) {const err = await res.json().catch(() => ({}));@@ -100,13 +119,21 @@ export class CohereProvider extends BaseProvider {yield* this.readSseStream(res);}- async validateKey(apiKey: string): Promise<boolean> {+ async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean> {// Transport errors propagate — health.ts marks status='error' without// counting toward auto-disable. Only confirmed 401/403 disables a key.const res = await this.fetchWithTimeout(`${API_BASE}/models`, {method: 'GET',headers: { 'Authorization': `Bearer ${apiKey}` },}, 10000);+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId: quotaContext?.modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'models',+ });return res.status !== 401 && res.status !== 403;}}diff --git a/server/src/providers/google.ts b/server/src/providers/google.tsindex e0f8882c..ec3004fd 100644--- a/server/src/providers/google.ts+++ b/server/src/providers/google.ts@@ -10,6 +10,7 @@ import type {import { BaseProvider, providerHttpError, type CompletionOptions } from './base.js';import { contentToString } from '../lib/content.js';import { proxyFetch } from '../lib/proxy.js';+import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';const API_BASE = 'https://generativelanguage.googleapis.com/v1beta';@@ -391,6 +392,7 @@ export class GoogleProvider extends BaseProvider {messages: ChatMessage[],modelId: string,options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,): Promise<ChatCompletionResponse> {const { contents, systemInstruction } = await toGeminiContents(messages);@@ -416,6 +418,15 @@ export class GoogleProvider extends BaseProvider {body: JSON.stringify(body),});+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'chat/completions',+ });+if (!res.ok) {const err = await res.json().catch(() => ({}));throw providerHttpError(res, `Google API error ${res.status}: ${(err as any).error?.message ?? res.statusText}`);@@ -457,6 +468,7 @@ export class GoogleProvider extends BaseProvider {messages: ChatMessage[],modelId: string,options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,): AsyncGenerator<ChatCompletionChunk> {const { contents, systemInstruction } = await toGeminiContents(messages);@@ -480,6 +492,15 @@ export class GoogleProvider extends BaseProvider {body: JSON.stringify(body),});+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'chat/completions',+ });+if (!res.ok) {const err = await res.json().catch(() => ({}));throw providerHttpError(res, `Google API error ${res.status}: ${(err as any).error?.message ?? res.statusText}`);@@ -597,7 +618,7 @@ export class GoogleProvider extends BaseProvider {}}- async validateKey(apiKey: string): Promise<boolean> {+ async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean> {// Transport errors propagate — health.ts marks status='error' without// counting toward auto-disable.const res = await this.fetchWithTimeout(@@ -605,6 +626,14 @@ export class GoogleProvider extends BaseProvider {{ method: 'GET' },10000,);+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId: quotaContext?.modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'models',+ });if (res.ok) return true;// Google's error taxonomy is NOT the usual 401/403-means-bad-key (#268):diff --git a/server/src/providers/openai-compat.ts b/server/src/providers/openai-compat.tsindex f430fd29..86caae9c 100644--- a/server/src/providers/openai-compat.ts+++ b/server/src/providers/openai-compat.ts@@ -8,6 +8,7 @@ import type {import { BaseProvider, providerHttpError, type CompletionOptions } from './base.js';import { rescueInlineToolCalls } from '../lib/tool-call-rescue.js';import { repairToolArguments, toolSchemaMap } from '../lib/tool-args.js';+import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';/*** Generic provider for platforms that use an OpenAI-compatible API.@@ -95,6 +96,7 @@ export class OpenAICompatProvider extends BaseProvider {messages: ChatMessage[],modelId: string,options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,): Promise<ChatCompletionResponse> {const res = await this.fetchWithTimeout(`${this.baseUrl}/chat/completions`, {method: 'POST',@@ -115,6 +117,15 @@ export class OpenAICompatProvider extends BaseProvider {}),}, options?.timeoutMs ?? this.timeoutMs);+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'chat/completions',+ });+if (!res.ok) {const err = await res.json().catch(() => ({}));const rescued = this.rescueFailedGeneration(err, options);@@ -157,6 +168,7 @@ export class OpenAICompatProvider extends BaseProvider {messages: ChatMessage[],modelId: string,options?: CompletionOptions,+ quotaContext?: QuotaObservationContext,): AsyncGenerator<ChatCompletionChunk> {const res = await this.fetchWithTimeout(`${this.baseUrl}/chat/completions`, {method: 'POST',@@ -178,6 +190,15 @@ export class OpenAICompatProvider extends BaseProvider {}),}, this.timeoutMs);+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ modelId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'chat/completions',+ });+if (!res.ok) {const err = await res.json().catch(() => ({}));const rescued = this.rescueFailedGeneration(err, options);@@ -195,7 +216,7 @@ export class OpenAICompatProvider extends BaseProvider {yield* this.readSseStream(res);}- async validateKey(apiKey: string): Promise<boolean> {+ async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean> {// Note: transport errors (DNS / timeout / TLS) propagate to the caller.// health.ts catches them and marks status='error' WITHOUT incrementing// the consecutive-failure counter — only confirmed 401/403 disables a key.@@ -212,6 +233,13 @@ export class OpenAICompatProvider extends BaseProvider {...this.extraHeaders,},}, 30000);+ recordQuotaObservationsFromResponse(res, {+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'models',+ });return res.status !== 401 && res.status !== 403;}}diff --git a/server/src/routes/health.ts b/server/src/routes/health.tsindex 171ad835..79aa9bdc 100644--- a/server/src/routes/health.ts+++ b/server/src/routes/health.ts@@ -3,6 +3,7 @@ import type { Request, Response } from 'express';import { getDb } from '../db/index.js';import { checkKeyHealth, checkAllKeys } from '../services/health.js';import { hasProvider } from '../providers/index.js';+import { getQuotaStateForKeys } from '../services/provider-quota.js';export const healthRouter = Router();@@ -51,6 +52,7 @@ healthRouter.get('/', (_req: Request, res: Response) => {createdAt: k.created_at,lastCheckedAt: k.last_checked_at,})),+ quotaStates: getQuotaStateForKeys(),});});diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.tsindex 6e5a5173..6748c09b 100644--- a/server/src/routes/proxy.ts+++ b/server/src/routes/proxy.ts@@ -16,6 +16,8 @@ import { getContextHandoffMode, recordIncomingMessages, maybeInjectContextHandofimport { isFusionModel, runFusion, fusionConfigSchema, FusionError, FUSION_MODEL_ID } from '../services/fusion.js';import { isRetryableError, isPaymentRequiredError, isModelNotFoundError, isModelAccessForbiddenError } from '../lib/error-classify.js';import { logRequest } from '../lib/request-log.js';+import type { Platform } from '@freellmapi/shared/types.js';+import { inferQuotaPoolKey, type QuotaObservationContext } from '../services/provider-quota.js';import { isUnifyEnabled, getModelGroups, resolveRequestedIdToMembers } from '../services/model-groups.js';import { buildModelListing } from '../services/model-listing.js';@@ -63,6 +65,17 @@ export function extractApiToken(req: Request): string | undefined {return trimmed || undefined;}+function quotaContextForRoute(route: RouteResult, endpoint: string): QuotaObservationContext {+ return {+ platform: route.platform as Platform,+ keyId: route.keyId,+ modelId: route.modelId,+ quotaPoolKey: inferQuotaPoolKey(route.platform as Platform, route.modelId),+ endpoint,+ origin: 'proxy',+ };+}+export function getRequestGroupId(req: Request): string {const raw = req.headers['x-request-id'];const value = Array.isArray(raw) ? raw[0] : raw;@@ -1003,6 +1016,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {const gen = route.provider.streamChatCompletion(route.apiKey, outboundMessages, route.modelId,{ temperature, max_tokens, top_p, tools, tool_choice, parallel_tool_calls },+ quotaContextForRoute(route, 'chat/completions'),);for await (const chunk of gen) {@@ -1200,6 +1214,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {const result = await route.provider.chatCompletion(route.apiKey, outboundMessages, route.modelId,{ temperature, max_tokens, top_p, tools, tool_choice, parallel_tool_calls },+ quotaContextForRoute(route, 'chat/completions'),);// Empty completion (no text, no tool calls) → fail over rather thandiff --git a/server/src/routes/responses.ts b/server/src/routes/responses.tsindex c8936d74..14ff2b1a 100644--- a/server/src/routes/responses.ts+++ b/server/src/routes/responses.ts@@ -7,6 +7,7 @@ import type {ChatToolCall,ChatToolDefinition,ChatToolChoice,+ Platform,} from '@freellmapi/shared/types.js';import { routeRequest, recordRateLimitHit, recordSuccess, hasEnabledToolsModel, type RouteResult } from '../services/router.js';import { recordRequest, recordTokens, setCooldown, getCooldownDurationForLimit, PAYMENT_REQUIRED_COOLDOWN_MS, learnLimitFromError } from '../services/ratelimit.js';@@ -28,6 +29,7 @@ import {logRequest,} from './proxy.js';import { sanitizeProviderErrorMessage } from '../lib/error-redaction.js';+import { inferQuotaPoolKey, type QuotaObservationContext } from '../services/provider-quota.js';export const responsesRouter = Router();@@ -264,6 +266,17 @@ export function buildResponseObject(opts: {};}+function quotaContextForRoute(route: RouteResult, endpoint: string): QuotaObservationContext {+ return {+ platform: route.platform as Platform,+ keyId: route.keyId,+ modelId: route.modelId,+ quotaPoolKey: inferQuotaPoolKey(route.platform as Platform, route.modelId),+ endpoint,+ origin: 'responses',+ };+}+responsesRouter.post('/responses', async (req: Request, res: Response) => {const start = Date.now();const requestGroupId = getRequestGroupId(req);@@ -419,7 +432,13 @@ responsesRouter.post('/responses', async (req: Request, res: Response) => {}};- const gen = route.provider.streamChatCompletion(route.apiKey, messages, route.modelId, completionOpts);+ const gen = route.provider.streamChatCompletion(+ route.apiKey,+ messages,+ route.modelId,+ completionOpts,+ quotaContextForRoute(route, 'responses'),+ );for await (const chunk of gen) {// In-band upstream error frame ({"error":...} inside a 200 SSE@@ -634,7 +653,13 @@ responsesRouter.post('/responses', async (req: Request, res: Response) => {logRequest(route.platform, route.modelId, route.keyId, 'success', estimatedInputTokens, totalOutputTokens, Date.now() - start, null);return;} else {- const result = await route.provider.chatCompletion(route.apiKey, messages, route.modelId, completionOpts);+ const result = await route.provider.chatCompletion(+ route.apiKey,+ messages,+ route.modelId,+ completionOpts,+ quotaContextForRoute(route, 'responses'),+ );const msg = result.choices[0]?.message;let text = contentToString(msg?.content ?? '');diff --git a/server/src/services/health.ts b/server/src/services/health.tsindex 00caecca..58cd0181 100644--- a/server/src/services/health.ts+++ b/server/src/services/health.ts@@ -2,6 +2,7 @@ import { getDb } from '../db/index.js';import { resolveProvider } from '../providers/index.js';import { decrypt } from '../lib/crypto.js';import type { Platform, KeyStatus } from '@freellmapi/shared/types.js';+import { inferQuotaPoolKey } from './provider-quota.js';const CHECK_INTERVAL_MS = 5 * 60 * 1000; // 5 minutesconst CONSECUTIVE_FAILURES_TO_DISABLE = 3;@@ -19,7 +20,13 @@ export async function checkKeyHealth(keyId: number): Promise<KeyStatus> {try {const apiKey = decrypt(row.encrypted_key, row.iv, row.auth_tag);- const isValid = await provider.validateKey(apiKey);+ const isValid = await provider.validateKey(apiKey, {+ platform: row.platform as Platform,+ keyId,+ quotaPoolKey: inferQuotaPoolKey(row.platform as Platform, null),+ endpoint: 'models',+ origin: 'health',+ });const status: KeyStatus = isValid ? 'healthy' : 'invalid';diff --git a/server/src/services/provider-quota.ts b/server/src/services/provider-quota.tsnew file mode 100644index 00000000..7025d270--- /dev/null+++ b/server/src/services/provider-quota.ts@@ -0,0 +1,441 @@+import crypto from 'crypto';+import { AsyncLocalStorage } from 'node:async_hooks';+import { getDb } from '../db/index.js';+import type {+ Platform,+ QuotaMetric,+ QuotaObservationSource,+ QuotaResetStrategy,+ ProviderQuotaObservation,+ ProviderQuotaState,+} from '@freellmapi/shared/types.js';++export interface QuotaObservationContext {+ platform: Platform;+ keyId?: number;+ providerAccountId?: string | null;+ modelId?: string | null;+ quotaPoolKey?: string | null;+ endpoint?: string | null;+ origin?: 'health' | 'proxy' | 'responses' | 'manual' | 'probe';+}++export interface QuotaObservationInput {+ platform?: Platform;+ keyId?: number;+ providerAccountId?: string | null;+ modelId?: string | null;+ quotaPoolKey?: string | null;+ metric?: QuotaMetric;+ limit?: number | null;+ remaining?: number | null;+ resetAt?: string | null;+ retryAfterMs?: number | null;+ resetStrategy?: QuotaResetStrategy;+ source?: QuotaObservationSource;+ statusCode?: number | null;+ notes?: string | null;+ rawJson?: string | null;+ endpoint?: string | null;+ confidence?: number;+ observedAt?: string;+}++export interface QuotaObservationView extends ProviderQuotaState {+ providerAccountId: string | null;+ modelId: string | null;+ endpoint: string | null;+ statusCode: number | null;+ retryAfterMs: number | null;+ rawJson: string | null;+ createdAt: string;+}++const contextStore = new AsyncLocalStorage<QuotaObservationContext>();++const DEFAULT_CONFIDENCE: Record<QuotaObservationSource, number> = {+ header: 1,+ quota_api: 1,+ error_body: 0.75,+ local_usage: 0.45,+ documentation: 0.35,+ probe: 0.6,+};++const SOURCE_PRIORITY: Record<QuotaObservationSource, number> = {+ header: 5,+ quota_api: 5,+ error_body: 4,+ probe: 3,+ local_usage: 2,+ documentation: 1,+};++export function runWithQuotaObservationContext<T>(context: QuotaObservationContext, fn: () => T): T {+ return contextStore.run(context, fn);+}++export function getQuotaObservationContext(): QuotaObservationContext | undefined {+ return contextStore.getStore();+}++function isoNow(): string {+ return new Date().toISOString();+}++function toSqliteUtc(value: Date | string | number): string {+ const date = value instanceof Date ? value : new Date(value);+ return date.toISOString().replace('T', ' ').replace('Z', '');+}++function parseHeaderNumber(raw: string | null): number | null {+ if (!raw) return null;+ const n = Number(raw.trim());+ return Number.isFinite(n) ? n : null;+}++function parseResetAtFromHeader(raw: string | null, now = Date.now()): string | null {+ const parsed = parseHeaderNumber(raw);+ if (parsed === null) return null;+ if (parsed > 1_000_000_000_000) return new Date(parsed).toISOString();+ if (parsed > 1_000_000_000) return new Date(parsed * 1000).toISOString();+ return new Date(now + parsed * 1000).toISOString();+}++function parseRetryAfterMs(raw: string | null): number | null {+ if (!raw) return null;+ const seconds = Number(raw.trim());+ if (Number.isFinite(seconds)) return Math.max(0, Math.round(seconds * 1000));+ const asDate = new Date(raw);+ const ms = asDate.getTime();+ if (Number.isNaN(ms)) return null;+ return Math.max(0, ms - Date.now());+}++function pickBetterSource(existing: QuotaObservationSource | null | undefined, next: QuotaObservationSource): QuotaObservationSource {+ if (!existing) return next;+ return SOURCE_PRIORITY[next] >= SOURCE_PRIORITY[existing] ? next : existing;+}++function inferPoolForPlatform(platform: Platform, modelId?: string | null): string {+ const normalizedModelId = modelId?.trim() ?? '';+ if (platform === 'openrouter') return normalizedModelId.endsWith(':free') ? 'openrouter::free' : 'openrouter::account';+ if (platform === 'google') return 'google::project';+ if (platform === 'groq') return 'groq::account';+ if (platform === 'cerebras') return 'cerebras::shared';+ if (platform === 'sambanova') return 'sambanova::shared';+ if (platform === 'nvidia') return 'nvidia::credit-pool';+ if (platform === 'mistral') return 'mistral::experiment-pool';+ if (platform === 'github') return 'github::account';+ if (platform === 'cohere') return 'cohere::trial-pool';+ if (platform === 'cloudflare') return 'cloudflare::account';+ if (platform === 'zhipu') return 'zhipu::account';+ if (platform === 'ollama') return 'ollama::cloud';+ if (platform === 'kilo') return 'kilo::anonymous';+ if (platform === 'pollinations') return 'pollinations::anonymous';+ if (platform === 'llm7') return 'llm7::anonymous';+ if (platform === 'huggingface') return 'huggingface::router';+ if (platform === 'opencode') return 'opencode::promo';+ return normalizedModelId ? `${platform}::${normalizedModelId}` : `${platform}::account`;+}++function isSharedPool(platform: Platform): boolean {+ return ['openrouter', 'google', 'groq', 'cerebras', 'sambanova', 'nvidia', 'mistral', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama', 'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode'].includes(platform);+}++type HeaderSpec = { metric: QuotaMetric; limit: string; remaining?: string; reset?: string; strategy?: QuotaResetStrategy };++const HEADER_SPECS: Partial<Record<Platform, HeaderSpec[]>> = {+ groq: [+ { metric: 'requests', limit: 'x-ratelimit-limit-requests', remaining: 'x-ratelimit-remaining-requests', reset: 'x-ratelimit-reset-requests', strategy: 'provider_reported' },+ { metric: 'tokens', limit: 'x-ratelimit-limit-tokens', remaining: 'x-ratelimit-remaining-tokens', reset: 'x-ratelimit-reset-tokens', strategy: 'provider_reported' },+ ],+ cerebras: [+ { metric: 'requests', limit: 'x-ratelimit-limit-requests-day', remaining: 'x-ratelimit-remaining-requests-day', reset: 'x-ratelimit-reset-requests-day', strategy: 'provider_reported' },+ { metric: 'tokens', limit: 'x-ratelimit-limit-tokens-minute', remaining: 'x-ratelimit-remaining-tokens-minute', reset: 'x-ratelimit-reset-tokens-minute', strategy: 'token_bucket' },+ ],+ openrouter: [+ { metric: 'requests', limit: 'x-ratelimit-limit-requests', remaining: 'x-ratelimit-remaining-requests', reset: 'x-ratelimit-reset-requests', strategy: 'provider_reported' },+ { metric: 'tokens', limit: 'x-ratelimit-limit-tokens', remaining: 'x-ratelimit-remaining-tokens', reset: 'x-ratelimit-reset-tokens', strategy: 'provider_reported' },+ ],+};++function extractContext(opts: Pick<QuotaObservationInput, 'platform' | 'modelId' | 'quotaPoolKey' | 'keyId' | 'providerAccountId' | 'endpoint'> = {}) {+ const context = getQuotaObservationContext();+ const platform = opts.platform ?? context?.platform;+ if (!platform) return null;+ return {+ platform,+ keyId: opts.keyId ?? context?.keyId ?? 0,+ providerAccountId: opts.providerAccountId ?? context?.providerAccountId ?? null,+ modelId: opts.modelId ?? context?.modelId ?? null,+ quotaPoolKey: opts.quotaPoolKey ?? context?.quotaPoolKey ?? inferPoolForPlatform(platform, opts.modelId ?? context?.modelId),+ endpoint: opts.endpoint ?? context?.endpoint ?? null,+ };+}++function maybeAddObservation(+ observations: QuotaObservationInput[],+ base: NonNullable<ReturnType<typeof extractContext>>,+ metric: QuotaMetric,+ limitRaw: string | null,+ remainingRaw: string | null | undefined,+ resetRaw: string | null | undefined,+ strategy: QuotaResetStrategy,+): void {+ const limit = parseHeaderNumber(limitRaw);+ const remaining = parseHeaderNumber(remainingRaw ?? null);+ const resetAt = parseResetAtFromHeader(resetRaw ?? null);+ if (limit === null && remaining === null && resetAt === null) return;+ observations.push({+ ...base,+ metric,+ limit,+ remaining,+ resetAt,+ resetStrategy: strategy,+ source: 'header',+ confidence: 1,+ });+}++export function inferQuotaPoolKey(platform: Platform, modelId?: string | null): string {+ return inferPoolForPlatform(platform, modelId);+}++export function parseQuotaObservationsFromResponse(+ response: Response,+ opts: Pick<QuotaObservationInput, 'platform' | 'modelId' | 'quotaPoolKey' | 'keyId' | 'providerAccountId' | 'endpoint'> = {},+): QuotaObservationInput[] {+ const base = extractContext(opts);+ if (!base) return [];++ const headers = response.headers;+ const get = (name: string) => headers?.get?.(name) ?? null;+ const observations: QuotaObservationInput[] = [];+ const specs = HEADER_SPECS[base.platform];+ if (specs) {+ for (const spec of specs) {+ maybeAddObservation(observations, base, spec.metric, get(spec.limit), spec.remaining ? get(spec.remaining) : null, spec.reset ? get(spec.reset) : null, spec.strategy ?? 'provider_reported');+ }+ }++ const retryAfterMs = parseRetryAfterMs(get('retry-after'));+ if (retryAfterMs !== null) {+ observations.push({+ ...base,+ metric: 'requests',+ limit: parseHeaderNumber(get('x-ratelimit-limit-requests')),+ remaining: 0,+ resetAt: new Date(Date.now() + retryAfterMs).toISOString(),+ retryAfterMs,+ resetStrategy: 'provider_reported',+ source: response.status === 429 ? 'header' : 'error_body',+ confidence: response.status === 429 ? 1 : 0.8,+ notes: `retry-after=${retryAfterMs}ms`,+ });+ }++ if (response.status === 429 || response.status === 402) {+ observations.push({+ ...base,+ metric: 'requests',+ limit: parseHeaderNumber(get('x-ratelimit-limit-requests')),+ remaining: 0,+ resetAt: get('x-ratelimit-reset-requests') ? parseResetAtFromHeader(get('x-ratelimit-reset-requests')) : null,+ retryAfterMs,+ resetStrategy: 'unknown',+ source: 'error_body',+ confidence: 0.55,+ notes: response.status === 402 ? 'upstream payment/credit exhaustion' : 'rate limited',+ });+ }++ if (observations.length === 0 && isSharedPool(base.platform) && response.status === 200) {+ observations.push({+ ...base,+ metric: 'requests',+ limit: null,+ remaining: null,+ resetAt: null,+ resetStrategy: 'unknown',+ source: 'probe',+ confidence: 0.1,+ notes: 'no quota headers exposed',+ });+ }++ return observations;+}++export function recordQuotaObservation(input: QuotaObservationInput): ProviderQuotaObservation | null {+ const context = getQuotaObservationContext();+ const platform = input.platform ?? context?.platform;+ if (!platform) return null;++ const keyId = input.keyId ?? context?.keyId ?? 0;+ const quotaPoolKey = input.quotaPoolKey ?? context?.quotaPoolKey ?? inferPoolForPlatform(platform, input.modelId ?? context?.modelId);+ const metric = input.metric ?? 'requests';+ const source = input.source ?? 'probe';+ const resetStrategy = input.resetStrategy ?? 'unknown';+ const confidence = input.confidence ?? DEFAULT_CONFIDENCE[source];+ const observedAt = input.observedAt ?? isoNow();+ const limitValue = input.limit ?? null;+ const remainingValue = input.remaining ?? null;+ const resetAt = input.resetAt ?? null;+ const retryAfterMs = input.retryAfterMs ?? null;+ const notes = input.notes ?? null;+ const providerAccountId = input.providerAccountId ?? context?.providerAccountId ?? null;+ const modelId = input.modelId ?? context?.modelId ?? null;+ const endpoint = input.endpoint ?? context?.endpoint ?? null;+ const statusCode = input.statusCode ?? null;+ const rawJson = input.rawJson ?? null;+ let db;+ try {+ db = getDb();+ } catch {+ return null;+ }+ const id = crypto.randomUUID();+ const nowSql = toSqliteUtc(observedAt);+ const updatedAt = nowSql;++ const prev = db.prepare(`+ SELECT confidence, notes, source+ FROM provider_quota_state+ WHERE platform = ?+ AND key_id = ?+ AND quota_pool_key = ?+ AND metric = ?+ `).get(platform, keyId, quotaPoolKey, metric) as { confidence: number; notes: string | null; source: QuotaObservationSource } | undefined;++ const nextConfidence = Math.max(prev?.confidence ?? 0, confidence);+ const nextNotes = notes ?? prev?.notes ?? null;+ const nextSource = pickBetterSource(prev?.source, source);++ db.transaction(() => {+ db.prepare(`+ INSERT INTO provider_quota_state (+ platform, key_id, quota_pool_key, metric, limit_value, remaining_value,+ reset_at, reset_strategy, source, confidence, notes, observed_at, updated_at+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)+ ON CONFLICT(platform, key_id, quota_pool_key, metric) DO UPDATE SET+ limit_value = COALESCE(excluded.limit_value, provider_quota_state.limit_value),+ remaining_value = COALESCE(excluded.remaining_value, provider_quota_state.remaining_value),+ reset_at = COALESCE(excluded.reset_at, provider_quota_state.reset_at),+ reset_strategy = CASE+ WHEN excluded.reset_strategy != 'unknown' THEN excluded.reset_strategy+ ELSE provider_quota_state.reset_strategy+ END,+ confidence = MAX(provider_quota_state.confidence, excluded.confidence),+ notes = COALESCE(excluded.notes, provider_quota_state.notes),+ observed_at = excluded.observed_at,+ updated_at = datetime('now')+ `).run(+ platform, keyId, quotaPoolKey, metric, limitValue, remainingValue, resetAt, resetStrategy, source, nextConfidence, nextNotes, nowSql, updatedAt,+ );++ db.prepare(`+ UPDATE provider_quota_state+ SET source = ?+ WHERE platform = ?+ AND key_id = ?+ AND quota_pool_key = ?+ AND metric = ?+ `).run(nextSource, platform, keyId, quotaPoolKey, metric);++ db.prepare(`+ INSERT INTO provider_quota_observations (+ id, platform, key_id, provider_account_id, model_id, quota_pool_key, metric,+ status_code, limit_value, remaining_value, reset_at, retry_after_ms,+ reset_strategy, source, confidence, notes, raw_json, endpoint, observed_at, created_at+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)+ `).run(+ id, platform, keyId, providerAccountId, modelId, quotaPoolKey, metric,+ statusCode, limitValue, remainingValue, resetAt, retryAfterMs,+ resetStrategy, source, confidence, notes, rawJson, endpoint, nowSql, nowSql,+ );+ })();++ return {+ id,+ platform,+ keyId,+ providerAccountId,+ modelId,+ quotaPoolKey,+ metric,+ statusCode,+ limit: limitValue,+ remaining: remainingValue,+ resetAt,+ retryAfterMs,+ resetStrategy,+ source,+ confidence: nextConfidence,+ notes: nextNotes,+ observedAt: nowSql,+ updatedAt,+ endpoint,+ rawJson,+ createdAt: nowSql,+ };+}++export function recordQuotaObservationsFromResponse(+ response: Response,+ opts: Pick<QuotaObservationInput, 'platform' | 'modelId' | 'quotaPoolKey' | 'keyId' | 'providerAccountId' | 'endpoint'> = {},+): ProviderQuotaObservation[] {+ return parseQuotaObservationsFromResponse(response, opts)+ .map(recordQuotaObservation)+ .filter((row): row is ProviderQuotaObservation => row !== null);+}++export function getQuotaStateForKeys(): QuotaObservationView[] {+ let db;+ try {+ db = getDb();+ } catch {+ return [];+ }+ return db.prepare(`+ WITH latest AS (+ SELECT+ oq.*,+ ROW_NUMBER() OVER (+ PARTITION BY oq.platform, oq.key_id, oq.quota_pool_key, oq.metric+ ORDER BY oq.observed_at DESC, oq.created_at DESC+ ) AS rn+ FROM provider_quota_observations oq+ )+ SELECT+ pqs.platform,+ pqs.key_id AS keyId,+ pqs.quota_pool_key AS quotaPoolKey,+ pqs.metric,+ pqs.limit_value AS "limit",+ pqs.remaining_value AS remaining,+ pqs.reset_at AS resetAt,+ pqs.reset_strategy AS resetStrategy,+ pqs.source,+ pqs.confidence,+ pqs.notes,+ pqs.observed_at AS observedAt,+ pqs.updated_at AS updatedAt,+ NULL AS providerAccountId,+ latest.model_id AS modelId,+ latest.endpoint AS endpoint,+ latest.status_code AS statusCode,+ latest.retry_after_ms AS retryAfterMs,+ latest.raw_json AS rawJson,+ latest.created_at AS createdAt+ FROM provider_quota_state pqs+ LEFT JOIN latest+ ON latest.platform = pqs.platform+ AND latest.key_id = pqs.key_id+ AND latest.quota_pool_key = pqs.quota_pool_key+ AND latest.metric = pqs.metric+ AND latest.rn = 1+ ORDER BY pqs.platform ASC, pqs.key_id ASC, pqs.quota_pool_key ASC, pqs.metric ASC+ `).all() as QuotaObservationView[];+}diff --git a/shared/types.ts b/shared/types.tsindex dba39844..762734bc 100644--- a/shared/types.ts+++ b/shared/types.ts@@ -13,6 +13,7 @@ export type Platform =| 'cerebras'| 'nvidia'| 'mistral'+ | 'sambanova'| 'openrouter'| 'github'| 'cohere'@@ -312,3 +313,36 @@ export interface RateLimitStatus {available: boolean;nextResetAt: string | null;}++// ---- Provider Quota Observability ----++export type QuotaMetric = 'requests' | 'tokens' | 'credits' | 'neurons';+export type QuotaResetStrategy = 'fixed_calendar' | 'rolling_window' | 'token_bucket' | 'provider_reported' | 'unknown';+export type QuotaObservationSource = 'header' | 'quota_api' | 'error_body' | 'local_usage' | 'documentation' | 'probe';++export interface ProviderQuotaState {+ platform: Platform;+ keyId: number;+ quotaPoolKey: string;+ metric: QuotaMetric;+ limit: number | null;+ remaining: number | null;+ resetAt: string | null;+ resetStrategy: QuotaResetStrategy;+ source: QuotaObservationSource;+ confidence: number;+ notes: string | null;+ observedAt: string;+ updatedAt: string;+}++export interface ProviderQuotaObservation extends ProviderQuotaState {+ id: string;+ statusCode: number | null;+ retryAfterMs: number | null;+ providerAccountId: string | null;+ modelId: string | null;+ endpoint: string | null;+ rawJson: string | null;+ createdAt: string;+}