@butlerw/vellum 0.1.0

package/src/tui/plugins.ts

@@ -0,0 +1,383 @@
+/**
+ * Plugin System Integration for TUI
+ *
+ * Provides initialization and integration of the plugin system with the CLI.
+ * Handles plugin loading from default search paths, command registration,
+ * and agent/hooks aggregation.
+ *
+ * @module cli/tui/plugins
+ */
+
+import {
+  getSearchPaths,
+  type HookContext,
+  type HookEvent,
+  type PluginAgentDefinition,
+  PluginManager,
+} from "@vellum/plugin";
+
+import type { CommandContext, CommandResult, SlashCommand } from "../commands/types.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Plugin initialization options
+ */
+export interface PluginInitOptions {
+  /**
+   * Project root directory for project-local plugins.
+   * If provided, plugins from `${projectRoot}/.vellum/plugins/` will be loaded.
+   * @default process.cwd()
+   */
+  projectRoot?: string;
+
+  /**
+   * Whether to automatically trust new plugins.
+   * @default false
+   */
+  autoTrust?: boolean;
+
+  /**
+   * Whether to eagerly load all plugin components.
+   * If false, only manifests are loaded initially.
+   * @default false
+   */
+  eagerLoad?: boolean;
+
+  /**
+   * Whether to include builtin plugins.
+   * @default true
+   */
+  includeBuiltin?: boolean;
+
+  /**
+   * Whether to include user plugins from ~/.vellum/plugins/
+   * @default true
+   */
+  includeUser?: boolean;
+
+  /**
+   * Whether to include global system plugins.
+   * @default true
+   */
+  includeGlobal?: boolean;
+}
+
+/**
+ * Result of plugin initialization
+ */
+export interface PluginInitResult {
+  /** Initialized plugin manager instance */
+  manager: PluginManager;
+
+  /** Number of plugins loaded */
+  pluginCount: number;
+
+  /** Number of commands available */
+  commandCount: number;
+
+  /** Number of agents available */
+  agentCount: number;
+
+  /** Any errors encountered during loading */
+  errors: PluginLoadError[];
+}
+
+/**
+ * Plugin load error information
+ */
+export interface PluginLoadError {
+  /** Plugin name */
+  name: string;
+
+  /** Plugin path */
+  path: string;
+
+  /** Error message */
+  message: string;
+}
+
+// =============================================================================
+// Plugin Manager Singleton
+// =============================================================================
+
+let _pluginManager: PluginManager | null = null;
+
+/**
+ * Gets the global plugin manager instance.
+ *
+ * Returns null if plugins have not been initialized yet.
+ *
+ * @returns The plugin manager or null
+ */
+export function getPluginManager(): PluginManager | null {
+  return _pluginManager;
+}
+
+// =============================================================================
+// Plugin Initialization
+// =============================================================================
+
+/**
+ * Initializes the plugin system.
+ *
+ * Loads plugins from:
+ * 1. Project plugins: `${projectRoot}/.vellum/plugins/`
+ * 2. User plugins: `~/.vellum/plugins/`
+ * 3. Global plugins: Platform-specific system directory
+ * 4. Builtin plugins: Shipped with the package
+ *
+ * @param options - Initialization options
+ * @returns Initialization result with manager and stats
+ *
+ * @example
+ * ```typescript
+ * const result = await initializePlugins({ projectRoot: process.cwd() });
+ * console.log(`Loaded ${result.pluginCount} plugins`);
+ *
+ * // Access plugin commands
+ * const commands = getPluginCommands(result.manager);
+ * ```
+ */
+export async function initializePlugins(
+  options: PluginInitOptions = {}
+): Promise<PluginInitResult> {
+  const {
+    projectRoot = process.cwd(),
+    autoTrust = false,
+    eagerLoad = false,
+    includeBuiltin = true,
+    includeUser = true,
+    includeGlobal = true,
+  } = options;
+
+  // Get search paths based on options
+  const searchPaths = getSearchPaths({
+    projectRoot,
+    includeBuiltin,
+    includeUser,
+    includeGlobal,
+    filterNonExistent: true,
+  });
+
+  // Create plugin manager with resolved paths
+  const manager = new PluginManager({
+    searchPaths,
+    autoTrust,
+    eagerLoad,
+  });
+  const errors: PluginLoadError[] = [];
+
+  // Initialize and load plugins
+  try {
+    await manager.initialize();
+  } catch (error) {
+    // Log initialization error but continue - manager may have partial success
+    console.warn("[plugins] Initialization warning:", error);
+  }
+
+  // Collect any failed plugins
+  for (const failed of manager.getFailedPlugins()) {
+    errors.push({
+      name: failed.name,
+      path: failed.path,
+      message: failed.error.message,
+    });
+  }
+
+  // Store manager globally for access by other modules
+  _pluginManager = manager;
+
+  // Return initialization result
+  const plugins = manager.getPlugins();
+  const commands = manager.getCommands();
+  const agents = manager.getAgents();
+
+  return {
+    manager,
+    pluginCount: plugins.length,
+    commandCount: commands.size,
+    agentCount: agents.size,
+    errors,
+  };
+}
+
+// =============================================================================
+// Command Integration
+// =============================================================================
+
+/**
+ * Gets plugin commands in CLI SlashCommand format.
+ *
+ * Converts plugin commands to the SlashCommand format used by the
+ * CommandRegistry. Commands are returned with `kind: 'plugin'` and
+ * include the source plugin name.
+ *
+ * @param manager - Plugin manager instance
+ * @returns Array of SlashCommand definitions
+ *
+ * @example
+ * ```typescript
+ * const commands = getPluginCommands(manager);
+ * for (const cmd of commands) {
+ *   commandRegistry.register(cmd);
+ * }
+ * ```
+ */
+export function getPluginCommands(manager: PluginManager): SlashCommand[] {
+  const pluginCommands = manager.getCommands();
+  const commands: SlashCommand[] = [];
+
+  for (const [_name, cmd] of pluginCommands) {
+    // Convert plugin SlashCommand to CLI SlashCommand
+    // Need to wrap execute to adapt context types
+    const cliCommand: SlashCommand = {
+      name: cmd.name,
+      description: cmd.description,
+      kind: "plugin",
+      category: "tools", // Plugin commands go to tools category
+      aliases: cmd.aliases,
+      execute: async (ctx: CommandContext): Promise<CommandResult> => {
+        // Adapt CLI CommandContext to plugin CommandContext
+        const pluginCtx = {
+          rawArgs: ctx.parsedArgs.raw,
+          parsedArgs: {
+            positional: ctx.parsedArgs.positional,
+            named: ctx.parsedArgs.named,
+          },
+          allowedTools: undefined,
+          signal: ctx.signal,
+        };
+
+        // Execute the plugin command
+        const result = await cmd.execute(pluginCtx);
+
+        // Adapt plugin result to CLI result
+        if (result.kind === "success") {
+          return {
+            kind: "success",
+            message: result.message,
+            data: result.data,
+          };
+        } else {
+          return {
+            kind: "error",
+            code: "INTERNAL_ERROR",
+            message: result.message,
+            suggestions: result.suggestions,
+          };
+        }
+      },
+    };
+
+    commands.push(cliCommand);
+  }
+
+  return commands;
+}
+
+/**
+ * Gets the count of available plugin commands.
+ *
+ * Useful for status displays without loading full command data.
+ *
+ * @param manager - Plugin manager instance
+ * @returns Number of registered plugin commands
+ */
+export function getPluginCommandCount(manager: PluginManager): number {
+  return manager.getCommands().size;
+}
+
+// =============================================================================
+// Agent Integration
+// =============================================================================
+
+/**
+ * Gets plugin agents.
+ *
+ * Returns all agents defined by loaded plugins, keyed by their
+ * qualified slug (pluginName:agentSlug).
+ *
+ * @param manager - Plugin manager instance
+ * @returns Map of agent slug to agent definition
+ *
+ * @example
+ * ```typescript
+ * const agents = getPluginAgents(manager);
+ * for (const [slug, agent] of agents) {
+ *   console.log(`Agent: ${agent.name} (${slug})`);
+ * }
+ * ```
+ */
+export function getPluginAgents(manager: PluginManager): Map<string, PluginAgentDefinition> {
+  return manager.getAgents();
+}
+
+/**
+ * Gets a list of plugin agent names for display.
+ *
+ * @param manager - Plugin manager instance
+ * @returns Array of agent display names
+ */
+export function getPluginAgentNames(manager: PluginManager): string[] {
+  const agents = manager.getAgents();
+  const names: string[] = [];
+
+  for (const [_slug, agent] of agents) {
+    names.push(agent.name);
+  }
+
+  return names;
+}
+
+// =============================================================================
+// Hook Integration
+// =============================================================================
+
+/**
+ * Executes plugin hooks for a given event.
+ *
+ * Delegates to the PluginManager's hook execution system.
+ * Results from all plugins are returned.
+ *
+ * @param manager - Plugin manager instance
+ * @param event - Hook event type
+ * @param context - Context for hook execution
+ * @returns Array of hook results from all plugins
+ *
+ * @example
+ * ```typescript
+ * const results = await executePluginHooks(manager, "PreToolUse", {
+ *   input: "user query",
+ *   sessionId: "session-123",
+ *   pluginName: "my-plugin",
+ * });
+ *
+ * // Check if any hook blocked the action
+ * const blocked = results.some(r => !r.allowed);
+ * ```
+ */
+export async function executePluginHooks(
+  manager: PluginManager,
+  event: HookEvent,
+  context: HookContext
+): Promise<Array<{ allowed: boolean; message?: string }>> {
+  const results = await manager.executeHook(event, context);
+  return results;
+}
+
+// =============================================================================
+// Cleanup
+// =============================================================================
+
+/**
+ * Disposes the plugin system.
+ *
+ * Cleans up resources and clears the global manager instance.
+ * Should be called during application shutdown.
+ */
+export function disposePlugins(): void {
+  _pluginManager = null;
+}

