aether-colony 1.1.0

package/bin/lib/model-verify.js

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+/**
+ * Model Routing Verification Module
+ *
+ * Verifies that model routing configuration is actually working.
+ * Addresses the gap between "configuration exists" and "execution verified".
+ *
+ * @module bin/lib/model-verify
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Check if LiteLLM proxy is running
+ * @returns {Promise<object>} Proxy status: { running: boolean, latency: number|null }
+ */
+async function checkLiteLLMProxy() {
+  const startTime = Date.now();
+
+  try {
+    // Try to connect to LiteLLM proxy health endpoint
+    const response = await fetch('http://localhost:4000/health', {
+      method: 'GET',
+      signal: AbortSignal.timeout(5000)
+    });
+
+    const latency = Date.now() - startTime;
+
+    if (response.ok) {
+      return {
+        running: true,
+        latency,
+        status: response.status
+      };
+    }
+
+    return {
+      running: false,
+      latency: null,
+      status: response.status
+    };
+  } catch (error) {
+    return {
+      running: false,
+      latency: null,
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Verify model assignment for a caste using aether-utils.sh
+ * @param {string} caste - Caste name (prime, builder, oracle, etc.)
+ * @returns {object} Model assignment: { assigned: boolean, model: string|null, via: string }
+ */
+function verifyModelAssignment(caste) {
+  try {
+    // Check if aether-utils.sh exists
+    const utilsPath = path.join(process.cwd(), '.aether', 'aether-utils.sh');
+    if (!fs.existsSync(utilsPath)) {
+      return {
+        assigned: false,
+        model: null,
+        via: 'not_found',
+        error: 'aether-utils.sh not found'
+      };
+    }
+
+    // Try to get model profile
+    const result = execSync(`bash "${utilsPath}" model-profile get ${caste}`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    // Parse result - should be JSON
+    try {
+      const profile = JSON.parse(result.trim());
+      return {
+        assigned: !!profile.model,
+        model: profile.model || null,
+        via: profile.source || 'unknown',
+        profile
+      };
+    } catch (parseError) {
+      return {
+        assigned: false,
+        model: null,
+        via: 'parse_error',
+        error: `Failed to parse profile: ${parseError.message}`,
+        raw: result
+      };
+    }
+  } catch (error) {
+    return {
+      assigned: false,
+      model: null,
+      via: 'error',
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Check ANTHROPIC_MODEL and ANTHROPIC_BASE_URL environment variables
+ * @returns {object} Environment status: { model: string|null, baseUrl: string|null, routingActive: boolean }
+ */
+function checkAnthropicModelEnv() {
+  const model = process.env.ANTHROPIC_MODEL || null;
+  const baseUrl = process.env.ANTHROPIC_BASE_URL || null;
+
+  // Routing is active if both are set and baseUrl points to LiteLLM proxy
+  const routingActive = !!model && !!baseUrl && baseUrl.includes('localhost:4000');
+
+  return {
+    model,
+    baseUrl,
+    routingActive
+  };
+}
+
+/**
+ * Verify worker spawn environment
+ * Simulates what build.md does before spawning workers
+ * @returns {object} Spawn verification: { wouldRoute: boolean, model: string, issues: string[] }
+ */
+function verifyWorkerSpawnEnv() {
+  const issues = [];
+
+  // Check ANTHROPIC_MODEL
+  const model = process.env.ANTHROPIC_MODEL;
+  if (!model) {
+    issues.push('ANTHROPIC_MODEL not set');
+  }
+
+  // Check ANTHROPIC_BASE_URL
+  const baseUrl = process.env.ANTHROPIC_BASE_URL;
+  if (!baseUrl) {
+    issues.push('ANTHROPIC_BASE_URL not set');
+  } else if (!baseUrl.includes('localhost:4000')) {
+    issues.push('ANTHROPIC_BASE_URL does not point to LiteLLM proxy (localhost:4000)');
+  }
+
+  // Check WORKER_NAME
+  const workerName = process.env.WORKER_NAME;
+  if (!workerName) {
+    issues.push('WORKER_NAME not set (optional but recommended)');
+  }
+
+  // Check CASTE
+  const caste = process.env.CASTE;
+  if (!caste) {
+    issues.push('CASTE not set (optional but recommended)');
+  }
+
+  // Would routing work?
+  const wouldRoute = !!model && !!baseUrl && baseUrl.includes('localhost:4000');
+
+  return {
+    wouldRoute,
+    model: model || 'default (claude-opus-4-6)',
+    caste: caste || 'unknown',
+    workerName: workerName || 'unknown',
+    issues
+  };
+}
+
+/**
+ * Check model profile configuration file
+ * @param {string} repoPath - Path to repository root
+ * @returns {object} Profile file status: { exists: boolean, path: string, profiles: object }
+ */
+function checkModelProfilesFile(repoPath) {
+  const profilesPath = path.join(repoPath, '.aether', 'model-profiles.yaml');
+
+  if (!fs.existsSync(profilesPath)) {
+    return {
+      exists: false,
+      path: profilesPath,
+      profiles: {}
+    };
+  }
+
+  try {
+    const content = fs.readFileSync(profilesPath, 'utf8');
+
+    // Simple YAML parsing for model profiles
+    // Looks for patterns like "prime: glm-5" or "builder: kimi-k2.5"
+    const profiles = {};
+    const lines = content.split('\n');
+
+    for (const line of lines) {
+      const match = line.match(/^(\w+):\s*(.+)$/);
+      if (match) {
+        const [, caste, model] = match;
+        profiles[caste] = model.trim();
+      }
+    }
+
+    return {
+      exists: true,
+      path: profilesPath,
+      profiles
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      path: profilesPath,
+      error: error.message,
+      profiles: {}
+    };
+  }
+}
+
+/**
+ * Create comprehensive verification report
+ * @param {string} repoPath - Path to repository root
+ * @returns {Promise<object>} Complete verification report
+ */
+async function createVerificationReport(repoPath) {
+  const issues = [];
+
+  // Check LiteLLM proxy
+  const proxy = await checkLiteLLMProxy();
+  if (!proxy.running) {
+    issues.push('LiteLLM proxy is not running on localhost:4000');
+  }
+
+  // Check environment
+  const env = checkAnthropicModelEnv();
+  if (!env.routingActive) {
+    issues.push('ANTHROPIC_MODEL/ANTHROPIC_BASE_URL not configured for proxy routing');
+  }
+
+  // Check model profiles file
+  const profilesFile = checkModelProfilesFile(repoPath);
+  if (!profilesFile.exists) {
+    issues.push('Model profiles file not found (.aether/model-profiles.yaml)');
+  }
+
+  // Verify caste assignments
+  const castes = {};
+  const casteNames = ['prime', 'builder', 'oracle', 'scout'];
+
+  for (const caste of casteNames) {
+    const assignment = verifyModelAssignment(caste);
+    castes[caste] = assignment;
+
+    if (!assignment.assigned) {
+      issues.push(`Model not assigned for caste: ${caste}`);
+    }
+  }
+
+  // Check worker spawn environment
+  const spawnEnv = verifyWorkerSpawnEnv();
+
+  // Generate recommendation
+  let recommendation;
+  if (issues.length === 0) {
+    recommendation = 'All checks passed. Model routing is properly configured and verified.';
+  } else if (!proxy.running) {
+    recommendation = 'Start LiteLLM proxy: litellm --config /path/to/config.yaml';
+  } else if (!env.routingActive) {
+    recommendation = 'Set environment variables: export ANTHROPIC_MODEL=your-model && export ANTHROPIC_BASE_URL=http://localhost:4000';
+  } else {
+    recommendation = 'Review configuration files and environment variables';
+  }
+
+  return {
+    proxy,
+    env,
+    profilesFile,
+    castes,
+    spawnEnv,
+    issues,
+    recommendation
+  };
+}
+
+module.exports = {
+  checkLiteLLMProxy,
+  verifyModelAssignment,
+  checkAnthropicModelEnv,
+  verifyWorkerSpawnEnv,
+  checkModelProfilesFile,
+  createVerificationReport
+};

package/bin/lib/nestmate-loader.js

@@ -0,0 +1,130 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Find nestmate colonies (sibling directories with .aether/)
+ * @param {string} currentRepoPath - Current repository path
+ * @returns {Array<{name: string, path: string, goal: string|null}>} Nestmate info
+ */
+function findNestmates(currentRepoPath) {
+  const parentDir = path.dirname(currentRepoPath);
+  const currentName = path.basename(currentRepoPath);
+
+  try {
+    const entries = fs.readdirSync(parentDir, { withFileTypes: true });
+    const nestmates = [];
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === currentName) continue;
+      if (entry.name.startsWith('.')) continue;
+
+      const siblingPath = path.join(parentDir, entry.name);
+      const aetherPath = path.join(siblingPath, '.aether');
+
+      if (fs.existsSync(aetherPath)) {
+        // Try to read colony goal from state
+        let goal = null;
+        try {
+          const statePath = path.join(aetherPath, 'data', 'COLONY_STATE.json');
+          if (fs.existsSync(statePath)) {
+            const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+            goal = state.goal || null;
+          }
+        } catch (e) {
+          // Ignore read errors
+        }
+
+        nestmates.push({
+          name: entry.name,
+          path: siblingPath,
+          goal: goal
+        });
+      }
+    }
+
+    return nestmates;
+  } catch (error) {
+    return [];
+  }
+}
+
+/**
+ * Load TO-DOs from a nestmate
+ * @param {string} nestmatePath - Path to nestmate repository
+ * @returns {Array<{file: string, todos: string[]}>} TO-DO items
+ */
+function loadNestmateTodos(nestmatePath) {
+  const todos = [];
+  const planningPath = path.join(nestmatePath, '.planning');
+
+  try {
+    // Look for TODO files in .planning/
+    if (fs.existsSync(planningPath)) {
+      const entries = fs.readdirSync(planningPath);
+      for (const entry of entries) {
+        if (entry.toLowerCase().includes('todo')) {
+          const todoPath = path.join(planningPath, entry);
+          const content = fs.readFileSync(todoPath, 'utf8');
+          // Extract TODO items (lines starting with - [ ] or TODO:)
+          const items = content.split('\n')
+            .filter(line => line.match(/^\s*-\s*\[\s*\]|TODO:/i))
+            .map(line => line.trim());
+
+          if (items.length > 0) {
+            todos.push({ file: entry, items });
+          }
+        }
+      }
+    }
+  } catch (error) {
+    // Ignore errors
+  }
+
+  return todos;
+}
+
+/**
+ * Get colony state summary from a nestmate
+ * @param {string} nestmatePath - Path to nestmate repository
+ * @returns {Object|null} State summary
+ */
+function getNestmateState(nestmatePath) {
+  try {
+    const statePath = path.join(nestmatePath, '.aether', 'data', 'COLONY_STATE.json');
+    if (!fs.existsSync(statePath)) return null;
+
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    return {
+      goal: state.goal,
+      state: state.state,
+      currentPhase: state.current_phase,
+      milestone: state.milestone
+    };
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Format nestmate info for display
+ * @param {Array} nestmates - Nestmate array from findNestmates
+ * @returns {string} Formatted string
+ */
+function formatNestmates(nestmates) {
+  if (nestmates.length === 0) {
+    return 'No nestmates found.';
+  }
+
+  return nestmates.map(n => {
+    const goal = n.goal ? ` - ${n.goal.substring(0, 40)}${n.goal.length > 40 ? '...' : ''}` : '';
+    return `  • ${n.name}${goal}`;
+  }).join('\n');
+}
+
+module.exports = {
+  findNestmates,
+  loadNestmateTodos,
+  getNestmateState,
+  formatNestmates
+};

package/bin/lib/proxy-health.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+/**
+ * Proxy Health Library
+ *
+ * Health checking utilities for LiteLLM proxy.
+ * Provides functions to verify proxy status, model availability, and routing.
+ */
+
+const { ConfigurationError } = require('./errors');
+
+/**
+ * Default timeout for health check requests (ms)
+ */
+const DEFAULT_TIMEOUT = 5000;
+
+/**
+ * Check proxy health endpoint
+ * @param {string} endpoint - Proxy endpoint URL (e.g., http://localhost:4000)
+ * @param {number} timeoutMs - Timeout in milliseconds (default: 5000)
+ * @returns {Promise<object>} Health status object
+ *   - healthy: boolean - Whether proxy is healthy
+ *   - status: number - HTTP status code
+ *   - latency: number - Response time in milliseconds
+ *   - error: string|null - Error message if unhealthy
+ *   - models: string[]|null - Available model IDs if healthy
+ */
+async function checkProxyHealth(endpoint, timeoutMs = DEFAULT_TIMEOUT) {
+  const startTime = Date.now();
+  const healthUrl = `${endpoint.replace(/\/$/, '')}/health`;
+
+  try {
+    // Use native fetch with AbortSignal for timeout (Node 18+)
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    const response = await fetch(healthUrl, {
+      method: 'GET',
+      signal: controller.signal,
+      headers: {
+        'Accept': 'application/json',
+      },
+    });
+
+    clearTimeout(timeoutId);
+    const latency = Date.now() - startTime;
+
+    if (!response.ok) {
+      return {
+        healthy: false,
+        status: response.status,
+        latency,
+        error: `HTTP ${response.status}: ${response.statusText}`,
+        models: null,
+      };
+    }
+
+    // Try to get models list
+    let models = null;
+    try {
+      models = await getProxyModels(endpoint, timeoutMs);
+    } catch {
+      // Models endpoint may fail even if health passes
+      models = null;
+    }
+
+    return {
+      healthy: true,
+      status: response.status,
+      latency,
+      error: null,
+      models,
+    };
+  } catch (error) {
+    const latency = Date.now() - startTime;
+
+    if (error.name === 'AbortError') {
+      return {
+        healthy: false,
+        status: 0,
+        latency,
+        error: `Timeout after ${timeoutMs}ms`,
+        models: null,
+      };
+    }
+
+    // Handle network errors
+    const errorMessage = error.message || 'Unknown error';
+    return {
+      healthy: false,
+      status: 0,
+      latency,
+      error: errorMessage,
+      models: null,
+    };
+  }
+}
+
+/**
+ * Verify a specific model is routable through the proxy
+ * @param {string} endpoint - Proxy endpoint URL
+ * @param {string} model - Model name to verify
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @returns {Promise<object>} Verification result
+ *   - available: boolean - Whether model is available on proxy
+ *   - found: boolean - Whether model was found in proxy's model list
+ *   - model: string - The model name that was checked
+ */
+async function verifyModelRouting(endpoint, model, timeoutMs = DEFAULT_TIMEOUT) {
+  try {
+    const models = await getProxyModels(endpoint, timeoutMs);
+
+    if (!models) {
+      return {
+        available: false,
+        found: false,
+        model,
+        error: 'Could not fetch models from proxy',
+      };
+    }
+
+    const found = models.includes(model);
+
+    return {
+      available: found,
+      found,
+      model,
+      error: found ? null : `Model '${model}' not found in proxy model list`,
+    };
+  } catch (error) {
+    return {
+      available: false,
+      found: false,
+      model,
+      error: error.message || 'Failed to verify model routing',
+    };
+  }
+}
+
+/**
+ * Fetch available models from proxy
+ * @param {string} endpoint - Proxy endpoint URL
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @returns {Promise<string[]|null>} Array of model IDs or null on error
+ */
+async function getProxyModels(endpoint, timeoutMs = DEFAULT_TIMEOUT) {
+  const modelsUrl = `${endpoint.replace(/\/$/, '')}/models`;
+
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    const response = await fetch(modelsUrl, {
+      method: 'GET',
+      signal: controller.signal,
+      headers: {
+        'Accept': 'application/json',
+      },
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const data = await response.json();
+
+    // LiteLLM returns models in OpenAI format: { data: [{ id: 'model-name' }, ...] }
+    if (data && Array.isArray(data.data)) {
+      return data.data.map(m => m.id).filter(Boolean);
+    }
+
+    // Fallback: try to extract models from various formats
+    if (Array.isArray(data)) {
+      return data.map(m => m.id || m.name || m).filter(Boolean);
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format proxy health status for display
+ * @param {object} health - Health status object from checkProxyHealth
+ * @returns {string} Formatted status string with colors/emoji
+ */
+function formatProxyStatus(health) {
+  if (!health) {
+    return 'Unknown';
+  }
+
+  if (health.healthy) {
+    const latencyStr = health.latency ? `(${health.latency}ms)` : '';
+    return `✓ Healthy ${latencyStr}`.trim();
+  }
+
+  const errorStr = health.error || 'Unknown error';
+  return `✗ Unhealthy: ${errorStr}`;
+}
+
+/**
+ * Format proxy health status with ANSI colors
+ * @param {object} health - Health status object
+ * @param {object} colors - Color functions from colors.js
+ * @returns {string} Colored status string
+ */
+function formatProxyStatusColored(health, colors) {
+  if (!health) {
+    return colors.dim('Unknown');
+  }
+
+  if (health.healthy) {
+    const latencyStr = health.latency ? `(${health.latency}ms)` : '';
+    return `${colors.success('✓')} ${colors.success('Healthy')} ${colors.dim(latencyStr)}`.trim();
+  }
+
+  const errorStr = health.error || 'Unknown error';
+  return `${colors.error('✗')} ${colors.error('Unhealthy')}: ${errorStr}`;
+}
+
+/**
+ * Verify caste model assignments against proxy
+ * @param {string} endpoint - Proxy endpoint URL
+ * @param {object} profiles - Model profiles object
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @returns {Promise<object>} Verification results for all castes
+ */
+async function verifyCasteModels(endpoint, profiles, timeoutMs = DEFAULT_TIMEOUT) {
+  const results = {};
+  const workerModels = profiles?.worker_models || {};
+
+  for (const [caste, model] of Object.entries(workerModels)) {
+    const verification = await verifyModelRouting(endpoint, model, timeoutMs);
+    results[caste] = {
+      model,
+      ...verification,
+    };
+  }
+
+  return results;
+}
+
+module.exports = {
+  checkProxyHealth,
+  verifyModelRouting,
+  getProxyModels,
+  formatProxyStatus,
+  formatProxyStatusColored,
+  verifyCasteModels,
+  DEFAULT_TIMEOUT,
+};