@byokit/usage 0.1.0 → 0.3.0

package/dist/providers.js

@@ -1,17 +1,34 @@
+import { retryAfterMs } from "./backoff.js";
 import { spawn } from 'node:child_process';
-import { record } from "./windows.js";
-export async function providerGet(source, fetcher, nowMs) {
+import { readJson, readJsonSnapshot } from "./store.js";
+import { claudeWindows, record } from "./windows.js";
+import { grokWindows } from "./quota.js";
+const USER_AGENT = 'byokit/usage/0.2.0';
+/** One bounded request; credentials and response bodies never become errors. */
+async function request(url, key, fetcher, nowMs, extra = {}, pacing) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 10_000);
+    const abort = () => controller.abort();
+    pacing?.signal?.addEventListener('abort', abort, { once: true });
+    if (pacing?.signal?.aborted)
+        controller.abort();
+    const timer = setTimeout(abort, 10_000);
     try {
-        const url = source.provider === 'opencode' ? 'https://opencode.ai/zen/go/v1/usage' : 'https://api.z.ai/api/monitor/usage/quota/limit';
-        const response = await fetcher(url, { headers: { accept: 'application/json', authorization: `Bearer ${source.key}` }, redirect: 'error', signal: controller.signal });
+        if (pacing?.hook)
+            await Promise.race([pacing.hook({ provider: pacing.provider, account: pacing.account, origin: new URL(url).origin, signal: controller.signal }), new Promise((_, reject) => {
+                    if (controller.signal.aborted)
+                        reject(new Error());
+                    else
+                        controller.signal.addEventListener('abort', () => reject(new Error()), { once: true });
+                })]);
+        if (controller.signal.aborted)
+            return { code: 'unavailable' };
+        const response = await fetcher(url, { headers: { accept: 'application/json', authorization: `Bearer ${key}`, 'User-Agent': USER_AGENT,
+                ...(extra.body !== undefined ? { 'content-type': 'application/json' } : {}), ...extra.headers },
+            ...(extra.body !== undefined ? { method: 'POST', body: JSON.stringify(extra.body) } : {}), redirect: 'error', signal: controller.signal });
         if (response.status === 429) {
-            const retry = response.headers.get('retry-after');
-            const seconds = Number(retry);
-            const delay = retry !== null && Number.isFinite(seconds) ? seconds * 1000 : Date.parse(retry ?? '') - nowMs;
+            const delay = retryAfterMs(response.headers.get('retry-after'), nowMs);
             controller.abort();
-            return { code: 'rate-limited', until: nowMs + Math.max(300_000, Number.isFinite(delay) ? delay : 0) };
+            return { code: 'rate-limited', retryAfterMs: delay };
         }
         if (response.status !== 200) {
             controller.abort();
@@ -40,17 +57,84 @@ export async function providerGet(source, fetcher, nowMs) {
         catch {
             return { code: 'incomplete' };
         }
-        if (!record(raw))
-            return { code: 'incomplete' };
-        if (source.provider === 'zai' && raw.success === false)
-            return { code: 'no-plan' };
-        return { raw: source.provider === 'opencode' ? raw.usage : record(raw.data) ? raw.data.limits : undefined };
+        return record(raw) ? { raw } : { code: 'incomplete' };
+    }
+    catch {
+        return { code: 'unavailable' };
+    }
+    finally {
+        clearTimeout(timer);
+        pacing?.signal?.removeEventListener('abort', abort);
+    }
+}
+export async function providerGet(source, fetcher, nowMs, pacing) {
+    const key = 'access' in source ? source.access : source.key;
+    const get = (url, extra) => request(url, key, fetcher, nowMs, extra, pacing);
+    switch (source.provider) {
+        case 'claude': return get('https://api.anthropic.com/api/oauth/usage', { headers: { 'anthropic-beta': 'oauth-2025-04-20' } });
+        case 'codex': return get('https://chatgpt.com/backend-api/wham/usage', { headers: { 'ChatGPT-Account-Id': source.accountId } });
+        case 'copilot': return get('https://api.github.com/copilot_internal/user');
+        case 'minimax': {
+            const answer = await get('https://api.minimax.io/v1/token_plan/remains');
+            return !answer.code && record(answer.raw) && record(answer.raw.base_resp) && answer.raw.base_resp.status_code !== 0 ? { code: 'no-plan' } : answer;
+        }
+        case 'kimi': return get('https://api.kimi.com/coding/v1/usages');
+        case 'grok': {
+            const answer = await get('https://cli-chat-proxy.grok.com/v1/billing?format=credits');
+            if (answer.code)
+                return answer;
+            const config = record(answer.raw) && record(answer.raw.config) ? answer.raw.config : undefined;
+            return config?.isUnifiedBillingUser === true || !grokWindows(answer.raw).length ? get('https://cli-chat-proxy.grok.com/v1/billing') : answer;
+        }
+        case 'gemini': {
+            let project = source.project;
+            if (!project) {
+                const loaded = await get('https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist', { body: { metadata: { ideType: 'IDE_UNSPECIFIED', platform: 'PLATFORM_UNSPECIFIED', pluginType: 'GEMINI' } } });
+                if (loaded.code)
+                    return loaded;
+                const value = record(loaded.raw) ? loaded.raw.cloudaicompanionProject : undefined;
+                project = typeof value === 'string' ? value : record(value) && typeof value.id === 'string' ? value.id : undefined;
+            }
+            return get('https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuota', { body: project ? { project } : {} });
+        }
+        case 'opencode': return get('https://opencode.ai/zen/go/v1/usage');
+        case 'zai': {
+            const answer = await get('https://api.z.ai/api/monitor/usage/quota/limit');
+            return !answer.code && record(answer.raw) && answer.raw.success === false ? { code: 'no-plan' } : answer;
+        }
+    }
+}
+/** A host hook gets the same deadline and failure envelope as built-in sources. */
+export async function customClaude(source, nowMs, pacing) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    pacing?.signal?.addEventListener('abort', abort, { once: true });
+    if (pacing?.signal?.aborted)
+        controller.abort();
+    const timer = setTimeout(abort, 10_000);
+    try {
+        const operation = async () => {
+            if (source.origin && pacing?.hook)
+                await pacing.hook({ provider: source.provider, account: pacing.account, origin: source.origin, signal: controller.signal });
+            if (controller.signal.aborted)
+                return { code: 'unavailable' };
+            const answer = await source.read({ nowMs, signal: controller.signal });
+            // Host readers may return cached figures; only the host knows observation time.
+            return { ...answer, at: answer.at };
+        };
+        return await Promise.race([operation(), new Promise((resolve) => {
+                if (controller.signal.aborted)
+                    resolve({ code: 'unavailable' });
+                else
+                    controller.signal.addEventListener('abort', () => resolve({ code: 'unavailable' }), { once: true });
+            })]);
     }
     catch {
         return { code: 'unavailable' };
     }
     finally {
         clearTimeout(timer);
+        pacing?.signal?.removeEventListener('abort', abort);
     }
 }
 export function codexUsage(source) {
@@ -107,3 +191,32 @@ export function codexUsage(source) {
         child.stdin.write(`${JSON.stringify({ id: 1, method: 'initialize', params: { clientInfo: { name: 'byokit', version: '1' } } })}\n`);
     });
 }
