@lincoln504/pi-research 0.1.13 → 1.0.1

package/src/utils/inject-date.ts

@@ -1,29 +0,0 @@
-/**
- * Date Injection Utility
- *
- * Injects the current date into agent prompts.
- */
-
-/**
- * Format current date as a readable string
- */
-function getCurrentDateString(): string {
-  const now = new Date();
-  const options: Intl.DateTimeFormatOptions = {
-    weekday: 'long',
-    year: 'numeric',
-    month: 'long',
-    day: 'numeric',
-  };
-  return now.toLocaleDateString('en-US', options);
-}
-
-/**
- * Inject current date into a prompt
- * Prepends a date context line to the prompt
- */
-export function injectCurrentDate(prompt: string, _agentType: 'coordinator' | 'researcher'): string {
-  const dateString = getCurrentDateString();
-  const dateContext = `**Current Date:** ${dateString}\n\n`;
-  return dateContext + prompt;
-}

package/src/utils/research-error.ts

@@ -1,205 +0,0 @@
-/**
- * Research Error Handling
- *
- * Custom error class and error codes for research operations.
- */
-
-import { logger } from '../logger.ts';
-
-/**
- * Research error codes
- */
-export enum ResearchErrorCode {
-  // General errors
-  UNKNOWN = 'UNKNOWN',
-  INVALID_INPUT = 'INVALID_INPUT',
-  NOT_IMPLEMENTED = 'NOT_IMPLEMENTED',
-
-  // Configuration errors
-  CONFIG_INVALID = 'CONFIG_INVALID',
-  CONFIG_MISSING = 'CONFIG_MISSING',
-
-  // Network/API errors
-  NETWORK_ERROR = 'NETWORK_ERROR',
-  API_ERROR = 'API_ERROR',
-  API_RATE_LIMITED = 'API_RATE_LIMITED',
-  API_TIMEOUT = 'API_TIMEOUT',
-  API_UNAVAILABLE = 'API_UNAVAILABLE',
-
-  // SearXNG errors
-  SEARXNG_START_FAILED = 'SEARXNG_START_FAILED',
-  SEARXNG_NOT_RUNNING = 'SEARXNG_NOT_RUNNING',
-  SEARXNG_QUERY_FAILED = 'SEARXNG_QUERY_FAILED',
-
-  // Orchestrator errors
-  ORCHESTRATION_FAILED = 'ORCHESTRATION_FAILED',
-  PLANNING_FAILED = 'PLANNING_FAILED',
-  RESEARCH_FAILED = 'RESEARCH_FAILED',
-  SYNTHESIS_FAILED = 'SYNTHESIS_FAILED',
-
-  // Researcher errors
-  RESEARCHER_FAILED = 'RESEARCHER_FAILED',
-  RESEARCHER_TIMEOUT = 'RESEARCHER_TIMEOUT',
-
-  // Scraping errors
-  SCRAPE_FAILED = 'SCRAPE_FAILED',
-  SCRAPE_TIMEOUT = 'SCRAPE_TIMEOUT',
-  SCRAPE_RATE_LIMITED = 'SCRAPE_RATE_LIMITED',
-
-  // Export errors
-  EXPORT_FAILED = 'EXPORT_FAILED',
-
-  // Validation errors
-  VALIDATION_FAILED = 'VALIDATION_FAILED',
-  QUERY_TOO_SHORT = 'QUERY_TOO_SHORT',
-  QUERY_TOO_LONG = 'QUERY_TOO_LONG',
-  QUERY_INVALID = 'QUERY_INVALID',
-
-  // State errors
-  STATE_INVALID = 'STATE_INVALID',
-  STATE_TRANSITION_FAILED = 'STATE_TRANSITION_FAILED',
-}
-
-/**
- * Research error class
- *
- * Provides structured error information for research operations.
- */
-export class ResearchError extends Error {
-  public readonly code: ResearchErrorCode;
-  public readonly details?: unknown;
-  public readonly correlationId: string;
-  public readonly timestamp: number;
-
-  constructor(
-    code: ResearchErrorCode,
-    message: string,
-    details?: unknown,
-  ) {
-    super(message);
-    this.name = 'ResearchError';
-    this.code = code;
-    this.details = details;
-    this.correlationId = generateCorrelationId();
-    this.timestamp = Date.now();
-
-    // Ensure proper prototype chain
-    Object.setPrototypeOf(this, ResearchError.prototype);
-  }
-
-  /**
-   * Convert error to a serializable object
-   */
-  toJSON(): {
-    name: string;
-    code: ResearchErrorCode;
-    message: string;
-    details?: unknown;
-    correlationId: string;
-    timestamp: number;
-  } {
-    return {
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      details: this.details,
-      correlationId: this.correlationId,
-      timestamp: this.timestamp,
-    };
-  }
-
-  /**
-   * Log the error with correlation ID
-   */
-  log(context?: string): void {
-    const prefix = context ? `[${context}] ` : '';
-    logger.error(`${prefix}ResearchError: ${this.code}`, {
-      message: this.message,
-      details: this.details,
-      correlationId: this.correlationId,
-      timestamp: this.timestamp,
-    });
-  }
-}
-
-/**
- * Generate a correlation ID for error tracking
- */
-function generateCorrelationId(): string {
-  return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
-}
-
-/**
- * Create a ResearchError from an unknown error
- *
- * @param error - The error to convert
- * @param defaultCode - Default error code if type cannot be determined
- * @returns A ResearchError instance
- */
-export function createResearchError(
-  error: unknown,
-  defaultCode: ResearchErrorCode = ResearchErrorCode.UNKNOWN,
-): ResearchError {
-  if (error instanceof ResearchError) {
-    return error;
-  }
-
-  if (error instanceof Error) {
-    // Try to determine error code from error message
-    const message = error.message.toLowerCase();
-
-    if (message.includes('timeout')) {
-      return new ResearchError(ResearchErrorCode.API_TIMEOUT, error.message, error);
-    }
-
-    if (message.includes('rate limit') || message.includes('too many requests')) {
-      return new ResearchError(ResearchErrorCode.API_RATE_LIMITED, error.message, error);
-    }
-
-    if (message.includes('network') || message.includes('econnrefused')) {
-      return new ResearchError(ResearchErrorCode.NETWORK_ERROR, error.message, error);
-    }
-
-    if (message.includes('404') || message.includes('not found')) {
-      return new ResearchError(ResearchErrorCode.API_UNAVAILABLE, error.message, error);
-    }
-
-    // Generic error
-    return new ResearchError(defaultCode, error.message, error);
-  }
-
-  // Unknown error type
-  return new ResearchError(
-    defaultCode,
-    typeof error === 'string' ? error : 'Unknown error',
-    error,
-  );
-}
-
-/**
- * Check if an error is transient (can be retried)
- *
- * @param error - The error to check
- * @returns True if the error is transient
- */
-export function isTransientError(error: ResearchError): boolean {
-  const transientCodes = [
-    ResearchErrorCode.NETWORK_ERROR,
-    ResearchErrorCode.API_RATE_LIMITED,
-    ResearchErrorCode.API_TIMEOUT,
-    ResearchErrorCode.API_UNAVAILABLE,
-    ResearchErrorCode.SEARXNG_START_FAILED,
-  ];
-
-  return transientCodes.includes(error.code);
-}
-
-/**
- * Check if an error is fatal (cannot be retried)
- *
- * @param error - The error to check
- * @returns True if the error is fatal
- */
-export function isFatalError(error: ResearchError): boolean {
-  return !isTransientError(error);
-}

