@songsid/agend 2.3.4-beta.8 → 2.3.4

package/dist/usage/capacity.d.ts

@@ -0,0 +1,69 @@
+/**
+ * #3066 §1: how much is 100% of an account's weekly quota, measured — what this account's agents used while the vendor's
+ * weekly percent moved (the readings of quota-history.ts, the hours of the usage ledger). Pure: the fleet gathers both.
+ *
+ * Within one reset window (the same `resetsAt`, the percent never going down) the first and last readings bound an
+ * interval: capacity = consumed in it ÷ Δ%. Two uncertainties, both carried into the range, never hidden:
+ * - the vendors report whole percents, so Δ is ±1: the range divides by Δ+1 … Δ−1;
+ * - the ledger is hourly, so the two boundary hours are uncertain: without them is the low end, with them the high.
+ * A window counts only when Δ ≥ 10 points (rounding then costs ≤ ~±10%). Several windows: the median of their midpoints,
+ * the range their lowest low … highest high.
+ *
+ * Three bases, because the vendor's weighting is not published: the API-equivalent at list price (likely what the quota
+ * tracks — it weighs Opus over Sonnet, cache reads far below input), output tokens, all tokens. With three windows or
+ * more, the basis whose capacity varies least across weeks (coefficient of variation) is named as the best fit.
+ *
+ * What it cannot see: the same account used outside this fleet (claude.ai, another machine) spends the quota without a
+ * token here, so the estimate comes out LOW; a window whose bases disagree with each other by more than 2× is marked
+ * `mixed`. The page says so (usage.capacity.only_agend, usage.capacity.mixed).
+ */
+import { type QuotaReading } from "./quota-history.js";
+export declare const CAPACITY_MIN_DELTA = 10;
+export declare const BASES: readonly ["api", "output", "all"];
+export type CapacityBasis = typeof BASES[number];
+/** One hour of one account's usage, on each basis (api null: a model in it has no list price). */
+export interface CapacityHour {
+    hour: number;
+    api: number | null;
+    output: number;
+    all: number;
+}
+/** `windows`: how many reset windows this basis was measured over (a basis can miss one: an unpriced hour). */
+export interface BasisEstimate {
+    median: number;
+    low: number;
+    high: number;
+    cv: number | null;
+    windows: number;
+}
+export type CapacityEstimate = {
+    status: "ok";
+    windows: number;
+    deltaPct: number;
+    bases: Partial<Record<CapacityBasis, BasisEstimate>>;
+    bestFit: CapacityBasis | null;
+    mixed: boolean;
+} | {
+    status: "not_enough";
+    deltaPct: number;
+};
+interface Window {
+    t1: number;
+    p1: number;
+    t2: number;
+    p2: number;
+}
+/**
+ * The reset windows the readings span: a new `resetsAt`, or a percent that went down, starts the next. "New" is
+ * quota-history's sameReset (Prism #3073 P2): a vendor that gives only "resets in N seconds" drifts by seconds between
+ * reads and is still one window; compared with the window's latest reading, a real reset moves it by days.
+ */
+export declare function quotaWindows(readings: readonly QuotaReading[]): Window[];
+/**
+ * The estimate for one account's one weekly metric. `available(from, to)`: whether every hour from `from` to `to` is in
+ * the ledger — kept and scanned (Prism #3073 P2): the quota history keeps 12 weeks, the hours 31 days, so a window
+ * outside them would count as zero use and the estimate would come out absurdly low. Such a window is left out.
+ * Null: there are windows to measure, but no usage of this account in any of them on any basis — nothing to show.
+ */
+export declare function estimateCapacity(readings: readonly QuotaReading[], hours: readonly CapacityHour[], available?: (from: number, to: number) => boolean): CapacityEstimate | null;
+export {};

package/dist/usage/capacity.js