+/** Re-read the tool's credentials so its own renewal is picked up; never renew or write them. */
+export function claudeAuth(source) {
+    const stored = readJson(source.credentialsFile, 64 * 1024);
+    const credentials = record(stored) && record(stored.claudeAiOauth) ? stored.claudeAiOauth : undefined;
+    const token = credentials?.accessToken;
+    if (!credentials || typeof token !== 'string' || !token.trim() || token.length > 16384 || token.includes('\0'))
+        return undefined;
+    const config = source.configFile ? readJson(source.configFile, 4 * 1024 * 1024) : undefined;
+    const oauthAccount = record(config) && record(config.oauthAccount) ? config.oauthAccount : undefined;
+    const identity = typeof credentials.accountUuid === 'string' ? credentials.accountUuid : typeof oauthAccount?.accountUuid === 'string' ? oauthAccount.accountUuid : `claude-file\0${source.credentialsFile}`;
+    if (typeof identity !== 'string' || !identity || identity.length > 16384)
+        return undefined;
+    return { token, account: identity, ...(typeof credentials.expiresAt === 'number' && Number.isFinite(credentials.expiresAt) ? { expiresAt: credentials.expiresAt } : {}) };
+}
+export async function claudeUsage(source, fetcher, nowMs, pacing) {
+    const snapshot = source.statuslineFile ? readJsonSnapshot(source.statuslineFile, 64 * 1024) : undefined;
+    if (snapshot && record(snapshot.value) && claudeWindows(snapshot.value).length) {
+        const rawTime = snapshot.value.fetched_at;
+        const at = typeof rawTime === 'number' ? rawTime : typeof rawTime === 'string' ? Date.parse(rawTime) : undefined;
+        if (at === undefined || !Number.isFinite(at) || nowMs < at || nowMs - at < 300_000)
+            return { raw: snapshot.value, at };
+    }
+    const auth = claudeAuth(source);
+    if (!auth)
+        return { code: 'not-connected' };
+    if (auth.expiresAt !== undefined && auth.expiresAt <= nowMs)
+        return { code: 'expired' };
+    return providerGet({ provider: 'claude', access: auth.token }, fetcher, nowMs, pacing);
+}

