@latentminds/pi-quotas 0.2.3 → 0.2.4

package/README.md

@@ -62,6 +62,7 @@ Use `/quotas:settings` to enable or disable:
 - Per-provider commands (`/anthropic:quotas`, `/codex:quotas`, `/github:quotas`, `/openrouter:quotas`, `/synthetic:quotas`)
 - Footer status widget
 - Quota warning notifications
+- **Defer to Synthetic** — when both pi-quotas and [pi-synthetic](https://www.npmjs.com/package/@aliou/pi-synthetic) are loaded, pi-quotas hides its own Synthetic footer to avoid showing duplicate quota information. Enabled by default; disable if you prefer to see both footers.
 
 Settings can be saved globally (`~/.pi/agent/extensions/quotas.json`) or per-project (`.pi/quotas.json`). Run `/reload` after changing command visibility.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latentminds/pi-quotas",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "license": "MIT",
   "type": "module",
   "private": false,

package/src/config.ts

@@ -9,7 +9,8 @@ export type QuotasFeatureId =
   | "quotasCommand"
   | "providerCommands"
   | "usageStatus"
-  | "quotaWarnings";
+  | "quotaWarnings"
+  | "deferToSynthetic";
 
 export const QUOTAS_EXTENSIONS_REQUEST_EVENT =
   "quotas:extensions:request" as const;
@@ -28,6 +29,8 @@ export interface QuotasConfig {
   providerCommands?: boolean;
   usageStatus?: boolean;
   quotaWarnings?: boolean;
+  /** When true and pi-synthetic's usage footer is active, hide pi-quotas' Synthetic footer. */
+  deferToSynthetic?: boolean;
 }
 
 export interface ResolvedQuotasConfig {
@@ -36,6 +39,7 @@ export interface ResolvedQuotasConfig {
   providerCommands: boolean;
   usageStatus: boolean;
   quotaWarnings: boolean;
+  deferToSynthetic: boolean;
 }
 
 const DEFAULT_CONFIG: ResolvedQuotasConfig = {
@@ -44,6 +48,7 @@ const DEFAULT_CONFIG: ResolvedQuotasConfig = {
   providerCommands: true,
   usageStatus: true,
   quotaWarnings: true,
+  deferToSynthetic: true,
 };
 
 let pendingMigrationNotice = false;
@@ -79,6 +84,7 @@ class QuotasConfigStore {
       providerCommands: input?.providerCommands ?? DEFAULT_CONFIG.providerCommands,
       usageStatus: input?.usageStatus ?? DEFAULT_CONFIG.usageStatus,
       quotaWarnings: input?.quotaWarnings ?? DEFAULT_CONFIG.quotaWarnings,
+      deferToSynthetic: input?.deferToSynthetic ?? DEFAULT_CONFIG.deferToSynthetic,
     };
   }
 
@@ -164,6 +170,11 @@ const FEATURE_META: Array<{
     label: "Quota warnings",
     description: "Toggle projected-usage warning notifications",
   },
+  {
+    id: "deferToSynthetic",
+    label: "Defer to Synthetic",
+    description: "When pi-synthetic is loaded, hide pi-quotas' Synthetic footer to avoid duplicates",
+  },
 ];
 
 export function registerQuotasSettings(
@@ -205,11 +216,11 @@ export function registerQuotasSettings(
 
         const feature = FEATURE_META.find((item) => selected.startsWith(item.label));
         if (!feature) continue;
-        if (!getLoadedFeatures().has(feature.id)) {
+        if (feature.id !== "deferToSynthetic" && !getLoadedFeatures().has(feature.id)) {
           ctx.ui.notify(`${feature.label} is not loaded by Pi in this session.`, "warning");
           continue;
         }
-        draft[feature.id] = !draft[feature.id];
+        (draft as unknown as Record<string, boolean>)[feature.id] = !(draft as unknown as Record<string, boolean>)[feature.id];
       }
     },
   });

package/src/extensions/usage-status/format-status.ts

