@cpretzinger/boss-claude 1.0.0 → 1.0.2

package/lib/mode-enforcer.js

@@ -0,0 +1,473 @@
+/**
+ * REDIS-BASED MODE ENFORCEMENT SYSTEM
+ *
+ * Purpose: Store "mode=orchestrator" flag in Redis and check BEFORE every action
+ * Architecture: Fail-safe gate that prevents operations outside current mode
+ *
+ * Key Design Principles:
+ * 1. Single source of truth in Redis
+ * 2. Atomic check-and-execute pattern
+ * 3. TTL-based auto-expiration (safety fallback)
+ * 4. Zero-downtime mode switching
+ * 5. Audit trail of all mode changes
+ */
+
+import Redis from 'ioredis';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+import os from 'os';
+import dotenv from 'dotenv';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Load environment variables
+const envPath = join(os.homedir(), '.boss-claude', '.env');
+if (existsSync(envPath)) {
+  dotenv.config({ path: envPath });
+}
+
+// ==========================================
+// REDIS CONNECTION SINGLETON
+// ==========================================
+let redis = null;
+
+function getRedis() {
+  if (!redis) {
+    if (!process.env.REDIS_URL) {
+      throw new Error('REDIS_URL not found. Run: boss-claude init');
+    }
+    redis = new Redis(process.env.REDIS_URL);
+  }
+  return redis;
+}
+
+// ==========================================
+// REDIS KEY ARCHITECTURE
+// ==========================================
+const KEYS = {
+  // Current active mode (orchestrator|specialist|worker)
+  MODE: 'boss:mode:current',
+
+  // Mode metadata (who set it, when, why)
+  MODE_META: 'boss:mode:metadata',
+
+  // Mode change history (sorted set by timestamp)
+  MODE_HISTORY: 'boss:mode:history',
+
+  // Action counter per mode (metrics)
+  MODE_ACTIONS: (mode) => `boss:mode:${mode}:actions`,
+
+  // Blocked action log (when mode check fails)
+  BLOCKED_ACTIONS: 'boss:mode:blocked_actions',
+
+  // Active session tracking
+  SESSION: 'boss:session:current',
+
+  // Agent identity (which agent is running)
+  AGENT_IDENTITY: 'boss:agent:identity'
+};
+
+// ==========================================
+// MODE DEFINITIONS
+// ==========================================
+const MODES = {
+  ORCHESTRATOR: 'orchestrator',  // Meta-boss coordinating agents
+  SPECIALIST: 'specialist',       // Domain expert (n8n, postgres, redis, etc)
+  WORKER: 'worker',               // Individual task execution
+  REVIEW: 'review',               // Code review mode
+  LEARNING: 'learning'            // Training/improvement mode
+};
+
+// Mode capabilities matrix
+const MODE_CAPABILITIES = {
+  [MODES.ORCHESTRATOR]: {
+    canDelegate: true,
+    canReview: true,
+    canExecute: true,
+    canLearn: true,
+    canModifyGlobalConfig: true,
+    canSwitchMode: true,
+    maxTokenBudget: 100000,
+    requiresApproval: false
+  },
+  [MODES.SPECIALIST]: {
+    canDelegate: false,
+    canReview: false,
+    canExecute: true,
+    canLearn: true,
+    canModifyGlobalConfig: false,
+    canSwitchMode: false,
+    maxTokenBudget: 50000,
+    requiresApproval: true
+  },
+  [MODES.WORKER]: {
+    canDelegate: false,
+    canReview: false,
+    canExecute: true,
+    canLearn: false,
+    canModifyGlobalConfig: false,
+    canSwitchMode: false,
+    maxTokenBudget: 20000,
+    requiresApproval: true
+  },
+  [MODES.REVIEW]: {
+    canDelegate: false,
+    canReview: true,
+    canExecute: false,
+    canLearn: true,
+    canModifyGlobalConfig: false,
+    canSwitchMode: false,
+    maxTokenBudget: 30000,
+    requiresApproval: false
+  },
+  [MODES.LEARNING]: {
+    canDelegate: false,
+    canReview: false,
+    canExecute: false,
+    canLearn: true,
+    canModifyGlobalConfig: false,
+    canSwitchMode: false,
+    maxTokenBudget: 15000,
+    requiresApproval: false
+  }
+};
+
+// ==========================================
+// MODE ENFORCEMENT CLASS
+// ==========================================
+export class ModeEnforcer {
+  constructor() {
+    this.redis = getRedis();
+  }
+
+  /**
+   * SET MODE - Atomic operation with metadata
+   *
+   * @param {string} mode - Mode to activate (orchestrator|specialist|worker|review|learning)
+   * @param {object} metadata - Who, when, why
+   * @param {number} ttl - TTL in seconds (default 86400 = 24h, prevents stuck modes)
+   */
+  async setMode(mode, metadata = {}, ttl = 86400) {
+    if (!Object.values(MODES).includes(mode)) {
+      throw new Error(`Invalid mode: ${mode}. Valid modes: ${Object.values(MODES).join(', ')}`);
+    }
+
+    const client = this.redis;
+    const timestamp = Date.now();
+
+    const modeData = {
+      mode,
+      setAt: new Date().toISOString(),
+      setBy: metadata.agent || 'boss-claude',
+      reason: metadata.reason || 'mode-change',
+      sessionId: metadata.sessionId || null,
+      ttl
+    };
+
+    // ATOMIC MULTI OPERATION
+    const pipeline = client.multi();
+
+    // 1. Set current mode with TTL
+    pipeline.set(KEYS.MODE, mode, 'EX', ttl);
+
+    // 2. Store metadata
+    pipeline.set(KEYS.MODE_META, JSON.stringify(modeData));
+
+    // 3. Add to history (sorted set by timestamp)
+    pipeline.zadd(KEYS.MODE_HISTORY, timestamp, JSON.stringify(modeData));
+
+    // 4. Trim history to last 1000 entries
+    pipeline.zremrangebyrank(KEYS.MODE_HISTORY, 0, -1001);
+
+    await pipeline.exec();
+
+    console.log(`[MODE ENFORCER] Mode set to: ${mode}`);
+    console.log(`[MODE ENFORCER] Metadata:`, modeData);
+
+    return modeData;
+  }
+
+  /**
+   * GET CURRENT MODE - Single source of truth
+   */
+  async getCurrentMode() {
+    const client = this.redis;
+    const mode = await client.get(KEYS.MODE);
+
+    if (!mode) {
+      // Default to WORKER mode if not set (safe default)
+      console.warn('[MODE ENFORCER] No mode set. Defaulting to WORKER mode.');
+      await this.setMode(MODES.WORKER, { reason: 'default-initialization' });
+      return MODES.WORKER;
+    }
+
+    return mode;
+  }
+
+  /**
+   * GET MODE METADATA - Who set it, when, why
+   */
+  async getModeMetadata() {
+    const client = this.redis;
+    const metadata = await client.get(KEYS.MODE_META);
+    return metadata ? JSON.parse(metadata) : null;
+  }
+
+  /**
+   * CHECK MODE - Gate check before every action
+   *
+   * @param {string} requiredMode - Mode required for this action
+   * @param {string} action - Description of action being attempted
+   * @throws {Error} if current mode doesn't match required mode
+   */
+  async checkMode(requiredMode, action = 'action') {
+    const currentMode = await this.getCurrentMode();
+
+    if (currentMode !== requiredMode) {
+      // Log blocked action
+      await this.logBlockedAction(currentMode, requiredMode, action);
+
+      throw new Error(
+        `[MODE ENFORCEMENT] Action blocked!\n` +
+        `Current mode: ${currentMode}\n` +
+        `Required mode: ${requiredMode}\n` +
+        `Action: ${action}\n` +
+        `Switch mode with: boss-claude mode ${requiredMode}`
+      );
+    }
+
+    // Increment action counter for this mode
+    await this.incrementActionCounter(currentMode);
+
+    return true;
+  }
+
+  /**
+   * CHECK CAPABILITY - Verify if current mode allows this capability
+   *
+   * @param {string} capability - Capability name (canDelegate, canReview, etc)
+   * @param {string} action - Description of action
+   * @throws {Error} if current mode lacks this capability
+   */
+  async checkCapability(capability, action = 'action') {
+    const currentMode = await this.getCurrentMode();
+    const capabilities = MODE_CAPABILITIES[currentMode];
+
+    if (!capabilities) {
+      throw new Error(`Unknown mode: ${currentMode}`);
+    }
+
+    if (!capabilities[capability]) {
+      await this.logBlockedAction(currentMode, `capability:${capability}`, action);
+
+      throw new Error(
+        `[CAPABILITY ENFORCEMENT] Action blocked!\n` +
+        `Current mode: ${currentMode}\n` +
+        `Required capability: ${capability}\n` +
+        `Action: ${action}\n` +
+        `This mode does not have ${capability} capability.`
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * ENFORCE TOKEN BUDGET - Check if action fits within mode's token budget
+   *
+   * @param {number} estimatedTokens - Estimated token cost
+   * @param {string} action - Description of action
+   */
+  async enforceTokenBudget(estimatedTokens, action = 'action') {
+    const currentMode = await this.getCurrentMode();
+    const capabilities = MODE_CAPABILITIES[currentMode];
+
+    if (estimatedTokens > capabilities.maxTokenBudget) {
+      await this.logBlockedAction(currentMode, 'token-budget-exceeded', action);
+
+      throw new Error(
+        `[TOKEN BUDGET ENFORCEMENT] Action blocked!\n` +
+        `Current mode: ${currentMode}\n` +
+        `Max budget: ${capabilities.maxTokenBudget} tokens\n` +
+        `Estimated cost: ${estimatedTokens} tokens\n` +
+        `Action: ${action}\n` +
+        `Consider delegating to a specialist or switching to orchestrator mode.`
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * LOG BLOCKED ACTION - Audit trail
+   */
+  async logBlockedAction(currentMode, requiredMode, action) {
+    const client = this.redis;
+    const timestamp = Date.now();
+
+    const blockData = {
+      timestamp: new Date().toISOString(),
+      currentMode,
+      requiredMode,
+      action,
+      stackTrace: new Error().stack
+    };
+
+    await client.zadd(
+      KEYS.BLOCKED_ACTIONS,
+      timestamp,
+      JSON.stringify(blockData)
+    );
+
+    // Keep last 500 blocked actions
+    await client.zremrangebyrank(KEYS.BLOCKED_ACTIONS, 0, -501);
+  }
+
+  /**
+   * INCREMENT ACTION COUNTER - Track actions per mode
+   */
+  async incrementActionCounter(mode) {
+    const client = this.redis;
+    await client.incr(KEYS.MODE_ACTIONS(mode));
+  }
+
+  /**
+   * GET MODE HISTORY - Last N mode changes
+   */
+  async getModeHistory(limit = 20) {
+    const client = this.redis;
+    const history = await client.zrevrange(KEYS.MODE_HISTORY, 0, limit - 1);
+    return history.map(entry => JSON.parse(entry));
+  }
+
+  /**
+   * GET BLOCKED ACTIONS - Last N blocked actions
+   */
+  async getBlockedActions(limit = 20) {
+    const client = this.redis;
+    const blocked = await client.zrevrange(KEYS.BLOCKED_ACTIONS, 0, limit - 1);
+    return blocked.map(entry => JSON.parse(entry));
+  }
+
+  /**
+   * GET MODE STATS - Action counts per mode
+   */
+  async getModeStats() {
+    const client = this.redis;
+    const stats = {};
+
+    for (const mode of Object.values(MODES)) {
+      const count = await client.get(KEYS.MODE_ACTIONS(mode));
+      stats[mode] = parseInt(count || 0);
+    }
+
+    return stats;
+  }
+
+  /**
+   * RESET MODE - Emergency reset to safe default
+   */
+  async resetMode() {
+    await this.setMode(MODES.WORKER, {
+      reason: 'emergency-reset',
+      agent: 'system'
+    });
+  }
+
+  /**
+   * SET AGENT IDENTITY - Track which agent is running
+   */
+  async setAgentIdentity(agentName, domain = null) {
+    const client = this.redis;
+    const identity = {
+      agent: agentName,
+      domain,
+      setAt: new Date().toISOString()
+    };
+
+    await client.set(KEYS.AGENT_IDENTITY, JSON.stringify(identity));
+    return identity;
+  }
+
+  /**
+   * GET AGENT IDENTITY - Who is running right now
+   */
+  async getAgentIdentity() {
+    const client = this.redis;
+    const identity = await client.get(KEYS.AGENT_IDENTITY);
+    return identity ? JSON.parse(identity) : null;
+  }
+}
+
+// ==========================================
+// CONVENIENCE EXPORTS
+// ==========================================
+export { MODES, MODE_CAPABILITIES };
+
+// Singleton instance
+let enforcerInstance = null;
+
+export function getEnforcer() {
+  if (!enforcerInstance) {
+    enforcerInstance = new ModeEnforcer();
+  }
+  return enforcerInstance;
+}
+
+// ==========================================
+// USAGE EXAMPLES
+// ==========================================
+
+/*
+
+// Example 1: Set orchestrator mode
+const enforcer = getEnforcer();
+await enforcer.setMode(MODES.ORCHESTRATOR, {
+  agent: 'boss-claude',
+  reason: 'session-start',
+  sessionId: 'session-12345'
+});
+
+// Example 2: Gate check before action
+try {
+  await enforcer.checkMode(MODES.ORCHESTRATOR, 'Delegating task to postgres-specialist');
+  // Action proceeds
+  console.log('✅ Action allowed');
+} catch (error) {
+  // Action blocked
+  console.error('❌', error.message);
+}
+
+// Example 3: Check capability
+try {
+  await enforcer.checkCapability('canDelegate', 'Assigning task to n8n-workflow-architect');
+  // Delegation allowed
+} catch (error) {
+  // Delegation blocked
+  console.error('❌', error.message);
+}
+
+// Example 4: Token budget enforcement
+try {
+  await enforcer.enforceTokenBudget(75000, 'Generating architecture document');
+  // Within budget
+} catch (error) {
+  // Over budget - should delegate
+  console.error('❌', error.message);
+}
+
+// Example 5: Get mode history
+const history = await enforcer.getModeHistory(10);
+console.log('Mode changes:', history);
+
+// Example 6: Get blocked actions (security audit)
+const blocked = await enforcer.getBlockedActions(10);
+console.log('Recent blocked actions:', blocked);
+
+// Example 7: Get mode stats
+const stats = await enforcer.getModeStats();
+console.log('Actions per mode:', stats);
+
+*/

package/lib/onyx-banner.js

@@ -0,0 +1,169 @@
+/**
+ * ONYX MODE Banner System
+ * Displays "ONYX MODE: DELEGATE ONLY" banner at conversation start and every 10 messages
+ */
+
+import chalk from 'chalk';
+
+/**
+ * ASCII art banner for ONYX MODE
+ */
+const ONYX_BANNER = `
+╔═══════════════════════════════════════════════════════════════════════════════╗
+║                                                                               ║
+║   ▄▄▄▄▄▄▄▄▄▄▄  ▄▄        ▄  ▄         ▄  ▄▄       ▄▄                         ║
+║  ▐░░░░░░░░░░░▌▐░░▌      ▐░▌▐░▌       ▐░▌▐░░▌     ▐░░▌                        ║
+║  ▐░█▀▀▀▀▀▀▀█░▌▐░▌░▌     ▐░▌ ▐░▌     ▐░▌ ▐░▌░▌   ▐░▐░▌                        ║
+║  ▐░▌       ▐░▌▐░▌▐░▌    ▐░▌  ▐░▌   ▐░▌  ▐░▌▐░▌ ▐░▌▐░▌                        ║
+║  ▐░▌       ▐░▌▐░▌ ▐░▌   ▐░▌   ▐░▌ ▐░▌   ▐░▌ ▐░▐░▌ ▐░▌                        ║
+║  ▐░▌       ▐░▌▐░▌  ▐░▌  ▐░▌    ▐░▐░▌    ▐░▌  ▐░▌  ▐░▌                        ║
+║  ▐░▌       ▐░▌▐░▌   ▐░▌ ▐░▌     ▐░▌     ▐░▌   ▀   ▐░▌                        ║
+║  ▐░▌       ▐░▌▐░▌    ▐░▌▐░▌    ▐░▌░▌    ▐░▌       ▐░▌                        ║
+║  ▐░█▄▄▄▄▄▄▄█░▌▐░▌     ▐░▐░▌   ▐░▌ ▐░▌   ▐░▌       ▐░▌                        ║
+║  ▐░░░░░░░░░░░▌▐░▌      ▐░░▌  ▐░▌   ▐░▌  ▐░▌       ▐░▌                        ║
+║   ▀▀▀▀▀▀▀▀▀▀▀  ▀        ▀▀    ▀     ▀    ▀         ▀                         ║
+║                                                                               ║
+║                     ███╗   ███╗ ██████╗ ██████╗ ███████╗                     ║
+║                     ████╗ ████║██╔═══██╗██╔══██╗██╔════╝                     ║
+║                     ██╔████╔██║██║   ██║██║  ██║█████╗                       ║
+║                     ██║╚██╔╝██║██║   ██║██║  ██║██╔══╝                       ║
+║                     ██║ ╚═╝ ██║╚██████╔╝██████╔╝███████╗                     ║
+║                     ╚═╝     ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝                     ║
+║                                                                               ║
+║                          DELEGATE ONLY - NO EXECUTION                        ║
+║                                                                               ║
+╚═══════════════════════════════════════════════════════════════════════════════╝
+`;
+
+/**
+ * Compact version of banner for periodic display
+ */
+const ONYX_BANNER_COMPACT = `
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃  ⬛ ONYX MODE: DELEGATE ONLY ⬛  No task execution | Agent delegation only  ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+`;
+
+/**
+ * Message counter for periodic banner display
+ */
+let messageCount = 0;
+
+/**
+ * Display the full ONYX MODE banner (for conversation start)
+ * @param {boolean} colorize - Whether to apply color styling
+ * @returns {string} Formatted banner
+ */
+export function displayOnyxBanner(colorize = true) {
+  if (colorize) {
+    return chalk.black.bgWhite(ONYX_BANNER);
+  }
+  return ONYX_BANNER;
+}
+
+/**
+ * Display the compact ONYX MODE banner (for periodic reminders)
+ * @param {boolean} colorize - Whether to apply color styling
+ * @returns {string} Formatted compact banner
+ */
+export function displayOnyxBannerCompact(colorize = true) {
+  if (colorize) {
+    return chalk.black.bgWhite(ONYX_BANNER_COMPACT);
+  }
+  return ONYX_BANNER_COMPACT;
+}
+
+/**
+ * Check if banner should be displayed based on message count
+ * Displays at start (count = 0) and every 10 messages
+ * @returns {boolean} True if banner should be shown
+ */
+export function shouldDisplayBanner() {
+  if (messageCount === 0 || messageCount % 10 === 0) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Increment message counter
+ * Call this after each user message
+ */
+export function incrementMessageCount() {
+  messageCount++;
+}
+
+/**
+ * Reset message counter
+ * Call this at conversation start
+ */
+export function resetMessageCount() {
+  messageCount = 0;
+}
+
+/**
+ * Get current message count
+ * @returns {number} Current message count
+ */
+export function getMessageCount() {
+  return messageCount;
+}
+
+/**
+ * Auto-display banner with message tracking
+ * Call this function after each message
+ * @param {boolean} isConversationStart - True if this is the first message
+ * @param {boolean} colorize - Whether to apply color styling
+ * @returns {string|null} Banner to display, or null if not needed
+ */
+export function autoDisplayBanner(isConversationStart = false, colorize = true) {
+  if (isConversationStart) {
+    resetMessageCount();
+    return displayOnyxBanner(colorize);
+  }
+
+  incrementMessageCount();
+
+  if (shouldDisplayBanner()) {
+    return displayOnyxBannerCompact(colorize);
+  }
+
+  return null;
+}
+
+/**
+ * Format banner for injection into CLI output
+ * Returns formatted string that can be console.log'd
+ * @param {boolean} isConversationStart - True if this is the first message
+ * @returns {string} Formatted banner ready for output
+ */
+export function formatForCLI(isConversationStart = false) {
+  const banner = autoDisplayBanner(isConversationStart, true);
+
+  if (!banner) {
+    return '';
+  }
+
+  return `\n${banner}\n`;
+}
+
+/**
+ * Get banner with statistics
+ * Displays banner plus message count info
+ * @param {boolean} isConversationStart - True if this is the first message
+ * @returns {string} Banner with stats
+ */
+export function getBannerWithStats(isConversationStart = false) {
+  const banner = autoDisplayBanner(isConversationStart, true);
+
+  if (!banner) {
+    return '';
+  }
+
+  const stats = chalk.dim(`Message count: ${messageCount} | Next banner at: ${Math.ceil(messageCount / 10) * 10}`);
+
+  return `\n${banner}\n${stats}\n`;
+}
+
+// Export constants for direct use
+export { ONYX_BANNER, ONYX_BANNER_COMPACT };