@tokentop/ttop 0.3.0 → 0.5.0

package/src/tui/views/ProjectsView.tsx

@@ -1202,6 +1202,7 @@ export function ProjectsView() {
   const [isFiltering, setIsFiltering] = useState(false);
   const scrollOffsetRef = useRef(0);
   const scrollboxRef = useRef<ScrollBoxRenderable>(null);
+  const selectedProjectPathRef = useRef<string | null>(null);
 
   // Aggregate projects
   const projectStats = useMemo(
@@ -1252,16 +1253,38 @@ export function ProjectsView() {
   // Visible columns
   const visibleColumns: ColumnSpec[] = useMemo(() => getVisibleColumns(termWidth), [termWidth]);
 
-  // Clamp selection
-  useEffect(() => {
+  // Stabilize selection across re-sorts: track selected project by path
+  // so the highlight follows the same project when live data causes reordering.
+  useLayoutEffect(() => {
     if (sortedProjects.length === 0) {
-      if (selectedIndex !== 0) setSelectedIndex(0);
+      setSelectedIndex(0);
       scrollOffsetRef.current = 0;
       scrollboxRef.current?.scrollTo(0);
-    } else if (selectedIndex >= sortedProjects.length) {
-      setSelectedIndex(sortedProjects.length - 1);
+      selectedProjectPathRef.current = null;
+      return;
+    }
+
+    if (selectedProjectPathRef.current) {
+      const newIndex = sortedProjects.findIndex((p) => p.path === selectedProjectPathRef.current);
+      if (newIndex !== -1) {
+        setSelectedIndex(newIndex);
+        return;
+      }
+      // Tracked project was filtered out — fall through to clamp
+      selectedProjectPathRef.current = null;
+    }
+
+    // Clamp to valid range (functional update avoids selectedIndex in deps)
+    setSelectedIndex((prev) => Math.min(prev, sortedProjects.length - 1));
+  }, [sortedProjects]);
+
+  // Record which project the user selected
+  useEffect(() => {
+    const project = sortedProjects[selectedIndex];
+    if (project) {
+      selectedProjectPathRef.current = project.path;
     }
-  }, [sortedProjects.length, selectedIndex]);
+  }, [selectedIndex, sortedProjects]);
 
   // Scroll to keep selected row visible
   const visibleRows = useMemo(() => {

package/src/tui/views/RealTimeDashboard.tsx

@@ -64,6 +64,7 @@ export function RealTimeDashboard() {
   const [sortField, setSortField] = useState<"cost" | "tokens" | "time">("cost");
   const [pendingG, setPendingG] = useState(false);
   const scrollOffsetRef = useRef(0);
+  const selectedSessionIdRef = useRef<string | null>(null);
   const setScrollOffset = useCallback((val: number) => {
     scrollOffsetRef.current = val;
     sessionsScrollboxRef.current?.scrollTo(val);
@@ -192,19 +193,39 @@ export function RealTimeDashboard() {
     return result;
   }, [baseFilteredSessions, activeDriverFilter, driverDimension, sortField]);
 
-  useEffect(() => {
+  // Stabilize selection across re-sorts: track selected session by ID
+  // so the highlight follows the same session when live data causes reordering.
+  useLayoutEffect(() => {
     if (processedSessions.length === 0) {
-      if (selectedRow !== 0) setSelectedRow(0);
-      if (scrollOffsetRef.current !== 0) setScrollOffset(0);
+      setSelectedRow(0);
+      setScrollOffset(0);
+      selectedSessionIdRef.current = null;
       return;
     }
 
-    const maxRow = processedSessions.length - 1;
-    if (selectedRow > maxRow) {
-      setSelectedRow(maxRow);
-      return;
+    if (selectedSessionIdRef.current) {
+      const newIndex = processedSessions.findIndex(
+        (s) => s.sessionId === selectedSessionIdRef.current,
+      );
+      if (newIndex !== -1) {
+        setSelectedRow(newIndex);
+        return;
+      }
+      // Tracked session was filtered out — fall through to clamp
+      selectedSessionIdRef.current = null;
+    }
+
+    // Clamp to valid range (functional update avoids selectedRow in deps)
+    setSelectedRow((prev) => Math.min(prev, processedSessions.length - 1));
+  }, [processedSessions, setScrollOffset]);
+
+  // Record which session the user selected (runs after navigation and stabilization)
+  useEffect(() => {
+    const session = processedSessions[selectedRow];
+    if (session) {
+      selectedSessionIdRef.current = session.sessionId;
     }
-  }, [processedSessions.length, selectedRow, setScrollOffset]);
+  }, [selectedRow, processedSessions]);
 
   useLayoutEffect(() => {
     if (!sessionsScrollboxRef.current || processedSessions.length === 0) return;

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";
@@ -284,7 +284,7 @@ export function SettingsView() {
   const colors = useColors();
   const { showToast } = useToastContext();
   const { config, isLoading, updateConfig, resetToDefaults, saveNow } = useConfig();
-  const { providers, notifications } = usePlugins();
+  const { providers, agents, themes, notifications } = usePlugins();
   const { demoMode, seed, preset } = useDemoMode();
   const { width: terminalWidth } = useTerminalDimensions();
 
@@ -293,9 +293,14 @@ export function SettingsView() {
   const [focusedPane, setFocusedPane] = useState<"categories" | "settings">("settings");
 
   const pluginSettings = useMemo(() => {
-    const allPlugins = [...Array.from(providers.values()).map((p) => p.plugin), ...notifications];
+    const allPlugins = [
+      ...Array.from(providers.values()).map((p) => p.plugin),
+      ...agents,
+      ...themes,
+      ...notifications,
+    ];
     return buildPluginSettings(allPlugins);
-  }, [providers, notifications, config]);
+  }, [providers, agents, themes, notifications]);
 
   const allSettings = useMemo(() => [...SETTINGS, ...pluginSettings], [pluginSettings]);
   const categorySettings = allSettings.filter((s) => s.category === selectedCategory);

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.3.0"; // x-release-please-version
+export const VERSION = "0.5.0"; // x-release-please-version

package/src/plugins/types/agent.ts

@@ -1,108 +0,0 @@
-import { z } from "zod";
-import type { BasePlugin, PluginHttpClient, PluginLogger } from "./base.ts";
-import type { Credentials, OAuthCredentials, PluginContext } from "./provider.ts";
-
-export const AgentCapabilitiesSchema = z.object({
-  sessionParsing: z.boolean(),
-  authReading: z.boolean(),
-  realTimeTracking: z.boolean(),
-  multiProvider: z.boolean(),
-});
-
-export type AgentCapabilities = z.infer<typeof AgentCapabilitiesSchema>;
-
-export interface AgentConfig {
-  /** Display name for this coding agent (e.g. "OpenCode", "Cursor"). */
-  name: string;
-  /** CLI command that launches the agent (for display/detection). */
-  command?: string;
-  /** Path to the agent's config directory (for display/debugging). */
-  configPath?: string;
-  /** Path to the agent's session storage. */
-  sessionPath?: string;
-  /** Path to the agent's auth file (for credential reading). */
-  authPath?: string;
-}
-
-export interface AgentCredentials {
-  providers: Record<string, Credentials | undefined>;
-  oauth?: Record<string, OAuthCredentials>;
-}
-
-export interface AgentProviderConfig {
-  id: string;
-  name: string;
-  configured: boolean;
-  enabled?: boolean;
-}
-
-export interface SessionParseOptions {
-  sessionId?: string;
-  timePeriod?: "session" | "daily" | "weekly" | "monthly";
-  limit?: number;
-  /** Epoch ms — only return sessions updated after this timestamp. */
-  since?: number;
-}
-
-export interface SessionUsageData {
-  sessionId: string;
-  sessionName?: string;
-  providerId: string;
-  modelId: string;
-  tokens: {
-    input: number;
-    output: number;
-    cacheRead?: number;
-    cacheWrite?: number;
-  };
-  timestamp: number;
-  sessionUpdatedAt?: number;
-  projectPath?: string;
-  cost?: number;
-}
-
-export interface AgentFetchContext {
-  readonly http: PluginHttpClient;
-  readonly logger: PluginLogger;
-  readonly config: Record<string, unknown>;
-  readonly signal: AbortSignal;
-}
-
-export interface ActivityUpdate {
-  sessionId: string;
-  messageId: string;
-  tokens: {
-    input: number;
-    output: number;
-    reasoning?: number;
-    cacheRead?: number;
-    cacheWrite?: number;
-  };
-  timestamp: number;
-}
-
-export type ActivityCallback = (update: ActivityUpdate) => void;
-
-export interface AgentPlugin extends BasePlugin {
-  readonly type: "agent";
-  readonly agent: AgentConfig;
-  readonly capabilities: AgentCapabilities;
-
-  /** Check if this coding agent is installed on the user's machine. */
-  isInstalled(ctx: PluginContext): Promise<boolean>;
-
-  /** Read credentials that the coding agent has stored. */
-  readCredentials?(ctx: AgentFetchContext): Promise<AgentCredentials>;
-
-  /** Parse session usage data from the agent's local storage. */
-  parseSessions(options: SessionParseOptions, ctx: AgentFetchContext): Promise<SessionUsageData[]>;
-
-  /** List which model providers this agent is configured to use. */
-  getProviders?(ctx: AgentFetchContext): Promise<AgentProviderConfig[]>;
-
-  /** Start watching for real-time activity updates. */
-  startActivityWatch?(ctx: PluginContext, callback: ActivityCallback): void;
-
-  /** Stop watching for real-time activity updates. */
-  stopActivityWatch?(ctx: PluginContext): void;
-}

package/src/plugins/types/base.ts

@@ -1,278 +0,0 @@
-/**
- * Base plugin types and interfaces for the tokentop plugin system.
- *
- * These types mirror the Plugin SDK (@tokentop/plugin-sdk) — the SDK is the
- * authoritative contract for community developers; core adapts to match.
- */
-
-import { z } from "zod";
-
-// ---------------------------------------------------------------------------
-// Identity
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin type discriminator
- */
-export type PluginType = "provider" | "agent" | "theme" | "notification";
-
-/**
- * Current API contract version.
- * Core checks this at load time to ensure compatibility.
- */
-export const CURRENT_API_VERSION = 2;
-
-// ---------------------------------------------------------------------------
-// Permissions
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin permissions schema - defines what a plugin can access
- */
-export const PluginPermissionsSchema = z.object({
-  network: z
-    .object({
-      enabled: z.boolean(),
-      allowedDomains: z.array(z.string()).optional(),
-    })
-    .optional(),
-  filesystem: z
-    .object({
-      read: z.boolean().optional(),
-      write: z.boolean().optional(),
-      paths: z.array(z.string()).optional(),
-    })
-    .optional(),
-  env: z
-    .object({
-      read: z.boolean().optional(),
-      vars: z.array(z.string()).optional(),
-    })
-    .optional(),
-  system: z
-    .object({
-      notifications: z.boolean().optional(),
-      clipboard: z.boolean().optional(),
-    })
-    .optional(),
-});
-
-export type PluginPermissions = z.infer<typeof PluginPermissionsSchema>;
-
-// ---------------------------------------------------------------------------
-// Metadata
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin metadata
- */
-export const PluginMetaSchema = z.object({
-  author: z.string().optional(),
-  description: z.string().optional(),
-  homepage: z.string().url().optional(),
-  repository: z.string().url().optional(),
-  license: z.string().optional(),
-  /**
-   * Brand color as a hex string (e.g. `"#d97757"`).
-   * Used by the TUI for provider cards, charts, and status indicators.
-   */
-  brandColor: z.string().optional(),
-  /**
-   * Single-character icon or short glyph for compact displays.
-   * Example: `"◆"`, `"▲"`, `"⚡"`
-   */
-  icon: z.string().optional(),
-  /**
-   * Additional provider IDs that should resolve to this plugin.
-   * Coding agents may tag sessions with provider IDs that differ from
-   * the plugin's `id` (e.g. OpenCode uses `"openai"` but the plugin
-   * registers as `"openai-api"`). List those alternate IDs here so the
-   * TUI can resolve brand colors and other metadata correctly.
-   */
-  providerAliases: z.array(z.string()).optional(),
-});
-
-export type PluginMeta = z.infer<typeof PluginMetaSchema>;
-
-// ---------------------------------------------------------------------------
-// Configuration
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin configuration field definition (for plugin settings UI)
- */
-export interface ConfigField {
-  /** Data type of the setting value. */
-  type: "string" | "number" | "boolean" | "select";
-  /** Label shown in the settings UI. */
-  label?: string;
-  /** Help text shown below the field. */
-  description?: string;
-  /** Whether the field must have a value. */
-  required?: boolean;
-  /** Default value when no user config exists. */
-  default?: unknown;
-  /** Available options (for `select` type only). */
-  options?: Array<{ value: string; label: string }>;
-  /** Minimum value (for `number` type only). */
-  min?: number;
-  /** Maximum value (for `number` type only). */
-  max?: number;
-}
-
-// ---------------------------------------------------------------------------
-// Lifecycle Context
-// ---------------------------------------------------------------------------
-
-/**
- * Minimal context provided to lifecycle hooks.
- */
-export interface PluginLifecycleContext {
-  /** Plugin's validated configuration values. */
-  readonly config: Record<string, unknown>;
-  /** Scoped logger that prefixes all output with the plugin ID. */
-  readonly logger: PluginLogger;
-}
-
-// ---------------------------------------------------------------------------
-// Base Plugin
-// ---------------------------------------------------------------------------
-
-/**
- * Base plugin interface - all plugins must implement this.
- *
- * Provides identity, metadata, permissions, optional configuration schema,
- * and lifecycle hooks.
- */
-export interface BasePlugin {
-  /** API version this plugin targets. Must equal {@link CURRENT_API_VERSION}. */
-  readonly apiVersion: 2;
-
-  /** Unique plugin identifier (kebab-case) */
-  readonly id: string;
-
-  /** Plugin type discriminator */
-  readonly type: PluginType;
-
-  /** Human-readable display name */
-  readonly name: string;
-
-  /** Semantic version string */
-  readonly version: string;
-
-  /** Plugin metadata */
-  readonly meta?: PluginMeta;
-
-  /** Required permissions */
-  readonly permissions: PluginPermissions;
-
-  /** Plugin-declared configuration fields, rendered in Settings UI */
-  readonly configSchema?: Record<string, ConfigField>;
-
-  /**
-   * Default config values. Used when no user configuration exists.
-   * Keys must match those in {@link configSchema}.
-   */
-  readonly defaultConfig?: Record<string, unknown>;
-
-  // -- Lifecycle Hooks (all optional) -------------------------------------
-
-  /**
-   * Called once after the plugin is loaded and validated.
-   * Use for one-time setup (open connections, allocate resources).
-   */
-  initialize?(ctx: PluginLifecycleContext): Promise<void>;
-
-  /**
-   * Called when the plugin should begin active work (e.g. polling).
-   * Called after `initialize()` during app startup, and after re-enable.
-   */
-  start?(ctx: PluginLifecycleContext): Promise<void>;
-
-  /**
-   * Called when the plugin should pause active work.
-   * Called before `destroy()` during app shutdown, and on disable.
-   */
-  stop?(ctx: PluginLifecycleContext): Promise<void>;
-
-  /**
-   * Called once before the plugin is unloaded.
-   * Use for cleanup (close connections, flush buffers).
-   */
-  destroy?(ctx: PluginLifecycleContext): Promise<void>;
-
-  /**
-   * Called when the user changes this plugin's configuration.
-   * Receive the new validated config values.
-   */
-  onConfigChange?(
-    config: Record<string, unknown>,
-    ctx: PluginLifecycleContext,
-  ): Promise<void> | void;
-}
-
-// ---------------------------------------------------------------------------
-// Logger
-// ---------------------------------------------------------------------------
-
-/**
- * Logger interface provided to plugins
- */
-export interface PluginLogger {
-  debug(message: string, data?: Record<string, unknown>): void;
-  info(message: string, data?: Record<string, unknown>): void;
-  warn(message: string, data?: Record<string, unknown>): void;
-  error(message: string, data?: Record<string, unknown>): void;
-}
-
-// ---------------------------------------------------------------------------
-// HTTP Client
-// ---------------------------------------------------------------------------
-
-/**
- * HTTP client interface provided to plugins (sandboxed)
- */
-export interface PluginHttpClient {
-  fetch(url: string, init?: RequestInit): Promise<Response>;
-}
-
-// ---------------------------------------------------------------------------
-// Validation
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin validation result
- */
-export interface PluginValidationResult {
-  valid: boolean;
-  errors: string[];
-  warnings: string[];
-}
-
-/**
- * Plugin load result
- */
-export interface PluginLoadResult<T extends BasePlugin = BasePlugin> {
-  success: boolean;
-  plugin?: T;
-  error?: string;
-  source: "builtin" | "local" | "npm";
-}
-
-// ---------------------------------------------------------------------------
-// Errors
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin permission error
- */
-export class PluginPermissionError extends Error {
-  constructor(
-    public readonly pluginId: string,
-    public readonly permission: keyof PluginPermissions,
-    message: string,
-  ) {
-    super(`Plugin "${pluginId}" permission denied: ${message}`);
-    this.name = "PluginPermissionError";
-  }
-}

package/src/plugins/types/index.ts

@@ -1,19 +0,0 @@
-export * from "./agent.ts";
-export * from "./base.ts";
-export * from "./notification.ts";
-export * from "./provider.ts";
-export * from "./theme.ts";
-
-import type { AgentPlugin } from "./agent.ts";
-import type { NotificationPlugin } from "./notification.ts";
-import type { ProviderPlugin } from "./provider.ts";
-import type { ThemePlugin } from "./theme.ts";
-
-export type AnyPlugin = ProviderPlugin | AgentPlugin | ThemePlugin | NotificationPlugin;
-
-export type PluginByType = {
-  provider: ProviderPlugin;
-  agent: AgentPlugin;
-  theme: ThemePlugin;
-  notification: NotificationPlugin;
-};

package/src/plugins/types/notification.ts

@@ -1,51 +0,0 @@
-import type { BasePlugin, PluginLogger } from "./base.ts";
-
-// ---------------------------------------------------------------------------
-// Notification Events
-// ---------------------------------------------------------------------------
-
-export type NotificationSeverity = "info" | "warning" | "critical";
-
-export type NotificationEventType =
-  | "budget.thresholdCrossed"
-  | "budget.limitReached"
-  | "provider.fetchFailed"
-  | "provider.limitReached"
-  | "provider.recovered"
-  | "plugin.crashed"
-  | "plugin.disabled"
-  | "app.started"
-  | "app.updated";
-
-export interface NotificationEvent {
-  type: NotificationEventType;
-  severity: NotificationSeverity;
-  title: string;
-  message: string;
-  timestamp: number;
-  data?: Record<string, unknown>;
-}
-
-// ---------------------------------------------------------------------------
-// Notification Context
-// ---------------------------------------------------------------------------
-
-export interface NotificationContext {
-  readonly logger: PluginLogger;
-  readonly config: Record<string, unknown>;
-  readonly signal: AbortSignal;
-}
-
-// ---------------------------------------------------------------------------
-// Notification Plugin
-// ---------------------------------------------------------------------------
-
-export interface NotificationPlugin extends BasePlugin {
-  readonly type: "notification";
-
-  initialize(ctx: NotificationContext): Promise<void>;
-  notify(ctx: NotificationContext, event: NotificationEvent): Promise<void>;
-  test?(ctx: NotificationContext): Promise<boolean>;
-  supports?(event: NotificationEvent): boolean;
-  destroy?(): Promise<void>;
-}