@@ -37,6 +37,11 @@ const SHORT_LABELS: Record<string, string> = {
   "Daily": "daily",
   "Weekly": "weekly",
   "Monthly": "monthly",
+  // Synthetic labels (match pi-synthetic extension)
+  "Credits / week": "week",
+  "Requests / 5h": "5h",
+  "Search / hour": "search",
+  "Free Tool Calls / day": "tools",
 };
 
 /**
@@ -68,8 +73,19 @@ export function formatWindowStatus(theme: ThemeLike, w: WindowStatus): string {
   const labelColor = isAtRisk ? color : "dim";
   const labelText = theme.fg(labelColor, `${short}:`);
 
+  // Synthetic windows always use compact "remaining%" format
+  // to match the pi-synthetic extension display
+  const SYNTHETIC_LABELS = new Set([
+    "Credits / week", "Requests / 5h", "Search / hour", "Free Tool Calls / day",
+  ]);
+  const isSynthetic = SYNTHETIC_LABELS.has(w.label);
+
   let valueText: string;
-  if (w.label === "Spend cap") {
+  if (isSynthetic) {
+    // Compact format matching pi-synthetic: just remaining%
+    const remaining = Math.max(0, Math.min(100, Math.round(100 - w.usedPercent)));
+    valueText = theme.fg(color, `${remaining}%`);
+  } else if (w.label === "Spend cap") {
     valueText = theme.fg(color, w.limited ? "REACHED" : "OK");
   } else if (w.isCurrency && w.usedValue != null && w.limitValue != null) {
     // Tracking-only windows have limitValue=0, show just usage

package/src/extensions/usage-status/index.ts

@@ -9,6 +9,12 @@ import {
   type QuotasConfigUpdatedPayload,
   configLoader,
 } from "../../config.js";
+
+/** Event emitted by pi-synthetic when its usage-status extension registers. */
+const SYNTHETIC_EXTENSIONS_REGISTER_EVENT = "synthetic:extensions:register";
+interface SyntheticExtensionsRegisterPayload {
+  feature: string;
+}
 import {
   fetchProviderQuotas,
   isSupportedProvider,
@@ -152,10 +158,28 @@ export default async function (pi: ExtensionAPI) {
   await configLoader.load();
   const refresher = createStatusRefresher();
   let enabled = configLoader.getConfig().usageStatus;
+  let deferToSynthetic = configLoader.getConfig().deferToSynthetic;
   let currentContext: ExtensionContext | undefined;
 
+  /** Whether pi-synthetic's usage footer is active in this session. */
+  let syntheticUsageActive = false;
+
+  pi.events.on(SYNTHETIC_EXTENSIONS_REGISTER_EVENT, (data: unknown) => {
+    const { feature } = data as SyntheticExtensionsRegisterPayload;
+    if (feature === "usageStatus") {
+      syntheticUsageActive = true;
+      // If currently showing synthetic data, clear our footer
+      if (currentContext && enabled && deferToSynthetic && currentContext.model?.provider === "synthetic") {
+        currentContext.ui.setStatus(EXTENSION_ID, undefined);
+        refresher.stop();
+      }
+    }
+  });
+
   pi.events.on(QUOTAS_CONFIG_UPDATED_EVENT, (data: unknown) => {
-    enabled = (data as QuotasConfigUpdatedPayload).config.usageStatus;
+    const config = (data as QuotasConfigUpdatedPayload).config;
+    enabled = config.usageStatus;
+    deferToSynthetic = config.deferToSynthetic;
     if (!enabled) {
       refresher.stop(currentContext);
       return;
@@ -166,9 +190,21 @@ export default async function (pi: ExtensionAPI) {
     }
   });
 
+  /**
+   * Whether to suppress our footer because pi-synthetic is showing
+   * the same data for the Synthetic provider.
+   */
+  function shouldDeferToSynthetic(provider: string | undefined): boolean {
+    return deferToSynthetic && syntheticUsageActive && provider === "synthetic";
+  }
+
   pi.on("session_start", async (_event, ctx) => {
     currentContext = ctx;
     if (!enabled) return;
+    if (shouldDeferToSynthetic(ctx.model?.provider)) {
+      ctx.ui.setStatus(EXTENSION_ID, undefined);
+      return;
+    }
     refresher.start();
     await refresher.refreshFor(ctx);
   });
@@ -176,6 +212,7 @@ export default async function (pi: ExtensionAPI) {
   pi.on("turn_end", async (_event, ctx) => {
     currentContext = ctx;
     if (!enabled) return;
+    if (shouldDeferToSynthetic(ctx.model?.provider)) return;
     await refresher.refreshFor(ctx);
   });
 
@@ -185,11 +222,16 @@ export default async function (pi: ExtensionAPI) {
       refresher.stop(ctx);
       return;
     }
+    if (shouldDeferToSynthetic(ctx.model?.provider)) {
+      ctx.ui.setStatus(EXTENSION_ID, undefined);
+      return;
+    }
     await refresher.refreshFor(ctx);
   });
 
   pi.on("session_shutdown", async (_event, ctx) => {
     currentContext = undefined;
+    syntheticUsageActive = false;
     refresher.stop(ctx);
   });
 

package/src/providers/parse.test.ts

@@ -3,6 +3,7 @@ import { parseAnthropicUsage } from "./providers.js";
 import { parseCodexUsage } from "./providers.js";
 import { parseGitHubCopilotUsage } from "./providers.js";
 import { parseOpenRouterUsage } from "./providers.js";
+import { parseSyntheticUsage } from "./providers.js";
 
 describe("parseAnthropicUsage", () => {
   it("maps oauth usage response into quota windows", () => {
@@ -410,3 +411,133 @@ describe("parseOpenRouterUsage", () => {
     expect(windows.find((w) => w.label === "Monthly")).toBeDefined();
   });
 });
+
+describe("parseSyntheticUsage", () => {
+  it("parses a full API response with all windows", () => {
+    const windows = parseSyntheticUsage({
+      subscription: {
+        limit: 500,
+        requests: 0,
+        renewsAt: "2026-05-06T12:27:17.097Z",
+      },
+      search: {
+        hourly: {
+          limit: 250,
+          requests: 30,
+          renewsAt: "2026-05-06T08:27:17.097Z",
+        },
+      },
+      freeToolCalls: {
+        limit: 0,
+        requests: 0,
+        renewsAt: "2026-05-07T07:27:17.102Z",
+      },
+      weeklyTokenLimit: {
+        nextRegenAt: "2026-05-06T09:44:14.000Z",
+        percentRemaining: 96.39,
+        maxCredits: "$24.00",
+        remainingCredits: "$23.13",
+        nextRegenCredits: "$0.48",
+      },
+      rollingFiveHourLimit: {
+        nextTickAt: "2026-05-06T07:27:51.000Z",
+        tickPercent: 0.05,
+        remaining: 420,
+        max: 500,
+        limited: false,
+      },
+    });
+
+    // subscription is NOT a window (matching pi-synthetic extension)
+    expect(windows.find((w) => w.label === "Subscription")).toBeUndefined();
+
+    // weeklyTokenLimit: 100 - 96.39 = ~3.61%
+    const credits = windows.find((w) => w.label === "Credits / week");
+    expect(credits).toBeDefined();
+    expect(credits!.usedPercent).toBeCloseTo(3.61, 1);
+    expect(credits!.isCurrency).toBe(true);
+    expect(credits!.limitValue).toBe(24);
+    expect(credits!.usedValue).toBeCloseTo(0.87, 1);
+    expect(credits!.paceScale).toBe(1 / 7);
+    expect(credits!.nextAmount).toBe("+$0.48");
+
+    // rollingFiveHourLimit: (500-420)/500 = 16%
+    const fiveHour = windows.find((w) => w.label === "Requests / 5h");
+    expect(fiveHour).toBeDefined();
+    expect(fiveHour!.usedPercent).toBe(16);
+    expect(fiveHour!.usedValue).toBe(80);
+    expect(fiveHour!.limitValue).toBe(500);
+    expect(fiveHour!.limited).toBe(false);
+
+    // search hourly
+    const search = windows.find((w) => w.label === "Search / hour");
+    expect(search).toBeDefined();
+    expect(search!.usedPercent).toBeCloseTo(12, 0);
+    expect(search!.usedValue).toBe(30);
+    expect(search!.limitValue).toBe(250);
+
+    // freeToolCalls with limit=0 is NOT shown
+    expect(windows.find((w) => w.label === "Free Tool Calls / day")).toBeUndefined();
+  });
+
+  it("shows freeToolCalls when limit > 0", () => {
+    const windows = parseSyntheticUsage({
+      weeklyTokenLimit: {
+        nextRegenAt: "2026-05-06T09:44:14.000Z",
+        percentRemaining: 50,
+        maxCredits: "$10.00",
+        remainingCredits: "$5.00",
+        nextRegenCredits: "$0.50",
+      },
+      freeToolCalls: {
+        limit: 100,
+        requests: 25,
+        renewsAt: "2026-05-07T07:27:17.102Z",
+      },
+    });
+
+    const tools = windows.find((w) => w.label === "Free Tool Calls / day");
+    expect(tools).toBeDefined();
+    expect(tools!.usedPercent).toBe(25);
+  });
+
+  it("parses currency strings like $24.00 correctly", () => {
+    const windows = parseSyntheticUsage({
+      weeklyTokenLimit: {
+        nextRegenAt: "2026-05-06T09:44:14.000Z",
+        percentRemaining: 75,
+        maxCredits: "$1,234.56",
+        remainingCredits: "$925.92",
+        nextRegenCredits: "$12.34",
+      },
+    });
+
+    const credits = windows.find((w) => w.label === "Credits / week");
+    expect(credits).toBeDefined();
+    expect(credits!.limitValue).toBe(1234.56);
+    expect(credits!.usedValue).toBeCloseTo(308.64, 1);
+    expect(credits!.usedPercent).toBe(25); // 100 - 75
+  });
+
+  it("handles limited state", () => {
+    const windows = parseSyntheticUsage({
+      rollingFiveHourLimit: {
+        nextTickAt: "2026-05-06T07:27:51.000Z",
+        tickPercent: 100,
+        remaining: 0,
+        max: 500,
+        limited: true,
+      },
+    });
+
+    const fiveHour = windows.find((w) => w.label === "Requests / 5h");
+    expect(fiveHour).toBeDefined();
+    expect(fiveHour!.usedPercent).toBe(100);
+    expect(fiveHour!.limited).toBe(true);
+  });
+
+  it("returns empty array when no data", () => {
+    const windows = parseSyntheticUsage({});
+    expect(windows).toHaveLength(0);
+  });
+});

package/src/providers/providers.ts

@@ -353,26 +353,55 @@ export function parseOpenRouterUsage(data: any): QuotaWindow[] {
   return windows;
 }
 
+/** Parse currency strings like "$24.00" to a number */
+function parseCurrency(value: string): number {
+  const n = Number(value.replace(/[^0-9.-]/g, ""));
+  return Number.isFinite(n) ? n : 0;
+}
+
 export function parseSyntheticUsage(data: any): QuotaWindow[] {
   const windows: QuotaWindow[] = [];
 
-  // Subscription (requests)
-  if (data?.subscription) {
+  // Weekly token/credit limit (primary window for paid plans)
+  if (data?.weeklyTokenLimit) {
+    const { weeklyTokenLimit } = data.weeklyTokenLimit;
+    const limitValue = parseCurrency(data.weeklyTokenLimit.maxCredits);
+    const remainingValue = parseCurrency(data.weeklyTokenLimit.remainingCredits);
     windows.push({
       provider: "synthetic",
-      label: "Subscription",
-      usedPercent: safePercent(data.subscription.requests, data.subscription.limit),
-      resetsAt: parseDateish(data.subscription.renewsAt),
-      windowSeconds: 30 * 24 * 60 * 60,
-      usedValue: data.subscription.requests,
-      limitValue: data.subscription.limit,
+      label: "Credits / week",
+      usedPercent: Math.max(0, Math.min(100, 100 - data.weeklyTokenLimit.percentRemaining)),
+      resetsAt: parseDateish(data.weeklyTokenLimit.nextRegenAt),
+      windowSeconds: 24 * 60 * 60,
+      usedValue: limitValue - remainingValue,
+      limitValue,
+      isCurrency: true,
       showPace: true,
-      nextLabel: "Resets",
+      paceScale: 1 / 7,
+      nextAmount: `+${data.weeklyTokenLimit.nextRegenCredits}`,
+      nextLabel: "Next regen",
+    });
+  }
+
+  // Rolling 5-hour request limit
+  if (data?.rollingFiveHourLimit && data.rollingFiveHourLimit.max > 0) {
+    const used = data.rollingFiveHourLimit.max - data.rollingFiveHourLimit.remaining;
+    windows.push({
+      provider: "synthetic",
+      label: "Requests / 5h",
+      usedPercent: safePercent(used, data.rollingFiveHourLimit.max),
+      resetsAt: parseDateish(data.rollingFiveHourLimit.nextTickAt),
+      windowSeconds: 5 * 60 * 60,
+      usedValue: Math.round(used),
+      limitValue: data.rollingFiveHourLimit.max,
+      showPace: false,
+      limited: data.rollingFiveHourLimit.limited,
+      nextLabel: data.rollingFiveHourLimit.limited ? "Limited" : "Resets",
     });
   }
 
-  // Search hourly
-  if (data?.search?.hourly) {
+  // Search hourly (only if limit > 0)
+  if (data?.search?.hourly?.limit && data.search.hourly.limit > 0) {
     windows.push({
       provider: "synthetic",
       label: "Search / hour",
@@ -381,59 +410,27 @@ export function parseSyntheticUsage(data: any): QuotaWindow[] {
       windowSeconds: 60 * 60,
       usedValue: data.search.hourly.requests,
       limitValue: data.search.hourly.limit,
-      showPace: false,
+      showPace: true,
+      paceScale: 1,
       nextLabel: "Resets",
     });
   }
 
-  // Free tool calls
-  if (data?.freeToolCalls) {
+  // Free tool calls (only if limit > 0)
+  if (data?.freeToolCalls?.limit && data.freeToolCalls.limit > 0) {
     windows.push({
       provider: "synthetic",
-      label: "Free Tools",
+      label: "Free Tool Calls / day",
       usedPercent: safePercent(data.freeToolCalls.requests, data.freeToolCalls.limit),
       resetsAt: parseDateish(data.freeToolCalls.renewsAt),
-      windowSeconds: 30 * 24 * 60 * 60,
+      windowSeconds: 24 * 60 * 60,
       usedValue: data.freeToolCalls.requests,
       limitValue: data.freeToolCalls.limit,
       showPace: true,
+      paceScale: 1,
       nextLabel: "Resets",
     });
   }
 
-  // Weekly token limit
-  if (data?.weeklyTokenLimit) {
-    const maxCredits = parseFloat(data.weeklyTokenLimit.maxCredits) || 0;
-    const remainingCredits = parseFloat(data.weeklyTokenLimit.remainingCredits) || 0;
-    windows.push({
-      provider: "synthetic",
-      label: "Weekly Tokens",
-      usedPercent: data.weeklyTokenLimit.percentRemaining ?? safePercent(remainingCredits, maxCredits),
-      resetsAt: parseDateish(data.weeklyTokenLimit.nextRegenAt),
-      windowSeconds: 7 * 24 * 60 * 60,
-      usedValue: maxCredits - remainingCredits,
-      limitValue: maxCredits,
-      isCurrency: true,
-      showPace: true,
-      nextLabel: "Regen",
-    });
-  }
-
-  // Rolling 5-hour limit
-  if (data?.rollingFiveHourLimit) {
-    windows.push({
-      provider: "synthetic",
-      label: "5h Limit",
-      usedPercent: data.rollingFiveHourLimit.tickPercent,
-      resetsAt: parseDateish(data.rollingFiveHourLimit.nextTickAt),
-      windowSeconds: 5 * 60 * 60,
-      usedValue: data.rollingFiveHourLimit.max - data.rollingFiveHourLimit.remaining,
-      limitValue: data.rollingFiveHourLimit.max,
-      limited: data.rollingFiveHourLimit.limited,
-      showPace: false,
-      nextLabel: data.rollingFiveHourLimit.limited ? "Limited" : "Resets",
-    });
-  }
-
   return windows;
 }