package/src/utils/searxng-config.ts

@@ -1,94 +0,0 @@
-/**
- * SearXNG Configuration Loader
- *
- * Reads the SearXNG config YAML and extracts active search engines.
- * Ensures healthcheck and config stay synchronized.
- */
-
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { load } from 'js-yaml';
-import { logger } from '../logger.ts';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-function parseYamlEngines(content: string): Array<{ name: string; disabled?: boolean }> {
-  const parsed = load(content) as { engines?: Array<{ name?: string; disabled?: boolean }> } | undefined;
-  const engines = parsed?.engines;
-
-  if (!Array.isArray(engines)) {
-    logger.warn('[searxng-config] No engines section found in config');
-    return [];
-  }
-
-  return engines
-    .filter((engine): engine is { name: string; disabled?: boolean } => typeof engine?.name === 'string')
-    .map((engine) => ({ name: engine.name.trim(), disabled: engine.disabled === true }));
-}
-
-/**
- * Load SearXNG configuration and extract active general search engines
- * Filters out:
- * - Disabled engines
- * - Category-specific engines (images, news, videos)
- * - Category-restricted engines (stackoverflow, arxiv, semantic scholar, etc.)
- * - Encyclopedic engines (wikipedia)
- */
-export function getActiveSearxngEngines(): string[] {
-  try {
-    const configPath = join(__dirname, '../../config/searxng/default-settings.yml');
-    const content = readFileSync(configPath, 'utf-8');
-    const allEngines = parseYamlEngines(content);
-
-    // List of general purpose search engines (whitelist approach is safer)
-    const knownGeneralEngines = ['google', 'bing', 'brave', 'duckduckgo', 'startpage', 'mojeek', 'qwant'];
-
-    // Filter for general search engines only
-    const activeGeneralEngines = allEngines
-      .filter(
-        e =>
-          !e.disabled && // Not disabled
-          knownGeneralEngines.includes(e.name.toLowerCase()) // Only known general engines
-      )
-      .map(e => e.name.toLowerCase());
-
-    if (activeGeneralEngines.length === 0) {
-      logger.warn('[searxng-config] No active general search engines found in config');
-    }
-
-    logger.log(`[searxng-config] Active general search engines: [${activeGeneralEngines.join(', ')}]`);
-    return activeGeneralEngines;
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    logger.error('[searxng-config] Failed to load config:', msg);
-    // Fallback to known good defaults if config can't be loaded
-    return ['google', 'bing', 'brave'];
-  }
-}
-
-/**
- * Validate that healthcheck engine list matches config
- * Used in tests to catch drift
- */
-export function validateEngineListConsistency(expectedEngines: string[]): {
-  isValid: boolean;
-  missing: string[];
-  extra: string[];
-} {
-  const actualEngines = getActiveSearxngEngines();
-  const actualSet = new Set(actualEngines);
-  const expectedSet = new Set(expectedEngines);
-
-  const missing = actualEngines.filter(e => !expectedSet.has(e));
-  const extra = expectedEngines.filter(e => !actualSet.has(e));
-
-  const isValid = missing.length === 0 && extra.length === 0;
-
-  return {
-    isValid,
-    missing,
-    extra,
-  };
-}

