@pellux/goodvibes-tui 0.18.23 → 0.19.1

package/src/input/settings-modal.ts

@@ -23,67 +23,23 @@ import type { FeatureFlag, FlagState } from '@pellux/goodvibes-sdk/platform/runt
 import type { McpRegistry } from '@pellux/goodvibes-sdk/platform/mcp/registry';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export type SettingsCategory = 'display' | 'ui' | 'provider' | 'subscriptions' | 'behavior' | 'storage' | 'permissions' | 'mcp' | 'sandbox' | 'danger' | 'tools' | 'flags';
-
-export const SETTINGS_CATEGORIES: SettingsCategory[] = [
-  'display',
-  'ui',
-  'provider',
-  'subscriptions',
-  'behavior',
-  'storage',
-  'permissions',
-  'mcp',
-  'sandbox',
-  'danger',
-  'tools',
-  'flags',
-];
-
-export interface SettingEntry {
-  setting: ConfigSetting;
-  currentValue: unknown;
-  isDefault: boolean;
-  effectiveSource?: 'default' | 'local' | 'synced' | 'managed';
-  locked?: boolean;
-  conflict?: boolean;
-  sourceLabel?: string;
-  lockReason?: string;
-}
-
-/** A single feature flag entry for the flags tab. */
-export interface FlagEntry {
-  flag: FeatureFlag;
-  state: FlagState;
-}
-
-export interface McpEntry {
-  name: string;
-  connected: boolean;
-  role: 'general' | 'docs' | 'filesystem' | 'git' | 'database' | 'browser' | 'automation' | 'ops' | 'remote';
-  trustMode: 'constrained' | 'ask-on-risk' | 'allow-all' | 'blocked';
-  allowedPaths: string[];
-  allowedHosts: string[];
-}
-
-export interface SubscriptionEntry {
-  provider: string;
-  state: 'active' | 'pending' | 'available';
-  tokenType?: string;
-  expiresAt?: number;
-  oauthConfigured: boolean;
-  activeRoute?: ProviderAuthRoute;
-  preferredRoute?: ProviderAuthRoute;
-  authFreshness?: ProviderAuthFreshness;
-  routeReason?: string;
-  issues?: string[];
-  nextActions?: string[];
-}
+import {
+  SETTINGS_CATEGORIES,
+  type FlagEntry,
+  type McpEntry,
+  type SettingEntry,
+  type SettingsCategory,
+  type SubscriptionEntry,
+} from './settings-modal-types.ts';
+
+export {
+  SETTINGS_CATEGORIES,
+  type FlagEntry,
+  type McpEntry,
+  type SettingEntry,
+  type SettingsCategory,
+  type SubscriptionEntry,
+} from './settings-modal-types.ts';
 
 /**
  * Map a config key to the model picker target it should open, or null if the
@@ -151,6 +107,13 @@ export class SettingsModal {
   /** Provider subscription entries (populated when subscriptions tab is active). */
   public subscriptionEntries: SubscriptionEntry[] = [];
 
+  /**
+   * Set after a network-category save that touches controlPlane or httpListener
+   * config keys.  Renderer reads this to display a transient restart notice.
+   * Cleared on next open() or close().
+   */
+  public lastSaveTriggeredRestart: 'control-plane' | 'http-listener' | 'web' | null = null;
+
   private configManager: ConfigManager | null = null;
   private featureFlagManager: FeatureFlagManager | null = null;
   private mcpRegistry: McpRegistry | null = null;
@@ -185,6 +148,7 @@ export class SettingsModal {
     this.editBuffer = '';
     this.mcpAllowAllConfirmationTarget = null;
     this.subscriptionLogoutConfirmationTarget = null;
+    this.lastSaveTriggeredRestart = null;
     this.active = true;
   }
 
