@cpretzinger/boss-claude 1.0.0 → 1.0.2

package/lib/onyx-identity.js

@@ -0,0 +1,214 @@
+/**
+ * ONYX IDENTITY MODULE
+ *
+ * Enforces orchestrator-only behavior by injecting identity into every system prompt.
+ * ONYX delegates to worker agents but NEVER uses worker tools directly.
+ */
+
+export const ONYX_IDENTITY = {
+  name: 'ONYX',
+  tier: 'Meta-Boss',
+  role: 'Orchestrator',
+  description: 'Top-level orchestrator that delegates to specialized agents',
+
+  // Core behavioral constraints
+  constraints: {
+    canDelegateToWorkers: true,
+    canDelegateToBosses: true,
+    canUseWorkerTools: false,
+    canExecuteDirectly: false,
+    mustValidateHierarchy: true
+  },
+
+  // Allowed operations (orchestration only)
+  allowedOperations: [
+    'task_analysis',
+    'agent_selection',
+    'delegation',
+    'validation',
+    'hierarchy_enforcement',
+    'result_aggregation',
+    'user_communication'
+  ],
+
+  // Forbidden operations (worker tasks)
+  forbiddenOperations: [
+    'direct_code_execution',
+    'database_queries',
+    'file_system_writes',
+    'api_calls',
+    'workflow_creation',
+    'deployment_operations'
+  ]
+};
+
+/**
+ * Generates the ONYX identity prompt that must be injected into every system context
+ *
+ * @returns {string} The ONYX identity statement
+ */
+export function getOnyxIdentityPrompt() {
+  return `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔷 YOU ARE ONYX - META-BOSS ORCHESTRATOR
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+IDENTITY: ${ONYX_IDENTITY.name}
+TIER: ${ONYX_IDENTITY.tier}
+ROLE: ${ONYX_IDENTITY.role}
+
+CORE DIRECTIVE: YOU ARE AN ORCHESTRATOR ONLY
+
+✅ YOU CAN:
+${ONYX_IDENTITY.allowedOperations.map(op => `  • ${op.replace(/_/g, ' ').toUpperCase()}`).join('\n')}
+
+❌ YOU CANNOT:
+${ONYX_IDENTITY.forbiddenOperations.map(op => `  • ${op.replace(/_/g, ' ').toUpperCase()}`).join('\n')}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  CRITICAL RULES:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. NEVER execute worker tasks yourself
+2. ALWAYS delegate to appropriate specialist agents
+3. ALWAYS validate hierarchy before accepting worker results
+4. NEVER use tools meant for worker agents (database, files, APIs)
+5. Your role is to ANALYZE, DELEGATE, and VALIDATE only
+
+When a user asks you to perform a task:
+  → Analyze the task
+  → Identify the specialist agent
+  → Delegate with clear requirements
+  → Validate the result through proper hierarchy
+  → Report back to user
+
+You are the conductor, not the orchestra.
+You are the architect, not the builder.
+You are the orchestrator, not the worker.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+}
+
+/**
+ * Validates that current operation adheres to ONYX identity constraints
+ *
+ * @param {string} operation - The operation being attempted
+ * @returns {Object} Validation result with allowed status and reason
+ */
+export function validateOnyxOperation(operation) {
+  const normalizedOp = operation.toLowerCase().replace(/\s+/g, '_');
+
+  // Check if operation is explicitly allowed
+  if (ONYX_IDENTITY.allowedOperations.some(allowed => normalizedOp.includes(allowed))) {
+    return {
+      allowed: true,
+      reason: `Operation "${operation}" is within ONYX orchestrator scope`,
+      operation
+    };
+  }
+
+  // Check if operation is explicitly forbidden
+  if (ONYX_IDENTITY.forbiddenOperations.some(forbidden => normalizedOp.includes(forbidden))) {
+    return {
+      allowed: false,
+      reason: `Operation "${operation}" is a worker task - ONYX must delegate`,
+      operation,
+      suggestedAction: 'Delegate to appropriate specialist agent',
+      violation: true
+    };
+  }
+
+  // Unknown operation - err on the side of caution
+  return {
+    allowed: false,
+    reason: `Operation "${operation}" is not in ONYX's allowed operations`,
+    operation,
+    suggestedAction: 'Verify if this requires delegation',
+    requiresReview: true
+  };
+}
+
+/**
+ * Generates context-refresh reminder that ONYX is orchestrator only
+ * Used in long conversations or after context resets
+ *
+ * @returns {string} Compact identity reminder
+ */
+export function getOnyxContextReminder() {
+  return `
+⚡ ONYX IDENTITY REMINDER ⚡
+You are ONYX (Meta-Boss Orchestrator). You DELEGATE tasks to specialists.
+You DO NOT execute worker tasks yourself. Analyze → Delegate → Validate.
+`;
+}
+
+/**
+ * Checks if a tool invocation violates ONYX orchestrator constraints
+ *
+ * @param {string} toolName - The tool being invoked
+ * @param {Object} toolParams - Tool parameters
+ * @returns {Object} Violation check result
+ */
+export function checkToolViolation(toolName, toolParams = {}) {
+  // Define tools that are ONLY for workers
+  const workerOnlyTools = [
+    'executeSQL',
+    'writeFile',
+    'createWorkflow',
+    'deployCode',
+    'callAPI',
+    'modifySchema',
+    'commitCode',
+    'runTests',
+    'startServer'
+  ];
+
+  // Define tools that are OK for orchestrators
+  const orchestratorTools = [
+    'analyzeTask',
+    'selectAgent',
+    'delegateTask',
+    'validateResult',
+    'hierarchyCheck',
+    'getStatus',
+    'reportToUser'
+  ];
+
+  const isWorkerTool = workerOnlyTools.some(tool =>
+    toolName.toLowerCase().includes(tool.toLowerCase())
+  );
+
+  const isOrchestratorTool = orchestratorTools.some(tool =>
+    toolName.toLowerCase().includes(tool.toLowerCase())
+  );
+
+  if (isWorkerTool) {
+    return {
+      violation: true,
+      severity: 'critical',
+      message: `ONYX VIOLATION: Tool "${toolName}" is for worker agents only`,
+      action: 'DELEGATE this task instead of executing directly',
+      toolName
+    };
+  }
+
+  if (isOrchestratorTool) {
+    return {
+      violation: false,
+      message: `Tool "${toolName}" is approved for orchestrator use`,
+      toolName
+    };
+  }
+
+  // Unknown tool - flag for review
+  return {
+    violation: false,
+    warning: true,
+    message: `Tool "${toolName}" not recognized - verify it's appropriate for orchestrator`,
+    action: 'Review if this should be delegated',
+    toolName
+  };
+}
+
+export default ONYX_IDENTITY;