@@ -0,0 +1,119 @@
+/**
+ * #3066 §1: how much is 100% of an account's weekly quota, measured — what this account's agents used while the vendor's
+ * weekly percent moved (the readings of quota-history.ts, the hours of the usage ledger). Pure: the fleet gathers both.
+ *
+ * Within one reset window (the same `resetsAt`, the percent never going down) the first and last readings bound an
+ * interval: capacity = consumed in it ÷ Δ%. Two uncertainties, both carried into the range, never hidden:
+ * - the vendors report whole percents, so Δ is ±1: the range divides by Δ+1 … Δ−1;
+ * - the ledger is hourly, so the two boundary hours are uncertain: without them is the low end, with them the high.
+ * A window counts only when Δ ≥ 10 points (rounding then costs ≤ ~±10%). Several windows: the median of their midpoints,
+ * the range their lowest low … highest high.
+ *
+ * Three bases, because the vendor's weighting is not published: the API-equivalent at list price (likely what the quota
+ * tracks — it weighs Opus over Sonnet, cache reads far below input), output tokens, all tokens. With three windows or
+ * more, the basis whose capacity varies least across weeks (coefficient of variation) is named as the best fit.
+ *
+ * What it cannot see: the same account used outside this fleet (claude.ai, another machine) spends the quota without a
+ * token here, so the estimate comes out LOW; a window whose bases disagree with each other by more than 2× is marked
+ * `mixed`. The page says so (usage.capacity.only_agend, usage.capacity.mixed).
+ */
+import { sameReset } from "./quota-history.js";
+export const CAPACITY_MIN_DELTA = 10;
+export const BASES = ["api", "output", "all"];
+const H = 3_600_000;
+/**
+ * The reset windows the readings span: a new `resetsAt`, or a percent that went down, starts the next. "New" is
+ * quota-history's sameReset (Prism #3073 P2): a vendor that gives only "resets in N seconds" drifts by seconds between
+ * reads and is still one window; compared with the window's latest reading, a real reset moves it by days.
+ */
+export function quotaWindows(readings) {
+    const out = [];
+    let cur = null;
+    for (const r of [...readings].sort((a, b) => a.t - b.t)) {
+        if (!cur || !sameReset(r.resetsAt, cur.resetsAt) || r.used < cur.p2) {
+            if (cur)
+                out.push(cur);
+            cur = { t1: r.t, p1: r.used, t2: r.t, p2: r.used, resetsAt: r.resetsAt };
+        }
+        else {
+            cur.t2 = r.t;
+            cur.p2 = r.used;
+            cur.resetsAt = r.resetsAt;
+        }
+    }
+    if (cur)
+        out.push(cur);
+    return out.map(({ t1, p1, t2, p2 }) => ({ t1, p1, t2, p2 }));
+}
+const median = (xs) => { const s = [...xs].sort((a, b) => a - b), m = s.length >> 1; return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2; };
+const cv = (xs) => {
+    if (xs.length < 2)
+        return null;
+    const mean = xs.reduce((a, b) => a + b, 0) / xs.length;
+    return mean > 0 ? Math.sqrt(xs.reduce((a, x) => a + (x - mean) ** 2, 0) / xs.length) / mean : null;
+};
+/**
+ * The estimate for one account's one weekly metric. `available(from, to)`: whether every hour from `from` to `to` is in
+ * the ledger — kept and scanned (Prism #3073 P2): the quota history keeps 12 weeks, the hours 31 days, so a window
+ * outside them would count as zero use and the estimate would come out absurdly low. Such a window is left out.
+ * Null: there are windows to measure, but no usage of this account in any of them on any basis — nothing to show.
+ */
+export function estimateCapacity(readings, hours, available = () => true) {
+    const windows = quotaWindows(readings).filter((w) => available(Math.floor(w.t1 / H) * H, w.t2));
+    const usable = windows.filter((w) => w.p2 - w.p1 >= CAPACITY_MIN_DELTA);
+    if (!usable.length) {
+        // No window inside the ledger at all: "not enough usage" would be a claim about weeks it cannot see. Say nothing.
+        if (!windows.length)
+            return null;
+        return { status: "not_enough", deltaPct: Math.max(0, ...windows.map((w) => w.p2 - w.p1)) };
+    }
+    const per = usable.map((w) => {
+        const delta = w.p2 - w.p1;
+        const inside = hours.filter((h) => h.hour >= w.t1 && h.hour + H <= w.t2); // whole hours within: low
+        const touching = hours.filter((h) => h.hour + H > w.t1 && h.hour < w.t2); // any hour touching: high
+        const sum = (list, b) => {
+            let n = 0;
+            for (const h of list) {
+                const v = h[b];
+                if (v === null)
+                    return null;
+                n += v;
+            }
+            return n;
+        };
+        const out = {};
+        for (const b of BASES) {
+            const lo = sum(inside, b), hi = sum(touching, b);
+            if (lo === null || hi === null || hi <= 0)
+                continue; // a basis with an unpriced hour, or nothing used
+            out[b] = { low: lo / ((delta + 1) / 100), mid: ((lo + hi) / 2) / (delta / 100), high: hi / ((delta - 1) / 100) };
+        }
+        return out;
+    });
+    const bases = {};
+    for (const b of BASES) {
+        const ws = per.map((p) => p[b]).filter((x) => !!x);
+        if (!ws.length)
+            continue;
+        const mids = ws.map((x) => x.mid);
+        bases[b] = { median: median(mids), low: Math.min(...ws.map((x) => x.low)), high: Math.max(...ws.map((x) => x.high)), cv: cv(mids), windows: ws.length };
+    }
+    if (!BASES.some((b) => bases[b]))
+        return null; // Prism #3073 P1: no basis, no estimate
+    // Best fit: with three windows or more, the basis that varies least across them.
+    const scored = BASES.filter((b) => bases[b]?.cv !== null && bases[b]?.cv !== undefined && bases[b].windows >= 3);
+    const bestFit = scored.length ? scored.reduce((a, b) => (bases[b].cv < bases[a].cv ? b : a)) : null;
+    // Mixed: in some window the API-equivalent and the token count disagree (each against its own median) by over 2×.
+    let mixed = false;
+    if (bases.api && bases.all && usable.length >= 2) {
+        for (const p of per) {
+            if (!p.api || !p.all)
+                continue;
+            const ra = p.api.mid / bases.api.median, rt = p.all.mid / bases.all.median;
+            if (Math.max(ra / rt, rt / ra) > 2)
+                mixed = true;
+        }
+    }
+    return { status: "ok", windows: usable.length, deltaPct: Math.max(...usable.map((w) => w.p2 - w.p1)), bases, bestFit, mixed };
+}
+//# sourceMappingURL=capacity.js.map

