@aliou/pi-synthetic 0.8.5 → 0.10.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.5",
+  "version": "0.10.0",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -36,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

@@ -1,20 +1,31 @@
 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()
+        fetchQuotas(apiKey)
           .then((quotas) => {
             if (!quotas) {
               component.setState({
                 type: "error",
-                message: "Failed to fetch quotas",
+                message:
+                  "Failed to fetch quotas. Check your Synthetic subscription status.",
               });
             } else {
               component.setState({ type: "loaded", quotas });
@@ -24,7 +35,8 @@ export function registerQuotasCommand(pi: ExtensionAPI): void {
           .catch(() => {
             component.setState({
               type: "error",
-              message: "Failed to fetch quotas",
+              message:
+                "Failed to fetch quotas. Check your Synthetic subscription status.",
             });
             tui.requestRender();
           });
@@ -38,7 +50,7 @@ export function registerQuotasCommand(pi: ExtensionAPI): void {
 
       // RPC fallback: return JSON
       if (result === undefined) {
-        const quotas = await fetchQuotas();
+        const quotas = await fetchQuotas(apiKey);
         if (!quotas) {
           ctx.ui.notify(
             JSON.stringify({ error: "Failed to fetch quotas" }),

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

@@ -20,16 +20,77 @@ interface QuotaWindow {
   windowSeconds: number;
   usedValue: number;
   limitValue: number;
+  isCredits?: boolean;
+  isLimited?: boolean;
+  tickPercent?: number;
+  nextRegenCredits?: 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.subscription.limit > 0) {
+  // Weekly token limit (credits-based)
+  if (quotas.weeklyTokenLimit) {
+    const { weeklyTokenLimit } = quotas;
+    const limitValue = parseCurrency(weeklyTokenLimit.maxCredits);
+    const remainingValue = parseCurrency(weeklyTokenLimit.remainingCredits);
+    windows.push({
+      label: "Credits",
+      usedPercent: Math.max(
+        0,
+        Math.min(100, 100 - weeklyTokenLimit.percentRemaining),
+      ),
+      resetsAt: new Date(weeklyTokenLimit.nextRegenAt),
+      windowSeconds: 7 * 24 * 60 * 60,
+      usedValue: limitValue - remainingValue,
+      limitValue,
+      isCredits: true,
+      nextRegenCredits: weeklyTokenLimit.nextRegenCredits,
+    });
+  }
+
+  // Rolling 5-hour limit (request-based)
+  if (quotas.rollingFiveHourLimit && quotas.rollingFiveHourLimit.max > 0) {
+    const { rollingFiveHourLimit } = quotas;
+    windows.push({
+      label: "5h",
+      usedPercent: safePercent(
+        rollingFiveHourLimit.max - rollingFiveHourLimit.remaining,
+        rollingFiveHourLimit.max,
+      ),
+      resetsAt: new Date(rollingFiveHourLimit.nextTickAt),
+      windowSeconds: 5 * 60 * 60,
+      usedValue: rollingFiveHourLimit.max - rollingFiveHourLimit.remaining,
+      limitValue: rollingFiveHourLimit.max,
+      isLimited: rollingFiveHourLimit.limited,
+      tickPercent: rollingFiveHourLimit.tickPercent,
+    });
+  }
+
+  // Legacy subscription (fallback if rollingFiveHourLimit not available)
+  if (
+    !quotas.rollingFiveHourLimit &&
+    quotas.subscription?.limit &&
+    quotas.subscription.limit > 0
+  ) {
     windows.push({
       label: "Completions",
-      usedPercent:
-        (quotas.subscription.requests / quotas.subscription.limit) * 100,
+      usedPercent: safePercent(
+        quotas.subscription.requests,
+        quotas.subscription.limit,
+      ),
       resetsAt: new Date(quotas.subscription.renewsAt),
       windowSeconds: 5 * 60 * 60,
       usedValue: quotas.subscription.requests,
@@ -37,11 +98,13 @@ function toWindows(quotas: QuotasResponse): QuotaWindow[] {
     });
   }
 
-  if (quotas.search.hourly.limit > 0) {
+  if (quotas.search?.hourly?.limit && quotas.search.hourly.limit > 0) {
     windows.push({
       label: "Search",
-      usedPercent:
-        (quotas.search.hourly.requests / quotas.search.hourly.limit) * 100,
+      usedPercent: safePercent(
+        quotas.search.hourly.requests,
+        quotas.search.hourly.limit,
+      ),
       resetsAt: new Date(quotas.search.hourly.renewsAt),
       windowSeconds: 60 * 60,
       usedValue: quotas.search.hourly.requests,
@@ -49,11 +112,13 @@ function toWindows(quotas: QuotasResponse): QuotaWindow[] {
     });
   }
 
-  if (quotas.freeToolCalls.limit > 0) {
+  if (quotas.freeToolCalls?.limit && quotas.freeToolCalls.limit > 0) {
     windows.push({
       label: "Free Tool Calls",
-      usedPercent:
-        (quotas.freeToolCalls.requests / quotas.freeToolCalls.limit) * 100,
+      usedPercent: safePercent(
+        quotas.freeToolCalls.requests,
+        quotas.freeToolCalls.limit,
+      ),
       resetsAt: new Date(quotas.freeToolCalls.renewsAt),
       windowSeconds: 24 * 60 * 60,
       usedValue: quotas.freeToolCalls.requests,
@@ -155,6 +220,34 @@ function renderProgressBar(
   return parts.join("");
 }
 
+function renderSimpleIndicatorBar(
+  usedPercent: number,
+  width: number,
+  theme: Theme,
+  severity: "success" | "warning" | "error",
+): string {
+  const clampedPercent = Math.max(0, Math.min(100, usedPercent));
+  // Clamp to width - 1 to avoid off-by-one when usedPercent === 100
+  const usedIndex = Math.min(
+    Math.round((clampedPercent / 100) * width),
+    width - 1,
+  );
+  const parts: string[] = [];
+
+  // Hide marker when within 5% of edges
+  const showMarker = clampedPercent >= 5 && clampedPercent <= 95;
+
+  for (let idx = 0; idx < width; idx++) {
+    if (showMarker && idx === usedIndex) {
+      parts.push(theme.fg(severity, "|"));
+    } else {
+      parts.push(theme.fg("dim", "░"));
+    }
+  }
+
+  return parts.join("");
+}
+
 export class QuotasComponent implements Component {
   private state: QuotasState = { type: "loading" };
   private theme: Theme;
@@ -254,22 +347,83 @@ export class QuotasComponent implements Component {
       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),
-    );
+    // Progress bar + usage (or indicator for new quota types)
+    if (window.isCredits || window.tickPercent !== undefined) {
+      // Show simple indicator bar for new quota types
+      const bar = renderSimpleIndicatorBar(
+        window.usedPercent,
+        barWidth,
+        theme,
+        severity,
+      );
+      const usedStr = window.isCredits
+        ? `$${window.usedValue.toFixed(2)}/$${window.limitValue.toFixed(2)} (${Math.round(window.usedPercent)}%)`
+        : `${window.usedValue.toFixed(0)}/${window.limitValue.toFixed(0)} (${Math.round(window.usedPercent)}%)`;
+      const limitedBadge = window.isLimited
+        ? theme.fg("error", " LIMITED")
+        : "";
+      lines.push(
+        truncateToWidth(
+          `  ${bar} ${theme.fg(severity, usedStr)}${limitedBadge}`,
+          maxWidth,
+        ),
+      );
+    } else {
+      // Traditional progress bar for legacy quota types
+      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) {
+
+    // Show tick info for rolling window
+    if (window.tickPercent !== undefined) {
+      const now = Date.now();
+      const remainingMs = window.resetsAt.getTime() - now;
+      const remainingMins = Math.ceil(remainingMs / (1000 * 60));
+      const remainingSecs = Math.ceil(remainingMs / 1000);
+      const timeStr =
+        remainingMs <= 0
+          ? "now"
+          : remainingMins >= 1
+            ? `${remainingMins}m`
+            : `${remainingSecs}s`;
+      const tickValue = (window.tickPercent / 100) * window.limitValue;
+      const tickStr = `+${tickValue.toFixed(1)} in ${timeStr}`;
+      leftParts.push(theme.fg("dim", tickStr));
+    }
+
+    // Show next regen credits for weekly token limit
+    if (window.nextRegenCredits !== undefined) {
+      const now = Date.now();
+      const remainingMs = window.resetsAt.getTime() - now;
+      const remainingHours = Math.ceil(remainingMs / (1000 * 60 * 60));
+      const remainingMins = Math.ceil(remainingMs / (1000 * 60));
+      const timeStr =
+        remainingMs <= 0
+          ? "now"
+          : remainingHours >= 1
+            ? `${remainingHours}h`
+            : `${remainingMins}m`;
+      const regenStr = `+${window.nextRegenCredits} in ${timeStr}`;
+      leftParts.push(theme.fg("dim", regenStr));
+    }
+
+    if (
+      projectedPercent > 0 &&
+      window.tickPercent === undefined &&
+      window.nextRegenCredits === undefined
+    ) {
       const estStr = `est ${Math.round(projectedPercent)}%`;
       leftParts.push(
         severity !== "success"
@@ -278,7 +432,11 @@ export class QuotasComponent implements Component {
       );
     }
 
-    if (pacePercent !== null) {
+    if (
+      pacePercent !== null &&
+      window.tickPercent === undefined &&
+      window.nextRegenCredits === undefined
+    ) {
       const paceDiff = window.usedPercent - pacePercent;
       if (Math.abs(paceDiff) > 5) {
         if (paceDiff > 0) {

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

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

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

@@ -1,4 +1,5 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+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";
 
@@ -27,34 +28,66 @@ interface SubCoreSettingsPayload {
 function toUsageSnapshot(quotas: QuotasResponse): UsageSnapshot {
   const windows: RateWindow[] = [];
 
-  if (quotas.subscription) {
+  // Weekly token limit (credits-based)
+  if (quotas.weeklyTokenLimit) {
+    const { weeklyTokenLimit } = quotas;
+    windows.push({
+      label: "Credits",
+      usedPercent: Math.round(
+        Math.max(0, Math.min(100, 100 - weeklyTokenLimit.percentRemaining)),
+      ),
+      resetDescription: formatResetTime(weeklyTokenLimit.nextRegenAt),
+      resetAt: weeklyTokenLimit.nextRegenAt,
+    });
+  }
+
+  // Rolling 5-hour limit (request-based)
+  if (quotas.rollingFiveHourLimit && quotas.rollingFiveHourLimit.max > 0) {
+    const { rollingFiveHourLimit } = quotas;
+    const used = rollingFiveHourLimit.max - rollingFiveHourLimit.remaining;
+    windows.push({
+      label: "5h",
+      usedPercent: Math.round(
+        Math.max(0, Math.min(100, (used / rollingFiveHourLimit.max) * 100)),
+      ),
+      resetDescription: formatResetTime(rollingFiveHourLimit.nextTickAt),
+      resetAt: rollingFiveHourLimit.nextTickAt,
+    });
+  }
+
+  // Legacy subscription (fallback if rollingFiveHourLimit not available)
+  if (
+    !quotas.rollingFiveHourLimit &&
+    quotas.subscription?.limit &&
+    quotas.subscription.limit > 0
+  ) {
     const pct =
       (quotas.subscription.requests / quotas.subscription.limit) * 100;
     windows.push({
       label: "5h",
-      usedPercent: Math.round(pct),
+      usedPercent: Math.round(Math.max(0, Math.min(100, pct))),
       resetDescription: formatResetTime(quotas.subscription.renewsAt),
       resetAt: quotas.subscription.renewsAt,
     });
   }
 
-  if (quotas.search?.hourly) {
+  if (quotas.search?.hourly?.limit && quotas.search.hourly.limit > 0) {
     const pct =
       (quotas.search.hourly.requests / quotas.search.hourly.limit) * 100;
     windows.push({
       label: "Search",
-      usedPercent: Math.round(pct),
+      usedPercent: Math.round(Math.max(0, Math.min(100, pct))),
       resetDescription: formatResetTime(quotas.search.hourly.renewsAt),
       resetAt: quotas.search.hourly.renewsAt,
     });
   }
 
-  if (quotas.freeToolCalls) {
+  if (quotas.freeToolCalls?.limit && quotas.freeToolCalls.limit > 0) {
     const pct =
       (quotas.freeToolCalls.requests / quotas.freeToolCalls.limit) * 100;
     windows.push({
       label: "Tools",
-      usedPercent: Math.round(pct),
+      usedPercent: Math.round(Math.max(0, Math.min(100, pct))),
       resetDescription: formatResetTime(quotas.freeToolCalls.renewsAt),
       resetAt: quotas.freeToolCalls.renewsAt,
     });
@@ -68,8 +101,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 +115,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 +132,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 +148,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 +193,7 @@ export function registerSubIntegration(pi: ExtensionAPI): void {
 
   pi.on("session_shutdown", () => {
     currentProvider = undefined;
+    currentAuthStorage = undefined;
     stop();
   });
 }

package/src/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/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

@@ -1,13 +1,6 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { hasSyntheticApiKey } from "../../lib/env";
-import { registerSyntheticWebSearchHooks } from "./hooks";
 import { registerSyntheticWebSearchTool } from "./tool";
 
 export default async function (pi: ExtensionAPI) {
-  if (!hasSyntheticApiKey()) {
-    return;
-  }
-
   registerSyntheticWebSearchTool(pi);
-  registerSyntheticWebSearchHooks(pi);
 }

package/src/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

@@ -1,7 +1,18 @@
-export function hasSyntheticApiKey(): boolean {
-  return Boolean(process.env.SYNTHETIC_API_KEY);
-}
+import type { AuthStorage } from "@mariozechner/pi-coding-agent";
+
+const PROVIDER_ID = "synthetic";
 
-export function getSyntheticApiKey(): string {
-  return process.env.SYNTHETIC_API_KEY || "";
+/**
+ * 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;
 }

package/src/types/quotas.ts

@@ -1,19 +1,33 @@
 export interface QuotasResponse {
-  subscription: {
+  subscription?: {
     limit: number;
     requests: number;
     renewsAt: string;
   };
-  search: {
-    hourly: {
+  search?: {
+    hourly?: {
       limit: number;
       requests: number;
       renewsAt: string;
     };
   };
-  freeToolCalls: {
+  freeToolCalls?: {
     limit: number;
     requests: number;
     renewsAt: string;
   };
+  weeklyTokenLimit?: {
+    nextRegenAt: string;
+    percentRemaining: number;
+    maxCredits: string;
+    remainingCredits: string;
+    nextRegenCredits: string;
+  };
+  rollingFiveHourLimit?: {
+    nextTickAt: string;
+    tickPercent: number;
+    remaining: number;
+    max: number;
+    limited: boolean;
+  };
 }

package/src/utils/quotas.ts

@@ -1,17 +1,18 @@
 import type { QuotasResponse } from "../types/quotas";
 
-const API_KEY = process.env.SYNTHETIC_API_KEY;
-
-export async function fetchQuotas(): Promise<QuotasResponse | null> {
-  if (!API_KEY) return null;
+export async function fetchQuotas(
+  apiKey: string,
+): Promise<QuotasResponse | null> {
+  if (!apiKey) return null;
 
   try {
     const response = await fetch("https://api.synthetic.new/v2/quotas", {
-      headers: { Authorization: `Bearer ${API_KEY}` },
+      headers: { Authorization: `Bearer ${apiKey}` },
     });
 
     if (!response.ok) return null;
-    return (await response.json()) as QuotasResponse;
+    const data: QuotasResponse = await response.json();
+    return data;
   } catch {
     return null;
   }

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

@@ -1,104 +0,0 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { SYNTHETIC_WEB_SEARCH_TOOL } from "./tool";
-
-async function checkSubscriptionAccess(
-  apiKey: string,
-): Promise<{ ok: true } | { ok: false; reason: string }> {
-  try {
-    const response = await fetch("https://api.synthetic.new/v2/quotas", {
-      method: "GET",
-      headers: {
-        Authorization: `Bearer ${apiKey}`,
-      },
-    });
-
-    if (!response.ok) {
-      return {
-        ok: false,
-        reason: `Quotas check failed (HTTP ${response.status})`,
-      };
-    }
-
-    const data = await response.json();
-    if (data?.subscription?.limit > 0) {
-      return { ok: true };
-    }
-
-    return {
-      ok: false,
-      reason: "No active subscription (search requires a subscription plan)",
-    };
-  } catch (error) {
-    const message =
-      error instanceof Error ? error.message : "Unknown error occurred";
-    return { ok: false, reason: `Quotas check failed: ${message}` };
-  }
-}
-
-export function registerSyntheticWebSearchHooks(pi: ExtensionAPI): void {
-  let accessCheckPromise:
-    | Promise<{ ok: true } | { ok: false; reason: string }>
-    | undefined;
-  let hasAccess = false;
-  let deniedReason: string | undefined;
-  let didNotifyDenied = false;
-
-  // Keep tool inactive at session start. Availability is decided before each agent run.
-  pi.on("session_start", () => {
-    const current = pi.getActiveTools();
-    if (current.includes(SYNTHETIC_WEB_SEARCH_TOOL)) {
-      pi.setActiveTools(
-        current.filter((toolName) => toolName !== SYNTHETIC_WEB_SEARCH_TOOL),
-      );
-    }
-  });
-
-  // Verify subscription only when user starts agent execution.
-  pi.on("before_agent_start", async (_event, ctx) => {
-    const apiKey = process.env.SYNTHETIC_API_KEY;
-    if (!apiKey) {
-      hasAccess = false;
-      deniedReason = "SYNTHETIC_API_KEY is not configured";
-      accessCheckPromise = undefined;
-    } else {
-      if (deniedReason === "SYNTHETIC_API_KEY is not configured") {
-        deniedReason = undefined;
-      }
-
-      if (!hasAccess && !deniedReason) {
-        accessCheckPromise ??= checkSubscriptionAccess(apiKey);
-        const access = await accessCheckPromise;
-
-        if (!access.ok) {
-          deniedReason = access.reason;
-        } else {
-          hasAccess = true;
-          didNotifyDenied = false;
-        }
-      }
-    }
-
-    if (deniedReason) {
-      const current = pi.getActiveTools();
-      if (current.includes(SYNTHETIC_WEB_SEARCH_TOOL)) {
-        pi.setActiveTools(
-          current.filter((toolName) => toolName !== SYNTHETIC_WEB_SEARCH_TOOL),
-        );
-      }
-
-      if (ctx.hasUI && !didNotifyDenied) {
-        ctx.ui.notify(
-          `Synthetic web search disabled: ${deniedReason}`,
-          "warning",
-        );
-        didNotifyDenied = true;
-      }
-      return;
-    }
-
-    const current = pi.getActiveTools();
-    if (!current.includes(SYNTHETIC_WEB_SEARCH_TOOL)) {
-      pi.setActiveTools([...current, SYNTHETIC_WEB_SEARCH_TOOL]);
-    }
-  });
-}