claude-flow-novice 2.15.4 → 2.15.6

package/claude-assets/skills/cfn-redis-coordination/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * CFN Redis Coordination - TypeScript Entry Point
+ *
+ * Complete Redis coordination layer with Task Mode graceful fallback
+ */
+
+// Core types
+export * from './types';
+
+// Mode detection
+export { detectMode, ConsoleLogger } from './mode-detector';
+
+// Redis client
+export { RedisCoordinator } from './redis-client';
+
+// Coordination modules
+export { ContextManager } from './context-manager';
+export type { SuccessCriteria } from './context-manager';
+
+export { CompletionReporter } from './completion-reporter';
+export type { CompletionReportOptions } from './completion-reporter';
+
+export { ResultCollector } from './result-collector';
+export type { CollectionResult, AggregatedScores } from './result-collector';
+
+export { WaitingCoordinator } from './waiting-coordinator';
+export type { WaitResult, SignalResult } from './waiting-coordinator';
+
+export { SwarmManager } from './swarm-manager';
+export type { SwarmMetadata, CancellationSignal } from './swarm-manager';
+
+export { AgentRecoveryManager } from './agent-recovery';
+export type { AgentHealth } from './agent-recovery';
+
+export { AgentLogger, storeAgentLog, getAgentLogs, getTaskLogs, clearLogs } from './agent-logger';
+export type { LogLevel, LogEntry } from './agent-logger';
+
+export { TaskAnalyzer } from './task-analyzer';
+export type { ComplexityAnalysis, DifficultyLevel } from './task-analyzer';
+
+export { TaskExecutor } from './task-executor';
+export type { ExecutionConfig, ExecutionResult, ExecutionProgress } from './task-executor';
+
+/**
+ * Factory function to initialize all coordination modules
+ *
+ * Lazy-loaded to avoid circular dependencies
+ */
+export async function initializeCoordination() {
+  // Dynamic imports to avoid circular dep issues
+  const { RedisCoordinator } = await import('./redis-client');
+  const { ConsoleLogger } = await import('./mode-detector');
+  const { ContextManager: CM } = await import('./context-manager');
+  const { CompletionReporter: CR } = await import('./completion-reporter');
+  const { ResultCollector: RC } = await import('./result-collector');
+  const { WaitingCoordinator: WC } = await import('./waiting-coordinator');
+  const { SwarmManager: SM } = await import('./swarm-manager');
+  const { AgentRecoveryManager: ARM } = await import('./agent-recovery');
+  const { TaskAnalyzer: TA } = await import('./task-analyzer');
+  const { TaskExecutor: TE } = await import('./task-executor');
+
+  const redis = new RedisCoordinator();
+  await redis.initialize();
+
+  const logger = new ConsoleLogger('[CFN-Coord]');
+
+  return {
+    redis,
+    logger,
+    context: new CM(redis, logger),
+    completion: new CR(redis, logger),
+    results: new RC(redis, logger),
+    waiting: new WC(redis, logger),
+    swarm: new SM(redis, logger),
+    recovery: new ARM(redis, logger),
+    analyzer: new TA(redis, logger),
+    executor: new TE(redis, logger)
+  };
+}
+
+// Re-export mode detection for convenience
+export { detectMode as default } from './mode-detector';

package/claude-assets/skills/cfn-redis-coordination/src/mode-detector.ts

