@lincoln504/pi-research 0.1.12 → 1.0.0

package/src/tui/research-tui-manager.ts

@@ -0,0 +1,233 @@
+/**
+ * Research TUI Manager
+ *
+ * Manages TUI interactions for research sessions:
+ * - Master widget creation and updates
+ * - Session panel management
+ * - Terminal input handling for cancellation
+ * - Debounced refresh coordination
+ */
+
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { TUI } from '@earendil-works/pi-tui';
+import { logger } from '../logger.ts';
+import type { Theme } from '../types/research-panel-types.ts';
+import {
+  createMasterResearchPanel,
+  createInitialPanelState,
+  clearAllFlashTimeouts,
+} from './research-panel.ts';
+import {
+  registerSessionPanel,
+  registerMasterUpdate,
+  registerMasterRemove,
+  refreshAllSessions,
+  flushMasterNow,
+  onSessionOrderChange,
+  getPiActivePanels,
+  normalizeSessionId,
+} from '../orchestration/session-state.ts';
+import { initGlobalTuiController, isInteractiveTuiActive } from './tui-controller.ts';
+import type { ResearchPanelState } from './research-panel.ts';
+
+export interface TuiContext {
+  piSessionId: string;
+  researchId: string;
+  query: string;
+  modelId: string;
+}
+
+export interface TuiDependencies {
+  ctx: ExtensionContext;
+}
+
+export interface TuiManager {
+  panelState: ResearchPanelState;
+  masterWidgetId: string;
+  unsubOrder: (() => void) | null;
+  debouncedRefresh: () => void;
+  /**
+   * Render the panel immediately, bypassing the debounce. Used by the wave
+   * animation pulse so frames are not swallowed by the 100ms state-refresh
+   * debounce; pi-tui's own 16ms throttle + diff caps and smooths the output.
+   */
+  renderImmediate: () => void;
+  initializePanel: () => void;
+  dispose: () => void;
+}
+
+/**
+ * Create a TUI manager for a research session
+ */
+export function createResearchTuiManager(
+  tuiCtx: TuiContext,
+  deps: TuiDependencies
+): TuiManager {
+  const {
+    piSessionId: rawPiSessionId,
+    researchId,
+    query,
+    modelId,
+  } = tuiCtx;
+  
+  const piSessionId = normalizeSessionId(rawPiSessionId);
+  const { ctx } = deps;
+  
+  const masterWidgetId = `pi-research-master-${piSessionId}`;
+  const panelState = createInitialPanelState(piSessionId, researchId, query, modelId);
+  logger.debug(`[tui-manager] Creating manager for session ${piSessionId}, research ${researchId}`);
+  
+  // Ensure the global TUI controller is initialized (handles cancellation and protocol leaks)
+  // Only in TUI mode with UI available
+  if (ctx.mode === 'tui' && ctx.hasUI) {
+    initGlobalTuiController(ctx.ui, piSessionId);
+  }
+
+  let unsubOrder: (() => void) | null = null;
+  let refreshTimeout: NodeJS.Timeout | null = null;
+  let refreshScheduled = false;
+
+  // Register the panel state
+  registerSessionPanel(piSessionId, researchId, panelState);
+
+  /**
+   * Debounced refresh to avoid excessive UI updates
+   */
+  const debouncedRefresh = () => {
+    // Only refresh if in TUI mode
+    if (ctx.mode !== 'tui') return;
+
+    if (refreshScheduled) return;
+
+    // Do not schedule background refreshes if a foreground interactive menu is active.
+    // This prevents background processing from stealing focus or fighting with the 
+    // interactive TUI's own rendering loop.
+    if (isInteractiveTuiActive()) return;
+
+    refreshScheduled = true;
+    
+    refreshTimeout = setTimeout(() => {
+      refreshScheduled = false;
+      refreshAllSessions(piSessionId);
+    }, 16); // 16ms coalescing window for low-frequency state changes (tokens,
+            // status, slices). Animation frames do NOT use this path — they go
+            // through renderImmediate() so they are never swallowed by the
+            // downstream 100ms refreshAllSessions debounce.
+  };
+
+  /**
+   * Initialize the master widget
+   */
+  const initializePanel = () => {
+    // Only initialize if in TUI mode and UI is available
+    if (ctx.mode !== 'tui' || !ctx.hasUI) return;
+    
+    // Do not initialize background widgets if a foreground interactive menu is active
+    if (isInteractiveTuiActive()) return;
+
+    const masterPanelCreator = createMasterResearchPanel(piSessionId, () => {
+      // Get active panels lazily to avoid circular dependencies
+      return getActivePanelsForSession(piSessionId);
+    });
+    
+    ctx.ui.setWidget(masterWidgetId, (tui: TUI, theme: Theme) => masterPanelCreator(tui, theme), { placement: 'aboveEditor' });
+  };
+
+  // Register master update function (re-registers the widget to trigger a render)
+  // setExtensionWidget() removes the old widget before adding the new one — no stacking.
+  // Calling refreshAllSessions() here would cause an infinite loop:
+  //   debouncedRefresh → refreshAllSessions → masterUpdate → refreshAllSessions → …
+  registerMasterUpdate(piSessionId, () => {
+    // Only update if in TUI mode and UI is available
+    if (ctx.mode !== 'tui' || !ctx.hasUI) return;
+    
+    // Do not update background widgets if a foreground interactive menu is active!
+    // This prevents the background research widget from fighting with the settings menu,
+    // which causes the terminal cursor to jump and "spam" duplicates down the screen.
+    if (isInteractiveTuiActive()) return;
+
+    const masterPanelCreator = createMasterResearchPanel(piSessionId, () => {
+      return getActivePanelsForSession(piSessionId);
+    });
+    ctx.ui.setWidget(masterWidgetId, (tui: TUI, theme: Theme) => masterPanelCreator(tui, theme), { placement: 'aboveEditor' });
+  });
+
+  // Register the remover so a foreground menu can fully hide the live panel.
+  // setWidget(key, undefined) removes the widget and forces a clean re-layout
+  // (renderWidgets()), which both frees the screen for the menu and clears any
+  // rows the panel occupied — preventing ghost/stacked panels on close.
+  registerMasterRemove(piSessionId, () => {
+    if (ctx.mode !== 'tui' || !ctx.hasUI) return;
+    (ctx.ui as unknown as { setWidget: (k: string, c?: unknown) => void }).setWidget(masterWidgetId, undefined);
+  });
+
+  // Subscribe to session order changes
+  unsubOrder = onSessionOrderChange(piSessionId, () => refreshAllSessions(piSessionId));
+
+  /**
+   * Dispose of TUI resources
+   */
+  const dispose = () => {
+    // Scope the clear to THIS run — clearing by piSessionId would cancel the flash
+    // timers of any concurrent sibling run sharing the session.
+    clearAllFlashTimeouts(researchId);
+
+    if (refreshTimeout) {
+      clearTimeout(refreshTimeout);
+      refreshTimeout = null;
+    }
+    
+    if (unsubOrder) {
+      unsubOrder();
+      unsubOrder = null;
+    }
+  };
+
+  /**
+   * Immediate (non-debounced) render for animation frames.
+   * Honors the same TUI-mode guard as debouncedRefresh; the foreground-menu
+   * guard lives inside masterUpdate (flushMasterNow → masterUpdate).
+   */
+  const renderImmediate = () => {
+    if (ctx.mode !== 'tui') return;
+    flushMasterNow(piSessionId);
+  };
+
+  return {
+    panelState,
+    masterWidgetId,
+    unsubOrder,
+    debouncedRefresh,
+    renderImmediate,
+    initializePanel,
+    dispose,
+  };
+}
+
+/**
+ * Get active panels for a session
+ * Helper function to avoid circular dependencies
+ */
+function getActivePanelsForSession(piSessionId: string) {
+  return getPiActivePanels(piSessionId);
+}
+
+/**
+ * Hide the working indicator during research
+ */
+export function hideWorkingIndicator(ctx: ExtensionContext): void {
+  const tuiUI = ctx.ui as { setWorkingVisible?: (visible: boolean) => void };
+  if (typeof tuiUI?.setWorkingVisible === 'function') {
+    tuiUI.setWorkingVisible(false);
+  }
+}
+
+/**
+ * Show the working indicator (typically on cleanup)
+ */
+export function showWorkingIndicator(ctx: ExtensionContext): void {
+  const tuiUI = ctx.ui as { setWorkingVisible?: (visible: boolean) => void };
+  if (typeof tuiUI?.setWorkingVisible === 'function') {
+    tuiUI.setWorkingVisible(true);
+  }
+}

