@tokentop/ttop 0.5.0 → 0.6.0

package/src/tui/components/SortOverlay.tsx

@@ -0,0 +1,167 @@
+import { useKeyboard } from "@opentui/react";
+import { useEffect, useState } from "react";
+import { useInputFocus } from "../contexts/InputContext.tsx";
+import { useColors } from "../contexts/ThemeContext.tsx";
+import type { SortDirection, SortFieldDef } from "../types/sort.ts";
+import { getSortDirectionIndicator } from "../types/sort.ts";
+import { ModalBackdrop, Z_INDEX } from "./ModalBackdrop.tsx";
+
+interface SortOverlayProps<F extends string = string> {
+  fields: readonly SortFieldDef<F>[];
+  currentField: F;
+  currentDirection: SortDirection;
+  onSelect: (field: F, direction: SortDirection) => void;
+  onClose: () => void;
+}
+
+export function SortOverlay<F extends string>({
+  fields,
+  currentField,
+  currentDirection,
+  onSelect,
+  onClose,
+}: SortOverlayProps<F>) {
+  const colors = useColors();
+  const { setInputFocused } = useInputFocus();
+
+  const [highlightedIndex, setHighlightedIndex] = useState(() => {
+    const idx = fields.findIndex((f) => f.id === currentField);
+    return idx === -1 ? 0 : idx;
+  });
+
+  const [pendingDirection, setPendingDirection] = useState<SortDirection>(currentDirection);
+
+  // Capture input focus to block App.tsx and view-level keyboard handlers
+  useEffect(() => {
+    setInputFocused(true);
+    return () => setInputFocused(false);
+  }, [setInputFocused]);
+
+  useKeyboard((key) => {
+    // Navigation
+    if (key.name === "up" || key.name === "k") {
+      setHighlightedIndex((prev) => (prev > 0 ? prev - 1 : fields.length - 1));
+      return;
+    }
+
+    if (key.name === "down" || key.name === "j") {
+      setHighlightedIndex((prev) => (prev < fields.length - 1 ? prev + 1 : 0));
+      return;
+    }
+
+    // Toggle direction in-place
+    if (key.name === "space" || key.sequence === " ") {
+      setPendingDirection((prev) => (prev === "asc" ? "desc" : "asc"));
+      return;
+    }
+
+    // Apply highlighted selection
+    if (key.name === "return") {
+      const field = fields[highlightedIndex];
+      if (field) {
+        onSelect(field.id, pendingDirection);
+      }
+      return;
+    }
+
+    // Cancel
+    if (key.name === "escape") {
+      onClose();
+      return;
+    }
+
+    // Number quick-select: 1-9 selects field by position
+    // If already sorting by that field, flip direction instead
+    if (key.sequence && key.sequence.length === 1) {
+      const digit = key.sequence.charCodeAt(0) - 48; // '0' = 48
+      if (digit >= 1 && digit <= fields.length) {
+        const field = fields[digit - 1];
+        if (field) {
+          const direction =
+            field.id === currentField
+              ? currentDirection === "desc"
+                ? "asc"
+                : "desc"
+              : field.defaultDirection;
+          onSelect(field.id, direction);
+        }
+        return;
+      }
+    }
+  });
+
+  return (
+    <ModalBackdrop zIndex={Z_INDEX.MODAL} onBackdropClick={onClose}>
+      <box
+        width={34}
+        flexDirection="column"
+        border
+        borderStyle="double"
+        borderColor={colors.primary}
+        backgroundColor={colors.background}
+        overflow="hidden"
+      >
+        {/* Header */}
+        <box height={1} justifyContent="center">
+          <text fg={colors.primary} height={1}>
+            Sort By
+          </text>
+        </box>
+
+        {/* Sort Fields */}
+        <box flexDirection="column">
+          {fields.map((field, index) => {
+            const isHighlighted = index === highlightedIndex;
+            const isCurrent = field.id === currentField;
+
+            const textColor = isHighlighted ? colors.background : colors.text;
+            const numberColor = isHighlighted ? colors.background : colors.textMuted;
+            const markerColor = isHighlighted ? colors.background : colors.primary;
+
+            return (
+              <box
+                key={field.id}
+                flexDirection="row"
+                height={1}
+                paddingLeft={1}
+                paddingRight={1}
+                justifyContent="space-between"
+                {...(isHighlighted ? { backgroundColor: colors.primary } : {})}
+              >
+                {/* Left: number + marker + label + direction */}
+                <text height={1}>
+                  <span fg={numberColor}>{index + 1} </span>
+                  <span fg={markerColor}>{isCurrent ? "● " : "  "}</span>
+                  <span fg={textColor}>{field.label}</span>
+                  {isHighlighted ? (
+                    <span fg={colors.warning}> {getSortDirectionIndicator(pendingDirection)}</span>
+                  ) : null}
+                </text>
+              </box>
+            );
+          })}
+        </box>
+
+        {/* Footer Hints */}
+        <box flexDirection="column" paddingLeft={1} paddingRight={1} marginTop={1}>
+          <box flexDirection="row" justifyContent="space-between" height={1}>
+            <text fg={colors.textSubtle} height={1}>
+              ↑↓ navigate
+            </text>
+            <text fg={colors.textSubtle} height={1}>
+              Space toggle
+            </text>
+          </box>
+          <box flexDirection="row" justifyContent="space-between" height={1}>
+            <text fg={colors.textSubtle} height={1}>
+              Enter apply
+            </text>
+            <text fg={colors.textSubtle} height={1}>
+              Esc cancel
+            </text>
+          </box>
+        </box>
+      </box>
+    </ModalBackdrop>
+  );
+}

