@aliou/pi-synthetic 0.8.4 → 0.9.0

package/README.md

@@ -8,18 +8,27 @@ A Pi extension that adds [Synthetic](https://synthetic.new) as a model provider,
 
 Sign up at [synthetic.new](https://synthetic.new/?referral=NDWw1u3UDWiFyDR) to get an API key (referral link).
 
-### Set Environment Variable
+### Configure Credentials
 
-```bash
-export SYNTHETIC_API_KEY="your-api-key-here"
+The extension uses Pi's credential storage. Add your API key to `~/.pi/agent/auth.json` (recommended):
+
+```json
+{
+  "synthetic": { "type": "api_key", "key": "your-api-key-here" }
+}
 ```
 
-Add to shell profile for persistence:
+Or set environment variable:
 
 ```bash
-echo 'export SYNTHETIC_API_KEY="your-api-key-here"' >> ~/.zshrc
+export SYNTHETIC_API_KEY="your-api-key-here"
 ```
 
+Credentials are resolved in this order:
+1. CLI `--api-key` flag
+2. `auth.json` entry for `synthetic`
+3. Environment variable `SYNTHETIC_API_KEY`
+
 ### Install Extension
 
 ```bash
@@ -43,7 +52,7 @@ Once installed, select `synthetic` as your provider and choose from available mo
 
 ### Web Search Tool
 
-The extension registers `synthetic_web_search` — a zero-data-retention web search tool. Available when you have an active Synthetic subscription.
+The extension registers `synthetic_web_search` — a zero-data-retention web search tool. The tool is always visible; it fails with a clear message if credentials are missing or the account lacks a subscription.
 
 ### Reasoning Levels
 
@@ -124,7 +133,7 @@ This repository uses [Changesets](https://github.com/changesets/changesets) for
 ## Requirements
 
 - Pi coding agent v0.50.0+
-- SYNTHETIC_API_KEY environment variable
+- Synthetic API key (configured in `~/.pi/agent/auth.json` or via `SYNTHETIC_API_KEY`)
 
 ## Links
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-synthetic",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -15,7 +15,9 @@
   },
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./src/extensions/provider/index.ts",
+      "./src/extensions/web-search/index.ts",
+      "./src/extensions/command-quotas/index.ts"
     ],
     "video": "https://assets.aliou.me/pi-extensions/demos/pi-synthetic.mp4"
   },
@@ -34,7 +36,7 @@
     "@aliou/pi-utils-ui": "^0.1.2"
   },
   "devDependencies": {
-    "@aliou/biome-plugins": "^0.3.2",
+    "@aliou/biome-plugins": "^0.7.0",
     "@biomejs/biome": "^2.4.2",
     "@changesets/cli": "^2.27.11",
     "@mariozechner/pi-coding-agent": "0.61.0",

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

@@ -0,0 +1,65 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { getSyntheticApiKey } from "../../lib/env";
+import { fetchQuotas } from "../../utils/quotas";
+import { QuotasComponent } from "./components/quotas-display";
+
+const MISSING_AUTH_MESSAGE =
+  "Synthetic quotas requires a Synthetic subscription. Add credentials to ~/.pi/agent/auth.json or set SYNTHETIC_API_KEY environment variable.";
+
+export function registerQuotasCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("synthetic:quotas", {
+    description: "Display Synthetic API usage quotas",
+    handler: async (_args, ctx) => {
+      const apiKey = await getSyntheticApiKey(ctx.modelRegistry.authStorage);
+      if (!apiKey) {
+        ctx.ui.notify(MISSING_AUTH_MESSAGE, "warning");
+        return;
+      }
+
+      const result = await ctx.ui.custom<null>((tui, theme, _kb, done) => {
+        const component = new QuotasComponent(theme, () => done(null));
+
+        fetchQuotas(apiKey)
+          .then((quotas) => {
+            if (!quotas) {
+              component.setState({
+                type: "error",
+                message:
+                  "Failed to fetch quotas. Check your Synthetic subscription status.",
+              });
+            } else {
+              component.setState({ type: "loaded", quotas });
+            }
+            tui.requestRender();
+          })
+          .catch(() => {
+            component.setState({
+              type: "error",
+              message:
+                "Failed to fetch quotas. Check your Synthetic subscription status.",
+            });
+            tui.requestRender();
+          });
+
+        return {
+          render: (width: number) => component.render(width),
+          invalidate: () => component.invalidate(),
+          handleInput: (data: string) => component.handleInput(data),
+        };
+      });
+
+      // RPC fallback: return JSON
+      if (result === undefined) {
+        const quotas = await fetchQuotas(apiKey);
+        if (!quotas) {
+          ctx.ui.notify(
+            JSON.stringify({ error: "Failed to fetch quotas" }),
+            "error",
+          );
+          return;
+        }
+        ctx.ui.notify(JSON.stringify(quotas, null, 2), "info");
+      }
+    },
+  });
+}

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

