myshell-tools 1.0.0 → 2.0.0-alpha.0

package/src/orchestrator/handoffs.mjs

@@ -1,231 +0,0 @@
-/**
- * handoffs.mjs — Comprehensive handoff logging and audit trail
- */
-
-import { existsSync, mkdirSync, appendFileSync, readFileSync } from 'fs';
-import { join } from 'path';
-
-/**
- * Log a handoff operation to the audit trail
- */
-export function logHandoff(operation, fromTier, toTier, metadata = {}) {
-  const handoffDir = getCortexDir();
-  ensureHandoffDir(handoffDir);
-
-  const entry = {
-    ts: Date.now(),
-    timestamp: new Date().toISOString(),
-    plan_id: metadata.planId || generatePlanId(),
-    op: operation,
-    from: fromTier,
-    to: toTier,
-    reason: metadata.reason || 'unknown',
-    confidence_in: metadata.confidenceIn || null,
-    confidence_out: metadata.confidenceOut || null,
-    duration_ms: metadata.durationMs || null,
-    provider_from: metadata.providerFrom || null,
-    provider_to: metadata.providerTo || null,
-    attempt: metadata.attempt || 1,
-    session_id: metadata.sessionId || 'unknown',
-    notes: metadata.notes || null
-  };
-
-  const logPath = join(handoffDir, 'handoffs.jsonl');
-
-  try {
-    appendFileSync(logPath, JSON.stringify(entry) + '\n');
-  } catch (error) {
-    console.warn(`Failed to log handoff: ${error.message}`);
-  }
-
-  return entry;
-}
-
-/**
- * Log escalation from one tier to another
- */
-export function logEscalation(fromTier, toTier, reason, metadata = {}) {
-  return logHandoff('escalate_up', fromTier, toTier, {
-    reason,
-    ...metadata
-  });
-}
-
-/**
- * Log delegation down to a lower tier
- */
-export function logDelegation(fromTier, toTier, reason, metadata = {}) {
-  return logHandoff('delegate_down', fromTier, toTier, {
-    reason,
-    ...metadata
-  });
-}
-
-/**
- * Log manager bounce back to IC with feedback
- */
-export function logBounce(fromTier, toTier, feedback, attempt, metadata = {}) {
-  return logHandoff('bounce_down', fromTier, toTier, {
-    reason: 'manager review failure',
-    notes: feedback,
-    attempt,
-    ...metadata
-  });
-}
-
-/**
- * Load recent handoffs for analysis and load balancing
- */
-export function getRecentHandoffs(timeWindowHours = 1, sessionId = null) {
-  const handoffDir = getCortexDir();
-  const logPath = join(handoffDir, 'handoffs.jsonl');
-
-  if (!existsSync(logPath)) {
-    return [];
-  }
-
-  const cutoffTime = Date.now() - (timeWindowHours * 60 * 60 * 1000);
-  const handoffs = [];
-
-  try {
-    const content = readFileSync(logPath, 'utf8');
-    const lines = content.trim().split('\n').filter(line => line.trim());
-
-    for (const line of lines) {
-      try {
-        const entry = JSON.parse(line);
-
-        // Filter by time window
-        if (entry.ts < cutoffTime) continue;
-
-        // Filter by session if specified
-        if (sessionId && entry.session_id !== sessionId) continue;
-
-        handoffs.push(entry);
-      } catch (error) {
-        // Skip malformed lines
-        continue;
-      }
-    }
-  } catch (error) {
-    console.warn(`Failed to read handoff log: ${error.message}`);
-    return [];
-  }
-
-  return handoffs.sort((a, b) => b.ts - a.ts); // Most recent first
-}
-
-/**
- * Get handoff statistics for load balancing
- */
-export function getHandoffStats(timeWindowHours = 1) {
-  const handoffs = getRecentHandoffs(timeWindowHours);
-
-  const stats = {
-    total: handoffs.length,
-    by_operation: {},
-    by_provider: {},
-    by_tier: {},
-    avg_duration_ms: 0,
-    success_rate: 0
-  };
-
-  let totalDuration = 0;
-  let durationsCount = 0;
-  let successful = 0;
-
-  for (const handoff of handoffs) {
-    // Count by operation
-    stats.by_operation[handoff.op] = (stats.by_operation[handoff.op] || 0) + 1;
-
-    // Count by provider (from)
-    if (handoff.provider_from) {
-      stats.by_provider[handoff.provider_from] = (stats.by_provider[handoff.provider_from] || 0) + 1;
-    }
-
-    // Count by tier
-    stats.by_tier[handoff.from] = (stats.by_tier[handoff.from] || 0) + 1;
-
-    // Track durations
-    if (handoff.duration_ms) {
-      totalDuration += handoff.duration_ms;
-      durationsCount++;
-    }
-
-    // Track success (escalations are "success" for routing, bounces are not)
-    if (handoff.op !== 'bounce_down') {
-      successful++;
-    }
-  }
-
-  stats.avg_duration_ms = durationsCount > 0 ? Math.round(totalDuration / durationsCount) : 0;
-  stats.success_rate = stats.total > 0 ? successful / stats.total : 0;
-
-  return stats;
-}
-
-/**
- * Check for failure loops similar to dual-brain pattern
- */
-export function checkFailureLoop(taskHash, timeWindowHours = 2) {
-  const handoffs = getRecentHandoffs(timeWindowHours);
-
-  // Count bounces and escalations for this task
-  const taskHandoffs = handoffs.filter(h =>
-    h.plan_id === taskHash ||
-    h.notes?.includes(taskHash) ||
-    h.reason?.includes(taskHash)
-  );
-
-  const bounces = taskHandoffs.filter(h => h.op === 'bounce_down');
-  const escalations = taskHandoffs.filter(h => h.op === 'escalate_up');
-
-  // Apply decay weight to recent failures (similar to dual-brain)
-  const now = Date.now();
-  let weightedScore = 0;
-
-  for (const handoff of bounces) {
-    const ageMs = now - handoff.ts;
-    const ageMin = ageMs / (60 * 1000);
-
-    let weight = 1.0;
-    if (ageMin > 30) weight = 0.5;
-    if (ageMin > 60) weight = 0.25;
-
-    weightedScore += weight;
-  }
-
-  const isLoop = weightedScore >= 2.0;
-
-  return {
-    isLoop,
-    bounceCount: bounces.length,
-    escalationCount: escalations.length,
-    weightedScore,
-    suggestion: isLoop ? 'escalate_to_manager' : null,
-    recentHandoffs: taskHandoffs.slice(0, 5) // Last 5 for context
-  };
-}
-
-/**
- * Generate a plan/session ID for tracking related handoffs
- */
-function generatePlanId() {
-  return `p_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
-}
-
-/**
- * Get or create .cortex directory
- */
-function getCortexDir(cwd = process.cwd()) {
-  return join(cwd, '.cortex');
-}
-
-/**
- * Ensure handoff directory exists
- */
-function ensureHandoffDir(cortexDir) {
-  if (!existsSync(cortexDir)) {
-    mkdirSync(cortexDir, { recursive: true });
-  }
-}

package/src/orchestrator/review.mjs

@@ -1,222 +0,0 @@
-/**
- * review.mjs — Manager review workflow and bounce-down pattern
- */
-
-import { logBounce, logEscalation, logHandoff } from './handoffs.mjs';
-import { parseConfidence } from './confidence.mjs';
-
-/**
- * Run manager review of IC work and decide action
- * Implements the BOUNCE DOWN workflow from dual-brain
- */
-export async function runManagerReview(task, icResult, context, runTierFn) {
-  console.log(`  🔍 MANAGER REVIEW: Evaluating IC work...`);
-
-  const reviewPrompt = buildManagerReviewPrompt(task, icResult, context);
-
-  // Execute manager review
-  const managerResult = await runTierFn('manager', reviewPrompt, {
-    ...context,
-    operation: 'review',
-    reviewTarget: 'ic_output'
-  });
-
-  if (!managerResult.success) {
-    console.log(`  ❌ Manager review failed: ${managerResult.error}`);
-    return {
-      verdict: 'error',
-      action: 'approve', // Default to approving if review fails
-      notes: `Manager review failed: ${managerResult.error}`,
-      managerResult
-    };
-  }
-
-  // Parse manager decision
-  const decision = parseManagerReviewDecision(managerResult.output);
-
-  console.log(`  📋 Manager decision: ${decision.verdict.toUpperCase()}`);
-  if (decision.notes) {
-    console.log(`  📝 Notes: ${decision.notes}`);
-  }
-
-  // Log the review handoff
-  logHandoff('manager_review', 'ic', 'manager', {
-    reason: 'post-execution review',
-    confidenceIn: icResult.confidence,
-    confidenceOut: managerResult.confidence,
-    durationMs: managerResult.durationMs,
-    sessionId: context.sessionId,
-    notes: decision.notes,
-    verdict: decision.verdict
-  });
-
-  return {
-    verdict: decision.verdict,
-    action: decision.action,
-    notes: decision.notes,
-    managerResult,
-    icResult
-  };
-}
-
-/**
- * Build the manager review prompt
- */
-function buildManagerReviewPrompt(originalTask, icResult, context) {
-  const prompt = `You are a MANAGER reviewing work completed by an IC (Individual Contributor).
-
-ORIGINAL TASK: ${originalTask}
-
-IC'S WORK RESULT:
-─────────────────
-${icResult.output}
-─────────────────
-IC Confidence: ${icResult.confidence || 'Not reported'}
-Duration: ${icResult.durationMs || 'Unknown'}ms
-Model: ${icResult.selectedModel?.model || 'Unknown'}
-
-Your job is to review this work and decide:
-
-REVIEW CRITERIA:
-1. CORRECTNESS: Did the IC actually complete the task as requested?
-2. QUALITY: Is the implementation solid, or are there obvious issues?
-3. SECURITY: Any security concerns or risky patterns?
-4. COMPLETENESS: Are there missing pieces or edge cases not handled?
-5. EDGE CASES: What could break under unusual conditions?
-
-POSSIBLE VERDICTS:
-- APPROVE: Work is good, ship it
-- BOUNCE: IC should fix issues and retry (provide specific feedback)
-- ESCALATE: Manager should take over this task directly
-- REFRAME: Task needs to be broken down or approached differently
-
-Your response MUST end with structured output:
-{"verdict": "approve|bounce|escalate|reframe", "notes": "specific feedback", "confidence": 0.0-1.0, "risk_level": "low|medium|high|critical"}
-
-If bouncing, be specific about what needs to be fixed.
-If approving, note any minor concerns for future reference.`;
-
-  // Add context about previous attempts if this is a retry
-  if (context.attempt && context.attempt > 1) {
-    prompt += `\n\nNOTE: This is attempt #${context.attempt}. Previous manager feedback was addressed.`;
-  }
-
-  // Add manager notes from previous bounces
-  if (context.managerNotes) {
-    prompt += `\n\nPREVIOUS MANAGER FEEDBACK:\n${context.managerNotes}`;
-  }
-
-  return prompt;
-}
-
-/**
- * Parse manager's review decision from their response
- */
-function parseManagerReviewDecision(managerOutput) {
-  const confidence = parseConfidence(managerOutput);
-
-  // Try to extract structured decision
-  const structuredMatch = managerOutput.match(/\{[^{}]*"verdict"[^{}]*\}/);
-
-  if (structuredMatch) {
-    try {
-      const data = JSON.parse(structuredMatch[0]);
-      return {
-        verdict: data.verdict || 'approve',
-        notes: data.notes || '',
-        confidence: data.confidence || confidence.confidence,
-        riskLevel: data.risk_level || 'medium',
-        action: mapVerdictToAction(data.verdict)
-      };
-    } catch (error) {
-      console.warn(`Failed to parse manager decision JSON: ${error.message}`);
-    }
-  }
-
-  // Fallback: try to parse from text patterns
-  const text = managerOutput.toLowerCase();
-
-  let verdict = 'approve'; // default
-  let action = 'approve';
-
-  if (text.includes('bounce') || text.includes('retry') || text.includes('fix')) {
-    verdict = 'bounce';
-    action = 'bounce';
-  } else if (text.includes('escalate') || text.includes('take over') || text.includes('manager should')) {
-    verdict = 'escalate';
-    action = 'escalate';
-  } else if (text.includes('reframe') || text.includes('break down') || text.includes('different approach')) {
-    verdict = 'reframe';
-    action = 'reframe';
-  } else if (text.includes('approve') || text.includes('lgtm') || text.includes('ship it')) {
-    verdict = 'approve';
-    action = 'approve';
-  }
-
-  // Extract notes from the content (everything before structured output)
-  const notes = structuredMatch
-    ? managerOutput.substring(0, managerOutput.indexOf(structuredMatch[0])).trim()
-    : managerOutput.substring(0, 300).trim(); // First 300 chars as fallback
-
-  return {
-    verdict,
-    action,
-    notes: notes || 'No specific notes provided',
-    confidence: confidence.confidence,
-    riskLevel: 'medium' // default when not specified
-  };
-}
-
-/**
- * Map verdict to specific action
- */
-function mapVerdictToAction(verdict) {
-  const actionMap = {
-    approve: 'approve',
-    bounce: 'bounce',
-    escalate: 'escalate',
-    reframe: 'reframe'
-  };
-
-  return actionMap[verdict] || 'approve';
-}
-
-/**
- * Check if task qualifies for automatic manager review
- * Based on risk level and tier routing rules
- */
-export function shouldTriggerManagerReview(task, classification, icResult) {
-  // Always review critical risk tasks
-  if (classification.risk === 'critical') {
-    return { required: true, reason: 'critical risk level' };
-  }
-
-  // Review high risk tasks with medium or low confidence
-  if (classification.risk === 'high' && icResult.confidence < 0.7) {
-    return { required: true, reason: 'high risk with low confidence' };
-  }
-
-  // Review if IC explicitly requested it
-  if (icResult.escalate === true) {
-    return { required: true, reason: 'IC requested escalation' };
-  }
-
-  // Review auth/billing/security related changes
-  if (classification.paths.some(path =>
-    path.includes('auth') ||
-    path.includes('credential') ||
-    path.includes('billing') ||
-    path.includes('payment')
-  )) {
-    return { required: true, reason: 'sensitive file paths' };
-  }
-
-  // Review if no tests were added for substantial changes
-  if (!icResult.output.toLowerCase().includes('test') &&
-      icResult.output.length > 500 &&
-      classification.risk !== 'low') {
-    return { required: true, reason: 'substantial change without tests' };
-  }
-
-  return { required: false, reason: 'standard IC work' };
-}

