@alilis/k-hat 0.2.6 → 0.2.7

package/dist/admin.js

@@ -5,6 +5,8 @@ import { UiSessions, serveUi } from './web-ui.js';
 import { ACCESS_TOKEN_REF, generateAccessToken } from './vault.js';
 import { providerUrl } from './config.js';
 import { findRoute, routeUpstreamModel } from './router.js';
+import { keyBlocked } from './selector.js';
+import { probeKey } from './probe.js';
 import { readExport, applyImport } from './portable-vault.js';
 // Admin API is the daemon's single-writer surface (ADR-0005). It is reachable
 // only from loopback and behind the proxy access token, so a local non-loopback
@@ -39,7 +41,7 @@ async function listProviderModels(store, providerId) {
     const provider = store.config.providers.find((item) => item.id === providerId);
     if (!provider)
         throw new Error(`unknown provider: ${providerId}`);
-    const key = provider.keys.find((item) => item.enabled !== false && store.states[`${provider.id}/${item.id}`]?.status !== 'unavailable');
+    const key = provider.keys.find((item) => item.enabled !== false && !keyBlocked(store.states[`${provider.id}/${item.id}`]));
     if (!key)
         throw new Error('provider has no available key');
     const secret = store.vault.get(key.vaultRef);
@@ -67,11 +69,14 @@ function buildStatus(store) {
             keys: provider.keys.map((key) => {
                 const state = store.states[`${provider.id}/${key.id}`];
                 const secret = store.vault.get(key.vaultRef);
+                // An expired cooldown is selectable again, so it must surface as available.
+                const status = keyBlocked(state) ? state.status : 'available';
                 return {
                     id: key.id,
                     weight: key.weight,
                     ...(key.enabled === false ? { enabled: false } : {}),
-                    status: state?.status === 'unavailable' ? 'unavailable' : 'available',
+                    status,
+                    ...(status === 'cooldown' ? { cooldownUntil: state.cooldownUntil } : {}),
                     lastError: state?.lastError,
                     secret: secret ? maskSecret(secret) : null,
                     counters: store.counters[`${provider.id}/${key.id}`] ?? { requests: 0, failed: 0, bytesOut: 0, tokensIn: 0, tokensOut: 0 }
@@ -206,15 +211,10 @@ async function route(req, res, store, sessionAuthorized = false) {
                 : store.config.routes.find((item) => item.provider === provider.id);
             if (!secret || !route || route.provider !== provider.id)
                 throw new Error('a key and route model are required for probing');
-            const model = routeUpstreamModel(route);
-            const path = provider.protocol === 'anthropic' ? '/v1/messages' : '/v1/chat/completions';
-            const headers = upstreamHeaders(provider.protocol, secret, true);
-            const body = provider.protocol === 'anthropic' ? { model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }] } : { model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }], stream: false };
-            const response = await fetch(providerUrl(provider.baseUrl, path), { method: 'POST', headers: headers, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000) });
-            await response.arrayBuffer();
-            if (response.ok)
+            const status = await probeKey(provider, routeUpstreamModel(route), secret);
+            if (status >= 200 && status < 300)
                 await store.mutate(() => enableKey(store, provider.id, key.id));
-            return json(res, response.ok ? 200 : 502, { ok: response.ok, status: response.status });
+            return json(res, status >= 200 && status < 300 ? 200 : 502, { ok: status >= 200 && status < 300, status });
         }
     }
     if (sub[0] === 'routes') {

package/dist/cli.js

@@ -195,7 +195,14 @@ function keyStatusLine(store, providerId, keyId) {
     const state = store.states[`${providerId}/${keyId}`];
     if (!state || state.status === 'available')
         return { status: 'available', note: '' };
-    return { status: 'unavailable', note: `  last error: ${state.lastError?.http ?? '?'} at ${state.lastError?.at ?? '?'}` };
+    const lastError = `last error: ${state.lastError?.http ?? '?'} at ${state.lastError?.at ?? '?'}`;
+    if (state.status === 'cooldown') {
+        const remaining = Date.parse(state.cooldownUntil ?? '') - Date.now();
+        if (remaining <= 0)
+            return { status: 'available', note: '' };
+        return { status: 'cooldown', note: `  cooling down, auto-retry in ${Math.ceil(remaining / 1000)}s (${lastError})` };
+    }
+    return { status: 'unavailable', note: `  ${lastError}` };
 }
 function printStatus(store) {
     const token = store.vault.get(ACCESS_TOKEN_REF);
@@ -402,7 +409,7 @@ async function runLog(flags) {
         return;
     }
     for (const entry of entries) {
-        console.log(`${entry.ts}\t${entry.status}\t${entry.provider}/${entry.key.split('/').pop()}\t${entry.model}\t${entry.durationMs}ms\t${entry.tokensIn ?? 0}/${entry.tokensOut ?? 0} tokens`);
+        console.log(`${entry.ts}\t${entry.status}\t${entry.provider}/${entry.key.split('/').pop()}\t${entry.model ?? '(probe)'}\t${entry.durationMs ?? '—'}\t${entry.tokensIn ?? 0}/${entry.tokensOut ?? 0} tokens`);
     }
 }
 async function runDoctor() {
@@ -677,7 +684,7 @@ try {
                     console.log(`${providerId}/${keyId} is available`);
                 }
                 else if ([401, 402, 429].includes(response.status))
-                    console.log('this error marks a key unavailable during proxying; check the key on the provider side');
+                    console.log(response.status === 429 ? 'a 429 during proxying puts the key in cooldown; it revives automatically when the cooldown expires' : 'this error marks a key unavailable during proxying; check the key on the provider side');
             }
             else {
                 console.error('usage: khat key add | list | update | remove | enable | test');

package/dist/config.js

@@ -53,6 +53,9 @@ export function validateConfig(config) {
     if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535) {
         throw new Error('Invalid config: port must be an integer between 1 and 65535');
     }
+    if (config.revision !== undefined && (!Number.isInteger(config.revision) || config.revision < 0)) {
+        throw new Error('Invalid config: revision must be a non-negative integer');
+    }
     for (const provider of config.providers) {
         if (!provider.id || !provider.baseUrl || (provider.protocol !== 'openai' && provider.protocol !== 'anthropic') || !Array.isArray(provider.keys))
             throw new Error(`Invalid provider: ${provider.id}`);

package/dist/probe.js

@@ -0,0 +1,15 @@
+import { providerUrl } from './config.js';
+const ANTHROPIC_VERSION = '2023-06-01';
+/** Minimal one-token ping shared by the Admin probe endpoint and the background prober. */
+export async function probeKey(provider, model, secret) {
+    const path = provider.protocol === 'anthropic' ? '/v1/messages' : '/v1/chat/completions';
+    const headers = provider.protocol === 'anthropic'
+        ? { 'content-type': 'application/json', 'x-api-key': secret, 'anthropic-version': ANTHROPIC_VERSION }
+        : { 'content-type': 'application/json', authorization: `Bearer ${secret}` };
+    const body = provider.protocol === 'anthropic'
+        ? { model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }] }
+        : { model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }], stream: false };
+    const response = await fetch(providerUrl(provider.baseUrl, path), { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000) });
+    await response.arrayBuffer();
+    return response.status;
+}

package/dist/selector.js

