@aliou/pi-synthetic 0.3.0 → 0.4.0

package/.github/workflows/publish.yml

@@ -4,6 +4,12 @@ on:
   push:
     branches:
       - main
+  workflow_dispatch:
+    inputs:
+      skip-checks:
+        description: "Skip lint and typecheck"
+        type: boolean
+        default: false
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -11,6 +17,7 @@ concurrency:
 
 jobs:
   check:
+    if: ${{ !(github.event_name == 'workflow_dispatch' && inputs.skip-checks) }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -34,6 +41,7 @@ jobs:
   publish:
     name: Publish
     needs: check
+    if: ${{ always() && (needs.check.result == 'success' || needs.check.result == 'skipped') }}
     runs-on: ubuntu-latest
     permissions:
       contents: write

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @aliou/pi-synthetic
 
+## 0.4.0
+
+### Minor Changes
+
+- 5cca252: Add `/synthetic:quotas` command to display API usage quotas
+
+  A new slash command that shows your Synthetic API subscription quotas in a rich terminal UI:
+
+  - Visual usage bar with color-coded severity (green/yellow/red based on usage)
+  - Aligned columns showing limit, used, and remaining requests
+  - ISO8601 renewal timestamp with relative time formatting (e.g., "in 5 hours")
+  - Closes on any key press
+
+  The command is only registered when `SYNTHETIC_API_KEY` environment variable is set.
+
+- a8cacfb: Add Synthetic web search tool
+
+  New tool `synthetic_web_search` allows agents to search the web using Synthetic's zero-data-retention API. Returns search results with titles, URLs, content snippets, and publication dates.
+
+  **Note:** Search is a subscription-only feature. The tool will only be registered if the `SYNTHETIC_API_KEY` belongs to an active subscription (verified via the usage endpoint).
+
 ## 0.3.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-synthetic",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/aliou/pi-synthetic"
@@ -16,8 +16,9 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
     "@changesets/cli": "^2.27.11",
-    "@mariozechner/pi-coding-agent": "^0.50.1",
-    "@mariozechner/pi-tui": "^0.50.1",
+    "@mariozechner/pi-coding-agent": "0.51.0",
+    "@mariozechner/pi-tui": "0.51.0",
+    "@sinclair/typebox": "^0.34.48",
     "@types/node": "^25.0.10",
     "husky": "^9.1.7",
     "typescript": "^5.9.3"

package/src/commands/quotas.ts

@@ -0,0 +1,124 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { Component } from "@mariozechner/pi-tui";
+import { QuotasDisplayComponent } from "../components/quotas-display.js";
+import { QuotasErrorComponent } from "../components/quotas-error.js";
+import { QuotasLoadingComponent } from "../components/quotas-loading.js";
+import type { QuotasResponse } from "../types/quotas.js";
+
+export function registerQuotasCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("synthetic:quotas", {
+    description: "Display Synthetic API usage quotas",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        const quotas = await fetchQuotas();
+        if (!quotas) {
+          console.error("Failed to fetch quotas");
+          return;
+        }
+        console.log(formatQuotasPlain(quotas));
+        return;
+      }
+
+      await ctx.ui.custom<void>((tui, theme, _kb, done) => {
+        let currentComponent: Component = new QuotasLoadingComponent(theme);
+
+        fetchQuotas()
+          .then((quotas) => {
+            if (!quotas) {
+              currentComponent = new QuotasErrorComponent(
+                theme,
+                "Failed to fetch quotas",
+              );
+            } else {
+              currentComponent = new QuotasDisplayComponent(theme, quotas);
+            }
+            tui.requestRender();
+          })
+          .catch(() => {
+            currentComponent = new QuotasErrorComponent(
+              theme,
+              "Failed to fetch quotas",
+            );
+            tui.requestRender();
+          });
+
+        return {
+          render: (width: number) => currentComponent.render(width),
+          invalidate: () => currentComponent.invalidate(),
+          handleInput: (_data: string) => {
+            done();
+          },
+        };
+      });
+    },
+  });
+}
+
+async function fetchQuotas(): Promise<QuotasResponse | null> {
+  const apiKey = process.env.SYNTHETIC_API_KEY;
+  if (!apiKey) {
+    return null;
+  }
+
+  try {
+    const response = await fetch("https://api.synthetic.new/v2/quotas", {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    return (await response.json()) as QuotasResponse;
+  } catch {
+    return null;
+  }
+}
+
+function formatQuotasPlain(quotas: QuotasResponse): string {
+  const remaining = quotas.subscription.limit - quotas.subscription.requests;
+  const percentUsed = Math.round(
+    (quotas.subscription.requests / quotas.subscription.limit) * 100,
+  );
+
+  return [
+    "Synthetic API Quotas",
+    "",
+    `Usage: ${percentUsed}%`,
+    `Limit: ${quotas.subscription.limit.toLocaleString()} requests`,
+    `Used: ${quotas.subscription.requests.toLocaleString()} requests`,
+    `Remaining: ${remaining.toLocaleString()} requests`,
+    "",
+    `Renews: ${quotas.subscription.renewsAt} (${formatRelativeTime(new Date(quotas.subscription.renewsAt))})`,
+  ].join("\n");
+}
+
+function formatRelativeTime(date: Date): string {
+  const now = new Date();
+  const diffMs = date.getTime() - now.getTime();
+
+  if (diffMs <= 0) {
+    return "renews soon";
+  }
+
+  const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
+  const diffMinutes = Math.ceil(diffMs / (1000 * 60));
+  const diffHours = Math.ceil(diffMs / (1000 * 60 * 60));
+  const diffDays = Math.ceil(diffMs / (1000 * 60 * 60 * 24));
+
+  if (diffMinutes < 60) {
+    return rtf.format(diffMinutes, "minute");
+  } else if (diffHours < 24) {
+    return rtf.format(diffHours, "hour");
+  } else if (diffDays < 30) {
+    return rtf.format(diffDays, "day");
+  } else if (diffDays < 365) {
+    const months = Math.floor(diffDays / 30);
+    return rtf.format(months, "month");
+  } else {
+    const years = Math.floor(diffDays / 365);
+    return rtf.format(years, "year");
+  }
+}

package/src/components/quotas-display.ts

@@ -0,0 +1,139 @@
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { DynamicBorder } from "@mariozechner/pi-coding-agent";
+import { type Component, Container, Text } from "@mariozechner/pi-tui";
+import type { QuotasResponse } from "../types/quotas.js";
+
+export class QuotasDisplayComponent implements Component {
+  private container: Container;
+
+  constructor(theme: Theme, quotas: QuotasResponse) {
+    this.container = new Container();
+    const border = new DynamicBorder((s: string) => theme.fg("accent", s));
+
+    this.container.addChild(border);
+    this.container.addChild(
+      new Text(theme.fg("accent", theme.bold(" Synthetic API Quotas ")), 1, 0),
+    );
+    this.container.addChild(new Text("", 0, 0));
+
+    const remaining = quotas.subscription.limit - quotas.subscription.requests;
+    const percentUsed = Math.round(
+      (quotas.subscription.requests / quotas.subscription.limit) * 100,
+    );
+
+    // Usage bar: left side = used (colored by severity), right side = remaining (neutral)
+    const barWidth = 40;
+    const usedWidth = Math.round((percentUsed / 100) * barWidth);
+    const remainingWidth = barWidth - usedWidth;
+
+    let bar: string;
+    if (usedWidth >= barWidth) {
+      bar = theme.fg("error", "█".repeat(barWidth));
+    } else if (percentUsed > 75) {
+      // High usage: used is warning, remaining is dim
+      bar =
+        theme.fg("warning", "█".repeat(usedWidth)) +
+        theme.fg("dim", "█".repeat(remainingWidth));
+    } else {
+      // Normal usage: used is success, remaining is dim
+      bar =
+        theme.fg("success", "█".repeat(usedWidth)) +
+        theme.fg("dim", "█".repeat(remainingWidth));
+    }
+
+    this.container.addChild(new Text(`  ${theme.bold("Usage")}`, 1, 0));
+    this.container.addChild(new Text(`  ${bar} ${percentUsed}%`, 1, 0));
+    this.container.addChild(new Text("", 0, 0));
+
+    // Numbers - aligned columns
+    const limitStr = quotas.subscription.limit.toLocaleString();
+    const usedStr = quotas.subscription.requests.toLocaleString();
+    const remainingStr = remaining.toLocaleString();
+    const maxValueWidth = Math.max(
+      limitStr.length,
+      usedStr.length,
+      remainingStr.length,
+    );
+
+    this.container.addChild(
+      new Text(
+        `  ${theme.fg("muted", "Limit:")}     ${limitStr.padStart(maxValueWidth, " ")} requests`,
+        1,
+        0,
+      ),
+    );
+    this.container.addChild(
+      new Text(
+        `  ${theme.fg("muted", "Used:")}      ${usedStr.padStart(maxValueWidth, " ")} requests`,
+        1,
+        0,
+      ),
+    );
+    this.container.addChild(
+      new Text(
+        `  ${theme.fg("muted", "Remaining:")} ${theme.fg(
+          remaining > 0 ? "success" : "error",
+          remainingStr.padStart(maxValueWidth, " "),
+        )} requests`,
+        1,
+        0,
+      ),
+    );
+    this.container.addChild(new Text("", 0, 0));
+
+    // Renewal date - ISO8601 with relative time
+    const renewsAt = new Date(quotas.subscription.renewsAt);
+    const isoStr = quotas.subscription.renewsAt;
+    const relativeStr = formatRelativeTime(renewsAt);
+
+    this.container.addChild(
+      new Text(
+        `  ${theme.fg("muted", "Renews:")}    ${isoStr} (${relativeStr})`,
+        1,
+        0,
+      ),
+    );
+
+    this.container.addChild(new Text("", 0, 0));
+    this.container.addChild(
+      new Text(theme.fg("dim", "  Press any key to close"), 1, 0),
+    );
+    this.container.addChild(border);
+  }
+
+  render(width: number): string[] {
+    return this.container.render(width);
+  }
+
+  invalidate(): void {
+    this.container.invalidate();
+  }
+}
+
+function formatRelativeTime(date: Date): string {
+  const now = new Date();
+  const diffMs = date.getTime() - now.getTime();
+
+  if (diffMs <= 0) {
+    return "renews soon";
+  }
+
+  const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
+  const diffMinutes = Math.ceil(diffMs / (1000 * 60));
+  const diffHours = Math.ceil(diffMs / (1000 * 60 * 60));
+  const diffDays = Math.ceil(diffMs / (1000 * 60 * 60 * 24));
+
+  if (diffMinutes < 60) {
+    return rtf.format(diffMinutes, "minute");
+  } else if (diffHours < 24) {
+    return rtf.format(diffHours, "hour");
+  } else if (diffDays < 30) {
+    return rtf.format(diffDays, "day");
+  } else if (diffDays < 365) {
+    const months = Math.floor(diffDays / 30);
+    return rtf.format(months, "month");
+  } else {
+    const years = Math.floor(diffDays / 365);
+    return rtf.format(years, "year");
+  }
+}

package/src/components/quotas-error.ts

@@ -0,0 +1,32 @@
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { DynamicBorder } from "@mariozechner/pi-coding-agent";
+import { type Component, Container, Text } from "@mariozechner/pi-tui";
+
+export class QuotasErrorComponent implements Component {
+  private container: Container;
+
+  constructor(theme: Theme, message: string) {
+    this.container = new Container();
+    const border = new DynamicBorder((s: string) => theme.fg("accent", s));
+
+    this.container.addChild(border);
+    this.container.addChild(
+      new Text(theme.fg("accent", theme.bold(" Synthetic API Quotas ")), 1, 0),
+    );
+    this.container.addChild(new Text("", 0, 0));
+    this.container.addChild(new Text(theme.fg("error", `  ${message}`), 1, 0));
+    this.container.addChild(new Text("", 0, 0));
+    this.container.addChild(
+      new Text(theme.fg("dim", "  Press any key to close"), 1, 0),
+    );
+    this.container.addChild(border);
+  }
+
+  render(width: number): string[] {
+    return this.container.render(width);
+  }
+
+  invalidate(): void {
+    this.container.invalidate();
+  }
+}

package/src/components/quotas-loading.ts

@@ -0,0 +1,30 @@
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { DynamicBorder } from "@mariozechner/pi-coding-agent";
+import { type Component, Container, Text } from "@mariozechner/pi-tui";
+
+export class QuotasLoadingComponent implements Component {
+  private container: Container;
+
+  constructor(theme: Theme) {
+    this.container = new Container();
+    const border = new DynamicBorder((s: string) => theme.fg("accent", s));
+
+    this.container.addChild(border);
+    this.container.addChild(
+      new Text(theme.fg("accent", theme.bold(" Synthetic API Quotas ")), 1, 0),
+    );
+    this.container.addChild(new Text("", 0, 0));
+    this.container.addChild(
+      new Text(theme.fg("dim", "  Loading quotas..."), 1, 0),
+    );
+    this.container.addChild(border);
+  }
+
+  render(width: number): string[] {
+    return this.container.render(width);
+  }
+
+  invalidate(): void {
+    this.container.invalidate();
+  }
+}

package/src/index.ts

@@ -1,6 +1,14 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerQuotasCommand } from "./commands/quotas.js";
 import { registerSyntheticProvider } from "./providers/index.js";
+import { registerSyntheticWebSearchTool } from "./tools/search.js";
 
-export default function (pi: ExtensionAPI) {
+export default async function (pi: ExtensionAPI) {
   registerSyntheticProvider(pi);
+
+  // Only register quotas command and web search tool if API key is available
+  if (process.env.SYNTHETIC_API_KEY) {
+    registerQuotasCommand(pi);
+    await registerSyntheticWebSearchTool(pi);
+  }
 }

package/src/tools/search.ts

@@ -0,0 +1,243 @@
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  ToolRenderResultOptions,
+} from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { type Static, Type } from "@sinclair/typebox";
+
+// Types
+interface SyntheticSearchResult {
+  url: string;
+  title: string;
+  text: string;
+  published: string;
+}
+
+interface SyntheticSearchResponse {
+  results: SyntheticSearchResult[];
+}
+
+interface WebSearchDetails {
+  results?: SyntheticSearchResult[];
+  query?: string;
+  error?: string;
+  isError?: boolean;
+}
+
+// Schema
+const SearchParams = Type.Object({
+  query: Type.String({
+    description: "The search query. Be specific for best results.",
+  }),
+});
+
+type SearchParamsType = Static<typeof SearchParams>;
+
+// Check if API key has subscription access by calling usage endpoint
+// Subscription keys have content in the response, usage-based keys return empty array
+async function hasSubscriptionAccess(apiKey: string): Promise<boolean> {
+  try {
+    const response = await fetch("https://api.synthetic.new/v2/usage", {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    });
+
+    if (!response.ok) {
+      return false;
+    }
+
+    const data = await response.json();
+    // Subscription keys have content in the response array
+    return Array.isArray(data) && data.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+// Tool Registration
+export async function registerSyntheticWebSearchTool(pi: ExtensionAPI) {
+  // Check for API key
+  const apiKey = process.env.SYNTHETIC_API_KEY;
+  if (!apiKey) {
+    return;
+  }
+
+  // Only register if user has subscription access (search is subscription-only)
+  const hasAccess = await hasSubscriptionAccess(apiKey);
+  if (!hasAccess) {
+    return;
+  }
+
+  pi.registerTool<typeof SearchParams, WebSearchDetails>({
+    name: "synthetic_web_search",
+    label: "Synthetic: Web Search",
+    description:
+      "Search the web using Synthetic's zero-data-retention API. Returns search results with titles, URLs, content snippets, and publication dates. Use for finding documentation, articles, recent information, or any web content. Results are fresh and not cached by Synthetic.",
+    parameters: SearchParams,
+
+    async execute(
+      _toolCallId: string,
+      params: SearchParamsType,
+      signal: AbortSignal | undefined,
+      onUpdate: (result: AgentToolResult<WebSearchDetails>) => void,
+      _ctx: ExtensionContext,
+    ): Promise<AgentToolResult<WebSearchDetails>> {
+      // Check for API key
+      const apiKey = process.env.SYNTHETIC_API_KEY;
+      if (!apiKey) {
+        const error = "SYNTHETIC_API_KEY environment variable is required";
+        return {
+          content: [{ type: "text", text: `Error: ${error}` }],
+          details: { error, isError: true },
+        };
+      }
+
+      // Send progress update
+      onUpdate({
+        content: [{ type: "text", text: "Searching..." }],
+        details: { query: params.query },
+      });
+
+      try {
+        // Make API request
+        const response = await fetch("https://api.synthetic.new/v2/search", {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ query: params.query }),
+          signal,
+        });
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          const error = `Search API error: ${response.status} ${errorText}`;
+          return {
+            content: [{ type: "text", text: `Error: ${error}` }],
+            details: { error, isError: true },
+          };
+        }
+
+        // Parse response
+        let data: SyntheticSearchResponse;
+        try {
+          data = await response.json();
+        } catch (parseError) {
+          const error =
+            parseError instanceof Error
+              ? `Failed to parse search results: ${parseError.message}`
+              : "Failed to parse search results";
+          return {
+            content: [{ type: "text", text: `Error: ${error}` }],
+            details: { error, isError: true },
+          };
+        }
+
+        // Format results for LLM
+        let content = `Found ${data.results.length} result(s):\n\n`;
+        for (const result of data.results) {
+          content += `## ${result.title}\n`;
+          content += `URL: ${result.url}\n`;
+          content += `Published: ${result.published}\n`;
+          content += `\n${result.text}\n`;
+          content += "\n---\n\n";
+        }
+
+        return {
+          content: [{ type: "text", text: content }],
+          details: {
+            results: data.results,
+            query: params.query,
+          },
+        };
+      } catch (error) {
+        // Handle abort signal
+        if (error instanceof Error && error.name === "AbortError") {
+          return {
+            content: [{ type: "text", text: "Search cancelled" }],
+            details: { query: params.query },
+          };
+        }
+
+        // Handle other errors
+        const message =
+          error instanceof Error ? error.message : "Unknown error occurred";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          details: { error: message, isError: true },
+        };
+      }
+    },
+
+    renderCall(args: SearchParamsType, theme: Theme): Text {
+      let text = theme.fg("toolTitle", theme.bold("Synthetic: WebSearch "));
+      text += theme.fg("accent", `"${args.query}"`);
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(
+      result: AgentToolResult<WebSearchDetails>,
+      options: ToolRenderResultOptions,
+      theme: Theme,
+    ): Text {
+      const { expanded, isPartial } = options;
+
+      // Handle partial/loading state
+      if (isPartial) {
+        const text =
+          result.content?.[0]?.type === "text"
+            ? result.content[0].text
+            : "Searching...";
+        return new Text(theme.fg("dim", text), 0, 0);
+      }
+
+      const details = result.details;
+
+      // Handle error state
+      if (details?.isError) {
+        const errorMsg =
+          result.content?.[0]?.type === "text"
+            ? result.content[0].text
+            : "Error occurred";
+        return new Text(theme.fg("error", errorMsg), 0, 0);
+      }
+
+      // Handle success state
+      const results = details?.results || [];
+      let text = theme.fg("success", `✓ Found ${results.length} result(s)`);
+
+      // Collapsed view
+      if (!expanded && results.length > 0) {
+        const first = results[0];
+        text += `\n  ${theme.fg("dim", `${first.title}`)}`;
+        if (results.length > 1) {
+          text += theme.fg("dim", ` (${results.length - 1} more)`);
+        }
+        text += theme.fg("muted", ` [Ctrl+O to expand]`);
+      }
+
+      // Expanded view
+      if (expanded) {
+        for (const r of results) {
+          text += `\n\n${theme.fg("accent", theme.bold(r.title))}`;
+          text += `\n${theme.fg("dim", r.url)}`;
+          if (r.text) {
+            const preview = r.text.slice(0, 200);
+            text += `\n${theme.fg("muted", preview)}`;
+            if (r.text.length > 200) {
+              text += theme.fg("dim", "...");
+            }
+          }
+        }
+      }
+
+      return new Text(text, 0, 0);
+    },
+  });
+}

package/src/types/quotas.ts

@@ -0,0 +1,7 @@
+export interface QuotasResponse {
+  subscription: {
+    limit: number;
+    requests: number;
+    renewsAt: string;
+  };
+}