@aliou/pi-synthetic 0.19.1 → 0.20.0

package/README.md

@@ -64,7 +64,7 @@ The `provider` field in `src/extensions/provider/models.ts` is for maintenance o
 
 ### Web Search Tool
 
-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.
+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, the account lacks a subscription, or the configured utility proxy rejects the request.
 
 ### Reasoning Levels
 
@@ -85,6 +85,12 @@ Check your API usage:
 /synthetic:quotas
 ```
 
+### Utility API Proxy
+
+Web search and quotas can use a proxy instead of `https://api.synthetic.new`. Configure it with `/synthetic:settings` under **Connection > Utility API Proxy**. The proxy is only used for `/v2/search` and `/v2/quotas`; model provider calls still use Synthetic's OpenAI-compatible endpoint directly.
+
+If the proxy requires auth, pi-synthetic still requires a Synthetic API key and sends `Authorization: Bearer ...`. If the proxy does not require auth, disable **Requires auth** and these utility calls skip API key checks and omit `Authorization`.
+
 ### 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.
@@ -107,7 +113,7 @@ 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`, `sub-bar-integration`, `usage-status`, or `provider` to disable other features.
 
-The **Proxied Models** setting is not a loadable extension feature. It is a regular setting controlled through `/synthetic:settings`.
+The **Proxied Models** and **Utility API Proxy** settings are not loadable extension features. They are regular settings controlled through `/synthetic:settings`.
 
 ## Adding or Updating Models
 
@@ -181,7 +187,7 @@ This repository uses [Changesets](https://github.com/changesets/changesets) for
 ## Requirements
 
 - Pi coding agent v0.77.0+
-- Synthetic API key (configured in `~/.pi/agent/auth.json` or via `SYNTHETIC_API_KEY`)
+- Synthetic API key (configured in `~/.pi/agent/auth.json` or via `SYNTHETIC_API_KEY`) for model provider calls and authenticated utility API calls
 
 ## Links
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-synthetic",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "license": "MIT",
   "type": "module",
   "private": false,

package/src/config.ts

@@ -2,11 +2,17 @@ import {
   ConfigLoader,
   type Migration,
   registerSettingsCommand,
+  SettingsDetailEditor,
   type SettingsSection,
 } from "@aliou/pi-utils-settings";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { SettingItem } from "@earendil-works/pi-tui";
 import pkg from "../package.json" with { type: "json" };
+import {
+  formatSyntheticUtilityApiProxySummary,
+  hasSyntheticUtilityApiProxy,
+  validateSyntheticUtilityApiProxyUrl,
+} from "./lib/utility-api";
 
 export type SyntheticFeatureId =
   | "webSearch"
@@ -36,6 +42,8 @@ export interface SyntheticConfig {
   quotaWarnings?: boolean;
   subBarIntegration?: boolean;
   proxiedModels?: boolean;
+  proxyUrl?: string;
+  proxyRequiresAuth?: boolean;
 }
 
 export interface ResolvedSyntheticConfig {
@@ -46,6 +54,8 @@ export interface ResolvedSyntheticConfig {
   quotaWarnings: boolean;
   subBarIntegration: boolean;
   proxiedModels: boolean;
+  proxyUrl: string;
+  proxyRequiresAuth: boolean;
 }
 
 const DEFAULT_CONFIG: ResolvedSyntheticConfig = {
@@ -56,6 +66,8 @@ const DEFAULT_CONFIG: ResolvedSyntheticConfig = {
   quotaWarnings: false,
   subBarIntegration: true,
   proxiedModels: false,
+  proxyUrl: "",
+  proxyRequiresAuth: true,
 };
 
 export const pendingMessages: string[] = [];
@@ -165,7 +177,7 @@ export function registerSyntheticSettings(
     commandDescription: "Configure Synthetic extension settings",
     title: "Synthetic Settings",
     configStore: configLoader,
-    buildSections: (tabConfig, resolved): SettingsSection[] => {
+    buildSections: (tabConfig, resolved, ctx): SettingsSection[] => {
       const loaded = getLoadedFeatures();
       const webSearch = tabConfig?.webSearch ?? resolved.webSearch;
       const quotasCommand = tabConfig?.quotasCommand ?? resolved.quotasCommand;
@@ -174,10 +186,100 @@ export function registerSyntheticSettings(
       const subBarIntegration =
         tabConfig?.subBarIntegration ?? resolved.subBarIntegration;
       const proxiedModels = tabConfig?.proxiedModels ?? resolved.proxiedModels;
+      const proxyUrl = tabConfig?.proxyUrl ?? resolved.proxyUrl;
+      const proxyRequiresAuth =
+        tabConfig?.proxyRequiresAuth ?? resolved.proxyRequiresAuth;
 
       const sections: SettingsSection[] = [];
 
       sections.push(
+        {
+          label: "Connection",
+          items: [
+            {
+              id: "utilityApiProxy",
+              label: "Utility API Proxy",
+              description:
+                "Override the Synthetic quotas and web search API root. The provider endpoint is not proxied.",
+              currentValue: formatSyntheticUtilityApiProxySummary({
+                proxyUrl,
+                proxyRequiresAuth,
+              }),
+              submenu: (_current, done) => {
+                const current: SyntheticConfig =
+                  tabConfig ?? (ctx.scope === "memory" ? resolved : {});
+                let nextProxyUrl = proxyUrl;
+                let nextProxyRequiresAuth =
+                  proxyUrl.trim() || proxyRequiresAuth
+                    ? proxyRequiresAuth
+                    : true;
+
+                const syncDraft = () => {
+                  ctx.setDraft({
+                    ...current,
+                    proxyUrl: nextProxyUrl.trim() || undefined,
+                    proxyRequiresAuth: nextProxyRequiresAuth,
+                  });
+                };
+
+                return new SettingsDetailEditor({
+                  title: "Utility API Proxy",
+                  theme: ctx.theme,
+                  fields: [
+                    {
+                      id: "proxyUrl.detail",
+                      type: "text",
+                      label: "Proxy URL",
+                      description:
+                        "Leave empty to call https://api.synthetic.new directly for quotas and web search.",
+                      getValue: () => nextProxyUrl,
+                      setValue: (value) => {
+                        nextProxyUrl = value;
+                        // Requires auth only makes sense with a proxy.
+                        // Enforce enabled state when the URL is empty.
+                        if (!value.trim()) nextProxyRequiresAuth = true;
+                        syncDraft();
+                      },
+                      validate: validateSyntheticUtilityApiProxyUrl,
+                      emptyValueText: "direct",
+                    },
+                    {
+                      id: "proxyRequiresAuth.detail",
+                      type: "boolean",
+                      label: "Requires auth",
+                      description:
+                        "When disabled, quotas and web search skip the Synthetic API key check and omit Authorization. Only effective when a proxy URL is set.",
+                      getValue: () =>
+                        hasSyntheticUtilityApiProxy({
+                          proxyUrl: nextProxyUrl,
+                          proxyRequiresAuth: nextProxyRequiresAuth,
+                        })
+                          ? nextProxyRequiresAuth
+                          : true,
+                      setValue: (value) => {
+                        nextProxyRequiresAuth = hasSyntheticUtilityApiProxy({
+                          proxyUrl: nextProxyUrl,
+                          proxyRequiresAuth: nextProxyRequiresAuth,
+                        })
+                          ? value
+                          : true;
+                        syncDraft();
+                      },
+                      trueLabel: "enabled",
+                      falseLabel: "disabled",
+                    },
+                  ],
+                  onDone: done,
+                  getDoneSummary: () =>
+                    formatSyntheticUtilityApiProxySummary({
+                      proxyUrl: nextProxyUrl,
+                      proxyRequiresAuth: nextProxyRequiresAuth,
+                    }),
+                });
+              },
+            },
+          ],
+        },
         {
           label: "Models",
           items: [

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

@@ -1,17 +1,38 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { configLoader } from "../../config";
 import { getSyntheticApiKey } from "../../lib/env";
-import { fetchQuotas } from "../../utils/quotas";
+import {
+  resolveSyntheticUtilityApiAuth,
+  type SyntheticUtilityApiConfig,
+} from "../../lib/utility-api";
+import { type FetchQuotasOptions, 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.";
+  "Synthetic quotas requires a Synthetic subscription or an unauthenticated proxy. Add credentials to ~/.pi/agent/auth.json, set SYNTHETIC_API_KEY, or disable proxy auth in /synthetic:settings.";
+
+async function buildQuotasOptions(
+  config: SyntheticUtilityApiConfig,
+  authStorage: NonNullable<Parameters<typeof getSyntheticApiKey>[0]>,
+): Promise<FetchQuotasOptions | undefined> {
+  const auth = await resolveSyntheticUtilityApiAuth(config, () =>
+    getSyntheticApiKey(authStorage),
+  );
+  if (!auth) return undefined;
+
+  return {
+    apiKey: auth.apiKey,
+    proxyUrl: config.proxyUrl,
+    requiresAuth: auth.requiresAuth,
+  };
+}
 
 export function registerQuotasCommand(pi: ExtensionAPI): void {
   pi.registerCommand("synthetic:quotas", {
     description: "Display Synthetic API usage quotas",
     handler: async (_args, ctx) => {
-      if (!configLoader.getConfig().quotasCommand) {
+      const config = configLoader.getConfig();
+      if (!config.quotasCommand) {
         ctx.ui.notify(
           "Synthetic quotas command is disabled. Restart Pi to unload the command after re-enabling or disabling it.",
           "warning",
@@ -19,12 +40,14 @@ export function registerQuotasCommand(pi: ExtensionAPI): void {
         return;
       }
 
-      const apiKey = await getSyntheticApiKey(ctx.modelRegistry.authStorage);
-      if (!apiKey) {
+      const quotasOptions = await buildQuotasOptions(
+        config,
+        ctx.modelRegistry.authStorage,
+      );
+      if (!quotasOptions) {
         ctx.ui.notify(MISSING_AUTH_MESSAGE, "warning");
         return;
       }
-      const key: string = apiKey;
 
       const result = await ctx.ui.custom<null>((tui, theme, _kb, done) => {
         const controller = new AbortController();
@@ -43,7 +66,10 @@ export function registerQuotasCommand(pi: ExtensionAPI): void {
         );
 
         async function loadQuotas(): Promise<void> {
-          const fetchResult = await fetchQuotas(key, controller.signal);
+          const fetchResult = await fetchQuotas({
+            ...quotasOptions,
+            signal: controller.signal,
+          });
           if (controller.signal.aborted) return;
           if (fetchResult.success) {
             component.setState({
@@ -74,7 +100,7 @@ export function registerQuotasCommand(pi: ExtensionAPI): void {
 
       // Non-interactive fallback (RPC, print, JSON modes)
       if (result === undefined) {
-        const fetchResult = await fetchQuotas(key);
+        const fetchResult = await fetchQuotas(quotasOptions);
         if (!fetchResult.success) {
           ctx.ui.notify(
             JSON.stringify({ error: fetchResult.error.message }),

package/src/extensions/provider/index.ts

@@ -16,6 +16,7 @@ import {
   seedSyntheticConfigIfMissing,
 } from "../../config";
 import { getSyntheticApiKey } from "../../lib/env";
+import { resolveSyntheticUtilityApiAuth } from "../../lib/utility-api";
 import { QuotaStore } from "../../services/quota-store";
 import {
   parseQuotaHeader,
@@ -94,13 +95,29 @@ export default async function (pi: ExtensionAPI) {
   await configLoader.load();
   await seedSyntheticConfigIfMissing();
 
-  const includeProxiedModels = configLoader.getConfig().proxiedModels;
+  const initialConfig = configLoader.getConfig();
+  const includeProxiedModels = initialConfig.proxiedModels;
+  let utilityApiProxyUrl = initialConfig.proxyUrl;
+  let utilityApiProxyRequiresAuth = initialConfig.proxyRequiresAuth;
+  const quotaStore = new QuotaStore();
+  let currentAuthStorage: AuthStorage | undefined;
+
   registerSyntheticProvider(pi, { includeProxiedModels });
 
   pi.events.on(SYNTHETIC_CONFIG_UPDATED_EVENT, (data: unknown) => {
-    const includeProxiedModels = (data as SyntheticConfigUpdatedPayload).config
-      .proxiedModels;
-    registerSyntheticProvider(pi, { includeProxiedModels });
+    const config = (data as SyntheticConfigUpdatedPayload).config;
+    registerSyntheticProvider(pi, {
+      includeProxiedModels: config.proxiedModels,
+    });
+
+    if (
+      config.proxyUrl !== utilityApiProxyUrl ||
+      config.proxyRequiresAuth !== utilityApiProxyRequiresAuth
+    ) {
+      quotaStore.clear();
+      utilityApiProxyUrl = config.proxyUrl;
+      utilityApiProxyRequiresAuth = config.proxyRequiresAuth;
+    }
   });
 
   const loadedFeatures = new Set<SyntheticFeatureId>();
@@ -114,14 +131,20 @@ export default async function (pi: ExtensionAPI) {
     getLoadedFeatures: () => loadedFeatures,
   });
 
-  const quotaStore = new QuotaStore();
-  let currentAuthStorage: AuthStorage | undefined;
-
   async function fetchQuotasFromAuth(): Promise<QuotasResponse | undefined> {
-    if (!currentAuthStorage) return undefined;
-    const apiKey = await getSyntheticApiKey(currentAuthStorage);
-    if (!apiKey) return undefined;
-    const result = await fetchQuotas(apiKey);
+    const config = configLoader.getConfig();
+    const auth = await resolveSyntheticUtilityApiAuth(config, () =>
+      currentAuthStorage
+        ? getSyntheticApiKey(currentAuthStorage)
+        : Promise.resolve(undefined),
+    );
+    if (!auth) return undefined;
+
+    const result = await fetchQuotas({
+      apiKey: auth.apiKey,
+      proxyUrl: config.proxyUrl,
+      requiresAuth: auth.requiresAuth,
+    });
     return result.success ? result.data.quotas : undefined;
   }
 

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

@@ -14,6 +14,11 @@ import { Container, Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
 import { configLoader } from "../../config";
 import { getSyntheticApiKey } from "../../lib/env";
+import {
+  resolveSyntheticUtilityApiAuth,
+  resolveSyntheticUtilityApiBaseUrl,
+  syntheticUtilityApiUrl,
+} from "../../lib/utility-api";
 
 export const SYNTHETIC_WEB_SEARCH_TOOL = "synthetic_web_search" as const;
 
@@ -69,28 +74,46 @@ export const syntheticWebSearchTool = defineTool({
       details: { query: params.query },
     });
 
-    if (!configLoader.getConfig().webSearch) {
+    const config = configLoader.getConfig();
+    if (!config.webSearch) {
       throw new Error(
         "Synthetic web search is disabled. Re-enable it with synthetic:settings or pi config.",
       );
     }
 
-    const apiKey = await getSyntheticApiKey(ctx.modelRegistry.authStorage);
-    if (!apiKey) {
+    const auth = await resolveSyntheticUtilityApiAuth(config, () =>
+      getSyntheticApiKey(ctx.modelRegistry.authStorage),
+    );
+    if (!auth) {
       throw new Error(
-        "Synthetic web search requires a Synthetic subscription. Add credentials to ~/.pi/agent/auth.json or set SYNTHETIC_API_KEY environment variable.",
+        "Synthetic web search requires a Synthetic subscription or an unauthenticated proxy. Add credentials to ~/.pi/agent/auth.json, set SYNTHETIC_API_KEY, or disable proxy auth in /synthetic:settings.",
       );
     }
 
-    const response = await fetch("https://api.synthetic.new/v2/search", {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${apiKey}`,
-        "Content-Type": "application/json",
+    let baseUrl: string;
+    try {
+      baseUrl = resolveSyntheticUtilityApiBaseUrl(config.proxyUrl);
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : "Invalid proxy URL";
+      throw new Error(`Synthetic web search: ${message}`);
+    }
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (auth.apiKey) {
+      headers.Authorization = `Bearer ${auth.apiKey}`;
+    }
+
+    const response = await fetch(
+      syntheticUtilityApiUrl(baseUrl, "/v2/search"),
+      {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ query: params.query }),
+        signal,
       },
