@aliou/pi-synthetic 0.11.0 → 0.13.0

package/README.md

@@ -73,6 +73,28 @@ Check your API usage:
 /synthetic:quotas
 ```
 
+### Usage Status
+
+When a Synthetic model is active, the footer status bar shows live quota usage (e.g. `week:82% (↺in 3d) 5h:95%`). Colors follow the same severity assessment as quota warnings: green by default, yellow/red only when projected usage is at risk. The status auto-refreshes every 60 seconds and after each turn.
+
+### Quota Warnings
+
+The extension automatically notifies you when you approach or exceed your Synthetic API quotas. Notifications fire on severity transitions only (no repeated alerts for the same level) and use correct terminology (regen/tick/resets) with precise time formatting.
+
+- Escalation always notifies
+- `high` and `critical` levels have no cooldown
+- `warning` level has a 60-minute cooldown
+
+## Disabling Features
+
+Each feature (provider, web search, quotas command, usage status, quota warnings) is a separate Pi extension. You can disable individual features using `pi config`:
+
+```
+pi config extensions.disabled add @aliou/pi-synthetic/quota-warnings
+```
+
+This prevents the quota-warnings extension from loading while keeping the rest of pi-synthetic active. Replace `quota-warnings` with `web-search`, `command-quotas`, or `provider` to disable other features.
+
 ## Adding or Updating Models
 
 Models are hardcoded in `src/providers/models.ts`. To add or update models:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-synthetic",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -17,7 +17,10 @@
     "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/sub-bar-integration/index.ts",
+      "./src/extensions/quota-warnings/index.ts",
+      "./src/extensions/usage-status/index.ts"
     ],
     "video": "https://assets.aliou.me/pi-extensions/demos/pi-synthetic.mp4"
   },
@@ -33,6 +36,7 @@
     "@mariozechner/pi-tui": "0.61.0"
   },
   "dependencies": {
+    "@aliou/pi-utils-settings": "^0.13.0",
     "@aliou/pi-utils-ui": "^0.1.2"
   },
   "devDependencies": {

package/src/config.ts

@@ -0,0 +1,277 @@
+import {
+  ConfigLoader,
+  type Migration,
+  registerSettingsCommand,
+  type SettingsSection,
+} from "@aliou/pi-utils-settings";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { SettingItem } from "@mariozechner/pi-tui";
+import pkg from "../package.json" with { type: "json" };
+
+export type SyntheticFeatureId =
+  | "webSearch"
+  | "quotasCommand"
+  | "subBarIntegration"
+  | "usageStatus"
+  | "quotaWarnings";
+
+export const SYNTHETIC_EXTENSIONS_REQUEST_EVENT =
+  "synthetic:extensions:request" as const;
+
+export const SYNTHETIC_EXTENSIONS_REGISTER_EVENT =
+  "synthetic:extensions:register" as const;
+
+export interface SyntheticExtensionsRegisterPayload {
+  feature: SyntheticFeatureId;
+}
+
+/**
+ * Config schema version. Stamped on disk when the initial migration runs or
+ * when the config is seeded. Uses the package version; bumping the package
+ * does not retrigger migrations (we only run them when `configVersion` is
+ * missing), but it records which release first created the file.
+ */
+export const SYNTHETIC_CONFIG_VERSION: string = pkg.version;
+
+export interface SyntheticConfig {
+  configVersion?: string;
+  webSearch?: boolean;
+  quotasCommand?: boolean;
+  usageStatus?: boolean;
+  quotaWarnings?: boolean;
+  subBarIntegration?: boolean;
+}
+
+export interface ResolvedSyntheticConfig {
+  configVersion: string;
+  webSearch: boolean;
+  quotasCommand: boolean;
+  usageStatus: boolean;
+  quotaWarnings: boolean;
+  subBarIntegration: boolean;
+}
+
+const DEFAULT_CONFIG: ResolvedSyntheticConfig = {
+  configVersion: SYNTHETIC_CONFIG_VERSION,
+  webSearch: true,
+  quotasCommand: true,
+  usageStatus: false,
+  quotaWarnings: false,
+  subBarIntegration: true,
+};
+
+// Module-level flag set when the v1 migration runs or when the global config
+// is seeded for the first time. Consumed once by the provider extension to
+// display a one-time notice about the new settings UI.
+let pendingMigrationNotice = false;
+
+export function hasPendingMigrationNotice(): boolean {
+  return pendingMigrationNotice;
+}
+
+export function clearPendingMigrationNotice(): void {
+  pendingMigrationNotice = false;
+}
+
+function markMigrationNoticePending(): void {
+  pendingMigrationNotice = true;
+}
+
+const migrations: Migration<SyntheticConfig>[] = [
+  {
+    name: "seed-defaults",
+    shouldRun: (config) => config.configVersion === undefined,
+    run: (config) => {
+      markMigrationNoticePending();
+      return {
+        configVersion: SYNTHETIC_CONFIG_VERSION,
+        webSearch: config.webSearch ?? DEFAULT_CONFIG.webSearch,
+        quotasCommand: config.quotasCommand ?? DEFAULT_CONFIG.quotasCommand,
+        usageStatus: config.usageStatus ?? DEFAULT_CONFIG.usageStatus,
+        quotaWarnings: config.quotaWarnings ?? DEFAULT_CONFIG.quotaWarnings,
+        subBarIntegration:
+          config.subBarIntegration ?? DEFAULT_CONFIG.subBarIntegration,
+      };
+    },
+  },
+];
+
+const QUOTA_WARNING_THRESHOLDS_DESCRIPTION =
+  "Toggle warnings when your quotas reach thresholds. Thresholds: warning at 80% projected usage, high at 90%, critical at 100% for fixed windows; dynamic windows use adaptive projected thresholds based on window progress.";
+
+export const configLoader = new ConfigLoader<
+  SyntheticConfig,
+  ResolvedSyntheticConfig
+>("synthetic", DEFAULT_CONFIG, { migrations });
+
+/**
+ * Seed the global config file on first use. When no config file exists in
+ * any scope, this writes the current defaults (with configVersion) to the
+ * global scope and flags the migration notice as pending.
+ *
+ * Must be called after `configLoader.load()`.
+ */
+export async function seedSyntheticConfigIfMissing(): Promise<void> {
+  if (configLoader.hasConfig("global") || configLoader.hasConfig("local")) {
+    return;
+  }
+  markMigrationNoticePending();
+  try {
+    await configLoader.save("global", {
+      configVersion: SYNTHETIC_CONFIG_VERSION,
+      webSearch: DEFAULT_CONFIG.webSearch,
+      quotasCommand: DEFAULT_CONFIG.quotasCommand,
+      usageStatus: DEFAULT_CONFIG.usageStatus,
+      quotaWarnings: DEFAULT_CONFIG.quotaWarnings,
+      subBarIntegration: DEFAULT_CONFIG.subBarIntegration,
+    });
+  } catch {
+    // If the write fails, keep the notice pending so the user still sees it.
+  }
+}
+
+export const SYNTHETIC_CONFIG_UPDATED_EVENT =
+  "synthetic:config:updated" as const;
+
+export interface SyntheticConfigUpdatedPayload {
+  config: ResolvedSyntheticConfig;
+}
+
+export function emitSyntheticConfigUpdated(pi: ExtensionAPI): void {
+  pi.events.emit(SYNTHETIC_CONFIG_UPDATED_EVENT, {
+    config: configLoader.getConfig(),
+  });
+}
+
+export interface RegisterSyntheticSettingsOptions {
+  getLoadedFeatures: () => Set<SyntheticFeatureId>;
+}
+
+function featureRow(
+  id: SyntheticFeatureId,
+  label: string,
+  description: string,
+  configValue: boolean,
+  isLoaded: boolean,
+): SettingItem {
+  if (isLoaded) {
+    return {
+      id,
+      label,
+      description,
+      currentValue: configValue ? "enabled" : "disabled",
+      values: ["enabled", "disabled"],
+    };
+  }
+  return {
+    id,
+    label,
+    description: `${description} (Not loaded by Pi)`,
+    currentValue: "unavailable",
+    values: [],
+  };
+}
+
+export function registerSyntheticSettings(
+  pi: ExtensionAPI,
+  options: RegisterSyntheticSettingsOptions,
+): void {
+  const { getLoadedFeatures } = options;
+
+  registerSettingsCommand<SyntheticConfig, ResolvedSyntheticConfig>(pi, {
+    commandName: "synthetic:settings",
+    commandDescription: "Configure Synthetic extension settings",
+    title: "Synthetic Settings",
+    configStore: configLoader,
+    buildSections: (tabConfig, resolved): SettingsSection[] => {
+      const loaded = getLoadedFeatures();
+      const webSearch = tabConfig?.webSearch ?? resolved.webSearch;
+      const quotasCommand = tabConfig?.quotasCommand ?? resolved.quotasCommand;
+      const usageStatus = tabConfig?.usageStatus ?? resolved.usageStatus;
+      const quotaWarnings = tabConfig?.quotaWarnings ?? resolved.quotaWarnings;
+      const subBarIntegration =
+        tabConfig?.subBarIntegration ?? resolved.subBarIntegration;
+
+      const sections: SettingsSection[] = [];
+
+      sections.push(
+        {
+          label: "Tools",
+          items: [
+            featureRow(
+              "webSearch",
+              "Web Search",
+              "Toggle `synthetic_web_search`, a tool for searching online with zero data retention",
+              webSearch,
+              loaded.has("webSearch"),
+            ),
+          ],
+        },
+        {
+          label: "Quotas",
+          items: [
+            featureRow(
+              "quotasCommand",
+              "Quotas Command",
+              "Toggle the `/synthetic:quotas` command, showing your quotas at a glance",
+              quotasCommand,
+              loaded.has("quotasCommand"),
+            ),
+            featureRow(
+              "usageStatus",
+              "Usage widget",
+              "Toggle the usage widget, showing your usage at a glance",
+              usageStatus,
+              loaded.has("usageStatus"),
+            ),
+            featureRow(
+              "quotaWarnings",
+              "Quota Warnings",
+              QUOTA_WARNING_THRESHOLDS_DESCRIPTION,
+              quotaWarnings,
+              loaded.has("quotaWarnings"),
+            ),
+          ],
+        },
+        {
+          label: "Integration",
+          items: [
+            featureRow(
+              "subBarIntegration",
+              "pi-sub-bar integration",
+              "Integration with `@marckrenn/pi-sub-bar`",
+              subBarIntegration,
+              loaded.has("subBarIntegration"),
+            ),
+          ],
+        },
+      );
+
+      return sections;
+    },
+    onSettingChange: (id, newValue, config) => {
+      if (!getLoadedFeatures().has(id as SyntheticFeatureId)) {
+        return null;
+      }
+
+      const enabled = newValue === "enabled";
+      switch (id) {
+        case "webSearch":
+          return { ...config, webSearch: enabled };
+        case "quotasCommand":
+          return { ...config, quotasCommand: enabled };
+        case "usageStatus":
+          return { ...config, usageStatus: enabled };
+        case "quotaWarnings":
+          return { ...config, quotaWarnings: enabled };
+        case "subBarIntegration":
+          return { ...config, subBarIntegration: enabled };
+        default:
+          return null;
+      }
+    },
+    onSave: async () => {
+      emitSyntheticConfigUpdated(pi);
+    },
+  });
+}

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

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { configLoader } from "../../config";
 import { getSyntheticApiKey } from "../../lib/env";
 import { fetchQuotas } from "../../utils/quotas";
 import { QuotasComponent } from "./components/quotas-display";
@@ -10,6 +11,14 @@ export function registerQuotasCommand(pi: ExtensionAPI): void {
   pi.registerCommand("synthetic:quotas", {
     description: "Display Synthetic API usage quotas",
     handler: async (_args, ctx) => {
+      if (!configLoader.getConfig().quotasCommand) {
+        ctx.ui.notify(
+          "Synthetic quotas command is disabled. Restart Pi to unload the command after re-enabling or disabling it.",
+          "warning",
+        );
+        return;
+      }
+
       const apiKey = await getSyntheticApiKey(ctx.modelRegistry.authStorage);
       if (!apiKey) {
         ctx.ui.notify(MISSING_AUTH_MESSAGE, "warning");

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.
@@ -298,7 +150,6 @@ export class QuotasComponent implements Component {
         width,
       ),
     );
-    lines.push("");
 
     switch (this.state.type) {
       case "loading":
@@ -334,6 +185,8 @@ export class QuotasComponent implements Component {
     const windows = toWindows(quotas);
     const barWidth = Math.min(50, Math.max(20, contentWidth - 20));
 
+    lines.push("");
+
     for (const window of windows) {
       lines.push(...this.renderWindow(window, barWidth, maxWidth));
       lines.push("");
@@ -355,15 +208,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 +221,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 +230,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/command-quotas/index.ts

@@ -1,8 +1,23 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  configLoader,
+  SYNTHETIC_EXTENSIONS_REGISTER_EVENT,
+  SYNTHETIC_EXTENSIONS_REQUEST_EVENT,
+} from "../../config";
 import { registerQuotasCommand } from "./command";
-import { registerSubIntegration } from "./sub-integration";
 
 export default async function (pi: ExtensionAPI) {
-  registerQuotasCommand(pi);
-  registerSubIntegration(pi);
+  await configLoader.load();
+
+  const config = configLoader.getConfig();
+
+  if (config.quotasCommand) {
+    registerQuotasCommand(pi);
+  }
+
+  pi.events.on(SYNTHETIC_EXTENSIONS_REQUEST_EVENT, () => {
+    pi.events.emit(SYNTHETIC_EXTENSIONS_REGISTER_EVENT, {
+      feature: "quotasCommand",
+    });
+  });
 }