package/dist/usage/capacity.js.map

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

package/dist/usage/i18n-keys.d.ts

@@ -3,5 +3,5 @@
  * Keep this list explicit: the parity test rejects a key missing from either
  * locale surface before a mixed-language release can ship.
  */
-export declare const USAGE_I18N_KEYS: readonly ["usage.title", "usage.title_plain", "usage.empty_active", "usage.not_logged_in", "usage.default_login", "usage.error_fallback", "usage.no_data", "usage.reset.in", "usage.reset.soon", "usage.duration.days_hours", "usage.duration.hours_minutes", "usage.duration.minutes", "usage.metric.session", "usage.metric.weekly", "usage.metric.monthly", "usage.metric.days_window", "usage.metric.named", "usage.metric.named_session", "usage.metric.named_weekly", "usage.metric.named_monthly", "usage.metric.named_days", "usage.metric.extra_usage", "usage.metric.rate_limit_resets", "usage.ticket_expiry", "usage.metric.credits", "usage.metric.weekly_limit", "usage.metric.pay_as_you_go", "usage.metric.bonus_credits", "usage.metric.overage_charges", "usage.metric.pay_per_use", "usage.unit.available", "usage.unit.credits", "usage.metric.usage_monthly", "usage.note.used_limit_unit", "usage.note.bonus_codes", "usage.value.disabled", "usage.value.cap", "usage.value.unlimited", "usage.note.binding", "usage.note.binding_severity", "usage.note.busiest_model", "usage.note.busiest_models", "usage.metric.agy_claude_others", "usage.metric.agy_claude_others_session", "usage.metric.agy_claude_others_weekly", "usage.hint.statusline_now", "usage.hint.statusline_minutes", "usage.hint.claude_api_key", "usage.hint.login_claude", "usage.hint.login_agy", "usage.hint.no_quota", "usage.hint.login_codex", "usage.hint.codex_no_oauth", "usage.hint.login_grok", "usage.hint.grok_no_login", "usage.hint.login_kiro", "usage.hint.kiro_signed_out", "usage.hint.claude_profile_signed_out", "usage.hint.claude_profile_signed_out_chat", "usage.hint.token_refreshing", "usage.hint.subscription_no_credit", "usage.hint.no_quota_account", "usage.error.unreachable", "usage.error.token_rejected", "usage.error.rate_limited", "usage.error.rate_limited_transient", "usage.stale_rate_limited", "usage.stale.expired", "usage.stale.transient", "usage.stale.error", "usage.metric.reset_since", "usage.error.http", "usage.error.billing_http", "usage.error.invalid_response", "usage.error.invalid_billing_response", "usage.error.invalid_kiro_response", "usage.error.claude_token_expired", "usage.error.codex_token_expired", "usage.error.grok_expired", "usage.error.grok_response_changed", "usage.error.agy_cap", "usage.error.agy_no_refresh", "usage.error.agy_token_expired", "usage.error.agy_login_expired", "usage.error.agy_refresh_empty", "usage.error.grok_auth_readonly", "usage.error.grok_no_refresh", "usage.error.grok_refresh_unreachable", "usage.error.grok_invalid_refresh", "usage.error.grok_persist"];
+export declare const USAGE_I18N_KEYS: readonly ["usage.title", "usage.title_plain", "usage.empty_active", "usage.not_logged_in", "usage.default_login", "usage.error_fallback", "usage.no_data", "usage.reset.in", "usage.reset.soon", "usage.duration.days_hours", "usage.duration.hours_minutes", "usage.duration.minutes", "usage.metric.session", "usage.metric.weekly", "usage.metric.monthly", "usage.metric.days_window", "usage.metric.named", "usage.metric.named_session", "usage.metric.named_weekly", "usage.metric.named_monthly", "usage.metric.named_days", "usage.metric.extra_usage", "usage.metric.rate_limit_resets", "usage.ticket_expiry", "usage.metric.credits", "usage.metric.weekly_limit", "usage.metric.pay_as_you_go", "usage.metric.bonus_credits", "usage.metric.overage_charges", "usage.metric.pay_per_use", "usage.unit.available", "usage.unit.credits", "usage.metric.usage_monthly", "usage.note.used_limit_unit", "usage.note.bonus_codes", "usage.value.disabled", "usage.value.cap", "usage.value.unlimited", "usage.note.binding", "usage.note.binding_severity", "usage.note.busiest_model", "usage.note.busiest_models", "usage.metric.agy_claude_others", "usage.metric.agy_claude_others_session", "usage.metric.agy_claude_others_weekly", "usage.hint.statusline_now", "usage.hint.statusline_minutes", "usage.hint.claude_api_key", "usage.hint.login_claude", "usage.hint.login_agy", "usage.hint.no_quota", "usage.hint.login_codex", "usage.hint.codex_no_oauth", "usage.hint.login_grok", "usage.hint.grok_no_login", "usage.hint.login_kiro", "usage.hint.kiro_signed_out", "usage.hint.claude_profile_signed_out", "usage.hint.claude_profile_signed_out_chat", "usage.hint.token_refreshing", "usage.hint.subscription_no_credit", "usage.hint.no_quota_account", "usage.error.unreachable", "usage.error.token_rejected", "usage.error.rate_limited", "usage.error.rate_limited_transient", "usage.stale_rate_limited", "usage.stale.expired", "usage.stale.transient", "usage.stale.error", "usage.metric.reset_since", "usage.error.http", "usage.error.billing_http", "usage.error.invalid_response", "usage.error.invalid_billing_response", "usage.error.invalid_kiro_response", "usage.error.claude_token_expired", "usage.error.codex_token_expired", "usage.error.grok_expired", "usage.error.grok_response_changed", "usage.error.agy_cap", "usage.error.agy_no_refresh", "usage.error.agy_token_expired", "usage.error.agy_login_expired", "usage.error.agy_refresh_empty", "usage.error.grok_auth_readonly", "usage.error.grok_no_refresh", "usage.error.grok_refresh_unreachable", "usage.error.grok_invalid_refresh", "usage.error.grok_persist", "usage.capacity.line", "usage.capacity.line_tokens", "usage.capacity.not_enough", "usage.capacity.only_agend", "usage.capacity.mixed", "usage.capacity.best_fit_api", "usage.capacity.best_fit_output", "usage.capacity.best_fit_all"];
 export type UsageI18nKey = typeof USAGE_I18N_KEYS[number];