package/src/tui/resilience.ts

@@ -0,0 +1,342 @@
+/**
+ * Resilience Integration
+ *
+ * Wires circuit breaker, rate limiter, and provider fallback chain
+ * to create resilient provider connections.
+ *
+ * @module cli/tui/resilience
+ */
+
+import {
+  CircuitBreaker,
+  type CircuitBreakerOptions,
+  CircuitOpenError,
+  // Rate limiter (from rate-limit module, now exported via core index)
+  createRateLimiter,
+  type FallbackConfig,
+  type FallbackProvider,
+  type FallbackResult,
+  ProviderFallbackChain,
+  RateLimiter,
+  type RateLimiterConfig,
+} from "@vellum/core";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Provider interface for resilience wrapping
+ */
+export interface Provider {
+  /** Provider identifier */
+  id: string;
+  /** Provider name for display */
+  name: string;
+  /** Priority (lower = higher priority) */
+  priority?: number;
+  /** Execute a request */
+  execute: <T>(request: () => Promise<T>) => Promise<T>;
+  /** Check if provider is healthy */
+  isHealthy?: () => boolean;
+}
+
+/**
+ * Resilient provider configuration
+ */
+export interface ResilientProviderConfig {
+  /** Circuit breaker options */
+  circuitBreaker?: Partial<CircuitBreakerOptions>;
+  /** Rate limiter options */
+  rateLimiter?: Partial<RateLimiterConfig>;
+  /** Fallback configuration */
+  fallback?: Partial<FallbackConfig>;
+  /** Enable metrics collection */
+  enableMetrics?: boolean;
+}
+
+/**
+ * Resilient provider wrapper
+ */
+export interface ResilientProvider {
+  /** Circuit breaker instance */
+  breaker: CircuitBreaker;
+  /** Rate limiter instance */
+  limiter: RateLimiter;
+  /** Execute a request with full resilience stack */
+  execute: <T>(
+    providerId: string,
+    request: () => Promise<T>
+  ) => Promise<{ success: boolean; value?: T; error?: Error }>;
+  /** Get circuit breaker state for a provider */
+  getCircuitState: (providerId: string) => string;
+  /** Get rate limiter stats */
+  getRateLimiterStats: () => { allowedRequests: number; throttledRequests: number };
+  /** Reset all circuits */
+  resetAllCircuits: () => void;
+  /** Dispose resources */
+  dispose: () => void;
+}
+
+/**
+ * Metrics for resilience tracking
+ */
+export interface ResilienceMetrics {
+  /** Total requests */
+  totalRequests: number;
+  /** Successful requests */
+  successfulRequests: number;
+  /** Failed requests */
+  failedRequests: number;
+  /** Circuit breaker trips */
+  circuitTrips: number;
+  /** Rate limited requests */
+  rateLimitedRequests: number;
+  /** Fallback activations */
+  fallbackActivations: number;
+}
+
+// =============================================================================
+// Default Configuration
+// =============================================================================
+
+const DEFAULT_CIRCUIT_BREAKER_OPTIONS: CircuitBreakerOptions = {
+  failureThreshold: 5,
+  resetTimeoutMs: 30000, // 30 seconds
+  halfOpenMaxAttempts: 3,
+  windowMs: 60000, // 1 minute
+};
+
+const DEFAULT_RATE_LIMITER_CONFIG: Partial<RateLimiterConfig> = {
+  defaultBucket: {
+    capacity: 60,
+    refillRate: 1, // 1 token per second = 60 RPM
+  },
+};
+
+// =============================================================================
+// Resilience Factory
+// =============================================================================
+
+/**
+ * Create a resilient provider wrapper with circuit breaker and rate limiter.
+ *
+ * @param providers - Array of providers to wrap
+ * @param config - Resilience configuration
+ * @returns Resilient provider wrapper
+ *
+ * @example
+ * ```typescript
+ * const resilient = createResilientProvider([
+ *   { id: "anthropic", name: "Anthropic Claude", execute: anthropicExecute },
+ *   { id: "openai", name: "OpenAI GPT", execute: openaiExecute, priority: 1 },
+ * ]);
+ *
+ * const result = await resilient.execute("anthropic", () => client.chat(...));
+ * if (result.success) {
+ *   console.log(result.value);
+ * } else {
+ *   console.error("Request failed:", result.error);
+ * }
+ * ```
+ */
+export function createResilientProvider(
+  providers: Provider[],
+  config: ResilientProviderConfig = {}
+): ResilientProvider {
+  // Create circuit breakers for each provider
+  const breakerOptions: CircuitBreakerOptions = {
+    ...DEFAULT_CIRCUIT_BREAKER_OPTIONS,
+    ...config.circuitBreaker,
+  };
+
+  const breakers = new Map<string, CircuitBreaker>();
+  for (const provider of providers) {
+    breakers.set(provider.id, new CircuitBreaker(provider.id, breakerOptions));
+  }
+
+  // Create rate limiter
+  const limiterConfig: RateLimiterConfig = {
+    ...DEFAULT_RATE_LIMITER_CONFIG,
+    ...config.rateLimiter,
+  } as RateLimiterConfig;
+  const limiter = createRateLimiter(limiterConfig);
+
+  // Metrics tracking
+  const metrics: ResilienceMetrics = {
+    totalRequests: 0,
+    successfulRequests: 0,
+    failedRequests: 0,
+    circuitTrips: 0,
+    rateLimitedRequests: 0,
+    fallbackActivations: 0,
+  };
+
+  // Get a circuit breaker for a provider (or create default)
+  const getBreaker = (providerId: string): CircuitBreaker => {
+    let breaker = breakers.get(providerId);
+    if (!breaker) {
+      breaker = new CircuitBreaker(providerId, breakerOptions);
+      breakers.set(providerId, breaker);
+    }
+    return breaker;
+  };
+
+  // Get primary breaker
+  const primaryBreaker = getBreaker(providers[0]?.id ?? "default");
+
+  return {
+    breaker: primaryBreaker,
+    limiter,
+
+    async execute<T>(
+      providerId: string,
+      request: () => Promise<T>
+    ): Promise<{ success: boolean; value?: T; error?: Error }> {
+      metrics.totalRequests++;
+
+      // Check rate limit first
+      const canProceed = limiter.tryAcquire(providerId);
+      if (!canProceed) {
+        metrics.rateLimitedRequests++;
+        // Wait for rate limit or throw
+        try {
+          await limiter.acquire(providerId, 1);
+        } catch {
+          return {
+            success: false,
+            error: new Error("Rate limit exceeded"),
+          };
+        }
+      }
+
+      // Get circuit breaker for provider
+      const breaker = getBreaker(providerId);
+
+      // Check circuit state
+      if (breaker.getState() === "OPEN") {
+        metrics.circuitTrips++;
+        return {
+          success: false,
+          error: new CircuitOpenError(providerId, breaker.getTimeUntilReset()),
+        };
+      }
+
+      // Execute through circuit breaker
+      try {
+        const result = await breaker.execute(request);
+        metrics.successfulRequests++;
+        return {
+          success: true,
+          value: result,
+        };
+      } catch (error) {
+        metrics.failedRequests++;
+
+        // If circuit opened, record it
+        if (error instanceof CircuitOpenError) {
+          metrics.circuitTrips++;
+        }
+
+        return {
+          success: false,
+          error: error as Error,
+        };
+      }
+    },
+
+    getCircuitState(providerId: string): string {
+      const breaker = breakers.get(providerId);
+      return breaker?.getState() ?? "unknown";
+    },
+
+    getRateLimiterStats() {
+      return {
+        allowedRequests: metrics.totalRequests - metrics.rateLimitedRequests,
+        throttledRequests: metrics.rateLimitedRequests,
+      };
+    },
+
+    resetAllCircuits() {
+      for (const breaker of breakers.values()) {
+        breaker.reset();
+      }
+      metrics.circuitTrips = 0;
+    },
+
+    dispose() {
+      breakers.clear();
+    },
+  };
+}
+
+/**
+ * Create a simple circuit breaker for a single operation.
+ *
+ * @param id - Circuit breaker identifier
+ * @param options - Circuit breaker options
+ * @returns Circuit breaker instance
+ *
+ * @example
+ * ```typescript
+ * const breaker = createCircuitBreaker("api", { failureThreshold: 3 });
+ * try {
+ *   const result = await breaker.execute(() => apiCall());
+ * } catch (error) {
+ *   if (error instanceof CircuitOpenError) {
+ *     console.log("Circuit is open, service unavailable");
+ *   }
+ * }
+ * ```
+ */
+export function createCircuitBreaker(
+  id: string = "default",
+  options: Partial<CircuitBreakerOptions> = {}
+): CircuitBreaker {
+  return new CircuitBreaker(id, {
+    ...DEFAULT_CIRCUIT_BREAKER_OPTIONS,
+    ...options,
+  });
+}
+
+/**
+ * Create a rate limiter for API calls.
+ *
+ * @param config - Rate limiter configuration
+ * @returns Rate limiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createApiRateLimiter({
+ *   defaultBucket: { capacity: 100, refillRate: 10 },
+ * });
+ *
+ * if (limiter.tryAcquire("api-key")) {
+ *   await makeApiCall();
+ * } else {
+ *   console.log("Rate limited, please wait");
+ * }
+ * ```
+ */
+export function createApiRateLimiter(config: Partial<RateLimiterConfig> = {}): RateLimiter {
+  return createRateLimiter({
+    ...DEFAULT_RATE_LIMITER_CONFIG,
+    ...config,
+  } as RateLimiterConfig);
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export {
+  CircuitBreaker,
+  type CircuitBreakerOptions,
+  CircuitOpenError,
+  ProviderFallbackChain,
+  type FallbackConfig,
+  type FallbackResult,
+  type FallbackProvider,
+  RateLimiter,
+  type RateLimiterConfig,
+};