charness 3.0.0 → 3.2.0

package/dist/utils/claudeUsage.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @description Per-profile Claude USAGE — how much of each subscription window an account profile
+ * (`utils/claudeProfiles.ts`) has used, and which profile a new process should run on.
+ *
+ * Two sources feed one snapshot per profile (`ClaudeProfileRecord.usage`):
+ *   - the OAuth usage endpoint (`GET https://api.anthropic.com/api/oauth/usage`, the profile's own access
+ *     token off its `.credentials.json`), polled by the bot (`claudeUsageRefresher.ts`) and on demand — its
+ *     `limits[]` carry the three windows: `session` (five hours), `weekly_all` (seven days, every model) and
+ *     `weekly_scoped` (seven days, ONE model — Fable; `scope.model.display_name`), measured on 2026-10-12;
+ *   - the `rate_limit_event` frames of a json-stream session, one per API request, whose `unifiedWindows`
+ *     carry the same windows under their CLI names (`five_hour`, `seven_day`, `seven_day_overage_included`
+ *     — the last one IS the Fable window: same utilization and reset instant as the endpoint's scoped limit).
+ *
+ * Token refresh is the CLI's job: a token past its `expiresAt` is never used (nor refreshed here) — the
+ * snapshot is marked stale and the next CLI run renews it. The token itself is never logged or returned.
+ *
+ * Pure except {@link readClaudeOAuthToken} (one file read) and {@link fetchClaudeUsage} (one GET through an
+ * injectable `fetch`), so the rest is unit-tested without the network.
+ */
+import type { ClaudeProfileRecord } from '../state';
+import { type ClaudeAccountKind } from './claudeProfiles';
+export declare const claudeUsageEndpoint = "https://api.anthropic.com/api/oauth/usage";
+export declare const claudeUsageFetchTimeoutMs = 15000;
+/** The one usage window kind set, named by what it bounds rather than by the API's spelling. */
+export type ClaudeUsageBucketKind = 'session' | 'weekly_all' | 'weekly_scoped';
+export declare const claudeUsageBucketKinds: readonly ClaudeUsageBucketKind[];
+export interface ClaudeUsageBucket {
+    kind: ClaudeUsageBucketKind;
+    /** 0..100, the endpoint's `percent` (the CLI's `utilization` × 100), rounded. */
+    percent: number;
+    /** ISO instant the window resets; `null` when the source carried none. */
+    resetsAt: string | null;
+    /** The model a `weekly_scoped` bucket is for (`"Fable"`); `null` for the shared windows. */
+    scopeModel: string | null;
+}
+/** The cached usage of one profile — what `ClaudeProfileRecord.usage` holds. */
+export interface ClaudeUsageSnapshot {
+    /** ISO instant of the last write (either source). */
+    fetchedAt: string;
+    source: 'api' | 'stream';
+    buckets: ClaudeUsageBucket[];
+    /**
+     * The profile's token had expired when the poll ran (the CLI renews it at its next run) or the fetch
+     * failed: the buckets are the LAST known ones, not fresh.
+     */
+    isStale?: boolean;
+    /** Why the last poll did not refresh (short, never the token). */
+    error?: string;
+}
+export interface ClaudeOAuthToken {
+    accessToken: string;
+    /** Epoch ms; `null` when the file carries none. */
+    expiresAtMs: number | null;
+}
+/**
+ * @description The subscription access token of a profile, off `<configDir>/.credentials.json`
+ * (`~/.claude/.credentials.json` for the default profile). `null` when the file or the OAuth entry is absent —
+ * a logged-out directory. The caller never logs the result.
+ */
+export declare function readClaudeOAuthToken(configDir: string | null, homeClaudeDir?: string): ClaudeOAuthToken | null;
+/** Whether the token is past its expiry at `nowMs` (a token without expiry counts as live). */
+export declare function checkIsClaudeTokenExpired(token: ClaudeOAuthToken, nowMs: number): boolean;
+export type ClaudeUsageFetchResult = {
+    ok: true;
+    buckets: ClaudeUsageBucket[];
+} | {
+    ok: false;
+    error: string;
+    isAuthError: boolean;
+};
+type FetchLike = (url: string, init: {
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<{
+    status: number;
+    json(): Promise<unknown>;
+}>;
+/**
+ * @description One GET of the usage endpoint with the profile's token. A 401/403 is an auth error (the
+ * token is no longer accepted — the CLI's next run renews it); anything else is a plain failure. Never
+ * throws; never includes the token in the result.
+ */
+export declare function fetchClaudeUsage(token: string, options?: {
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+}): Promise<ClaudeUsageFetchResult>;
+/**
+ * @description The buckets of a usage response. Reads `limits[]` (`kind` session / weekly_all /
+ * weekly_scoped, `percent`, `resets_at`, `scope.model.display_name`); a response without it (an older
+ * shape) falls back to the top-level `five_hour` / `seven_day` objects (`utilization` already 0..100).
+ * Unknown kinds are dropped, so a window the API adds later never breaks a reader.
+ */
+export declare function parseClaudeUsageResponse(body: unknown): ClaudeUsageBucket[];
+/** One `unifiedWindows` entry of a `rate_limit_event` frame, as `claudeStreamJson.ts` lifts it. */
+export interface ClaudeRateLimitWindow {
+    /** `five_hour` / `seven_day` / `seven_day_overage_included` (the CLI's names). */
+    name: string;
+    /** 0..1 */
+    utilization: number;
+    /** Epoch ms; `null` when absent. */
+    resetsAtMs: number | null;
+}
+/** The buckets a frame's windows carry (unknown window names are dropped). */
+export declare function buildBucketsFromRateLimitWindows(windows: readonly ClaudeRateLimitWindow[]): ClaudeUsageBucket[];
+/**
+ * @description Fold fresh buckets into a profile's snapshot. The endpoint answers with EVERY window, so an
+ * `api` read replaces the set; a frame carries only the windows the request touched, so a `stream` read
+ * upserts those and keeps the rest. Either way the snapshot is fresh (not stale) afterwards.
+ */
+export declare function mergeClaudeUsageSnapshot(previous: ClaudeUsageSnapshot | undefined, incoming: readonly ClaudeUsageBucket[], source: ClaudeUsageSnapshot['source'], nowMs: number): ClaudeUsageSnapshot;
+/** The snapshot kept as it was, marked stale with the reason (a failed or impossible poll). */
+export declare function markClaudeUsageSnapshotStale(previous: ClaudeUsageSnapshot | undefined, error: string, nowMs: number): ClaudeUsageSnapshot;
+/** Whether `next` says anything `previous` did not — a stream frame per API request must not rewrite state.json each time. */
+export declare function checkClaudeUsageBucketsChanged(previous: ClaudeUsageSnapshot | undefined, next: readonly ClaudeUsageBucket[]): boolean;
+export declare function getClaudeUsageBucket(snapshot: ClaudeUsageSnapshot | undefined, kind: ClaudeUsageBucketKind): ClaudeUsageBucket | null;
+/** Whether a model name (`fable`, `claude-fable-5-1`, …) runs on the scoped weekly window. */
+export declare function checkIsScopedWeeklyModel(model: string | null): boolean;
+/** The windows that bound a launch of `model`: the session window plus the weekly one the model drains. */
+export declare function getRelevantClaudeUsageKinds(model: string | null): ClaudeUsageBucketKind[];
+/** What the ranking needs to know about one profile (the bot reads it off state, the CLI off state.json). */
+export interface ClaudeProfileUsageView {
+    name: string;
+    configDir: string | null;
+    loggedIn: boolean | undefined;
+    email: string | null;
+    subscriptionType: string | null;
+    usage: ClaudeUsageSnapshot | undefined;
+    limitedUntil: string | null;
+}
+/** One profile in the report the MCP tool and the CLI hand to an agent. */
+export interface ClaudeProfileReportEntry {
+    name: string;
+    /** The `CLAUDE_CONFIG_DIR` to launch under; `null` for the default profile (set nothing). */
+    configDir: string | null;
+    email: string | null;
+    kind: ClaudeAccountKind;
+    subscriptionType: string | null;
+    /** `null` when never probed. */
+    loggedIn: boolean | null;
+    buckets: ClaudeUsageBucket[];
+    usageFetchedAt: string | null;
+    isUsageStale: boolean;
+    limitedUntil: string | null;
+    /** Signed in, not limited, and not at 100 % on a window the model drains. */
+    isEligible: boolean;
+    /** `100 − max(relevant percent)`; `null` when the usage is unknown. */
+    headroomPercent: number | null;
+    isRecommended: boolean;
+}
+export interface ClaudeProfilesReport {
+    model: string | null;
+    /** The windows the ranking looked at for `model`. */
+    relevantBuckets: ClaudeUsageBucketKind[];
+    /** The profile a new process of `model` should run on; `null` when none is eligible. */
+    recommended: string | null;
+    profiles: ClaudeProfileReportEntry[];
+}
+/**
+ * @description Rank the profiles for a launch of `model`: a profile that is signed out, marked limited
+ * (`limitedUntil` in the future) or at 100 % on a relevant window is out; the rest are ordered by headroom on
+ * the relevant windows (most first; unknown usage ranks after any known one; a tie goes to the lower total of
+ * the relevant percentages). The first in that order is `recommended`. The entries keep the input order.
+ */
+export declare function buildClaudeProfilesReport(profiles: readonly ClaudeProfileUsageView[], model: string | null, nowMs: number): ClaudeProfilesReport;
+/**
+ * @description The ranking's view of every profile off the registry: `default` (its hidden record, when the
+ * bot has written one) first, then the added profiles in creation order. Shared by the bot (live state) and
+ * the CLI (`state.json` read directly).
+ */
+export declare function buildClaudeProfileUsageViews(input: {
+    dataDir: string;
+    /** Every record, the hidden `default` one included (`StateStore.getClaudeProfileInfo` / the raw file). */
+    records: Readonly<Record<string, ClaudeProfileRecord>>;
+}): ClaudeProfileUsageView[];
+/** The profile registry as `state.json` holds it — the CLI's read, no `StateStore` (which would migrate and lock). */
+export declare function readClaudeProfileRecordsFromStateFile(dataDir: string): Readonly<Record<string, ClaudeProfileRecord>>;
+/**
+ * @description A reset instant for a human, in the instance zone: `16:00` when it is today there, `Sat 00:00`
+ * within the week, `17.10 00:00` beyond. The weekday is English on purpose (a three-letter token every locale
+ * reads; the surrounding line is localised).
+ */
+export declare function formatClaudeUsageResetAt(resetsAt: string | null, timezone: string, nowMs: number): string;
+/** The words a relative reset is spelled with: `pattern` carries `{time}`, the units are appended to their numbers. */
+export interface ClaudeRelativeResetWords {
+    pattern: string;
+    day: string;
+    hour: string;
+    minute: string;
+}
+/** English words, the CLI's (the bot passes its localised ones). */
+export declare const englishRelativeResetWords: ClaudeRelativeResetWords;
+/**
+ * @description A reset instant as a time from now: `🔄 in 2d 1h`, `🔄 in 2h`, `🔄 in 30m`. The two largest
+ * units at most, minutes only under an hour: from a day up it is days + hours (hours dropped when zero), from
+ * an hour up whole hours (rounded), below that minutes (at least one). An instant already past reads as
+ * `🔄 in 1m` (the window is about to roll over). `?` for a missing or unparseable instant.
+ */
+export declare function formatClaudeUsageRelativeReset(resetsAt: string | null, nowMs: number, words?: ClaudeRelativeResetWords): string;
+/**
+ * @description `81% 🔄 in 2h` for a bucket, `—` for a missing one. A bucket whose reset is unknown shows
+ * `fallbackResetsAt` instead (the session window's reset is often missing while the weekly one is known);
+ * with neither it is the bare percent — a «?» after a number would read as a doubt about the number.
+ */
+export declare function formatClaudeUsageBucket(bucket: ClaudeUsageBucket | null, nowMs: number, options?: {
+    fallbackResetsAt?: string | null;
+    words?: ClaudeRelativeResetWords;
+}): string;
+export {};
+//# sourceMappingURL=claudeUsage.d.ts.map

package/dist/utils/claudeUsage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claudeUsage.d.ts","sourceRoot":"","sources":["../../src/utils/claudeUsage.ts"],"names":[],"mappings":"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"}

package/dist/utils/claudeUsage.js

@@ -0,0 +1,413 @@
+"use strict";
+/**
+ * @description Per-profile Claude USAGE — how much of each subscription window an account profile
+ * (`utils/claudeProfiles.ts`) has used, and which profile a new process should run on.
+ *
+ * Two sources feed one snapshot per profile (`ClaudeProfileRecord.usage`):
+ *   - the OAuth usage endpoint (`GET https://api.anthropic.com/api/oauth/usage`, the profile's own access
+ *     token off its `.credentials.json`), polled by the bot (`claudeUsageRefresher.ts`) and on demand — its
+ *     `limits[]` carry the three windows: `session` (five hours), `weekly_all` (seven days, every model) and
+ *     `weekly_scoped` (seven days, ONE model — Fable; `scope.model.display_name`), measured on 2026-10-12;
+ *   - the `rate_limit_event` frames of a json-stream session, one per API request, whose `unifiedWindows`
+ *     carry the same windows under their CLI names (`five_hour`, `seven_day`, `seven_day_overage_included`
+ *     — the last one IS the Fable window: same utilization and reset instant as the endpoint's scoped limit).
+ *
+ * Token refresh is the CLI's job: a token past its `expiresAt` is never used (nor refreshed here) — the
+ * snapshot is marked stale and the next CLI run renews it. The token itself is never logged or returned.
+ *
+ * Pure except {@link readClaudeOAuthToken} (one file read) and {@link fetchClaudeUsage} (one GET through an
+ * injectable `fetch`), so the rest is unit-tested without the network.
+ */
+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.englishRelativeResetWords = exports.claudeUsageBucketKinds = exports.claudeUsageFetchTimeoutMs = exports.claudeUsageEndpoint = void 0;
+exports.readClaudeOAuthToken = readClaudeOAuthToken;
+exports.checkIsClaudeTokenExpired = checkIsClaudeTokenExpired;
+exports.fetchClaudeUsage = fetchClaudeUsage;
+exports.parseClaudeUsageResponse = parseClaudeUsageResponse;
+exports.buildBucketsFromRateLimitWindows = buildBucketsFromRateLimitWindows;
+exports.mergeClaudeUsageSnapshot = mergeClaudeUsageSnapshot;
+exports.markClaudeUsageSnapshotStale = markClaudeUsageSnapshotStale;
+exports.checkClaudeUsageBucketsChanged = checkClaudeUsageBucketsChanged;
+exports.getClaudeUsageBucket = getClaudeUsageBucket;
+exports.checkIsScopedWeeklyModel = checkIsScopedWeeklyModel;
+exports.getRelevantClaudeUsageKinds = getRelevantClaudeUsageKinds;
+exports.buildClaudeProfilesReport = buildClaudeProfilesReport;
+exports.buildClaudeProfileUsageViews = buildClaudeProfileUsageViews;
+exports.readClaudeProfileRecordsFromStateFile = readClaudeProfileRecordsFromStateFile;
+exports.formatClaudeUsageResetAt = formatClaudeUsageResetAt;
+exports.formatClaudeUsageRelativeReset = formatClaudeUsageRelativeReset;
+exports.formatClaudeUsageBucket = formatClaudeUsageBucket;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const claudeProfiles_1 = require("./claudeProfiles");
+exports.claudeUsageEndpoint = 'https://api.anthropic.com/api/oauth/usage';
+/** The OAuth beta header the CLI sends with its subscription token. */
+const claudeOAuthBetaHeader = 'oauth-2025-04-20';
+exports.claudeUsageFetchTimeoutMs = 15_000;
+exports.claudeUsageBucketKinds = ['session', 'weekly_all', 'weekly_scoped'];
+/**
+ * @description The subscription access token of a profile, off `<configDir>/.credentials.json`
+ * (`~/.claude/.credentials.json` for the default profile). `null` when the file or the OAuth entry is absent —
+ * a logged-out directory. The caller never logs the result.
+ */
+function readClaudeOAuthToken(configDir, homeClaudeDir = (0, claudeProfiles_1.resolveHomeClaudeDir)()) {
+    const file = path.join(configDir ?? homeClaudeDir, '.credentials.json');
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const oauth = checkIsRecord(parsed) && checkIsRecord(parsed.claudeAiOauth) ? parsed.claudeAiOauth : null;
+    if (!oauth || typeof oauth.accessToken !== 'string' || oauth.accessToken === '')
+        return null;
+    return { accessToken: oauth.accessToken, expiresAtMs: typeof oauth.expiresAt === 'number' ? oauth.expiresAt : null };
+}
+/** Whether the token is past its expiry at `nowMs` (a token without expiry counts as live). */
+function checkIsClaudeTokenExpired(token, nowMs) {
+    return token.expiresAtMs !== null && token.expiresAtMs <= nowMs;
+}
+/**
+ * @description One GET of the usage endpoint with the profile's token. A 401/403 is an auth error (the
+ * token is no longer accepted — the CLI's next run renews it); anything else is a plain failure. Never
+ * throws; never includes the token in the result.
+ */
+async function fetchClaudeUsage(token, options = {}) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? exports.claudeUsageFetchTimeoutMs);
+    try {
+        const response = await fetchImpl(exports.claudeUsageEndpoint, {
+            headers: { Authorization: `Bearer ${token}`, 'anthropic-beta': claudeOAuthBetaHeader, Accept: 'application/json' },
+            signal: controller.signal,
+        });
+        if (response.status === 401 || response.status === 403)
+            return { ok: false, error: `http ${response.status}`, isAuthError: true };
+        if (response.status !== 200)
+            return { ok: false, error: `http ${response.status}`, isAuthError: false };
+        const buckets = parseClaudeUsageResponse(await response.json());
+        if (buckets.length === 0)
+            return { ok: false, error: 'no limits in the response', isAuthError: false };
+        return { ok: true, buckets };
+    }
+    catch (e) {
+        const reason = e instanceof Error ? (e.name === 'AbortError' ? 'timeout' : e.message) : String(e);
+        return { ok: false, error: reason.slice(0, 120), isAuthError: false };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * @description The buckets of a usage response. Reads `limits[]` (`kind` session / weekly_all /
+ * weekly_scoped, `percent`, `resets_at`, `scope.model.display_name`); a response without it (an older
+ * shape) falls back to the top-level `five_hour` / `seven_day` objects (`utilization` already 0..100).
+ * Unknown kinds are dropped, so a window the API adds later never breaks a reader.
+ */
+function parseClaudeUsageResponse(body) {
+    if (!checkIsRecord(body))
+        return [];
+    if (Array.isArray(body.limits)) {
+        const buckets = [];
+        for (const limit of body.limits) {
+            if (!checkIsRecord(limit))
+                continue;
+            const kind = readBucketKind(limit.kind);
+            if (!kind || typeof limit.percent !== 'number')
+                continue;
+            const scope = checkIsRecord(limit.scope) && checkIsRecord(limit.scope.model) ? limit.scope.model : null;
+            buckets.push({
+                kind,
+                percent: clampPercent(limit.percent),
+                resetsAt: readIso(limit.resets_at),
+                scopeModel: scope && typeof scope.display_name === 'string' ? scope.display_name : null,
+            });
+        }
+        if (buckets.length > 0)
+            return buckets;
+    }
+    const buckets = [];
+    for (const [field, kind] of [['five_hour', 'session'], ['seven_day', 'weekly_all']]) {
+        const window = body[field];
+        if (!checkIsRecord(window) || typeof window.utilization !== 'number')
+            continue;
+        buckets.push({ kind, percent: clampPercent(window.utilization), resetsAt: readIso(window.resets_at), scopeModel: null });
+    }
+    return buckets;
+}
+function readBucketKind(value) {
+    return value === 'session' || value === 'weekly_all' || value === 'weekly_scoped' ? value : null;
+}
+/** The CLI's window names → bucket kinds; `seven_day_overage_included` is the Fable window (see the module doc). */
+const rateLimitWindowKinds = {
+    five_hour: { kind: 'session', scopeModel: null },
+    seven_day: { kind: 'weekly_all', scopeModel: null },
+    seven_day_overage_included: { kind: 'weekly_scoped', scopeModel: 'Fable' },
+};
+/** The buckets a frame's windows carry (unknown window names are dropped). */
+function buildBucketsFromRateLimitWindows(windows) {
+    const buckets = [];
+    for (const window of windows) {
+        const mapping = rateLimitWindowKinds[window.name];
+        if (!mapping)
+            continue;
+        buckets.push({
+            kind: mapping.kind,
+            percent: clampPercent(window.utilization * 100),
+            resetsAt: window.resetsAtMs === null ? null : new Date(window.resetsAtMs).toISOString(),
+            scopeModel: mapping.scopeModel,
+        });
+    }
+    return buckets;
+}
+// ── the snapshot ──
+/**
+ * @description Fold fresh buckets into a profile's snapshot. The endpoint answers with EVERY window, so an
+ * `api` read replaces the set; a frame carries only the windows the request touched, so a `stream` read
+ * upserts those and keeps the rest. Either way the snapshot is fresh (not stale) afterwards.
+ */
+function mergeClaudeUsageSnapshot(previous, incoming, source, nowMs) {
+    let buckets;
+    if (source === 'api' || !previous) {
+        buckets = [...incoming];
+    }
+    else {
+        buckets = previous.buckets.filter((bucket) => !incoming.some((fresh) => fresh.kind === bucket.kind));
+        buckets.push(...incoming);
+    }
+    buckets.sort((a, b) => exports.claudeUsageBucketKinds.indexOf(a.kind) - exports.claudeUsageBucketKinds.indexOf(b.kind));
+    return { fetchedAt: new Date(nowMs).toISOString(), source, buckets };
+}
+/** The snapshot kept as it was, marked stale with the reason (a failed or impossible poll). */
+function markClaudeUsageSnapshotStale(previous, error, nowMs) {
+    return { fetchedAt: previous?.fetchedAt ?? new Date(nowMs).toISOString(), source: previous?.source ?? 'api', buckets: previous?.buckets ?? [], isStale: true, error };
+}
+/** Whether `next` says anything `previous` did not — a stream frame per API request must not rewrite state.json each time. */
+function checkClaudeUsageBucketsChanged(previous, next) {
+    if (!previous || previous.isStale)
+        return true;
+    return next.some((bucket) => {
+        const old = previous.buckets.find((candidate) => candidate.kind === bucket.kind);
+        return !old || old.percent !== bucket.percent || old.resetsAt !== bucket.resetsAt;
+    });
+}
+function getClaudeUsageBucket(snapshot, kind) {
+    return snapshot?.buckets.find((bucket) => bucket.kind === kind) ?? null;
+}
+// ── which profile for a model ──
+/** Whether a model name (`fable`, `claude-fable-5-1`, …) runs on the scoped weekly window. */
+function checkIsScopedWeeklyModel(model) {
+    return model !== null && /fable/i.test(model);
+}
+/** The windows that bound a launch of `model`: the session window plus the weekly one the model drains. */
+function getRelevantClaudeUsageKinds(model) {
+    return ['session', checkIsScopedWeeklyModel(model) ? 'weekly_scoped' : 'weekly_all'];
+}
+/**
+ * @description Rank the profiles for a launch of `model`: a profile that is signed out, marked limited
+ * (`limitedUntil` in the future) or at 100 % on a relevant window is out; the rest are ordered by headroom on
+ * the relevant windows (most first; unknown usage ranks after any known one; a tie goes to the lower total of
+ * the relevant percentages). The first in that order is `recommended`. The entries keep the input order.
+ */
+function buildClaudeProfilesReport(profiles, model, nowMs) {
+    const relevantBuckets = getRelevantClaudeUsageKinds(model);
+    const entries = profiles.map((profile) => {
+        const relevant = relevantBuckets
+            .map((kind) => getClaudeUsageBucket(profile.usage, kind))
+            .filter((bucket) => bucket !== null);
+        const maxPercent = relevant.length === 0 ? null : Math.max(...relevant.map((bucket) => bucket.percent));
+        const isLimited = profile.limitedUntil !== null && Date.parse(profile.limitedUntil) > nowMs;
+        const isEligible = profile.loggedIn !== false && !isLimited && (maxPercent === null || maxPercent < 100);
+        return {
+            name: profile.name,
+            configDir: profile.configDir,
+            email: profile.email,
+            kind: (0, claudeProfiles_1.getClaudeAccountKind)(profile.subscriptionType),
+            subscriptionType: profile.subscriptionType,
+            loggedIn: profile.loggedIn ?? null,
+            buckets: profile.usage?.buckets ?? [],
+            usageFetchedAt: profile.usage?.fetchedAt ?? null,
+            isUsageStale: profile.usage?.isStale === true,
+            limitedUntil: profile.limitedUntil,
+            isEligible,
+            headroomPercent: maxPercent === null ? null : 100 - maxPercent,
+            isRecommended: false,
+        };
+    });
+    const ranked = entries
+        .filter((entry) => entry.isEligible)
+        .sort((a, b) => {
+        if (a.headroomPercent === null || b.headroomPercent === null) {
+            return (a.headroomPercent === null ? 1 : 0) - (b.headroomPercent === null ? 1 : 0);
+        }
+        if (a.headroomPercent !== b.headroomPercent)
+            return b.headroomPercent - a.headroomPercent;
+        return sumRelevantPercent(a, relevantBuckets) - sumRelevantPercent(b, relevantBuckets);
+    });
+    const recommended = ranked[0] ?? null;
+    if (recommended)
+        recommended.isRecommended = true;
+    return { model, relevantBuckets, recommended: recommended?.name ?? null, profiles: entries };
+}
+function sumRelevantPercent(entry, kinds) {
+    return entry.buckets.filter((bucket) => kinds.includes(bucket.kind)).reduce((sum, bucket) => sum + bucket.percent, 0);
+}
+/**
+ * @description The ranking's view of every profile off the registry: `default` (its hidden record, when the
+ * bot has written one) first, then the added profiles in creation order. Shared by the bot (live state) and
+ * the CLI (`state.json` read directly).
+ */
+function buildClaudeProfileUsageViews(input) {
+    // A `default` the operator signed out through /accounts stays out of every ranking until it is signed in again.
+    const isDefaultRemoved = input.records.default?.isRemoved === true;
+    const toView = (name, record) => ({
+        name,
+        configDir: (0, claudeProfiles_1.resolveClaudeProfileDir)(input.dataDir, name),
+        loggedIn: record?.loggedIn,
+        email: record?.email ?? null,
+        subscriptionType: record?.subscriptionType ?? null,
+        usage: record?.usage,
+        limitedUntil: record?.limitedUntil ?? null,
+    });
+    const added = Object.entries(input.records)
+        .filter(([name]) => name !== 'default')
+        .sort(([, a], [, b]) => a.createdAt.localeCompare(b.createdAt));
+    return [...(isDefaultRemoved ? [] : [toView('default', input.records.default)]), ...added.map(([name, record]) => toView(name, record))];
+}
+/** The profile registry as `state.json` holds it — the CLI's read, no `StateStore` (which would migrate and lock). */
+function readClaudeProfileRecordsFromStateFile(dataDir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(path.join(dataDir, 'state.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+    const records = checkIsRecord(parsed) && checkIsRecord(parsed.claudeProfiles) ? parsed.claudeProfiles : {};
+    const result = {};
+    for (const [name, record] of Object.entries(records)) {
+        if (checkIsRecord(record) && typeof record.createdAt === 'string')
+            result[name] = record;
+    }
+    return result;
+}
+// ── rendering ──
+/**
+ * @description A reset instant for a human, in the instance zone: `16:00` when it is today there, `Sat 00:00`
+ * within the week, `17.10 00:00` beyond. The weekday is English on purpose (a three-letter token every locale
+ * reads; the surrounding line is localised).
+ */
+function formatClaudeUsageResetAt(resetsAt, timezone, nowMs) {
+    if (resetsAt === null)
+        return '?';
+    const exact = Date.parse(resetsAt);
+    if (Number.isNaN(exact))
+        return '?';
+    // Windows reset on a minute boundary; the endpoint's instant carries jitter below a second (`13:00:00.40`,
+    // once `12:59:59.9`), which must not read as a minute earlier.
+    const at = Math.round(exact / 60_000) * 60_000;
+    const read = (options, instant) => new Intl.DateTimeFormat('en-GB', { timeZone: timezone, hourCycle: 'h23', ...options }).format(instant);
+    const time = read({ hour: '2-digit', minute: '2-digit' }, at);
+    const dayOf = (instant) => read({ year: 'numeric', month: '2-digit', day: '2-digit' }, instant);
+    if (dayOf(at) === dayOf(nowMs))
+        return time;
+    if (at - nowMs < 6 * 24 * 3_600_000)
+        return `${read({ weekday: 'short' }, at)} ${time}`;
+    return `${read({ day: '2-digit' }, at)}.${read({ month: '2-digit' }, at)} ${time}`;
+}
+/** English words, the CLI's (the bot passes its localised ones). */
+exports.englishRelativeResetWords = { pattern: '🔄 in {time}', day: 'd', hour: 'h', minute: 'm' };
+/**
+ * @description A reset instant as a time from now: `🔄 in 2d 1h`, `🔄 in 2h`, `🔄 in 30m`. The two largest
+ * units at most, minutes only under an hour: from a day up it is days + hours (hours dropped when zero), from
+ * an hour up whole hours (rounded), below that minutes (at least one). An instant already past reads as
+ * `🔄 in 1m` (the window is about to roll over). `?` for a missing or unparseable instant.
+ */
+function formatClaudeUsageRelativeReset(resetsAt, nowMs, words = exports.englishRelativeResetWords) {
+    if (resetsAt === null)
+        return '?';
+    const at = Date.parse(resetsAt);
+    if (Number.isNaN(at))
+        return '?';
+    const totalMinutes = Math.max(1, Math.round((at - nowMs) / 60_000));
+    let time;
+    if (totalMinutes < 60) {
+        time = `${totalMinutes}${words.minute}`;
+    }
+    else if (totalMinutes < 24 * 60) {
+        // 23h40m rounds to 24h: that is a day.
+        time = totalMinutes / 60 >= 23.5 ? `1${words.day}` : `${Math.round(totalMinutes / 60)}${words.hour}`;
+    }
+    else {
+        let days = Math.floor(totalMinutes / 1440);
+        let hours = Math.round((totalMinutes % 1440) / 60);
+        if (hours === 24) {
+            days += 1;
+            hours = 0;
+        }
+        time = hours === 0 ? `${days}${words.day}` : `${days}${words.day} ${hours}${words.hour}`;
+    }
+    return words.pattern.replace('{time}', time);
+}
+/**
+ * @description `81% 🔄 in 2h` for a bucket, `—` for a missing one. A bucket whose reset is unknown shows
+ * `fallbackResetsAt` instead (the session window's reset is often missing while the weekly one is known);
+ * with neither it is the bare percent — a «?» after a number would read as a doubt about the number.
+ */
+function formatClaudeUsageBucket(bucket, nowMs, options = {}) {
+    if (bucket === null)
+        return '—';
+    const known = bucket.resetsAt !== null && !Number.isNaN(Date.parse(bucket.resetsAt));
+    const resetsAt = known ? bucket.resetsAt : options.fallbackResetsAt ?? null;
+    if (resetsAt === null || Number.isNaN(Date.parse(resetsAt)))
+        return `${bucket.percent}%`;
+    return `${bucket.percent}% ${formatClaudeUsageRelativeReset(resetsAt, nowMs, options.words)}`;
+}
+// ── small readers ──
+function checkIsRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readIso(value) {
+    if (typeof value !== 'string')
+        return null;
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? null : new Date(ms).toISOString();
+}
+function clampPercent(value) {
+    return Math.max(0, Math.min(100, Math.round(value)));
+}
+//# sourceMappingURL=claudeUsage.js.map