package/src/utils/session-state.ts

@@ -1,295 +0,0 @@
-/**
- * Research Session State Management
- *
- * Tracks failures and state for multiple simultaneous research sessions,
- * scoped by parent Pi session to prevent cross-context interference.
- */
-
-import { generateSessionId as generateUniqueSessionId } from './shared-links.ts';
-import { logger } from '../logger.ts';
-import { getConfig } from '../config.ts';
-import type { ResearchPanelState } from '../tui/research-panel.ts';
-
-/**
- * State container for a single Pi session
- */
-interface PiSessionState {
-  /** Map of research run ID → array of failed researcher IDs */
-  failures: Map<string, string[]>;
-  /** Ordered list of research run IDs for TUI stacking (Index 0 = oldest/bottom-most) */
-  order: string[];
-  /** Registry of panel states for each research run */
-  panels: Map<string, ResearchPanelState>;
-  /** Subscribers for order changes in this Pi session */
-  subscribers: Array<() => void>;
-  /** Global debounce timer for this specific Pi session */
-  refreshTimeout: NodeJS.Timeout | null;
-  /** Single update function for the Master Widget of this Pi session */
-  masterUpdate: (() => void) | null;
-}
-
-/**
- * Global map of Pi session ID → PiSessionState
- */
-const piSessions = new Map<string, PiSessionState>();
-
-/**
- * Get or create state for a specific Pi session
- */
-function getPiState(piSessionId: string): PiSessionState {
-  let state = piSessions.get(piSessionId);
-  if (!state) {
-    state = {
-      failures: new Map(),
-      order: [],
-      panels: new Map(),
-      subscribers: [],
-      refreshTimeout: null,
-      masterUpdate: null,
-    };
-    piSessions.set(piSessionId, state);
-  }
-  return state;
-}
-
-/**
- * Maximum allowed unique failed researchers before stopping research
- */
-const MAX_FAILED_RESEARCHERS = 2;
-
-/**
- * Subscribe to session order changes for a specific Pi session
- */
-export function onSessionOrderChange(piSessionId: string, callback: () => void): () => void {
-  const state = getPiState(piSessionId);
-  state.subscribers.push(callback);
-  return () => {
-    const index = state.subscribers.indexOf(callback);
-    if (index !== -1) {
-      state.subscribers.splice(index, 1);
-    }
-  };
-}
-
-/**
- * Notify subscribers of session order change
- */
-function notifyOrderChange(piSessionId: string): void {
-  const state = getPiState(piSessionId);
-  for (const subscriber of state.subscribers) {
-    try {
-      subscriber();
-    } catch (error) {
-      logger.error(`[session-state] Error in subscriber for ${piSessionId}:`, error);
-    }
-  }
-}
-
-/**
- * Register a panel state for a research run
- */
-export function registerSessionPanel(piSessionId: string, researchId: string, panel: ResearchPanelState): void {
-  const state = getPiState(piSessionId);
-  state.panels.set(researchId, panel);
-  
-  if (!state.order.includes(researchId)) {
-    state.order.push(researchId);
-    notifyOrderChange(piSessionId);
-  }
-}
-
-/**
- * Unregister a panel state
- */
-export function unregisterSessionPanel(piSessionId: string, researchId: string): void {
-  const state = getPiState(piSessionId);
-  state.panels.delete(researchId);
-}
-
-/**
- * Register the update function for a Pi session's Master Widget
- */
-export function registerMasterUpdate(piSessionId: string, update: () => void): void {
-  const state = getPiState(piSessionId);
-  state.masterUpdate = update;
-}
-
-/**
- * Refresh the Master Widget for a Pi session
- */
-export function refreshAllSessions(piSessionId: string): void {
-  const state = getPiState(piSessionId);
-
-  // Clear existing timeout for this specific Pi session
-  if (state.refreshTimeout) {
-    clearTimeout(state.refreshTimeout);
-  }
-
-  const debounceMs = getConfig().TUI_REFRESH_DEBOUNCE_MS;
-  state.refreshTimeout = setTimeout(() => {
-    try {
-      // Validate order integrity
-      const validIds = state.order.filter(id =>
-        state.panels.has(id) && state.failures.has(id)
-      );
-
-      if (validIds.length !== state.order.length) {
-        for (const id of state.order) {
-          if (!validIds.includes(id)) {
-            state.failures.delete(id);
-            state.panels.delete(id);
-          }
-        }
-        state.order.length = 0;
-        state.order.push(...validIds);
-      }
-
-      // Trigger the single Master Update for this Pi session
-      if (state.masterUpdate) {
-        try {
-          state.masterUpdate();
-        } catch (error) {
-          logger.error(`[session-state] Error updating Master Widget for ${piSessionId}:`, error);
-        }
-      }
-    } finally {
-      state.refreshTimeout = null;
-    }
-  }, debounceMs);
-}
-
-/**
- * Start a new research run within a Pi session
- */
-export function startResearchSession(piSessionId: string): string {
-  const researchId = generateUniqueSessionId('research');
-  const state = getPiState(piSessionId);
-  state.failures.set(researchId, []);
-  return researchId;
-}
-
-/**
- * Clear pending refreshes for a Pi session
- */
-export function clearPendingRefresh(piSessionId: string): void {
-  const state = piSessions.get(piSessionId);
-  if (state?.refreshTimeout) {
-    clearTimeout(state.refreshTimeout);
-    state.refreshTimeout = null;
-  }
-}
-
-/**
- * End a research run
- */
-export function endResearchSession(piSessionId: string, researchId: string): void {
-  const state = piSessions.get(piSessionId);
-  if (!state) return;
-
-  state.failures.delete(researchId);
-  state.panels.delete(researchId);
-
-  const index = state.order.indexOf(researchId);
-  if (index !== -1) {
-    state.order.splice(index, 1);
-    notifyOrderChange(piSessionId);
-  }
-
-  // If this was the last research run in the Pi session, clean up the state
-  if (state.order.length === 0 && state.panels.size === 0 && state.subscribers.length === 0) {
-    clearPendingRefresh(piSessionId);
-    piSessions.delete(piSessionId);
-  }
-}
-
-/**
- * Check if a research run is the bottom-most in its Pi session
- */
-export function isBottomMostSession(piSessionId: string, researchId: string): boolean {
-  const state = piSessions.get(piSessionId);
-  if (!state || state.order.length === 0) return false;
-  return state.order[0] === researchId;
-}
-
-/**
- * Record a researcher failure
- */
-export function recordResearcherFailure(piSessionId: string, researchId: string, researcherId: string): void {
-  const state = getPiState(piSessionId);
-  const failures = state.failures.get(researchId) || [];
-  failures.push(researcherId);
-  state.failures.set(researchId, failures);
-}
-
-/**
- * Get list of unique failed researchers in a research run
- */
-export function getFailedResearchers(piSessionId: string, researchId: string): string[] {
-  const state = getPiState(piSessionId);
-  const failures = state.failures.get(researchId) || [];
-  return [...new Set(failures)];
-}
-
-/**
- * Check if research should stop due to too many unique failures
- */
-export function shouldStopResearch(piSessionId: string, researchId: string): boolean {
-  return getFailedResearchers(piSessionId, researchId).length >= MAX_FAILED_RESEARCHERS;
-}
-
-/**
- * Get formatted error message for research stoppage
- */
-export function getResearchStopMessage(piSessionId: string, researchId: string): string {
-  const failed = getFailedResearchers(piSessionId, researchId);
-  const count = failed.length;
-
-  return [
-    `Research stopped: ${count} researcher(s) failed: ${failed.join(', ')}.`,
-    '',
-    'This indicates infrastructure failure — multiple researchers could not complete research.',
-    'Possible causes: network unavailable, SearXNG container not running, search engines returning errors.',
-    '',
-    '▎ If the health check passed (search and scrape verified), this failure is at the AI session layer —',
-    '   check model availability, API key, and context settings.',
-    '',
-    'Troubleshooting:',
-    '• Verify network connection is active',
-    '• Check SearXNG container: `docker ps | grep searxng`',
-    '• View SearXNG logs: `docker logs pi-searxng` (check for engine HTTP errors like 503, 400)',
-    '• Verify PROXY_URL if configured (optional): should be socks5://host:port or http://host:port',
-    '• Check PI_RESEARCH_RESEARCHER_TIMEOUT_MS if set (default: 4 minutes)',
-    '',
-    'Partial results may be available below.',
-  ].join('\n');
-}
-
-/**
- * Get all active research panels in a Pi session, in display order (newest first)
- */
-export function getPiActivePanels(piSessionId: string): ResearchPanelState[] {
-  const state = piSessions.get(piSessionId);
-  if (!state) return [];
-  // Return in reverse order (newest first) for top-to-bottom stacking in a single widget
-  return [...state.order].reverse().map(id => state.panels.get(id)!).filter(Boolean);
-}
-
-/**
- * Get ordered list of active research runs in a Pi session
- */
-export function getPiActiveSessionOrder(piSessionId: string): string[] {
-  const state = piSessions.get(piSessionId);
-  return state ? [...state.order] : [];
-}
-
-/**
- * Reset all state (for testing only)
- */
-export function resetAllPiSessions(): void {
-  for (const state of piSessions.values()) {
-    if (state.refreshTimeout) {
-      clearTimeout(state.refreshTimeout);
-    }
-  }
-  piSessions.clear();
-}

package/src/web-research/dependencies.ts

@@ -1,20 +0,0 @@
-/**
- * Web Research Extension - Dependencies
- *
- * Dependencies are managed by npm via package.json.
- * No custom install/uninstall commands needed.
- */
-
-import { getDependencyStatus } from './scrapers.ts';
-
-/**
- * Check all dependencies and return detailed status
- */
-export function checkAllDependencies(): {
-  playwrightAvailable: boolean;
-  } {
-  const scrapersStatus = getDependencyStatus();
-  return {
-    playwrightAvailable: scrapersStatus.playwrightAvailable,
-  };
-}