@aliou/pi-synthetic 0.14.0 → 0.16.0

package/src/services/quota-store.ts

@@ -0,0 +1,112 @@
+import type { QuotaSource, QuotasResponse } from "../types/quotas";
+
+export interface QuotaSnapshot {
+  quotas: QuotasResponse;
+  source: QuotaSource;
+  updatedAt: number; // epoch ms
+}
+
+type Listener = (snapshot: QuotaSnapshot) => void;
+
+/**
+ * Pi-agnostic in-memory quota store.
+ *
+ * Ingests quota data from headers or API, handles throttling of
+ * header-sourced updates, and notifies subscribers on change.
+ *
+ * Usage:
+ *   const store = new QuotaStore();
+ *   store.subscribe((snap) => { ... });
+ *   store.ingest(quotas, "header");
+ *   store.ingest(quotas, "api");
+ */
+export class QuotaStore {
+  private snapshot: QuotaSnapshot | undefined;
+  private listeners = new Set<Listener>();
+  private lastHeaderIngestAt = 0;
+  private inFlightRefresh: Promise<QuotaSnapshot | undefined> | undefined;
+  private inFlightId = 0;
+
+  /** Throttle header ingestion: skip if last header ingest was within this window. */
+  headerThrottleMs = 5_000;
+
+  /** Current snapshot (may be undefined if no data has been ingested yet). */
+  getSnapshot(): QuotaSnapshot | undefined {
+    return this.snapshot;
+  }
+
+  /** Subscribe to snapshot updates. Returns unsubscribe function. */
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private emit(snapshot: QuotaSnapshot): void {
+    for (const l of this.listeners) l(snapshot);
+  }
+
+  /**
+   * Ingest quota data. Returns true if the snapshot was updated
+   * (i.e. not throttled).
+   *
+   * Header-sourced data is throttled: if the last header ingest was
+   * within `headerThrottleMs`, it is silently dropped.
+   * API-sourced data always goes through.
+   */
+  ingest(quotas: QuotasResponse, source: QuotaSource): boolean {
+    const now = Date.now();
+
+    if (source === "header") {
+      if (now - this.lastHeaderIngestAt < this.headerThrottleMs) return false;
+      this.lastHeaderIngestAt = now;
+    }
+
+    this.snapshot = { quotas, source, updatedAt: now };
+    this.emit(this.snapshot);
+    return true;
+  }
+
+  /**
+   * Refresh quotas by calling the provided fetcher.
+   * Deduplicates concurrent calls — only one fetch runs at a time.
+   */
+  async refreshFromApi(
+    fetcher: () => Promise<QuotasResponse | undefined>,
+  ): Promise<QuotaSnapshot | undefined> {
+    if (this.inFlightRefresh) return this.inFlightRefresh;
+
+    this.inFlightId++;
+    const id = this.inFlightId;
+
+    this.inFlightRefresh = (async () => {
+      try {
+        const quotas = await fetcher();
+        if (quotas && id === this.inFlightId) {
+          this.ingest(quotas, "api");
+        }
+        return this.snapshot;
+      } finally {
+        if (id === this.inFlightId) {
+          this.inFlightRefresh = undefined;
+        }
+      }
+    })();
+
+    return this.inFlightRefresh;
+  }
+
+  /** Returns true if a refresh is currently in flight. */
+  get isRefreshing(): boolean {
+    return !!this.inFlightRefresh;
+  }
+
+  /** Clear all state. Call on session shutdown or reset. */
+  clear(): void {
+    this.inFlightId++; // Invalidates in-flight refresh
+    this.snapshot = undefined;
+    this.lastHeaderIngestAt = 0;
+    this.inFlightRefresh = undefined;
+  }
+}

package/src/services/quota-warnings.test.ts