package/dist/quota.d.ts

@@ -0,0 +1,8 @@
+import type { Window } from './types.ts';
+export declare function codexTokenWindows(raw: unknown, nowMs?: number): Window[];
+export declare function codexHardLimit(raw: unknown): boolean;
+export declare function copilotWindows(raw: unknown): Window[];
+export declare function grokWindows(raw: unknown): Window[];
+export declare function minimaxWindows(raw: unknown): Window[];
+export declare function geminiWindows(raw: unknown): Window[];
+export declare function kimiWindows(raw: unknown, nowMs: number): Window[];

package/dist/quota.js

@@ -0,0 +1,91 @@
+// Protocol shapes informed by can1357/oh-my-pi (MIT), pinned at 2b023d1.
+// This module normalizes quota fields only; it does not import upstream runtime code.
+import { record, window, codexWindows } from "./windows.js";
+const obj = (value) => record(value) ? value : {};
+const rows = (value) => Array.isArray(value) ? value : [];
+const number = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+const label = (value) => typeof value === 'string' ? value.replace(/[^\x20-\x7e]/g, ' ').trim().slice(0, 80) || undefined : undefined;
+const time = (value) => typeof value === 'string' ? Date.parse(value) : number(value);
+const ratio = (used, limit, remaining) => {
+    const cap = number(limit);
+    const consumed = number(used);
+    const left = number(remaining);
+    return cap !== undefined && cap > 0 && (consumed !== undefined || left !== undefined) ? 100 * (consumed ?? cap - left) / cap : undefined;
+};
+export function codexTokenWindows(raw, nowMs) {
+    const source = obj(raw);
+    const plan = obj(source.rate_limit);
+    const group = (value, name) => ({ limitName: name, limitReached: value.limit_reached === true,
+        ...Object.fromEntries(['primary', 'secondary'].filter((key) => record(value[`${key}_window`])).map((key) => {
+            const w = obj(value[`${key}_window`]);
+            return [key, { usedPercent: w.used_percent, windowDurationMins: typeof w.limit_window_seconds === 'number' ? w.limit_window_seconds / 60 : undefined, resetsAt: w.reset_at !== undefined ? w.reset_at : number(w.reset_after_seconds) !== undefined && number(w.reset_after_seconds) >= 0 && nowMs !== undefined ? (nowMs + number(w.reset_after_seconds) * 1000) / 1000 : undefined }];
+        })) });
+    return codexWindows({ rateLimitsByLimitId: Object.fromEntries([
+            ['plan', group(plan, 'Codex')], ...rows(source.additional_rate_limits).map((v, i) => { const extra = obj(v); return [String(i), group(obj(extra.rate_limit), label(extra.limit_name))]; }),
+        ]) });
+}
+export function codexHardLimit(raw) {
+    const source = obj(raw);
+    return obj(source.rate_limit).limit_reached === true || obj(source.rateLimits).limitReached === true || Object.values(obj(source.rateLimitsByLimitId)).some((v) => obj(v).limitReached === true) || rows(source.additional_rate_limits).some((v) => obj(obj(v).rate_limit).limit_reached === true);
+}
+export function copilotWindows(raw) {
+    const source = obj(raw);
+    return Object.entries(obj(source.quota_snapshots)).flatMap(([key, value]) => {
+        const quota = obj(value);
+        if (quota.unlimited === true)
+            return [];
+        const left = number(quota.percent_remaining);
+        return window('copilot', 'monthly', left === undefined ? ratio(undefined, quota.entitlement, quota.remaining) : 100 - left, undefined, time(source.quota_reset_date), false, label(key));
+    });
+}
+export function grokWindows(raw) {
+    const config = obj(obj(raw).config);
+    const period = obj(config.currentPeriod);
+    const weekly = number(config.creditUsagePercent);
+    if (weekly !== undefined)
+        return window('grok', 'weekly', weekly, 10080, time(period.end));
+    return window('grok', 'monthly', ratio(config.used, config.monthlyLimit), undefined, time(config.periodEnd));
+}
+export function minimaxWindows(raw) {
+    const source = obj(raw);
+    if (obj(source.base_resp).status_code !== 0)
+        return [];
+    return rows(source.model_remains).flatMap((value) => {
+        const bucket = obj(value);
+        if (bucket.current_interval_status === 3 && bucket.current_weekly_status === 3 && bucket.current_interval_total_count === 0 && bucket.current_weekly_total_count === 0)
+            return [];
+        return ['interval', 'weekly'].flatMap((key) => {
+            const left = number(bucket[`current_${key}_remaining_percent`]);
+            const exhausted = bucket[`current_${key}_status`] === 2;
+            const rawReset = bucket[key === 'interval' ? 'end_time' : 'weekly_end_time'];
+            const reset = typeof rawReset === 'number' && rawReset > 0 ? rawReset < 1e12 ? rawReset * 1000 : rawReset : time(rawReset);
+            return window('minimax', key === 'weekly' ? 'weekly' : 'rolling', exhausted ? 100 : left === undefined ? undefined : 100 - left, key === 'weekly' ? 10080 : undefined, reset, exhausted, label(bucket.model_name));
+        });
+    });
+}
+export function geminiWindows(raw) {
+    return rows(obj(raw).buckets).flatMap((value) => {
+        const bucket = obj(value);
+        const left = number(bucket.remainingFraction);
+        return window('gemini', 'custom', left === undefined ? undefined : 100 - left * 100, undefined, time(bucket.resetTime), false, label(bucket.modelId));
+    });
+}
+export function kimiWindows(raw, nowMs) {
+    const source = obj(raw);
+    const read = (value, minutes, reset) => {
+        const detail = obj(value);
+        const units = { SECOND: 1 / 60, MINUTE: 1, HOUR: 60, DAY: 1440, WEEK: 10080 };
+        const w = obj(detail.window);
+        const duration = number(w.duration);
+        const m = minutes ?? (duration === undefined ? undefined : duration * (units[String(w.timeUnit).toUpperCase().replace(/S$/, '')] ?? NaN));
+        const row = record(detail.detail) ? detail.detail : detail;
+        const resetValue = reset ?? w.resetTime ?? row.resetTime ?? row.reset_at ?? row.resetAt;
+        let resetMs = time(resetValue);
+        if (typeof resetValue === 'number')
+            resetMs = resetValue > 1e12 ? resetValue : resetValue * 1000;
+        if (resetValue === undefined && number(row.reset_in) !== undefined)
+            resetMs = nowMs + number(row.reset_in) * 1000;
+        return window('kimi', m === 300 ? 'session' : m === 10080 ? 'weekly' : m === 43200 ? 'monthly' : 'custom', ratio(row.used, row.limit, row.remaining), m, resetMs);
+    };
+    return [...read(source.usage, 10080), ...read(source.totalQuota), ...rows(source.limits).flatMap((row) => read(row))];
+}