@@ -0,0 +1,155 @@
+/**
+ * Mode Detection for CFN Loop Agents
+ * 
+ * Detects whether an agent is running in Task Mode or CLI Mode,
+ * and whether Redis operations are safe to execute.
+ * 
+ * CRITICAL: Task Mode agents should NOT use Redis (per CLAUDE.md).
+ * This module enforces that distinction at runtime.
+ */
+
+import type { ExecutionMode, ModeDetection, Logger } from './types';
+
+/**
+ * Detect execution mode and Redis availability
+ * 
+ * @param logger Optional logger for diagnostics
+ * @returns ModeDetection with full context
+ */
+export async function detectMode(logger?: Logger): Promise<ModeDetection> {
+  // Check environment variables
+  const cfnMode = process.env.CFN_MODE?.toLowerCase();
+  const taskId = process.env.TASK_ID;
+  const agentId = process.env.AGENT_ID;
+  
+  // Check Redis availability (quick test)
+  const redisAvailable = await checkRedisAvailability();
+  
+  // Determine mode
+  let mode: ExecutionMode = 'unknown';
+  let canUseRedis = false;
+  let reason = '';
+  
+  // Explicit CFN_MODE takes precedence
+  if (cfnMode === 'task') {
+    mode = 'task';
+    canUseRedis = false;
+    reason = 'CFN_MODE=task (explicit Task Mode - Redis operations disabled)';
+  } else if (cfnMode === 'cli') {
+    mode = 'cli';
+    canUseRedis = redisAvailable;
+    reason = redisAvailable 
+      ? 'CFN_MODE=cli (CLI Mode - Redis operations enabled)'
+      : 'CFN_MODE=cli but Redis unavailable (Redis operations disabled)';
+  } 
+  // Fallback: Infer mode from environment variables
+  else if (taskId && agentId) {
+    mode = 'cli';
+    canUseRedis = redisAvailable;
+    reason = redisAvailable
+      ? 'TASK_ID and AGENT_ID present, Redis available (inferred CLI Mode)'
+      : 'TASK_ID and AGENT_ID present but Redis unavailable (Redis operations disabled)';
+  } else {
+    mode = 'task';
+    canUseRedis = false;
+    reason = 'No TASK_ID or AGENT_ID (inferred Task Mode - Redis operations disabled)';
+  }
+  
+  const detection: ModeDetection = {
+    mode,
+    redisAvailable,
+    taskIdPresent: !!taskId,
+    agentIdPresent: !!agentId,
+    canUseRedis,
+    reason
+  };
+  
+  // Log detection result
+  if (logger) {
+    logger.info('Mode detection complete', detection as unknown as Record<string, unknown>);
+    
+    if (mode === 'task') {
+      logger.info('⚠️  Task Mode detected: Redis operations will be stubbed');
+      logger.info('💡 Task Mode agents return results directly to Main Chat');
+      logger.info('🔧 Redis coordination is only for CLI Mode agents');
+    } else if (mode === 'cli' && !redisAvailable) {
+      logger.warn('⚠️  CLI Mode but Redis unavailable: Operations will soft-fail');
+      logger.warn('💡 Check Redis connection: REDIS_HOST, REDIS_PORT');
+    } else if (mode === 'cli' && redisAvailable) {
+      logger.info('✅ CLI Mode with Redis: Full coordination available');
+    }
+  }
+  
+  return detection;
+}
+
+/**
+ * Check if Redis is available
+ * 
+ * Quick connectivity test with 1 second timeout.
+ * Returns false instead of throwing errors.
+ */
+async function checkRedisAvailability(): Promise<boolean> {
+  try {
+    // Dynamic import to avoid loading Redis in Task Mode
+    const Redis = (await import('ioredis')).default;
+    
+    const host = process.env.REDIS_HOST || 'localhost';
+    const port = parseInt(process.env.REDIS_PORT || '6379', 10);
+    const password = process.env.REDIS_PASSWORD || process.env.CFN_REDIS_PASSWORD;
+    
+    const client = new Redis({
+      host,
+      port,
+      password: password || undefined,
+      connectTimeout: 1000,
+      maxRetriesPerRequest: 0,
+      retryStrategy: () => null, // Don't retry
+      lazyConnect: true
+    });
+    
+    try {
+      await client.connect();
+      const result = await client.ping();
+      await client.quit();
+      return result === 'PONG';
+    } catch {
+      try {
+        await client.disconnect();
+      } catch {
+        // Ignore disconnect errors
+      }
+      return false;
+    }
+  } catch {
+    // Redis module not available or connection failed
+    return false;
+  }
+}
+
+/**
+ * Console logger implementation for mode detection
+ * 
+ * Simple console-based logger that doesn't require external dependencies.
+ */
+export class ConsoleLogger implements Logger {
+  constructor(private prefix: string = '[CFN-Redis]') {}
+  
+  debug(message: string, context?: Record<string, unknown>): void {
+    if (process.env.DEBUG) {
+      console.log(`${this.prefix} DEBUG: ${message}`, context || '');
+    }
+  }
+  
+  info(message: string, context?: Record<string, unknown>): void {
+    console.log(`${this.prefix} ${message}`, context || '');
+  }
+  
+  warn(message: string, context?: Record<string, unknown>): void {
+    console.warn(`${this.prefix} ⚠️  ${message}`, context || '');
+  }
+  
+  error(message: string, error?: Error, context?: Record<string, unknown>): void {
+    console.error(`${this.prefix} ❌ ${message}`, error?.message || '', context || '');
+  }
+}

package/claude-assets/skills/cfn-redis-coordination/src/redis/redis-client.ts

