@aliou/pi-synthetic 0.8.5 → 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.5",
+  "version": "0.9.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/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";
 
@@ -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/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/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]);
-    }
-  });
-}