package/src/tui/tui-controller.ts

@@ -0,0 +1,137 @@
+/**
+ * Global TUI Controller
+ *
+ * Centralizes TUI-related logic that needs to be global across the extension:
+ * - Single onTerminalInput listener per Pi session
+ * - Protocol response filtering
+ * - Global cancellation (Esc/Ctrl+C) with context awareness
+ */
+
+import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import { matchesKey } from '@earendil-works/pi-tui';
+import { getActiveSessionCount, abortAllSessions, refreshAllSessions, hideMasterWidget } from '../orchestration/session-state.ts';
+import { logger } from '../logger.ts';
+
+/**
+ * Global state for TUI controller
+ */
+interface GlobalTuiState {
+  /** Unsubscribe function for terminal input listener */
+  unsubInput: (() => void) | null;
+  /** Whether an interactive custom TUI is currently active */
+  isInteractiveTuiActive: boolean;
+  /** The Pi session ID this controller belongs to */
+  piSessionId: string | undefined;
+}
+
+const state: GlobalTuiState = {
+  unsubInput: null,
+  isInteractiveTuiActive: false,
+  piSessionId: undefined,
+};
+
+/**
+ * Initialize the global TUI controller
+ * 
+ * @param ui - The UI context from Pi
+ * @param piSessionId - The current Pi session ID for scoped cancellation
+ */
+export function initGlobalTuiController(ui: ExtensionUIContext, piSessionId?: string): void {
+  // Always refresh the active session id FIRST — even when the input handler is
+  // already wired from a prior run. A second research run in the same process must
+  // scope cancellation (Esc/Ctrl+C), widget hide/restore, and abortAllSessions to
+  // ITS session; the old guard returned early and left piSessionId stuck on run 1.
+  state.piSessionId = piSessionId;
+
+  if (state.unsubInput) return;
+
+  // Double check if ui and onTerminalInput exist (it should in interactive mode)
+  if (!ui || typeof ui.onTerminalInput !== 'function') {
+    logger.debug('[TUI] Global TUI controller skipped: UI context or onTerminalInput not available');
+    return;
+  }
+
+  /**
+   * Handle terminal input for cancellation and protocol cleanup
+
+   */
+  const handleTerminalInput = (data: string) => {
+    // If an interactive TUI is active (like the config menu), 
+    // let it handle ALL input. We don't want to trigger a global abort
+    // while the user is navigating a menu.
+    if (state.isInteractiveTuiActive) {
+      return undefined;
+    }
+
+    // Check for specific global cancel keys (Escape and Ctrl+C)
+    // We only trigger abort if research is actually running.
+    if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c')) {
+      const activeCount = getActiveSessionCount();
+      if (activeCount > 0) {
+        // FIX (New Issues B & E): Use abortAllSessions scoped to the current Pi session
+        // instead of clearAllSessionState() which nukes ALL sessions across ALL Pi instances.
+        logger.info(`[TUI] Global cancel requested (${data === '\x03' ? 'Ctrl+C' : 'Esc'}). Aborting active sessions...`);
+        
+        try {
+          // Scope to this Pi session to avoid cross-session interference
+          abortAllSessions(state.piSessionId);
+        } catch (err) {
+          logger.error('[TUI] Failed to abort sessions on cancel:', err);
+        }
+      }
+      
+      // Let the key fall through so Pi can handle its own cancellation
+      // or other TUIs can respond.
+      return undefined;
+    }
+
+    return undefined;
+  };
+
+  // Register the global listener
+  state.unsubInput = ui.onTerminalInput(handleTerminalInput);
+  
+  logger.debug('[TUI] Global TUI controller initialized');
+}
+
+/**
+ * Mark an interactive TUI as active/inactive
+ */
+export function setInteractiveTuiActive(active: boolean): void {
+  state.isInteractiveTuiActive = active;
+  logger.debug(`[TUI] Interactive TUI state changed: ${active}`);
+
+  if (active && state.piSessionId !== undefined) {
+    // When a foreground menu opens, fully remove the live research panel from
+    // the screen. Freezing its updates (the isInteractiveTuiActive gate) is not
+    // enough: a tall, still-present panel above the editor crowds the inline
+    // menu and leaves ghost rows behind. Removing it gives the menu the full
+    // screen, identical to opening the menu with no run active.
+    hideMasterWidget(state.piSessionId);
+  }
+
+  if (!active && state.piSessionId !== undefined) {
+    // When the menu closes, immediately refresh the background research widgets
+    // because they were paused/removed while the menu was open.
+    refreshAllSessions(state.piSessionId);
+  }
+}
+
+/**
+ * Check if an interactive TUI is active
+ */
+export function isInteractiveTuiActive(): boolean {
+  return state.isInteractiveTuiActive;
+}
+
+/**
+ * Dispose the global TUI controller
+ */
+export function disposeGlobalTuiController(): void {
+  if (state.unsubInput) {
+    state.unsubInput();
+    state.unsubInput = null;
+  }
+  state.piSessionId = undefined;
+  state.isInteractiveTuiActive = false;
+}