@@ -0,0 +1,314 @@
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { DynamicBorder } from "@mariozechner/pi-coding-agent";
+import type { Component } from "@mariozechner/pi-tui";
+import {
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+} from "@mariozechner/pi-tui";
+import type { QuotasResponse } from "../../../types/quotas";
+
+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;
+}
+
+function toWindows(quotas: QuotasResponse): QuotaWindow[] {
+  const windows: QuotaWindow[] = [];
+
+  if (quotas.subscription.limit > 0) {
+    windows.push({
+      label: "Completions",
+      usedPercent:
+        (quotas.subscription.requests / quotas.subscription.limit) * 100,
+      resetsAt: new Date(quotas.subscription.renewsAt),
+      windowSeconds: 5 * 60 * 60,
+      usedValue: quotas.subscription.requests,
+      limitValue: quotas.subscription.limit,
+    });
+  }
+
+  if (quotas.search.hourly.limit > 0) {
+    windows.push({
+      label: "Search",
+      usedPercent:
+        (quotas.search.hourly.requests / quotas.search.hourly.limit) * 100,
+      resetsAt: new Date(quotas.search.hourly.renewsAt),
+      windowSeconds: 60 * 60,
+      usedValue: quotas.search.hourly.requests,
+      limitValue: quotas.search.hourly.limit,
+    });
+  }
+
+  if (quotas.freeToolCalls.limit > 0) {
+    windows.push({
+      label: "Free Tool Calls",
+      usedPercent:
+        (quotas.freeToolCalls.requests / quotas.freeToolCalls.limit) * 100,
+      resetsAt: new Date(quotas.freeToolCalls.renewsAt),
+      windowSeconds: 24 * 60 * 60,
+      usedValue: quotas.freeToolCalls.requests,
+      limitValue: quotas.freeToolCalls.limit,
+    });
+  }
+
+  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 formatResetDateTime(date: Date): string {
+  const now = new Date();
+  const isToday =
+    date.getDate() === now.getDate() &&
+    date.getMonth() === now.getMonth() &&
+    date.getFullYear() === now.getFullYear();
+
+  const timeStr = date.toLocaleTimeString("en-US", {
+    hour: "numeric",
+    minute: "2-digit",
+    hour12: true,
+  });
+
+  if (isToday) {
+    return `today ${timeStr}`;
+  }
+
+  const dateStr = date.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+  });
+
+  return `${dateStr} ${timeStr}`;
+}
+
+function renderProgressBar(
+  percent: number,
+  width: number,
+  theme: Theme,
+  fillColor: "success" | "warning" | "error",
+  pacePercent?: number | null,
+): string {
+  const clamped = Math.max(0, Math.min(100, Math.round(percent)));
+  const filled = Math.round((clamped / 100) * width);
+  const paceIndex =
+    pacePercent === null || pacePercent === undefined || pacePercent <= percent
+      ? null
+      : Math.round((Math.max(0, Math.min(100, pacePercent)) / 100) * width);
+
+  const parts: string[] = [];
+  for (let idx = 0; idx < width; idx++) {
+    if (idx < filled) {
+      parts.push(theme.fg(fillColor, "█"));
+    } else if (paceIndex !== null && idx < paceIndex) {
+      parts.push(theme.fg(fillColor, "▓"));
+    } else {
+      parts.push(theme.fg("dim", "░"));
+    }
+  }
+
+  return parts.join("");
+}
+
+export class QuotasComponent implements Component {
+  private state: QuotasState = { type: "loading" };
+  private theme: Theme;
+  private onClose: () => void;
+
+  constructor(theme: Theme, onClose: () => void) {
+    this.theme = theme;
+    this.onClose = onClose;
+  }
+
+  setState(state: QuotasState): void {
+    this.state = state;
+  }
+
+  handleInput(data: string): boolean {
+    if (matchesKey(data, "escape") || data === "q") {
+      this.onClose();
+      return true;
+    }
+    return false;
+  }
+
+  render(width: number): string[] {
+    const lines: string[] = [];
+    const border = new DynamicBorder((s: string) => this.theme.fg("border", s));
+    const contentWidth = Math.max(1, width - 4);
+
+    lines.push(...border.render(width));
+    lines.push(
+      truncateToWidth(
+        ` ${this.theme.fg("accent", this.theme.bold("Synthetic API Quotas"))}`,
+        width,
+      ),
+    );
+    lines.push("");
+
+    switch (this.state.type) {
+      case "loading":
+        lines.push(this.theme.fg("muted", "  Loading..."));
+        break;
+      case "error":
+        lines.push(this.theme.fg("error", `  ${this.state.message}`));
+        break;
+      case "loaded":
+        lines.push(
+          ...this.renderLoaded(this.state.quotas, contentWidth, width),
+        );
+        break;
+    }
+
+    lines.push("");
+    lines.push(this.theme.fg("dim", "  q/Esc to close"));
+    lines.push(...border.render(width));
+
+    return lines;
+  }
+
+  private renderLoaded(
+    quotas: QuotasResponse,
+    contentWidth: number,
+    maxWidth: number,
+  ): string[] {
+    const lines: string[] = [];
+    const windows = toWindows(quotas);
+    const barWidth = Math.min(50, Math.max(20, contentWidth - 20));
+
+    for (const window of windows) {
+      lines.push(...this.renderWindow(window, barWidth, maxWidth));
+      lines.push("");
+    }
+
+    // Remove trailing empty line
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+      lines.pop();
+    }
+
+    return lines;
+  }
+
+  private renderWindow(
+    window: QuotaWindow,
+    barWidth: number,
+    maxWidth: number,
+  ): string[] {
+    const lines: string[] = [];
+    const theme = this.theme;
+
+    const pacePercent = getPacePercent(window);
+    const projectedPercent = getProjectedPercent(
+      window.usedPercent,
+      pacePercent,
+    );
+    const severity = getSeverity(projectedPercent, pacePercent);
+
+    // Label
+    lines.push(
+      truncateToWidth(`  ${theme.fg("accent", window.label)}`, maxWidth),
+    );
+
+    // Progress bar + usage
+    const bar = renderProgressBar(
+      window.usedPercent,
+      barWidth,
+      theme,
+      severity,
+      pacePercent,
+    );
+    const usedStr = `${window.usedValue.toLocaleString()}/${window.limitValue.toLocaleString()} (${Math.round(window.usedPercent)}%)`;
+    lines.push(
+      truncateToWidth(`  ${bar} ${theme.fg(severity, usedStr)}`, maxWidth),
+    );
+
+    // Metadata: estimated + pace left, reset time right
+    const leftParts: string[] = [];
+    if (projectedPercent > 0) {
+      const estStr = `est ${Math.round(projectedPercent)}%`;
+      leftParts.push(
+        severity !== "success"
+          ? theme.fg(severity, estStr)
+          : theme.fg("dim", estStr),
+      );
+    }
+
+    if (pacePercent !== null) {
+      const paceDiff = window.usedPercent - pacePercent;
+      if (Math.abs(paceDiff) > 5) {
+        if (paceDiff > 0) {
+          leftParts.push(
+            theme.fg("warning", `${Math.round(Math.abs(paceDiff))}% ahead`),
+          );
+        } else {
+          leftParts.push(
+            theme.fg("success", `${Math.round(Math.abs(paceDiff))}% behind`),
+          );
+        }
+      }
+    }
+
+    const leftStr = leftParts.join("  ");
+    const resetStr = formatResetDateTime(window.resetsAt);
+    const rightStr = theme.fg("dim", resetStr);
+
+    const leftW = visibleWidth(leftStr);
+    const rightW = visibleWidth(rightStr);
+    const gap = Math.max(2, barWidth - leftW - rightW);
+
+    lines.push(
+      truncateToWidth(`  ${leftStr}${" ".repeat(gap)}${rightStr}`, maxWidth),
+    );
+
+    return lines;
+  }
+
+  invalidate(): void {
+    // No internal cached state to invalidate
+  }
+}

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

