@tokentop/ttop 0.4.0 → 0.6.0

package/src/plugins/themes/tokyo-night.ts

@@ -1,4 +1,4 @@
-import type { ThemePlugin } from "../types/theme.ts";
+import type { ThemePlugin } from "@tokentop/plugin-sdk";
 
 export const tokyoNightTheme: ThemePlugin = {
   apiVersion: 2,

package/src/plugins/update-checker.ts

@@ -9,7 +9,7 @@
  * skipped because they have no registry entry to compare against.
  */
 
-import type { PluginType } from "./types/base.ts";
+import type { PluginType } from "@tokentop/plugin-sdk";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -60,7 +60,7 @@ function isNewer(current: string, latest: string): boolean {
  * Uses the abbreviated metadata endpoint for minimal payload.
  */
 async function fetchLatestVersion(packageName: string): Promise<string> {
-  const url = `https://registry.npmjs.org/${encodeURIComponent(packageName).replace("%40", "@")}`;
+  const url = `https://registry.npmjs.org/${encodeURIComponent(packageName).replaceAll("%40", "@")}`;
   const res = await fetch(url, {
     headers: { Accept: "application/vnd.npm.install-v1+json" },
     signal: AbortSignal.timeout(8_000),

package/src/pricing/estimator.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import type { ModelPricing } from "@/plugins/types/provider.ts";
+import type { ModelPricing } from "@tokentop/plugin-sdk";
 import { estimateCost, estimateSessionCost, formatCost, formatTokenCount } from "./estimator.ts";
 
 describe("estimateCost()", () => {

package/src/pricing/estimator.ts

@@ -1,4 +1,4 @@
-import type { CostBreakdown, ModelPricing } from "@/plugins/types/provider.ts";
+import type { CostBreakdown, ModelPricing } from "@tokentop/plugin-sdk";
 
 export interface TokenUsage {
   input: number;

package/src/pricing/fallback.ts

@@ -1,4 +1,4 @@
-import type { ModelPricing } from "@/plugins/types/provider.ts";
+import type { ModelPricing } from "@tokentop/plugin-sdk";
 
 //TODO: get more up to date fallback pricing
 export const FALLBACK_PRICING: Record<string, Record<string, ModelPricing>> = {
@@ -57,6 +57,10 @@ export const FALLBACK_PRICING: Record<string, Record<string, ModelPricing>> = {
     "gemini-2.0-flash-lite": { input: 0.075, output: 0.3, source: "fallback" },
     "gemini-2.5-pro": { input: 1.25, output: 10, source: "fallback" },
     "gemini-2.5-flash": { input: 0.15, output: 0.6, source: "fallback" },
+    "gemini-3-flash-preview": { input: 0.5, output: 3, cacheRead: 0.05, source: "fallback" },
+    "gemini-3-pro-preview": { input: 2, output: 12, cacheRead: 0.2, source: "fallback" },
+    "gemini-3.1-pro-preview": { input: 2, output: 12, cacheRead: 0.2, source: "fallback" },
+    "gemini-3.1-flash-lite-preview": { input: 0.25, output: 1.5, source: "fallback" },
   },
 
   openrouter: {

package/src/pricing/index.ts

@@ -1,4 +1,4 @@
-import type { ModelPricing, ProviderPlugin, ProviderPricing } from "@/plugins/types/provider.ts";
+import type { ModelPricing, ProviderPlugin, ProviderPricing } from "@tokentop/plugin-sdk";
 import { getFallbackPricing, getFallbackProviderPricing } from "./fallback.ts";
 import {
   clearCache as clearModelsDevCache,

package/src/pricing/models-dev.ts

@@ -1,4 +1,4 @@
-import type { ModelPricing } from "@/plugins/types/provider.ts";
+import type { ModelPricing } from "@tokentop/plugin-sdk";
 
 const MODELS_DEV_API = "https://models.dev/api.json";
 const CACHE_TTL_MS = 3600000;

package/src/storage/index.ts

@@ -15,6 +15,12 @@ export {
   insertAgentSessionSnapshot,
   upsertAgentSession,
 } from "./repos/agentSessions.ts";
+export {
+  pluginStorageDelete,
+  pluginStorageGet,
+  pluginStorageHas,
+  pluginStorageSet,
+} from "./repos/pluginStorage.ts";
 export {
   getLatestProviderSnapshot,
   insertProviderSnapshot,

package/src/storage/migrations/index.ts

@@ -164,6 +164,23 @@ export const migrations: Migration[] = [
       `);
     },
   },
+  {
+    version: 2,
+    up: (db: Database) => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS plugin_storage (
+          plugin_id TEXT NOT NULL,
+          key TEXT NOT NULL,
+          value TEXT NOT NULL,
+          updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+          PRIMARY KEY (plugin_id, key)
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_plugin_storage_plugin
+          ON plugin_storage(plugin_id);
+      `);
+    },
+  },
 ];
 
 export function getCurrentVersion(db: Database): number {

package/src/storage/repos/pluginStorage.ts

@@ -0,0 +1,35 @@
+import { getDatabase } from "../db.ts";
+
+// ---------------------------------------------------------------------------
+// Plugin KV storage
+// ---------------------------------------------------------------------------
+
+export function pluginStorageGet(pluginId: string, key: string): string | null {
+  const db = getDatabase();
+  const row = db
+    .prepare("SELECT value FROM plugin_storage WHERE plugin_id = ? AND key = ?")
+    .get(pluginId, key) as { value: string } | null;
+  return row?.value ?? null;
+}
+
+export function pluginStorageSet(pluginId: string, key: string, value: string): void {
+  const db = getDatabase();
+  db.prepare(
+    `INSERT INTO plugin_storage (plugin_id, key, value, updated_at)
+     VALUES (?, ?, ?, ?)
+     ON CONFLICT(plugin_id, key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`,
+  ).run(pluginId, key, value, Math.floor(Date.now() / 1000));
+}
+
+export function pluginStorageDelete(pluginId: string, key: string): void {
+  const db = getDatabase();
+  db.prepare("DELETE FROM plugin_storage WHERE plugin_id = ? AND key = ?").run(pluginId, key);
+}
+
+export function pluginStorageHas(pluginId: string, key: string): boolean {
+  const db = getDatabase();
+  const row = db
+    .prepare("SELECT 1 FROM plugin_storage WHERE plugin_id = ? AND key = ?")
+    .get(pluginId, key);
+  return row !== null && row !== undefined;
+}

package/src/tui/App.tsx

@@ -1,7 +1,7 @@
 import { useKeyboard } from "@opentui/react";
+import type { ThemePlugin } from "@tokentop/plugin-sdk";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import * as builtinThemeExports from "@/plugins/themes/index.ts";
-import type { ThemePlugin } from "@/plugins/types/theme.ts";
 import { resolveTheme, ThemeProvider, useColors, useTheme } from "./contexts/ThemeContext.tsx";
 import {
   type BurstRecorder,
@@ -48,6 +48,7 @@ interface AppProps {
   demoSeed?: number;
   demoPreset?: DemoPreset;
   cliPlugins?: string[];
+  cliTheme?: string;
 }
 
 type View = "dashboard" | "providers" | "trends" | "projects";
@@ -55,7 +56,7 @@ type View = "dashboard" | "providers" | "trends" | "projects";
 function AppContent() {
   const renderer = useSafeRenderer();
   const colors = useColors();
-  const { theme, setTheme } = useTheme();
+  const { theme, setTheme, cliTheme } = useTheme();
   const { refreshAllProviders, isInitialized, themes } = usePlugins();
   const { info } = useLogs();
   const { toast, showToast, dismissToast } = useToastContext();
@@ -292,8 +293,10 @@ function AppContent() {
 
   useEffect(() => {
     if (themes.length === 0) return;
+    // CLI --theme flag takes priority over config
+    const themeId = cliTheme ?? config.display.theme;
     const resolved = resolveTheme(
-      config.display.theme,
+      themeId,
       config.display.colorScheme,
       themes,
       renderer?.themeMode ?? null,
@@ -301,7 +304,7 @@ function AppContent() {
     if (resolved.id !== theme.id) {
       setTheme(resolved);
     }
-  }, [themes, config.display.theme, config.display.colorScheme, renderer]);
+  }, [themes, cliTheme, config.display.theme, config.display.colorScheme, renderer]);
 
   useEffect(() => {
     if (isInitialized) {
@@ -364,23 +367,24 @@ function AppContent() {
   );
 }
 
-function ConfiguredApp({ cliPlugins }: { cliPlugins?: string[] }) {
+function ConfiguredApp({ cliPlugins, cliTheme }: { cliPlugins?: string[]; cliTheme?: string }) {
   const { config, isLoading } = useConfig();
 
   if (isLoading) {
     return null;
   }
 
-  const initialTheme = builtinThemeList.find((t) => t.id === config.display.theme);
+  const themeId = cliTheme ?? config.display.theme;
+  const initialTheme = builtinThemeList.find((t) => t.id === themeId);
   const themeProps = initialTheme ? { initialTheme } : {};
 
   return (
-    <ThemeProvider {...themeProps}>
+    <ThemeProvider {...themeProps} {...(cliTheme ? { cliTheme } : {})}>
       <TimeWindowProvider defaultWindow={config.display.defaultTimeWindow}>
         <ToastProvider>
           <PluginProvider {...(cliPlugins ? { cliPlugins } : {})}>
             <RealTimeActivityProvider>
-              <AgentSessionProvider autoRefresh={true} refreshInterval={1000}>
+              <AgentSessionProvider autoRefresh={true}>
                 <DashboardRuntimeProvider>
                   <DrawerProvider>
                     <AppContent />
@@ -401,6 +405,7 @@ export function App({
   demoSeed,
   demoPreset,
   cliPlugins,
+  cliTheme,
 }: AppProps) {
   const demoProviderProps: { demoMode: boolean; demoSeed?: number; demoPreset?: DemoPreset } = {
     demoMode,
@@ -414,7 +419,10 @@ export function App({
         <InputProvider>
           <StorageProvider>
             <ConfigProvider>
-              <ConfiguredApp {...(cliPlugins ? { cliPlugins } : {})} />
+              <ConfiguredApp
+                {...(cliPlugins ? { cliPlugins } : {})}
+                {...(cliTheme ? { cliTheme } : {})}
+              />
             </ConfigProvider>
           </StorageProvider>
         </InputProvider>

package/src/tui/components/HelpOverlay.tsx

@@ -59,7 +59,7 @@ export function HelpOverlay() {
           <text width={10} height={1} fg={colors.textMuted}>
             s
           </text>
-          <text height={1}>Sort</text>
+          <text height={1}>Sort menu</text>
         </box>
         <box flexDirection="row" height={1}>
           <text width={10} height={1} fg={colors.textMuted}>

package/src/tui/components/LimitGauge.tsx

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { getErrorCategoryDisplay, type ProviderErrorCategory } from "@/utils/error-category.ts";
 import { useColors } from "../contexts/ThemeContext.tsx";
 import { usePulse } from "../hooks/usePulse.ts";
 
@@ -8,6 +9,7 @@ interface LimitGaugeProps {
   color: string;
   ghost?: boolean;
   error?: string;
+  errorCategory?: ProviderErrorCategory;
   resetTime?: string;
   compact?: boolean;
   labelWidth?: number;
@@ -89,6 +91,7 @@ export function LimitGauge({
   color,
   ghost = false,
   error,
+  errorCategory,
   resetTime,
   compact = false,
   labelWidth = 12,
@@ -152,7 +155,12 @@ export function LimitGauge({
 
   if (error) {
     const displayLabel = truncateLabel(label, labelWidth);
-    const errorIcon = selected ? "▌" : "✗";
+
+    const display = errorCategory ? getErrorCategoryDisplay(errorCategory) : undefined;
+    const errColor = display?.isWarning ? colors.warning : colors.error;
+    const errLabel = display?.label ?? "ERR";
+    const errorIcon = selected ? "\u258C" : (display?.icon ?? "\u2717");
+
     return (
       <box
         height={1}
@@ -160,10 +168,10 @@ export function LimitGauge({
         {...(selected ? { backgroundColor: colors.borderMuted } : {})}
       >
         <text height={1}>
-          <span fg={selected ? colors.primary : colors.error}>{errorIcon} </span>
+          <span fg={selected ? colors.primary : errColor}>{errorIcon} </span>
           <span fg={selected ? colors.text : colors.text}>{displayLabel} </span>
-          <span fg={colors.error}>{"─".repeat(barWidth)}</span>
-          <span fg={colors.error}> ERR</span>
+          <span fg={errColor}>{"\u2500".repeat(barWidth)}</span>
+          <span fg={errColor}> {errLabel}</span>
         </text>
       </box>
     );

package/src/tui/components/ProviderCard.tsx

@@ -1,10 +1,12 @@
 import type { BoxRenderable } from "@opentui/core";
 import { useTerminalDimensions } from "@opentui/react";
-import { forwardRef, useCallback, useEffect, useState } from "react";
-import type { ProviderUsageData } from "@/plugins/types/provider.ts";
+import type { ProviderUsageData } from "@tokentop/plugin-sdk";
+import { forwardRef, useCallback } from "react";
+import { classifyProviderError, getErrorCategoryDisplay } from "@/utils/error-category.ts";
 import { useColors } from "../contexts/ThemeContext.tsx";
+import { usePulse } from "../hooks/usePulse.ts";
 import { SkeletonProviderContent } from "./Skeleton.tsx";
-import { useSpinner } from "./Spinner.tsx";
+import { Spinner } from "./Spinner.tsx";
 import { UsageGauge } from "./UsageGauge.tsx";
 
 interface CompactGaugeProps {
@@ -60,9 +62,11 @@ export const ProviderCard = forwardRef<BoxRenderable, ProviderCardProps>(
     const colors = useColors();
     const { width: termWidth } = useTerminalDimensions();
     const providerColor = color ?? colors.primary;
-    const spinnerFrame = useSpinner();
-
-    const [pulseStep, setPulseStep] = useState(0);
+    const pulseStep = usePulse({
+      enabled: usage?.limitReached ?? false,
+      intervalMs: 150,
+      steps: 12,
+    });
 
     const rawItems = usage?.limits?.items;
     const hasItems = rawItems && rawItems.length > 0;
@@ -78,36 +82,34 @@ export const ProviderCard = forwardRef<BoxRenderable, ProviderCardProps>(
       sortedItems.length > maxVisibleGauges ? sortedItems.slice(0, maxVisibleGauges) : sortedItems;
     const useCompactMode = visibleItems.length > 3;
 
-    useEffect(() => {
-      if (!usage?.limitReached) {
-        setPulseStep(0);
-        return;
-      }
-
-      const timer = setInterval(() => {
-        setPulseStep((p) => (p + 1) % 12);
-      }, 150);
-
-      return () => clearInterval(timer);
-    }, [usage?.limitReached]);
-
     const handleClick = useCallback(() => {
       if (onFocus) {
         onFocus();
       }
     }, [onFocus]);
 
+    const errorCategory = usage?.error ? classifyProviderError(usage.error) : undefined;
+    const errorDisplay = errorCategory ? getErrorCategoryDisplay(errorCategory) : undefined;
+
     const statusColor = !configured
       ? colors.textSubtle
       : loading
         ? colors.info
         : usage?.error
-          ? colors.error
+          ? errorDisplay?.isWarning
+            ? colors.warning
+            : colors.error
           : usage?.limitReached
             ? colors.warning
             : colors.success;
 
-    const statusIcon = !configured ? "○" : usage?.error ? "✗" : usage?.limitReached ? "!" : "●";
+    const statusIcon = !configured
+      ? "○"
+      : usage?.error
+        ? (errorDisplay?.icon ?? "✗")
+        : usage?.limitReached
+          ? "!"
+          : "●";
 
     const isInitialLoad = loading && !usage;
 
@@ -154,7 +156,11 @@ export const ProviderCard = forwardRef<BoxRenderable, ProviderCardProps>(
               <strong>{name}</strong>
             </span>
           </text>
-          <text fg={statusColor}>{configured && loading ? spinnerFrame : statusIcon}</text>
+          {configured && loading ? (
+            <Spinner color={statusColor} />
+          ) : (
+            <text fg={statusColor}>{statusIcon}</text>
+          )}
         </box>
 
         {!configured && <text fg={colors.textSubtle}>Not configured</text>}
@@ -162,7 +168,17 @@ export const ProviderCard = forwardRef<BoxRenderable, ProviderCardProps>(
         {configured && isInitialLoad && <SkeletonProviderContent />}
 
         {configured && !isInitialLoad && usage?.error && (
-          <text fg={colors.error}>{usage.error}</text>
+          <box flexDirection="column" gap={0}>
+            <text fg={errorDisplay?.isWarning ? colors.warning : colors.error}>
+              <span>
+                <bold>{errorDisplay?.label ?? "ERR"}</bold>
+              </span>
+              <span fg={colors.textMuted}> — </span>
+              <span fg={errorDisplay?.isWarning ? colors.warning : colors.error}>
+                {usage.error}
+              </span>
+            </text>
+          </box>
         )}
 
         {configured && !isInitialLoad && usage && !usage.error && (

package/src/tui/components/ProviderDetailPanel.tsx

@@ -1,4 +1,4 @@
-import type { UsageLimit } from "@/plugins/types/provider.ts";
+import type { UsageLimit } from "@tokentop/plugin-sdk";
 import type { ProviderState } from "../contexts/PluginContext.tsx";
 import { useColors } from "../contexts/ThemeContext.tsx";
 import { Sparkline } from "./Sparkline.tsx";

package/src/tui/components/ProviderLimitsPanel.tsx

@@ -1,5 +1,6 @@
 import { useTerminalDimensions } from "@opentui/react";
 import { useMemo } from "react";
+import type { ProviderErrorCategory } from "@/utils/error-category.ts";
 import { useConfig } from "../contexts/ConfigContext.tsx";
 import { useColors } from "../contexts/ThemeContext.tsx";
 import { usePulse } from "../hooks/usePulse.ts";
@@ -34,6 +35,7 @@ interface ProviderData {
   usedPercent: number;
   color: string;
   error?: string;
+  errorCategory?: ProviderErrorCategory;
   resetTime?: string;
   used?: number;
   limit?: number;
@@ -186,6 +188,7 @@ export function ProviderLimitsPanel({
               usedPercent={p.usedPercent}
               color={p.color}
               {...(p.error ? { error: p.error } : {})}
+              {...(p.errorCategory ? { errorCategory: p.errorCategory } : {})}
               compact={true}
               selected={focused && startIndex + idx === safeSelectedIndex}
               warningThreshold={warningThreshold}
@@ -269,6 +272,7 @@ export function ProviderLimitsPanel({
               usedPercent={p.usedPercent}
               color={p.color}
               {...(p.error ? { error: p.error } : {})}
+              {...(p.errorCategory ? { errorCategory: p.errorCategory } : {})}
               {...(p.resetTime ? { resetTime: p.resetTime } : {})}
               labelWidth={14}
               barWidth={12}
@@ -326,6 +330,7 @@ export function ProviderLimitsPanel({
             usedPercent={p.usedPercent}
             color={p.color}
             {...(p.error ? { error: p.error } : {})}
+            {...(p.errorCategory ? { errorCategory: p.errorCategory } : {})}
             {...(p.resetTime ? { resetTime: p.resetTime } : {})}
             labelWidth={12}
             barWidth={10}

package/src/tui/components/SessionDetailsDrawer.tsx

@@ -314,6 +314,16 @@ export function SessionDetailsDrawer({ session, onClose: _onClose }: SessionDeta
             </text>
           </box>
 
+          {session.metadata?.isEstimated === true && (
+            <box flexDirection="row" height={1} marginBottom={0}>
+              <text height={1} overflow="hidden">
+                <span fg={colors.warning}>
+                  ≈ Token data is estimated — server enrichment pending
+                </span>
+              </text>
+            </box>
+          )}
+
           {hasCacheData && (
             <box flexDirection="row" height={1} marginBottom={0}>
               <text height={1} overflow="hidden">