@@ -194,6 +158,7 @@ export class SettingsModal {
     this.editBuffer = '';
     this.mcpAllowAllConfirmationTarget = null;
     this.subscriptionLogoutConfirmationTarget = null;
+    this.lastSaveTriggeredRestart = null;
     this.serviceRegistry = null;
   }
 
@@ -548,7 +513,15 @@ export class SettingsModal {
     for (const setting of CONFIG_SCHEMA) {
       const rawCat = setting.key.split('.')[0] as string;
       // Route helper.* settings into the tools group for unified display
-      const cat = (rawCat === 'helper' ? 'tools' : rawCat) as SettingsCategory;
+      // Route controlPlane.* and httpListener.* into the network group
+      let cat: SettingsCategory;
+      if (rawCat === 'helper') {
+        cat = 'tools';
+      } else if (rawCat === 'controlPlane' || rawCat === 'httpListener' || rawCat === 'web') {
+        cat = 'network';
+      } else {
+        cat = rawCat as SettingsCategory;
+      }
       if (!this.groups.has(cat)) continue;
       const currentValue = configManager.get(setting.key as ConfigKey);
       const resolved = getResolvedSettingLookup(configManager, setting.key as ConfigKey)?.entry;
@@ -720,17 +693,62 @@ export class SettingsModal {
   /** Returns [] for the flags category (flags use flagEntries instead). */
   private _currentItems(): SettingEntry[] {
     if (this.currentCategory === 'flags' || this.currentCategory === 'mcp' || this.currentCategory === 'subscriptions') return [];
-    return this.groups.get(this.currentCategory) ?? [];
+    const items = this.groups.get(this.currentCategory) ?? [];
+    if (this.currentCategory === 'network') {
+      // Hide host fields when the corresponding hostMode is not 'custom'
+      return items.filter(entry => {
+        if (entry.setting.key === 'controlPlane.host') {
+          const hostMode = this.configManager?.get('controlPlane.hostMode');
+          return hostMode === 'custom';
+        }
+        if (entry.setting.key === 'httpListener.host') {
+          const hostMode = this.configManager?.get('httpListener.hostMode');
+          return hostMode === 'custom';
+        }
+        if (entry.setting.key === 'web.host') {
+          const hostMode = this.configManager?.get('web.hostMode');
+          return hostMode === 'custom';
+        }
+        return true;
+      });
+    }
+    return items;
   }
 
   private _setValue(key: ConfigKey, value: unknown): void {
     if (!this.configManager) return;
+    // Diff previous value before writing — avoids false restart notices on no-op saves
+    const previousValue = this.configManager.get(key);
+    const isRestartKey = ['host', 'port', 'hostMode', 'enabled'].includes(key.split('.')[1] ?? '');
     try {
       this.configManager.setDynamic(key, value);
       // Update the cached entry in-place — avoids full schema re-scan on each edit
       const rawCat = key.split('.')[0] as string;
-      // helper.* entries are stored in the tools group
-      const cat = (rawCat === 'helper' ? 'tools' : rawCat) as SettingsCategory;
+      // Resolve the display category from the key prefix
+      let cat: SettingsCategory;
+      if (rawCat === 'helper') {
+        cat = 'tools';
+      } else if (rawCat === 'controlPlane') {
+        cat = 'network';
+        // SDK auto-restarts the daemon server on controlPlane binding changes
+        if (isRestartKey && previousValue !== value) {
+          this.lastSaveTriggeredRestart = 'control-plane';
+        }
+      } else if (rawCat === 'httpListener') {
+        cat = 'network';
+        // SDK auto-restarts the HTTP listener on binding changes
+        if (isRestartKey && previousValue !== value) {
+          this.lastSaveTriggeredRestart = 'http-listener';
+        }
+      } else if (rawCat === 'web') {
+        cat = 'network';
+        // SDK auto-restarts the web server on binding changes
+        if (isRestartKey && previousValue !== value) {
+          this.lastSaveTriggeredRestart = 'web';
+        }
+      } else {
+        cat = rawCat as SettingsCategory;
+      }
       const entries = this.groups.get(cat);
       if (entries) {
         const entry = entries.find(e => e.setting.key === key);

package/src/main.ts

@@ -80,6 +80,49 @@ function resolveShellEntrypointOwnership(): ShellEntrypointOwnership {
   };
 }
 
+// ---------------------------------------------------------------------------
+// CLI flag parsing (TUI shell entry point)
+// ---------------------------------------------------------------------------
+
+type TuiCliFlags = {
+  readonly provider: string | undefined;
+  readonly model: string | undefined;
+};
+
+function parseTuiCliFlags(argv: readonly string[]): TuiCliFlags {
+  let provider: string | undefined;
+  let model: string | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      // eslint-disable-next-line no-console
+      console.log([
+        'Usage: goodvibes [options]',
+        '',
+        'Options:',
+        '  --provider <id>          Override the provider from settings.json at startup',
+        '  --model <registryKey>    Override the model from settings.json at startup',
+        '                           Format: provider:modelId (e.g. inception:mercury-2)',
+        '                           If provider:modelId format is used, --provider is inferred',
+        '  --help, -h               Show this help message',
+      ].join('\n'));
+      process.exit(0);
+    }
+    if (arg === '--provider' && argv[i + 1] !== undefined) {
+      provider = argv[++i];
+    } else if (arg === '--model' && argv[i + 1] !== undefined) {
+      model = argv[++i];
+      // Infer provider from registryKey format (provider:modelId) if --provider not given
+      if (typeof model === 'string' && model.includes(':') && provider === undefined) {
+        provider = model.split(':')[0];
+      }
+    }
+  }
+
+  return { provider, model };
+}
+
 async function main() {
   const stdout = process.stdout;
   const stdin = process.stdin;
@@ -95,6 +138,15 @@ async function main() {
   });
   new GlobalNetworkTransportInstaller().install(configManager);
 
+  // Apply CLI flags — override settings.json before the provider registry is constructed
+  const cliFlags = parseTuiCliFlags(process.argv.slice(2));
+  if (cliFlags.provider !== undefined) {
+    configManager.set('provider.provider', cliFlags.provider);
+  }
+  if (cliFlags.model !== undefined) {
+    configManager.set('provider.model', cliFlags.model);
+  }
+
   // ── Bootstrap all runtime subsystems ─────────────────────────────────────
   // bootstrapRuntime initializes all subsystems in dependency order and returns
   // a fully-wired BootstrapContext. main.ts owns terminal setup, the render loop,

package/src/panels/agent-inspector-panel.ts

@@ -97,7 +97,7 @@ export class AgentInspectorPanel extends BasePanel {
   private cursorIndex = 0;
 
   // Refresh timer (active only while panel is active)
-  private refreshTimer: ReturnType<typeof setInterval> | null = null;
+  private refreshTimerId: ReturnType<typeof setInterval> | null = null;
 
   // Row cache — cleared on markDirty(), computed once per render cycle
   private _cachedRows: DisplayRow[] | null = null;
@@ -131,7 +131,7 @@ export class AgentInspectorPanel extends BasePanel {
     this.cursorIndex = 0;
     this.timeline = [];
     this.markDirty();
-    this._refreshTimeline().catch(() => {});
+    this._refreshTimeline().catch((err) => { logger.debug('agent inspector timeline refresh failed', { err }); });
   }
 
   // -------------------------------------------------------------------------
@@ -149,6 +149,7 @@ export class AgentInspectorPanel extends BasePanel {
 
   override onDestroy(): void {
     this._stopRefresh();
+    super.onDestroy();
   }
 
   // -------------------------------------------------------------------------
@@ -461,16 +462,16 @@ export class AgentInspectorPanel extends BasePanel {
   }
 
   private _startRefresh(): void {
-    if (this.refreshTimer) return;
-    this.refreshTimer = setInterval(() => {
-      this._refreshTimeline().catch(() => {});
-    }, REFRESH_MS);
+    if (this.refreshTimerId) return;
+    this.refreshTimerId = this.registerTimer(setInterval(() => {
+      this._refreshTimeline().catch((err) => { logger.debug('agent inspector timeline refresh tick failed', { err }); });
+    }, REFRESH_MS));
   }
 
   private _stopRefresh(): void {
-    if (this.refreshTimer) {
-      clearInterval(this.refreshTimer);
-      this.refreshTimer = null;
+    if (this.refreshTimerId) {
+      this.clearTimer(this.refreshTimerId);
+      this.refreshTimerId = null;
     }
   }
 

package/src/panels/agent-logs-panel.ts

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync, watch, type FSWatcher } from 'fs';
+import { promises as fsPromises, watch, type FSWatcher } from 'fs';
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine, createStyledCell } from '../types/grid.ts';
 import { ScrollableListPanel } from './scrollable-list-panel.ts';
@@ -61,6 +61,7 @@ export class AgentLogsPanel extends ScrollableListPanel<LogEntry> {
 
   constructor(agentEvents: UiEventFeed<AgentEvent>, private readonly deps: AgentLogsPanelDeps) {
     super('agent-logs', 'Agents', 'A', 'agent');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.agentEvents = agentEvents;
     this._refreshAgents();
     this._startPolling();
@@ -256,14 +257,22 @@ export class AgentLogsPanel extends ScrollableListPanel<LogEntry> {
   }
 
   private _pollCurrentAgent(): void {
+    void this._pollCurrentAgentAsync();
+  }
+
+  private async _pollCurrentAgentAsync(): Promise<void> {
     const agent = this._selectedAgent();
     if (!agent) return;
 
     const sessionFile = this._sessionFilePath(agent.id);
-    if (!existsSync(sessionFile)) return;
+    try {
+      await fsPromises.access(sessionFile);
+    } catch {
+      return;
+    }
 
     try {
-      const content = readFileSync(sessionFile, 'utf-8');
+      const content = await fsPromises.readFile(sessionFile, 'utf-8');
       if (content.length === this.lastFileSize) return;
       this.lastFileSize = content.length;
 
@@ -284,7 +293,9 @@ export class AgentLogsPanel extends ScrollableListPanel<LogEntry> {
   private _watchAgent(agentId: string): void {
     this._stopWatcher();
     const sessionFile = this._sessionFilePath(agentId);
-    if (!existsSync(sessionFile)) return;
+    // Start watching immediately; the watcher setup itself is synchronous,
+    // the file-existence check is skipped to avoid blocking — if the file
+    // does not yet exist watch() will throw and we catch it below.
     try {
       this.fsWatcher = watch(sessionFile, () => {
         if (!this.paused) {
@@ -392,24 +403,33 @@ export class AgentLogsPanel extends ScrollableListPanel<LogEntry> {
   }
 
   private _reloadAgent(agent: AgentRecord): void {
+    void this._reloadAgentAsync(agent);
+  }
+
+  private async _reloadAgentAsync(agent: AgentRecord): Promise<void> {
     const sessionFile = this._sessionFilePath(agent.id);
-    if (!existsSync(sessionFile)) {
+    try {
+      await fsPromises.access(sessionFile);
+    } catch {
       this.allEntries = [];
       this.filteredEntries = [];
       this.lastFileSize = 0;
+      this.markDirty();
       return;
     }
     try {
-      const content = readFileSync(sessionFile, 'utf-8');
+      const content = await fsPromises.readFile(sessionFile, 'utf-8');
       this.lastFileSize = content.length;
       this.allEntries = parseAgentJsonl(content);
       this._applyFilter();
       if (this.autoFollow) {
         this.selectedIndex = Math.max(0, this.filteredEntries.length - 1);
       }
+      this.markDirty();
     } catch {
       this.allEntries = [];
       this.filteredEntries = [];
+      this.markDirty();
     }
   }
 

package/src/panels/approval-panel.ts

@@ -33,6 +33,7 @@ export class ApprovalPanel extends ScrollableListPanel<ApprovalRow> {
 
   public constructor(policyRuntimeState: Pick<PolicyRuntimeState, 'getSnapshot'>) {
     super('approval', 'Approval', 'A', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.policyRuntimeState = policyRuntimeState;
   }
 

package/src/panels/automation-control-panel.ts

@@ -45,6 +45,7 @@ export class AutomationControlPanel extends ScrollableListPanel<AutomationRun> {
 
   public constructor(readModel?: UiReadModel<UiAutomationSnapshot>) {
     super('automation', 'Automation', 'M', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.readModel = readModel;
     this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
   }

package/src/panels/base-panel.ts

@@ -11,14 +11,54 @@ export abstract class BasePanel implements Panel {
   public isPinned = false;
   protected readonly componentHealthMonitor?: ComponentHealthMonitor;
 
+  // -------------------------------------------------------------------------
+  // Timer registry
+  // -------------------------------------------------------------------------
+
+  /** All timers registered via registerTimer(). Cleared automatically on onDestroy(). */
+  private readonly _timers: Set<ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>> = new Set();
+
+  /**
+   * Register a timer id (from setInterval or setTimeout) so it is
+   * automatically cleared when the panel is destroyed. Returns the id
+   * unchanged so the call can be chained inline:
+   *
+   * ```ts
+   * this.registerTimer(setInterval(() => this.refresh(), 5_000));
+   * ```
+   */
+  protected registerTimer<T extends ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>>(id: T): T {
+    this._timers.add(id);
+    return id;
+  }
+
+  /**
+   * Clear a specific timer and remove it from the registry.
+   * Safe to call with an id that was never registered or already cleared.
+   */
+  protected clearTimer(id: ReturnType<typeof setTimeout> | ReturnType<typeof setInterval>): void {
+    clearInterval(id as ReturnType<typeof setInterval>);
+    this._timers.delete(id);
+  }
+
   // -------------------------------------------------------------------------
   // I2: Error surface slot
   // -------------------------------------------------------------------------
 
-  /** Last error message to surface in the panel footer. Auto-cleared on next input. */
+  /**
+   * Last error message to surface in the panel footer.
+   * Auto-cleared on the next keystroke by `ScrollableListPanel.handleInput()` (and any
+   * subclass that calls `super.handleInput()` or manually calls `this.clearError()` at
+   * the start of its handler). BasePanel itself does NOT auto-clear — only subclasses
+   * that opt into the contract do.
+   */
   protected lastError: string | null = null;
 
-  /** Set a transient error message. Triggers a re-render. */
+  /**
+   * Set a transient error message. Triggers a re-render.
+   * The error will be auto-cleared on the next keystroke if the panel extends
+   * `ScrollableListPanel` (which calls `clearError()` at the top of `handleInput()`).
+   */
   protected setError(msg: string): void {
     this.lastError = msg;
     this.needsRender = true;
@@ -66,6 +106,32 @@ export abstract class BasePanel implements Panel {
     this.needsRender = true;
   }
 
+  /**
+   * Run an async operation with the panel's loading spinner visible.
+   * The spinner is always cleared on completion, whether the operation succeeds or throws
+   * (uses try/finally). Rethrows any error so callers can handle it or forward to setError.
+   *
+   * @param label Optional label shown next to the spinner.
+   * @param fn    The async work to run.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   await this.withLoading('Loading diff…', () => this.fetchDiff());
+   * } catch (err) {
+   *   this.setError(summarizeError(err));
+   * }
+   * ```
+   */
+  protected async withLoading<T>(label: string | undefined, fn: () => Promise<T>): Promise<T> {
+    this.startLoading(label);
+    try {
+      return await fn();
+    } finally {
+      this.stopLoading();
+    }
+  }
+
   /**
    * Build a spinner Line for the loading state.
    * Returns null when loadingState is not 'loading'.
@@ -107,7 +173,17 @@ export abstract class BasePanel implements Panel {
 
   onActivate(): void { this.needsRender = true; }
   onDeactivate(): void {}
-  onDestroy(): void {}
+
+  /**
+   * Called when the panel is permanently removed. Subclasses should call
+   * `super.onDestroy()` to ensure all registered timers are cleared.
+   */
+  onDestroy(): void {
+    for (const id of this._timers) {
+      clearInterval(id as ReturnType<typeof setInterval>);
+    }
+    this._timers.clear();
+  }
 
   abstract render(width: number, height: number): Line[];
 
@@ -146,4 +222,33 @@ export abstract class BasePanel implements Panel {
   protected reportRenderDuration(durationMs: number, now: number = Date.now()): void {
     this.componentHealthMonitor?.recordRender(this.id, durationMs, now);
   }
+
+  /** Cache of the most recent lines produced by trackedRender. */
+  private _lastTrackedLines: Line[] = [];
+
+  /**
+   * Wrap a render body with canRenderNow throttle check, wall-clock timing,
+   * and automatic reportRenderDuration.
+   *
+   * When throttled, returns the previously cached lines (stale but correctly
+   * sized) rather than empty lines, avoiding a flicker on every skipped frame.
+   *
+   * Usage:
+   * ```ts
+   * render(width: number, height: number): Line[] {
+   *   return this.trackedRender(() => {
+   *     // expensive render logic
+   *     return lines;
+   *   });
+   * }
+   * ```
+   */
+  protected trackedRender(fn: () => Line[]): Line[] {
+    if (!this.canRenderNow()) return this._lastTrackedLines;
+    const start = Date.now();
+    const lines = fn();
+    this.reportRenderDuration(Date.now() - start);
+    this._lastTrackedLines = lines;
+    return lines;
+  }
 }

package/src/panels/communication-panel.ts

@@ -32,6 +32,7 @@ export class CommunicationPanel extends ScrollableListPanel<CommunicationRecord>
 
   public constructor(readModel?: UiReadModel<UiCommunicationSnapshot>) {
     super('communication', 'Communication', 'Y', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.readModel = readModel;
     this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
   }

package/src/panels/context-visualizer-panel.ts

@@ -72,6 +72,7 @@ export class ContextVisualizerPanel extends BasePanel {
   }
 
   render(width: number, height: number): Line[] {
+    return this.trackedRender(() => {
     if (height <= 0 || width <= 0) return [];
 
     const input = this.snapshot.input;
@@ -131,6 +132,7 @@ export class ContextVisualizerPanel extends BasePanel {
       ],
       palette: DEFAULT_PANEL_PALETTE,
     });
+    });
   }
 
   private _renderBar(width: number, barWidth: number, input: number, limit: number): Line {

package/src/panels/control-plane-panel.ts

@@ -43,6 +43,7 @@ export class ControlPlanePanel extends ScrollableListPanel<ControlPlaneClient> {
 
   public constructor(private readonly readModel?: UiReadModel<UiControlPlaneSnapshot>) {
     super('control-plane', 'Control Plane', 'C', 'monitoring');
+    this.showSelectionGutter = true; // I5: non-color selection affordance
     this.unsub = readModel ? readModel.subscribe(() => this.markDirty()) : null;
   }
 

package/src/panels/diff-panel.ts

@@ -345,6 +345,7 @@ export class DiffPanel extends BasePanel {
   // -------------------------------------------------------------------------
 
   render(width: number, height: number): Line[] {
+    return this.trackedRender(() => {
     if (height <= 0 || width <= 0) return [];
 
     if (this.entries.length === 0) {
@@ -440,6 +441,7 @@ export class DiffPanel extends BasePanel {
       sections,
       footerLines: [this.renderStatusBar(width, entry)],
     });
+    });
   }
 
   // ── Tab bar ──────────────────────────────────────────────────────────────