sidekick-shared 0.25.0 → 0.26.0

package/dist/providers/rolloutWalker.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * One capped walker for Codex rollout files.
+ *
+ * Codex writes `<home>/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl`.
+ * Six recursive, uncapped walkers used to exist across the provider and the
+ * quota resolver; this module replaces them with a single walk that caps
+ * depth and file count, visits the newest-dated directories first so a
+ * `limit` can stop early, stats each file exactly once, and returns results
+ * newest first with the size and session id already attached.
+ *
+ * With `limit`, the early exit is by directory date: a rollout that was
+ * created days ago but is still being written lands in its creation day's
+ * directory, so a very small limit can miss it in favour of newer-dated,
+ * older-modified files. Callers that need exact mtime order over the whole
+ * history omit `limit` (the `maxFiles` cap still applies).
+ *
+ * @module providers/rolloutWalker
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ROLLOUT_WALK_MAX_FILES = exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH = void 0;
+exports.isRolloutFile = isRolloutFile;
+exports.extractRolloutSessionId = extractRolloutSessionId;
+exports.walkRolloutFiles = walkRolloutFiles;
+exports.walkRolloutFilesAsync = walkRolloutFilesAsync;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH = 6;
+exports.DEFAULT_ROLLOUT_WALK_MAX_FILES = 20_000;
+/** Test if a filename is a Codex rollout file. */
+function isRolloutFile(filename) {
+    return filename.startsWith('rollout-') && filename.endsWith('.jsonl');
+}
+/**
+ * Extract the session UUID from a rollout filename.
+ * Format: rollout-<timestamp>-<uuid>.jsonl -> <uuid>
+ */
+function extractRolloutSessionId(filename) {
+    const base = path.basename(filename, '.jsonl');
+    // rollout-YYYYMMDD-HHMMSS-<uuid> or rollout-<timestamp>-<uuid>
+    const parts = base.split('-');
+    // The UUID is typically the last 5 segments (8-4-4-4-12)
+    if (parts.length >= 6) {
+        const possibleUuid = parts.slice(-5).join('-');
+        if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(possibleUuid)) {
+            return possibleUuid;
+        }
+    }
+    // Fallback: use everything after "rollout-"
+    return base.replace(/^rollout-/, '');
+}
+function walkState(options) {
+    const maxFiles = Math.max(0, options.maxFiles ?? exports.DEFAULT_ROLLOUT_WALK_MAX_FILES);
+    const limit = options.limit === undefined ? Infinity : Math.max(0, options.limit);
+    return {
+        results: [],
+        seen: new Set(),
+        cap: Math.min(maxFiles, limit),
+        maxDepth: options.maxDepth ?? exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH,
+        sessionId: options.sessionId ? options.sessionId.trim().toLowerCase() : null,
+        includeEmpty: options.includeEmpty ?? false,
+    };
+}
+/** Newest-dated first: directory and file names sort descending. */
+function byNameDescending(a, b) {
+    return b.name.localeCompare(a.name);
+}
+function matchesFilter(state, name) {
+    if (!isRolloutFile(name))
+        return false;
+    return (state.sessionId === null || extractRolloutSessionId(name).toLowerCase() === state.sessionId);
+}
+function record(state, fullPath, name, stat) {
+    if (!state.includeEmpty && stat.size <= 0)
+        return;
+    if (state.seen.has(fullPath))
+        return;
+    state.seen.add(fullPath);
+    state.results.push({
+        path: fullPath,
+        mtime: stat.mtime,
+        sizeBytes: stat.size,
+        sessionId: extractRolloutSessionId(name),
+    });
+}
+function finish(state) {
+    return state.results.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+}
+function visitSync(state, dir, depth) {
+    if (depth > state.maxDepth || state.results.length >= state.cap)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort(byNameDescending);
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (!entry.isFile() || !matchesFilter(state, entry.name))
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        try {
+            record(state, fullPath, entry.name, fs.statSync(fullPath));
+        }
+        catch {
+            // Skip files that vanish between readdir and stat.
+        }
+    }
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (entry.isDirectory())
+            visitSync(state, path.join(dir, entry.name), depth + 1);
+    }
+}
+/**
+ * Walk one or more `sessions` roots for rollout files, newest first.
+ * Missing or unreadable directories are skipped; paths are deduplicated.
+ */
+function walkRolloutFiles(roots, options = {}) {
+    const state = walkState(options);
+    for (const root of roots)
+        visitSync(state, root, 0);
+    return finish(state);
+}
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+async function visitAsync(state, dir, depth) {
+    if (depth > state.maxDepth || state.results.length >= state.cap)
+        return;
+    let entries;
+    try {
+        entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort(byNameDescending);
+    let sinceYield = 0;
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (!entry.isFile() || !matchesFilter(state, entry.name))
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        try {
+            record(state, fullPath, entry.name, await fs.promises.stat(fullPath));
+        }
+        catch {
+            // Skip files that vanish between readdir and stat.
+        }
+        if (++sinceYield >= 200) {
+            sinceYield = 0;
+            await yieldToEventLoop();
+        }
+    }
+    await yieldToEventLoop();
+    for (const entry of entries) {
+        if (state.results.length >= state.cap)
+            return;
+        if (entry.isDirectory())
+            await visitAsync(state, path.join(dir, entry.name), depth + 1);
+    }
+}
+/** Async twin of {@link walkRolloutFiles} that yields between directories. */
+async function walkRolloutFilesAsync(roots, options = {}) {
+    const state = walkState(options);
+    for (const root of roots)
+        await visitAsync(state, root, 0);
+    return finish(state);
+}