package/dist/room.d.ts

@@ -0,0 +1,3 @@
+import type { Reading, Room } from './types.ts';
+/** Figures retain their observation age; poll failure does not imply exhaustion. */
+export declare function roomOf(reading: Reading, nowMs: number): Room;

package/dist/room.js

@@ -0,0 +1,25 @@
+/** Figures retain their observation age; poll failure does not imply exhaustion. */
+export function roomOf(reading, nowMs) {
+    const at = reading.at;
+    const ageMs = at !== undefined && Number.isFinite(at) && Number.isFinite(nowMs) && nowMs >= at ? nowMs - at : undefined;
+    const freshness = at === undefined || !Number.isFinite(at) || !Number.isFinite(nowMs) ? 'unknown' : nowMs < at ? 'future' : ageMs > 86_400_000 ? 'stale' : 'fresh';
+    const meta = { ...(at !== undefined ? { at } : {}), ...(ageMs !== undefined ? { ageMs } : {}), freshness,
+        ...(reading.poll ? { poll: reading.poll } : {}) };
+    const blocked = reading.windows.find((w) => w.limited === true);
+    // A reset prediction never clears an authoritative block, even in an old reading.
+    if (reading.limited || blocked)
+        return { ...meta, left: 0, span: 'tightest', limited: true,
+            ...(blocked?.scope ? { scope: blocked.scope } : {}), ...(blocked?.resetsAt !== undefined ? { resetsAt: blocked.resetsAt } : {}) };
+    if (freshness !== 'fresh' || ['not-connected', 'expired', 'auth', 'no-plan'].includes(reading.code ?? ''))
+        return { ...meta, left: 'unknown' };
+    const tight = reading.windows.reduce((worst, w) => typeof w.usedPercent === 'number' && Number.isFinite(w.usedPercent) && (!worst || w.usedPercent > worst.usedPercent) ? w : worst, undefined);
+    if (!tight)
+        return { ...meta, left: 'unknown' };
+    const span = tight.kind === 'weekly' ? 'week' : tight.kind === 'monthly' ? 'month' : tight.kind === 'session' ? 'session' : 'tightest';
+    const left = Math.max(0, Math.min(100, 100 - tight.usedPercent));
+    // Incomplete applicable windows cannot establish available room. Known exhaustion still stands.
+    if (left > 0 && reading.windows.some((w) => w.usedPercent === undefined))
+        return { ...meta, left: 'unknown' };
+    return { ...meta, left, span, ...(tight.scope ? { scope: tight.scope } : {}),
+        ...(Number.isFinite(tight.resetsAt) ? { resetsAt: tight.resetsAt } : {}) };
+}