@@ -0,0 +1,305 @@
+/**
+ * Redis Client Wrapper
+ *
+ * Provides graceful fallback for Task mode and robust connection management
+ * Replaces: redis-cli-wrapper.sh, redis-functions.sh
+ *
+ * Security:
+ * - CWE-400: Connection timeouts and circuit breaker
+ * - CWE-78: No shell execution
+ * - Input validation via branded types
+ */
+
+import Redis, { Redis as RedisClient, RedisOptions } from 'ioredis';
+import {
+  RedisConfig,
+  RedisConnectionError,
+  TimeoutError,
+  CircuitBreakerOpenError,
+} from '../types';
+
+export interface RedisClientOptions extends RedisConfig {
+  gracefulFallback?: boolean;  // If true, soft-fail when Redis unavailable (Task mode)
+  logger?: Logger;
+}
+
+export interface Logger {
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  debug(message: string, ...args: unknown[]): void;
+}
+
+class ConsoleLogger implements Logger {
+  info(message: string, ...args: unknown[]): void {
+    console.log(`[INFO] ${message}`, ...args);
+  }
+  warn(message: string, ...args: unknown[]): void {
+    console.warn(`[WARN] ${message}`, ...args);
+  }
+  error(message: string, ...args: unknown[]): void {
+    console.error(`[ERROR] ${message}`, ...args);
+  }
+  debug(message: string, ...args: unknown[]): void {
+    if (process.env.DEBUG === 'true') {
+      console.log(`[DEBUG] ${message}`, ...args);
+    }
+  }
+}
+
+type CircuitBreakerState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+/**
+ * Redis Client with graceful fallback and circuit breaker
+ */
+export class CFNRedisClient {
+  private client: RedisClient | null = null;
+  private readonly options: RedisClientOptions;
+  private readonly logger: Logger;
+  private isConnected: boolean = false;
+  private connectionAttempts: number = 0;
+  private lastConnectionAttempt: number = 0;
+  private circuitBreakerState: CircuitBreakerState = 'CLOSED';
+  private circuitBreakerFailures: number = 0;
+  private readonly CIRCUIT_BREAKER_THRESHOLD = 5;
+  private readonly CIRCUIT_BREAKER_RESET_TIMEOUT = 60000; // 1 minute
+
+  constructor(options: RedisClientOptions) {
+    this.options = {
+      host: options.host || process.env.REDIS_HOST || 'localhost',
+      port: options.port || parseInt(process.env.REDIS_PORT || '6379', 10),
+      password: options.password || process.env.REDIS_PASSWORD || process.env.CFN_REDIS_PASSWORD,
+      db: options.db || parseInt(process.env.REDIS_DB || '0', 10),
+      connectTimeout: options.connectTimeout || 1000,
+      commandTimeout: options.commandTimeout || 5000,
+      enableOfflineQueue: options.enableOfflineQueue ?? false,
+      lazyConnect: options.lazyConnect ?? true,
+      gracefulFallback: options.gracefulFallback ?? false,
+      retryStrategy: options.retryStrategy || this.defaultRetryStrategy.bind(this),
+    };
+    this.logger = options.logger || new ConsoleLogger();
+  }
+
+  /**
+   * Default retry strategy: exponential backoff with max 3 attempts
+   */
+  private defaultRetryStrategy(times: number): number | null {
+    if (times > 3) {
+      this.logger.warn('Redis connection failed after 3 attempts');
+      return null; // Stop retrying
+    }
+    const delay = Math.min(times * 200, 3000);
+    this.logger.debug(`Redis retry ${times} in ${delay}ms`);
+    return delay;
+  }
+
+  /**
+   * Connect to Redis (lazy connection)
+   */
+  async connect(): Promise<void> {
+    if (this.isConnected && this.client) {
+      return;
+    }
+
+    if (this.circuitBreakerState === 'OPEN') {
+      const now = Date.now();
+      if (now - this.lastConnectionAttempt < this.CIRCUIT_BREAKER_RESET_TIMEOUT) {
+        throw new CircuitBreakerOpenError(
+          'Circuit breaker is OPEN. Redis connection attempts blocked.'
+        );
+      }
+      // Transition to HALF_OPEN to test connection
+      this.circuitBreakerState = 'HALF_OPEN';
+      this.logger.info('Circuit breaker transitioning to HALF_OPEN');
+    }
+
+    this.lastConnectionAttempt = Date.now();
+    this.connectionAttempts++;
+
+    try {
+      const redisOptions: RedisOptions = {
+        host: this.options.host,
+        port: this.options.port,
+        password: this.options.password,
+        db: this.options.db,
+        connectTimeout: this.options.connectTimeout,
+        commandTimeout: this.options.commandTimeout,
+        enableOfflineQueue: this.options.enableOfflineQueue,
+        lazyConnect: this.options.lazyConnect,
+        retryStrategy: this.options.retryStrategy,
+        maxRetriesPerRequest: 1,
+      };
+
+      this.client = new Redis(redisOptions);
+
+      // Wait for connection with timeout
+      await Promise.race([
+        new Promise<void>((resolve, reject) => {
+          this.client!.once('ready', () => {
+            this.isConnected = true;
+            this.circuitBreakerState = 'CLOSED';
+            this.circuitBreakerFailures = 0;
+            this.logger.info(
+              `Redis connected: ${this.options.host}:${this.options.port} (db: ${this.options.db})`
+            );
+            resolve();
+          });
+          this.client!.once('error', (err) => {
+            reject(err);
+          });
+        }),
+        new Promise<void>((_, reject) =>
+          setTimeout(() => reject(new Error('Connection timeout')), this.options.connectTimeout!)
+        ),
+      ]);
+
+      // Verify connection with PING
+      await this.client.ping();
+
+    } catch (error) {
+      this.isConnected = false;
+      this.circuitBreakerFailures++;
+
+      if (this.circuitBreakerFailures >= this.CIRCUIT_BREAKER_THRESHOLD) {
+        this.circuitBreakerState = 'OPEN';
+        this.logger.error(
+          `Circuit breaker opened after ${this.circuitBreakerFailures} failures`
+        );
+      }
+
+      if (this.options.gracefulFallback) {
+        this.logger.warn('⚠️  Redis unavailable - graceful fallback mode (Task mode)');
+        this.logger.info('💡 This is expected in Task mode (Main Chat coordination)');
+        this.logger.info('🔧 Agents should output JSON directly instead of Redis coordination');
+        return; // Soft fail - don't throw
+      }
+
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new RedisConnectionError(
+        `Failed to connect to Redis at ${this.options.host}:${this.options.port}: ${errorMessage}`,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  /**
+   * Check if Redis is available
+   */
+  isAvailable(): boolean {
+    return this.isConnected && this.client !== null;
+  }
+
+  /**
+   * Get the underlying Redis client (throws if not connected)
+   */
+  getClient(): RedisClient {
+    if (!this.client || !this.isConnected) {
+      if (this.options.gracefulFallback) {
+        throw new Error('Redis not available in graceful fallback mode');
+      }
+      throw new RedisConnectionError('Redis client is not connected');
+    }
+    return this.client;
+  }
+
+  /**
+   * Execute Redis command with timeout and error handling
+   */
+  async execute<T>(
+    operation: (client: RedisClient) => Promise<T>,
+    operationName: string = 'command'
+  ): Promise<T | null> {
+    if (!this.isAvailable()) {
+      if (this.options.gracefulFallback) {
+        this.logger.debug(`Redis unavailable, skipping: ${operationName}`);
+        return null;
+      }
+      throw new RedisConnectionError('Redis not available');
+    }
+
+    try {
+      const client = this.getClient();
+      const result = await Promise.race([
+        operation(client),
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () => reject(new TimeoutError(`Redis ${operationName} timeout`, this.options.commandTimeout!)),
+            this.options.commandTimeout
+          )
+        ),
+      ]);
+
+      return result;
+    } catch (error) {
+      this.logger.error(`Redis ${operationName} failed:`, error);
+
+      if (error instanceof TimeoutError) {
+        throw error;
+      }
+
+      if (this.options.gracefulFallback) {
+        this.logger.warn(`Graceful fallback for failed ${operationName}`);
+        return null;
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Ping Redis to check connectivity
+   */
+  async ping(): Promise<boolean> {
+    try {
+      const result = await this.execute(
+        (client) => client.ping(),
+        'PING'
+      );
+      return result === 'PONG';
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Disconnect from Redis
+   */
+  async disconnect(): Promise<void> {
+    if (this.client) {
+      await this.client.quit();
+      this.client = null;
+      this.isConnected = false;
+      this.logger.info('Redis disconnected');
+    }
+  }
+
+  /**
+   * Get connection statistics
+   */
+  getStats(): {
+    isConnected: boolean;
+    connectionAttempts: number;
+    circuitBreakerState: CircuitBreakerState;
+    circuitBreakerFailures: number;
+  } {
+    return {
+      isConnected: this.isConnected,
+      connectionAttempts: this.connectionAttempts,
+      circuitBreakerState: this.circuitBreakerState,
+      circuitBreakerFailures: this.circuitBreakerFailures,
+    };
+  }
+}
+
+/**
+ * Create a CFNRedisClient instance from environment variables
+ */
+export function createRedisClientFromEnv(gracefulFallback: boolean = false): CFNRedisClient {
+  return new CFNRedisClient({
+    host: process.env.REDIS_HOST || 'localhost',
+    port: parseInt(process.env.REDIS_PORT || '6379', 10),
+    password: process.env.REDIS_PASSWORD || process.env.CFN_REDIS_PASSWORD,
+    db: parseInt(process.env.REDIS_DB || '0', 10),
+    gracefulFallback,
+  });
+}