package/src/types/extension-context.ts

@@ -1,60 +1,29 @@
 /**
  * Extended Type Definitions for pi Extension Context
  *
- * These types extend the base ExtensionContext from @mariozechner/pi-coding-agent
+ * These types extend the base ExtensionContext from @earendil-works/pi-coding-agent
  * to provide type safety for additional properties that are accessed at runtime.
  */
 
-import type { SettingsManager } from '@mariozechner/pi-coding-agent';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+export type { AgentSessionEvent } from '@earendil-works/pi-coding-agent';
 
 /**
- * Session manager interface for accessing session metadata
- */
-export interface SessionManager {
-  getSessionId(): string;
-  getSessionFile(): string;
-}
-
-/**
- * Extended ExtensionContext with additional properties
- * Note: We don't extend ExtensionContext to avoid type conflicts with
- * ReadonlySessionManager. This is used as a cast target only.
+ * Extended ExtensionContext with additional properties.
+ * Provides type safety for properties accessed at runtime.
+ *
+ * NOTE: We do NOT re-declare properties from ExtensionContext (sessionManager,
+ * modelRegistry, etc.) to avoid type conflicts when the base library evolves.
+ * Instead, consumers cast to ExtendedExtensionContext only for the properties
+ * that the base type doesn't include (sessionId, settingsManager, excludeTools).
  */