package/dist/store.d.ts

@@ -1,12 +1,15 @@
-import type { Provider } from './types.ts';
-export interface Stored {
-    at: number;
-    raw: unknown;
-}
+import type { Provider, StoredReading, UsageStore, Window, Poll } from './types.ts';
+export type Stored = StoredReading;
 /** Bounded regular files only; do not follow credential or state symlinks. */
+export declare function readJsonSnapshot(file: string, cap: number): {
+    value: unknown;
+    modified: number;
+} | undefined;
 export declare function readJson(file: string, cap: number): unknown;
 export declare function fingerprint(salt: string): (provider: Provider, value: string) => string;
-export declare function store(stateDir: string): {
-    get: (id: Provider, fp: string) => Stored | undefined;
-    put(id: Provider, fp: string, reading: Stored): void;
-};
+/** Poll metadata is distinct from the observation timestamp. */
+export declare function safePoll(raw: unknown): Poll | undefined;
+export declare function store(stateDir: string): UsageStore;
+/** Public stores receive only these quota fields, never raw provider payloads. */
+export declare function safeWindows(provider: Provider, raw: unknown): Window[];
+export declare function memoryUsageStore(): UsageStore;

package/dist/store.js

@@ -1,9 +1,10 @@
 import { createHash, randomUUID, scryptSync } from 'node:crypto';
 import { chmodSync, closeSync, fstatSync, mkdirSync, openSync, readSync, renameSync, unlinkSync, writeFileSync, constants } from 'node:fs';
-import { join } from 'node:path';
-import { record } from "./windows.js";
+import { isAbsolute, join } from 'node:path';
+import { UsageError } from "./types.js";
+import { record, quotaScope } from "./windows.js";
 /** Bounded regular files only; do not follow credential or state symlinks. */
