@songsid/agend 2.3.4-beta.7 → 2.3.4-beta.9

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.
  *

package/dist/usage/usage-api.js

@@ -7,6 +7,7 @@ import { getAgendHome } from "../paths.js";
 import { t } from "../locale.js";
 import { usageExpiryText, usageResetSinceText, usageResetText, usageRowName, usageStaleText, usageText } from "./i18n.js";
 import { guestRequestOf } from "../web-guest-access.js";
+import { quotaHistoryOffForTests, recordQuotaReadings } from "./quota-history.js";
 /** Keep primary account limits even at zero; hide only unused per-model noise. */
 export function isVisibleUsageMetric(metric) {
     return !(metric.scope === "model"
@@ -114,6 +115,7 @@ export function setUsageFetcherForTests(fn) {
     lastGood.clear();
     lastGoodFile = null;
     lastGoodLoaded = true;
+    quotaHistoryOffForTests();
     retryAfterUntil.clear();
 }
 /** Tests: persist lastGood at `path` (read it on the next use), or not at all (null). */
@@ -267,6 +269,7 @@ function withStaleFallback(payload) {
     const providers = payload.providers.map(p => {
         if (p.status === "ok" && p.metrics.length > 0) {
             lastGood.set(p.id, { at: now, provider: p });
+            recordQuotaReadings(p, now); // #3066 §1d: the weekly percent over time (only when it moved)
             changed = true;
             return p;
         }
@@ -410,7 +413,83 @@ function fetchFor(owner, effectiveForce, again) {
  * second entry point that bypassed it would defeat that.
  */
 export async function getUsageSnapshot(force = false, providerIds, opts = {}) {
-    return filterUsageProviders(reageStale(await usage(force, opts.allowStale === true), Date.now()), providerIds, { hostLogins: true });
+    return withCapacity(filterUsageProviders(reageStale(await usage(force, opts.allowStale === true), Date.now()), providerIds, { hostLogins: true }));
+}
+/** Published by the fleet (FleetManager.refreshCapacity): the estimate for a provider's metric, read synchronously. */
+let capacityLookup = null;
+export function setCapacityLookup(fn) { capacityLookup = fn; }
+const money0 = (n) => `$${n >= 100 ? Math.round(n).toLocaleString("en-US") : n.toFixed(2)}`;
+export const compactTokens = (n) => (n >= 1e9 ? `${(n / 1e9).toFixed(1)}B` : n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${Math.round(n / 1e3)}k` : String(Math.round(n)));
+const ref = (key, args) => ({ key: key, args });
+const fill = (text, args) => args.reduce((s, a, i) => s.split(`{${i}}`).join(String(a)), text);
+/**
+ * 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 function capacityText(est) {
+    const onlyAgend = { text: "Counts only this fleet's agents; use of the same account elsewhere makes this low.", i18n: ref("usage.capacity.only_agend", []) };
+    if (est.status === "not_enough") {
+        const args = [est.deltaPct];
+        return { status: "not_enough", deltaPct: est.deltaPct, line: { text: fill("Not enough usage yet to measure 100% (Δ {0}% of 10%)", args), i18n: ref("usage.capacity.not_enough", args) }, notes: [onlyAgend] };
+    }
+    const api = est.bases.api, tokensBasis = est.bases.all ?? est.bases.output;
+    if (!api && !tokensBasis)
+        return null;
+    const basis = api ? "api" : est.bases.all ? "all" : "output";
+    const chosen = est.bases[basis];
+    let line;
+    if (api && est.bases.all) {
+        const args = [money0(api.median), money0(api.low), money0(api.high), compactTokens(est.bases.all.median), api.windows];
+        line = { text: fill("100% ≈ {0} ({1}–{2}) · ≈ {3} tokens · from {4} weeks", args), i18n: ref("usage.capacity.line", args) };
+    }
+    else {
+        const args = [compactTokens(chosen.median), compactTokens(chosen.low), compactTokens(chosen.high), chosen.windows];
+        line = { text: fill("100% ≈ {0} tokens ({1}–{2}) · from {3} weeks", args), i18n: ref("usage.capacity.line_tokens", args) };
+    }
+    const notes = [onlyAgend];
+    const fit = est.bestFit ? est.bases[est.bestFit] : undefined;
+    if (est.bestFit && fit && fit.cv !== null) {
+        const args = [Math.round(fit.cv * 100), fit.windows];
+        const sentence = { api: "API-equivalent fits best: ±{0}% across {1} weeks", output: "Output tokens fit best: ±{0}% across {1} weeks", all: "All tokens fit best: ±{0}% across {1} weeks" }[est.bestFit];
+        notes.push({ text: fill(sentence, args), i18n: ref(`usage.capacity.best_fit_${est.bestFit}`, args) });
+    }
+    if (est.mixed)
+        notes.push({ text: "Bases disagree — possibly used outside this fleet", i18n: ref("usage.capacity.mixed", []) });
+    return { status: "ok", deltaPct: est.deltaPct, windows: chosen.windows, basis, median: chosen.median, low: chosen.low, high: chosen.high,
+        ...(api && est.bases.all ? { tokens: est.bases.all.median } : {}), bestFit: est.bestFit, mixed: est.mixed, line, notes };
+}
+/** Each weekly percent metric with an estimate gets `capacity` — on copies: the cached payload stays as read. */
+function withCapacity(payload) {
+    const look = capacityLookup;
+    if (!look)
+        return payload;
+    let any = false;
+    const providers = payload.providers.map((p) => {
+        if (p.status !== "ok")
+            return p;
+        let changed = false;
+        const metrics = p.metrics.map((m) => {
+            if (m.type !== "percent" || typeof m.windowMs !== "number" || m.windowMs < 24 * 3_600_000)
+                return m;
+            let capacity = null;
+            try {
+                const est = look(p.id, m.label);
+                capacity = est ? capacityText(est) : null;
+            }
+            catch {
+                capacity = null;
+            }
+            if (!capacity)
+                return m; // an estimate that cannot be put in words never fails the read
+            changed = true;
+            return { ...m, capacity };
+        });
+        if (!changed)
+            return p;
+        any = true;
+        return { ...p, metrics };
+    });
+    return any ? { ...payload, providers } : payload;
 }
 /**
  * Last known numbers age while they are served (Prism #2257 P2): a snapshot is reused for minutes, and a window may