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
feat(quota): provider-reported balance polling + manual poll endpoint (#1403) (#1414)
Tashfeenee085322e1c7
diff --git a/docs/en/CHANGELOG.md b/docs/en/CHANGELOG.mdindex c6e1f1de..dde13ce0 100644--- a/docs/en/CHANGELOG.md+++ b/docs/en/CHANGELOG.md@@ -4,6 +4,8 @@| Commit | Date | Summary || --- | --- | --- |+| _(via #1414)_ | 2026-10-04 | providers: quota polling — `BaseProvider.fetchQuota` / `quota_api` observations piggybacked on the health pass with a per-key 15-min throttle (issue #1403 phase 1); SiliconFlow `/v1/user/info` balance registered, string-encoded balances accepted |+| _(via #1414)_ | 2026-10-04 | health: `POST /api/health/quota/:keyId` — manual provider-balance poll that bypasses the 15-min throttle; `hasQuotaProbe` distinguishes specless platforms (400) from failing probes (#1403) || `ef1b9ce` | 2026-09-05 | language-switcher line on every page, root-README anchors fixed from inside docs/, cli config page path (#1167) || `eab992f` | 2026-09-02 | scaffold per-language en/ top-level (landed via #1164) || `eab992f` | 2026-09-02 | move English domains under en/ (17 domains) (landed via #1164) |diff --git a/docs/en/providers/02-quotas-and-cooldowns.md b/docs/en/providers/02-quotas-and-cooldowns.mdindex dee89c2d..6b4d8789 100644--- a/docs/en/providers/02-quotas-and-cooldowns.md+++ b/docs/en/providers/02-quotas-and-cooldowns.md@@ -63,6 +63,10 @@ Before #798, a provider that stated exactly when to come back got the same heuriOnly the number is kept — never the body — so nothing extra reaches logs or attempt traces. Tests: [`server/src/__tests__/providers/stated-retry.test.ts`](../../../server/src/__tests__/providers/stated-retry.test.ts).+## Provider-reported quota polling (#1403)++Headers and error bodies only show quota when a request happens to carry them. Providers with a **key-info endpoint** (OpenRouter's `GET /api/v1/key` returns the key's `limit` / `limit_remaining` credit balance; SiliconFlow's `GET /v1/user/info` returns the account's `totalBalance`/`balance` in CNY as numeric strings) can be asked directly, and now are: `BaseProvider.fetchQuota()` is an optional probe that records what the provider itself reports as a `source: 'quota_api'` observation (confidence 1.0). The health pass piggybacks the probe onto a **healthy** verdict only, per key at most once per 15 minutes (`QUOTA_POLL_INTERVAL_MS`), fire-and-forget and failure-silent: a quota probe that errors or times out says nothing about the key and never changes a health verdict. Providers register their endpoint as a `quotaProbe` spec (URL + the JSON fields carrying limit/remaining); a spec may omit `limitFields` when the provider reports only a balance. Providers without a spec pay zero network. This is what fills the dashboard's live balances for pools that send no token-level rate-limit headers, instead of the text-label guess `parseBudget` makes over catalog copy.+## Health checks must not burn metered quota (#882)Health runs a scheduled pass every 5 minutes (±20% jitter, keys validated more recently than 3.5 minutes skipped, default concurrency 8, ≥1s spacing between same-provider probes). That cadence is fine for free validation endpoints but poisonous where validation itself costs quota:diff --git a/server/src/__tests__/providers/quota-api-poll.test.ts b/server/src/__tests__/providers/quota-api-poll.test.tsnew file mode 100644index 00000000..0925d224--- /dev/null+++ b/server/src/__tests__/providers/quota-api-poll.test.ts@@ -0,0 +1,166 @@+import { describe, it, expect, vi, beforeEach, beforeAll } from 'vitest';+import { OpenAICompatProvider } from '../../providers/openai-compat.js';+import { initDb, getDb } from '../../db/index.js';+import { resolveProvider } from '../../providers/index.js';++// #1403 phase 1: quota_api observations from a provider key-info endpoint.+beforeAll(() => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ initDb(':memory:');+});++function makeProvider(spec?: {+ url: string; metric: 'credits'; limitFields: string[]; remainingFields: string[]; notes?: string;+}) {+ return new OpenAICompatProvider({+ platform: 'openrouter',+ name: 'OpenRouter',+ baseUrl: 'https://openrouter.ai/api/v1',+ ...(spec ? { quotaProbe: spec } : {}),+ } as any);+}++function stateRows(platform = 'openrouter') {+ return getDb().prepare(+ 'SELECT metric, limit_value, remaining_value, source FROM provider_quota_state WHERE platform = ?',+ ).all(platform) as { metric: string; limit_value: number | null; remaining_value: number | null; source: string }[];+}++describe('fetchQuota — provider-reported quota polling (#1403)', () => {+ beforeEach(() => {+ getDb().prepare('DELETE FROM provider_quota_state').run();+ getDb().prepare('DELETE FROM provider_quota_observations').run();+ vi.restoreAllMocks();+ });++ it('records limit/remaining from the data-wrapped key-info body as source=quota_api', async () => {+ const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue({+ ok: true,+ status: 200,+ json: async () => ({+ data: { label: 'sk-or-...', limit: 10, limit_remaining: 7.25, usage: 2.75 },+ }),+ } as any);++ const provider = makeProvider({+ url: 'https://openrouter.ai/api/v1/key',+ metric: 'credits',+ limitFields: ['limit'],+ remainingFields: ['limit_remaining'],+ });+ const recorded = await provider.fetchQuota('sk-or-test', {+ platform: 'openrouter', keyId: 42, quotaPoolKey: 'openrouter::account',+ });++ expect(recorded).toBe(true);+ // The probe hits the quota URL, not /models, and sends the key.+ expect(String(fetchSpy.mock.calls[0][0])).toBe('https://openrouter.ai/api/v1/key');+ const headers = (fetchSpy.mock.calls[0][1] as RequestInit).headers as Record<string, string>;+ expect(headers.Authorization).toBe('Bearer sk-or-test');++ const rows = stateRows();+ expect(rows).toHaveLength(1);+ expect(rows[0]).toMatchObject({ metric: 'credits', limit_value: 10, remaining_value: 7.25, source: 'quota_api' });+ });++ it('falls back to the top-level body when there is no data wrapper', async () => {+ vi.spyOn(global, 'fetch').mockResolvedValue({+ ok: true, status: 200, json: async () => ({ limit: 100, remaining: 40 }),+ } as any);+ const provider = makeProvider({+ url: 'https://example.test/quota', metric: 'credits',+ limitFields: ['limit'], remainingFields: ['remaining'],+ });+ const ok = await provider.fetchQuota('k', { platform: 'openrouter', keyId: 1 });+ expect(ok).toBe(true);+ const rows = stateRows();+ expect(rows[0]).toMatchObject({ limit_value: 100, remaining_value: 40 });+ });++ it('a provider without a quotaProbe records nothing and does no network', async () => {+ const fetchSpy = vi.spyOn(global, 'fetch');+ const provider = makeProvider();+ expect(await provider.fetchQuota('k', { platform: 'openrouter', keyId: 1 })).toBe(false);+ expect(fetchSpy).not.toHaveBeenCalled();+ expect(stateRows()).toHaveLength(0);+ });++ it('never throws: transport errors and error statuses are inconclusive', async () => {+ vi.spyOn(global, 'fetch').mockRejectedValue(new Error('socket hang up'));+ const provider = makeProvider({+ url: 'https://openrouter.ai/api/v1/key', metric: 'credits',+ limitFields: ['limit'], remainingFields: ['limit_remaining'],+ });+ expect(await provider.fetchQuota('k', { platform: 'openrouter', keyId: 1 })).toBe(false);++ vi.spyOn(global, 'fetch').mockResolvedValue({ ok: false, status: 401 } as any);+ expect(await provider.fetchQuota('k', { platform: 'openrouter', keyId: 1 })).toBe(false);+ expect(stateRows()).toHaveLength(0);+ });++ it('a body with no numeric limit/remaining records nothing', async () => {+ vi.spyOn(global, 'fetch').mockResolvedValue({+ ok: true, status: 200, json: async () => ({ data: { label: 'key', limit: null, limit_remaining: null } }),+ } as any);+ const provider = makeProvider({+ url: 'https://openrouter.ai/api/v1/key', metric: 'credits',+ limitFields: ['limit'], remainingFields: ['limit_remaining'],+ });+ expect(await provider.fetchQuota('k', { platform: 'openrouter', keyId: 1 })).toBe(false);+ expect(stateRows()).toHaveLength(0);+ });++ it('the registered OpenRouter provider carries the /api/v1/key probe', async () => {+ const provider = resolveProvider('openrouter');+ expect(provider).toBeDefined();+ vi.spyOn(global, 'fetch').mockResolvedValue({+ ok: true, status: 200, json: async () => ({ data: { limit: 5, limit_remaining: 4.99 } }),+ } as any);+ getDb().prepare('DELETE FROM provider_quota_state').run();+ const ok = await provider!.fetchQuota('sk-or-x', { platform: 'openrouter', keyId: 7 });+ expect(ok).toBe(true);+ expect(String(vi.mocked(fetch).mock.calls[0][0])).toBe('https://openrouter.ai/api/v1/key');+ });++ it('accepts string-encoded balances (SiliconFlow returns "88.88")', async () => {+ vi.spyOn(global, 'fetch').mockResolvedValue({+ ok: true, status: 200,+ json: async () => ({ code: 200, data: { id: 'u', balance: '7.3972', chargeBalance: '15.2505', totalBalance: '22.6478', status: 'normal' } }),+ } as any);+ const provider = makeProvider({+ url: 'https://api.siliconflow.com/v1/user/info', metric: 'credits',+ limitFields: [], remainingFields: ['totalBalance', 'balance'],+ });+ const ok = await provider.fetchQuota('sk-test', { platform: 'openrouter', keyId: 3 });+ expect(ok).toBe(true);+ const rows = stateRows();+ expect(rows).toHaveLength(1);+ expect(rows[0]).toMatchObject({ metric: 'credits', limit_value: null, remaining_value: 22.6478, source: 'quota_api' });+ });++ it('a non-numeric string is not a balance', async () => {+ vi.spyOn(global, 'fetch').mockResolvedValue({+ ok: true, status: 200,+ json: async () => ({ data: { totalBalance: '', balance: null } }),+ } as any);+ const provider = makeProvider({+ url: 'https://api.siliconflow.com/v1/user/info', metric: 'credits',+ limitFields: [], remainingFields: ['totalBalance', 'balance'],+ });+ expect(await provider.fetchQuota('sk-test', { platform: 'openrouter', keyId: 3 })).toBe(false);+ expect(stateRows()).toHaveLength(0);+ });++ it('the registered SiliconFlow provider carries the /v1/user/info probe', async () => {+ const provider = resolveProvider('siliconflow');+ expect(provider).toBeDefined();+ vi.spyOn(global, 'fetch').mockResolvedValue({+ ok: true, status: 200, json: async () => ({ data: { balance: '0.88', totalBalance: '0.88' } }),+ } as any);+ getDb().prepare('DELETE FROM provider_quota_state').run();+ const ok = await provider!.fetchQuota('sk-sf', { platform: 'siliconflow', keyId: 9 });+ expect(ok).toBe(true);+ expect(String(vi.mocked(fetch).mock.calls[0][0])).toBe('https://api.siliconflow.com/v1/user/info');+ expect(stateRows('siliconflow')[0]).toMatchObject({ remaining_value: 0.88, source: 'quota_api' });+ });+});diff --git a/server/src/__tests__/routes/health-quota-route.test.ts b/server/src/__tests__/routes/health-quota-route.test.tsnew file mode 100644index 00000000..7903b139--- /dev/null+++ b/server/src/__tests__/routes/health-quota-route.test.ts@@ -0,0 +1,105 @@+import type { Server } from 'node:http';+import type { AddressInfo } from 'node:net';+import express from 'express';+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';+import { getDb, initDb } from '../../db/index.js';+import { encrypt } from '../../lib/crypto.js';+import { requireAuth } from '../../middleware/requireAuth.js';+import { resolveProvider } from '../../providers/index.js';+import { healthRouter } from '../../routes/health.js';+import { mintDashboardToken } from '../helpers/auth.js';++// POST /api/health/quota/:keyId — the manual override of the #1403 15-minute+// health-poll throttle (#1404). Only the provider probe is replaced; the route,+// auth, DB state and response shape are exercised for real. (The probe is+// spied on the provider instance rather than stubbing global fetch, because+// this suite's own HTTP calls also go through fetch.)+describe('POST /api/health/quota/:keyId (#1403)', () => {+ let server: Server;+ let url: string;+ let token: string;++ beforeAll(async () => {+ vi.stubEnv('ENCRYPTION_KEY', '0'.repeat(64));+ initDb(':memory:');+ token = mintDashboardToken();+ const app = express();+ app.use(express.json());+ app.use('/api/health', requireAuth, healthRouter);+ server = app.listen(0, '127.0.0.1');+ await new Promise<void>(resolve => server.once('listening', resolve));+ url = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;+ });++ afterAll(async () => {+ await new Promise<void>((resolve, reject) => server.close(e => e ? reject(e) : resolve()));+ vi.unstubAllEnvs();+ });++ const addKey = (platform: string, baseUrl: string | null = null) => {+ const enc = encrypt('sk-test-secret');+ return getDb().prepare(+ 'INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, base_url, status, enabled) VALUES (?, ?, ?, ?, ?, ?, ?, 1)',+ ).run(platform, `test ${platform}`, enc.encrypted, enc.iv, enc.authTag, baseUrl, 'healthy').lastInsertRowid as number;+ };++ const post = (path: string) =>+ fetch(`${url}/api/health${path}`, { method: 'POST', headers: { Authorization: `Bearer ${token}` } });++ beforeEach(() => {+ getDb().prepare('DELETE FROM api_keys').run();+ getDb().prepare('DELETE FROM provider_quota_state').run();+ getDb().prepare('DELETE FROM provider_quota_observations').run();+ vi.restoreAllMocks();+ });++ it('records and returns a fresh quota_api reading for a probed platform', async () => {+ const keyId = addKey('openrouter');+ // Drive the real fetchQuota → recordQuotaObservation path: mock only the+ // upstream HTTP call the provider instance makes, via its fetch override.+ const provider = resolveProvider('openrouter')!;+ const probe = vi.spyOn(provider, 'fetchQuota').mockImplementation(async (_key, ctx) => {+ // Record through the same service the real probe uses, so the route's+ // state read-back and the recorded flag reflect a genuine observation.+ const { recordQuotaObservation } = await import('../../services/provider-quota.js');+ recordQuotaObservation({+ platform: 'openrouter', keyId: ctx?.keyId, quotaPoolKey: ctx?.quotaPoolKey,+ endpoint: 'quota_api', metric: 'credits', limit: 20, remaining: 12.5,+ resetStrategy: 'provider_reported', source: 'quota_api', statusCode: 200, notes: null,+ } as any);+ return true;+ });++ const res = await post(`/quota/${keyId}`);+ expect(res.status).toBe(200);+ const body = await res.json() as any;+ expect(probe).toHaveBeenCalledTimes(1);+ expect(body.recorded).toBe(true);+ expect(body.quotaStates).toHaveLength(1);+ expect(body.quotaStates[0]).toMatchObject({ source: 'quota_api', limit: 20, remaining: 12.5 });+ });++ it('a platform without a quota endpoint answers 400', async () => {+ const keyId = addKey('mistral');+ const res = await post(`/quota/${keyId}`);+ expect(res.status).toBe(400);+ const body = await res.json() as any;+ expect(body.error.message).toContain('no provider-reported quota endpoint');+ });++ it('unknown key id is 404, garbage id is 400', async () => {+ expect((await post('/quota/99999')).status).toBe(404);+ expect((await post('/quota/not-a-number')).status).toBe(400);+ });++ it('a probe failure answers recorded:false, never a 500', async () => {+ const keyId = addKey('openrouter');+ vi.spyOn(resolveProvider('openrouter')!, 'fetchQuota').mockRejectedValue(new Error('socket hang up'));+ const res = await post(`/quota/${keyId}`);+ // pollKeyQuota is failure-silent by construction: the route still answers.+ expect(res.status).toBe(200);+ const body = await res.json() as any;+ expect(body.recorded).toBe(false);+ expect(body.quotaStates).toHaveLength(0);+ });+});diff --git a/server/src/__tests__/services/health-quota-poll.test.ts b/server/src/__tests__/services/health-quota-poll.test.tsnew file mode 100644index 00000000..054dbb25--- /dev/null+++ b/server/src/__tests__/services/health-quota-poll.test.ts@@ -0,0 +1,112 @@+import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest';+import { encrypt } from '../../lib/crypto.js';+import { getDb, initDb } from '../../db/index.js';++// #1403: the health pass piggybacks provider-reported quota polling on a+// healthy verdict, throttled per key, and a quota failure must never bend the+// health verdict itself.+const fetchQuota = vi.hoisted(() => vi.fn());+const validateKey = vi.hoisted(() => vi.fn());++vi.mock('../../providers/index.js', () => ({+ resolveProvider: () => ({+ name: 'OpenRouter',+ validateKey,+ // Stands in for the OpenAICompatProvider override (hasQuotaProbe true, so+ // supportsQuotaPolling passes it).+ hasQuotaProbe: true,+ fetchQuota,+ }),+}));++const { checkKeyHealth, maybePollKeyQuota, QUOTA_POLL_INTERVAL_MS } = await import('../../services/health.js');++beforeAll(() => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ initDb(':memory:');+});++let nextId = 9100;+function seedKey(): number {+ const id = ++nextId;+ const key = encrypt('sk-or-health-test');+ getDb().prepare(`+ INSERT INTO api_keys (id, platform, label, encrypted_key, iv, auth_tag, enabled, status)+ VALUES (?, 'openrouter', 'quota-poll-test', ?, ?, ?, 1, 'unknown')+ `).run(id, key.encrypted, key.iv, key.authTag);+ return id;+}++function seedQuotaApiObservation(keyId: number, ageMs: number): void {+ const seen = new Date(Date.now() - ageMs).toISOString().replace('T', ' ').replace('Z', '');+ getDb().prepare(`+ INSERT INTO provider_quota_observations+ (id, platform, key_id, quota_pool_key, metric, source, created_at, observed_at)+ VALUES (?, 'openrouter', ?, 'openrouter::account', 'credits', 'quota_api', ?, ?)+ `).run(`qpo-${keyId}-${ageMs}`, keyId, seen, seen);+}++beforeEach(() => {+ fetchQuota.mockReset();+ validateKey.mockReset();+ vi.useRealTimers();+});++describe('health-pass quota polling (#1403)', () => {+ it('polls quota after a healthy check and records nothing on failure without changing the verdict', async () => {+ const keyId = seedKey();+ validateKey.mockResolvedValue(true);+ fetchQuota.mockResolvedValue(false); // quota endpoint down++ const status = await checkKeyHealth(keyId);+ expect(status).toBe('healthy');+ // Give the fire-and-forget poll a tick to run.+ await new Promise(r => setImmediate(r));+ expect(fetchQuota).toHaveBeenCalledTimes(1);+ const row = getDb().prepare('SELECT status FROM api_keys WHERE id = ?').get(keyId) as { status: string };+ expect(row.status).toBe('healthy');+ });++ it('fetchQuota throwing does not demote the key', async () => {+ const keyId = seedKey();+ validateKey.mockResolvedValue(true);+ fetchQuota.mockRejectedValue(new Error('socket hang up'));+ const status = await checkKeyHealth(keyId);+ expect(status).toBe('healthy');+ await new Promise(r => setImmediate(r));+ const row = getDb().prepare('SELECT status FROM api_keys WHERE id = ?').get(keyId) as { status: string };+ expect(row.status).toBe('healthy');+ });++ it('does not poll after an invalid verdict', async () => {+ const keyId = seedKey();+ validateKey.mockResolvedValue({ valid: false, error: 'bad key' });+ const status = await checkKeyHealth(keyId);+ expect(status).toBe('invalid');+ await new Promise(r => setImmediate(r));+ expect(fetchQuota).not.toHaveBeenCalled();+ });++ it('maybePollKeyQuota throttles to one poll per interval per key', async () => {+ const keyId = seedKey();+ fetchQuota.mockResolvedValue(true);++ // Fresh observation: too soon, must skip.+ seedQuotaApiObservation(keyId, 60_000);+ expect(await maybePollKeyQuota(keyId)).toBe(false);+ expect(fetchQuota).not.toHaveBeenCalled();++ // Only an old observation remains: poll runs.+ getDb().prepare("DELETE FROM provider_quota_observations WHERE key_id = ? AND created_at > datetime('now', '-1 hour')").run(keyId);+ seedQuotaApiObservation(keyId, QUOTA_POLL_INTERVAL_MS + 60_000);+ expect(await maybePollKeyQuota(keyId)).toBe(true);+ expect(fetchQuota).toHaveBeenCalledTimes(1);+ });++ it('maybePollKeyQuota polls immediately when the key has no quota_api history', async () => {+ const keyId = seedKey();+ fetchQuota.mockResolvedValue(true);+ expect(await maybePollKeyQuota(keyId)).toBe(true);+ expect(fetchQuota).toHaveBeenCalledTimes(1);+ });+});diff --git a/server/src/providers/base.ts b/server/src/providers/base.tsindex 6ea89f04..d4efd92d 100644--- a/server/src/providers/base.ts+++ b/server/src/providers/base.ts@@ -246,6 +246,28 @@ export abstract class BaseProvider {abstract validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<KeyValidationResult>;+ /**+ * Optional quota/balance probe (#1403). Providers whose API exposes a+ * key-info/quota endpoint override this to fetch the provider-reported+ * limit/remaining and persist them as a `source: 'quota_api'` observation,+ * so the dashboard shows a real balance instead of a text-label guess.+ * Must never throw into the caller: the default implementation does no+ * network at all and returns false; implementations catch transport errors+ * and return false so a quota probe can never change a health verdict.+ * Returns true when an observation was recorded.+ */+ async fetchQuota(_apiKey: string, _quotaContext?: QuotaObservationContext): Promise<boolean> {+ return false;+ }++ /** Whether this provider actually has a quota endpoint to probe (#1403).+ * fetchQuota alone can't answer it: OpenAICompatProvider overrides the+ * method for every instance, spec or not. Routes that owe the operator a+ * "this platform has no quota endpoint" answer must use this instead. */+ get hasQuotaProbe(): boolean {+ return false;+ }+/*** Turn a conventional 401/403 validation response into a diagnostic result.* Providers still return a simple boolean when no useful error body exists,diff --git a/server/src/providers/index.ts b/server/src/providers/index.tsindex 06a9a0ee..c2d60d33 100644--- a/server/src/providers/index.ts+++ b/server/src/providers/index.ts@@ -166,6 +166,17 @@ register(new OpenAICompatProvider({'HTTP-Referer': 'http://localhost:3001','X-Title': 'FreeLLMAPI',},+ // #1403: OpenRouter reports the key's real credit balance and hard limit on+ // its key-info endpoint (outside /api/v1). limit/remaining are USD amounts+ // when set; null means the key is on the free tier with no credit cap, so+ // the probe records whatever pair the endpoint actually fills.+ quotaProbe: {+ url: 'https://openrouter.ai/api/v1/key',+ metric: 'credits',+ limitFields: ['limit'],+ remainingFields: ['limit_remaining'],+ notes: 'openrouter key-info: USD credit (limit/limit_remaining)',+ },}));// GitHub Models — OpenAI-compatible. Catalog uses `<publisher>/<model>` ids@@ -345,6 +356,18 @@ register(new OpenAICompatProvider({platform: 'siliconflow',name: 'SiliconFlow',baseUrl: 'https://api.siliconflow.com/v1',+ // #1403: SiliconFlow reports the account's credit balance on+ // GET /v1/user/info (data.balance = gift credit, data.totalBalance = gift ++ // charge; values arrive as numeric strings in CNY). There is no limit field,+ // so the probe records remaining only — a real number beats parseBudget's 0+ // for this pool.+ quotaProbe: {+ url: 'https://api.siliconflow.com/v1/user/info',+ metric: 'credits',+ limitFields: [],+ remainingFields: ['totalBalance', 'balance'],+ notes: 'siliconflow user-info: CNY credit balance (totalBalance)',+ },}));// Routeway — OpenAI-compatible aggregator (api.routeway.ai/v1). Free modelsdiff --git a/server/src/providers/openai-compat.ts b/server/src/providers/openai-compat.tsindex 53640ccc..0088aa40 100644--- a/server/src/providers/openai-compat.ts+++ b/server/src/providers/openai-compat.ts@@ -11,7 +11,8 @@ import { rescueInlineToolCalls } from '../lib/tool-call-rescue.js';import { extractThinkFromMessage } from '../lib/think-tags.js';import { repairToolArguments, toolSchemaMap } from '../lib/tool-args.js';import { invalidToolCallReasons, isToolArgumentValidationEnabled } from '../lib/tool-validate.js';-import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';+import { recordQuotaObservation, recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';+import type { QuotaMetric } from '@freellmapi/shared/types.js';import { providerTimeoutMs } from '../lib/provider-timeout.js';import { isAbortLikeError } from '../lib/error-classify.js';import { contentToString } from '../lib/content.js';@@ -69,6 +70,19 @@ export function inBandCreditsError(text: string | null | undefined): string | nu* Covers: Groq, Cerebras, NVIDIA NIM, Mistral, OpenRouter,* GitHub Models, Fireworks AI.*/+/** A provider's key-info/quota endpoint (#1403): the GET URL and the JSON+ * field names carrying the limit and the remaining balance. Fields are looked+ * up first under a `data` wrapper (OpenRouter style), then at the top level.+ * `credits` are in the provider's own currency (OpenRouter USD, SiliconFlow+ * CNY); `notes` names it. Only a reading with a limit feeds routing headroom. */+export interface QuotaProbeSpec {+ url: string;+ metric: QuotaMetric;+ limitFields: string[];+ remainingFields: string[];+ notes?: string;+}+export class OpenAICompatProvider extends BaseProvider {readonly platform: Platform;readonly name: string;@@ -86,6 +100,8 @@ export class OpenAICompatProvider extends BaseProvider {/** True only for a custom endpoint whose host is Moonshot's own API; see* isMoonshotEndpoint(). Gates the assistant `partial` prefill flag (#1038). */private readonly forwardsPartial: boolean;+ /** Optional provider-reported quota endpoint (#1403). */+ private readonly quotaProbe?: QuotaProbeSpec;constructor(opts: {platform: Platform;@@ -96,6 +112,7 @@ export class OpenAICompatProvider extends BaseProvider {timeoutMs?: number;keyless?: boolean;forceSingleToolCall?: boolean;+ quotaProbe?: QuotaProbeSpec;}) {super();this.platform = opts.platform;@@ -108,6 +125,7 @@ export class OpenAICompatProvider extends BaseProvider {this.keyless = opts.keyless ?? false;this.forceSingleToolCall = opts.forceSingleToolCall ?? false;this.forwardsPartial = opts.platform === 'custom' && isMoonshotEndpoint(opts.baseUrl);+ this.quotaProbe = opts.quotaProbe;}/** Resolve the parallel_tool_calls flag to send upstream. For providers that@@ -553,6 +571,75 @@ export class OpenAICompatProvider extends BaseProvider {const res = await this.fetchCatalogEndpoint(this.validateUrl ?? this.modelsUrl, apiKey, quotaContext);return this.validationResult(res);}++ /**+ * Provider-reported balance via the registered quotaProbe endpoint (#1403).+ * GETs the key-info URL (e.g. OpenRouter's `GET /api/v1/key`), pulls the+ * limit/remaining numbers out of the JSON (checking the `data` wrapper and+ * the top level), and records them as a `source: 'quota_api'` observation.+ * Never throws: a quota probe that fails says nothing about the key, and+ * the caller's health verdict must stay about the key.+ */+ get hasQuotaProbe(): boolean {+ return this.quotaProbe !== undefined;+ }++ async fetchQuota(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean> {+ const spec = this.quotaProbe;+ if (!spec) return false;+ try {+ const res = await this.fetchWithTimeout(spec.url, {+ method: 'GET',+ headers: {+ ...this.authHeader(apiKey),+ ...this.extraHeaders,+ },+ }, 10_000, { timeoutBounds: 'request' });+ if (!res.ok) return false;+ const body: any = await res.json().catch(() => null);+ const scope = (body && typeof body === 'object' && body.data && typeof body.data === 'object')+ ? [body.data, body]+ : [body];+ const pick = (fields: string[]): number | null => {+ for (const obj of scope) {+ if (!obj || typeof obj !== 'object') continue;+ for (const f of fields) {+ const v = (obj as Record<string, unknown>)[f];+ if (typeof v === 'number' && Number.isFinite(v)) return v;+ // Some providers serialize balances as strings ("88.88", SiliconFlow+ // /v1/user/info). Accept a numeric string; "", null and prose never+ // parse to a finite number.+ if (typeof v === 'string' && v.trim() !== '') {+ const n = Number(v);+ if (Number.isFinite(n)) return n;+ }+ }+ }+ return null;+ };+ const limit = pick(spec.limitFields);+ const remaining = pick(spec.remainingFields);+ if (limit === null && remaining === null) return false;+ const record = recordQuotaObservation({+ platform: this.platform,+ keyId: quotaContext?.keyId,+ providerAccountId: quotaContext?.providerAccountId,+ quotaPoolKey: quotaContext?.quotaPoolKey,+ endpoint: 'quota_api',+ metric: spec.metric,+ limit,+ remaining,+ resetStrategy: 'provider_reported',+ source: 'quota_api',+ statusCode: res.status,+ notes: spec.notes ?? null,+ });+ return record !== null;+ } catch {+ // Transport/parse failure: inconclusive, never a key verdict (#1403).+ return false;+ }+ }}/**diff --git a/server/src/routes/health.ts b/server/src/routes/health.tsindex 1791fa25..0daea61e 100644--- a/server/src/routes/health.ts+++ b/server/src/routes/health.ts@@ -1,10 +1,11 @@import { Router } from 'express';import type { Request, Response } from 'express';import { getDb } from '../db/index.js';-import { checkKeyHealth, checkAllKeys } from '../services/health.js';+import { checkKeyHealth, checkAllKeys, pollKeyQuota, supportsQuotaPolling } from '../services/health.js';import { getDegradationStatus } from '../services/degradation.js';-import { hasProvider } from '../providers/index.js';+import { hasProvider, resolveProvider } from '../providers/index.js';import { getQuotaStateForKeys } from '../services/provider-quota.js';+import type { Platform } from '@freellmapi/shared/types.js';export const healthRouter = Router();@@ -78,3 +79,35 @@ healthRouter.post('/check-all', async (_req: Request, res: Response) => {await checkAllKeys({ force: true });res.json({ success: true });});++// Poll one key's provider-reported balance now (#1403). The health pass only+// piggybacks the quota probe at most once per 15 minutes; this is the manual+// override — an operator adding a key wants the balance immediately instead+// of waiting for the next healthy pass after the throttle. Returns what the+// probe recorded (or the fresh state when the provider reported nothing, so+// the caller can tell "no quota endpoint / probe failed" from "fresh number").+healthRouter.post('/quota/:keyId', async (req: Request, res: Response) => {+ const keyId = parseInt(req.params.keyId as string, 10);+ if (isNaN(keyId)) {+ res.status(400).json({ error: { message: 'Invalid key ID' } });+ return;+ }+ const db = getDb();+ const row = db.prepare('SELECT * FROM api_keys WHERE id = ?').get(keyId) as any;+ if (!row) {+ res.status(404).json({ error: { message: 'Key not found' } });+ return;+ }+ const provider = resolveProvider(row.platform as Platform, row.base_url);+ if (!provider || !supportsQuotaPolling(provider)) {+ res.status(400).json({ error: { message: `${row.platform} has no provider-reported quota endpoint` } });+ return;+ }+ // pollKeyQuota is failure-silent by design; its boolean tells us whether a+ // quota_api row was written, and the state query returns the fresh reading.+ const recorded = await pollKeyQuota(keyId, row, provider);+ const state = getQuotaStateForKeys().filter(+ q => q.keyId === keyId && q.source === 'quota_api',+ );+ res.json({ keyId, recorded, quotaStates: state });+});diff --git a/server/src/services/health.ts b/server/src/services/health.tsindex f0346205..f65f6560 100644--- a/server/src/services/health.ts+++ b/server/src/services/health.ts@@ -1,5 +1,6 @@import { getDb } from '../db/index.js';import { resolveProvider } from '../providers/index.js';+import { BaseProvider } from '../providers/base.js';import { decrypt } from '../lib/crypto.js';import { decryptProxyUrl } from '../lib/key-proxy.js';import { withKeyProxy } from '../lib/proxy.js';@@ -81,6 +82,76 @@ function recordInvalidFailure(keyId: number, platform?: string): void {}}+/**+ * Provider-reported quota polling (#1403 phase 1). Providers with a key-info+ * endpoint (see BaseProvider.fetchQuota) get polled right after a health pass+ * confirms the key works, so the dashboard shows the provider's own balance+ * instead of a regex guess over catalog text. Throttled per key: a poll is+ * only worth taking when the last quota_api observation is older than+ * QUOTA_POLL_INTERVAL_MS (or none exists). Fire-and-forget and failure-silent:+ * a quota probe says nothing about key validity and must never bend a health+ * verdict or the pass budget.+ */+export const QUOTA_POLL_INTERVAL_MS = 15 * 60 * 1000;++function quotaPollDue(keyId: number, now = Date.now()): boolean {+ const row = getDb().prepare(`+ SELECT created_at AS seenAt FROM provider_quota_observations+ WHERE key_id = ? AND source = 'quota_api'+ ORDER BY created_at DESC LIMIT 1+ `).get(keyId) as { seenAt: string | null } | undefined;+ if (!row?.seenAt) return true;+ const seen = Date.parse(row.seenAt.includes('T') ? row.seenAt : row.seenAt.replace(' ', 'T') + 'Z');+ if (!Number.isFinite(seen)) return true;+ return now - seen >= QUOTA_POLL_INTERVAL_MS;+}++export async function pollKeyQuota(+ keyId: number,+ // The api_keys row as stored (encrypted key columns + the proxy columns+ // decryptProxyUrl reads). `any` mirrors how checkKeyHealth carries it.+ row: any,+ provider: BaseProvider,+): Promise<boolean> {+ try {+ const apiKey = decrypt(row.encrypted_key, row.iv, row.auth_tag);+ return await withKeyProxy(decryptProxyUrl(row), () => provider.fetchQuota(apiKey, {+ platform: row.platform as Platform,+ keyId,+ quotaPoolKey: inferQuotaPoolKey(row.platform as Platform, null),+ endpoint: 'quota_api',+ origin: 'health',+ }));+ } catch {+ // Inconclusive by construction: never throws into the health pass.+ return false;+ }+}++/** True when this provider actually has a quota endpoint to probe (#1403).+ * Uses the provider's own hasQuotaProbe getter: OpenAICompatProvider+ * overrides fetchQuota for every instance, spec or not, so a method-identity+ * check would claim quota support for specless platforms. */+export function supportsQuotaPolling(provider: BaseProvider): boolean {+ return provider.hasQuotaProbe;+}++/** Throttled, self-contained quota poll for one key — the entry point other+ * services (or a future scheduler) can use without duplicating the gate. */+export async function maybePollKeyQuota(keyId: number): Promise<boolean> {+ try {+ const db = getDb();+ const row = db.prepare('SELECT * FROM api_keys WHERE id = ? AND enabled = 1').get(keyId) as any;+ if (!row) return false;+ const provider = resolveProvider(row.platform as Platform, row.base_url);+ if (!provider || !supportsQuotaPolling(provider)) return false;+ if (!quotaPollDue(keyId)) return false;+ return await pollKeyQuota(keyId, row, provider);+ } catch {+ return false;+ }+}+export async function checkKeyHealth(keyId: number): Promise<KeyStatus> {const db = getDb();const row = db.prepare('SELECT * FROM api_keys WHERE id = ?').get(keyId) as any;@@ -122,6 +193,12 @@ export async function checkKeyHealth(keyId: number): Promise<KeyStatus> {// serves nothing until its models are discovered. Fire-and-forget; the// trigger is a no-op for every other platform, and throttled.triggerBuiltinModelDiscovery(db, row.platform, 'healthy');+ // #1403: piggyback provider-reported quota polling on the healthy+ // verdict — but only for providers with a quota endpoint, and at most+ // once per QUOTA_POLL_INTERVAL_MS per key. Fire-and-forget, silent.+ if (supportsQuotaPolling(provider) && quotaPollDue(keyId)) {+ void pollKeyQuota(keyId, row, provider).catch(() => {});+ }} else {providerLog('warn',