@@ -1,7 +1,19 @@
+/** True when a key must not be selected: permanently unavailable, or still cooling down after a 429. */
+export function keyBlocked(state, now = Date.now()) {
+    if (!state)
+        return false;
+    if (state.status === 'unavailable')
+        return true;
+    if (state.status === 'cooldown') {
+        const until = Date.parse(state.cooldownUntil ?? '');
+        return Number.isNaN(until) || until > now;
+    }
+    return false;
+}
 export class WeightedSelector {
     current = new Map();
     select(providerId, keys, states) {
-        const available = keys.filter((key) => key.enabled !== false && states[`${providerId}/${key.id}`]?.status !== 'unavailable');
+        const available = keys.filter((key) => key.enabled !== false && !keyBlocked(states[`${providerId}/${key.id}`]));
         if (!available.length)
             return undefined;
         let total = 0;

package/dist/server.js

@@ -6,10 +6,21 @@ import { join, basename } from 'node:path';
 import { findRoute, routeUpstreamModel, resolveProvider, isRouteDisabled } from './router.js';
 import { WeightedSelector } from './selector.js';
 import { handleAdmin } from './admin.js';
+import { enableKey } from './store.js';
+import { probeKey } from './probe.js';
 import { ACCESS_TOKEN_REF } from './vault.js';
 const RETRYABLE = new Set([401, 402, 429]);
 const HOP_BY_HOP = new Set(['content-length', 'transfer-encoding', 'connection']);
 const ANTHROPIC_VERSION = '2023-06-01';
+/** 429 cooldown: first wait, doubling per consecutive cycle, capped. */
+const COOLDOWN_BASE_MS = 30_000;
+const COOLDOWN_MAX_MS = 10 * 60_000;
+/** An upstream Retry-After is honored, but never beyond this cap. */
+const RETRY_AFTER_MAX_MS = 30 * 60_000;
+/** Background probe cadence for permanently unavailable keys (cooldown keys revive on their own). */
+const PROBE_INTERVAL_MS = 5 * 60_000;
+/** Upper bound for buffering a non-streaming response to read its usage. */
+const USAGE_BUFFER_LIMIT = 16 * 1024 * 1024;
 /** Entry paths accepted by the proxy, mapped to the protocol family they speak. */
 const ENDPOINTS = {
     '/v1/chat/completions': 'openai',
@@ -35,22 +46,27 @@ async function readBody(req, limit) {
     return Buffer.concat(chunks);
 }
 function scanUsage(protocol, text) {
+    // Usage snapshots are cumulative within a stream (Anthropic message_start/message_delta each
+    // carry a running total), so the per-field max across snapshots is the stream total; summing
+    // would double-count.
     let tokensIn = 0;
     let tokensOut = 0;
     for (const line of text.split('\n')) {
         if (!line.startsWith('data: '))
             continue;
         try {
-            const usage = JSON.parse(line.slice(6)).usage;
+            const payload = JSON.parse(line.slice(6));
+            // Anthropic's message_start nests usage under `message`; message_delta and OpenAI carry it at the top level.
+            const usage = payload.usage ?? payload.message?.usage;
             if (!usage || typeof usage !== 'object')
                 continue;
             if (protocol === 'openai') {
-                tokensIn += Number(usage.prompt_tokens ?? usage.input_tokens ?? 0) || 0;
-                tokensOut += Number(usage.completion_tokens ?? usage.output_tokens ?? 0) || 0;
+                tokensIn = Math.max(tokensIn, Number(usage.prompt_tokens ?? usage.input_tokens ?? 0) || 0);
+                tokensOut = Math.max(tokensOut, Number(usage.completion_tokens ?? usage.output_tokens ?? 0) || 0);
             }
             else {
-                tokensIn += Number(usage.input_tokens ?? 0) || 0;
-                tokensOut += Number(usage.output_tokens ?? 0) || 0;
+                tokensIn = Math.max(tokensIn, Number(usage.input_tokens ?? 0) || 0);
+                tokensOut = Math.max(tokensOut, Number(usage.output_tokens ?? 0) || 0);
             }
         }
         catch { }
@@ -64,6 +80,18 @@ function upstreamAbort(abort, message) {
     reason.upstreamTimeout = true;
     abort.abort(reason);
 }
+/** Parse a Retry-After header (delta-seconds or HTTP-date) into a capped cooldown duration. */
+function retryAfterMs(value) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.min(seconds * 1000, RETRY_AFTER_MAX_MS);
+    const date = Date.parse(value);
+    if (!Number.isNaN(date))
+        return Math.min(Math.max(date - Date.now(), 0), RETRY_AFTER_MAX_MS);
+    return undefined;
+}
 export function createKhatServer(options) {
     const states = options.states ?? {};
     const secrets = { ...(options.secrets ?? {}) };
@@ -72,8 +100,26 @@ export function createKhatServer(options) {
     const statePath = options.statePath;
     const logger = options.store ? new LogWriter(join(options.store.dir, 'logs')) : undefined;
     const timeouts = () => ({ ...defaultTimeouts, ...options.config.timeouts });
-    const markUnavailable = async (providerId, keyId, status) => {
-        states[`${providerId}/${keyId}`] = { status: 'unavailable', lastError: { http: status, at: new Date().toISOString() } };
+    const markFailure = async (providerId, keyId, status, retryAfterHeader) => {
+        const ref = `${providerId}/${keyId}`;
+        const at = new Date().toISOString();
+        if (status === 429) {
+            // 429 is transient: cool down and auto-revive at cooldownUntil instead of dying permanently.
+            const previous = states[ref];
+            const count = previous?.status === 'cooldown' ? (previous.cooldownCount ?? 0) + 1 : 1;
+            const waitMs = retryAfterMs(retryAfterHeader) ?? Math.min(COOLDOWN_BASE_MS * 2 ** (count - 1), COOLDOWN_MAX_MS);
+            states[ref] = { status: 'cooldown', cooldownUntil: new Date(Date.now() + waitMs).toISOString(), cooldownCount: count, lastError: { http: status, at } };
+        }
+        else {
+            // 401/402 mean the key itself is bad; recovery requires a probe, manual enable, or the background prober.
+            states[ref] = { status: 'unavailable', lastError: { http: status, at } };
+        }
+        if (statePath)
+            await saveJsonAtomic(statePath, { keys: states, counters: options.store?.counters ?? {} });
+    };
+    const markHealthy = async (ref) => {
+        // A success clears cooldown residue and resets the backoff counter.
+        delete states[ref];
         if (statePath)
             await saveJsonAtomic(statePath, { keys: states, counters: options.store?.counters ?? {} });
     };
@@ -114,8 +160,16 @@ export function createKhatServer(options) {
             const tried = new Set();
             while (true) {
                 const key = selector.select(provider.id, provider.keys.filter((item) => !tried.has(item.id)), states);
-                if (!key)
-                    return json(res, 503, { error: { message: 'All keys are unavailable', keys: provider.keys.map((item) => ({ id: item.id, ...(states[`${provider.id}/${item.id}`] ?? { status: 'available' }) })) } });
+                if (!key) {
+                    const now = Date.now();
+                    const waits = provider.keys
+                        .map((item) => states[`${provider.id}/${item.id}`])
+                        .filter((state) => state?.status === 'cooldown' && Date.parse(state.cooldownUntil ?? '') > now)
+                        .map((state) => Date.parse(state.cooldownUntil));
+                    const earliest = waits.length ? Math.min(...waits) : undefined;
+                    const hint = earliest !== undefined ? ` (${waits.length} cooling down, earliest retry in ~${Math.ceil((earliest - now) / 1000)}s)` : '';
+                    return json(res, 503, { error: { message: `All keys are unavailable${hint}`, keys: provider.keys.map((item) => ({ id: item.id, ...(states[`${provider.id}/${item.id}`] ?? { status: 'available' }) })) } });
+                }
                 tried.add(key.id);
                 const secret = currentSecret(key.vaultRef);
                 if (secret === undefined)
@@ -137,7 +191,7 @@ export function createKhatServer(options) {
                     clearTimeout(headerTimer);
                 }
                 if (RETRYABLE.has(upstream.status)) {
-                    await markUnavailable(provider.id, key.id, upstream.status);
+                    await markFailure(provider.id, key.id, upstream.status, upstream.headers.get('retry-after'));
                     if (tried.size < provider.keys.length) {
                         res.off('close', clientGone);
                         continue;
@@ -155,28 +209,55 @@ export function createKhatServer(options) {
                 res.writeHead(upstream.status, responseHeaders);
                 if (upstream.body) {
                     const idleTimer = setTimeout(() => upstreamAbort(abort, 'upstream stream idle timeout'), timeouts().streamIdleMs);
+                    // Non-streaming JSON responses carry usage at the top level instead of in SSE lines;
+                    // buffer them (bounded) so their tokens can be counted too.
+                    const isEventStream = (upstream.headers.get('content-type') ?? '').toLowerCase().includes('text/event-stream');
+                    let jsonBuffer = isEventStream ? undefined : [];
+                    let jsonSize = 0;
                     try {
                         for await (const chunk of upstream.body) {
                             const buffer = Buffer.from(chunk);
                             if (firstByteAt === undefined)
                                 firstByteAt = Date.now();
                             bytes += buffer.length;
-                            const combined = sseRemainder + buffer.toString('utf8');
-                            const lastNewline = combined.lastIndexOf('\n');
-                            if (lastNewline >= 0) {
-                                const usage = scanUsage(protocol, combined.slice(0, lastNewline + 1));
-                                tokensIn += usage.tokensIn;
-                                tokensOut += usage.tokensOut;
-                                sseRemainder = combined.slice(lastNewline + 1);
+                            if (isEventStream) {
+                                const combined = sseRemainder + buffer.toString('utf8');
+                                const lastNewline = combined.lastIndexOf('\n');
+                                if (lastNewline >= 0) {
+                                    const usage = scanUsage(protocol, combined.slice(0, lastNewline + 1));
+                                    tokensIn = Math.max(tokensIn, usage.tokensIn);
+                                    tokensOut = Math.max(tokensOut, usage.tokensOut);
+                                    sseRemainder = combined.slice(lastNewline + 1);
+                                }
+                                else
+                                    sseRemainder = combined;
+                            }
+                            if (jsonBuffer) {
+                                jsonSize += buffer.length;
+                                if (jsonSize > USAGE_BUFFER_LIMIT)
+                                    jsonBuffer = undefined;
+                                else
+                                    jsonBuffer.push(buffer);
                             }
-                            else
-                                sseRemainder = combined;
                             res.write(buffer);
                             idleTimer.refresh();
                         }
-                        const usage = scanUsage(protocol, sseRemainder);
-                        tokensIn += usage.tokensIn;
-                        tokensOut += usage.tokensOut;
+                        if (isEventStream) {
+                            const usage = scanUsage(protocol, sseRemainder);
+                            tokensIn = Math.max(tokensIn, usage.tokensIn);
+                            tokensOut = Math.max(tokensOut, usage.tokensOut);
+                        }
+                        if (jsonBuffer) {
+                            try {
+                                const payload = JSON.parse(Buffer.concat(jsonBuffer).toString('utf8'));
+                                const jsonUsage = payload?.usage;
+                                if (jsonUsage && typeof jsonUsage === 'object') {
+                                    tokensIn = Math.max(tokensIn, Number(jsonUsage.prompt_tokens ?? jsonUsage.input_tokens ?? 0) || 0);
+                                    tokensOut = Math.max(tokensOut, Number(jsonUsage.completion_tokens ?? jsonUsage.output_tokens ?? 0) || 0);
+                                }
+                            }
+                            catch { }
+                        }
                     }
                     catch (error) {
                         if (error?.upstreamTimeout)
@@ -190,6 +271,8 @@ export function createKhatServer(options) {
                 const durationMs = Date.now() - startedAt;
                 const ttfbMs = (firstByteAt ?? Date.now()) - startedAt;
                 const keyRef = `${provider.id}/${key.id}`;
+                if (upstream.ok && states[keyRef])
+                    await markHealthy(keyRef);
                 options.store?.recordCounter(keyRef, { requests: 1, failed: upstream.ok ? 0 : 1, bytesOut: bytes, tokensIn, tokensOut });
                 try {
                     await logger?.append({ ts: new Date().toISOString(), event: 'forward', model: parsed.model, provider: provider.id, key: keyRef, status: upstream.status, ttfbMs, durationMs, bytes, tokensIn, tokensOut });
@@ -218,6 +301,19 @@ export function createKhatServer(options) {
                 if (next === undefined)
                     return;
                 const validated = validateConfig(next);
+                // The daemon is the single writer (ADR-0005): a disk copy older than the in-memory config
+                // can only be a stale echo of our own write, never a genuine external edit.
+                const diskRevision = validated.revision;
+                const memoryRevision = options.config.revision;
+                if (diskRevision !== undefined && memoryRevision !== undefined && diskRevision < memoryRevision)
+                    return;
+                // The socket keeps the address it was started with; adopting a new bind/port here would
+                // make status report an endpoint the process is not actually listening on.
+                if (validated.bind !== options.config.bind || validated.port !== options.config.port) {
+                    console.error(`[khat] bind/port change requires a restart; still listening on ${options.config.bind}:${options.config.port}`);
+                    validated.port = options.config.port;
+                    validated.bind = options.config.bind;
+                }
                 Object.assign(options.config, validated);
                 for (const key of Object.keys(secrets))
                     delete secrets[key];
@@ -233,6 +329,45 @@ export function createKhatServer(options) {
             }
         })();
     }) : undefined;
-    server.once('close', () => configWatcher?.close());
+    // Cooldown keys revive on their own at cooldownUntil (probing them early would just re-429
+    // and extend the cooldown), so the prober only targets permanently unavailable keys.
+    const probeIntervalMs = options.probeIntervalMs ?? PROBE_INTERVAL_MS;
+    let probeInFlight = false;
+    const runProbeCycle = async () => {
+        if (probeInFlight)
+            return;
+        probeInFlight = true;
+        try {
+            for (const provider of options.config.providers) {
+                const route = options.config.routes.find((item) => item.provider === provider.id);
+                if (!route)
+                    continue;
+                for (const target of provider.keys) {
+                    if (states[`${provider.id}/${target.id}`]?.status !== 'unavailable')
+                        continue;
+                    try {
+                        const secret = currentSecret(target.vaultRef);
+                        if (secret === undefined)
+                            continue;
+                        const status = await probeKey(provider, routeUpstreamModel(route), secret);
+                        if (status >= 200 && status < 300) {
+                            await options.store.mutate(() => enableKey(options.store, provider.id, target.id));
+                            await logger?.append({ ts: new Date().toISOString(), event: 'probe', provider: provider.id, key: `${provider.id}/${target.id}`, status, outcome: 'enabled' });
+                        }
+                    }
+                    catch (error) {
+                        console.error(`[khat] background probe failed for ${provider.id}/${target.id}: ${error?.message ?? error}`);
+                    }
+                }
+            }
+        }
+        finally {
+            probeInFlight = false;
+        }
+    };
+    const prober = options.store && probeIntervalMs > 0 ? setInterval(() => { void runProbeCycle(); }, probeIntervalMs) : undefined;
+    prober?.unref();
+    server.once('close', () => { configWatcher?.close(); if (prober)
+        clearInterval(prober); });
     return server;
 }

package/dist/store.js

@@ -43,7 +43,12 @@ export async function openStore(dir, protector) {
                 release();
             }
         },
-        saveConfig: () => saveJsonAtomic(configPath, config),
+        saveConfig: () => {
+            // Monotonic marker: lets the config watcher tell our own writes (and stale reads of them)
+            // apart from genuine external edits.
+            config.revision = Number.isInteger(config.revision) ? config.revision + 1 : 1;
+            return saveJsonAtomic(configPath, config);
+        },
         saveState: () => saveJsonAtomic(statePath, { keys: store.states, counters: store.counters }),
         recordCounter: (keyRef, delta) => {
             const current = store.counters[keyRef] ?? { requests: 0, failed: 0, bytesOut: 0, tokensIn: 0, tokensOut: 0 };
@@ -57,7 +62,9 @@ export async function openStore(dir, protector) {
             if (!stateTimer)
                 stateTimer = setTimeout(() => {
                     stateTimer = undefined;
-                    void store.saveState();
+                    store.saveState().catch((error) => {
+                        console.error(`[khat] failed to persist state: ${error?.message ?? error}`);
+                    });
                 }, 1_000);
             stateTimer.unref();
         }

package/dist/tui-state.js

@@ -8,8 +8,8 @@ export function keyRows(status) {
         for (const key of provider.keys)
             rows.push({ providerId: provider.id, keyId: key.id, key });
     }
+    const rank = (row) => (row.key.status === 'unavailable' ? 0 : row.key.status === 'cooldown' ? 1 : 2);
     return rows.sort((a, b) => {
-        const rank = (row) => (row.key.status === 'unavailable' ? 0 : 1);
         const byRank = rank(a) - rank(b);
         if (byRank !== 0)
             return byRank;
@@ -22,10 +22,12 @@ export function keyRows(status) {
 export function providerOf(status, id) {
     return status?.providers.find((item) => item.id === id);
 }
-/** Green = available, red = unavailable, yellow = available but failing often. */
+/** Green = available, yellow = cooling down or failing often, red = unavailable. */
 export function keyTone(key) {
     if (key.status === 'unavailable')
         return 'red';
+    if (key.status === 'cooldown')
+        return 'yellow';
     return key.counters.failed > 0 ? 'yellow' : 'green';
 }
 export function filterLogs(logs, filter) {

package/dist/tui.js

@@ -20,10 +20,11 @@ function Tabs({ section }) {
 function Edge({ text }) { return _jsx(Text, { dimColor: true, children: text }); }
 function KeyDetail({ row, status }) {
     const provider = providerOf(status, row.providerId);
-    return _jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [_jsxs(Text, { bold: true, color: "cyan", children: ["\u2500 ", row.providerId, "/", row.keyId, " (", provider?.protocol ?? '?', ") ", provider?.baseUrl ?? ''] }), _jsxs(Text, { children: ["\u72B6\u6001 ", _jsx(Dot, { tone: keyTone(row.key) }), " ", row.key.status === 'available' ? '可用' : '不可用', " \u00B7 \u6743\u91CD ", row.key.weight, " \u00B7 \u5BC6\u94A5 ", row.key.secret ?? '(缺失)'] }), _jsxs(Text, { children: ["\u8BF7\u6C42 ", n(row.key.counters.requests), " \u00B7 \u5931\u8D25 ", n(row.key.counters.failed), " \u00B7 \u5B57\u8282 ", bytes(row.key.counters.bytesOut), " \u00B7 tokens ", compact(row.key.counters.tokensIn), " / ", compact(row.key.counters.tokensOut)] }), _jsxs(Text, { children: ["\u6700\u8FD1\u9519\u8BEF ", row.key.lastError ? `HTTP ${row.key.lastError.http} · ${day(row.key.lastError.at)}` : '—'] })] });
+    const cooldownLeft = row.key.status === 'cooldown' ? Math.max(0, Math.ceil((Date.parse(row.key.cooldownUntil ?? '') - Date.now()) / 1000)) : undefined;
+    return _jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [_jsxs(Text, { bold: true, color: "cyan", children: ["\u2500 ", row.providerId, "/", row.keyId, " (", provider?.protocol ?? '?', ") ", provider?.baseUrl ?? ''] }), _jsxs(Text, { children: ["\u72B6\u6001 ", _jsx(Dot, { tone: keyTone(row.key) }), " ", row.key.status === 'available' ? '可用' : row.key.status === 'cooldown' ? `冷却中 · 约 ${cooldownLeft ?? '?'}s 后自动恢复` : '不可用', " \u00B7 \u6743\u91CD ", row.key.weight, " \u00B7 \u5BC6\u94A5 ", row.key.secret ?? '(缺失)'] }), _jsxs(Text, { children: ["\u8BF7\u6C42 ", n(row.key.counters.requests), " \u00B7 \u5931\u8D25 ", n(row.key.counters.failed), " \u00B7 \u5B57\u8282 ", bytes(row.key.counters.bytesOut), " \u00B7 tokens ", compact(row.key.counters.tokensIn), " / ", compact(row.key.counters.tokensOut)] }), _jsxs(Text, { children: ["\u6700\u8FD1\u9519\u8BEF ", row.key.lastError ? `HTTP ${row.key.lastError.http} · ${day(row.key.lastError.at)}` : '—'] })] });
 }
 function LogDetail({ log }) {
-    return _jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [_jsxs(Text, { bold: true, color: "cyan", children: ["\u2500 ", day(log.ts), " \u00B7 ", log.model] }), _jsxs(Text, { children: ["provider ", log.provider, " \u00B7 key ", log.key, " \u00B7 HTTP ", log.status, log.ttfbMs !== undefined ? ` · ttfb ${duration(log.ttfbMs)}` : ''] }), _jsxs(Text, { children: ["\u8017\u65F6 ", log.durationMs !== undefined ? duration(log.durationMs) : '—', " \u00B7 \u5927\u5C0F ", log.bytes !== undefined ? bytes(log.bytes) : '—', " \u00B7 tokens ", log.tokensIn !== undefined ? n(log.tokensIn) : '—', " / ", log.tokensOut !== undefined ? n(log.tokensOut) : '—'] })] });
+    return _jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [_jsxs(Text, { bold: true, color: "cyan", children: ["\u2500 ", day(log.ts), " \u00B7 ", log.model ?? '(probe)'] }), _jsxs(Text, { children: ["provider ", log.provider, " \u00B7 key ", log.key, " \u00B7 HTTP ", log.status, log.ttfbMs !== undefined ? ` · ttfb ${duration(log.ttfbMs)}` : ''] }), _jsxs(Text, { children: ["\u8017\u65F6 ", log.durationMs !== undefined ? duration(log.durationMs) : '—', " \u00B7 \u5927\u5C0F ", log.bytes !== undefined ? bytes(log.bytes) : '—', " \u00B7 tokens ", log.tokensIn !== undefined ? n(log.tokensIn) : '—', " / ", log.tokensOut !== undefined ? n(log.tokensOut) : '—'] })] });
 }
 function OverviewBody({ status, rows, cursor, detailOpen, height }) {
     const keys = rows.map((row) => row.key);
@@ -32,13 +33,14 @@ function OverviewBody({ status, rows, cursor, detailOpen, height }) {
     const tokensIn = keys.reduce((sum, item) => sum + item.counters.tokensIn, 0);
     const tokensOut = keys.reduce((sum, item) => sum + item.counters.tokensOut, 0);
     const unavailable = keys.filter((item) => item.status === 'unavailable').length;
+    const cooling = keys.filter((item) => item.status === 'cooldown').length;
     const tableHeight = Math.max(3, height - 5 - (detailOpen ? 5 : 0));
     const view = viewport(rows.length, cursor, tableHeight);
-    return _jsxs(Box, { flexDirection: "column", gap: 1, children: [status ? _jsxs(Text, { children: ["daemon ", _jsx(Dot, { tone: "green" }), " \u5728\u7EBF ", status.listen, " \u00B7 keys ", keys.length, unavailable > 0 ? _jsxs(Text, { color: "red", children: ["\uFF08", unavailable, " \u4E0D\u53EF\u7528\uFF09"] }) : null, " \u00B7 \u8BF7\u6C42 ", compact(requests), " \u00B7 \u5931\u8D25 ", compact(failed), " \u00B7 tokens ", compact(tokensIn), "/", compact(tokensOut)] }) : _jsx(Text, { dimColor: true, children: "\u7B49\u5F85 daemon \u6570\u636E\u2026" }), rows.length === 0 ? _jsx(Text, { dimColor: true, children: "\u6682\u65E0 key \u00B7 \u7528 khat provider add / khat key add \u6DFB\u52A0" }) : _jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: `   ${cell('PROVIDER', 14)}${cell('KEY', 14)}${'WT'.padStart(3)}  · ${'REQ'.padStart(8)}${'FAIL'.padStart(8)}${'ERR'.padStart(9)}` }), view.above > 0 && _jsx(Edge, { text: `  ↑ ${view.above} more` }), view.items.map((index) => {
+    return _jsxs(Box, { flexDirection: "column", gap: 1, children: [status ? _jsxs(Text, { children: ["daemon ", _jsx(Dot, { tone: "green" }), " \u5728\u7EBF ", status.listen, " \u00B7 keys ", keys.length, unavailable > 0 ? _jsxs(Text, { color: "red", children: ["\uFF08", unavailable, " \u4E0D\u53EF\u7528\uFF09"] }) : null, cooling > 0 ? _jsxs(Text, { color: "yellow", children: ["\uFF08", cooling, " \u51B7\u5374\u4E2D\uFF09"] }) : null, " \u00B7 \u8BF7\u6C42 ", compact(requests), " \u00B7 \u5931\u8D25 ", compact(failed), " \u00B7 tokens ", compact(tokensIn), "/", compact(tokensOut)] }) : _jsx(Text, { dimColor: true, children: "\u7B49\u5F85 daemon \u6570\u636E\u2026" }), rows.length === 0 ? _jsx(Text, { dimColor: true, children: "\u6682\u65E0 key \u00B7 \u7528 khat provider add / khat key add \u6DFB\u52A0" }) : _jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: `   ${cell('PROVIDER', 14)}${cell('KEY', 14)}${'WT'.padStart(3)}  · ${'REQ'.padStart(8)}${'FAIL'.padStart(8)}${'ERR'.padStart(9)}` }), view.above > 0 && _jsx(Edge, { text: `  ↑ ${view.above} more` }), view.items.map((index) => {
                         const row = rows[index];
                         const selected = index === cursor;
                         const tone = keyTone(row.key);
-                        return (_jsxs(Box, { children: [_jsx(Text, { color: selected ? 'yellow' : row.key.status === 'unavailable' ? 'red' : undefined, children: `${selected ? '›' : ' '} ${cell(row.providerId, 14)}${cell(row.keyId, 14)} ${String(row.key.weight).padStart(2)} ` }), _jsx(Dot, { tone: tone }), _jsx(Text, { color: selected ? 'yellow' : row.key.status === 'unavailable' ? 'red' : undefined, children: ` ${numCell(row.key.counters.requests, 8)}${numCell(row.key.counters.failed, 8)}${(row.key.lastError ? `HTTP ${row.key.lastError.http}` : '—').padStart(9)}` })] }, `${row.providerId}/${row.keyId}`));
+                        return (_jsxs(Box, { children: [_jsx(Text, { color: selected ? 'yellow' : row.key.status === 'unavailable' ? 'red' : row.key.status === 'cooldown' ? 'yellow' : undefined, children: `${selected ? '›' : ' '} ${cell(row.providerId, 14)}${cell(row.keyId, 14)} ${String(row.key.weight).padStart(2)} ` }), _jsx(Dot, { tone: tone }), _jsx(Text, { color: selected ? 'yellow' : row.key.status === 'unavailable' ? 'red' : row.key.status === 'cooldown' ? 'yellow' : undefined, children: ` ${numCell(row.key.counters.requests, 8)}${numCell(row.key.counters.failed, 8)}${(row.key.lastError ? `HTTP ${row.key.lastError.http}` : '—').padStart(9)}` })] }, `${row.providerId}/${row.keyId}`));
                     }), view.below > 0 && _jsx(Edge, { text: `  ↓ ${view.below} more` }), detailOpen && rows[cursor] && _jsx(KeyDetail, { row: rows[cursor], status: status })] })] });
 }
 function RoutesBody({ status, cursor, height }) {
@@ -57,7 +59,7 @@ function LogsBody({ logs, filter, cursor, detailOpen, height }) {
                         const log = rows[index];
                         const selected = index === cursor;
                         const failed = log.status >= 400;
-                        return (_jsx(Text, { color: selected ? 'yellow' : failed ? 'red' : undefined, children: `${selected ? '›' : ' '} ${cell(clock(log.ts), 8)} ${cell(String(log.status), 3)} ${cell(log.model, 26)}${cell(log.key, 14)}${(log.durationMs !== undefined ? duration(log.durationMs) : '—').padStart(8)}` }, `${log.ts}-${index}`));
+                        return (_jsx(Text, { color: selected ? 'yellow' : failed ? 'red' : undefined, children: `${selected ? '›' : ' '} ${cell(clock(log.ts), 8)} ${cell(String(log.status), 3)} ${cell(log.model ?? '(probe)', 26)}${cell(log.key, 14)}${(log.durationMs !== undefined ? duration(log.durationMs) : '—').padStart(8)}` }, `${log.ts}-${index}`));
                     }), view.below > 0 && _jsx(Edge, { text: `  ↓ ${view.below} more` }), detailOpen && rows[cursor] && _jsx(LogDetail, { log: rows[cursor] })] })] });
 }
 function DiagnosticsBody({ snapshot }) {

package/dist/web-ui.js

@@ -92,6 +92,7 @@ tbody tr:hover td{background:var(--surface-2)}
 .pill{display:inline-flex;align-items:center;gap:5px;height:21px;padding:1px 9px;border-radius:999px;font-size:12px;font-weight:600;border:1px solid;white-space:nowrap}
 .pill-status::before{content:'';width:6px;height:6px;border-radius:999px;background:currentColor;flex:none}
 .pill-ok{background:var(--ok-bg);color:var(--ok);border-color:var(--ok-border)}
+.pill-warn{background:var(--warn-bg);color:var(--warn);border-color:var(--warn-border)}
 .pill-bad{background:var(--bad-bg);color:var(--bad);border-color:var(--bad-border)}
 .protocol-pill{background:var(--accent-soft);color:var(--accent);border-color:transparent}
 .legend{display:flex;align-items:center;gap:14px;font-size:12px;color:var(--muted);align-self:center}
@@ -118,7 +119,7 @@ tbody tr:hover td{background:var(--surface-2)}
 <div id="toasts" class="toasts"></div>
 <header class="topbar"><div class="container topbar-inner">
 <div class="brand"><span class="logo" aria-hidden="true"></span><span>khat</span><span id="connection" class="conn-badge"></span></div>
-<div class="topbar-actions"><span class="auto-note" data-i18n="autoRefresh">每 30 秒自动刷新</span><button id="langToggle" class="btn btn-secondary btn-icon" type="button" data-i18n-aria="toggleLang" title="中文 / English">EN</button><button id="themeToggle" class="btn btn-secondary btn-icon" type="button" data-i18n-aria="toggleTheme" title="切换深色 / 浅色模式">🌙</button><button id="refresh" class="btn btn-secondary" type="button" data-i18n="refresh">刷新</button></div>
+<div class="topbar-actions"><span class="auto-note" data-i18n="autoRefresh">每 5 秒自动刷新</span><button id="langToggle" class="btn btn-secondary btn-icon" type="button" data-i18n-aria="toggleLang" title="中文 / English">EN</button><button id="themeToggle" class="btn btn-secondary btn-icon" type="button" data-i18n-aria="toggleTheme" title="切换深色 / 浅色模式">🌙</button><button id="refresh" class="btn btn-secondary" type="button" data-i18n="refresh">刷新</button></div>
 </div></header>
 <main class="container">
 <p id="error" class="alert alert-error"></p>
@@ -137,7 +138,7 @@ tbody tr:hover td{background:var(--surface-2)}
 <div class="card-head"><div><h2 class="card-title" data-i18n="cardProviders">Provider / Key 管理</h2><p class="card-sub" data-i18n="cardProvidersSub">维护服务商、密钥池与轮询权重；下方筛选均在本地完成，不会请求服务端。</p></div></div>
 <form id="providerForm" class="toolbar" autocomplete="off"><input name="id" placeholder="provider id" data-i18n-ph="phProviderId" required><input name="baseUrl" placeholder="https://api.example.com" data-i18n-ph="phBaseUrl" required><select name="protocol"><option>openai</option><option>anthropic</option></select><button class="btn btn-primary" data-i18n="btnAddProvider">添加 Provider</button></form>
 <form id="keyForm" class="toolbar" autocomplete="off"><select name="provider" required></select><input name="id" placeholder="key id" data-i18n-ph="phKeyId" required><input name="weight" type="number" min="1" step="1" value="1" data-i18n-title="weightTitle"><input name="value" type="password" placeholder="API key 明文（加密存入密钥库）" data-i18n-ph="phKeyValue" required autocomplete="new-password"><button class="btn btn-primary" data-i18n="btnAddKey">添加 Key</button></form>
-<div class="filter-bar"><input id="keySearch" type="search" placeholder="搜索 provider 名称 / baseUrl / key id / 错误原因…" data-i18n-ph="phSearchKey" data-i18n-aria="keyFilterAria" aria-label="筛选 Key"><select id="keyStatus" data-i18n-aria="statusFilterAria" aria-label="状态筛选"><option value="all" data-i18n="allStatus">全部状态</option><option value="available" data-i18n="onlyAvail">仅可用</option><option value="unavailable" data-i18n="onlyUnavail">仅不可用</option></select><span class="match-info" id="keyMatchInfo"></span></div>
+<div class="filter-bar"><input id="keySearch" type="search" placeholder="搜索 provider 名称 / baseUrl / key id / 错误原因…" data-i18n-ph="phSearchKey" data-i18n-aria="keyFilterAria" aria-label="筛选 Key"><select id="keyStatus" data-i18n-aria="statusFilterAria" aria-label="状态筛选"><option value="all" data-i18n="allStatus">全部状态</option><option value="available" data-i18n="onlyAvail">仅可用</option><option value="cooldown" data-i18n="onlyCooldown">仅冷却中</option><option value="unavailable" data-i18n="onlyUnavail">仅不可用</option></select><span class="match-info" id="keyMatchInfo"></span></div>
 <div id="providers"></div>
 </section>
 <section class="card">
@@ -161,8 +162,8 @@ const NS='http://www.w3.org/2000/svg';
 const pad2=n=>String(n).padStart(2,'0');
 const state={status:null,logs:[],logTail:'100',keyKeyword:'',keyStatus:'all',logKeyword:'',logStatus:'all',routeModels:[],routeSelected:new Set(),routeFilter:'',routeOpen:false,routeProvider:''};
 const I18N={
- zh:{title:'khat 密钥管理',toggleTheme:'切换深色 / 浅色模式',toggleLang:'切换语言',keyFilterAria:'筛选 Key',statusFilterAria:'状态筛选',resultFilterAria:'结果筛选',logCountAria:'日志条数',autoRefresh:'每 30 秒自动刷新',refresh:'刷新',statProviders:'Provider 数量',statProvidersSub:'已配置的服务商',statKeys:'Key 可用率',statReq:'近期请求成功率',statReqSub:'按最近一次拉取的日志统计',statTokens:'近期 Tokens 用量',statTokensSub:'输入 / 输出 合计',cardProviders:'Provider / Key 管理',cardProvidersSub:'维护服务商、密钥池与轮询权重；下方筛选均在本地完成，不会请求服务端。',phProviderId:'provider id',phName:'名称',phBaseUrl:'https://api.example.com',btnAddProvider:'添加 Provider',phKeyId:'key id',weightTitle:'轮询权重：该 key 在 Provider 内多个 key 间被选中的相对占比，默认 1',phKeyValue:'API key 明文（加密存入密钥库）',btnAddKey:'添加 Key',phSearchKey:'搜索 provider 名称 / baseUrl / key id / 错误原因…',allProviders:'全部 Provider',btnClearProvider:'显示全部 Provider',allStatus:'全部状态',onlyAvail:'仅可用',onlyUnavail:'仅不可用',cardRoutes:'Routes',cardRoutesSub:'模型到 Provider 的转发映射规则。',phModel:'model',btnAddRoute:'批量添加 Route',btnLoadModels:'获取模型',msEmpty:'请先获取模型',msLoading:'加载中…',msPlaceholder:'搜索 model…',msSelectAll:'全选',msSelected:'已选 {n} / {total}',msNoMatch:'无匹配模型',msNeedProvider:'请先选择 Provider',thModel:'Model',thProvider:'Provider',cardTraffic:'请求成功 / 失败趋势',cardTrafficSub:'将最近拉取的日志按时间分桶聚合（最多 30 桶），悬停柱体可查看详情。',legendOk:'成功',legendFail:'失败',chartEmpty:'暂无请求记录',cardLogs:'Logs',cardLogsSub:'最近的转发日志；关键字与结果类型为本地即时筛选，修改“条数”才会重新拉取。',phFilterLog:'按 model / key / provider / status 筛选…',allResult:'全部结果',onlyOk:'仅成功',onlyFail:'仅失败',logTail100:'最近 100 条',logTail300:'最近 300 条',logTail1000:'最近 1000 条',thTime:'Time',thStatus:'Status',thDuration:'Duration',thTokensInOut:'Tokens in/out',thKey:'Key',thWeight:'Weight',thRequests:'Requests',thFailed:'Failed',thErrReason:'错误原因',thActions:'操作',avail:'可用',unavail:'不可用',disabled:'已停用',noKeysMatch:'没有符合筛选条件的 key',noKeysYet:'该 Provider 尚未添加 key，可在上方表单中添加',keyMatchInfo:'匹配 {k} / {t} 个 key · 显示 {p} 个 Provider',noProviderMatch:'没有匹配的 Provider 或 Key，试试调整关键字或状态筛选。',noRoutes:'暂无路由配置',cardImport:'导入加密备份',cardImportSub:'选择 khat export 导出的 .khat 文件并输入导出密码；导入会替换当前的 Provider、Route 与密钥配置。',phImportPassword:'导出密码',btnImport:'导入',confirmImport:'导入将替换当前的 Provider、Route 与密钥配置，且无法撤销。确定继续？',importFileAria:'选择导出文件',imported:'导入成功：{s} 个密钥 · {p} 个 Provider · {r} 条 Route',errChooseFile:'请先选择导出文件',noLogs:'暂无请求日志',noLogMatch:'没有匹配的日志，试试调整筛选条件。',poolWarn:'Provider {p} 没有可用的 Key，请恢复或探活后再重试。',btnDisable:'停用',btnRecover:'恢复',btnProbe:'探活',btnDelete:'删除',confirmDelKey:'删除 key {p}/{k}？',saved:'已保存',errOpenViaUi:'请通过 khat ui 打开此页面',errTicket:'票据无效或已过期',err401:'401 未授权（key 无效或被撤销）',err402:'402 余额不足',err429:'429 限速',errHttp:'HTTP {h} 错误',errOccurredAt:'发生于',trafficTip:'{t}：成功 {ok} 次 · 失败 {bad} 次',showLogs:'显示 {n} / {t} 条',statKeysSubTpl:'可用 {a} 个 · 共 {t} 个',statReqSubTpl:'成功 {ok} 次 · 失败 {fail} 次',keyCountTpl:'{n} 个 key',trafficAria:'请求成功 / 失败趋势'},
- en:{title:'khat Key Manager',toggleTheme:'Toggle dark / light theme',toggleLang:'Switch language',keyFilterAria:'Filter keys',statusFilterAria:'Filter by status',resultFilterAria:'Filter by result',logCountAria:'Log count',autoRefresh:'Auto-refresh every 30s',refresh:'Refresh',statProviders:'Providers',statProvidersSub:'Configured services',statKeys:'Key availability',statReq:'Recent success rate',statReqSub:'From last fetched logs',statTokens:'Recent tokens',statTokensSub:'Input / Output total',cardProviders:'Provider / Key Management',cardProvidersSub:'Manage providers, key pools and weights; filtering is local only.',phProviderId:'provider id',phName:'Name',phBaseUrl:'https://api.example.com',btnAddProvider:'Add Provider',phKeyId:'key id',weightTitle:'Polling weight: relative share among keys in this provider, default 1',phKeyValue:'API key plaintext (stored encrypted)',btnAddKey:'Add Key',phSearchKey:'Search provider / baseUrl / key id / error…',allProviders:'All providers',btnClearProvider:'Show all providers',allStatus:'All status',onlyAvail:'Available only',onlyUnavail:'Unavailable only',cardRoutes:'Routes',cardRoutesSub:'Model-to-Provider forwarding rules.',phModel:'model',btnAddRoute:'Batch add Routes',btnLoadModels:'Load models',msEmpty:'Load models first',msLoading:'Loading…',msPlaceholder:'Search model…',msSelectAll:'Select all',msSelected:'{n} / {total} selected',msNoMatch:'No matching models',msNeedProvider:'Select a provider first',thModel:'Model',thProvider:'Provider',cardTraffic:'Request success / failure trend',cardTrafficSub:'Aggregates recent logs into time buckets (max 30). Hover bars for detail.',legendOk:'Success',legendFail:'Failure',chartEmpty:'No request records',cardLogs:'Logs',cardLogsSub:'Recent forwarding logs; keyword & result filtering is local; changing count re-fetches.',phFilterLog:'Filter by model / key / provider / status…',allResult:'All results',onlyOk:'Success only',onlyFail:'Failure only',logTail100:'Last 100',logTail300:'Last 300',logTail1000:'Last 1000',thTime:'Time',thStatus:'Status',thDuration:'Duration',thTokensInOut:'Tokens in/out',thKey:'Key',thWeight:'Weight',thRequests:'Requests',thFailed:'Failed',thErrReason:'Error reason',thActions:'Actions',avail:'Available',unavail:'Unavailable',disabled:'Disabled',noKeysMatch:'No keys match the filters',noKeysYet:'No keys yet for this provider; add via the form above',keyMatchInfo:'{k} / {t} keys matched · {p} providers shown',noProviderMatch:'No matching provider or key; adjust filters.',noRoutes:'No routes configured',cardImport:'Import encrypted backup',cardImportSub:'Pick a .khat file produced by khat export and enter its password; importing replaces the current providers, routes and keys.',phImportPassword:'Export password',btnImport:'Import',confirmImport:'Importing replaces the current providers, routes and keys. This cannot be undone. Continue?',importFileAria:'Choose export file',imported:'Imported: {s} secrets · {p} providers · {r} routes',errChooseFile:'Choose an export file first',noLogs:'No request logs',noLogMatch:'No matching logs; adjust filters.',poolWarn:'Provider {p} has no available keys. Recover or probe a key before retrying.',btnDisable:'Disable',btnRecover:'Enable',btnProbe:'Probe',btnDelete:'Delete',confirmDelKey:'Delete key {p}/{k}?',saved:'Saved',errOpenViaUi:'Please open this page via khat ui',errTicket:'Ticket invalid or expired',err401:'401 Unauthorized (key invalid or revoked)',err402:'402 Insufficient balance',err429:'429 Rate limited',errHttp:'HTTP {h} error',errOccurredAt:'at',trafficTip:'{t}: {ok} ok · {bad} failed',showLogs:'Showing {n} / {t}',statKeysSubTpl:'{a} available · {t} total',statReqSubTpl:'{ok} ok · {fail} failed',keyCountTpl:'{n} keys',trafficAria:'request success/failure trend'}
+ zh:{title:'khat 密钥管理',toggleTheme:'切换深色 / 浅色模式',toggleLang:'切换语言',keyFilterAria:'筛选 Key',statusFilterAria:'状态筛选',resultFilterAria:'结果筛选',logCountAria:'日志条数',autoRefresh:'每 5 秒自动刷新',refresh:'刷新',statProviders:'Provider 数量',statProvidersSub:'已配置的服务商',statKeys:'Key 可用率',statReq:'近期请求成功率',statReqSub:'按最近一次拉取的日志统计',statTokens:'近期 Tokens 用量',statTokensSub:'输入 / 输出 合计',cardProviders:'Provider / Key 管理',cardProvidersSub:'维护服务商、密钥池与轮询权重；下方筛选均在本地完成，不会请求服务端。',phProviderId:'provider id',phName:'名称',phBaseUrl:'https://api.example.com',btnAddProvider:'添加 Provider',phKeyId:'key id',weightTitle:'轮询权重：该 key 在 Provider 内多个 key 间被选中的相对占比，默认 1',phKeyValue:'API key 明文（加密存入密钥库）',btnAddKey:'添加 Key',phSearchKey:'搜索 provider 名称 / baseUrl / key id / 错误原因…',allProviders:'全部 Provider',btnClearProvider:'显示全部 Provider',allStatus:'全部状态',onlyAvail:'仅可用',onlyCooldown:'仅冷却中',onlyUnavail:'仅不可用',cardRoutes:'Routes',cardRoutesSub:'模型到 Provider 的转发映射规则。',phModel:'model',btnAddRoute:'批量添加 Route',btnLoadModels:'获取模型',msEmpty:'请先获取模型',msLoading:'加载中…',msPlaceholder:'搜索 model…',msSelectAll:'全选',msSelected:'已选 {n} / {total}',msNoMatch:'无匹配模型',msNeedProvider:'请先选择 Provider',thModel:'Model',thProvider:'Provider',cardTraffic:'请求成功 / 失败趋势',cardTrafficSub:'将最近拉取的日志按时间分桶聚合（最多 30 桶），悬停柱体可查看详情。',legendOk:'成功',legendFail:'失败',chartEmpty:'暂无请求记录',cardLogs:'Logs',cardLogsSub:'最近的转发日志；关键字与结果类型为本地即时筛选，修改“条数”才会重新拉取。',phFilterLog:'按 model / key / provider / status 筛选…',allResult:'全部结果',onlyOk:'仅成功',onlyFail:'仅失败',logTail100:'最近 100 条',logTail300:'最近 300 条',logTail1000:'最近 1000 条',thTime:'Time',thStatus:'Status',thDuration:'Duration',thTokensInOut:'Tokens in/out',thKey:'Key',thWeight:'Weight',thRequests:'Requests',thFailed:'Failed',thErrReason:'错误原因',thActions:'操作',avail:'可用',cooldown:'冷却中',unavail:'不可用',disabled:'已停用',noKeysMatch:'没有符合筛选条件的 key',noKeysYet:'该 Provider 尚未添加 key，可在上方表单中添加',keyMatchInfo:'匹配 {k} / {t} 个 key · 显示 {p} 个 Provider',noProviderMatch:'没有匹配的 Provider 或 Key，试试调整关键字或状态筛选。',noRoutes:'暂无路由配置',cardImport:'导入加密备份',cardImportSub:'选择 khat export 导出的 .khat 文件并输入导出密码；导入会替换当前的 Provider、Route 与密钥配置。',phImportPassword:'导出密码',btnImport:'导入',confirmImport:'导入将替换当前的 Provider、Route 与密钥配置，且无法撤销。确定继续？',importFileAria:'选择导出文件',imported:'导入成功：{s} 个密钥 · {p} 个 Provider · {r} 条 Route',errChooseFile:'请先选择导出文件',noLogs:'暂无请求日志',noLogMatch:'没有匹配的日志，试试调整筛选条件。',poolWarn:'Provider {p} 没有可用的 Key，请恢复或探活后再重试。',btnDisable:'停用',btnRecover:'恢复',btnProbe:'探活',btnDelete:'删除',confirmDelKey:'删除 key {p}/{k}？',saved:'已保存',errOpenViaUi:'请通过 khat ui 打开此页面',errTicket:'票据无效或已过期',err401:'401 未授权（key 无效或被撤销）',err402:'402 余额不足',err429:'429 限速',errHttp:'HTTP {h} 错误',errOccurredAt:'发生于',trafficTip:'{t}：成功 {ok} 次 · 失败 {bad} 次',showLogs:'显示 {n} / {t} 条',statKeysSubTpl:'可用 {a} 个 · 共 {t} 个',statReqSubTpl:'成功 {ok} 次 · 失败 {fail} 次',keyCountTpl:'{n} 个 key',trafficAria:'请求成功 / 失败趋势'},
+ en:{title:'khat Key Manager',toggleTheme:'Toggle dark / light theme',toggleLang:'Switch language',keyFilterAria:'Filter keys',statusFilterAria:'Filter by status',resultFilterAria:'Filter by result',logCountAria:'Log count',autoRefresh:'Auto-refresh every 5s',refresh:'Refresh',statProviders:'Providers',statProvidersSub:'Configured services',statKeys:'Key availability',statReq:'Recent success rate',statReqSub:'From last fetched logs',statTokens:'Recent tokens',statTokensSub:'Input / Output total',cardProviders:'Provider / Key Management',cardProvidersSub:'Manage providers, key pools and weights; filtering is local only.',phProviderId:'provider id',phName:'Name',phBaseUrl:'https://api.example.com',btnAddProvider:'Add Provider',phKeyId:'key id',weightTitle:'Polling weight: relative share among keys in this provider, default 1',phKeyValue:'API key plaintext (stored encrypted)',btnAddKey:'Add Key',phSearchKey:'Search provider / baseUrl / key id / error…',allProviders:'All providers',btnClearProvider:'Show all providers',allStatus:'All status',onlyAvail:'Available only',onlyCooldown:'Cooling only',onlyUnavail:'Unavailable only',cardRoutes:'Routes',cardRoutesSub:'Model-to-Provider forwarding rules.',phModel:'model',btnAddRoute:'Batch add Routes',btnLoadModels:'Load models',msEmpty:'Load models first',msLoading:'Loading…',msPlaceholder:'Search model…',msSelectAll:'Select all',msSelected:'{n} / {total} selected',msNoMatch:'No matching models',msNeedProvider:'Select a provider first',thModel:'Model',thProvider:'Provider',cardTraffic:'Request success / failure trend',cardTrafficSub:'Aggregates recent logs into time buckets (max 30). Hover bars for detail.',legendOk:'Success',legendFail:'Failure',chartEmpty:'No request records',cardLogs:'Logs',cardLogsSub:'Recent forwarding logs; keyword & result filtering is local; changing count re-fetches.',phFilterLog:'Filter by model / key / provider / status…',allResult:'All results',onlyOk:'Success only',onlyFail:'Failure only',logTail100:'Last 100',logTail300:'Last 300',logTail1000:'Last 1000',thTime:'Time',thStatus:'Status',thDuration:'Duration',thTokensInOut:'Tokens in/out',thKey:'Key',thWeight:'Weight',thRequests:'Requests',thFailed:'Failed',thErrReason:'Error reason',thActions:'Actions',avail:'Available',cooldown:'Cooling',unavail:'Unavailable',disabled:'Disabled',noKeysMatch:'No keys match the filters',noKeysYet:'No keys yet for this provider; add via the form above',keyMatchInfo:'{k} / {t} keys matched · {p} providers shown',noProviderMatch:'No matching provider or key; adjust filters.',noRoutes:'No routes configured',cardImport:'Import encrypted backup',cardImportSub:'Pick a .khat file produced by khat export and enter its password; importing replaces the current providers, routes and keys.',phImportPassword:'Export password',btnImport:'Import',confirmImport:'Importing replaces the current providers, routes and keys. This cannot be undone. Continue?',importFileAria:'Choose export file',imported:'Imported: {s} secrets · {p} providers · {r} routes',errChooseFile:'Choose an export file first',noLogs:'No request logs',noLogMatch:'No matching logs; adjust filters.',poolWarn:'Provider {p} has no available keys. Recover or probe a key before retrying.',btnDisable:'Disable',btnRecover:'Enable',btnProbe:'Probe',btnDelete:'Delete',confirmDelKey:'Delete key {p}/{k}?',saved:'Saved',errOpenViaUi:'Please open this page via khat ui',errTicket:'Ticket invalid or expired',err401:'401 Unauthorized (key invalid or revoked)',err402:'402 Insufficient balance',err429:'429 Rate limited',errHttp:'HTTP {h} error',errOccurredAt:'at',trafficTip:'{t}: {ok} ok · {bad} failed',showLogs:'Showing {n} / {t}',statKeysSubTpl:'{a} available · {t} total',statReqSubTpl:'{ok} ok · {fail} failed',keyCountTpl:'{n} keys',trafficAria:'request success/failure trend'}
 };
 let lang=(()=>{try{return localStorage.getItem('khatLang')==='en'?'en':'zh'}catch(e){return 'zh'}})();
 function t(key){return (I18N[lang]&&I18N[lang][key])||I18N.zh[key]||key}
@@ -178,7 +179,19 @@ function formatTs(ts){const d=new Date(ts);if(isNaN(d.getTime()))return String(t
 function errText(k){const http=k.lastError&&k.lastError.http;if(http===undefined)return '—';if(http===401)return t('err401');if(http===402)return t('err402');if(http===429)return t('err429');return tf('errHttp',{h:http})}
 function btn(label,className,onclick){const b=document.createElement('button');b.type='button';b.className=className;b.textContent=label;b.onclick=onclick;return b}
 function run(fn){return async arg=>{try{await fn(arg)}catch(e){error.textContent=e.message;toast(e.message)}}}
-function statusCell(ok,text,title){const td=document.createElement('td');const sp=document.createElement('span');sp.className='pill pill-status '+(ok?'pill-ok':'pill-bad');sp.textContent=text;if(title)sp.title=title;td.append(sp);return td}
+function statusCell(kind,text,title){const td=document.createElement('td');const sp=document.createElement('span');sp.className='pill pill-status '+kind;sp.textContent=text;if(title)sp.title=title;td.append(sp);return td}
+function cdUntilText(until){const s=Math.max(0,Math.ceil((Date.parse(until||'')-Date.now())/1000));return t('cooldown')+' · '+s+'s'}
+function cdText(k){return cdUntilText(k.cooldownUntil)}
+/** Route availability mirrors its provider's key pool: a route with no usable key cannot serve. */
+function routePool(providerId){
+ const p=(state.status?state.status.providers:[]).find(x=>x.id===providerId);
+ const keys=(p?p.keys:[]).filter(k=>k.enabled!==false);
+ if(!keys.length)return{state:'unavail'};
+ if(keys.some(k=>k.status==='available'))return{state:'avail'};
+ const cooling=keys.filter(k=>k.status==='cooldown');
+ if(cooling.length)return{state:'cooldown',earliest:Math.min(...cooling.map(k=>Date.parse(k.cooldownUntil||'')))};
+ return{state:'unavail'};
+}
 function syncProviderSelect(sel,providers,allowEmpty){const ids=providers.map(p=>p.id).join(',');if(sel.dataset.ids===ids&&(!allowEmpty||sel.dataset.allowEmpty==='1'))return;sel.dataset.ids=ids;if(allowEmpty)sel.dataset.allowEmpty='1';const prev=sel.value;const options=providers.map(p=>{const o=document.createElement('option');o.value=p.id;o.textContent=p.id;return o});if(allowEmpty){const o=document.createElement('option');o.value='';o.textContent=t('allProviders');options.unshift(o)}sel.replaceChildren(...options);if(ids.split(',').includes(prev)||allowEmpty&&!prev)sel.value=prev}
 function renderConnection(){if(!state.status)return;const c=$('#connection');c.replaceChildren(Object.assign(document.createElement('i'),{className:'dot'}),document.createTextNode(' '+state.status.listen))}
 function renderStats(){const st=state.status;if(!st)return;const keys=[];for(const p of st.providers)for(const k of p.keys)keys.push(k);const avail=keys.filter(k=>k.enabled!==false&&k.status==='available').length;$('#statProviders').textContent=String(st.providers.length);$('#statKeys').textContent=keys.length?Math.round(avail*100/keys.length)+'%':'—';$('#statKeysSub').textContent=keys.length?tf('statKeysSubTpl',{a:avail,t:keys.length}):'—';let ok=0,fail=0,tIn=0,tOut=0;for(const x of state.logs){if(Number(x.status)<400)ok++;else fail++;tIn+=x.tokensIn||0;tOut+=x.tokensOut||0}const total=ok+fail;$('#statReq').textContent=total?Math.round(ok*100/total)+'%':'—';$('#statReqSub').textContent=tf('statReqSubTpl',{ok:ok,fail:fail});$('#statTokens').textContent=total?fmtNum(tIn)+' / '+fmtNum(tOut):'—'}
@@ -211,7 +224,7 @@ function renderProviders(){
    if(k.secret){const sk=document.createElement('span');sk.className='key-secret';sk.textContent=k.secret;kt.append(sk)}
    tr.append(kt);
    tr.append(cell(k.weight,'num'));
-   tr.append(statusCell(k.enabled!==false&&k.status==='available',k.enabled===false?t('disabled'):(k.status==='available'?t('avail'):t('unavail')),k.lastError?errText(k)+(k.lastError.at?' · '+t('errOccurredAt')+' '+k.lastError.at:''):''));
+   tr.append(statusCell(k.enabled===false?'pill-bad':k.status==='available'?'pill-ok':k.status==='cooldown'?'pill-warn':'pill-bad',k.enabled===false?t('disabled'):(k.status==='available'?t('avail'):k.status==='cooldown'?cdText(k):t('unavail')),k.lastError?errText(k)+(k.lastError.at?' · '+t('errOccurredAt')+' '+k.lastError.at:''):''));
    tr.append(cell(k.counters.requests||0,'num'),cell(k.counters.failed||0,'num'),cell((k.counters.tokensIn||0)+' / '+(k.counters.tokensOut||0),'num'));
    const et=document.createElement('td');et.textContent=errText(k);et.className=k.lastError?'err-text':'err-text none';if(k.lastError)et.title=t('errOccurredAt')+' '+k.lastError.at;
    tr.append(et);
@@ -239,7 +252,13 @@ function renderRoutes(){
   if(!rs.length){const er=document.createElement('tr');er.className='empty-row';const ed=document.createElement('td');ed.colSpan=5;ed.textContent=t('noRoutes');er.append(ed);tb.append(er);return}
   for(const rt of rs){
    const tr=document.createElement('tr');
-   tr.append(cell(rt.model,'mono-cell'),cell(rt.upstreamModel||rt.model,'mono-cell'),cell(rt.provider),statusCell(rt.enabled!==false,rt.enabled!==false?t('avail'):t('unavail')));
+   const pool=routePool(rt.provider);
+   let pillKind,pillText,pillTitle;
+   if(rt.enabled===false){pillKind='pill-bad';pillText=t('disabled')}
+   else if(pool.state==='avail'){pillKind='pill-ok';pillText=t('avail')}
+   else if(pool.state==='cooldown'){pillKind='pill-warn';pillText=cdUntilText(new Date(pool.earliest||Date.now()).toISOString())}
+   else{pillKind='pill-bad';pillText=t('unavail');pillTitle=tf('poolWarn',{p:rt.provider})}
+   tr.append(cell(rt.model,'mono-cell'),cell(rt.upstreamModel||rt.model,'mono-cell'),cell(rt.provider),statusCell(pillKind,pillText,pillTitle));
   const d=document.createElement('td');
   const toggle=rt.enabled!==false?'disable':'enable';
   d.append(btn(rt.enabled!==false?t('btnDisable'):t('btnRecover'),'btn btn-secondary btn-sm',run(async()=>{await api('/_keys/routes/'+toggle+'?model='+encodeURIComponent(rt.model),{method:'POST'});toast(t('saved'),'ok');load()})));
@@ -295,7 +314,7 @@ function renderLogs(){
  for(const e of rows){
   const r=document.createElement('tr');
   r.append(cell(formatTs(e.ts),'mono-cell'));
-  r.append(statusCell(Number(e.status)<400,String(e.status)));
+  r.append(statusCell(Number(e.status)<400?'pill-ok':'pill-bad',String(e.status)));
   r.append(cell(e.provider,'mono-cell'),cell(e.key,'mono-cell'),cell(e.model,'mono-cell'));
   r.append(cell((e.durationMs==null?0:e.durationMs)+'ms','num'));
   r.append(cell((e.tokensIn||0)+' / '+(e.tokensOut||0),'num'));
@@ -399,13 +418,25 @@ $('#refresh').onclick=()=>load();
 window.addEventListener('resize',drawTraffic);
 load();setInterval(load,5000);
 </script></body></html>`;
+/** Web UI sessions: sliding 1-hour expiry, so a closed tab does not leave an authorized session on the server forever. */
 export class UiSessions {
+    ttlMs;
     tickets = new Map();
-    sessions = new Set();
+    sessions = new Map();
+    constructor(ttlMs = 3_600_000) {
+        this.ttlMs = ttlMs;
+    }
     createTicket() { const t = randomBytes(32).toString('base64url'); this.tickets.set(t, Date.now() + 60000); return t; }
     exchange(t) { const expires = this.tickets.get(t); this.tickets.delete(t); if (expires === undefined || expires < Date.now())
-        return undefined; const s = randomBytes(32).toString('base64url'); this.sessions.add(s); return s; }
-    valid(s) { return s !== undefined && this.sessions.has(s); }
+        return undefined; const now = Date.now(); for (const [s, e] of this.sessions)
+        if (e < now)
+            this.sessions.delete(s); const s = randomBytes(32).toString('base64url'); this.sessions.set(s, now + this.ttlMs); return s; }
+    valid(s) { if (s === undefined)
+        return false; const expires = this.sessions.get(s); if (expires === undefined)
+        return false; const now = Date.now(); if (expires < now) {
+        this.sessions.delete(s);
+        return false;
+    } this.sessions.set(s, now + this.ttlMs); return true; }
 }
 export function serveUi(req, res) { const path = new URL(req.url ?? '/', 'http://localhost').pathname; if (path !== '/_keys/ui' && path !== '/_keys/ui/')
     return false; res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' }); res.end(PAGE); return true; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alilis/k-hat",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "publishConfig": {
     "access": "public"
   },
@@ -38,7 +38,8 @@
     "prepare": "npm run build",
     "start": "node dist/cli.js start",
     "khat": "node dist/cli.js",
-    "test": "npm run build && node --test test/**/*.test.js"
+    "test": "npm run build && node --test test/**/*.test.js",
+    "bench": "node bench/bench.js"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",