package/dist/providers/types.d.ts

@@ -11,6 +11,7 @@
 import type { ReadSessionContextSnapshotOptions, SessionContextSnapshot } from '../context/sessionContext';
 import type { SessionEvent, SubagentStats, TokenUsage, ContextAttribution } from '../types/sessionEvent';
 import { SESSION_PROVIDER_IDS } from '../providerIds';
+import type { AggregatedCostProvenance } from '../aggregation/types';
 /** Stable runtime list for consumers that must enumerate session providers. */
 export { SESSION_PROVIDER_IDS } from '../providerIds';
 export type ProviderId = (typeof SESSION_PROVIDER_IDS)[number];
@@ -58,6 +59,12 @@ export interface SessionFileInfo {
     /** Optional provider-recorded creation timestamp. */
     createdAt?: Date;
 }
+/** How much of a session `readSessionStats()` could read. */
+export type SessionFileStatsAvailability = 'full' | 'partial' | 'unavailable';
+/**
+ * Aggregated stats for one session file, computed by `computeSessionFileStats()`
+ * over the shared `EventAggregator` for every provider.
+ */
 export interface SessionFileStats {
     providerId: ProviderId;
     sessionId: string;
@@ -66,19 +73,42 @@ export interface SessionFileStats {
     startTime: string;
     endTime: string;
     messageCount: number;
+    /** Token buckets; `summarizeTokens()` turns them into the cache-inclusive total. */
     tokens: {
         input: number;
         output: number;
         cacheWrite: number;
         cacheRead: number;
     };
+    /**
+     * Per-model calls, cache-inclusive token total (the `summarizeTokens().total`
+     * vocabulary), priced cost, and whether every call could be priced.
+     */
     modelUsage: Record<string, {
         calls: number;
         tokens: number;
+        costUsd: number;
+        priced: boolean;
     }>;
+    /** Calls per tool name: successful, failed, and still pending. */
     toolUsage: Record<string, number>;
+    /** Failed calls per tool name; a subset of `toolUsage`. */
+    toolFailures: Record<string, number>;
     compactionEstimate: number;
     truncationCount: number;
+    /** Cost of the priced portion of the session; read `costProvenance` before labelling it. */
+    costUsd: number;
+    costProvenance: AggregatedCostProvenance;
+    /** Usage events with neither a provider-reported cost nor a catalog price. */
+    unpricedCalls: number;
+    /**
+     * `full` when every event was read, `partial` when the reader reported a
+     * truncated source, `unavailable` when the session could not be read at all
+     * (`unavailableReason` says why and every number is zero).
+     */
+    availability: SessionFileStatsAvailability;
+    unavailableReason?: string;
+    /** @deprecated Same value as `costUsd`; use it together with `costProvenance`. */
     reportedCost: number;
 }
 export interface ProjectFolderInfo {

package/dist/quota.d.ts

@@ -46,12 +46,26 @@ export interface QuotaState {
     projectedSevenDay?: number;
     /** Provider that produced this quota sample */
     providerId?: QuotaProviderId;
-    /** Source of the sample */
-    source?: 'api' | 'session' | 'cache';
+    /**
+     * Source of the sample. `statusline` is the official rate-limit block Claude
+     * Code hands to its status-line command; `session` is inferred from session
+     * logs; `api` is a live usage-endpoint fetch; `cache` is a persisted snapshot.
+     */
+    source?: 'api' | 'session' | 'cache' | 'statusline';
+    /**
+     * Where a cached sample originally came from. `readQuotaSnapshot()` forces
+     * `source` to `cache`; this keeps the origin (`statusline`, `session`, `api`)
+     * so a reader can rank an official status-line sample above a session guess.
+     */
+    capturedSource?: 'api' | 'session' | 'statusline';
     /** ISO timestamp when the sample was captured */
     capturedAt?: string;
     /** Whether the sample is stale cached data */
     stale?: boolean;
+    /** Milliseconds between `capturedAt` and the read, when read from a snapshot. */
+    ageMs?: number;
+    /** Freshness tier derived from `ageMs`; see `classifyQuotaFreshness`. */
+    freshness?: QuotaFreshness;
     /** Provider-specific display label for the first window */
     fiveHourLabel?: string;
     /** Provider-specific display label for the second window */
@@ -71,6 +85,16 @@ export interface QuotaState {
 }
 export declare const FIVE_HOUR_WINDOW_MS: number;
 export declare const SEVEN_DAY_WINDOW_MS: number;
+/** How much to trust a cached quota sample, by age. */
+export type QuotaFreshness = 'fresh' | 'aging' | 'stale';
+/** A snapshot younger than this is as good as live. */
+export declare const QUOTA_FRESH_MAX_AGE_MS: number;
+/** A snapshot older than this should be labelled as stale wherever it is shown. */
+export declare const QUOTA_AGING_MAX_AGE_MS: number;
+/** Classify a cached sample's age. Non-finite or negative ages count as stale. */
+export declare function classifyQuotaFreshness(ageMs: number | undefined): QuotaFreshness;
+/** Compact age label for status lines and table footers: `just now`, `3m ago`, `2h ago`, `3d ago`. */
+export declare function formatQuotaAge(ageMs: number | undefined): string;
 export interface QuotaProjectionInput {
     utilization: number;
     resetsAt: string;
@@ -95,6 +119,9 @@ export declare function withQuotaProjections<T extends QuotaState>(state: T, opt
  * it in a polling loop, VS Code EventEmitter, or CLI interval as needed.
  *
  * @param accessToken - OAuth access token from `readClaudeMaxCredentials()`
+ * @param options.fetchImpl - Fetch implementation (defaults to the global `fetch`; tests inject a stub)
  * @returns QuotaState with utilization data and elapsed-time projections
  */
-export declare function fetchQuota(accessToken: string): Promise<QuotaState>;
+export declare function fetchQuota(accessToken: string, options?: {
+    fetchImpl?: typeof fetch;
+}): Promise<QuotaState>;

package/dist/quota.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SEVEN_DAY_WINDOW_MS = exports.FIVE_HOUR_WINDOW_MS = exports.QUOTA_PROVIDER_IDS = void 0;
+exports.QUOTA_AGING_MAX_AGE_MS = exports.QUOTA_FRESH_MAX_AGE_MS = exports.SEVEN_DAY_WINDOW_MS = exports.FIVE_HOUR_WINDOW_MS = exports.QUOTA_PROVIDER_IDS = void 0;
+exports.classifyQuotaFreshness = classifyQuotaFreshness;
+exports.formatQuotaAge = formatQuotaAge;
 exports.projectQuotaWindow = projectQuotaWindow;
 exports.withQuotaProjections = withQuotaProjections;
 exports.fetchQuota = fetchQuota;
@@ -11,6 +13,34 @@ const BETA_HEADER = 'oauth-2025-04-20';
 const FETCH_TIMEOUT_MS = 10_000;
 exports.FIVE_HOUR_WINDOW_MS = 5 * 3_600_000;
 exports.SEVEN_DAY_WINDOW_MS = 7 * 86_400_000;
+/** A snapshot younger than this is as good as live. */
+exports.QUOTA_FRESH_MAX_AGE_MS = 5 * 60_000;
+/** A snapshot older than this should be labelled as stale wherever it is shown. */
+exports.QUOTA_AGING_MAX_AGE_MS = 60 * 60_000;
+/** Classify a cached sample's age. Non-finite or negative ages count as stale. */
+function classifyQuotaFreshness(ageMs) {
+    if (typeof ageMs !== 'number' || !Number.isFinite(ageMs) || ageMs < 0)
+        return 'stale';
+    if (ageMs < exports.QUOTA_FRESH_MAX_AGE_MS)
+        return 'fresh';
+    if (ageMs < exports.QUOTA_AGING_MAX_AGE_MS)
+        return 'aging';
+    return 'stale';
+}
+/** Compact age label for status lines and table footers: `just now`, `3m ago`, `2h ago`, `3d ago`. */
+function formatQuotaAge(ageMs) {
+    if (typeof ageMs !== 'number' || !Number.isFinite(ageMs) || ageMs < 0)
+        return 'age unknown';
+    const minutes = Math.floor(ageMs / 60_000);
+    if (minutes < 1)
+        return 'just now';
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h ago`;
+    return `${Math.floor(hours / 24)}d ago`;
+}
 /**
  * Projects utilization at end of window based on elapsed time.
  *
@@ -88,14 +118,16 @@ function parseRetryAfterMs(retryAfter) {
  * it in a polling loop, VS Code EventEmitter, or CLI interval as needed.
  *
  * @param accessToken - OAuth access token from `readClaudeMaxCredentials()`
+ * @param options.fetchImpl - Fetch implementation (defaults to the global `fetch`; tests inject a stub)
  * @returns QuotaState with utilization data and elapsed-time projections
  */
-async function fetchQuota(accessToken) {
+async function fetchQuota(accessToken, options = {}) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
     timeout.unref();
     try {
-        const res = await fetch(USAGE_URL, {
+        const fetchImpl = options.fetchImpl ?? fetch;
+        const res = await fetchImpl(USAGE_URL, {
             method: 'GET',
             signal: controller.signal,
             headers: {

package/dist/quotaHistory.d.ts

@@ -23,7 +23,7 @@ export interface QuotaHistorySample {
     };
     available: boolean;
     error?: string;
-    source?: 'session' | 'cache' | 'api';
+    source?: 'session' | 'cache' | 'api' | 'statusline';
     stale?: boolean;
 }
 export interface QuotaHistoryAppendOptions {

package/dist/quotaHistory.js

@@ -50,8 +50,10 @@ exports._resetQuotaHistoryInMemoryStateForTests = _resetQuotaHistoryInMemoryStat
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const formatting_1 = require("./formatting");
 const paths_1 = require("./paths");
 const quotaSnapshots_1 = require("./quotaSnapshots");
+const atomic_1 = require("./writers/atomic");
 const DEFAULT_MIN_INTERVAL_MS = 60_000;
 const DEFAULT_RETENTION_DAYS = 91;
 const PRUNE_FILESIZE_THRESHOLD = 16 * 1024;
@@ -150,21 +152,16 @@ function readLastSampleTimestampMs(filePath) {
         }
     }
 }
+/**
+ * Append-and-prune under the shared cross-process lock. Without it a prune
+ * rewrite (rename over the file) could race another process's append, and
+ * the appended line would land on the old, unlinked inode.
+ */
+function withHistoryFileLock(filePath, operation) {
+    return (0, atomic_1.withFileLockSync)(`${filePath}.lock`, operation);
+}
 function atomicRewriteFile(filePath, contents) {
-    const tmp = `${filePath}.${process.pid}.${Date.now()}.${crypto.randomBytes(8).toString('hex')}.tmp`;
-    try {
-        fs.writeFileSync(tmp, contents, { encoding: 'utf8', mode: 0o600 });
-        fs.renameSync(tmp, filePath);
-    }
-    catch (error) {
-        try {
-            fs.rmSync(tmp, { force: true });
-        }
-        catch {
-            // Best effort cleanup only.
-        }
-        throw error;
-    }
+    (0, atomic_1.atomicWriteFileSync)(filePath, contents, 0o600);
 }
 function pruneFileSync(filePath, retentionDays) {
     let stat;
@@ -245,18 +242,19 @@ async function runAppend(sample, filePath, options) {
     }
     ensureHistoryDir(sample.workspaceId);
     const line = JSON.stringify(sample) + '\n';
-    await fs.promises.appendFile(filePath, line, { encoding: 'utf8', mode: 0o600 });
-    lastWriteCache.set(filePath, Number.isFinite(sampleTs) ? sampleTs : Date.now());
-    // Opportunistic prune. Skip when the file is small to avoid pointless rewrite churn.
-    try {
-        const stat = await fs.promises.stat(filePath);
-        if (stat.size >= PRUNE_FILESIZE_THRESHOLD) {
-            pruneFileSync(filePath, options.retentionDays);
+    withHistoryFileLock(filePath, () => {
+        fs.appendFileSync(filePath, line, { encoding: 'utf8', mode: 0o600 });
+        // Opportunistic prune. Skip when the file is small to avoid pointless rewrite churn.
+        try {
+            if (fs.statSync(filePath).size >= PRUNE_FILESIZE_THRESHOLD) {
+                pruneFileSync(filePath, options.retentionDays);
+            }
         }
-    }
-    catch {
-        // ignore
-    }
+        catch {
+            // ignore
+        }
+    });
+    lastWriteCache.set(filePath, Number.isFinite(sampleTs) ? sampleTs : Date.now());
     // Backwards-compat: keep the latest-snapshot store hot so existing callers (DashboardViewProvider,
     // codex session provider, external consumers) don't have to query history for "latest".
     try {
@@ -323,23 +321,26 @@ async function readQuotaHistoryRange(options) {
     samples.sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
     return samples;
 }
-function utcDateString(ms) {
-    return new Date(ms).toISOString().slice(0, 10);
-}
-function addDaysUtc(dateString, days) {
-    const ms = Date.parse(`${dateString}T00:00:00Z`) + days * MS_PER_DAY;
-    return utcDateString(ms);
+/**
+ * Daily buckets are keyed by the machine's local calendar day, matching the
+ * `today` brief, the historical-data store, and the dashboard date filters.
+ */
+function localDateString(ms) {
+    return (0, formatting_1.formatLocalDateKey)(ms);
 }
 async function readQuotaHistoryDailyBuckets(options) {
     const samples = await readQuotaHistoryRange(options);
     const { fromMs: defaultFromMs, toMs: defaultToMs } = defaultRangeMs();
     const fromMs = options.from ? Date.parse(options.from) : defaultFromMs;
     const toMs = options.to ? Date.parse(options.to) : defaultToMs;
-    const startDate = utcDateString(fromMs);
-    const endDate = utcDateString(toMs);
+    const startDate = localDateString(fromMs);
+    const endDate = localDateString(toMs);
     const grouped = new Map();
     for (const sample of samples) {
-        const day = sample.timestamp.slice(0, 10);
+        const sampleMs = Date.parse(sample.timestamp);
+        if (!Number.isFinite(sampleMs))
+            continue;
+        const day = localDateString(sampleMs);
         const bucket = grouped.get(day);
         if (bucket) {
             bucket.push(sample);
@@ -389,7 +390,7 @@ async function readQuotaHistoryDailyBuckets(options) {
                 anyUnavailable,
             });
         }
-        cursor = addDaysUtc(cursor, 1);
+        cursor = (0, formatting_1.addLocalDays)(cursor, 1);
     }
     return buckets;
 }

package/dist/quotaResolver.d.ts

@@ -0,0 +1,81 @@
+/**
+ * One quota resolution path for every Sidekick surface.
+ *
+ * `sidekick quota`, `quota --all`, the MCP facts server, and both dashboards
+ * used to pick between the live API, session logs, and the persisted snapshot
+ * in four different orders. `resolveQuota()` applies one precedence:
+ *
+ * 1. a fresh persisted snapshot (younger than `QUOTA_FRESH_MAX_AGE_MS`, whatever
+ *    its origin: the official status-line sample, a session log, or an earlier
+ *    API call) — zero network;
+ * 2. a session-derived sample (Codex rollouts carry rate limits; Claude and
+ *    z.ai have no local equivalent);
+ * 3. the provider API, when `allowApi` is not disabled;
+ * 4. an aging or stale snapshot, labelled as such, with the API failure attached;
+ * 5. an unavailable state describing why nothing could be resolved.
+ *
+ * `preferFresh: false` skips step 1 (the `--refresh` flag). Every result carries
+ * `source`, `capturedSource`, `freshness`, `ageMs`, and a `resolution` tag.
+ */
+import type { ResolvedActiveAccount, SavedAccountProfile } from './accountRegistry';
+import type { ProviderQuotaState } from './providerQuota';
+import type { CodexProvider } from './providers/codex';
+import type { QuotaState } from './quota';
+import type { QuotaSnapshotProviderId } from './quotaSnapshots';
+import type { ZaiQuotaApiOptions } from './zaiQuotaApi';
+/** Providers the resolver knows how to read. `opencode` callers map to `zai`. */
+export type QuotaResolveProviderId = 'claude-code' | 'codex' | 'zai';
+/** Which step of the precedence produced the answer. */
+export type QuotaResolution = 'snapshot-fresh' | 'session' | 'api' | 'snapshot-aging' | 'snapshot-stale' | 'unavailable';
+type RuntimeProviderFor<T extends QuotaResolveProviderId> = T extends 'claude-code' ? 'claude' : T extends 'codex' ? 'codex' : 'zai';
+export interface ResolvedQuota<T extends QuotaResolveProviderId = QuotaResolveProviderId> extends ProviderQuotaState<RuntimeProviderFor<T>> {
+    /** Precedence step that produced this sample. */
+    resolution: QuotaResolution;
+}
+export interface ResolveQuotaOptions<T extends QuotaResolveProviderId = QuotaResolveProviderId> {
+    providerId: T;
+    /** Snapshot key; derived from the active account when omitted. */
+    accountId?: string;
+    /** Workspace whose Codex rollouts are searched first for session-derived rate limits. */
+    workspacePath?: string;
+    /** Use a fresh persisted snapshot before anything else (default true). `--refresh` passes false. */
+    preferFresh?: boolean;
+    /** Allow a provider API call when no fresh local sample exists (default true). */
+    allowApi?: boolean;
+    /** Re-point a stale saved-account pointer while resolving the account (default true). */
+    selfHeal?: boolean;
+    /** Clock for freshness classification; defaults to `new Date()`. */
+    now?: Date;
+    /** Fetch implementation forwarded to every API call (tests inject a stub). */
+    fetchImpl?: typeof fetch;
+    readSnapshot?: (providerId: QuotaSnapshotProviderId, accountId: string, now?: Date) => QuotaState | null;
+    writeSnapshot?: (providerId: QuotaSnapshotProviderId, accountId: string, quota: QuotaState) => void;
+    /** Claude access token source; defaults to `readClaudeMaxCredentials()`. */
+    getClaudeAccessToken?: () => Promise<string | null>;
+    /** Claude account resolution; defaults to `resolveActiveClaudeAccount()`. */
+    resolveClaudeAccount?: (options: {
+        selfHeal?: boolean;
+    }) => ResolvedActiveAccount;
+    /** Codex account resolution; defaults to the self-healing registry lookup. */
+    resolveCodexAccount?: (options: {
+        selfHeal?: boolean;
+    }) => SavedAccountProfile | null;
+    /** Reuse a caller-owned Codex provider for the session scan. */
+    codexProvider?: CodexProvider;
+    /** Codex home whose `auth.json` and rollouts are read. */
+    codexHome?: string;
+    /** Explicit Codex access token for the API step. */
+    codexAccessToken?: string;
+    /** z.ai credential discovery and API options. */
+    zai?: ZaiQuotaApiOptions;
+}
+/**
+ * Resolve the current quota for one provider with the shared precedence
+ * described at the top of this file.
+ *
+ * The result always has `runtimeProvider`, `resolution`, `freshness`, and
+ * (when a capture time is known) `ageMs`; `failure` describes an API failure
+ * even when older numbers were returned from a snapshot.
+ */
+export declare function resolveQuota<T extends QuotaResolveProviderId>(options: ResolveQuotaOptions<T>): Promise<ResolvedQuota<T>>;
+export {};