package/dist/usage/i18n-keys.js

@@ -31,5 +31,8 @@ export const USAGE_I18N_KEYS = [
     "usage.error.agy_no_refresh", "usage.error.agy_token_expired", "usage.error.agy_login_expired",
     "usage.error.agy_refresh_empty", "usage.error.grok_auth_readonly", "usage.error.grok_no_refresh",
     "usage.error.grok_refresh_unreachable", "usage.error.grok_invalid_refresh", "usage.error.grok_persist",
+    // #3066 §1: a weekly quota's measured 100%.
+    "usage.capacity.line", "usage.capacity.line_tokens", "usage.capacity.not_enough", "usage.capacity.only_agend", "usage.capacity.mixed",
+    "usage.capacity.best_fit_api", "usage.capacity.best_fit_output", "usage.capacity.best_fit_all",
 ];
 //# sourceMappingURL=i18n-keys.js.map

package/dist/usage/i18n-keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"i18n-keys.js","sourceRoot":"","sources":["../../src/usage/i18n-keys.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,aAAa,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,qBAAqB;IACtG,sBAAsB,EAAE,eAAe,EAAE,gBAAgB,EAAE,kBAAkB;IAC7E,2BAA2B,EAAE,8BAA8B,EAAE,wBAAwB;IACrF,sBAAsB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,0BAA0B;IACjG,oBAAoB,EAAE,4BAA4B,EAAE,2BAA2B;IAC/E,4BAA4B,EAAE,yBAAyB,EAAE,0BAA0B;IACnF,gCAAgC,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,2BAA2B;IAC5G,4BAA4B,EAAE,4BAA4B,EAAE,8BAA8B;IAC1F,0BAA0B,EAAE,sBAAsB,EAAE,oBAAoB;IACxE,4BAA4B,EAAE,4BAA4B,EAAE,wBAAwB;IACpF,sBAAsB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,oBAAoB;IACxF,6BAA6B,EAAE,0BAA0B,EAAE,2BAA2B;IACtF,gCAAgC,EAAE,wCAAwC,EAAE,uCAAuC;IACnH,2BAA2B,EAAE,+BAA+B,EAAE,2BAA2B;IACzF,yBAAyB,EAAE,sBAAsB,EAAE,qBAAqB;IACxE,wBAAwB,EAAE,2BAA2B,EAAE,uBAAuB;IAC9E,0BAA0B,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,sCAAsC,EAAE,2CAA2C;IACtK,6BAA6B,EAAE,mCAAmC,EAAE,6BAA6B;IACjG,yBAAyB,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,oCAAoC,EAAE,0BAA0B;IACrJ,qBAAqB,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,0BAA0B;IAC/F,kBAAkB,EAAE,0BAA0B,EAAE,8BAA8B;IAC9E,sCAAsC,EAAE,mCAAmC;IAC3E,kCAAkC,EAAE,iCAAiC;IACrE,0BAA0B,EAAE,mCAAmC,EAAE,qBAAqB;IACtF,4BAA4B,EAAE,+BAA+B,EAAE,+BAA+B;IAC9F,+BAA+B,EAAE,gCAAgC,EAAE,6BAA6B;IAChG,sCAAsC,EAAE,kCAAkC,EAAE,0BAA0B;CAC9F,CAAC"}
+{"version":3,"file":"i18n-keys.js","sourceRoot":"","sources":["../../src/usage/i18n-keys.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,aAAa,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,qBAAqB;IACtG,sBAAsB,EAAE,eAAe,EAAE,gBAAgB,EAAE,kBAAkB;IAC7E,2BAA2B,EAAE,8BAA8B,EAAE,wBAAwB;IACrF,sBAAsB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,0BAA0B;IACjG,oBAAoB,EAAE,4BAA4B,EAAE,2BAA2B;IAC/E,4BAA4B,EAAE,yBAAyB,EAAE,0BAA0B;IACnF,gCAAgC,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,2BAA2B;IAC5G,4BAA4B,EAAE,4BAA4B,EAAE,8BAA8B;IAC1F,0BAA0B,EAAE,sBAAsB,EAAE,oBAAoB;IACxE,4BAA4B,EAAE,4BAA4B,EAAE,wBAAwB;IACpF,sBAAsB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,oBAAoB;IACxF,6BAA6B,EAAE,0BAA0B,EAAE,2BAA2B;IACtF,gCAAgC,EAAE,wCAAwC,EAAE,uCAAuC;IACnH,2BAA2B,EAAE,+BAA+B,EAAE,2BAA2B;IACzF,yBAAyB,EAAE,sBAAsB,EAAE,qBAAqB;IACxE,wBAAwB,EAAE,2BAA2B,EAAE,uBAAuB;IAC9E,0BAA0B,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,sCAAsC,EAAE,2CAA2C;IACtK,6BAA6B,EAAE,mCAAmC,EAAE,6BAA6B;IACjG,yBAAyB,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,oCAAoC,EAAE,0BAA0B;IACrJ,qBAAqB,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,0BAA0B;IAC/F,kBAAkB,EAAE,0BAA0B,EAAE,8BAA8B;IAC9E,sCAAsC,EAAE,mCAAmC;IAC3E,kCAAkC,EAAE,iCAAiC;IACrE,0BAA0B,EAAE,mCAAmC,EAAE,qBAAqB;IACtF,4BAA4B,EAAE,+BAA+B,EAAE,+BAA+B;IAC9F,+BAA+B,EAAE,gCAAgC,EAAE,6BAA6B;IAChG,sCAAsC,EAAE,kCAAkC,EAAE,0BAA0B;IACtG,4CAA4C;IAC5C,qBAAqB,EAAE,4BAA4B,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,sBAAsB;IACrI,6BAA6B,EAAE,gCAAgC,EAAE,6BAA6B;CACtF,CAAC"}

package/dist/usage/profile-timeline.d.ts

@@ -0,0 +1,16 @@
+export interface ProfileSpan {
+    t: number;
+    profile: string;
+}
+export declare const PROFILE_TIMELINE_FILE = "codex-profile-timeline.json";
+export declare const PROFILE_TIMELINE_MAX = 200;
+export declare const PROFILE_UNRECORDED = "unrecorded";
+/** The file's entries, checked and sorted (an unreadable or missing file: none). */
+export declare function readProfileTimeline(path: string): Promise<ProfileSpan[]>;
+/**
+ * A launch under `profile` at `t`. One write at a time per file; nothing is added when the last entry already names the
+ * same profile. Never throws: a lost entry leaves that run's turns under the previous entry's profile (or unrecorded).
+ */
+export declare function recordProfileLaunch(path: string, profile: string, t?: number): Promise<void>;
+/** The profile in effect at `t`: the latest entry at or before it, else "unrecorded". */
+export declare function profileAt(spans: readonly ProfileSpan[], t: number): string;

package/dist/usage/profile-timeline.js

@@ -0,0 +1,58 @@
+/**
+ * #3066 §1d: which credential profile a Codex instance ran under, and since when — so its usage is told by account. A
+ * Codex rollout does not say which login wrote it (so its hours were all "unrecorded"); AgEnD does know which profile it
+ * launched each Codex under. Each launch appends `{ t, profile }` to the instance's `codex-profile-timeline.json`; the
+ * usage scan tags each turn with the profile in effect at its time (the latest entry at or before it). A switch of
+ * profile is a relaunch, so a turn is never between two entries of one run. Turns from before the first entry stay
+ * "unrecorded" — history is never guessed.
+ *
+ * Small (≤ 200 entries, the oldest dropped) and written off the fleet's thread, atomically.
+ */
+import { readFile, rename, writeFile } from "node:fs/promises";
+export const PROFILE_TIMELINE_FILE = "codex-profile-timeline.json";
+export const PROFILE_TIMELINE_MAX = 200;
+export const PROFILE_UNRECORDED = "unrecorded";
+/** The file's entries, checked and sorted (an unreadable or missing file: none). */
+export async function readProfileTimeline(path) {
+    let v;
+    try {
+        v = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const list = v && typeof v === "object" && !Array.isArray(v) && Array.isArray(v.spans) ? v.spans : [];
+    return list.filter((e) => !!e && typeof e === "object" && typeof e.t === "number"
+        && Number.isFinite(e.t) && typeof e.profile === "string" && e.profile !== "")
+        .map((e) => ({ t: e.t, profile: e.profile })).sort((a, b) => a.t - b.t);
+}
+const writes = new Map();
+/**
+ * A launch under `profile` at `t`. One write at a time per file; nothing is added when the last entry already names the
+ * same profile. Never throws: a lost entry leaves that run's turns under the previous entry's profile (or unrecorded).
+ */
+export function recordProfileLaunch(path, profile, t = Date.now()) {
+    const next = (writes.get(path) ?? Promise.resolve()).then(async () => {
+        const spans = await readProfileTimeline(path);
+        if (spans.at(-1)?.profile === profile)
+            return;
+        const kept = [...spans, { t, profile }].slice(-PROFILE_TIMELINE_MAX);
+        const tmp = `${path}.${process.pid}.tmp`;
+        await writeFile(tmp, JSON.stringify({ v: 1, spans: kept }), { mode: 0o600 });
+        await rename(tmp, path);
+    }).catch(() => { });
+    writes.set(path, next);
+    return next;
+}
+/** The profile in effect at `t`: the latest entry at or before it, else "unrecorded". */
+export function profileAt(spans, t) {
+    let found = PROFILE_UNRECORDED;
+    for (const s of spans) {
+        if (s.t <= t)
+            found = s.profile;
+        else
+            break;
+    }
+    return found;
+}
+//# sourceMappingURL=profile-timeline.js.map

package/dist/usage/profile-timeline.js.map

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

package/dist/usage/quota-history.d.ts

@@ -0,0 +1,43 @@
+import type { ProviderUsage } from "./providers.js";
+export interface QuotaReading {
+    /** When the reading was made (ms). */
+    t: number;
+    /** The usage row's id: "claude", "claude:hsinlin", "codex:yanxianchen", … — one account. */
+    provider: string;
+    /** The credential profile, when the row has one. */
+    profile?: string;
+    /** The metric's label: "Weekly", "Sonnet (weekly)", … */
+    metric: string;
+    /** "model": the vendor's per-model quota (UsageMetric.scope) — its label names the model. Absent: not one. */
+    scope?: "model";
+    /** Percent used (0–100, as the vendor reports it). */
+    used: number;
+    /** When this window resets (ISO), or null when the vendor did not say. */
+    resetsAt: string | null;
+    windowMs: number | null;
+}
+export declare const QUOTA_HISTORY_KEEP_MS: number;
+export declare const QUOTA_HISTORY_MAX_BYTES: number;
+/**
+ * The same reset (Fable r1 #5): a vendor that gives only "resets in N seconds" yields a time that drifts by the read's own
+ * timing; within 10 minutes it is the same window, never a new line on every read. A real reset moves it by days.
+ */
+export declare const RESET_TOLERANCE_MS: number;
+export declare function sameReset(a: string | null, b: string | null): boolean;
+/** A line from the file, checked whole (it is not trusted): null when it is not a reading. */
+export declare function parseQuotaReading(line: string): QuotaReading | null;
+/** The weekly-or-longer percent metrics of a good read, as readings at `now`. */
+export declare function quotaReadingsOf(p: ProviderUsage, now: number): QuotaReading[];
+/**
+ * Record a good read's weekly readings: a line for each metric whose percent or reset time changed since its last line.
+ * Never throws and never blocks the caller: the write is queued (one at a time) and a failure only loses this reading.
+ */
+export declare function recordQuotaReadings(p: ProviderUsage, now?: number): void;
+/** Every reading kept, oldest first (§1 reads it). Unreadable lines are skipped. */
+export declare function readQuotaHistory(): Promise<QuotaReading[]>;
+/** Tests: write to `path` (null: nowhere), starting from what that file holds; resolves when queued writes are done. */
+export declare function setQuotaHistoryFileForTests(path: string | null): Promise<void>;
+/** Tests (usage-api's fetcher seam): record nothing, at once — never into the real AGEND_HOME. */
+export declare function quotaHistoryOffForTests(): void;
+/** Tests: wait for the queued writes. */
+export declare function flushQuotaHistory(): Promise<void>;

package/dist/usage/quota-history.js

@@ -0,0 +1,168 @@
+/**
+ * #3066 §1d: the weekly quota readings over time — the history the capacity estimate (§1) matches against the tokens each
+ * account used. Only the readings AgEnD already makes (get_usage, the usage page, the Discord presence refresh, the
+ * 30-minute background read): never an extra vendor call of its own.
+ *
+ * One JSON line per change: a weekly metric's percent or its reset time moved since the last line for that (provider,
+ * metric). A week is at most ~100 steps of a whole percent, so ≤ ~110 lines an account-week (~1–3 KB). Kept 12 weeks
+ * (older lines are dropped on the first write of each day) and never over 2 MB (the oldest lines go first, whenever the
+ * file is over it). A reset time within 10 minutes of the last is the same reset. Written off the fleet's thread
+ * (fs/promises), one write at a time.
+ * `usage-quota-history.jsonl` in AGEND_HOME.
+ */
+import { appendFile, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgendHome } from "../paths.js";
+export const QUOTA_HISTORY_KEEP_MS = 12 * 7 * 24 * 3_600_000;
+export const QUOTA_HISTORY_MAX_BYTES = 2 * 1024 * 1024;
+/** A window of a day or longer is a quota worth matching (the five-hour session window is not). */
+const MIN_WINDOW_MS = 24 * 3_600_000;
+let fileOf = () => join(getAgendHome(), "usage-quota-history.jsonl");
+/** The last reading written per (provider, metric): what a new one is compared with. */
+const last = new Map();
+let loaded = false;
+let chain = Promise.resolve();
+const keyOf = (provider, metric) => `${provider}\u0000${metric}`;
+/**
+ * The same reset (Fable r1 #5): a vendor that gives only "resets in N seconds" yields a time that drifts by the read's own
+ * timing; within 10 minutes it is the same window, never a new line on every read. A real reset moves it by days.
+ */
+export const RESET_TOLERANCE_MS = 10 * 60_000;
+export function sameReset(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    const ta = Date.parse(a), tb = Date.parse(b);
+    return Number.isFinite(ta) && Number.isFinite(tb) && Math.abs(ta - tb) < RESET_TOLERANCE_MS;
+}
+/** A line from the file, checked whole (it is not trusted): null when it is not a reading. */
+export function parseQuotaReading(line) {
+    let v;
+    try {
+        v = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return null;
+    const r = v;
+    if (typeof r.t !== "number" || !Number.isFinite(r.t) || typeof r.provider !== "string" || typeof r.metric !== "string"
+        || typeof r.used !== "number" || !Number.isFinite(r.used) || !(r.resetsAt === null || typeof r.resetsAt === "string")
+        || !(r.windowMs === null || (typeof r.windowMs === "number" && Number.isFinite(r.windowMs)))
+        || !(r.profile === undefined || typeof r.profile === "string") || !(r.scope === undefined || r.scope === "model"))
+        return null;
+    return { t: r.t, provider: r.provider, ...(r.profile !== undefined ? { profile: r.profile } : {}), metric: r.metric, ...(r.scope === "model" ? { scope: "model" } : {}), used: r.used,
+        resetsAt: r.resetsAt, windowMs: r.windowMs };
+}
+/** The weekly-or-longer percent metrics of a good read, as readings at `now`. */
+export function quotaReadingsOf(p, now) {
+    if (p.status !== "ok")
+        return [];
+    const out = [];
+    for (const m of p.metrics) {
+        if (m.type !== "percent" || typeof m.used !== "number" || !Number.isFinite(m.used))
+            continue;
+        if (typeof m.windowMs !== "number" || m.windowMs < MIN_WINDOW_MS)
+            continue;
+        out.push({ t: now, provider: p.id, ...(p.profile ? { profile: p.profile } : {}), metric: m.label, ...(m.scope === "model" ? { scope: "model" } : {}), used: m.used,
+            resetsAt: typeof m.resetsAt === "string" ? m.resetsAt : null, windowMs: m.windowMs });
+    }
+    return out;
+}
+async function load(path) {
+    if (loaded)
+        return;
+    loaded = true;
+    let text = "";
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        return;
+    } // none yet
+    for (const line of text.split("\n")) {
+        const r = line ? parseQuotaReading(line) : null;
+        if (r)
+            last.set(keyOf(r.provider, r.metric), { used: r.used, resetsAt: r.resetsAt });
+    }
+}
+/** When lines older than 12 weeks were last dropped: once a day (Fable r1 #3), and whenever the file is over its cap. */
+let lastAgePrune = Number.NEGATIVE_INFINITY;
+const AGE_PRUNE_EVERY_MS = 24 * 3_600_000;
+/** Keep the last 12 weeks, and the file under its cap (oldest first out). Rewritten atomically. */
+async function prune(path, now) {
+    let size = 0;
+    try {
+        size = (await stat(path)).size;
+    }
+    catch {
+        return;
+    }
+    if (size <= QUOTA_HISTORY_MAX_BYTES && now - lastAgePrune < AGE_PRUNE_EVERY_MS)
+        return;
+    lastAgePrune = now;
+    const lines = (await readFile(path, "utf8")).split("\n").filter((l) => {
+        const r = l ? parseQuotaReading(l) : null;
+        return r !== null && r.t >= now - QUOTA_HISTORY_KEEP_MS;
+    });
+    let bytes = lines.reduce((n, l) => n + Buffer.byteLength(l) + 1, 0), from = 0;
+    while (bytes > QUOTA_HISTORY_MAX_BYTES * 0.9 && from < lines.length)
+        bytes -= Buffer.byteLength(lines[from++]) + 1;
+    const tmp = `${path}.${process.pid}.tmp`;
+    await writeFile(tmp, lines.slice(from).map((l) => `${l}\n`).join(""), { mode: 0o600 });
+    await rename(tmp, path);
+}
+/**
+ * Record a good read's weekly readings: a line for each metric whose percent or reset time changed since its last line.
+ * Never throws and never blocks the caller: the write is queued (one at a time) and a failure only loses this reading.
+ */
+export function recordQuotaReadings(p, now = Date.now()) {
+    if (!fileOf)
+        return;
+    const readings = quotaReadingsOf(p, now);
+    if (!readings.length)
+        return;
+    const path = fileOf();
+    chain = chain.then(async () => {
+        await load(path);
+        const fresh = readings.filter((r) => {
+            const was = last.get(keyOf(r.provider, r.metric));
+            return !was || was.used !== r.used || !sameReset(was.resetsAt, r.resetsAt);
+        });
+        if (!fresh.length)
+            return;
+        await appendFile(path, fresh.map((r) => `${JSON.stringify(r)}\n`).join(""), { mode: 0o600 });
+        for (const r of fresh)
+            last.set(keyOf(r.provider, r.metric), { used: r.used, resetsAt: r.resetsAt });
+        await prune(path, now);
+    }).catch(() => { });
+}
+/** Every reading kept, oldest first (§1 reads it). Unreadable lines are skipped. */
+export async function readQuotaHistory() {
+    if (!fileOf)
+        return [];
+    await chain;
+    let text = "";
+    try {
+        text = await readFile(fileOf(), "utf8");
+    }
+    catch {
+        return [];
+    }
+    return text.split("\n").map((l) => (l ? parseQuotaReading(l) : null)).filter((r) => r !== null).sort((a, b) => a.t - b.t);
+}
+/** Tests: write to `path` (null: nowhere), starting from what that file holds; resolves when queued writes are done. */
+export async function setQuotaHistoryFileForTests(path) {
+    await chain;
+    fileOf = path === null ? null : () => path;
+    last.clear();
+    loaded = false;
+    lastAgePrune = Number.NEGATIVE_INFINITY;
+}
+/** Tests (usage-api's fetcher seam): record nothing, at once — never into the real AGEND_HOME. */
+export function quotaHistoryOffForTests() { fileOf = null; last.clear(); loaded = false; }
+/** Tests: wait for the queued writes. */
+export function flushQuotaHistory() { return chain; }
+//# sourceMappingURL=quota-history.js.map

package/dist/usage/quota-history.js.map

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

package/dist/usage/usage-api.d.ts

@@ -15,6 +15,8 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { FleetConfig } from "../types.js";
 import type { Logger } from "pino";
 import { type ProviderUsage, type UsageMetric } from "./providers.js";
+import type { CapacityBasis, CapacityEstimate } from "./capacity.js";
+import type { UsageI18nRef } from "./providers.js";
 export interface UsageApiContext {
     readonly fleetConfig: FleetConfig | null;
     readonly logger: Logger;
@@ -50,6 +52,35 @@ export declare function setUsageLastGoodFileForTests(path: string | null): Promi
 export declare function getUsageSnapshot(force?: boolean, providerIds?: Iterable<string>, opts?: {
     allowStale?: boolean;
 }): Promise<UsagePayload>;
+/** A weekly metric's measured 100%, as served: the numbers, and its lines in words (text + key, like a metric's note). */
+export interface UsageCapacity {
+    status: "ok" | "not_enough";
+    deltaPct: number;
+    windows?: number;
+    basis?: CapacityBasis;
+    median?: number;
+    low?: number;
+    high?: number;
+    /** All tokens at 100% (median), beside an API-equivalent line. */
+    tokens?: number;
+    bestFit?: CapacityBasis | null;
+    mixed?: boolean;
+    line: {
+        text: string;
+        i18n: UsageI18nRef;
+    };
+    notes: Array<{
+        text: string;
+        i18n: UsageI18nRef;
+    }>;
+}
+export declare function setCapacityLookup(fn: ((provider: string, metric: string) => CapacityEstimate | null) | null): void;
+export declare const compactTokens: (n: number) => string;
+/**
+ * The words for an estimate (English text; the page shows its own language from the key). Null when an "ok" estimate
+ * has no basis (Prism #3073 P1: estimateCapacity never makes one, but a read must not fail on it).
+ */
+export declare function capacityText(est: CapacityEstimate): UsageCapacity | null;
 /**
  * Render a usage payload as one compact chat message.
  *