-export function readJson(file, cap) {
+export function readJsonSnapshot(file, cap) {
     let fd;
     try {
         fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
@@ -18,7 +19,7 @@ export function readJson(file, cap) {
                 break;
             length += count;
         }
-        return length <= cap ? JSON.parse(body.subarray(0, length).toString('utf8')) : undefined;
+        return length <= cap ? { value: JSON.parse(body.subarray(0, length).toString('utf8')), modified: stat.mtimeMs } : undefined;
     }
     catch {
         return undefined;
@@ -28,6 +29,7 @@ export function readJson(file, cap) {
             closeSync(fd);
     }
 }
+export function readJson(file, cap) { return readJsonSnapshot(file, cap)?.value; }
 export function fingerprint(salt) {
     const memo = new Map();
     return (provider, value) => {
@@ -42,21 +44,29 @@ export function fingerprint(salt) {
         return fp;
     };
 }
+/** Poll metadata is distinct from the observation timestamp. */
+export function safePoll(raw) {
+    if (!record(raw) || typeof raw.at !== 'number' || !Number.isFinite(raw.at) || !['ok', 'not-connected', 'expired', 'auth', 'no-plan', 'rate-limited', 'unavailable', 'incomplete', 'refresh-failed'].includes(String(raw.outcome)))
+        return undefined;
+    return { at: raw.at, outcome: raw.outcome, ...(typeof raw.retryAt === 'number' && Number.isFinite(raw.retryAt) ? { retryAt: raw.retryAt } : {}) };
+}
 export function store(stateDir) {
-    const path = join(stateDir, 'plans-v1.json');
+    if (typeof stateDir !== 'string' || !isAbsolute(stateDir) || /[\0\r\n]/.test(stateDir))
+        throw new UsageError();
+    const path = join(stateDir, 'plans-v2.json');
     function load() {
         const saved = readJson(path, 256 * 1024);
         const plans = {};
         if (!record(saved) || !record(saved.plans))
             return plans;
-        for (const id of ['claude', 'codex', 'opencode', 'zai']) {
+        for (const id of ['claude', 'codex', 'opencode', 'zai', 'copilot', 'grok', 'minimax', 'gemini', 'kimi']) {
             const entries = saved.plans[id];
             if (!record(entries))
                 continue;
             const readings = Object.create(null);
             for (const [fp, r] of Object.entries(entries)) {
-                if (/^[a-f0-9]{64}$/.test(fp) && record(r) && typeof r.at === 'number' && Number.isFinite(r.at))
-                    readings[fp] = { at: r.at, raw: r.raw };
+                if (/^[a-f0-9]{64}$/.test(fp) && record(r) && (r.at === undefined || typeof r.at === 'number' && Number.isFinite(r.at)))
+                    readings[fp] = { ...(typeof r.at === 'number' ? { at: r.at } : {}), windows: safeWindows(id, r.windows), ...(r.limited === true ? { limited: true } : {}), ...(safePoll(r.poll) ? { poll: safePoll(r.poll) } : {}) };
             }
             plans[id] = readings;
         }
@@ -65,13 +75,15 @@ export function store(stateDir) {
     return {
         get: (id, fp) => load()[id]?.[fp],
         put(id, fp, reading) {
+            if (!/^[a-f0-9]{64}$/.test(fp) || !Number.isFinite(reading.at))
+                return;
             const temporary = `${path}.${randomUUID()}.tmp`;
             try {
                 const plans = load();
                 const entries = plans[id] ?? {};
-                if (reading.at < (entries[fp]?.at ?? -Infinity))
+                if (reading.at !== undefined && reading.at < (entries[fp]?.at ?? -Infinity))
                     return;
-                entries[fp] = reading;
+                entries[fp] = { at: reading.at, windows: safeWindows(id, reading.windows), ...(reading.limited ? { limited: true } : {}), ...(safePoll(reading.poll) ? { poll: safePoll(reading.poll) } : {}) };
                 plans[id] = entries;
                 const body = JSON.stringify({ plans });
                 if (Buffer.byteLength(body) > 256 * 1024)
@@ -91,3 +103,22 @@ export function store(stateDir) {
         },
     };
 }
+/** Public stores receive only these quota fields, never raw provider payloads. */
+export function safeWindows(provider, raw) {
+    return (Array.isArray(raw) ? raw : []).slice(0, 64).flatMap((value) => {
+        if (!record(value) || !['session', 'weekly', 'monthly', 'rolling', 'custom'].includes(String(value.kind)) || value.usedPercent !== undefined && (typeof value.usedPercent !== 'number' || !Number.isFinite(value.usedPercent)))
+            return [];
+        return [{ provider, kind: value.kind, ...(typeof value.usedPercent === 'number' ? { usedPercent: Math.max(0, Math.min(100, value.usedPercent)) } : {}),
+                ...(quotaScope(value.scope) ? { scope: quotaScope(value.scope) } : {}),
+                ...(typeof value.minutes === 'number' && Number.isFinite(value.minutes) && value.minutes > 0 ? { minutes: value.minutes } : {}),
+                ...(typeof value.resetsAt === 'number' && Number.isFinite(value.resetsAt) ? { resetsAt: value.resetsAt } : {}),
+                ...(value.limited === true ? { limited: true } : {}),
+                ...(typeof value.limit === 'string' && value.limit.length <= 80 ? { limit: value.limit } : {}) }];
+    });
+}
+export function memoryUsageStore() {
+    const readings = new Map();
+    return { get: (provider, account) => { const r = readings.get(`${provider}\0${account}`); return r ? { at: r.at, windows: safeWindows(provider, r.windows), ...(r.limited ? { limited: true } : {}), ...(safePoll(r.poll) ? { poll: safePoll(r.poll) } : {}) } : undefined; },
+        put: (provider, account, reading) => { const key = `${provider}\0${account}`; if (reading.at === undefined || reading.at >= (readings.get(key)?.at ?? -Infinity))
+            readings.set(key, { at: reading.at, windows: safeWindows(provider, reading.windows), ...(reading.limited ? { limited: true } : {}), ...(safePoll(reading.poll) ? { poll: safePoll(reading.poll) } : {}) }); } };
+}

package/dist/types.d.ts

@@ -1,47 +1,149 @@
-export type Provider = 'claude' | 'codex' | 'opencode' | 'zai';
-/** Claude's credential adapter belongs to the host; only its parser ships here. */
+export type Provider = 'claude' | 'codex' | 'opencode' | 'zai' | 'copilot' | 'grok' | 'minimax' | 'gemini' | 'kimi';
+/** Host-owned identity makes readings survive token renewal. Tokens never become stored identities. */
+type Identity = {
+    accountId?: string;
+};
 export type Source = {
     provider: 'codex';
     bin: string;
     home: string;
     env?: Record<string, string>;
 } | {
-    provider: 'opencode';
-    key: string;
-} | {
-    provider: 'zai';
+    provider: 'codex';
+    access: string;
+    accountId: string;
+} | ({
+    provider: 'claude';
+    access: string;
+    accountUuid?: string;
+} & Identity) | ({
+    provider: 'claude';
+    accountUuid: string;
+    read: ClaudeReader;
+    origin?: string;
+    connected?: () => boolean;
+}) | {
+    provider: 'claude';
+    credentialsFile: string;
+    configFile?: string;
+    statuslineFile?: string;
+} | ({
+    provider: 'opencode' | 'zai';
     key: string;
-};
+} & Identity) | ({
+    provider: 'copilot' | 'grok' | 'minimax' | 'kimi';
+    access: string;
+} & Identity) | ({
+    provider: 'gemini';
+    access: string;
+    project?: string;
+} & Identity);
 export type Kind = 'session' | 'weekly' | 'monthly' | 'rolling' | 'custom';
+/** All reset times are epoch milliseconds in 0.2.0. */
 export type Window = {
     provider: Provider;
     kind: Kind;
     limit?: string;
-    usedPercent: number;
+    usedPercent?: number;
+    scope?: Scope;
     minutes?: number;
     resetsAt?: number;
     limited?: boolean;
 };
-export type Code = 'not-connected' | 'expired' | 'auth' | 'no-plan' | 'rate-limited' | 'unavailable' | 'incomplete';
+export type Scope = {
+    model?: string;
+    surface?: string;
+};
+export type Poll = {
+    at: number;
+    outcome: Code | 'ok';
+    retryAt?: number;
+};
+export type Freshness = 'fresh' | 'stale' | 'future' | 'unknown';
+export type Code = 'not-connected' | 'expired' | 'auth' | 'no-plan' | 'rate-limited' | 'unavailable' | 'incomplete' | 'refresh-failed';
 export type Reading = {
     provider: Provider;
     windows: Window[];
-    at: number;
+    at?: number;
+    limited?: boolean;
+    poll?: Poll;
     code?: Code;
 };
+export type Room = {
+    at?: number;
+    ageMs?: number;
+    freshness: Freshness;
+    poll?: Poll;
+    scope?: Scope;
+    limited?: boolean;
+} & ({
+    left: number;
+    span: 'session' | 'week' | 'month' | 'tightest';
+    resetsAt?: number;
+} | {
+    left: 'unknown';
+});
 export type ReadOptions = {
     nowMs?: number;
+    signal?: AbortSignal;
+};
+export type SourceAnswer = {
+    raw?: unknown;
+    code?: Code;
+    retryAfterMs?: number;
+    limited?: boolean;
+    at?: number;
+};
+/** The app owns credential reads/refresh and sends its own requests through this seam. */
+export type ClaudeReader = (options: {
+    nowMs: number;
+    signal: AbortSignal;
+}) => Promise<SourceAnswer>;
+export type StoredReading = {
+    at?: number;
+    windows: Window[];
+    limited?: boolean;
+    poll?: Poll;
+};
+export interface UsageStore {
+    get(provider: Provider, account: string): StoredReading | undefined;
+    put(provider: Provider, account: string, reading: StoredReading): void;
+}
+export type BackoffState = {
+    untilMs: number;
+    at: number;
+    outcome: Code;
+    failures: number;
 };
+export interface BackoffPolicy {
+    get(provider: Provider, account: string): number | BackoffState | undefined;
+    set(provider: Provider, account: string, untilMs: number, state?: BackoffState): void;
+    /** Retry-After duration to wait; context carries the current outcome and its consecutive failures. */
+    delayMs?(retryAfterMs: number | undefined, context: {
+        outcome: Code;
+        failures: number;
+    }): number;
+}
+export type PacingHook = (request: {
+    provider: Provider;
+    account: string;
+    origin: string;
+    signal: AbortSignal;
+}) => Promise<void>;
 export type UsageOptions = {
-    stateDir: string;
+    stateDir?: string;
+    store?: UsageStore;
+    backoff?: BackoffPolicy;
     salt?: string;
     fetch?: typeof fetch;
     now?: () => number;
+    pace?: PacingHook;
 };
 export interface Usage {
     read(source: Source, options?: ReadOptions): Promise<Reading>;
     lastKnown(source: Source, options?: ReadOptions): Reading | undefined;
     connected(source: Source): boolean;
+    /** Stable identity fingerprint, absent for an opaque token without a host-supplied id. */
     account(source: Source): string | undefined;
 }
 export declare class UsageError extends Error {
@@ -49,3 +151,4 @@ export declare class UsageError extends Error {
     name: string;
     constructor();
 }
+export {};

package/dist/windows.d.ts

@@ -1,6 +1,9 @@
-import type { Window } from './types.ts';
+import type { Kind, Provider, Window, Scope } from './types.ts';
 export declare const record: (v: unknown) => v is Record<string, unknown>;
-/** Accepts both the statusline envelope and the provider's usage payload. */
+export declare function window(provider: Provider, kind: Kind, used: unknown, minutes?: number, resetsAt?: number, limited?: boolean, limit?: string): Window[];
+/** Scope is an allowlisted descriptor, never arbitrary provider data. */
+export declare function quotaScope(raw: unknown): Scope | undefined;
+/** Normalized rows override legacy aggregates of the same kind, even if incomplete. */
 export declare function claudeWindows(raw: unknown): Window[];
 /** Accepts the `usage` member; monthly length is deliberately absent. */
 export declare function goWindows(raw: unknown): Window[];