@cpretzinger/boss-claude 1.0.0 → 1.0.2

package/lib/onyx-wrapper.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/**
+ * ONYX WRAPPER - Claude Code Integration
+ *
+ * Drop-in replacement for direct tool calls that enforces ONYX delegation rules.
+ * This wrapper intercepts ALL tool calls and applies pre-hook validation.
+ *
+ * USAGE:
+ *   import { onyxWrapper } from '@cpretzinger/boss-claude/lib/onyx-wrapper.js';
+ *
+ *   // Wrap tool execution
+ *   const result = await onyxWrapper.executeTool('Read', { file_path: '/path/to/file.js' });
+ *
+ * INTEGRATION:
+ *   Replace direct tool calls in ONYX agent with onyxWrapper.executeTool()
+ */
+
+import chalk from 'chalk';
+import onyxInterceptor from './onyx-tool-interceptor.js';
+
+/**
+ * ONYX Wrapper Class
+ * Wraps tool execution and enforces delegation rules
+ */
+export class OnyxWrapper {
+  constructor() {
+    this.interceptor = onyxInterceptor;
+    this.executionLog = [];
+  }
+
+  /**
+   * Execute tool with pre-hook validation
+   *
+   * @param {string} toolName - Name of the tool (Read, Write, Edit, etc.)
+   * @param {Object} toolParams - Tool parameters
+   * @param {Object} options - Execution options
+   * @returns {Promise<Object>} Tool execution result
+   */
+  async executeTool(toolName, toolParams = {}, options = {}) {
+    const startTime = Date.now();
+
+    // PRE-HOOK: Intercept before execution
+    const interceptionResult = await this.interceptor.interceptToolCall(toolName, toolParams);
+
+    // Log execution attempt
+    this._logExecution(toolName, toolParams, interceptionResult, startTime);
+
+    if (!interceptionResult.allowed) {
+      // Tool blocked - handle delegation or rejection
+      return this._handleBlockedTool(toolName, toolParams, interceptionResult, options);
+    }
+
+    if (interceptionResult.override) {
+      console.log(chalk.yellow('\n⚠️  ONYX delegation override - proceeding with caution'));
+    }
+
+    // Tool allowed - execute if executor provided
+    if (options.executor && typeof options.executor === 'function') {
+      try {
+        const result = await options.executor(toolName, toolParams);
+        return {
+          success: true,
+          tool: toolName,
+          result,
+          override: interceptionResult.override || false,
+          executionTime: Date.now() - startTime
+        };
+      } catch (error) {
+        return {
+          success: false,
+          tool: toolName,
+          error: error.message,
+          executionTime: Date.now() - startTime
+        };
+      }
+    }
+
+    // No executor - return allowed status
+    return {
+      success: true,
+      allowed: true,
+      tool: toolName,
+      params: toolParams,
+      override: interceptionResult.override || false,
+      message: 'Tool allowed - no executor provided (dry run)',
+      executionTime: Date.now() - startTime
+    };
+  }
+
+  /**
+   * Handle blocked tool - auto-delegate or reject
+   */
+  async _handleBlockedTool(toolName, toolParams, interceptionResult, options) {
+    if (interceptionResult.delegateTo === 'Task') {
+      // Auto-delegate to Task tool
+      console.log(chalk.cyan('\n📤 Auto-delegating to Task tool...'));
+      console.log(chalk.dim(interceptionResult.delegationMessage));
+
+      if (options.taskExecutor && typeof options.taskExecutor === 'function') {
+        // Execute via Task tool
+        try {
+          const taskResult = await options.taskExecutor({
+            description: interceptionResult.delegationMessage,
+            context: {
+              originalTool: toolName,
+              originalParams: toolParams,
+              delegatedBy: 'ONYX',
+              delegationReason: interceptionResult.reason
+            }
+          });
+
+          return {
+            success: true,
+            delegated: true,
+            delegateTo: 'Task',
+            tool: toolName,
+            originalParams: toolParams,
+            delegationMessage: interceptionResult.delegationMessage,
+            taskResult
+          };
+        } catch (error) {
+          return {
+            success: false,
+            delegated: true,
+            delegateTo: 'Task',
+            tool: toolName,
+            error: error.message
+          };
+        }
+      }
+
+      // No task executor - return delegation info
+      return {
+        success: false,
+        delegated: true,
+        delegateTo: 'Task',
+        tool: toolName,
+        originalParams: toolParams,
+        delegationMessage: interceptionResult.delegationMessage,
+        message: 'Delegation required - no task executor provided'
+      };
+    }
+
+    if (interceptionResult.rejected) {
+      // Tool rejected entirely
+      console.log(chalk.red('\n❌ Tool call rejected by ONYX interceptor'));
+
+      return {
+        success: false,
+        blocked: true,
+        rejected: true,
+        tool: toolName,
+        reason: interceptionResult.reason
+      };
+    }
+
+    // Generic block
+    return {
+      success: false,
+      blocked: true,
+      tool: toolName,
+      reason: interceptionResult.reason
+    };
+  }
+
+  /**
+   * Log tool execution attempt
+   */
+  _logExecution(toolName, toolParams, interceptionResult, startTime) {
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      tool: toolName,
+      params: toolParams,
+      allowed: interceptionResult.allowed,
+      blocked: interceptionResult.blocked || false,
+      delegated: interceptionResult.delegateTo ? true : false,
+      override: interceptionResult.override || false,
+      startTime
+    };
+
+    this.executionLog.push(logEntry);
+
+    // Keep only last 100 entries
+    if (this.executionLog.length > 100) {
+      this.executionLog.shift();
+    }
+  }
+
+  /**
+   * Get execution log
+   */
+  getExecutionLog(limit = 20) {
+    return this.executionLog.slice(-limit);
+  }
+
+  /**
+   * Print execution summary
+   */
+  printExecutionSummary() {
+    console.log(chalk.blue('\n📊 ONYX TOOL EXECUTION SUMMARY'));
+    console.log(chalk.dim('═'.repeat(80)));
+
+    const stats = this._calculateStats();
+
+    console.log(chalk.white(`Total Calls: ${chalk.magenta(stats.total)}`));
+    console.log(chalk.white(`Allowed: ${chalk.green(stats.allowed)}`));
+    console.log(chalk.white(`Blocked: ${chalk.red(stats.blocked)}`));
+    console.log(chalk.white(`Delegated: ${chalk.cyan(stats.delegated)}`));
+    console.log(chalk.white(`Overrides: ${chalk.yellow(stats.overrides)}`));
+
+    console.log(chalk.dim('\n─'.repeat(80)));
+
+    if (stats.topTools.length > 0) {
+      console.log(chalk.white('\nTop Tools Used:'));
+      stats.topTools.forEach((item, i) => {
+        console.log(chalk.dim(`  ${i + 1}. ${item.tool} (${item.count} calls)`));
+      });
+    }
+
+    console.log(chalk.dim('═'.repeat(80)));
+  }
+
+  /**
+   * Calculate execution statistics
+   */
+  _calculateStats() {
+    const stats = {
+      total: this.executionLog.length,
+      allowed: 0,
+      blocked: 0,
+      delegated: 0,
+      overrides: 0,
+      toolCounts: {}
+    };
+
+    this.executionLog.forEach(log => {
+      if (log.allowed) stats.allowed++;
+      if (log.blocked) stats.blocked++;
+      if (log.delegated) stats.delegated++;
+      if (log.override) stats.overrides++;
+
+      stats.toolCounts[log.tool] = (stats.toolCounts[log.tool] || 0) + 1;
+    });
+
+    // Sort tools by usage
+    stats.topTools = Object.entries(stats.toolCounts)
+      .map(([tool, count]) => ({ tool, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 5);
+
+    return stats;
+  }
+
+  /**
+   * Clear execution log
+   */
+  clearLog() {
+    this.executionLog = [];
+    console.log(chalk.green('\n✅ Execution log cleared'));
+  }
+}
+
+// Singleton instance
+const onyxWrapper = new OnyxWrapper();
+
+export default onyxWrapper;
+
+/**
+ * INTEGRATION EXAMPLES:
+ *
+ * 1. Basic usage - dry run (no executor):
+ *
+ *    import onyxWrapper from '@cpretzinger/boss-claude/lib/onyx-wrapper.js';
+ *
+ *    const result = await onyxWrapper.executeTool('Read', {
+ *      file_path: '/path/to/file.js'
+ *    });
+ *
+ *    if (result.success && result.allowed) {
+ *      console.log('Tool allowed');
+ *    } else if (result.delegated) {
+ *      console.log('Delegated to:', result.delegateTo);
+ *    }
+ *
+ * 2. With executor function:
+ *
+ *    const result = await onyxWrapper.executeTool('Read', {
+ *      file_path: '/path/to/file.js'
+ *    }, {
+ *      executor: async (tool, params) => {
+ *        // Your actual tool execution logic
+ *        return await actualReadTool(params);
+ *      }
+ *    });
+ *
+ * 3. With Task delegation executor:
+ *
+ *    const result = await onyxWrapper.executeTool('Grep', {
+ *      pattern: 'function',
+ *      path: '/src'
+ *    }, {
+ *      taskExecutor: async (taskParams) => {
+ *        // Execute via Task tool
+ *        return await taskTool.execute(taskParams);
+ *      }
+ *    });
+ *
+ * 4. Print execution summary:
+ *
+ *    onyxWrapper.printExecutionSummary();
+ *
+ * 5. Get interceptor report:
+ *
+ *    onyxWrapper.interceptor.printReport();
+ */

package/lib/orchestrator-gate.js

@@ -0,0 +1,334 @@
+/**
+ * ORCHESTRATOR GATE - Pre-Action Hook System
+ *
+ * Purpose: Enforce mode checks BEFORE every significant action
+ * Pattern: Decorator pattern wrapping critical operations
+ *
+ * Architecture:
+ * 1. Intercepts all major operations (delegate, execute, review)
+ * 2. Validates mode + capabilities + token budget
+ * 3. Logs all actions (allowed or blocked)
+ * 4. Provides clear error messages when blocked
+ */
+
+import { getEnforcer, MODES, MODE_CAPABILITIES } from './mode-enforcer.js';
+import { loadIdentity } from './identity.js';
+
+// ==========================================
+// ORCHESTRATOR GATE CLASS
+// ==========================================
+export class OrchestratorGate {
+  constructor() {
+    this.enforcer = getEnforcer();
+  }
+
+  /**
+   * BEFORE DELEGATE - Check if delegation is allowed
+   *
+   * @param {string} targetAgent - Agent to delegate to
+   * @param {object} task - Task description
+   * @param {number} estimatedTokens - Estimated cost
+   */
+  async beforeDelegate(targetAgent, task, estimatedTokens = 0) {
+    console.log(`\n[ORCHESTRATOR GATE] Checking delegation permission...`);
+    console.log(`Target agent: ${targetAgent}`);
+    console.log(`Task: ${task.description || 'N/A'}`);
+    console.log(`Estimated tokens: ${estimatedTokens}`);
+
+    // 1. Check if current mode allows delegation
+    await this.enforcer.checkCapability(
+      'canDelegate',
+      `Delegating to ${targetAgent}: ${task.description || 'task'}`
+    );
+
+    // 2. Check token budget if applicable
+    if (estimatedTokens > 0) {
+      await this.enforcer.enforceTokenBudget(
+        estimatedTokens,
+        `Delegation to ${targetAgent}`
+      );
+    }
+
+    // 3. Verify orchestrator mode is active
+    const currentMode = await this.enforcer.getCurrentMode();
+    if (currentMode !== MODES.ORCHESTRATOR) {
+      throw new Error(
+        `[GATE BLOCKED] Delegation requires orchestrator mode.\n` +
+        `Current mode: ${currentMode}\n` +
+        `Switch with: boss-claude mode orchestrator`
+      );
+    }
+
+    console.log(`[ORCHESTRATOR GATE] ✅ Delegation approved`);
+    return true;
+  }
+
+  /**
+   * BEFORE EXECUTE - Check if direct execution is allowed
+   *
+   * @param {object} action - Action to execute
+   * @param {number} estimatedTokens - Estimated cost
+   */
+  async beforeExecute(action, estimatedTokens = 0) {
+    console.log(`\n[ORCHESTRATOR GATE] Checking execution permission...`);
+    console.log(`Action: ${action.description || 'N/A'}`);
+    console.log(`Estimated tokens: ${estimatedTokens}`);
+
+    // 1. Check if current mode allows execution
+    await this.enforcer.checkCapability(
+      'canExecute',
+      `Executing: ${action.description || 'action'}`
+    );
+
+    // 2. Check token budget
+    if (estimatedTokens > 0) {
+      await this.enforcer.enforceTokenBudget(
+        estimatedTokens,
+        `Direct execution: ${action.description || 'action'}`
+      );
+    }
+
+    console.log(`[ORCHESTRATOR GATE] ✅ Execution approved`);
+    return true;
+  }
+
+  /**
+   * BEFORE REVIEW - Check if code review is allowed
+   *
+   * @param {string} workerAgent - Agent whose code is being reviewed
+   * @param {object} code - Code to review
+   */
+  async beforeReview(workerAgent, code) {
+    console.log(`\n[ORCHESTRATOR GATE] Checking review permission...`);
+    console.log(`Worker agent: ${workerAgent}`);
+
+    // 1. Check if current mode allows review
+    await this.enforcer.checkCapability(
+      'canReview',
+      `Reviewing code from ${workerAgent}`
+    );
+
+    // 2. Verify orchestrator or review mode is active
+    const currentMode = await this.enforcer.getCurrentMode();
+    if (currentMode !== MODES.ORCHESTRATOR && currentMode !== MODES.REVIEW) {
+      throw new Error(
+        `[GATE BLOCKED] Code review requires orchestrator or review mode.\n` +
+        `Current mode: ${currentMode}\n` +
+        `Switch with: boss-claude mode orchestrator`
+      );
+    }
+
+    console.log(`[ORCHESTRATOR GATE] ✅ Review approved`);
+    return true;
+  }
+
+  /**
+   * BEFORE LEARN - Check if learning/memory write is allowed
+   *
+   * @param {string} learningType - Type of learning (success|failure|pattern)
+   * @param {object} data - Learning data
+   */
+  async beforeLearn(learningType, data) {
+    console.log(`\n[ORCHESTRATOR GATE] Checking learning permission...`);
+    console.log(`Learning type: ${learningType}`);
+
+    // 1. Check if current mode allows learning
+    await this.enforcer.checkCapability(
+      'canLearn',
+      `Recording learning: ${learningType}`
+    );
+
+    console.log(`[ORCHESTRATOR GATE] ✅ Learning approved`);
+    return true;
+  }
+
+  /**
+   * BEFORE CONFIG CHANGE - Check if global config modification is allowed
+   *
+   * @param {string} configKey - Config key being modified
+   * @param {any} newValue - New value
+   */
+  async beforeConfigChange(configKey, newValue) {
+    console.log(`\n[ORCHESTRATOR GATE] Checking config change permission...`);
+    console.log(`Config key: ${configKey}`);
+
+    // 1. Check if current mode allows global config changes
+    await this.enforcer.checkCapability(
+      'canModifyGlobalConfig',
+      `Modifying global config: ${configKey}`
+    );
+
+    // 2. Verify orchestrator mode is active
+    const currentMode = await this.enforcer.getCurrentMode();
+    if (currentMode !== MODES.ORCHESTRATOR) {
+      throw new Error(
+        `[GATE BLOCKED] Global config changes require orchestrator mode.\n` +
+        `Current mode: ${currentMode}\n` +
+        `Config key: ${configKey}\n` +
+        `Switch with: boss-claude mode orchestrator`
+      );
+    }
+
+    console.log(`[ORCHESTRATOR GATE] ✅ Config change approved`);
+    return true;
+  }
+
+  /**
+   * GET GATE STATUS - Current mode and capabilities
+   */
+  async getStatus() {
+    const currentMode = await this.enforcer.getCurrentMode();
+    const metadata = await this.enforcer.getModeMetadata();
+    const capabilities = MODE_CAPABILITIES[currentMode];
+    const agentIdentity = await this.enforcer.getAgentIdentity();
+    const bossIdentity = await loadIdentity();
+
+    return {
+      mode: currentMode,
+      metadata,
+      capabilities,
+      agent: agentIdentity,
+      boss: {
+        level: bossIdentity.level,
+        xp: bossIdentity.xp,
+        token_bank: bossIdentity.token_bank
+      },
+      restrictions: {
+        canDelegate: capabilities.canDelegate,
+        canReview: capabilities.canReview,
+        canExecute: capabilities.canExecute,
+        canLearn: capabilities.canLearn,
+        canModifyGlobalConfig: capabilities.canModifyGlobalConfig,
+        maxTokenBudget: capabilities.maxTokenBudget
+      }
+    };
+  }
+
+  /**
+   * PRINT STATUS - Human-readable gate status
+   */
+  async printStatus() {
+    const status = await this.getStatus();
+
+    console.log(`\n╔══════════════════════════════════════════════════════════╗`);
+    console.log(`║          ORCHESTRATOR GATE STATUS                       ║`);
+    console.log(`╚══════════════════════════════════════════════════════════╝`);
+    console.log(`\nMode: ${status.mode.toUpperCase()}`);
+    console.log(`Set by: ${status.metadata?.setBy || 'N/A'}`);
+    console.log(`Set at: ${status.metadata?.setAt || 'N/A'}`);
+    console.log(`Reason: ${status.metadata?.reason || 'N/A'}`);
+
+    if (status.agent) {
+      console.log(`\nAgent: ${status.agent.agent}`);
+      console.log(`Domain: ${status.agent.domain || 'N/A'}`);
+    }
+
+    console.log(`\nBoss Identity:`);
+    console.log(`  Level: ${status.boss.level}`);
+    console.log(`  XP: ${status.boss.xp}`);
+    console.log(`  Token Bank: ${status.boss.token_bank}`);
+
+    console.log(`\nCapabilities:`);
+    console.log(`  Delegate: ${status.restrictions.canDelegate ? '✅' : '❌'}`);
+    console.log(`  Review: ${status.restrictions.canReview ? '✅' : '❌'}`);
+    console.log(`  Execute: ${status.restrictions.canExecute ? '✅' : '❌'}`);
+    console.log(`  Learn: ${status.restrictions.canLearn ? '✅' : '❌'}`);
+    console.log(`  Modify Config: ${status.restrictions.canModifyGlobalConfig ? '✅' : '❌'}`);
+    console.log(`  Max Token Budget: ${status.restrictions.maxTokenBudget.toLocaleString()}`);
+
+    console.log(`\n`);
+  }
+}
+
+// ==========================================
+// SINGLETON INSTANCE
+// ==========================================
+let gateInstance = null;
+
+export function getGate() {
+  if (!gateInstance) {
+    gateInstance = new OrchestratorGate();
+  }
+  return gateInstance;
+}
+
+// ==========================================
+// CONVENIENCE WRAPPER FUNCTIONS
+// ==========================================
+
+/**
+ * Initialize orchestrator mode - Call at session start
+ */
+export async function initOrchestratorMode(sessionId = null) {
+  const enforcer = getEnforcer();
+
+  await enforcer.setMode(MODES.ORCHESTRATOR, {
+    agent: 'boss-claude',
+    reason: 'session-start',
+    sessionId
+  });
+
+  await enforcer.setAgentIdentity('boss-claude', 'orchestrator');
+
+  console.log(`\n[ORCHESTRATOR MODE] Initialized`);
+  console.log(`Session ID: ${sessionId || 'N/A'}`);
+  console.log(`Mode: ${MODES.ORCHESTRATOR}`);
+
+  return true;
+}
+
+/**
+ * Switch to specialist mode
+ */
+export async function switchToSpecialist(agentName, domain) {
+  const enforcer = getEnforcer();
+
+  await enforcer.setMode(MODES.SPECIALIST, {
+    agent: agentName,
+    reason: 'specialist-delegation',
+    domain
+  });
+
+  await enforcer.setAgentIdentity(agentName, domain);
+
+  console.log(`\n[MODE SWITCH] Switched to specialist mode`);
+  console.log(`Agent: ${agentName}`);
+  console.log(`Domain: ${domain}`);
+
+  return true;
+}
+
+/**
+ * Return to orchestrator mode
+ */
+export async function returnToOrchestrator() {
+  const enforcer = getEnforcer();
+
+  await enforcer.setMode(MODES.ORCHESTRATOR, {
+    agent: 'boss-claude',
+    reason: 'specialist-task-complete'
+  });
+
+  await enforcer.setAgentIdentity('boss-claude', 'orchestrator');
+
+  console.log(`\n[MODE SWITCH] Returned to orchestrator mode`);
+
+  return true;
+}
+
+/**
+ * Emergency reset to safe default
+ */
+export async function emergencyReset() {
+  const enforcer = getEnforcer();
+  await enforcer.resetMode();
+  console.log(`\n[EMERGENCY RESET] Mode reset to WORKER (safe default)`);
+}
+
+// ==========================================
+// EXPORTS
+// ==========================================
+export {
+  MODES,
+  MODE_CAPABILITIES
+};