package/lib/onyx-monitor.js

@@ -0,0 +1,381 @@
+import Redis from 'ioredis';
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+import os from 'os';
+import { appendFileSync, mkdirSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Load environment variables from ~/.boss-claude/.env
+const envPath = join(os.homedir(), '.boss-claude', '.env');
+if (existsSync(envPath)) {
+  dotenv.config({ path: envPath });
+}
+
+const BOSS_DIR = join(os.homedir(), '.boss-claude');
+const ALERT_LOG = join(BOSS_DIR, 'onyx-alerts.log');
+
+// Ensure directory exists
+try {
+  mkdirSync(BOSS_DIR, { recursive: true });
+} catch (err) {
+  // Directory already exists
+}
+
+let redis = null;
+
+function getRedis() {
+  if (!redis) {
+    if (!process.env.REDIS_URL) {
+      throw new Error('REDIS_URL not found. Please run: boss-claude init');
+    }
+    redis = new Redis(process.env.REDIS_URL);
+  }
+  return redis;
+}
+
+// Redis keys
+const DELEGATION_KEY = 'boss:onyx:delegation';
+const DIRECT_ACTION_KEY = 'boss:onyx:direct_actions';
+const ALERT_THRESHOLD_KEY = 'boss:onyx:alert_threshold';
+const LAST_ALERT_KEY = 'boss:onyx:last_alert';
+
+// Default alert threshold: 95%
+const DEFAULT_THRESHOLD = 0.95;
+
+/**
+ * Log an alert to file
+ * @param {string} message - Alert message
+ * @param {object} data - Additional data to log
+ */
+function logAlert(message, data = {}) {
+  const timestamp = new Date().toISOString();
+  const logLine = `[${timestamp}] ALERT: ${message}\n${JSON.stringify(data, null, 2)}\n\n`;
+
+  try {
+    appendFileSync(ALERT_LOG, logLine, 'utf8');
+  } catch (err) {
+    console.error(`Failed to write alert log: ${err.message}`);
+  }
+}
+
+/**
+ * Track a task delegated to ONYX agent
+ * @param {string} agentName - Name of the ONYX agent
+ * @param {string} taskDescription - Description of the task
+ * @param {object} metadata - Additional metadata
+ * @returns {Promise<object>} Updated statistics
+ */
+export async function trackDelegation(agentName, taskDescription, metadata = {}) {
+  const client = getRedis();
+  const timestamp = new Date().toISOString();
+
+  // Increment delegation counter
+  await client.hincrby(DELEGATION_KEY, 'total', 1);
+  await client.hincrby(DELEGATION_KEY, `agent:${agentName}`, 1);
+
+  // Store delegation event
+  const event = {
+    type: 'delegation',
+    agent: agentName,
+    task: taskDescription,
+    timestamp,
+    metadata
+  };
+
+  await client.lpush('boss:onyx:events', JSON.stringify(event));
+  await client.ltrim('boss:onyx:events', 0, 999); // Keep last 1000 events
+
+  // Check delegation ratio and alert if needed
+  const stats = await getDelegationStats();
+  await checkThresholdAndAlert(stats);
+
+  return stats;
+}
+
+/**
+ * Track a direct action taken by Boss Claude (not delegated)
+ * @param {string} actionType - Type of direct action
+ * @param {string} description - Description of the action
+ * @param {object} metadata - Additional metadata
+ * @returns {Promise<object>} Updated statistics
+ */
+export async function trackDirectAction(actionType, description, metadata = {}) {
+  const client = getRedis();
+  const timestamp = new Date().toISOString();
+
+  // Increment direct action counter
+  await client.hincrby(DIRECT_ACTION_KEY, 'total', 1);
+  await client.hincrby(DIRECT_ACTION_KEY, `type:${actionType}`, 1);
+
+  // Store direct action event
+  const event = {
+    type: 'direct_action',
+    action_type: actionType,
+    description,
+    timestamp,
+    metadata
+  };
+
+  await client.lpush('boss:onyx:events', JSON.stringify(event));
+  await client.ltrim('boss:onyx:events', 0, 999);
+
+  // Check delegation ratio and alert if needed
+  const stats = await getDelegationStats();
+  await checkThresholdAndAlert(stats);
+
+  return stats;
+}
+
+/**
+ * Get current delegation statistics
+ * @returns {Promise<object>} Delegation stats including ratio
+ */
+export async function getDelegationStats() {
+  const client = getRedis();
+
+  const delegationData = await client.hgetall(DELEGATION_KEY);
+  const directActionData = await client.hgetall(DIRECT_ACTION_KEY);
+
+  const totalDelegations = parseInt(delegationData.total || 0);
+  const totalDirectActions = parseInt(directActionData.total || 0);
+  const totalActions = totalDelegations + totalDirectActions;
+
+  const delegationRatio = totalActions > 0 ? totalDelegations / totalActions : 0;
+
+  // Get agent breakdown
+  const agentStats = {};
+  for (const [key, value] of Object.entries(delegationData)) {
+    if (key.startsWith('agent:')) {
+      const agentName = key.replace('agent:', '');
+      agentStats[agentName] = parseInt(value);
+    }
+  }
+
+  // Get action type breakdown
+  const actionTypeStats = {};
+  for (const [key, value] of Object.entries(directActionData)) {
+    if (key.startsWith('type:')) {
+      const actionType = key.replace('type:', '');
+      actionTypeStats[actionType] = parseInt(value);
+    }
+  }
+
+  const threshold = parseFloat(await client.get(ALERT_THRESHOLD_KEY) || DEFAULT_THRESHOLD);
+
+  return {
+    total_delegations: totalDelegations,
+    total_direct_actions: totalDirectActions,
+    total_actions: totalActions,
+    delegation_ratio: delegationRatio,
+    delegation_percentage: (delegationRatio * 100).toFixed(2),
+    threshold: threshold,
+    threshold_percentage: (threshold * 100).toFixed(0),
+    meets_threshold: delegationRatio >= threshold,
+    agent_breakdown: agentStats,
+    direct_action_breakdown: actionTypeStats
+  };
+}
+
+/**
+ * Get recent events (delegations and direct actions)
+ * @param {number} limit - Number of events to retrieve (default: 50)
+ * @returns {Promise<Array>} Recent events
+ */
+export async function getRecentEvents(limit = 50) {
+  const client = getRedis();
+  const events = await client.lrange('boss:onyx:events', 0, limit - 1);
+
+  return events.map(e => JSON.parse(e));
+}
+
+/**
+ * Check if delegation ratio meets threshold and alert if not
+ * @param {object} stats - Current delegation statistics
+ * @returns {Promise<boolean>} True if alert was triggered
+ */
+async function checkThresholdAndAlert(stats) {
+  const client = getRedis();
+
+  // Don't alert if we don't have enough data
+  if (stats.total_actions < 10) {
+    return false;
+  }
+
+  if (!stats.meets_threshold) {
+    // Check if we've alerted recently (throttle to once per hour)
+    const lastAlert = await client.get(LAST_ALERT_KEY);
+    const now = Date.now();
+
+    if (lastAlert) {
+      const lastAlertTime = parseInt(lastAlert);
+      const hoursSinceLastAlert = (now - lastAlertTime) / (1000 * 60 * 60);
+
+      if (hoursSinceLastAlert < 1) {
+        return false; // Skip alert, too soon
+      }
+    }
+
+    // Trigger alert
+    const alertMessage = `ONYX delegation ratio dropped below ${stats.threshold_percentage}%`;
+    const alertData = {
+      current_ratio: stats.delegation_percentage + '%',
+      threshold: stats.threshold_percentage + '%',
+      total_actions: stats.total_actions,
+      delegations: stats.total_delegations,
+      direct_actions: stats.total_direct_actions,
+      agent_breakdown: stats.agent_breakdown,
+      direct_action_breakdown: stats.direct_action_breakdown
+    };
+
+    logAlert(alertMessage, alertData);
+    console.warn(`\n⚠️  ${alertMessage}`);
+    console.warn(`Current ratio: ${stats.delegation_percentage}% (${stats.total_delegations}/${stats.total_actions})`);
+    console.warn(`View details: boss-claude onyx-status\n`);
+
+    // Update last alert timestamp
+    await client.set(LAST_ALERT_KEY, now.toString());
+
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Set the alert threshold (0.0 to 1.0)
+ * @param {number} threshold - New threshold value (e.g., 0.95 for 95%)
+ * @returns {Promise<number>} The new threshold
+ */
+export async function setAlertThreshold(threshold) {
+  if (threshold < 0 || threshold > 1) {
+    throw new Error('Threshold must be between 0 and 1');
+  }
+
+  const client = getRedis();
+  await client.set(ALERT_THRESHOLD_KEY, threshold.toString());
+
+  return threshold;
+}
+
+/**
+ * Get the current alert threshold
+ * @returns {Promise<number>} Current threshold
+ */
+export async function getAlertThreshold() {
+  const client = getRedis();
+  return parseFloat(await client.get(ALERT_THRESHOLD_KEY) || DEFAULT_THRESHOLD);
+}
+
+/**
+ * Reset all delegation tracking data
+ * @returns {Promise<void>}
+ */
+export async function resetTracking() {
+  const client = getRedis();
+
+  await client.del(DELEGATION_KEY);
+  await client.del(DIRECT_ACTION_KEY);
+  await client.del('boss:onyx:events');
+  await client.del(LAST_ALERT_KEY);
+
+  console.log('ONYX delegation tracking has been reset');
+}
+
+/**
+ * Generate a comprehensive delegation report
+ * @param {object} options - Report options
+ * @returns {Promise<object>} Detailed report
+ */
+export async function generateReport(options = {}) {
+  const stats = await getDelegationStats();
+  const recentEvents = await getRecentEvents(options.eventLimit || 50);
+
+  // Calculate time-based metrics
+  const now = new Date();
+  const oneDayAgo = new Date(now - 24 * 60 * 60 * 1000);
+  const oneWeekAgo = new Date(now - 7 * 24 * 60 * 60 * 1000);
+
+  const last24h = recentEvents.filter(e => new Date(e.timestamp) > oneDayAgo);
+  const last7d = recentEvents.filter(e => new Date(e.timestamp) > oneWeekAgo);
+
+  const delegations24h = last24h.filter(e => e.type === 'delegation').length;
+  const directActions24h = last24h.filter(e => e.type === 'direct_action').length;
+  const total24h = delegations24h + directActions24h;
+  const ratio24h = total24h > 0 ? delegations24h / total24h : 0;
+
+  const delegations7d = last7d.filter(e => e.type === 'delegation').length;
+  const directActions7d = last7d.filter(e => e.type === 'direct_action').length;
+  const total7d = delegations7d + directActions7d;
+  const ratio7d = total7d > 0 ? delegations7d / total7d : 0;
+
+  return {
+    overall: stats,
+    time_periods: {
+      last_24h: {
+        delegations: delegations24h,
+        direct_actions: directActions24h,
+        total: total24h,
+        ratio: ratio24h,
+        percentage: (ratio24h * 100).toFixed(2)
+      },
+      last_7d: {
+        delegations: delegations7d,
+        direct_actions: directActions7d,
+        total: total7d,
+        ratio: ratio7d,
+        percentage: (ratio7d * 100).toFixed(2)
+      }
+    },
+    recent_events: recentEvents.slice(0, 10),
+    generated_at: now.toISOString()
+  };
+}
+
+/**
+ * Get formatted status for display
+ * @returns {Promise<string>} Formatted status string
+ */
+export async function getFormattedStatus() {
+  const report = await generateReport();
+  const stats = report.overall;
+
+  const statusIcon = stats.meets_threshold ? '✅' : '⚠️';
+
+  return `
+${statusIcon} ONYX DELEGATION MONITOR
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+OVERALL STATISTICS:
+  Delegation Ratio: ${stats.delegation_percentage}% (${stats.total_delegations}/${stats.total_actions})
+  Alert Threshold:  ${stats.threshold_percentage}%
+  Status:           ${stats.meets_threshold ? 'PASSING ✅' : 'BELOW THRESHOLD ⚠️'}
+
+RECENT ACTIVITY (Last 24h):
+  Delegations:      ${report.time_periods.last_24h.delegations}
+  Direct Actions:   ${report.time_periods.last_24h.direct_actions}
+  Ratio:            ${report.time_periods.last_24h.percentage}%
+
+AGENT BREAKDOWN:
+${Object.entries(stats.agent_breakdown)
+  .sort((a, b) => b[1] - a[1])
+  .map(([agent, count]) => `  ${agent}: ${count} tasks`)
+  .join('\n') || '  No delegations yet'}
+
+DIRECT ACTION BREAKDOWN:
+${Object.entries(stats.direct_action_breakdown)
+  .sort((a, b) => b[1] - a[1])
+  .map(([type, count]) => `  ${type}: ${count} actions`)
+  .join('\n') || '  No direct actions yet'}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Alert Log: ${ALERT_LOG}
+Run 'boss-claude onyx-report' for detailed analysis
+`;
+}
+
+export { ALERT_LOG };