@aliou/pi-synthetic 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-synthetic",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -17,7 +17,8 @@
     "extensions": [
       "./src/extensions/provider/index.ts",
       "./src/extensions/web-search/index.ts",
-      "./src/extensions/command-quotas/index.ts"
+      "./src/extensions/command-quotas/index.ts",
+      "./src/extensions/quota-warnings/index.ts"
     ],
     "video": "https://assets.aliou.me/pi-extensions/demos/pi-synthetic.mp4"
   },

package/src/extensions/command-quotas/components/quotas-display.ts

@@ -3,167 +3,19 @@ import { DynamicBorder } from "@mariozechner/pi-coding-agent";
 import type { Component, TUI } from "@mariozechner/pi-tui";
 import { Loader, matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
 import type { QuotasResponse } from "../../../types/quotas";
+import {
+  assessWindow,
+  formatTimeRemaining,
+  getSeverityColor,
+  type QuotaWindow,
+  toWindows,
+} from "../../../utils/quotas-severity";
 
 type QuotasState =
   | { type: "loading" }
   | { type: "error"; message: string }
   | { type: "loaded"; quotas: QuotasResponse };
 
-interface QuotaWindow {
-  label: string;
-  usedPercent: number;
-  resetsAt: Date;
-  windowSeconds: number;
-  usedValue: number;
-  limitValue: number;
-  isCurrency?: boolean;
-  showPace?: boolean;
-  paceScale?: number;
-  limited?: boolean;
-  nextAmount?: string;
-  nextLabel?: string;
-}
-
-/** Safely compute percentage, guarding against division by zero */
-function safePercent(used: number, limit: number): number {
-  if (!Number.isFinite(used) || !Number.isFinite(limit) || limit <= 0) return 0;
-  return Math.max(0, Math.min(100, (used / limit) * 100));
-}
-
-/** Parse currency string like "$1,234.56" to number */
-function parseCurrency(value: string): number {
-  const n = Number(value.replace(/[^0-9.-]/g, ""));
-  return Number.isFinite(n) ? n : 0;
-}
-
-function toWindows(quotas: QuotasResponse): QuotaWindow[] {
-  const windows: QuotaWindow[] = [];
-
-  if (quotas.weeklyTokenLimit) {
-    const { weeklyTokenLimit } = quotas;
-    const limitValue = parseCurrency(weeklyTokenLimit.maxCredits);
-    const remainingValue = parseCurrency(weeklyTokenLimit.remainingCredits);
-    windows.push({
-      label: "Credits / week",
-      usedPercent: Math.max(
-        0,
-        Math.min(100, 100 - weeklyTokenLimit.percentRemaining),
-      ),
-      resetsAt: new Date(weeklyTokenLimit.nextRegenAt),
-      windowSeconds: 24 * 60 * 60,
-      usedValue: limitValue - remainingValue,
-      limitValue,
-      isCurrency: true,
-      showPace: true,
-      paceScale: 1 / 7,
-      nextAmount: `+${weeklyTokenLimit.nextRegenCredits}`,
-      nextLabel: "Next regen",
-    });
-  }
-
-  if (quotas.rollingFiveHourLimit && quotas.rollingFiveHourLimit.max > 0) {
-    const { rollingFiveHourLimit } = quotas;
-    const used = rollingFiveHourLimit.max - rollingFiveHourLimit.remaining;
-    const tickAmount =
-      rollingFiveHourLimit.tickPercent * rollingFiveHourLimit.max;
-    windows.push({
-      label: "Requests / 5h",
-      usedPercent: safePercent(used, rollingFiveHourLimit.max),
-      resetsAt: new Date(rollingFiveHourLimit.nextTickAt),
-      windowSeconds: 5 * 60 * 60,
-      usedValue: Math.round(used),
-      limitValue: rollingFiveHourLimit.max,
-      showPace: false,
-      limited: rollingFiveHourLimit.limited,
-      nextAmount: `+${tickAmount.toFixed(1)}`,
-      nextLabel: "Next tick",
-    });
-  }
-
-  if (quotas.search?.hourly?.limit && quotas.search.hourly.limit > 0) {
-    const { hourly } = quotas.search;
-    windows.push({
-      label: "Search / hour",
-      usedPercent: safePercent(hourly.requests, hourly.limit),
-      resetsAt: new Date(hourly.renewsAt),
-      windowSeconds: 60 * 60,
-      usedValue: hourly.requests,
-      limitValue: hourly.limit,
-      showPace: true,
-      paceScale: 1,
-      nextLabel: "Resets",
-    });
-  }
-
-  if (quotas.freeToolCalls?.limit && quotas.freeToolCalls.limit > 0) {
-    windows.push({
-      label: "Free Tool Calls / day",
-      usedPercent: safePercent(
-        quotas.freeToolCalls.requests,
-        quotas.freeToolCalls.limit,
-      ),
-      resetsAt: new Date(quotas.freeToolCalls.renewsAt),
-      windowSeconds: 24 * 60 * 60,
-      usedValue: quotas.freeToolCalls.requests,
-      limitValue: quotas.freeToolCalls.limit,
-      showPace: true,
-      paceScale: 1,
-      nextLabel: "Resets",
-    });
-  }
-
-  return windows;
-}
-
-function getPacePercent(window: QuotaWindow): number | null {
-  const totalMs = window.windowSeconds * 1000;
-  if (totalMs <= 0) return null;
-  const remainingMs = window.resetsAt.getTime() - Date.now();
-  const elapsedMs = totalMs - remainingMs;
-  return Math.max(0, Math.min(100, (elapsedMs / totalMs) * 100));
-}
-
-function getProjectedPercent(
-  usedPercent: number,
-  pacePercent: number | null,
-): number {
-  if (pacePercent === null) return usedPercent;
-  const effectivePace = Math.max(5, pacePercent);
-  return Math.max(0, (usedPercent / effectivePace) * 100);
-}
-
-function getSeverity(
-  projectedPercent: number,
-  pacePercent: number | null,
-): "success" | "warning" | "error" {
-  if (pacePercent === null) {
-    if (projectedPercent >= 100) return "error";
-    if (projectedPercent >= 90) return "warning";
-    return "success";
-  }
-  // Dynamic thresholds based on window progress
-  const progress = pacePercent / 100;
-  const warnThreshold = 260 - (260 - 120) * progress;
-  const highThreshold = 320 - (320 - 145) * progress;
-  const criticalThreshold = 400 - (400 - 170) * progress;
-
-  if (projectedPercent >= criticalThreshold) return "error";
-  if (projectedPercent >= highThreshold) return "error";
-  if (projectedPercent >= warnThreshold) return "warning";
-  return "success";
-}
-
-function formatTimeRemaining(date: Date): string {
-  const ms = date.getTime() - Date.now();
-  if (ms <= 0) return "now";
-  const totalMins = Math.ceil(ms / (1000 * 60));
-  const hours = Math.floor(totalMins / 60);
-  const mins = totalMins % 60;
-  if (hours >= 1) return mins > 0 ? `${hours}h${mins}m` : `${hours}h`;
-  const totalSecs = Math.ceil(ms / 1000);
-  return totalMins >= 1 ? `${totalMins}m` : `${totalSecs}s`;
-}
-
 /**
  * Convert a foreground ANSI escape to its background equivalent.
  * Handles truecolor (38;2), 256-color (38;5), and basic (3X) escapes.
@@ -355,15 +207,8 @@ export class QuotasComponent implements Component {
     const lines: string[] = [];
     const theme = this.theme;
 
-    const rawPace = window.showPace ? getPacePercent(window) : null;
-    const pacePercent =
-      rawPace !== null ? rawPace * (window.paceScale ?? 1) : null;
-    const projectedPercent = getProjectedPercent(
-      window.usedPercent,
-      pacePercent,
-    );
-    let severity = getSeverity(projectedPercent, pacePercent);
-    if (window.limited) severity = "error";
+    const assessment = assessWindow(window);
+    const color = getSeverityColor(assessment.severity);
 
     // Label
     lines.push(
@@ -375,8 +220,8 @@ export class QuotasComponent implements Component {
       window.usedPercent,
       barWidth,
       theme,
-      severity,
-      pacePercent,
+      color,
+      assessment.pacePercent,
     );
     const usedStr = window.isCurrency
       ? `${Math.round(window.usedPercent)}%/$${window.limitValue.toFixed(2)}`
@@ -384,7 +229,7 @@ export class QuotasComponent implements Component {
     const limitedBadge = window.limited ? theme.fg("error", " LIMITED") : "";
     lines.push(
       truncateToWidth(
-        `  ${bar} ${theme.fg(severity, usedStr)}${limitedBadge}`,
+        `  ${bar} ${theme.fg(color, usedStr)}${limitedBadge}`,
         maxWidth,
       ),
     );

package/src/extensions/provider/models.ts

@@ -36,7 +36,7 @@ const SYNTHETIC_REASONING_EFFORT_MAP = {
 } as const;
 
 export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
-  // API: hf:zai-org/GLM-4.7 → ctx=202752, multimodal
+  // API: hf:zai-org/GLM-4.7 → ctx=202752
   {
     id: "hf:zai-org/GLM-4.7",
     name: "zai-org/GLM-4.7",
@@ -45,11 +45,11 @@ export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
       supportsReasoningEffort: true,
       reasoningEffortMap: SYNTHETIC_REASONING_EFFORT_MAP,
     },
-    input: ["text", "image"],
+    input: ["text"],
     cost: {
-      input: 2.19,
+      input: 0.45,
       output: 2.19,
-      cacheRead: 2.19,
+      cacheRead: 0.45,
       cacheWrite: 0,
     },
     contextWindow: 202752,

package/src/extensions/quota-warnings/index.ts

@@ -0,0 +1,22 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { clearAlertState, triggerCheck } from "./notifier";
+
+export default async function (pi: ExtensionAPI) {
+  // Session start: reset local warning state and run an immediate check
+  pi.on("session_start", async (_event, ctx) => {
+    if (ctx.model?.provider !== "synthetic") return;
+    clearAlertState();
+    triggerCheck(ctx, ctx.model, false);
+  });
+
+  // Check after agent turn - only warn for newly crossed thresholds
+  pi.on("agent_end", async (_event, ctx) => {
+    if (ctx.model?.provider !== "synthetic") return;
+    triggerCheck(ctx, ctx.model, true);
+  });
+
+  // Clear state on shutdown
+  pi.on("session_shutdown", async () => {
+    clearAlertState();
+  });
+}

package/src/extensions/quota-warnings/notifier.test.ts

@@ -0,0 +1,280 @@
+import { assert, beforeEach, describe, expect, it } from "vitest";
+import type { QuotasResponse } from "../../types/quotas";
+import { assessWindow, type QuotaWindow } from "../../utils/quotas-severity";
+import {
+  clearAlertState,
+  findHighRiskWindows,
+  formatWarningMessage,
+  markNotified,
+  shouldNotify,
+} from "./notifier";
+
+// Access the module-scoped windowAlerts map for test inspection.
+// We import the module and rely on clearAlertState() to reset between tests.
+//
+// Since windowAlerts is not exported, we test shouldNotify/markNotified
+// by observing their behavior (the state machine) rather than reading the map directly.
+
+beforeEach(() => {
+  clearAlertState();
+});
+
+describe("shouldNotify", () => {
+  it("notifies on first time seeing a window at risk", () => {
+    expect(shouldNotify("Credits / week", "warning")).toBe(true);
+    expect(shouldNotify("Requests / 5h", "high")).toBe(true);
+    expect(shouldNotify("Search / hour", "critical")).toBe(true);
+  });
+
+  it("notifies on severity escalation", () => {
+    markNotified("Credits / week", "warning");
+    expect(shouldNotify("Credits / week", "high")).toBe(true);
+
+    markNotified("Requests / 5h", "high");
+    expect(shouldNotify("Requests / 5h", "critical")).toBe(true);
+  });
+
+  it("notifies on skip from none to any risk level", () => {
+    // When a window was at "none" (implicitly, by not being in the map)
+    // and escalates, it's first-time => true. But also test explicit none->warning.
+    markNotified("Test", "none");
+    expect(shouldNotify("Test", "warning")).toBe(true);
+  });
+
+  it("does not notify on same severity for warning within cooldown", () => {
+    markNotified("Credits / week", "warning");
+    expect(shouldNotify("Credits / week", "warning")).toBe(false);
+  });
+
+  it("does not notify on downgrade to warning", () => {
+    markNotified("Credits / week", "high");
+    expect(shouldNotify("Credits / week", "warning")).toBe(false);
+  });
+
+  it("does notify on downgrade to high (no cooldown)", () => {
+    // high always re-notifies regardless of previous severity
+    markNotified("Requests / 5h", "critical");
+    expect(shouldNotify("Requests / 5h", "high")).toBe(true);
+  });
+
+  it("always notifies for high severity (no cooldown)", () => {
+    markNotified("Credits / week", "high");
+    // Same severity, but high always re-notifies
+    expect(shouldNotify("Credits / week", "high")).toBe(true);
+  });
+
+  it("always notifies for critical severity (no cooldown)", () => {
+    markNotified("Credits / week", "critical");
+    expect(shouldNotify("Credits / week", "critical")).toBe(true);
+  });
+});
+
+describe("markNotified", () => {
+  it("tracks severity per window key", () => {
+    markNotified("Credits / week", "warning");
+    // After marking as warning, re-checking warning should be blocked
+    expect(shouldNotify("Credits / week", "warning")).toBe(false);
+
+    // But a different key is independent
+    expect(shouldNotify("Requests / 5h", "warning")).toBe(true);
+  });
+
+  it("allows re-notification after escalation then downgrade then re-escalation", () => {
+    markNotified("Test", "high");
+    // Downgrade doesn't notify but updates state
+    expect(shouldNotify("Test", "warning")).toBe(false);
+    // Re-escalation notifies
+    expect(shouldNotify("Test", "high")).toBe(true);
+  });
+});
+
+describe("clearAlertState", () => {
+  it("resets all alert state so windows notify again", () => {
+    markNotified("Credits / week", "warning");
+    expect(shouldNotify("Credits / week", "warning")).toBe(false);
+
+    clearAlertState();
+
+    expect(shouldNotify("Credits / week", "warning")).toBe(true);
+  });
+});
+
+describe("findHighRiskWindows", () => {
+  const baseQuotas: QuotasResponse = {
+    weeklyTokenLimit: {
+      nextRegenAt: new Date(Date.now() + 6 * 24 * 3600 * 1000).toISOString(),
+      percentRemaining: 90, // 10% used
+      maxCredits: "$10.00",
+      remainingCredits: "$9.00",
+      nextRegenCredits: "$0.50",
+    },
+    rollingFiveHourLimit: {
+      nextTickAt: new Date(Date.now() + 2.5 * 3600 * 1000).toISOString(),
+      tickPercent: 10,
+      remaining: 90,
+      max: 100,
+      limited: false,
+    },
+    search: {
+      hourly: {
+        limit: 100,
+        requests: 10, // 10% used
+        renewsAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
+      },
+    },
+    freeToolCalls: {
+      limit: 100,
+      requests: 5, // 5% used
+      renewsAt: new Date(Date.now() + 12 * 3600 * 1000).toISOString(),
+    },
+  };
+
+  it("returns empty for low-usage quotas", () => {
+    const risks = findHighRiskWindows(baseQuotas);
+    // All windows have low usage, most should be "none"
+    // The 5h window at 10% used with no pace => "none"
+    // Weekly at 10% with paceScale 1/7 => very low projected => "none"
+    expect(risks).toHaveLength(0);
+  });
+
+  it("finds windows with high usage", () => {
+    const quotas: QuotasResponse = {
+      ...baseQuotas,
+      rollingFiveHourLimit: {
+        nextTickAt: new Date(Date.now() + 2.5 * 3600 * 1000).toISOString(),
+        tickPercent: 10,
+        remaining: 5,
+        max: 100,
+        limited: false,
+      },
+    };
+    const risks = findHighRiskWindows(quotas);
+    // 95% used, no pace => static: >=90 => high
+    const fiveHourRisk = risks.find((r) => r.window.label === "Requests / 5h");
+    assert(fiveHourRisk, "fiveHourRisk should exist");
+    expect(fiveHourRisk.assessment.severity).toBe("high");
+  });
+
+  it("finds limited windows even with low usage", () => {
+    const quotas: QuotasResponse = {
+      ...baseQuotas,
+      rollingFiveHourLimit: {
+        nextTickAt: new Date(Date.now() + 2.5 * 3600 * 1000).toISOString(),
+        tickPercent: 10,
+        remaining: 95,
+        max: 100,
+        limited: true,
+      },
+    };
+    const risks = findHighRiskWindows(quotas);
+    const fiveHourRisk = risks.find((r) => r.window.label === "Requests / 5h");
+    assert(fiveHourRisk, "fiveHourRisk should exist");
+    expect(fiveHourRisk.assessment.severity).toBe("critical");
+  });
+
+  it("returns empty for quotas with no windows", () => {
+    const quotas: QuotasResponse = {};
+    expect(findHighRiskWindows(quotas)).toHaveLength(0);
+  });
+});
+
+describe("formatWarningMessage", () => {
+  it("formats single window warning", () => {
+    const w: QuotaWindow = {
+      label: "Requests / 5h",
+      usedPercent: 92,
+      resetsAt: new Date(Date.now() + 2 * 3600 * 1000),
+      windowSeconds: 5 * 3600,
+      usedValue: 92,
+      limitValue: 100,
+      showPace: false,
+    };
+    const assessment = assessWindow(w);
+    const msg = formatWarningMessage([{ window: w, assessment }]);
+    expect(msg).toContain("Synthetic quota warning:");
+    expect(msg).toContain("Requests / 5h");
+    expect(msg).toContain("92% used");
+    expect(msg).toContain("projected");
+  });
+
+  it("formats multiple windows", () => {
+    const w1: QuotaWindow = {
+      label: "Credits / week",
+      usedPercent: 85,
+      resetsAt: new Date(Date.now() + 6 * 24 * 3600 * 1000),
+      windowSeconds: 7 * 24 * 3600,
+      usedValue: 85,
+      limitValue: 100,
+      showPace: true,
+      paceScale: 1 / 7,
+    };
+    const w2: QuotaWindow = {
+      label: "Requests / 5h",
+      usedPercent: 92,
+      resetsAt: new Date(Date.now() + 2 * 3600 * 1000),
+      windowSeconds: 5 * 3600,
+      usedValue: 92,
+      limitValue: 100,
+      showPace: false,
+    };
+    const msg = formatWarningMessage([
+      { window: w1, assessment: assessWindow(w1) },
+      { window: w2, assessment: assessWindow(w2) },
+    ]);
+    expect(msg).toContain("Credits / week");
+    expect(msg).toContain("Requests / 5h");
+    // Two separate lines
+    const lines = msg.split("\n");
+    expect(lines).toHaveLength(3); // header + 2 windows
+  });
+
+  it("includes severity label for non-none severities", () => {
+    const w: QuotaWindow = {
+      label: "Requests / 5h",
+      usedPercent: 92,
+      resetsAt: new Date(Date.now() + 2 * 3600 * 1000),
+      windowSeconds: 5 * 3600,
+      usedValue: 92,
+      limitValue: 100,
+      showPace: false,
+    };
+    const msg = formatWarningMessage([
+      { window: w, assessment: assessWindow(w) },
+    ]);
+    expect(msg).toMatch(/\(high\)/);
+  });
+});
+
+describe("notification flow (shouldNotify + markNotified integration)", () => {
+  it("notifies once on first warning, blocks repeat, notifies on escalation", () => {
+    // 1. First warning
+    expect(shouldNotify("Credits / week", "warning")).toBe(true);
+    markNotified("Credits / week", "warning");
+
+    // 2. Same severity within cooldown
+    expect(shouldNotify("Credits / week", "warning")).toBe(false);
+
+    // 3. Escalation to high
+    expect(shouldNotify("Credits / week", "high")).toBe(true);
+    markNotified("Credits / week", "high");
+
+    // 4. High always re-notifies (no cooldown)
+    expect(shouldNotify("Credits / week", "high")).toBe(true);
+  });
+
+  it("allows re-notification after clear", () => {
+    expect(shouldNotify("Credits / week", "warning")).toBe(true);
+    markNotified("Credits / week", "warning");
+    expect(shouldNotify("Credits / week", "warning")).toBe(false);
+
+    clearAlertState();
+
+    expect(shouldNotify("Credits / week", "warning")).toBe(true);
+  });
+
+  it("tracks windows independently", () => {
+    markNotified("Credits / week", "warning");
+    expect(shouldNotify("Credits / week", "warning")).toBe(false);
+    expect(shouldNotify("Search / hour", "warning")).toBe(true);
+  });
+});

package/src/extensions/quota-warnings/notifier.ts

@@ -0,0 +1,200 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { getSyntheticApiKey } from "../../lib/env";
+import type { QuotasResponse } from "../../types/quotas";
+import { fetchQuotas } from "../../utils/quotas";
+import {
+  assessWindow,
+  formatTimeRemaining,
+  type QuotaWindow,
+  type RiskAssessment,
+  type RiskSeverity,
+  toWindows,
+} from "../../utils/quotas-severity";
+
+const COOLDOWN_MS = 60 * 60 * 1000; // 60 minutes
+const MIN_FETCH_INTERVAL_MS = 30_000; // 30 seconds
+
+export interface WindowAlertState {
+  lastSeverity: RiskSeverity;
+  lastNotifiedAt: number; // epoch ms
+}
+
+// Key format: "label" (e.g., "Credits / week", "Requests / 5h")
+const windowAlerts = new Map<string, WindowAlertState>();
+
+let lastFetchAt = 0;
+
+interface WindowRisk {
+  window: QuotaWindow;
+  assessment: RiskAssessment;
+}
+
+/**
+ * Finds windows that exceed the risk threshold.
+ * Returns windows with their risk assessments.
+ */
+export function findHighRiskWindows(quotas: QuotasResponse): WindowRisk[] {
+  const windows = toWindows(quotas);
+  return windows
+    .map((window) => ({ window, assessment: assessWindow(window) }))
+    .filter((item) => item.assessment.severity !== "none");
+}
+
+/**
+ * Determines if we should notify for this window based on cooldown and severity rules.
+ * Rules:
+ * - First time seeing this window at risk: notify
+ * - Severity escalation (warning → high → critical): notify
+ * - Cooldown elapsed (60 min) AND severity is "warning": notify
+ * - High/Critical severity: always notify (no cooldown)
+ */
+export function shouldNotify(
+  windowKey: string,
+  severity: RiskSeverity,
+): boolean {
+  const state = windowAlerts.get(windowKey);
+
+  if (!state) {
+    // First time seeing this window at risk
+    return true;
+  }
+
+  // Severity escalation always notifies
+  const severityOrder: RiskSeverity[] = ["none", "warning", "high", "critical"];
+  const currentIndex = severityOrder.indexOf(severity);
+  const lastIndex = severityOrder.indexOf(state.lastSeverity);
+  if (currentIndex > lastIndex) {
+    return true;
+  }
+
+  // High and critical: no cooldown, always notify
+  if (severity === "high" || severity === "critical") {
+    return true;
+  }
+
+  // Warning: only notify if cooldown elapsed
+  if (severity === "warning") {
+    const elapsed = Date.now() - state.lastNotifiedAt;
+    return elapsed >= COOLDOWN_MS;
+  }
+
+  return false;
+}
+
+/**
+ * Updates alert state after notifying.
+ */
+export function markNotified(windowKey: string, severity: RiskSeverity): void {
+  windowAlerts.set(windowKey, {
+    lastSeverity: severity,
+    lastNotifiedAt: Date.now(),
+  });
+}
+
+/**
+ * Formats the warning message for the notification.
+ */
+export function formatWarningMessage(windows: WindowRisk[]): string {
+  const lines = windows.map(({ window, assessment }) => {
+    const status = assessment.severity;
+    const statusLabel = status !== "none" ? ` (${status})` : "";
+    const projected = Math.round(assessment.projectedPercent);
+    const used = Math.round(window.usedPercent);
+    const timeStr = formatTimeRemaining(window.resetsAt);
+    const eventStr = window.nextAmount
+      ? `${window.nextAmount} in ${timeStr}`
+      : `${window.nextLabel ?? "Resets"} in ${timeStr}`;
+    return `- ${window.label}: ${used}% used, projected ${projected}%${statusLabel}, ${eventStr}`;
+  });
+  return `Synthetic quota warning:\n${lines.join("\n")}`;
+}
+
+/**
+ * Clears the alert state and resets fetch tracking.
+ * Call on session start, model change, or shutdown.
+ */
+export function clearAlertState(): void {
+  windowAlerts.clear();
+  lastFetchAt = 0;
+}
+
+/**
+ * Checks quotas and shows a warning if above threshold.
+ * This is fire-and-forget - does not block the caller.
+ *
+ * @param skipAlreadyWarned - If true, only warn for windows that haven't been warned yet.
+ *                            If false, warn for all high usage windows (used on session start).
+ */
+export async function checkAndWarn(
+  ctx: ExtensionContext,
+  model: { provider: string; id: string } | undefined,
+  skipAlreadyWarned: boolean,
+): Promise<void> {
+  if (!ctx.hasUI) return;
+  if (model?.provider !== "synthetic") return;
+
+  const apiKey = await getSyntheticApiKey(ctx.modelRegistry.authStorage);
+  if (!apiKey) return;
+
+  // Throttle: skip if fetched recently, unless skipAlreadyWarned is false
+  // (session start / model change always fetches)
+  const now = Date.now();
+  if (skipAlreadyWarned && now - lastFetchAt < MIN_FETCH_INTERVAL_MS) {
+    return;
+  }
+
+  lastFetchAt = now;
+
+  try {
+    const result = await fetchQuotas(apiKey);
+    if (!result.success) return;
+
+    const highRiskWindows = findHighRiskWindows(result.data.quotas);
+    if (highRiskWindows.length === 0) return;
+
+    // Filter to only windows that should be notified
+    const windowsToNotify = skipAlreadyWarned
+      ? highRiskWindows.filter(({ window, assessment }) => {
+          return shouldNotify(window.label, assessment.severity);
+        })
+      : highRiskWindows;
+
+    if (windowsToNotify.length === 0) return;
+
+    // Mark only the windows that were actually notified
+    for (const { window, assessment } of windowsToNotify) {
+      markNotified(window.label, assessment.severity);
+    }
+
+    const message = formatWarningMessage(windowsToNotify);
+
+    // Determine severity based on highest projected usage
+    const hasCritical = windowsToNotify.some(
+      ({ assessment }) => assessment.severity === "critical",
+    );
+    const hasHigh = windowsToNotify.some(
+      ({ assessment }) => assessment.severity === "high",
+    );
+    const notifyLevel = hasCritical ? "error" : hasHigh ? "error" : "warning";
+
+    ctx.ui.notify(message, notifyLevel);
+  } catch {
+    // Silently ignore errors
+  }
+}
+
+/**
+ * Fire-and-forget wrapper that ensures the check is non-blocking.
+ *
+ * @param skipAlreadyWarned - If true, only warn for windows that haven't been warned yet.
+ */
+export function triggerCheck(
+  ctx: ExtensionContext,
+  model: { provider: string; id: string } | undefined,
+  skipAlreadyWarned: boolean,
+): void {
+  // Do not await - this is intentionally fire-and-forget
+  checkAndWarn(ctx, model, skipAlreadyWarned).catch(() => {
+    // Ignore errors
+  });
+}

package/src/utils/quotas-severity.test.ts

@@ -0,0 +1,278 @@
+import { assert, describe, expect, it } from "vitest";
+import {
+  assessWindow,
+  getPacePercent,
+  getProjectedPercent,
+  getSeverityColor,
+  parseCurrency,
+  type QuotaWindow,
+  safePercent,
+} from "./quotas-severity";
+
+// Helper to create a QuotaWindow with sensible defaults
+function makeWindow(
+  overrides: Partial<QuotaWindow> & Pick<QuotaWindow, "usedPercent">,
+): QuotaWindow {
+  const windowSeconds = overrides.windowSeconds ?? 3600;
+  // resetsAt defaults to 30 minutes from now (50% through a 1h window)
+  const resetsAt =
+    overrides.resetsAt ?? new Date(Date.now() + windowSeconds * 500);
+  return {
+    label: "Test Window",
+    resetsAt,
+    windowSeconds,
+    usedValue: 0,
+    limitValue: 100,
+    ...overrides,
+  };
+}
+
+describe("safePercent", () => {
+  it("returns 0 for zero/invalid limit", () => {
+    expect(safePercent(50, 0)).toBe(0);
+    expect(safePercent(50, -1)).toBe(0);
+    expect(safePercent(50, NaN)).toBe(0);
+    expect(safePercent(NaN, 100)).toBe(0);
+  });
+
+  it("computes correct percentage", () => {
+    expect(safePercent(50, 100)).toBe(50);
+    expect(safePercent(75, 100)).toBe(75);
+    expect(safePercent(1, 3)).toBeCloseTo(33.33);
+  });
+
+  it("clamps to 0-100", () => {
+    expect(safePercent(150, 100)).toBe(100);
+    expect(safePercent(-10, 100)).toBe(0);
+  });
+});
+
+describe("parseCurrency", () => {
+  it("parses dollar amounts", () => {
+    expect(parseCurrency("$1,234.56")).toBe(1234.56);
+    expect(parseCurrency("$10.00")).toBe(10);
+  });
+
+  it("returns 0 for invalid input", () => {
+    expect(parseCurrency("")).toBe(0);
+    expect(parseCurrency("abc")).toBe(0);
+  });
+});
+
+describe("getPacePercent", () => {
+  it("returns null for zero window", () => {
+    const w = makeWindow({ usedPercent: 50, windowSeconds: 0 });
+    expect(getPacePercent(w)).toBeNull();
+  });
+
+  it("returns ~50 for a window 50% elapsed", () => {
+    const w = makeWindow({
+      usedPercent: 50,
+      windowSeconds: 3600,
+      resetsAt: new Date(Date.now() + 1800 * 1000), // 30 min remaining
+    });
+    const pace = getPacePercent(w);
+    assert(pace, "pace should not be null");
+    expect(pace).toBeCloseTo(50, 0);
+  });
+
+  it("clamps to 0-100", () => {
+    const w = makeWindow({
+      usedPercent: 50,
+      windowSeconds: 3600,
+      resetsAt: new Date(Date.now() + 7200 * 1000), // way past
+    });
+    expect(getPacePercent(w)).toBe(0);
+  });
+});
+
+describe("getProjectedPercent", () => {
+  it("returns usedPercent when no pace", () => {
+    expect(getProjectedPercent(42, null)).toBe(42);
+  });
+
+  it("projects based on pace", () => {
+    // 50% used, 25% through window => projected 200%
+    expect(getProjectedPercent(50, 25)).toBe(200);
+  });
+
+  it("uses minimum pace of 5", () => {
+    // Very low pace should not blow up projection
+    expect(getProjectedPercent(1, 0)).toBe(20); // 1 / 5 * 100
+    expect(getProjectedPercent(1, 1)).toBe(20); // clamped to 5
+  });
+});
+
+describe("assessWindow", () => {
+  describe("no pace (showPace: false)", () => {
+    it("returns none for low usage", () => {
+      const w = makeWindow({ usedPercent: 10, showPace: false });
+      expect(assessWindow(w).severity).toBe("none");
+    });
+
+    it("returns warning at 80% projected", () => {
+      const w = makeWindow({ usedPercent: 85, showPace: false });
+      expect(assessWindow(w).severity).toBe("warning");
+    });
+
+    it("returns high at 90% projected", () => {
+      const w = makeWindow({ usedPercent: 92, showPace: false });
+      expect(assessWindow(w).severity).toBe("high");
+    });
+
+    it("returns critical at 100% projected", () => {
+      const w = makeWindow({ usedPercent: 100, showPace: false });
+      expect(assessWindow(w).severity).toBe("critical");
+    });
+
+    it("returns critical for limited window regardless of usage", () => {
+      const w = makeWindow({ usedPercent: 5, showPace: false, limited: true });
+      expect(assessWindow(w).severity).toBe("critical");
+    });
+  });
+
+  describe("with pace (showPace: true)", () => {
+    it("returns none when usage is low and pace is normal", () => {
+      const w = makeWindow({
+        usedPercent: 20,
+        showPace: true,
+        paceScale: 1,
+        windowSeconds: 3600,
+        resetsAt: new Date(Date.now() + 1800 * 1000), // 50% through
+      });
+      expect(assessWindow(w).severity).toBe("none");
+    });
+
+    it("returns warning when projected exceeds warn threshold", () => {
+      // 50% used, 50% through => projected 100%, well above warn at 50% progress (190)
+      // But usedFloor at 50% progress is 20.5, so 50% > 20.5 => passes floor check
+      const w = makeWindow({
+        usedPercent: 50,
+        showPace: true,
+        paceScale: 1,
+        windowSeconds: 3600,
+        resetsAt: new Date(Date.now() + 1800 * 1000),
+      });
+      const result = assessWindow(w);
+      // projected = 50 / 50 * 100 = 100
+      // At 50% progress: warn = 260 - (260-120)*0.5 = 190, high = 232.5, critical = 285
+      // 100 < 190 => none actually. Let me pick better numbers.
+      expect(result.severity).toBe("none");
+    });
+
+    it("returns warning when projected exceeds dynamic warn threshold", () => {
+      // 95% used, 50% through => projected 190%
+      // At 50% progress: warn = 190, so 190 >= 190 => warning
+      // usedFloor at 50% = 20.5, 95 >= 20.5 => passes
+      const w = makeWindow({
+        usedPercent: 95,
+        showPace: true,
+        paceScale: 1,
+        windowSeconds: 3600,
+        resetsAt: new Date(Date.now() + 1800 * 1000),
+      });
+      const result = assessWindow(w);
+      expect(result.severity).toBe("warning");
+    });
+
+    it("uses paceScale to normalize pace", () => {
+      // Weekly window with daily pace: paceScale = 1/7
+      // At 50% through the day (12h), raw pace = 50%, scaled = 50/7 ≈ 7.14%
+      // So progress ≈ 0.0714, projected = 95 / max(5, 7.14) * 100 ≈ 1330%
+      const w = makeWindow({
+        usedPercent: 95,
+        showPace: true,
+        paceScale: 1 / 7,
+        windowSeconds: 7 * 24 * 3600, // 1 week
+        resetsAt: new Date(Date.now() + 6 * 24 * 3600 * 1000), // 6 days remaining
+      });
+      const result = assessWindow(w);
+      // With paceScale applied, projected should be much higher
+      assert(result.pacePercent, "pacePercent should not be null");
+      expect(result.pacePercent).toBeLessThan(15); // scaled down
+      expect(result.projectedPercent).toBeGreaterThan(500);
+      expect(result.severity).toBe("critical");
+    });
+
+    it("does not use pace when showPace is false", () => {
+      // Same timestamps but showPace: false
+      const w = makeWindow({
+        usedPercent: 50,
+        showPace: false,
+        windowSeconds: 5 * 3600,
+        resetsAt: new Date(Date.now() + 2.5 * 3600 * 1000),
+      });
+      const result = assessWindow(w);
+      expect(result.pacePercent).toBeNull();
+      expect(result.progress).toBeNull();
+      // Static thresholds: 50% < 80 => none
+      expect(result.severity).toBe("none");
+    });
+
+    it("suppresses warning when usage is below usedFloor", () => {
+      // Early window: raw pace ~10%, with paceScale=1 => progress=0.1
+      // usedFloor at 10% progress = 33 - (33-8)*0.1 = 33 - 2.5 = 30.5
+      // If used = 15% (< 30.5), projected might exceed warn but floor blocks it
+      const w = makeWindow({
+        usedPercent: 15,
+        showPace: true,
+        paceScale: 1,
+        windowSeconds: 3600,
+        // 10% through: 54 min remaining
+        resetsAt: new Date(Date.now() + 54 * 60 * 1000),
+      });
+      const result = assessWindow(w);
+      // projected = 15 / 10 * 100 = 150, which exceeds warn at 10% progress (246)
+      // But usedFloor = 30.5, and 15 < 30.5 => suppressed
+      expect(result.severity).toBe("none");
+    });
+
+    it("allows warning when usage exceeds usedFloor", () => {
+      // Same timing but higher usage
+      const w = makeWindow({
+        usedPercent: 50,
+        showPace: true,
+        paceScale: 1,
+        windowSeconds: 3600,
+        resetsAt: new Date(Date.now() + 54 * 60 * 1000),
+      });
+      const result = assessWindow(w);
+      // projected = 50 / 10 * 100 = 500
+      // warn at 10% progress = 246, high = 282.5, critical = 357
+      // 500 >= 357 => critical, usedFloor = 30.5, 50 >= 30.5 => passes
+      expect(result.severity).toBe("critical");
+    });
+  });
+
+  describe("limited flag", () => {
+    it("overrides severity to critical even with low usage", () => {
+      const w = makeWindow({
+        usedPercent: 5,
+        showPace: false,
+        limited: true,
+      });
+      expect(assessWindow(w).severity).toBe("critical");
+    });
+
+    it("overrides severity to critical even with pace showing none", () => {
+      const w = makeWindow({
+        usedPercent: 5,
+        showPace: true,
+        paceScale: 1,
+        limited: true,
+        windowSeconds: 3600,
+        resetsAt: new Date(Date.now() + 54 * 60 * 1000),
+      });
+      expect(assessWindow(w).severity).toBe("critical");
+    });
+  });
+});
+
+describe("getSeverityColor", () => {
+  it("maps severity levels to display colors", () => {
+    expect(getSeverityColor("none")).toBe("success");
+    expect(getSeverityColor("warning")).toBe("warning");
+    expect(getSeverityColor("high")).toBe("error");
+    expect(getSeverityColor("critical")).toBe("error");
+  });
+});

package/src/utils/quotas-severity.ts

@@ -0,0 +1,272 @@
+import type { QuotasResponse } from "../types/quotas";
+
+export type RiskSeverity = "none" | "warning" | "high" | "critical";
+
+export interface QuotaWindow {
+  label: string;
+  usedPercent: number;
+  resetsAt: Date;
+  windowSeconds: number;
+  usedValue: number;
+  limitValue: number;
+  isCurrency?: boolean;
+  showPace?: boolean;
+  paceScale?: number;
+  limited?: boolean;
+  nextAmount?: string;
+  nextLabel?: string;
+}
+
+export interface WindowProjection {
+  pacePercent: number | null;
+  progress: number | null; // 0..1
+  projectedPercent: number; // 0..+
+  usedPercent: number;
+}
+
+export interface RiskAssessment extends WindowProjection {
+  usedFloorPercent: number | null;
+  warnProjectedPercent: number | null;
+  highProjectedPercent: number | null;
+  criticalProjectedPercent: number | null;
+  severity: RiskSeverity;
+}
+
+const MIN_PACE_PERCENT = 5;
+
+// Threshold interpolation points
+// Early window (0% progress) -> Late window (100% progress)
+const THRESHOLDS = {
+  usedFloor: { start: 33, end: 8 },
+  warnProjected: { start: 260, end: 120 },
+  highProjected: { start: 320, end: 145 },
+  criticalProjected: { start: 400, end: 170 },
+};
+
+function interpolate(start: number, end: number, progress: number): number {
+  const clampedProgress = Math.max(0, Math.min(1, progress));
+  return start + (end - start) * clampedProgress;
+}
+
+/** Safely compute percentage, guarding against division by zero */
+export function safePercent(used: number, limit: number): number {
+  if (!Number.isFinite(used) || !Number.isFinite(limit) || limit <= 0) return 0;
+  return Math.max(0, Math.min(100, (used / limit) * 100));
+}
+
+/** Parse currency string like "$1,234.56" to number */
+export function parseCurrency(value: string): number {
+  const n = Number(value.replace(/[^0-9.-]/g, ""));
+  return Number.isFinite(n) ? n : 0;
+}
+
+export function toWindows(quotas: QuotasResponse): QuotaWindow[] {
+  const windows: QuotaWindow[] = [];
+
+  if (quotas.weeklyTokenLimit) {
+    const { weeklyTokenLimit } = quotas;
+    const limitValue = parseCurrency(weeklyTokenLimit.maxCredits);
+    const remainingValue = parseCurrency(weeklyTokenLimit.remainingCredits);
+    windows.push({
+      label: "Credits / week",
+      usedPercent: Math.max(
+        0,
+        Math.min(100, 100 - weeklyTokenLimit.percentRemaining),
+      ),
+      resetsAt: new Date(weeklyTokenLimit.nextRegenAt),
+      windowSeconds: 24 * 60 * 60,
+      usedValue: limitValue - remainingValue,
+      limitValue,
+      isCurrency: true,
+      showPace: true,
+      paceScale: 1 / 7,
+      nextAmount: `+${weeklyTokenLimit.nextRegenCredits}`,
+      nextLabel: "Next regen",
+    });
+  }
+
+  if (quotas.rollingFiveHourLimit && quotas.rollingFiveHourLimit.max > 0) {
+    const { rollingFiveHourLimit } = quotas;
+    const used = rollingFiveHourLimit.max - rollingFiveHourLimit.remaining;
+    const tickAmount =
+      rollingFiveHourLimit.tickPercent * rollingFiveHourLimit.max;
+    windows.push({
+      label: "Requests / 5h",
+      usedPercent: safePercent(used, rollingFiveHourLimit.max),
+      resetsAt: new Date(rollingFiveHourLimit.nextTickAt),
+      windowSeconds: 5 * 60 * 60,
+      usedValue: Math.round(used),
+      limitValue: rollingFiveHourLimit.max,
+      showPace: false,
+      limited: rollingFiveHourLimit.limited,
+      nextAmount: `+${tickAmount.toFixed(1)}`,
+      nextLabel: "Next tick",
+    });
+  }
+
+  if (quotas.search?.hourly?.limit && quotas.search.hourly.limit > 0) {
+    const { hourly } = quotas.search;
+    windows.push({
+      label: "Search / hour",
+      usedPercent: safePercent(hourly.requests, hourly.limit),
+      resetsAt: new Date(hourly.renewsAt),
+      windowSeconds: 60 * 60,
+      usedValue: hourly.requests,
+      limitValue: hourly.limit,
+      showPace: true,
+      paceScale: 1,
+      nextLabel: "Resets",
+    });
+  }
+
+  if (quotas.freeToolCalls?.limit && quotas.freeToolCalls.limit > 0) {
+    windows.push({
+      label: "Free Tool Calls / day",
+      usedPercent: safePercent(
+        quotas.freeToolCalls.requests,
+        quotas.freeToolCalls.limit,
+      ),
+      resetsAt: new Date(quotas.freeToolCalls.renewsAt),
+      windowSeconds: 24 * 60 * 60,
+      usedValue: quotas.freeToolCalls.requests,
+      limitValue: quotas.freeToolCalls.limit,
+      showPace: true,
+      paceScale: 1,
+      nextLabel: "Resets",
+    });
+  }
+
+  return windows;
+}
+
+export function getPacePercent(window: QuotaWindow): number | null {
+  const totalMs = window.windowSeconds * 1000;
+  if (totalMs <= 0) return null;
+  const remainingMs = window.resetsAt.getTime() - Date.now();
+  const elapsedMs = totalMs - remainingMs;
+  return Math.max(0, Math.min(100, (elapsedMs / totalMs) * 100));
+}
+
+export function getProjectedPercent(
+  usedPercent: number,
+  pacePercent: number | null,
+): number {
+  if (pacePercent === null) return usedPercent;
+  const effectivePace = Math.max(MIN_PACE_PERCENT, pacePercent);
+  return Math.max(0, (usedPercent / effectivePace) * 100);
+}
+
+export function assessWindow(window: QuotaWindow): RiskAssessment {
+  // Respect showPace/paceScale: only compute pace when the window opts in,
+  // and apply paceScale to normalize (e.g. weekly windows scale daily pace by 1/7).
+  const rawPace = window.showPace ? getPacePercent(window) : null;
+  const pacePercent =
+    rawPace !== null ? rawPace * (window.paceScale ?? 1) : null;
+  const projectedPercent = getProjectedPercent(window.usedPercent, pacePercent);
+
+  // Calculate progress (0 to 1) through the window
+  let progress: number | null = null;
+  if (pacePercent !== null) {
+    progress = pacePercent / 100;
+  }
+
+  const base: WindowProjection = {
+    pacePercent,
+    progress,
+    projectedPercent,
+    usedPercent: window.usedPercent,
+  };
+
+  // Fallback when pace/progress unavailable: use static thresholds on projected only
+  if (progress === null) {
+    let severity: RiskSeverity = "none";
+    if (window.limited) {
+      severity = "critical";
+    } else if (projectedPercent >= 100) {
+      severity = "critical";
+    } else if (projectedPercent >= 90) {
+      severity = "high";
+    } else if (projectedPercent >= 80) {
+      severity = "warning";
+    }
+
+    return {
+      ...base,
+      usedFloorPercent: null,
+      warnProjectedPercent: 80,
+      highProjectedPercent: 90,
+      criticalProjectedPercent: 100,
+      severity,
+    };
+  }
+
+  // Dynamic thresholds based on window progress
+  const usedFloorPercent = interpolate(
+    THRESHOLDS.usedFloor.start,
+    THRESHOLDS.usedFloor.end,
+    progress,
+  );
+  const warnProjectedPercent = interpolate(
+    THRESHOLDS.warnProjected.start,
+    THRESHOLDS.warnProjected.end,
+    progress,
+  );
+  const highProjectedPercent = interpolate(
+    THRESHOLDS.highProjected.start,
+    THRESHOLDS.highProjected.end,
+    progress,
+  );
+  const criticalProjectedPercent = interpolate(
+    THRESHOLDS.criticalProjected.start,
+    THRESHOLDS.criticalProjected.end,
+    progress,
+  );
+
+  // Determine severity (hard-limited windows are always critical)
+  let severity: RiskSeverity = "none";
+  if (window.limited) {
+    severity = "critical";
+  } else if (window.usedPercent >= usedFloorPercent) {
+    if (projectedPercent >= criticalProjectedPercent) {
+      severity = "critical";
+    } else if (projectedPercent >= highProjectedPercent) {
+      severity = "high";
+    } else if (projectedPercent >= warnProjectedPercent) {
+      severity = "warning";
+    }
+  }
+
+  return {
+    ...base,
+    usedFloorPercent,
+    warnProjectedPercent,
+    highProjectedPercent,
+    criticalProjectedPercent,
+    severity,
+  };
+}
+
+export function formatTimeRemaining(date: Date): string {
+  const ms = date.getTime() - Date.now();
+  if (ms <= 0) return "now";
+  const totalMins = Math.ceil(ms / (1000 * 60));
+  const hours = Math.floor(totalMins / 60);
+  const mins = totalMins % 60;
+  if (hours >= 1) return mins > 0 ? `${hours}h${mins}m` : `${hours}h`;
+  const totalSecs = Math.ceil(ms / 1000);
+  return totalMins >= 1 ? `${totalMins}m` : `${totalSecs}s`;
+}
+
+export function getSeverityColor(
+  severity: RiskSeverity,
+): "success" | "warning" | "error" {
+  switch (severity) {
+    case "critical":
+    case "high":
+      return "error";
+    case "warning":
+      return "warning";
+    default:
+      return "success";
+  }
+}