@cpretzinger/boss-claude 1.0.0 → 1.0.2

package/lib/auto-monitor.js

@@ -0,0 +1,131 @@
+/**
+ * AUTO-MONITOR
+ *
+ * Automatic token monitoring that wraps around Boss Claude operations.
+ * Can be used as a drop-in middleware to enforce delegation rules.
+ */
+
+import tokenMonitor from './token-monitor.js';
+import hierarchyValidator from './hierarchy-validator.js';
+import chalk from 'chalk';
+
+/**
+ * Auto-monitored operation wrapper
+ *
+ * Usage:
+ *   const result = await autoMonitor.execute('Search codebase', async () => {
+ *     // Your operation here
+ *     return await searchCodebase();
+ *   }, { estimatedTokens: 250 });
+ *
+ * @param {string} description - Operation description
+ * @param {Function} operation - Async operation to execute
+ * @param {Object} options - Options
+ * @param {number} options.estimatedTokens - Estimated token cost
+ * @param {boolean} options.forceDelegation - Force delegation check
+ * @param {string} options.agent - Agent performing operation (default: 'Boss Claude')
+ * @returns {Promise<Object>} Result with tokens used and operation ID
+ */
+export async function execute(description, operation, options = {}) {
+  const {
+    estimatedTokens = 0,
+    forceDelegation = false,
+    agent = 'Boss Claude'
+  } = options;
+
+  // Start monitoring
+  const opId = tokenMonitor.startOperation(description, estimatedTokens);
+
+  try {
+    // Check if delegation is recommended
+    if (estimatedTokens > 100 || forceDelegation) {
+      const delegation = await hierarchyValidator.checkDelegation(
+        description,
+        estimatedTokens,
+        agent
+      );
+
+      if (delegation.shouldDelegate && !delegation.override) {
+        // User chose to delegate - record it
+        tokenMonitor.recordDelegation(opId, delegation.agent);
+
+        return {
+          delegated: true,
+          agent: delegation.agent,
+          opId,
+          message: `Operation delegated to ${delegation.agent}`
+        };
+      }
+
+      if (delegation.override) {
+        // User overrode delegation - will be monitored closely
+        console.log(chalk.yellow(`⚠️  Override logged - monitoring token usage`));
+      }
+    }
+
+    // Execute operation
+    const startTime = Date.now();
+    const result = await operation();
+    const duration = Date.now() - startTime;
+
+    // Estimate tokens used (rough heuristic: 1 token ≈ 2ms for I/O operations)
+    const estimatedActualTokens = Math.floor(duration / 2);
+
+    // Update monitor with actual tokens
+    tokenMonitor.addTokens(opId, estimatedActualTokens);
+
+    // Complete operation
+    tokenMonitor.completeOperation(opId);
+
+    return {
+      success: true,
+      result,
+      opId,
+      tokensUsed: estimatedActualTokens,
+      duration
+    };
+  } catch (error) {
+    // Log error and complete operation
+    console.error(chalk.red(`❌ Operation failed: ${error.message}`));
+    tokenMonitor.completeOperation(opId);
+
+    throw error;
+  }
+}
+
+/**
+ * Quick delegation check without execution
+ */
+export function shouldDelegate(estimatedTokens) {
+  return tokenMonitor.shouldDelegate(estimatedTokens);
+}
+
+/**
+ * Display session summary
+ */
+export function showSummary() {
+  tokenMonitor.displaySummary();
+}
+
+/**
+ * Reset session
+ */
+export function reset() {
+  tokenMonitor.resetSession();
+}
+
+/**
+ * Get violation count for current session
+ */
+export function getViolations() {
+  const summary = tokenMonitor.getSessionSummary();
+  return summary.violations;
+}
+
+export default {
+  execute,
+  shouldDelegate,
+  showSummary,
+  reset,
+  getViolations
+};

package/lib/checkpoint-hook.js