@@ -0,0 +1,8 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerQuotasCommand } from "./command";
+import { registerSubIntegration } from "./sub-integration";
+
+export default async function (pi: ExtensionAPI) {
+  registerQuotasCommand(pi);
+  registerSubIntegration(pi);
+}

package/src/{hooks → extensions/command-quotas}/sub-integration.ts

@@ -1,6 +1,7 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import type { QuotasResponse } from "../types/quotas";
-import { fetchQuotas, formatResetTime } from "../utils/quotas";
+import type { AuthStorage, ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { getSyntheticApiKey } from "../../lib/env";
+import type { QuotasResponse } from "../../types/quotas";
+import { fetchQuotas, formatResetTime } from "../../utils/quotas";
 
 interface RateWindow {
   label: string;
@@ -53,7 +54,7 @@ function toUsageSnapshot(quotas: QuotasResponse): UsageSnapshot {
     const pct =
       (quotas.freeToolCalls.requests / quotas.freeToolCalls.limit) * 100;
     windows.push({
-      label: "Free",
+      label: "Tools",
       usedPercent: Math.round(pct),
       resetDescription: formatResetTime(quotas.freeToolCalls.renewsAt),
       resetAt: quotas.freeToolCalls.renewsAt,
@@ -68,8 +69,13 @@ function toUsageSnapshot(quotas: QuotasResponse): UsageSnapshot {
   };
 }
 
-async function emitCurrentUsage(pi: ExtensionAPI): Promise<void> {
-  const quotas = await fetchQuotas();
+async function emitCurrentUsage(
+  pi: ExtensionAPI,
+  authStorage: AuthStorage,
+): Promise<void> {
+  const apiKey = await getSyntheticApiKey(authStorage);
+  if (!apiKey) return;
+  const quotas = await fetchQuotas(apiKey);
   if (!quotas) return;
   pi.events.emit("sub-core:update-current", {
     state: { provider: "synthetic", usage: toUsageSnapshot(quotas) },
@@ -77,12 +83,11 @@ async function emitCurrentUsage(pi: ExtensionAPI): Promise<void> {
 }
 
 export function registerSubIntegration(pi: ExtensionAPI): void {
-  if (!process.env.SYNTHETIC_API_KEY) return;
-
   let interval: NodeJS.Timeout | undefined;
   let refreshMs = 60000;
   let subCoreReady = false;
   let currentProvider: string | undefined;
+  let currentAuthStorage: AuthStorage | undefined;
 
   function isSynthetic(): boolean {
     return currentProvider === "synthetic";
@@ -95,15 +100,15 @@ export function registerSubIntegration(pi: ExtensionAPI): void {
     }
   }
 
-  function start(): void {
+  function startPolling(authStorage: AuthStorage): void {
     stop();
-    if (!subCoreReady || !isSynthetic()) {
-      return;
-    }
-    emitCurrentUsage(pi);
+    currentAuthStorage = authStorage;
+    void emitCurrentUsage(pi, authStorage);
     const ms = Math.max(10000, refreshMs);
     interval = setInterval(() => {
-      if (isSynthetic()) emitCurrentUsage(pi);
+      if (isSynthetic() && currentAuthStorage) {
+        void emitCurrentUsage(pi, currentAuthStorage);
+      }
     }, ms);
     interval.unref?.();
   }
@@ -111,28 +116,44 @@ export function registerSubIntegration(pi: ExtensionAPI): void {
   // Custom events (inter-extension bus)
   pi.events.on("sub-core:ready", () => {
     subCoreReady = true;
-    start();
+    // Polling starts in session_start/model_select when provider is synthetic
   });
 
   pi.events.on("sub-core:settings:updated", (data: unknown) => {
     const payload = data as SubCoreSettingsPayload;
     if (payload.settings?.behavior?.refreshInterval) {
       refreshMs = payload.settings.behavior.refreshInterval * 1000;
-      if (interval) start();
+      // Restart with new interval if currently running
+      if (interval && isSynthetic() && currentAuthStorage) {
+        startPolling(currentAuthStorage);
+      }
     }
   });
 
-  // Lifecycle events (pi.on, not pi.events.on)
-  pi.on("session_start", (_event, ctx) => {
+  // Lifecycle events
+  pi.on("session_start", async (_event, ctx) => {
     currentProvider = ctx.model?.provider;
-    start();
+    currentAuthStorage = ctx.modelRegistry.authStorage;
+
+    if (subCoreReady && isSynthetic()) {
+      const apiKey = await getSyntheticApiKey(currentAuthStorage);
+      if (apiKey) {
+        startPolling(currentAuthStorage);
+      }
+    }
   });
 
-  pi.on("model_select", (event, _ctx) => {
+  pi.on("model_select", async (event, ctx) => {
     currentProvider = event.model?.provider;
-    if (isSynthetic()) {
-      emitCurrentUsage(pi);
-      start();
+    currentAuthStorage = ctx.modelRegistry.authStorage;
+
+    if (subCoreReady && isSynthetic()) {
+      const apiKey = await getSyntheticApiKey(currentAuthStorage);
+      if (apiKey) {
+        startPolling(currentAuthStorage);
+      } else {
+        stop();
+      }
     } else {
       stop();
     }
@@ -140,6 +161,7 @@ export function registerSubIntegration(pi: ExtensionAPI): void {
 
   pi.on("session_shutdown", () => {
     currentProvider = undefined;
+    currentAuthStorage = undefined;
     stop();
   });
 }

package/src/{providers → extensions/provider}/index.ts

@@ -26,3 +26,7 @@ export function registerSyntheticProvider(pi: ExtensionAPI): void {
     })),
   });
 }
+
+export default async function (pi: ExtensionAPI) {
+  registerSyntheticProvider(pi);
+}

package/src/{providers → extensions/provider}/models.test.ts

@@ -42,7 +42,7 @@ async function fetchApiModels(): Promise<ApiModel[]> {
     );
   }
 
-  const data = (await response.json()) as ApiResponse;
+  const data: ApiResponse = await response.json();
   return data.data;
 }
 

package/src/{providers → extensions/provider}/models.ts

@@ -67,7 +67,7 @@ export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
     input: ["text"],
     cost: {
       input: 1,
-      output: 6,
+      output: 3,
       cacheRead: 1,
       cacheWrite: 0,
     },

package/src/extensions/web-search/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerSyntheticWebSearchTool } from "./tool";
+
+export default async function (pi: ExtensionAPI) {
+  registerSyntheticWebSearchTool(pi);
+}

package/src/{tools/search.ts → extensions/web-search/tool.ts}

@@ -9,6 +9,7 @@ import type {
 import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
 import { Container, Markdown, Text } from "@mariozechner/pi-tui";
 import { type Static, Type } from "@sinclair/typebox";
+import { getSyntheticApiKey } from "../../lib/env";
 
 export const SYNTHETIC_WEB_SEARCH_TOOL = "synthetic_web_search" as const;
 
@@ -51,16 +52,18 @@ export function registerSyntheticWebSearchTool(pi: ExtensionAPI): void {
       onUpdate:
         | ((result: AgentToolResult<WebSearchDetails>) => void)
         | undefined,
-      _ctx: ExtensionContext,
+      ctx: ExtensionContext,
     ): Promise<AgentToolResult<WebSearchDetails>> {
       onUpdate?.({
         content: [{ type: "text", text: "Searching..." }],
         details: { query: params.query },
       });
 
-      const apiKey = process.env.SYNTHETIC_API_KEY;
+      const apiKey = await getSyntheticApiKey(ctx.modelRegistry.authStorage);
       if (!apiKey) {
-        throw new Error("SYNTHETIC_API_KEY is not configured");
+        throw new Error(
+          "Synthetic web search requires a Synthetic subscription. Add credentials to ~/.pi/agent/auth.json or set SYNTHETIC_API_KEY environment variable.",
+        );
       }
 
       const response = await fetch("https://api.synthetic.new/v2/search", {

package/src/lib/env.ts

@@ -0,0 +1,18 @@
+import type { AuthStorage } from "@mariozechner/pi-coding-agent";
+
+const PROVIDER_ID = "synthetic";
+
+/**
+ * Get the Synthetic API key through Pi's auth handling.
+ *
+ * Resolution order:
+ * 1. Runtime override (CLI --api-key)
+ * 2. auth.json entry for "synthetic"
+ * 3. Environment variable SYNTHETIC_API_KEY
+ */
+export async function getSyntheticApiKey(
+  authStorage: AuthStorage,
+): Promise<string | undefined> {
+  const key = await authStorage.getApiKey(PROVIDER_ID);
+  return key ?? process.env.SYNTHETIC_API_KEY;
+}