@aliou/pi-synthetic 0.10.2 → 0.12.0

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
+  });
+}