@@ -0,0 +1,112 @@
+/**
+ * CHECKPOINT AUTOMATION HOOK
+ * Automatically triggers checkpoint every 5 messages
+ * Integrated with Boss Claude session tracking
+ */
+
+import { incrementMessage, formatCheckpointPrompt, getCheckpointStatus } from './checkpoint.js';
+
+/**
+ * Pre-message hook - call before ONYX processes each message
+ * Returns checkpoint prompt if checkpoint needed
+ */
+export async function preMessageHook() {
+  try {
+    const checkpoint = await incrementMessage();
+
+    if (checkpoint) {
+      // Checkpoint triggered - return prompt
+      return {
+        needsCheckpoint: true,
+        prompt: formatCheckpointPrompt(checkpoint),
+        checkpoint
+      };
+    }
+
+    return {
+      needsCheckpoint: false
+    };
+  } catch (error) {
+    console.error('Checkpoint hook error:', error.message);
+    return { needsCheckpoint: false };
+  }
+}
+
+/**
+ * Post-message hook - track ONYX activity
+ * Can be used to auto-detect delegation vs direct execution
+ */
+export async function postMessageHook(messageData) {
+  // Future: Auto-detect delegation from message patterns
+  // Look for keywords: "delegating to", "assigning to", specialist names
+  const specialists = [
+    'n8n-workflow-architect',
+    'postgres-n8n-specialist',
+    'redis-architect',
+    'github-expert',
+    'automation-architect',
+    'openai-streaming-expert',
+    'data-science-pipeline'
+  ];
+
+  const message = messageData.content?.toLowerCase() || '';
+
+  const delegationDetected = specialists.some(s =>
+    message.includes(s.toLowerCase()) ||
+    message.includes('delegate') ||
+    message.includes('assigning to')
+  );
+
+  return {
+    delegation_detected: delegationDetected,
+    specialist: specialists.find(s => message.includes(s.toLowerCase()))
+  };
+}
+
+/**
+ * Generate checkpoint reminder for ONYX
+ */
+export function generateCheckpointReminder(messagesUntilCheckpoint) {
+  if (messagesUntilCheckpoint <= 2) {
+    return `\n⚠️  CHECKPOINT in ${messagesUntilCheckpoint} message${messagesUntilCheckpoint === 1 ? '' : 's'}\n`;
+  }
+  return '';
+}
+
+/**
+ * Validate checkpoint response
+ */
+export function validateCheckpointResponse(response) {
+  const required = ['choice', 'tokens', 'justification'];
+  const missing = required.filter(field => !(field in response));
+
+  if (missing.length > 0) {
+    return {
+      valid: false,
+      error: `Missing required fields: ${missing.join(', ')}`
+    };
+  }
+
+  if (![1, 2].includes(response.choice)) {
+    return {
+      valid: false,
+      error: 'Choice must be 1 (delegated) or 2 (burned)'
+    };
+  }
+
+  if (typeof response.tokens !== 'number' || response.tokens < 0) {
+    return {
+      valid: false,
+      error: 'Tokens must be a positive number'
+    };
+  }
+
+  if (response.choice === 1 && !response.specialist) {
+    return {
+      valid: false,
+      error: 'Specialist required when delegation chosen'
+    };
+  }
+
+  return { valid: true };
+}

package/lib/checkpoint.js

