@tokentop/ttop 0.4.0 → 0.6.0

package/src/tui/hooks/useValueFlash.ts

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState } from "react";
+import { animationTick } from "./useAnimationTick.ts";
 
 export interface UseValueFlashOptions {
   durationMs?: number;
@@ -20,12 +21,9 @@ export function useValueFlash(
 
   const prevValueRef = useRef<number>(value);
   const [isFlashing, setIsFlashing] = useState(false);
-  const [step, setStep] = useState(0);
-  const flashTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const animationIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
-
-  const steps = 18;
-  const stepDuration = durationMs / steps;
+  const [intensity, setIntensity] = useState(0);
+  const flashStartRef = useRef(0);
+  const unsubRef = useRef<(() => void) | null>(null);
 
   useEffect(() => {
     const prevValue = prevValueRef.current;
@@ -34,45 +32,39 @@ export function useValueFlash(
     const shouldFlash = increaseOnly ? delta > threshold : Math.abs(delta) > threshold;
 
     if (shouldFlash && prevValue !== value) {
-      if (flashTimeoutRef.current) {
-        clearTimeout(flashTimeoutRef.current);
-      }
-      if (animationIntervalRef.current) {
-        clearInterval(animationIntervalRef.current);
-      }
+      // Clean up any existing subscription
+      unsubRef.current?.();
 
+      flashStartRef.current = Date.now();
       setIsFlashing(true);
-      setStep(0);
-
-      let currentStep = 0;
-      animationIntervalRef.current = setInterval(() => {
-        currentStep++;
-        if (currentStep >= steps) {
-          if (animationIntervalRef.current) {
-            clearInterval(animationIntervalRef.current);
-            animationIntervalRef.current = null;
-          }
+
+      // Subscribe to global tick
+      unsubRef.current = animationTick.subscribe((now) => {
+        const elapsed = now - flashStartRef.current;
+        const progress = elapsed / durationMs;
+
+        if (progress >= 1) {
           setIsFlashing(false);
-          setStep(0);
+          setIntensity(0);
+          unsubRef.current?.();
+          unsubRef.current = null;
         } else {
-          setStep(currentStep);
+          const currentIntensity = Math.sin(progress * Math.PI);
+          setIntensity(currentIntensity);
         }
-      }, stepDuration);
+      });
     }
 
     prevValueRef.current = value;
 
     return () => {
-      if (flashTimeoutRef.current) {
-        clearTimeout(flashTimeoutRef.current);
-      }
-      if (animationIntervalRef.current) {
-        clearInterval(animationIntervalRef.current);
-      }
+      unsubRef.current?.();
+      unsubRef.current = null;
     };
-  }, [value, durationMs, increaseOnly, threshold, steps, stepDuration]);
+  }, [value, durationMs, increaseOnly, threshold]);
 
-  const intensity = isFlashing ? Math.sin((step / steps) * Math.PI) : 0;
+  // step is kept for backward API compatibility
+  const step = isFlashing ? Math.round(intensity * 9) : 0;
 
   return { isFlashing, intensity, step };
 }

package/src/tui/index.tsx

@@ -13,6 +13,7 @@ export interface TuiOptions {
   demoSeed?: number;
   demoPreset?: DemoPreset;
   cliPlugins?: string[];
+  cliTheme?: string;
 }
 
 const FORCE_EXIT_GRACE_MS = 1_000;
@@ -45,6 +46,9 @@ export async function startTui(options: TuiOptions = {}) {
   if (options.cliPlugins !== undefined) {
     appOptions.cliPlugins = options.cliPlugins;
   }
+  if (options.cliTheme !== undefined) {
+    appOptions.cliTheme = options.cliTheme;
+  }
 
   root.render(createAppElement(appOptions));
 

package/src/tui/types/projectSort.ts

@@ -0,0 +1,35 @@
+import type { SortFieldDef } from "./sort.ts";
+import { buildShortcutMap } from "./sort.ts";
+
+export type ProjectSortField =
+  | "project"
+  | "cost"
+  | "tokens"
+  | "sessions"
+  | "cache"
+  | "cpr"
+  | "activity";
+
+export const PROJECT_SORT_FIELDS: readonly SortFieldDef<ProjectSortField>[] = [
+  { id: "project", label: "Project", shortcutKey: "P", defaultDirection: "asc" },
+  { id: "cost", label: "Cost", shortcutKey: "C", defaultDirection: "desc" },
+  { id: "tokens", label: "Tokens", shortcutKey: "K", defaultDirection: "desc" },
+  { id: "sessions", label: "Sessions", shortcutKey: "S", defaultDirection: "desc" },
+  { id: "cache", label: "Cache", shortcutKey: "H", defaultDirection: "desc" },
+  { id: "cpr", label: "$/Req", shortcutKey: "R", defaultDirection: "desc" },
+  { id: "activity", label: "Activity", shortcutKey: "A", defaultDirection: "desc" },
+] as const;
+
+/** Map from lowercase shortcut key → ProjectSortField */
+export const PROJECT_SHORTCUT_TO_FIELD: ReadonlyMap<string, ProjectSortField> =
+  buildShortcutMap(PROJECT_SORT_FIELDS);
+
+export function getProjectSortFieldDef(field: ProjectSortField): SortFieldDef<ProjectSortField> {
+  const def = PROJECT_SORT_FIELDS.find((f) => f.id === field);
+  if (!def) throw new Error(`Unknown project sort field: ${field}`);
+  return def;
+}
+
+export function getProjectSortFieldLabel(field: ProjectSortField): string {
+  return getProjectSortFieldDef(field).label;
+}

package/src/tui/types/sort.ts

@@ -0,0 +1,61 @@
+export type SortDirection = "asc" | "desc";
+
+export interface SortFieldDef<F extends string = string> {
+  readonly id: F;
+  readonly label: string;
+  /** Uppercase letter shown in overlay + used as Shift+key shortcut */
+  readonly shortcutKey: string;
+  /** Default direction when switching to this field */
+  readonly defaultDirection: SortDirection;
+}
+
+/** Build a lowercase-key → field-id map from any fields array */
+export function buildShortcutMap<F extends string>(
+  fields: readonly SortFieldDef<F>[],
+): ReadonlyMap<string, F> {
+  return new Map(fields.map((f) => [f.shortcutKey.toLowerCase(), f.id]));
+}
+
+// ---------------------------------------------------------------------------
+// Dashboard sort fields
+// ---------------------------------------------------------------------------
+
+export type SortField =
+  | "cost"
+  | "tokens"
+  | "time"
+  | "requests"
+  | "duration"
+  | "project"
+  | "agent"
+  | "model"
+  | "name";
+
+export const SORT_FIELDS: readonly SortFieldDef<SortField>[] = [
+  { id: "agent", label: "Agent", shortcutKey: "A", defaultDirection: "desc" },
+  { id: "model", label: "Model", shortcutKey: "M", defaultDirection: "desc" },
+  { id: "requests", label: "Requests", shortcutKey: "E", defaultDirection: "desc" },
+  { id: "tokens", label: "Tokens", shortcutKey: "K", defaultDirection: "desc" },
+  { id: "cost", label: "Cost", shortcutKey: "C", defaultDirection: "desc" },
+  { id: "project", label: "Project", shortcutKey: "O", defaultDirection: "desc" },
+  { id: "name", label: "Name", shortcutKey: "N", defaultDirection: "desc" },
+  { id: "duration", label: "Duration", shortcutKey: "U", defaultDirection: "desc" },
+  { id: "time", label: "Time", shortcutKey: "T", defaultDirection: "desc" },
+] as const;
+
+/** Map from lowercase shortcut key → SortField (dashboard) */
+export const SHORTCUT_TO_FIELD: ReadonlyMap<string, SortField> = buildShortcutMap(SORT_FIELDS);
+
+export function getSortFieldDef(field: SortField): SortFieldDef<SortField> {
+  const def = SORT_FIELDS.find((f) => f.id === field);
+  if (!def) throw new Error(`Unknown sort field: ${field}`);
+  return def;
+}
+
+export function getSortFieldLabel(field: SortField): string {
+  return getSortFieldDef(field).label;
+}
+
+export function getSortDirectionIndicator(dir: SortDirection): string {
+  return dir === "desc" ? "▼" : "▲";
+}

package/src/tui/views/ProjectsView.tsx

@@ -4,16 +4,21 @@ import { useKeyboard, useTerminalDimensions } from "@opentui/react";
 import type React from "react";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import type { AgentSessionAggregate } from "../../agents/types.ts";
+import { SortOverlay } from "../components/SortOverlay.tsx";
 import { useAgentSessions } from "../contexts/AgentSessionContext.tsx";
 import { useInputFocus } from "../contexts/InputContext.tsx";
 import { useColors } from "../contexts/ThemeContext.tsx";
 import { useTimeWindow } from "../contexts/TimeWindowContext.tsx";
+import type { ProjectSortField } from "../types/projectSort.ts";
+import { getProjectSortFieldLabel, PROJECT_SORT_FIELDS } from "../types/projectSort.ts";
+import type { SortDirection } from "../types/sort.ts";
+import { getSortDirectionIndicator } from "../types/sort.ts";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-type SortField = "cost" | "tokens" | "sessions" | "cache" | "cpr" | "activity";
+// ProjectSortField imported from ../types/projectSort.ts
 
 interface ModelStats {
   modelId: string;
@@ -264,50 +269,48 @@ function aggregateProjects(
 }
 
 // ---------------------------------------------------------------------------
-// Sort fields cycle
+// Sorting
 // ---------------------------------------------------------------------------
 
-const SORT_FIELDS: SortField[] = ["cost", "tokens", "sessions", "cache", "cpr", "activity"];
-
-const SORT_LABELS: Record<SortField, string> = {
-  cost: "COST",
-  tokens: "TOKENS",
-  sessions: "SESSIONS",
-  cache: "CACHE",
-  cpr: "$/REQ",
-  activity: "ACTIVITY",
-};
-
 function sortProjects(
   projects: ProjectStats[],
-  field: SortField,
-  _totalCost?: number,
+  field: ProjectSortField,
+  direction: SortDirection,
 ): ProjectStats[] {
   return [...projects].sort((a, b) => {
+    let cmp = 0;
     switch (field) {
       case "cost":
-        return b.cost - a.cost;
+        cmp = a.cost - b.cost;
+        break;
       case "tokens":
-        return b.tokens - a.tokens;
+        cmp = a.tokens - b.tokens;
+        break;
       case "sessions":
-        return b.sessionCount - a.sessionCount;
+        cmp = a.sessionCount - b.sessionCount;
+        break;
       case "cache": {
         const cacheA =
           a.inputTokens + a.cacheRead > 0 ? a.cacheRead / (a.inputTokens + a.cacheRead) : 0;
         const cacheB =
           b.inputTokens + b.cacheRead > 0 ? b.cacheRead / (b.inputTokens + b.cacheRead) : 0;
-        return cacheB - cacheA;
+        cmp = cacheA - cacheB;
+        break;
       }
       case "cpr": {
         const cprA = a.requestCount > 0 ? a.cost / a.requestCount : 0;
         const cprB = b.requestCount > 0 ? b.cost / b.requestCount : 0;
-        return cprB - cprA;
+        cmp = cprA - cprB;
+        break;
       }
       case "activity":
-        return b.activeSessions - a.activeSessions;
-      default:
-        return 0;
+        cmp = a.activeSessions - b.activeSessions;
+        break;
+      case "project":
+        cmp = a.name.localeCompare(b.name);
+        break;
     }
+    return direction === "desc" ? -cmp : cmp;
   });
 }
 
@@ -360,7 +363,8 @@ interface AggregateHeaderProps {
   projectCount: number;
   sessionCount: number;
   windowLabel: string;
-  sortField: SortField;
+  sortField: ProjectSortField;
+  sortDirection: SortDirection;
 }
 
 function AggregateHeader({
@@ -370,6 +374,7 @@ function AggregateHeader({
   sessionCount,
   windowLabel,
   sortField,
+  sortDirection,
 }: AggregateHeaderProps) {
   const colors = useColors();
   const avgPerProject = projectCount > 0 ? totalCost / projectCount : 0;
@@ -393,7 +398,10 @@ function AggregateHeader({
         <span fg={colors.text}>{formatCost(avgPerProject)}</span>
       </text>
       <text height={1} fg={colors.textMuted}>
-        [{windowLabel}] Sort: <span fg={colors.primary}>{SORT_LABELS[sortField]}</span>
+        [{windowLabel}] Sort:{" "}
+        <span fg={colors.primary}>
+          {getProjectSortFieldLabel(sortField)} {getSortDirectionIndicator(sortDirection)}
+        </span>
       </text>
     </box>
   );
@@ -1195,7 +1203,9 @@ export function ProjectsView() {
   const { setInputFocused } = useInputFocus();
 
   const [selectedIndex, setSelectedIndex] = useState(0);
-  const [sortField, setSortField] = useState<SortField>("cost");
+  const [sortField, setSortField] = useState<ProjectSortField>("cost");
+  const [sortDirection, setSortDirection] = useState<SortDirection>("desc");
+  const [showSortOverlay, setShowSortOverlay] = useState(false);
   const [showInsights, setShowInsights] = useState(termHeight >= 35);
   const [drawerProject, setDrawerProject] = useState<ProjectStats | null>(null);
   const [filterQuery, setFilterQuery] = useState("");
@@ -1246,13 +1256,44 @@ export function ProjectsView() {
 
   // Sort
   const sortedProjects = useMemo(
-    () => sortProjects(filteredProjects, sortField, totalCost),
-    [filteredProjects, sortField, totalCost],
+    () => sortProjects(filteredProjects, sortField, sortDirection),
+    [filteredProjects, sortField, sortDirection],
   );
 
   // Visible columns
   const visibleColumns: ColumnSpec[] = useMemo(() => getVisibleColumns(termWidth), [termWidth]);
 
+  // Map column keys → sort field IDs so we can hide sort fields for hidden columns.
+  // "tokens" has no dedicated column but is always available (related to cost data).
+  const COLUMN_TO_SORT_FIELD: Record<string, ProjectSortField> = {
+    project: "project",
+    cost: "cost",
+    sess: "sessions",
+    cache: "cache",
+    cpr: "cpr",
+    activity: "activity",
+  };
+
+  // Sort indicator helpers for column headers (matches SessionsTable pattern)
+  const sortIndicatorForCol = (colKey: string) => {
+    const field = COLUMN_TO_SORT_FIELD[colKey];
+    return field && sortField === field ? (sortDirection === "desc" ? "▼" : "▲") : " ";
+  };
+  const sortColorForCol = (colKey: string) => {
+    const field = COLUMN_TO_SORT_FIELD[colKey];
+    return field && sortField === field ? colors.primary : colors.textMuted;
+  };
+  const visibleSortFields = useMemo(() => {
+    const visibleFieldIds = new Set<ProjectSortField>(
+      visibleColumns
+        .map((c) => COLUMN_TO_SORT_FIELD[c.key])
+        .filter((id): id is ProjectSortField => id !== undefined),
+    );
+    // Always include tokens — no dedicated column but universally useful
+    visibleFieldIds.add("tokens");
+    return PROJECT_SORT_FIELDS.filter((f) => visibleFieldIds.has(f.id));
+  }, [visibleColumns]);
+
   // Stabilize selection across re-sorts: track selected project by path
   // so the highlight follows the same project when live data causes reordering.
   useLayoutEffect(() => {
@@ -1336,6 +1377,9 @@ export function ProjectsView() {
   useKeyboard(
     useCallback(
       (key: { name: string; shift?: boolean; ctrl?: boolean }) => {
+        // Sort overlay is open — let SortOverlay handle keys
+        if (showSortOverlay) return;
+
         // Drawer open: only Esc closes
         if (drawerProject) {
           if (key.name === "escape") {
@@ -1355,19 +1399,18 @@ export function ProjectsView() {
           return;
         }
 
+        // Open sort overlay menu
+        if (key.name === "s") {
+          setShowSortOverlay(true);
+          return;
+        }
+
         // Navigation
         if (key.name === "down" || key.name === "j") {
           setSelectedIndex((prev: number) => Math.min(prev + 1, sortedProjects.length - 1));
         } else if (key.name === "up" || key.name === "k") {
           setSelectedIndex((prev: number) => Math.max(prev - 1, 0));
         }
-        // Sort cycling
-        else if (key.name === "s") {
-          setSortField((prev: SortField) => {
-            const idx = SORT_FIELDS.indexOf(prev);
-            return SORT_FIELDS[(idx + 1) % SORT_FIELDS.length]!;
-          });
-        }
         // Time window
         else if (key.name === "t") {
           cycleWindow();
@@ -1401,7 +1444,15 @@ export function ProjectsView() {
           scrollOffsetRef.current = 0;
         }
       },
-      [drawerProject, isFiltering, sortedProjects, selectedIndex, cycleWindow, filterQuery],
+      [
+        drawerProject,
+        isFiltering,
+        sortedProjects,
+        selectedIndex,
+        cycleWindow,
+        filterQuery,
+        showSortOverlay,
+      ],
     ),
   );
 
@@ -1441,6 +1492,20 @@ export function ProjectsView() {
         />
       )}
 
+      {/* Sort overlay */}
+      {showSortOverlay && (
+        <SortOverlay
+          fields={visibleSortFields}
+          currentField={sortField}
+          currentDirection={sortDirection}
+          onSelect={(field, direction) => {
+            setSortField(() => field);
+            setSortDirection(() => direction);
+            setShowSortOverlay(false);
+          }}
+          onClose={() => setShowSortOverlay(false)}
+        />
+      )}
       {/* Aggregate header */}
       <AggregateHeader
         totalCost={visibleCost}
@@ -1449,6 +1514,7 @@ export function ProjectsView() {
         sessionCount={visibleSessions}
         windowLabel={windowLabel}
         sortField={sortField}
+        sortDirection={sortDirection}
       />
 
       {/* Column headers */}
@@ -1458,8 +1524,8 @@ export function ProjectsView() {
         </text>
         {visibleColumns.map((col: ColumnSpec) => (
           <box key={col.key} marginRight={1}>
-            <text width={col.width} height={1} fg={colors.textMuted}>
-              {padRight(col.label, col.width)}
+            <text width={col.width} height={1} fg={sortColorForCol(col.key)}>
+              {padRight(`${col.label}${sortIndicatorForCol(col.key)}`, col.width)}
             </text>
           </box>
         ))}

package/src/tui/views/RealTimeDashboard.tsx

@@ -2,11 +2,13 @@ import type { ScrollBoxRenderable } from "@opentui/core";
 import { useTerminalDimensions } from "@opentui/react";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { notificationBus } from "@/plugins/notification-bus.ts";
+import { classifyProviderError } from "@/utils/error-category.ts";
 import { HelpOverlay } from "../components/HelpOverlay.tsx";
 import { KpiStrip } from "../components/KpiStrip.tsx";
 import { ProviderLimitsPanel } from "../components/ProviderLimitsPanel.tsx";
 import { SessionsTable } from "../components/SessionsTable.tsx";
 import { type DriverDimension, getSidebarMode, SmartSidebar } from "../components/SmartSidebar.tsx";
+import { SortOverlay } from "../components/SortOverlay.tsx";
 import { useAgentSessions } from "../contexts/AgentSessionContext.tsx";
 import { useConfig } from "../contexts/ConfigContext.tsx";
 import { useDashboardRuntime } from "../contexts/DashboardRuntimeContext.tsx";
@@ -15,6 +17,8 @@ import { usePlugins } from "../contexts/PluginContext.tsx";
 import { useColors } from "../contexts/ThemeContext.tsx";
 import { useTimeWindow } from "../contexts/TimeWindowContext.tsx";
 import { useDashboardKeyboard } from "../hooks/useDashboardKeyboard.ts";
+import type { SortDirection, SortField } from "../types/sort.ts";
+import { SORT_FIELDS } from "../types/sort.ts";
 import { getProviderColor } from "../utils/providerColor.ts";
 
 export function RealTimeDashboard() {
@@ -30,6 +34,23 @@ export function RealTimeDashboard() {
   const showLargeHeader = terminalHeight >= 35;
   const showProviderLimitsPanel = terminalHeight >= 24;
 
+  // SessionsTable hides REQ, NAME, DUR, TIME columns in narrow mode (<140).
+  // Filter sort fields to match visible columns.
+  const SESSIONS_WIDE_THRESHOLD = 140;
+  const NARROW_HIDDEN_FIELDS: ReadonlySet<SortField> = new Set([
+    "requests",
+    "name",
+    "duration",
+    "time",
+  ]);
+  const visibleSortFields = useMemo(
+    () =>
+      terminalWidth >= SESSIONS_WIDE_THRESHOLD
+        ? SORT_FIELDS
+        : SORT_FIELDS.filter((f) => !NARROW_HIDDEN_FIELDS.has(f.id)),
+    [terminalWidth],
+  );
+
   // Visible-row count for scroll tracking — every non-session-data line must be counted.
   const visibleRows = (() => {
     const appChrome = (showLargeHeader ? 7 : 1) + 1; // App.tsx: Header + StatusBar
@@ -61,7 +82,9 @@ export function RealTimeDashboard() {
   const [sidebarCollapsed, setSidebarCollapsed] = useState(config.display.sidebarCollapsed);
   const [filterQuery, setFilterQuery] = useState("");
   const [isFiltering, setIsFiltering] = useState(false);
-  const [sortField, setSortField] = useState<"cost" | "tokens" | "time">("cost");
+  const [sortField, setSortField] = useState<SortField>("time");
+  const [sortDirection, setSortDirection] = useState<SortDirection>("desc");
+  const [showSortOverlay, setShowSortOverlay] = useState(false);
   const [pendingG, setPendingG] = useState(false);
   const scrollOffsetRef = useRef(0);
   const selectedSessionIdRef = useRef<string | null>(null);
@@ -184,14 +207,53 @@ export function RealTimeDashboard() {
       const bActive = b.status === "active" ? 1 : 0;
       if (bActive !== aActive) return bActive - aActive;
 
-      if (sortField === "cost") return (b.totalCostUsd ?? 0) - (a.totalCostUsd ?? 0);
-      if (sortField === "tokens")
-        return b.totals.input + b.totals.output - (a.totals.input + a.totals.output);
-      return b.lastActivityAt - a.lastActivityAt;
+      let cmp = 0;
+      switch (sortField) {
+        case "cost":
+          cmp = (a.totalCostUsd ?? 0) - (b.totalCostUsd ?? 0);
+          break;
+        case "tokens":
+          cmp = a.totals.input + a.totals.output - (b.totals.input + b.totals.output);
+          break;
+        case "time":
+          cmp = a.lastActivityAt - b.lastActivityAt;
+          break;
+        case "requests":
+          cmp = a.requestCount - b.requestCount;
+          break;
+        case "duration": {
+          const aDur = (a.endedAt ?? Date.now()) - a.startedAt;
+          const bDur = (b.endedAt ?? Date.now()) - b.startedAt;
+          cmp = aDur - bDur;
+          break;
+        }
+        case "project": {
+          const aProj = a.projectPath?.split("/").pop() ?? "";
+          const bProj = b.projectPath?.split("/").pop() ?? "";
+          cmp = aProj.localeCompare(bProj);
+          break;
+        }
+        case "agent":
+          cmp = a.agentName.localeCompare(b.agentName);
+          break;
+        case "model": {
+          const aModel = a.streams[0]?.modelId ?? "";
+          const bModel = b.streams[0]?.modelId ?? "";
+          cmp = aModel.localeCompare(bModel);
+          break;
+        }
+        case "name": {
+          const aName = a.sessionName ?? "";
+          const bName = b.sessionName ?? "";
+          cmp = aName.localeCompare(bName);
+          break;
+        }
+      }
+      return sortDirection === "desc" ? -cmp : cmp;
     });
 
     return result;
-  }, [baseFilteredSessions, activeDriverFilter, driverDimension, sortField]);
+  }, [baseFilteredSessions, activeDriverFilter, driverDimension, sortField, sortDirection]);
 
   // Stabilize selection across re-sorts: track selected session by ID
   // so the highlight follows the same session when live data causes reordering.
@@ -261,6 +323,7 @@ export function RealTimeDashboard() {
       filterQuery,
       isFiltering,
       sortField,
+      sortDirection,
       pendingG,
       scrollOffset: scrollOffsetRef.current,
       limitSelectedIndex,
@@ -269,6 +332,7 @@ export function RealTimeDashboard() {
       selectedDriverIndex,
       activeDriverFilter,
       sidebarMode,
+      showSortOverlay,
     },
     actions: {
       setShowHelp,
@@ -280,12 +344,14 @@ export function RealTimeDashboard() {
       setFilterQuery,
       setIsFiltering,
       setSortField,
+      setSortDirection,
       setPendingG,
       setScrollOffset,
       setLimitSelectedIndex,
       setDriverDimension,
       setSelectedDriverIndex,
       setActiveDriverFilter,
+      setShowSortOverlay,
     },
     processedSessions,
   });
@@ -348,6 +414,19 @@ export function RealTimeDashboard() {
   return (
     <box flexDirection="column" flexGrow={1} padding={1} gap={1} overflow="hidden">
       {showHelp && <HelpOverlay />}
+      {showSortOverlay && (
+        <SortOverlay
+          fields={visibleSortFields}
+          currentField={sortField}
+          currentDirection={sortDirection}
+          onSelect={(field, direction) => {
+            setSortField(() => field);
+            setSortDirection(() => direction);
+            setShowSortOverlay(false);
+          }}
+          onClose={() => setShowSortOverlay(false)}
+        />
+      )}
 
       <KpiStrip
         totalCost={windowedKpis.cost}
@@ -382,7 +461,9 @@ export function RealTimeDashboard() {
           name: p.plugin.name,
           usedPercent: getMaxUsedPercent(p),
           color: providerColorOf(p.plugin.id),
-          ...(p.usage?.error ? { error: p.usage.error } : {}),
+          ...(p.usage?.error
+            ? { error: p.usage.error, errorCategory: classifyProviderError(p.usage.error) }
+            : {}),
         }))}
         focused={focusedPanel === "limits"}
         selectedIndex={limitSelectedIndex}
@@ -416,6 +497,8 @@ export function RealTimeDashboard() {
           focusedPanel={focusedPanel}
           windowLabel={windowLabel}
           getProviderColor={providerColorOf}
+          sortField={sortField}
+          sortDirection={sortDirection}
         />
 
         {!effectiveSidebarCollapsed && (
@@ -440,7 +523,7 @@ export function RealTimeDashboard() {
               : activeDriverFilter
                 ? `Filter: ${activeDriverFilter}  Esc clear`
                 : focusedPanel === "sessions"
-                  ? "/ filter  ↑↓ navigate  Enter details  s sort  l limits  Tab next  ⇧Tab prev"
+                  ? "/ filter  ↑↓ navigate  Enter details  s sort  l limits  Tab next"
                   : focusedPanel === "limits"
                     ? "←→ select provider  Tab next  ⇧Tab prev  Esc back"
                     : focusedPanel === "sidebar"

package/src/tui/views/SettingsView.tsx

@@ -1,7 +1,7 @@
 import { useKeyboard, useTerminalDimensions } from "@opentui/react";
+import type { ConfigField } from "@tokentop/plugin-sdk";
 import { useCallback, useMemo, useState } from "react";
 import type { AppConfig } from "@/config/schema.ts";
-import type { ConfigField } from "@/plugins/types/base.ts";
 import { useConfig } from "../contexts/ConfigContext.tsx";
 import { useDemoMode } from "../contexts/DemoModeContext.tsx";
 import { usePlugins } from "../contexts/PluginContext.tsx";