-export interface ExtendedExtensionContext {
-  sessionManager?: SessionManager;
-  settingsManager?: SettingsManager;
-}
+export interface ExtendedExtensionContext extends ExtensionContext {
+   /** Session ID (provided by extension host) */
+   sessionId?: string;
+   /** Settings manager (provided in some contexts) */
+   settingsManager?: any;
+   /** Current tool exclusion list */
+   excludeTools?: string[];
+ }
 
-/**
- * Model with ID property and optional cost information
- */
-export interface ModelWithId {
-  id: string;
-  cost?: {
-    input: number;
-    output: number;
-    cacheRead?: number;
-    cacheWrite?: number;
-  };
-}
 
-/**
- * Agent session event with usage and error information
- */
-export interface ExtendedAgentSessionEvent {
-  type: string;
-  message?: {
-    role?: string;
-    usage?: {
-      totalTokens?: number;
-      input?: number;
-      output?: number;
-      cacheRead?: number;
-      cacheWrite?: number;
-    };
-  };
-  isError?: boolean;
-  details?: {
-    blocked?: boolean;
-  };
-}

package/src/types/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Central type definitions for pi-research
+ * This module provides strongly-typed interfaces to replace 'as any' usage
+ */
+
+/**
+ * Research depth levels
+ */
+export type ResearchDepth = 0 | 1 | 2 | 3;
+
+/**
+ * Research result details
+ */
+export interface ResearchResultDetails {
+  totalTokens?: number;
+  cost?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Browser task with query or URL
+ */
+export interface BrowserTask {
+  query?: string;
+  url?: string;
+  sessionId?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Context object threaded through cleanup operations for a research session.
+ */
+export interface CleanupContext {
+  researchId: string;
+  piSessionId: string;
+  masterWidgetId: string;
+  panelState: import('./research-panel-types.ts').ResearchPanelState;
+  waveTimer: NodeJS.Timeout | null;
+  unsubOrder: (() => void) | null;
+  unsubOrderRef?: { value: (() => void) | null };
+}
+
+/**
+ * Research message from observer events
+ */
+export interface ResearchMessage {
+  type: string;
+  content?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Node.js error with code property
+ */
+export interface NodeError extends Error {
+  code?: string;
+  errno?: number;
+  syscall?: string;
+  [key: string]: unknown;
+}
+

package/src/types/llm.ts

@@ -2,12 +2,14 @@
  * LLM-Related Type Definitions
  *
  * Shared type definitions for LLM responses, usage, and message content.
- * These types complement the types from @mariozechner/pi-ai and provide
+ * These types complement the types from @earendil-works/pi-ai and provide
  * more specific typing for our use cases.
  */
 
+import { calculateCost, type Model } from '@earendil-works/pi-ai';
+
 /**
- * Token usage information from LLM responses
+ * Token usage and cost information from LLM responses
  */
 export interface TokenUsage {
   /** Input tokens consumed */
@@ -20,10 +22,18 @@ export interface TokenUsage {
   cacheWrite?: number;
   /** Total tokens (may be provided by some providers) */
   totalTokens?: number;
+  /** Cost details */
+  cost?: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
 }
 
 /**
- * Text content block in a message
+ * Text content block
  */
 export interface TextContentBlock {
   type: 'text';
@@ -31,48 +41,44 @@ export interface TextContentBlock {
 }
 
 /**
- * Message content (can be a string or array of blocks)
+ * Thinking/Reasoning content block
  */
-export type MessageContent = string | TextContentBlock[];
+export interface ThinkingContentBlock {
+  type: 'thinking';
+  content: string;
+}
 
 /**
- * Filter for text content blocks from a message content array
+ * Tool call block
  */
-export function isTextContentBlock(block: unknown): block is TextContentBlock {
-  return (
-    block !== null &&
-    typeof block === 'object' &&
-    (block as Record<string, unknown>)['type'] === 'text' &&
-    typeof (block as Record<string, unknown>)['text'] === 'string'
-  );
+export interface ToolCallBlock {
+  type: 'tool_call';
+  id?: string;
+  name: string;
+  arguments: any;
 }
 
 /**
- * Extract text from a message content block or string
+ * Message content block
  */
-export function extractTextFromContent(content: MessageContent): string {
-  if (typeof content === 'string') {
-    return content;
-  }
-  if (Array.isArray(content)) {
-    return content
-      .filter(isTextContentBlock)
-      .map(block => block.text)
-      .join('\n');
-  }
-  return '';
-}
+export type MessageBlock = TextContentBlock | ThinkingContentBlock | ToolCallBlock;
+
+/**
+ * Message content (can be a string or array of blocks)
+ */
+export type MessageContent = string | MessageBlock[];
+
 
 /**
  * Parse token usage from an unknown object
  * Returns a partial usage object with any fields that were present
  */
-export function parseTokenUsage(usage: unknown): Partial<TokenUsage> {
+function parseTokenUsage(usage: unknown): Partial<TokenUsage> {
   if (!usage || typeof usage !== 'object') {
     return {};
   }
 
-  const obj = usage as Record<string, unknown>;
+  const obj = usage as Record<string, any>;
   const result: Partial<TokenUsage> = {};
 
   if (typeof obj['input'] === 'number') {
@@ -90,6 +96,9 @@ export function parseTokenUsage(usage: unknown): Partial<TokenUsage> {
   if (typeof obj['totalTokens'] === 'number') {
     result.totalTokens = obj['totalTokens'];
   }
+  if (obj['cost'] && typeof obj['cost'] === 'object') {
+    result.cost = obj['cost'];
+  }
 
   return result;
 }
@@ -98,7 +107,7 @@ export function parseTokenUsage(usage: unknown): Partial<TokenUsage> {
  * Calculate total tokens from usage object
  * Falls back to sum of individual components if totalTokens not provided
  */
-export function calculateTotalTokens(usage: Partial<TokenUsage>): number {
+function calculateTotalTokens(usage: Partial<TokenUsage>): number {
   if (usage.totalTokens !== undefined) {
     return usage.totalTokens;
   }
@@ -109,3 +118,33 @@ export function calculateTotalTokens(usage: Partial<TokenUsage>): number {
     (usage.cacheWrite ?? 0)
   );
 }
+
+/**
+ * Extract usage (tokens and cost) from a raw LLM usage object.
+ * Handles both provided cost and estimated cost via calculateCost.
+ * 
+ * @param model - The model used for the call (for cost estimation)
+ * @param rawUsage - The raw usage object from the LLM response
+ */
+export function extractUsage(model: Model<any>, rawUsage: any): { tokens: number; cost: number; parsed: Partial<TokenUsage> } {
+  if (!rawUsage) {
+    return { tokens: 0, cost: 0, parsed: {} };
+  }
+
+  const parsed = parseTokenUsage(rawUsage);
+  const tokens = calculateTotalTokens(parsed);
+
+  // Ultra-accurate cost calculation
+  let cost = parsed.cost?.total ?? rawUsage.cost?.total ?? 0;
+  if (cost === 0 && tokens > 0) {
+    try {
+      const calculatedCost = calculateCost(model, rawUsage);
+      cost = calculatedCost.total;
+    } catch {
+      // Best-effort cost calculation; if calculateCost fails (e.g. model not in registry), keep 0.
+    }
+  }
+
+  return { tokens, cost, parsed };
+}
+