package/src/providers/balance.mjs

@@ -1,201 +0,0 @@
-/**
- * balance.mjs — Provider load balancing and health monitoring
- */
-
-import { getRecentHandoffs, getHandoffStats } from '../orchestrator/handoffs.mjs';
-
-/**
- * Balance load across providers by tracking recent usage
- */
-export function balanceProviderLoad(availableModels, tier, context = {}) {
-  const tierModels = availableModels[tier] || [];
-  if (tierModels.length <= 1) {
-    return tierModels[0] || null;
-  }
-
-  const { sessionId } = context;
-  const timeWindow = 1; // 1 hour window
-
-  // Get recent usage per provider
-  const usage = getProviderUsage(sessionId, timeWindow);
-  const health = getProviderHealthStatus();
-
-  // Score each model based on usage and health
-  const scoredModels = tierModels.map(model => {
-    const providerUsage = usage[model.provider] || 0;
-    const providerHealth = health[model.provider] || { score: 1.0 };
-
-    // Lower usage = higher score (load balancing)
-    const usageScore = Math.max(0, 1 - (providerUsage / 10)); // Penalize after 10 uses
-
-    // Health score (0.0 = unhealthy, 1.0 = healthy)
-    const healthScore = providerHealth.score;
-
-    // Combined score
-    const totalScore = (usageScore * 0.6) + (healthScore * 0.4);
-
-    return {
-      ...model,
-      score: totalScore,
-      usage: providerUsage,
-      health: providerHealth,
-      reasoning: `usage: ${providerUsage}, health: ${healthScore.toFixed(2)}, score: ${totalScore.toFixed(2)}`
-    };
-  });
-
-  // Sort by score and return best
-  scoredModels.sort((a, b) => b.score - a.score);
-  return scoredModels[0];
-}
-
-/**
- * Get provider usage statistics for load balancing
- */
-function getProviderUsage(sessionId, timeWindowHours) {
-  const handoffs = getRecentHandoffs(timeWindowHours, sessionId);
-
-  const usage = {};
-
-  for (const handoff of handoffs) {
-    // Count operations initiated by each provider
-    if (handoff.provider_from) {
-      usage[handoff.provider_from] = (usage[handoff.provider_from] || 0) + 1;
-    }
-  }
-
-  return usage;
-}
-
-/**
- * Get provider health status based on recent failures
- */
-function getProviderHealthStatus() {
-  const handoffs = getRecentHandoffs(0.5); // Last 30 minutes
-  const health = {};
-
-  // Track failures per provider
-  const failures = {};
-  const total = {};
-
-  for (const handoff of handoffs) {
-    if (!handoff.provider_from) continue;
-
-    const provider = handoff.provider_from;
-    total[provider] = (total[provider] || 0) + 1;
-
-    // Count escalations due to failures as failures
-    if (handoff.op === 'escalate_up' && (
-      handoff.reason.includes('failure') ||
-      handoff.reason.includes('error') ||
-      handoff.reason.includes('timeout')
-    )) {
-      failures[provider] = (failures[provider] || 0) + 1;
-    }
-  }
-
-  // Calculate health scores
-  for (const provider of ['claude', 'codex']) {
-    const totalOps = total[provider] || 0;
-    const failedOps = failures[provider] || 0;
-
-    let score = 1.0; // Default healthy
-
-    if (totalOps > 0) {
-      const failureRate = failedOps / totalOps;
-      score = Math.max(0, 1 - (failureRate * 2)); // Penalize failures heavily
-    }
-
-    // Severely degraded if no operations completed successfully recently
-    if (totalOps === 0 && failedOps > 0) {
-      score = 0.1;
-    }
-
-    health[provider] = {
-      score,
-      failures: failedOps,
-      total: totalOps,
-      failure_rate: totalOps > 0 ? (failedOps / totalOps) : 0,
-      status: score > 0.8 ? 'healthy' : score > 0.5 ? 'degraded' : 'unhealthy'
-    };
-  }
-
-  return health;
-}
-
-/**
- * Check if we should redistribute load
- */
-export function shouldRedistributeLoad(sessionId, threshold = 5) {
-  const usage = getProviderUsage(sessionId, 1);
-  const providers = Object.keys(usage);
-
-  if (providers.length < 2) return false;
-
-  const usageValues = Object.values(usage);
-  const maxUsage = Math.max(...usageValues);
-  const minUsage = Math.min(...usageValues);
-
-  // Redistribute if difference is greater than threshold
-  return (maxUsage - minUsage) > threshold;
-}
-
-/**
- * Get load balancing recommendations
- */
-export function getLoadBalanceRecommendations(sessionId) {
-  const usage = getProviderUsage(sessionId, 1);
-  const health = getProviderHealthStatus();
-  const shouldRedist = shouldRedistributeLoad(sessionId);
-
-  const recommendations = [];
-
-  if (shouldRedist) {
-    // Find overused and underused providers
-    const sorted = Object.entries(usage).sort(([,a], [,b]) => b - a);
-    const [overused] = sorted[0] || [];
-    const [underused] = sorted[sorted.length - 1] || [];
-
-    if (overused && underused && health[underused]?.status === 'healthy') {
-      recommendations.push({
-        type: 'redistribute',
-        from: overused,
-        to: underused,
-        reason: `${overused} is overloaded (${usage[overused]} ops), prefer ${underused} (${usage[underused]} ops)`
-      });
-    }
-  }
-
-  // Health-based recommendations
-  for (const [provider, healthInfo] of Object.entries(health)) {
-    if (healthInfo.status === 'unhealthy') {
-      recommendations.push({
-        type: 'avoid',
-        provider,
-        reason: `${provider} is unhealthy (${Math.round(healthInfo.failure_rate * 100)}% failure rate)`
-      });
-    }
-  }
-
-  return {
-    should_redistribute: shouldRedist,
-    recommendations,
-    current_usage: usage,
-    provider_health: health
-  };
-}
-
-/**
- * Force a provider offline for maintenance
- */
-export function setProviderMaintenance(provider, offline = true) {
-  // This would integrate with a persistent config or state system
-  // For now, just log the maintenance status
-  console.log(`Provider ${provider} maintenance mode: ${offline ? 'ON' : 'OFF'}`);
-
-  // Return updated health status
-  return {
-    provider,
-    maintenance: offline,
-    timestamp: new Date().toISOString()
-  };
-}