@@ -0,0 +1,393 @@
+import {
+  afterEach,
+  assert,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+import type { QuotasResponse } from "../types/quotas";
+import { assessWindow, type QuotaWindow } from "../utils/quotas-severity";
+import { type NotifyFn, QuotaWarningNotifier } from "./quota-warnings";
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("QuotaWarningNotifier", () => {
+  const baseQuotas: QuotasResponse = {
+    weeklyTokenLimit: {
+      nextRegenAt: new Date(Date.now() + 6 * 24 * 3600 * 1000).toISOString(),
+      percentRemaining: 90,
+      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,
+        renewsAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
+      },
+    },
+    freeToolCalls: {
+      limit: 100,
+      requests: 5,
+      renewsAt: new Date(Date.now() + 12 * 3600 * 1000).toISOString(),
+    },
+  };
+
+  describe("shouldNotify", () => {
+    it("notifies on first time seeing a window at risk", () => {
+      const notifier = new QuotaWarningNotifier();
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(true);
+      expect(notifier.shouldNotify("Requests / 5h", "high")).toBe(true);
+      expect(notifier.shouldNotify("Search / hour", "critical")).toBe(true);
+    });
+
+    it("notifies on severity escalation", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Credits / week", "warning");
+      expect(notifier.shouldNotify("Credits / week", "high")).toBe(true);
+
+      notifier.markNotified("Requests / 5h", "high");
+      expect(notifier.shouldNotify("Requests / 5h", "critical")).toBe(true);
+    });
+
+    it("notifies on skip from none to any risk level", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Test", "none");
+      expect(notifier.shouldNotify("Test", "warning")).toBe(true);
+    });
+
+    it("does not notify on same severity for warning within cooldown", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Credits / week", "warning");
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(false);
+    });
+
+    it("does notify on warning after cooldown elapsed", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Credits / week", "warning");
+
+      vi.advanceTimersByTime(60 * 60 * 1000 + 1);
+
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(true);
+    });
+
+    it("does not notify on downgrade to warning", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Credits / week", "high");
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(false);
+    });
+
+    it("does notify on downgrade to high (no cooldown)", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Requests / 5h", "critical");
+      expect(notifier.shouldNotify("Requests / 5h", "high")).toBe(true);
+    });
+
+    it("always notifies for high severity (no cooldown)", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Credits / week", "high");
+      expect(notifier.shouldNotify("Credits / week", "high")).toBe(true);
+    });
+
+    it("always notifies for critical severity (no cooldown)", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Credits / week", "critical");
+      expect(notifier.shouldNotify("Credits / week", "critical")).toBe(true);
+    });
+  });
+
+  describe("markNotified", () => {
+    it("tracks severity per window key", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Credits / week", "warning");
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(false);
+
+      // Different key is independent
+      expect(notifier.shouldNotify("Requests / 5h", "warning")).toBe(true);
+    });
+
+    it("allows re-notification after escalation then downgrade then re-escalation", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Test", "high");
+      expect(notifier.shouldNotify("Test", "warning")).toBe(false);
+      expect(notifier.shouldNotify("Test", "high")).toBe(true);
+    });
+  });
+
+  describe("clearAlertState", () => {
+    it("resets all alert state so windows notify again", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Credits / week", "warning");
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(false);
+
+      notifier.clearAlertState();
+
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(true);
+    });
+  });
+
+  describe("findHighRiskWindows", () => {
+    it("returns empty for low-usage quotas", () => {
+      const notifier = new QuotaWarningNotifier();
+      const risks = notifier.findHighRiskWindows(baseQuotas);
+      expect(risks).toHaveLength(0);
+    });
+
+    it("finds windows with high usage", () => {
+      const notifier = new QuotaWarningNotifier();
+      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 = notifier.findHighRiskWindows(quotas);
+      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 notifier = new QuotaWarningNotifier();
+      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 = notifier.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 notifier = new QuotaWarningNotifier();
+      expect(notifier.findHighRiskWindows({})).toHaveLength(0);
+    });
+  });
+
+  describe("formatWarningMessage", () => {
+    it("formats single window warning", () => {
+      const notifier = new QuotaWarningNotifier();
+      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 = notifier.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 notifier = new QuotaWarningNotifier();
+      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 = notifier.formatWarningMessage([
+        { window: w1, assessment: assessWindow(w1) },
+        { window: w2, assessment: assessWindow(w2) },
+      ]);
+      expect(msg).toContain("Credits / week");
+      expect(msg).toContain("Requests / 5h");
+      const lines = msg.split("\n");
+      expect(lines).toHaveLength(3); // header + 2 windows
+    });
+
+    it("includes severity label for non-none severities", () => {
+      const notifier = new QuotaWarningNotifier();
+      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 = notifier.formatWarningMessage([
+        { window: w, assessment: assessWindow(w) },
+      ]);
+      expect(msg).toMatch(/\(high\)/);
+    });
+  });
+
+  describe("evaluate", () => {
+    it("does not notify for low-usage quotas", () => {
+      const notifier = new QuotaWarningNotifier();
+      const calls: Array<[string, string]> = [];
+      const notify: NotifyFn = (msg, lvl) => calls.push([msg, lvl]);
+
+      notifier.evaluate(baseQuotas, false, notify);
+      expect(calls).toHaveLength(0);
+    });
+
+    it("notifies for high-usage quotas with skipAlreadyWarned=false", () => {
+      const notifier = new QuotaWarningNotifier();
+      const calls: Array<[string, string]> = [];
+      const notify: NotifyFn = (msg, lvl) => calls.push([msg, lvl]);
+
+      const highUsageQuotas: QuotasResponse = {
+        ...baseQuotas,
+        rollingFiveHourLimit: {
+          nextTickAt: new Date(Date.now() + 2.5 * 3600 * 1000).toISOString(),
+          tickPercent: 10,
+          remaining: 5,
+          max: 100,
+          limited: false,
+        },
+      };
+
+      notifier.evaluate(highUsageQuotas, false, notify);
+      expect(calls).toHaveLength(1);
+      expect(calls[0][0]).toContain("Synthetic quota warning");
+    });
+
+    it("does not re-notify on same severity with skipAlreadyWarned=true", () => {
+      const notifier = new QuotaWarningNotifier();
+      const calls: Array<[string, string]> = [];
+      const notify: NotifyFn = (msg, lvl) => calls.push([msg, lvl]);
+
+      // 85% used (no pace) → warning severity, which has cooldown
+      const warningQuotas: QuotasResponse = {
+        ...baseQuotas,
+        rollingFiveHourLimit: {
+          nextTickAt: new Date(Date.now() + 2.5 * 3600 * 1000).toISOString(),
+          tickPercent: 10,
+          remaining: 15,
+          max: 100,
+          limited: false,
+        },
+      };
+
+      notifier.evaluate(warningQuotas, true, notify);
+      expect(calls).toHaveLength(1);
+
+      // Same severity, same data — should not re-notify (warning has cooldown)
+      notifier.evaluate(warningQuotas, true, notify);
+      expect(calls).toHaveLength(1);
+    });
+
+    it("notifies on severity escalation even with skipAlreadyWarned=true", () => {
+      const notifier = new QuotaWarningNotifier();
+      const calls: Array<[string, string]> = [];
+      const notify: NotifyFn = (msg, lvl) => calls.push([msg, lvl]);
+
+      // 92% used (no pace) → high severity
+      const highQuotas: QuotasResponse = {
+        ...baseQuotas,
+        rollingFiveHourLimit: {
+          nextTickAt: new Date(Date.now() + 2.5 * 3600 * 1000).toISOString(),
+          tickPercent: 10,
+          remaining: 8,
+          max: 100,
+          limited: false,
+        },
+      };
+
+      notifier.evaluate(highQuotas, true, notify);
+      expect(calls).toHaveLength(1);
+
+      // Escalate to critical (limited)
+      const criticalQuotas: QuotasResponse = {
+        ...baseQuotas,
+        rollingFiveHourLimit: {
+          nextTickAt: new Date(Date.now() + 2.5 * 3600 * 1000).toISOString(),
+          tickPercent: 10,
+          remaining: 2,
+          max: 100,
+          limited: true,
+        },
+      };
+
+      notifier.evaluate(criticalQuotas, true, notify);
+      expect(calls).toHaveLength(2);
+      expect(calls[1][1]).toBe("error");
+    });
+  });
+
+  describe("notification flow (shouldNotify + markNotified integration)", () => {
+    it("notifies once on first warning, blocks repeat, notifies on escalation", () => {
+      const notifier = new QuotaWarningNotifier();
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(true);
+      notifier.markNotified("Credits / week", "warning");
+
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(false);
+
+      expect(notifier.shouldNotify("Credits / week", "high")).toBe(true);
+      notifier.markNotified("Credits / week", "high");
+
+      expect(notifier.shouldNotify("Credits / week", "high")).toBe(true);
+    });
+
+    it("allows re-notification after clear", () => {
+      const notifier = new QuotaWarningNotifier();
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(true);
+      notifier.markNotified("Credits / week", "warning");
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(false);
+
+      notifier.clearAlertState();
+
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(true);
+    });
+
+    it("tracks windows independently", () => {
+      const notifier = new QuotaWarningNotifier();
+      notifier.markNotified("Credits / week", "warning");
+      expect(notifier.shouldNotify("Credits / week", "warning")).toBe(false);
+      expect(notifier.shouldNotify("Search / hour", "warning")).toBe(true);
+    });
+  });
+});