package/src/tui/components/Spinner.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
+import { animationTick } from "../hooks/useAnimationTick.ts";
 
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 const FRAME_INTERVAL = 80;
@@ -9,13 +10,15 @@ interface SpinnerProps {
 
 export function Spinner({ color }: SpinnerProps) {
   const [frameIndex, setFrameIndex] = useState(0);
+  const lastAdvanceRef = useRef(Date.now());
 
   useEffect(() => {
-    const interval = setInterval(() => {
-      setFrameIndex((i) => (i + 1) % SPINNER_FRAMES.length);
-    }, FRAME_INTERVAL);
-
-    return () => clearInterval(interval);
+    return animationTick.subscribe((now) => {
+      if (now - lastAdvanceRef.current >= FRAME_INTERVAL) {
+        lastAdvanceRef.current = now;
+        setFrameIndex((i) => (i + 1) % SPINNER_FRAMES.length);
+      }
+    });
   }, []);
 
   return <text {...(color ? { fg: color } : {})}>{SPINNER_FRAMES[frameIndex]}</text>;
@@ -23,13 +26,15 @@ export function Spinner({ color }: SpinnerProps) {
 
 export function useSpinner(): string {
   const [frameIndex, setFrameIndex] = useState(0);
+  const lastAdvanceRef = useRef(Date.now());
 
   useEffect(() => {
-    const interval = setInterval(() => {
-      setFrameIndex((i) => (i + 1) % SPINNER_FRAMES.length);
-    }, FRAME_INTERVAL);
-
-    return () => clearInterval(interval);
+    return animationTick.subscribe((now) => {
+      if (now - lastAdvanceRef.current >= FRAME_INTERVAL) {
+        lastAdvanceRef.current = now;
+        setFrameIndex((i) => (i + 1) % SPINNER_FRAMES.length);
+      }
+    });
   }, []);
 
   return SPINNER_FRAMES[frameIndex] ?? "⠋";

package/src/tui/contexts/AgentSessionContext.tsx

@@ -8,7 +8,7 @@ import {
   useRef,
   useState,
 } from "react";
-import { aggregateSessionUsage } from "@/agents/aggregator.ts";
+import { aggregateSessionUsage, deduplicateAggregates } from "@/agents/aggregator.ts";
 import { priceSessions } from "@/agents/costing.ts";
 import type { AgentId, AgentInfo, AgentSessionAggregate } from "@/agents/types.ts";
 import { createPluginContext } from "@/plugins/plugin-context-factory.ts";
@@ -21,6 +21,10 @@ import { useLogs } from "./LogContext.tsx";
 import { usePlugins } from "./PluginContext.tsx";
 import { useTimeWindow } from "./TimeWindowContext.tsx";
 
+/** Polling interval when at least one session is active. */
+const ACTIVE_INTERVAL_MS = 3_000;
+/** Polling interval when all sessions are idle/historical. */
+const IDLE_INTERVAL_MS = 15_000;
 interface AgentSessionContextValue {
   sessions: AgentSessionAggregate[];
   agents: AgentInfo[];
@@ -35,14 +39,24 @@ const AgentSessionContext = createContext<AgentSessionContextValue | null>(null)
 interface AgentSessionProviderProps {
   children: ReactNode;
   autoRefresh?: boolean;
-  refreshInterval?: number;
 }
 
-export function AgentSessionProvider({
-  children,
-  autoRefresh = false,
-  refreshInterval = 30000,
-}: AgentSessionProviderProps) {
+/**
+ * Compute a lightweight fingerprint of session state.
+ * If the fingerprint hasn't changed, we skip setSessions() to avoid
+ * unnecessary React re-renders of the entire session list.
+ */
+function computeSessionFingerprint(sessions: AgentSessionAggregate[]): string {
+  // Build a compact string from the fields that actually affect the UI.
+  // This is intentionally simple — no crypto hashing needed, just string comparison.
+  let fp = `${sessions.length}:`;
+  for (const s of sessions) {
+    fp += `${s.sessionId},${s.status},${s.lastActivityAt},${s.totals.input},${s.totals.output},${s.totalCostUsd ?? 0},${s.requestCount};`;
+  }
+  return fp;
+}
+
+export function AgentSessionProvider({ children, autoRefresh = false }: AgentSessionProviderProps) {
   const [sessions, setSessions] = useState<AgentSessionAggregate[]>([]);
   const [agents, setAgents] = useState<AgentInfo[]>([]);
   const [isLoading, setIsLoading] = useState(false);
@@ -54,6 +68,7 @@ export function AgentSessionProvider({
   const { windowMs } = useTimeWindow();
   const hasBackfilled = useRef(false);
   const isRefreshingRef = useRef(false);
+  const lastFingerprintRef = useRef<string>("");
 
   const discoverAgents = useCallback(async (): Promise<AgentInfo[]> => {
     const agentPlugins = pluginRegistry.getAll("agent");
@@ -178,10 +193,34 @@ export function AgentSessionProvider({
           }
         }
 
-        const pricedSessions = await priceSessions(allAggregates);
+        // Deduplicate sessions claimed by multiple agents scanning the same directory.
+        const dedupedAggregates = deduplicateAggregates(allAggregates);
+        if (dedupedAggregates.length < allAggregates.length) {
+          debug(
+            `Deduplicated sessions: ${allAggregates.length} \u2192 ${dedupedAggregates.length}`,
+            undefined,
+            "agent-sessions",
+          );
+        }
+
+        const pricedSessions = await priceSessions(dedupedAggregates);
 
         pricedSessions.sort((a, b) => b.lastActivityAt - a.lastActivityAt);
 
+        // --- Change detection: skip React update if nothing changed ---
+        const newFingerprint = computeSessionFingerprint(pricedSessions);
+        const changed = newFingerprint !== lastFingerprintRef.current;
+        lastFingerprintRef.current = newFingerprint;
+
+        if (!changed) {
+          debug(
+            "Session refresh: no changes detected, skipping render",
+            undefined,
+            "agent-sessions",
+          );
+          return;
+        }
+
         // Persist to storage — the persistence service handles throttling
         // internally (fingerprint gate + 5-minute per-session throttle).
         // Safe to call every tick; state lives on globalThis, survives HMR.
@@ -260,18 +299,32 @@ export function AgentSessionProvider({
   useEffect(() => {
     if (!autoRefresh) return;
 
-    debug(`Setting up session refresh interval: ${refreshInterval}ms`, undefined, "agent-sessions");
+    // Adaptive polling: poll faster when sessions are active, slower when idle.
+    // The interval is re-evaluated after each tick based on current session state.
+    let timerId: ReturnType<typeof setTimeout> | null = null;
 
-    const intervalId = setInterval(() => {
-      debug("Interval tick - refreshing sessions", undefined, "agent-sessions");
-      refreshSessionsRef.current();
-    }, refreshInterval);
+    const scheduleNext = () => {
+      const hasActive = sessions.some((s) => s.status === "active");
+      const interval = hasActive ? ACTIVE_INTERVAL_MS : IDLE_INTERVAL_MS;
+
+      timerId = setTimeout(() => {
+        debug(
+          `Adaptive tick (${hasActive ? "active" : "idle"}, ${interval}ms)`,
+          undefined,
+          "agent-sessions",
+        );
+        refreshSessionsRef.current().then(scheduleNext);
+      }, interval);
+    };
+
+    scheduleNext();
 
     return () => {
-      debug("Clearing session refresh interval", undefined, "agent-sessions");
-      clearInterval(intervalId);
+      if (timerId !== null) {
+        clearTimeout(timerId);
+      }
     };
-  }, [autoRefresh, refreshInterval, debug]);
+  }, [autoRefresh, sessions, debug]);
 
   const value: AgentSessionContextValue = {
     sessions,

package/src/tui/contexts/PluginContext.tsx

@@ -44,6 +44,8 @@ export interface ProviderState {
   loading: boolean;
   lastFetchAt: number | null;
   history: UsageSnapshot[];
+  /** Timestamp (ms) until which this provider should be skipped due to rate limiting. 0 = not rate limited. */
+  rateLimitUntil: number;
 }
 
 interface PluginContextValue {
@@ -190,6 +192,7 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
           loading: false,
           lastFetchAt: null,
           history: [],
+          rateLimitUntil: 0,
         });
 
         if (configured) {
@@ -264,6 +267,18 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
         return;
       }
 
+      // Skip providers that are currently rate-limited (backoff)
+      const now = Date.now();
+      if (state.rateLimitUntil > now) {
+        const remainingSec = Math.round((state.rateLimitUntil - now) / 1000);
+        debug(
+          `Skipping ${providerId}: rate limited for ${remainingSec}s more`,
+          undefined,
+          "refresh",
+        );
+        return;
+      }
+
       info(`Refreshing ${providerId}...`, undefined, "refresh");
 
       setProviders((prev) => {
@@ -310,6 +325,7 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
               usage,
               loading: false,
               lastFetchAt: Date.now(),
+              rateLimitUntil: 0,
               history: addToHistory(currentHistory, snapshotEntry),
             });
             return next;
@@ -337,16 +353,24 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
         const http = createSandboxedHttpClient(providerId, state.plugin.permissions);
         const logger = createPluginLogger(providerId);
 
-        const fetchResult = await safeInvoke(providerId, "fetchUsage", () =>
-          runInPluginGuard(providerId, state.plugin.permissions, () =>
-            state.plugin.fetchUsage({
-              credentials: creds,
-              http,
-              logger,
-              config: {},
-              signal: AbortSignal.timeout(30_000),
-            }),
-          ),
+        const fetchResult = await safeInvoke(
+          providerId,
+          "fetchUsage",
+          () =>
+            runInPluginGuard(providerId, state.plugin.permissions, () =>
+              state.plugin.fetchUsage({
+                credentials: creds,
+                http,
+                logger,
+                config: {},
+                signal: AbortSignal.timeout(30_000),
+              }),
+            ),
+          {
+            // Count non-rate-limit errors as circuit breaker failures.
+            // Rate limits are handled separately via backoff scheduling.
+            isFailure: (usage) => !!usage.error && !usage.rateLimited,
+          },
         );
 
         if (!fetchResult.ok) {
@@ -355,6 +379,34 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
 
         const usage = fetchResult.value;
 
+        // Handle rate-limited responses: set backoff, preserve last good data
+        if (usage.rateLimited) {
+          const backoffMs = usage.retryAfterMs ?? 300_000; // default 5 min
+          const backoffUntil = Date.now() + backoffMs;
+          warn(
+            `${providerId} rate limited, backing off for ${Math.round(backoffMs / 1000)}s`,
+            { retryAfterMs: backoffMs, until: new Date(backoffUntil).toISOString() },
+            "refresh",
+          );
+
+          setProviders((prev) => {
+            const next = new Map(prev);
+            const current = next.get(providerId);
+            // Preserve the last successful usage data if we have it
+            const preservedUsage = current?.usage && !current.usage.error ? current.usage : usage;
+            next.set(providerId, {
+              ...state,
+              usage: preservedUsage,
+              loading: false,
+              lastFetchAt: Date.now(),
+              rateLimitUntil: backoffUntil,
+              history: current?.history ?? [],
+            });
+            return next;
+          });
+          return;
+        }
+
         if (usage.error) {
           warn(`${providerId} returned error: ${usage.error}`, undefined, "refresh");
         } else {
@@ -399,6 +451,7 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
             usage,
             loading: false,
             lastFetchAt: Date.now(),
+            rateLimitUntil: 0,
             history: addToHistory(currentHistory, snapshot),
           });
           return next;
@@ -418,6 +471,7 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
             },
             loading: false,
             lastFetchAt: Date.now(),
+            rateLimitUntil: current?.rateLimitUntil ?? 0,
             history: current?.history ?? [],
           });
           return next;

package/src/tui/contexts/ThemeContext.tsx

@@ -16,6 +16,7 @@ interface ThemeContextValue {
   setTheme: (theme: ThemePlugin) => void;
   previewTheme: ThemePlugin | null;
   setPreviewTheme: (theme: ThemePlugin | null) => void;
+  cliTheme: string | undefined;
 }
 
 const defaultComponents: ThemeComponents = {
@@ -29,10 +30,11 @@ const ThemeContext = createContext<ThemeContextValue | null>(null);
 
 interface ThemeProviderProps {
   initialTheme?: ThemePlugin;
+  cliTheme?: string;
   children: ReactNode;
 }
 
-export function ThemeProvider({ initialTheme, children }: ThemeProviderProps) {
+export function ThemeProvider({ initialTheme, cliTheme, children }: ThemeProviderProps) {
   const [theme, setTheme] = useState<ThemePlugin>(initialTheme ?? tokyoNightTheme);
   const [previewTheme, setPreviewTheme] = useState<ThemePlugin | null>(null);
 
@@ -46,6 +48,7 @@ export function ThemeProvider({ initialTheme, children }: ThemeProviderProps) {
     setTheme,
     previewTheme,
     setPreviewTheme,
+    cliTheme,
   };
 
   return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;

package/src/tui/createApp.tsx

@@ -13,6 +13,7 @@ export interface CreateAppOptions {
   demoSeed?: number;
   demoPreset?: DemoPreset;
   cliPlugins?: string[];
+  cliTheme?: string;
 }
 
 export const DEFAULT_APP_OPTIONS = {
@@ -32,6 +33,7 @@ export function createAppElement(options: CreateAppOptions = {}): ReactNode {
       {...(options.demoSeed !== undefined ? { demoSeed: options.demoSeed } : {})}
       {...(options.demoPreset !== undefined ? { demoPreset: options.demoPreset } : {})}
       {...(options.cliPlugins ? { cliPlugins: options.cliPlugins } : {})}
+      {...(options.cliTheme ? { cliTheme: options.cliTheme } : {})}
     />
   );
 

package/src/tui/hooks/index.ts

@@ -6,6 +6,7 @@ export {
   useAnimatedTokens,
   useAnimatedValue,
 } from "./useAnimatedValue.ts";
+export { animationTick, useAnimationTick } from "./useAnimationTick.ts";
 export type { DashboardDeltas, UseDashboardStateResult } from "./useDashboardState.ts";
 export { useDashboardState } from "./useDashboardState.ts";
 export type { ActivityDebugData, ActivityState, UseActivityRateResult } from "./useEmaActivity.ts";

package/src/tui/hooks/useAnimatedValue.ts

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState } from "react";
+import { animationTick } from "./useAnimationTick.ts";
 
 export type EasingFunction = (t: number) => number;
 
@@ -14,6 +15,7 @@ export interface UseAnimatedValueOptions {
   durationMs?: number;
   easing?: keyof typeof easings | EasingFunction;
   precision?: number;
+  /** @deprecated Ignored — animations now use the global 30 Hz tick. */
   frameRate?: number;
 }
 
@@ -21,57 +23,58 @@ export function useAnimatedValue(
   targetValue: number,
   options: UseAnimatedValueOptions = {},
 ): number {
-  const { durationMs = 300, easing = "easeOutQuad", precision = 2, frameRate = 60 } = options;
+  const { durationMs = 300, easing = "easeOutQuad", precision = 2 } = options;
 
   const [displayValue, setDisplayValue] = useState(targetValue);
-  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const displayRef = useRef(targetValue);
   const startValueRef = useRef(targetValue);
-  const startTimeRef = useRef<number>(Date.now());
+  const startTimeRef = useRef(0);
   const targetRef = useRef(targetValue);
+  const unsubRef = useRef<(() => void) | null>(null);
 
   const easingFn = typeof easing === "function" ? easing : easings[easing];
-  const frameInterval = Math.round(1000 / frameRate);
 
   useEffect(() => {
-    if (targetRef.current === targetValue && displayValue === targetValue) {
+    // Already at target — nothing to animate
+    if (targetRef.current === targetValue && displayRef.current === targetValue) {
       return;
     }
 
-    if (intervalRef.current !== null) {
-      clearInterval(intervalRef.current);
-    }
+    // Clean up any existing subscription
+    unsubRef.current?.();
 
-    startValueRef.current = displayValue;
+    // Set up animation from current display value to new target
+    startValueRef.current = displayRef.current;
     startTimeRef.current = Date.now();
     targetRef.current = targetValue;
 
-    intervalRef.current = setInterval(() => {
-      const elapsed = Date.now() - startTimeRef.current;
+    // Subscribe to global tick — auto-starts the shared timer
+    unsubRef.current = animationTick.subscribe((now) => {
+      const elapsed = now - startTimeRef.current;
       const progress = Math.min(elapsed / durationMs, 1);
       const easedProgress = easingFn(progress);
-
       const startVal = startValueRef.current;
-      const currentValue = startVal + (targetRef.current - startVal) * easedProgress;
-      const roundedValue = Number(currentValue.toFixed(precision));
+      const target = targetRef.current;
+      const currentValue = startVal + (target - startVal) * easedProgress;
+      const rounded = Number(currentValue.toFixed(precision));
 
-      setDisplayValue(roundedValue);
+      displayRef.current = rounded;
+      setDisplayValue(rounded);
 
       if (progress >= 1) {
-        if (intervalRef.current !== null) {
-          clearInterval(intervalRef.current);
-          intervalRef.current = null;
-        }
-        setDisplayValue(targetRef.current);
+        displayRef.current = target;
+        setDisplayValue(target);
+        // Unsubscribe — if no other animations are active, the global timer stops
+        unsubRef.current?.();
+        unsubRef.current = null;
       }
-    }, frameInterval);
+    });
 
     return () => {
-      if (intervalRef.current !== null) {
-        clearInterval(intervalRef.current);
-        intervalRef.current = null;
-      }
+      unsubRef.current?.();
+      unsubRef.current = null;
     };
-  }, [targetValue, durationMs, easingFn, precision, frameInterval, displayValue]);
+  }, [targetValue, durationMs, easingFn, precision]);
 
   return displayValue;
 }