@tokentop/ttop 0.5.0 → 0.6.1

package/src/plugins/notifications/terminal-bell.ts

@@ -4,6 +4,80 @@ import type {
   NotificationPlugin,
 } from "@tokentop/plugin-sdk";
 
+const SEVERITY_ORDER = ["info", "warning", "critical"];
+
+/**
+ * Write directly to stderr so the escape sequences bypass OpenTUI's
+ * stdout render pipeline. Most terminals still interpret BEL and OSC
+ * sequences arriving on fd 2.
+ */
+function writeEsc(data: string): void {
+  process.stderr.write(data);
+}
+
+/**
+ * OSC 777 (notify;title;body) — supported by iTerm2, Kitty, WezTerm, rxvt-unicode.
+ * OSC 9 (notify;body)         — supported by Windows Terminal, ConEmu.
+ * BEL (\x07)                  — universal fallback (if terminal has bell enabled).
+ *
+ * We send all three; unsupported sequences are silently ignored.
+ */
+function sendDesktopNotification(title: string, body: string): void {
+  writeEsc(`\x1b]777;notify;${title};${body}\x07`);
+  writeEsc(`\x1b]9;${title}: ${body}\x07`);
+  writeEsc("\x07");
+}
+
+/**
+ * macOS: afplay with system sounds (Ping, Funk, Glass, etc.)
+ * Linux: paplay → aplay → canberra-gtk-play (first available)
+ *
+ * Fire-and-forget — errors are silently ignored so a missing
+ * sound binary never breaks notifications.
+ */
+const SEVERITY_SOUNDS: Record<string, string> = {
+  critical: "Funk.aiff",
+  warning: "Ping.aiff",
+  info: "Pop.aiff",
+};
+
+function playSystemSound(severity: string): void {
+  const platform = process.platform;
+
+  if (platform === "darwin") {
+    const sound = SEVERITY_SOUNDS[severity] ?? "Ping.aiff";
+    Bun.spawn(["afplay", `/System/Library/Sounds/${sound}`], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    return;
+  }
+
+  if (platform === "linux") {
+    const xdgSound =
+      severity === "critical"
+        ? "dialog-error"
+        : severity === "warning"
+          ? "dialog-warning"
+          : "dialog-information";
+
+    Bun.spawn(["canberra-gtk-play", "-i", xdgSound], {
+      stdout: "ignore",
+      stderr: "ignore",
+    }).exited.then((code) => {
+      if (code !== 0) {
+        Bun.spawn(["paplay", "/usr/share/sounds/freedesktop/stereo/bell.oga"], {
+          stdout: "ignore",
+          stderr: "ignore",
+        });
+      }
+    });
+    return;
+  }
+
+  // Windows / other — BEL only (already sent via sendDesktopNotification)
+}
+
 export const terminalBellPlugin: NotificationPlugin = {
   apiVersion: 2,
   id: "terminal-bell",
@@ -12,7 +86,7 @@ export const terminalBellPlugin: NotificationPlugin = {
   version: "1.0.0",
 
   meta: {
-    description: "Simple terminal bell (BEL character) for alerts",
+    description: "Desktop notification + system sound alerts",
   },
 
   permissions: {},
@@ -50,30 +124,20 @@ export const terminalBellPlugin: NotificationPlugin = {
   },
 
   async notify(ctx: NotificationContext, event: NotificationEvent): Promise<void> {
-    const severityOrder = ["info", "warning", "critical"];
     const minSeverity = (ctx.config.minSeverity as string) ?? "warning";
 
-    if (severityOrder.indexOf(event.severity) < severityOrder.indexOf(minSeverity)) {
+    if (SEVERITY_ORDER.indexOf(event.severity) < SEVERITY_ORDER.indexOf(minSeverity)) {
       return;
     }
 
-    const bellCount = event.severity === "critical" ? 3 : 1;
-
-    for (let i = 0; i < bellCount; i++) {
-      process.stdout.write("\x07");
-      if (i < bellCount - 1) {
-        await sleep(200);
-      }
-    }
+    sendDesktopNotification(event.title, event.message);
+    playSystemSound(event.severity);
   },
 
   async test(ctx: NotificationContext): Promise<boolean> {
     ctx.logger.info("Testing terminal bell...");
-    process.stdout.write("\x07");
+    sendDesktopNotification("tokentop", "Test notification");
+    playSystemSound("warning");
     return true;
   },
 };
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/src/plugins/notifications/visual-flash.ts

@@ -12,7 +12,7 @@ export const visualFlashPlugin: NotificationPlugin = {
   version: "1.0.0",
 
   meta: {
-    description: "Visual screen flash using ANSI escape sequences",
+    description: "Visual screen flash for alerts (rendered via TUI overlay)",
   },
 
   permissions: {},
@@ -27,7 +27,7 @@ export const visualFlashPlugin: NotificationPlugin = {
     duration: {
       type: "number",
       label: "Flash duration (ms)",
-      default: 100,
+      default: 150,
       description: "Flash duration in milliseconds",
     },
   },
@@ -44,26 +44,13 @@ export const visualFlashPlugin: NotificationPlugin = {
     ctx.logger.debug("Visual flash notification plugin initialized");
   },
 
-  async notify(ctx: NotificationContext, event: NotificationEvent): Promise<void> {
-    const duration = (ctx.config.duration as number) ?? 100;
-
-    const colorCode =
-      event.severity === "critical" ? "41" : event.severity === "warning" ? "43" : "42";
-
-    process.stdout.write(`\x1b[${colorCode}m`);
-    await sleep(duration);
-    process.stdout.write("\x1b[0m");
+  async notify(_ctx: NotificationContext, _event: NotificationEvent): Promise<void> {
+    // Flash is handled by the NotificationFlash React component via
+    // notificationBus.flashHandler — raw ANSI escapes conflict with OpenTUI.
   },
 
   async test(ctx: NotificationContext): Promise<boolean> {
     ctx.logger.info("Testing visual flash...");
-    process.stdout.write("\x1b[44m");
-    await sleep(100);
-    process.stdout.write("\x1b[0m");
     return true;
   },
 };
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/src/plugins/plugin-host.test.ts

@@ -0,0 +1,197 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { getPluginHealth, resetAllCircuits, safeInvoke } from "./plugin-host.ts";
+
+afterEach(() => {
+  resetAllCircuits();
+});
+
+// ---------------------------------------------------------------------------
+// Baseline behaviour (no isFailure)
+// ---------------------------------------------------------------------------
+
+describe("safeInvoke — baseline", () => {
+  test("returns ok:true on success", async () => {
+    const result = await safeInvoke("test-plugin", "test", async () => 42);
+    expect(result).toEqual({ ok: true, value: 42 });
+  });
+
+  test("returns ok:false on thrown error", async () => {
+    const result = await safeInvoke("test-plugin", "test", async () => {
+      throw new Error("boom");
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toBe("boom");
+      expect(result.circuitOpen).toBe(false);
+    }
+  });
+
+  test("increments failure count on thrown errors", async () => {
+    for (let i = 0; i < 3; i++) {
+      await safeInvoke("fail-plugin", "test", async () => {
+        throw new Error("oops");
+      });
+    }
+    const health = getPluginHealth("fail-plugin");
+    expect(health.consecutiveFailures).toBe(3);
+    expect(health.totalFailures).toBe(3);
+  });
+
+  test("resets failure count on success", async () => {
+    // Fail twice
+    for (let i = 0; i < 2; i++) {
+      await safeInvoke("reset-plugin", "test", async () => {
+        throw new Error("fail");
+      });
+    }
+    expect(getPluginHealth("reset-plugin").consecutiveFailures).toBe(2);
+
+    // Succeed once — should reset
+    await safeInvoke("reset-plugin", "test", async () => "ok");
+    expect(getPluginHealth("reset-plugin").consecutiveFailures).toBe(0);
+  });
+
+  test("trips circuit after 5 consecutive failures", async () => {
+    for (let i = 0; i < 5; i++) {
+      await safeInvoke("trip-plugin", "test", async () => {
+        throw new Error("fail");
+      });
+    }
+    const health = getPluginHealth("trip-plugin");
+    expect(health.healthy).toBe(false);
+    expect(health.disabledUntil).not.toBeNull();
+
+    // Next call should be short-circuited
+    const result = await safeInvoke("trip-plugin", "test", async () => "ok");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.circuitOpen).toBe(true);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isFailure predicate (the new feature)
+// ---------------------------------------------------------------------------
+
+interface MockUsage {
+  value: number;
+  error?: string;
+  rateLimited?: boolean;
+}
+
+describe("safeInvoke — isFailure predicate", () => {
+  test("counts logical failures when isFailure returns true", async () => {
+    const isFailure = (v: MockUsage) => !!v.error && !v.rateLimited;
+
+    const result = await safeInvoke(
+      "logical-fail",
+      "fetchUsage",
+      async () => ({ value: 0, error: "API error: 500 Internal Server Error" }),
+      { isFailure },
+    );
+
+    // Still returns ok:true so caller can inspect the error details
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.error).toContain("500");
+    }
+
+    // But the circuit breaker counted it as a failure
+    const health = getPluginHealth("logical-fail");
+    expect(health.consecutiveFailures).toBe(1);
+    expect(health.totalFailures).toBe(1);
+  });
+
+  test("does NOT count rate-limited responses as failures", async () => {
+    const isFailure = (v: MockUsage) => !!v.error && !v.rateLimited;
+
+    const result = await safeInvoke(
+      "rate-limit",
+      "fetchUsage",
+      async () => ({
+        value: 0,
+        error: "Rate limited. Retry after 300s.",
+        rateLimited: true,
+      }),
+      { isFailure },
+    );
+
+    expect(result.ok).toBe(true);
+    const health = getPluginHealth("rate-limit");
+    expect(health.consecutiveFailures).toBe(0);
+    expect(health.totalFailures).toBe(0);
+  });
+
+  test("resets failures after a true success", async () => {
+    const isFailure = (v: MockUsage) => !!v.error;
+
+    // Fail 3 times logically
+    for (let i = 0; i < 3; i++) {
+      await safeInvoke(
+        "reset-after-logical",
+        "fetchUsage",
+        async () => ({ value: 0, error: "fail" }),
+        { isFailure },
+      );
+    }
+    expect(getPluginHealth("reset-after-logical").consecutiveFailures).toBe(3);
+
+    // Succeed — should reset
+    await safeInvoke("reset-after-logical", "fetchUsage", async () => ({ value: 42 }), {
+      isFailure,
+    });
+    expect(getPluginHealth("reset-after-logical").consecutiveFailures).toBe(0);
+  });
+
+  test("trips circuit after 5 consecutive logical failures", async () => {
+    const isFailure = (v: MockUsage) => !!v.error;
+
+    for (let i = 0; i < 5; i++) {
+      await safeInvoke(
+        "trip-logical",
+        "fetchUsage",
+        async () => ({ value: 0, error: `fail ${i}` }),
+        { isFailure },
+      );
+    }
+
+    const health = getPluginHealth("trip-logical");
+    expect(health.healthy).toBe(false);
+    expect(health.consecutiveFailures).toBe(5);
+    expect(health.disabledUntil).not.toBeNull();
+  });
+
+  test("mixes thrown errors and logical failures for circuit breaker", async () => {
+    const isFailure = (v: MockUsage) => !!v.error;
+
+    // 3 logical failures
+    for (let i = 0; i < 3; i++) {
+      await safeInvoke("mixed-fail", "fetchUsage", async () => ({ value: 0, error: "logical" }), {
+        isFailure,
+      });
+    }
+
+    // 2 thrown errors
+    for (let i = 0; i < 2; i++) {
+      await safeInvoke("mixed-fail", "fetchUsage", async () => {
+        throw new Error("thrown");
+      });
+    }
+
+    // Total: 5 consecutive failures → circuit should trip
+    const health = getPluginHealth("mixed-fail");
+    expect(health.consecutiveFailures).toBe(5);
+    expect(health.healthy).toBe(false);
+  });
+
+  test("does not treat successful value as failure when isFailure returns false", async () => {
+    const result = await safeInvoke("success-check", "fetchUsage", async () => ({ value: 42 }), {
+      isFailure: (v: MockUsage) => !!v.error,
+    });
+
+    expect(result.ok).toBe(true);
+    const health = getPluginHealth("success-check");
+    expect(health.consecutiveFailures).toBe(0);
+  });
+});

package/src/plugins/plugin-host.ts

@@ -52,18 +52,41 @@ export type SafeInvokeResult<T> =
   | { ok: true; value: T }
   | { ok: false; error: Error; circuitOpen: boolean };
 
+/**
+ * Options for `safeInvoke`.
+ *
+ * @template T  The return type of the plugin method.
+ */
+export interface SafeInvokeOptions<T> {
+  /**
+   * Optional predicate that inspects a *successful* return value and decides
+   * whether it should count as a logical failure for the circuit breaker.
+   *
+   * Use this when plugins return error-carrying objects instead of throwing
+   * (e.g. `{ error: "429 Too Many Requests" }`).
+   *
+   * When the predicate returns `true`:
+   *   - The circuit breaker's failure counter is incremented
+   *   - The value is still returned as `{ ok: true, value }` so the caller
+   *     can inspect the error details
+   */
+  isFailure?: (value: T) => boolean;
+}
+
 /**
  * Safely invoke a plugin method with circuit breaker protection.
  *
  * @param pluginId  Unique plugin identifier (for circuit tracking + logging)
  * @param method    Human-readable method name (for logging, e.g. "fetchUsage")
  * @param fn        The actual async function to call
+ * @param options   Optional configuration (e.g. `isFailure` predicate)
  * @returns         `{ ok: true, value }` or `{ ok: false, error, circuitOpen }`
  */
 export async function safeInvoke<T>(
   pluginId: string,
   method: string,
   fn: () => Promise<T>,
+  options?: SafeInvokeOptions<T>,
 ): Promise<SafeInvokeResult<T>> {
   const circuit = getCircuit(pluginId);
   const log = createPluginLogger(pluginId);
@@ -91,7 +114,28 @@ export async function safeInvoke<T>(
   try {
     const value = await fn();
 
-    // Success — reset consecutive failures
+    // Check for logical failures (e.g. provider returned { error: "..." })
+    if (options?.isFailure?.(value)) {
+      circuit.consecutiveFailures++;
+      circuit.totalFailures++;
+      circuit.lastFailureAt = Date.now();
+
+      log.warn(
+        `${method} returned logical failure (${circuit.consecutiveFailures}/${MAX_CONSECUTIVE_FAILURES})`,
+      );
+
+      if (circuit.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+        circuit.disabledUntil = Date.now() + COOLDOWN_MS;
+        log.error(
+          `Circuit OPEN — plugin disabled for ${COOLDOWN_MS / 1000}s after ${circuit.consecutiveFailures} consecutive failures`,
+        );
+      }
+
+      // Still return the value — caller needs the error details
+      return { ok: true, value };
+    }
+
+    // True success — reset consecutive failures
     if (circuit.consecutiveFailures > 0) {
       log.info(
         `${method} succeeded — resetting circuit breaker (was at ${circuit.consecutiveFailures} failures)`,

package/src/plugins/providers/anthropic.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  Credentials,
+  PluginHttpClient,
+  PluginLogger,
+  ProviderFetchContext,
+} from "@tokentop/plugin-sdk";
+import { anthropicPlugin } from "./anthropic.ts";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createMockLogger(): PluginLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+  };
+}
+
+function createMockHttpClient(response: {
+  status: number;
+  statusText?: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+}): PluginHttpClient {
+  return {
+    fetch: async () =>
+      new Response(JSON.stringify(response.body ?? {}), {
+        status: response.status,
+        statusText: response.statusText ?? "",
+        headers: new Headers(response.headers ?? {}),
+      }),
+  };
+}
+
+function createFetchContext(
+  overrides: { http?: PluginHttpClient; credentials?: Credentials } = {},
+): ProviderFetchContext {
+  return {
+    credentials: overrides.credentials ?? {
+      oauth: {
+        accessToken: "test-token",
+        expiresAt: Date.now() + 3_600_000, // 1 hour from now
+      },
+      source: "external",
+    },
+    http: overrides.http ?? createMockHttpClient({ status: 200, body: {} }),
+    logger: createMockLogger(),
+    config: {},
+    signal: AbortSignal.timeout(5000),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 429 Rate limit handling
+// ---------------------------------------------------------------------------
+
+describe("anthropic fetchUsage — 429 rate limit", () => {
+  test("returns rateLimited:true with default 300s when retry-after is 0", async () => {
+    const http = createMockHttpClient({
+      status: 429,
+      statusText: "Too Many Requests",
+      headers: { "retry-after": "0" },
+      body: { error: { message: "Rate limited", type: "rate_limit_error" } },
+    });
+
+    const result = await anthropicPlugin.fetchUsage(createFetchContext({ http }));
+
+    expect(result.rateLimited).toBe(true);
+    expect(result.retryAfterMs).toBe(300_000); // 300s default when retry-after is 0
+    expect(result.error).toContain("Rate limited");
+    expect(result.error).toContain("300s");
+  });
+
+  test("returns rateLimited:true with parsed retry-after when positive", async () => {
+    const http = createMockHttpClient({
+      status: 429,
+      statusText: "Too Many Requests",
+      headers: { "retry-after": "60" },
+      body: { error: { message: "Rate limited", type: "rate_limit_error" } },
+    });
+
+    const result = await anthropicPlugin.fetchUsage(createFetchContext({ http }));
+
+    expect(result.rateLimited).toBe(true);
+    expect(result.retryAfterMs).toBe(60_000); // 60s parsed from header
+    expect(result.error).toContain("60s");
+  });
+
+  test("returns rateLimited:true with default 300s when no retry-after header", async () => {
+    const http = createMockHttpClient({
+      status: 429,
+      statusText: "Too Many Requests",
+      body: { error: { message: "Rate limited", type: "rate_limit_error" } },
+    });
+
+    const result = await anthropicPlugin.fetchUsage(createFetchContext({ http }));
+
+    expect(result.rateLimited).toBe(true);
+    expect(result.retryAfterMs).toBe(300_000); // 300s default
+  });
+
+  test("429 response always includes fetchedAt", async () => {
+    const before = Date.now();
+    const http = createMockHttpClient({
+      status: 429,
+      statusText: "Too Many Requests",
+      headers: { "retry-after": "10" },
+    });
+
+    const result = await anthropicPlugin.fetchUsage(createFetchContext({ http }));
+
+    expect(result.fetchedAt).toBeGreaterThanOrEqual(before);
+    expect(result.fetchedAt).toBeLessThanOrEqual(Date.now());
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Other HTTP error codes (regression — should NOT have rateLimited)
+// ---------------------------------------------------------------------------
+
+describe("anthropic fetchUsage — non-429 errors", () => {
+  test("401 returns error without rateLimited", async () => {
+    const http = createMockHttpClient({
+      status: 401,
+      statusText: "Unauthorized",
+    });
+
+    const result = await anthropicPlugin.fetchUsage(createFetchContext({ http }));
+
+    expect(result.error).toContain("expired or invalid");
+    expect(result.rateLimited).toBeUndefined();
+    expect(result.retryAfterMs).toBeUndefined();
+  });
+
+  test("403 returns error without rateLimited", async () => {
+    const http = createMockHttpClient({
+      status: 403,
+      statusText: "Forbidden",
+    });
+
+    const result = await anthropicPlugin.fetchUsage(createFetchContext({ http }));
+
+    expect(result.error).toContain("lacks required scope");
+    expect(result.rateLimited).toBeUndefined();
+  });
+
+  test("500 returns generic error without rateLimited", async () => {
+    const http = createMockHttpClient({
+      status: 500,
+      statusText: "Internal Server Error",
+    });
+
+    const result = await anthropicPlugin.fetchUsage(createFetchContext({ http }));
+
+    expect(result.error).toContain("500");
+    expect(result.rateLimited).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Successful responses
+// ---------------------------------------------------------------------------
+
+describe("anthropic fetchUsage — success", () => {
+  test("parses usage data correctly", async () => {
+    const http = createMockHttpClient({
+      status: 200,
+      body: {
+        five_hour: { utilization: 45.5, resets_at: "2026-03-08T15:00:00Z" },
+        seven_day: { utilization: 72.3, resets_at: "2026-03-10T00:00:00Z" },
+      },
+    });
+
+    const result = await anthropicPlugin.fetchUsage(createFetchContext({ http }));
+
+    expect(result.error).toBeUndefined();
+    expect(result.rateLimited).toBeUndefined();
+    expect(result.limits?.primary?.usedPercent).toBe(46); // rounded from 45.5
+    expect(result.limits?.primary?.label).toBe("5-hour window");
+    expect(result.limits?.secondary?.usedPercent).toBe(72); // rounded from 72.3
+    expect(result.limits?.secondary?.label).toBe("7-day window");
+  });
+
+  test("returns API plan type for apiKey-only credentials", async () => {
+    const result = await anthropicPlugin.fetchUsage(
+      createFetchContext({
+        credentials: {
+          apiKey: "sk-test-key",
+          source: "env",
+        },
+      }),
+    );
+
+    expect(result.planType).toBe("API");
+    expect(result.allowed).toBe(true);
+    expect(result.error).toBeUndefined();
+  });
+});

package/src/plugins/providers/anthropic.ts

@@ -234,6 +234,25 @@ export const anthropicPlugin: ProviderPlugin = {
       if (!response.ok) {
         log.warn("Failed to fetch Anthropic usage", { status: response.status });
 
+        if (response.status === 429) {
+          const retryAfterHeader = response.headers.get("retry-after");
+          const parsedRetryAfter = retryAfterHeader
+            ? Number.parseInt(retryAfterHeader, 10)
+            : Number.NaN;
+          const retrySec =
+            Number.isFinite(parsedRetryAfter) && parsedRetryAfter > 0 ? parsedRetryAfter : 300;
+          log.warn("Rate limited by Anthropic API", {
+            retryAfterHeader,
+            retryAfterSec: retrySec,
+          });
+          return {
+            fetchedAt: Date.now(),
+            error: `Rate limited. Retry after ${retrySec}s.`,
+            rateLimited: true,
+            retryAfterMs: retrySec * 1000,
+          };
+        }
+
         if (response.status === 401) {
           return {
             fetchedAt: Date.now(),

package/src/plugins/providers/antigravity.ts

@@ -241,6 +241,22 @@ export const antigravityPlugin: ProviderPlugin = {
           const errorText = await response.text().catch(() => "");
           lastError = `${response.status} ${response.statusText}: ${errorText.slice(0, 100)}`;
 
+          if (response.status === 429) {
+            const retryAfterHeader = response.headers.get("retry-after");
+            const parsedRetryAfter = retryAfterHeader
+              ? Number.parseInt(retryAfterHeader, 10)
+              : Number.NaN;
+            const retrySec =
+              Number.isFinite(parsedRetryAfter) && parsedRetryAfter > 0 ? parsedRetryAfter : 300;
+            log.warn("Rate limited by Google API", { retryAfterHeader, retryAfterSec: retrySec });
+            return {
+              fetchedAt: Date.now(),
+              error: `Rate limited. Retry after ${retrySec}s.`,
+              rateLimited: true,
+              retryAfterMs: retrySec * 1000,
+            };
+          }
+
           if (response.status === 401) {
             return {
               fetchedAt: Date.now(),