-      body: JSON.stringify({ query: params.query }),
-      signal,
-    });
+    );
 
     if (!response.ok) {
       const errorText = await response.text();

package/src/lib/utility-api.ts

@@ -0,0 +1,85 @@
+export const DEFAULT_SYNTHETIC_API_BASE_URL = "https://api.synthetic.new";
+
+export interface SyntheticUtilityApiConfig {
+  proxyUrl?: string;
+  proxyRequiresAuth?: boolean;
+}
+
+export function hasSyntheticUtilityApiProxy(
+  config: SyntheticUtilityApiConfig,
+): boolean {
+  return !!config.proxyUrl?.trim();
+}
+
+export function syntheticUtilityApiRequiresAuth(
+  config: SyntheticUtilityApiConfig,
+): boolean {
+  return (
+    !hasSyntheticUtilityApiProxy(config) || config.proxyRequiresAuth !== false
+  );
+}
+
+export function validateSyntheticUtilityApiProxyUrl(
+  value: string,
+): string | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return "Proxy URL must be a valid URL";
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return "Proxy URL must use http or https";
+  }
+
+  return null;
+}
+
+export function resolveSyntheticUtilityApiBaseUrl(proxyUrl?: string): string {
+  const raw = proxyUrl?.trim() || DEFAULT_SYNTHETIC_API_BASE_URL;
+  const error = validateSyntheticUtilityApiProxyUrl(raw);
+  if (error) {
+    throw new Error(`Synthetic utility API: ${error}`);
+  }
+  return raw.replace(/\/+$/, "");
+}
+
+export function syntheticUtilityApiUrl(baseUrl: string, path: string): string {
+  return `${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+
+export function formatSyntheticUtilityApiProxySummary(
+  config: SyntheticUtilityApiConfig,
+): string {
+  if (!hasSyntheticUtilityApiProxy(config)) return "direct";
+  const auth = syntheticUtilityApiRequiresAuth(config) ? "auth" : "no auth";
+  return `${config.proxyUrl?.trim()} · ${auth}`;
+}
+
+export interface ResolvedSyntheticUtilityApiAuth {
+  apiKey: string | undefined;
+  requiresAuth: boolean;
+}
+
+/**
+ * Resolve the auth state for a utility API request.
+ *
+ * - When auth is required (direct calls, or proxy with auth enabled), the
+ *   provided `getApiKey` callback is awaited. Returns `null` if no key is
+ *   available, so callers can surface a missing-credentials error.
+ * - When auth is not required (unauthenticated proxy), `apiKey` is left
+ *   `undefined` and the Synthetic API key check is skipped.
+ */
+export async function resolveSyntheticUtilityApiAuth(
+  config: SyntheticUtilityApiConfig,
+  getApiKey: () => Promise<string | undefined>,
+): Promise<ResolvedSyntheticUtilityApiAuth | null> {
+  const requiresAuth = syntheticUtilityApiRequiresAuth(config);
+  const apiKey = requiresAuth ? await getApiKey() : undefined;
+  if (requiresAuth && !apiKey) return null;
+  return { apiKey, requiresAuth };
+}

package/src/utils/quotas.ts

@@ -1,7 +1,18 @@
+import {
+  resolveSyntheticUtilityApiBaseUrl,
+  syntheticUtilityApiUrl,
+} from "../lib/utility-api";
 import type { QuotasResponse, QuotasResult } from "../types/quotas";
 
 const FETCH_TIMEOUT_MS = 15_000;
 
+export interface FetchQuotasOptions {
+  apiKey?: string;
+  proxyUrl?: string;
+  requiresAuth?: boolean;
+  signal?: AbortSignal;
+}
+
 function isTimeoutReason(reason: unknown): boolean {
   return (
     (reason instanceof DOMException && reason.name === "TimeoutError") ||
@@ -10,23 +21,37 @@ function isTimeoutReason(reason: unknown): boolean {
 }
 
 export async function fetchQuotas(
-  apiKey: string,
-  signal?: AbortSignal,
+  options: FetchQuotasOptions,
 ): Promise<QuotasResult> {
-  if (!apiKey) {
+  const requiresAuth = options.requiresAuth ?? true;
+  if (requiresAuth && !options.apiKey) {
     return {
       success: false,
       error: { message: "No API key provided", kind: "config" },
     };
   }
 
+  let url: string;
+  try {
+    const baseUrl = resolveSyntheticUtilityApiBaseUrl(options.proxyUrl);
+    url = syntheticUtilityApiUrl(baseUrl, "/v2/quotas");
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : "Invalid proxy URL";
+    return { success: false, error: { message, kind: "config" } };
+  }
+
   const signals: AbortSignal[] = [AbortSignal.timeout(FETCH_TIMEOUT_MS)];
-  if (signal) signals.push(signal);
+  if (options.signal) signals.push(options.signal);
   const combined = AbortSignal.any(signals);
 
   try {
-    const response = await fetch("https://api.synthetic.new/v2/quotas", {
-      headers: { Authorization: `Bearer ${apiKey}` },
+    const headers: Record<string, string> = {};
+    if (options.apiKey) {
+      headers.Authorization = `Bearer ${options.apiKey}`;
+    }
+
+    const response = await fetch(url, {
+      headers,
       signal: combined,
     });