@@ -0,0 +1,319 @@
+/**
+ * ONYX CHECKPOINT SYSTEM
+ * Pauses every 5 messages to enforce delegation accountability
+ * Rule: "Did you delegate or burn tokens?"
+ */
+
+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 { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+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 });
+}
+
+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;
+}
+
+async function getCurrentRepo() {
+  try {
+    const { stdout: repoPath } = await execAsync('git rev-parse --show-toplevel');
+    const { stdout: repoUrl } = await execAsync('git config --get remote.origin.url');
+    const repoName = repoUrl.trim().split('/').pop().replace('.git', '');
+
+    return {
+      name: repoName,
+      path: repoPath.trim(),
+      url: repoUrl.trim()
+    };
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Initialize checkpoint tracking for current session
+ */
+export async function initCheckpoint() {
+  const repo = await getCurrentRepo();
+  if (!repo) {
+    throw new Error('Not in a git repository');
+  }
+
+  const client = getRedis();
+  const checkpointKey = `boss:checkpoint:${repo.name}:current`;
+
+  const checkpoint = {
+    repo: repo.name,
+    started_at: new Date().toISOString(),
+    message_count: 0,
+    checkpoints_passed: 0,
+    delegation_count: 0,
+    token_burn_count: 0,
+    last_checkpoint: null,
+    total_tokens_saved: 0,
+    total_tokens_burned: 0
+  };
+
+  await client.set(checkpointKey, JSON.stringify(checkpoint));
+  return checkpoint;
+}
+
+/**
+ * Increment message counter and check if checkpoint needed
+ * Returns checkpoint data if checkpoint triggered, null otherwise
+ */
+export async function incrementMessage() {
+  const repo = await getCurrentRepo();
+  if (!repo) {
+    return null;
+  }
+
+  const client = getRedis();
+  const checkpointKey = `boss:checkpoint:${repo.name}:current`;
+
+  let checkpoint = await client.get(checkpointKey);
+  if (!checkpoint) {
+    checkpoint = await initCheckpoint();
+  } else {
+    checkpoint = JSON.parse(checkpoint);
+  }
+
+  checkpoint.message_count++;
+
+  // Check if checkpoint needed (every 5 messages)
+  const needsCheckpoint = checkpoint.message_count % 5 === 0;
+
+  if (needsCheckpoint) {
+    checkpoint.last_checkpoint = new Date().toISOString();
+    checkpoint.awaiting_response = true;
+  }
+
+  await client.set(checkpointKey, JSON.stringify(checkpoint));
+
+  return needsCheckpoint ? checkpoint : null;
+}
+
+/**
+ * Record delegation decision at checkpoint
+ * @param {boolean} delegated - Did ONYX delegate the task?
+ * @param {number} tokensSaved - Estimated tokens saved by delegation (if delegated)
+ * @param {number} tokensBurned - Actual tokens used (if not delegated)
+ * @param {string} justification - Reason for decision
+ * @param {string} specialist - Which specialist was used (if delegated)
+ */
+export async function recordCheckpoint(delegated, tokensSaved = 0, tokensBurned = 0, justification = '', specialist = '') {
+  const repo = await getCurrentRepo();
+  if (!repo) {
+    throw new Error('Not in a git repository');
+  }
+
+  const client = getRedis();
+  const checkpointKey = `boss:checkpoint:${repo.name}:current`;
+
+  let checkpoint = await client.get(checkpointKey);
+  if (!checkpoint) {
+    throw new Error('No active checkpoint found');
+  }
+
+  checkpoint = JSON.parse(checkpoint);
+
+  if (!checkpoint.awaiting_response) {
+    throw new Error('No checkpoint awaiting response');
+  }
+
+  // Update checkpoint stats
+  checkpoint.checkpoints_passed++;
+  checkpoint.awaiting_response = false;
+
+  if (delegated) {
+    checkpoint.delegation_count++;
+    checkpoint.total_tokens_saved += tokensSaved;
+  } else {
+    checkpoint.token_burn_count++;
+    checkpoint.total_tokens_burned += tokensBurned;
+  }
+
+  // Save checkpoint record to history
+  const historyKey = `boss:checkpoint:${repo.name}:history`;
+  const record = {
+    timestamp: checkpoint.last_checkpoint,
+    message_count: checkpoint.message_count,
+    delegated,
+    tokens_saved: tokensSaved,
+    tokens_burned: tokensBurned,
+    justification,
+    specialist
+  };
+
+  await client.lpush(historyKey, JSON.stringify(record));
+  await client.ltrim(historyKey, 0, 99); // Keep last 100 checkpoints
+
+  // Update current checkpoint
+  await client.set(checkpointKey, JSON.stringify(checkpoint));
+
+  return {
+    checkpoint,
+    record
+  };
+}
+
+/**
+ * Get current checkpoint status
+ */
+export async function getCheckpointStatus() {
+  const repo = await getCurrentRepo();
+  if (!repo) {
+    return null;
+  }
+
+  const client = getRedis();
+  const checkpointKey = `boss:checkpoint:${repo.name}:current`;
+
+  const checkpoint = await client.get(checkpointKey);
+  if (!checkpoint) {
+    return null;
+  }
+
+  return JSON.parse(checkpoint);
+}
+
+/**
+ * Get checkpoint history
+ * @param {number} limit - Number of records to retrieve
+ */
+export async function getCheckpointHistory(limit = 20) {
+  const repo = await getCurrentRepo();
+  if (!repo) {
+    return [];
+  }
+
+  const client = getRedis();
+  const historyKey = `boss:checkpoint:${repo.name}:history`;
+
+  const records = await client.lrange(historyKey, 0, limit - 1);
+  return records.map(r => JSON.parse(r));
+}
+
+/**
+ * Calculate delegation efficiency
+ */
+export async function getDelegationEfficiency() {
+  const checkpoint = await getCheckpointStatus();
+  if (!checkpoint || checkpoint.checkpoints_passed === 0) {
+    return {
+      delegation_rate: 0,
+      total_checkpoints: 0,
+      tokens_saved: 0,
+      tokens_burned: 0,
+      efficiency_score: 0
+    };
+  }
+
+  const delegation_rate = (checkpoint.delegation_count / checkpoint.checkpoints_passed) * 100;
+  const efficiency_score = checkpoint.total_tokens_saved > 0
+    ? ((checkpoint.total_tokens_saved - checkpoint.total_tokens_burned) / checkpoint.total_tokens_saved) * 100
+    : 0;
+
+  return {
+    delegation_rate: delegation_rate.toFixed(1),
+    total_checkpoints: checkpoint.checkpoints_passed,
+    delegations: checkpoint.delegation_count,
+    token_burns: checkpoint.token_burn_count,
+    tokens_saved: checkpoint.total_tokens_saved,
+    tokens_burned: checkpoint.total_tokens_burned,
+    net_savings: checkpoint.total_tokens_saved - checkpoint.total_tokens_burned,
+    efficiency_score: efficiency_score.toFixed(1)
+  };
+}
+
+/**
+ * Format checkpoint prompt for ONYX
+ */
+export function formatCheckpointPrompt(checkpoint) {
+  const efficiency = checkpoint.checkpoints_passed > 0
+    ? ((checkpoint.delegation_count / checkpoint.checkpoints_passed) * 100).toFixed(1)
+    : 0;
+
+  return `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  CHECKPOINT #${checkpoint.checkpoints_passed + 1}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Session Stats:
+   Messages: ${checkpoint.message_count}
+   Checkpoints Passed: ${checkpoint.checkpoints_passed}
+   Delegation Rate: ${efficiency}%
+   Tokens Saved: ${checkpoint.total_tokens_saved.toLocaleString()}
+   Tokens Burned: ${checkpoint.total_tokens_burned.toLocaleString()}
+
+🔍 ACCOUNTABILITY QUESTION:
+
+Did you delegate or burn tokens?
+
+Options:
+1. DELEGATED - I assigned work to a specialist
+2. BURNED - I did it myself (justify why)
+
+Respond with:
+- Choice: [1 or 2]
+- Tokens: [saved if delegated, burned if not]
+- Specialist: [name if delegated]
+- Justification: [brief reason]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+}
+
+/**
+ * Reset checkpoint for new session
+ */
+export async function resetCheckpoint() {
+  const repo = await getCurrentRepo();
+  if (!repo) {
+    throw new Error('Not in a git repository');
+  }
+
+  const client = getRedis();
+  const checkpointKey = `boss:checkpoint:${repo.name}:current`;
+  await client.del(checkpointKey);
+
+  return await initCheckpoint();
+}
+
+/**
+ * Export checkpoint data for analysis
+ */
+export async function exportCheckpointData() {
+  const checkpoint = await getCheckpointStatus();
+  const history = await getCheckpointHistory(100);
+  const efficiency = await getDelegationEfficiency();
+
+  return {
+    current: checkpoint,
+    history,
+    efficiency,
+    exported_at: new Date().toISOString()
+  };
+}