package/src/services/quota-warnings.ts

@@ -0,0 +1,149 @@
+import type { QuotasResponse } from "../types/quotas";
+import {
+  assessWindow,
+  formatTimeRemaining,
+  type QuotaWindow,
+  type RiskAssessment,
+  type RiskSeverity,
+  toWindows,
+} from "../utils/quotas-severity";
+
+const COOLDOWN_MS = 60 * 60 * 1000; // 60 minutes
+
+export interface WindowAlertState {
+  lastSeverity: RiskSeverity;
+  lastNotifiedAt: number; // epoch ms
+}
+
+interface WindowRisk {
+  window: QuotaWindow;
+  assessment: RiskAssessment;
+}
+
+export type NotifyFn = (message: string, level: "warning" | "error") => void;
+
+/**
+ * Pi-agnostic quota warning evaluator.
+ *
+ * Call `evaluate()` with a QuotasResponse and it decides whether
+ * to fire a notification based on severity, escalation, and cooldown rules.
+ *
+ * Usage:
+ *   const notifier = new QuotaWarningNotifier();
+ *   notifier.evaluate(quotas, true, (msg, lvl) => ctx.ui.notify(msg, lvl));
+ */
+export class QuotaWarningNotifier {
+  private windowAlerts = new Map<string, WindowAlertState>();
+
+  /** Finds windows that exceed the risk threshold. */
+  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)
+   */
+  shouldNotify(windowKey: string, severity: RiskSeverity): boolean {
+    const state = this.windowAlerts.get(windowKey);
+
+    if (!state) return true;
+
+    const severityOrder: RiskSeverity[] = [
+      "none",
+      "warning",
+      "high",
+      "critical",
+    ];
+    const currentIndex = severityOrder.indexOf(severity);
+    const lastIndex = severityOrder.indexOf(state.lastSeverity);
+    if (currentIndex > lastIndex) return true;
+
+    if (severity === "high" || severity === "critical") return true;
+
+    if (severity === "warning") {
+      return Date.now() - state.lastNotifiedAt >= COOLDOWN_MS;
+    }
+
+    return false;
+  }
+
+  /** Updates alert state after notifying. */
+  markNotified(windowKey: string, severity: RiskSeverity): void {
+    this.windowAlerts.set(windowKey, {
+      lastSeverity: severity,
+      lastNotifiedAt: Date.now(),
+    });
+  }
+
+  /** Formats the warning message for the notification. */
+  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")}`;
+  }
+
+  /** Clear all alert state. Call on session start, model change, or shutdown. */
+  clearAlertState(): void {
+    this.windowAlerts.clear();
+  }
+
+  /**
+   * Evaluate a QuotasResponse and notify if thresholds are exceeded.
+   *
+   * @param quotas - The quota data to evaluate
+   * @param skipAlreadyWarned - If true, only warn for windows not yet warned.
+   *                            If false, warn for all high-usage windows.
+   * @param notify - Callback to display the notification
+   */
+  evaluate(
+    quotas: QuotasResponse,
+    skipAlreadyWarned: boolean,
+    notify: NotifyFn,
+  ): void {
+    const highRiskWindows = this.findHighRiskWindows(quotas);
+    if (highRiskWindows.length === 0) return;
+
+    const windowsToNotify = skipAlreadyWarned
+      ? highRiskWindows.filter(({ window, assessment }) =>
+          this.shouldNotify(window.label, assessment.severity),
+        )
+      : highRiskWindows;
+
+    if (windowsToNotify.length === 0) return;
+
+    for (const { window, assessment } of windowsToNotify) {
+      this.markNotified(window.label, assessment.severity);
+    }
+
+    const message = this.formatWarningMessage(windowsToNotify);
+
+    const hasCritical = windowsToNotify.some(
+      ({ assessment }) => assessment.severity === "critical",
+    );
+    const hasHigh = windowsToNotify.some(
+      ({ assessment }) => assessment.severity === "high",
+    );
+    const notifyLevel = hasCritical || hasHigh ? "error" : "warning";
+
+    notify(message, notifyLevel);
+  }
+}

package/src/types/quotas.ts

@@ -1,3 +1,30 @@
+export type QuotaSource = "header" | "api";
+
+export const SYNTHETIC_QUOTAS_UPDATED_EVENT =
+  "synthetic:quotas:updated" as const;
+
+export const SYNTHETIC_QUOTAS_REQUEST_EVENT =
+  "synthetic:quotas:request" as const;
+
+export const SYNTHETIC_QUOTAS_READ_EVENT = "synthetic:quotas:read" as const;
+
+export interface SyntheticQuotasSnapshotPayload {
+  quotas: QuotasResponse;
+  source: QuotaSource;
+  updatedAt: number;
+}
+
+export interface SyntheticQuotasUpdatedPayload
+  extends SyntheticQuotasSnapshotPayload {}
+
+export interface SyntheticQuotasReadPayload {
+  respond: (snapshot: SyntheticQuotasSnapshotPayload | undefined) => void;
+}
+
+export interface SyntheticQuotasRequestPayload {
+  respond?: (snapshot: SyntheticQuotasSnapshotPayload | undefined) => void;
+}
+
 export type QuotasErrorKind =
   | "cancelled"
   | "timeout"
@@ -42,3 +69,23 @@ export interface QuotasResponse {
     limited: boolean;
   };
 }
+
+/** Parse the `x-synthetic-quotas` header value into a QuotasResponse.
+ *  Returns undefined if the header is missing or invalid. */
+export function parseQuotaHeader(
+  headers: Record<string, string>,
+): QuotasResponse | undefined {
+  const entry = Object.entries(headers).find(
+    ([key]) => key.toLowerCase() === "x-synthetic-quotas",
+  );
+  if (!entry?.[1]) return undefined;
+  try {
+    const parsed = JSON.parse(entry[1]);
+    // Basic structural check: must be a non-null object
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+      return undefined;
+    return parsed as QuotasResponse;
+  } catch {
+    return undefined;
+  }
+}