antigravity-ai-kit 2.1.0 → 3.0.1

package/lib/agent-reputation.js

@@ -0,0 +1,351 @@
+/**
+ * Antigravity AI Kit — Agent Reputation Scoring
+ *
+ * Tracks agent task outcomes and computes reputation scores
+ * using a weighted formula with time-decay and cold-start bonus.
+ *
+ * @module lib/agent-reputation
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const AGENT_DIR = '.agent';
+const ENGINE_DIR = 'engine';
+const REPUTATION_FILE = 'reputation.json';
+
+/** Score bounds */
+const MIN_SCORE = 0;
+const MAX_SCORE = 1000;
+
+/** Scoring weights */
+const COMPLETION_WEIGHT = 10;
+const FAILURE_WEIGHT = 15;
+
+/** Cold-start threshold — bonus for agents with fewer than this many outcomes */
+const COLD_START_THRESHOLD = 3;
+const COLD_START_BONUS = 250;
+
+/** Default half-life in days for time decay */
+const DEFAULT_HALF_LIFE_DAYS = 30;
+
+/**
+ * @typedef {object} OutcomeRecord
+ * @property {string} id - Unique outcome ID
+ * @property {string} agent - Agent name
+ * @property {'success' | 'failure'} result - Outcome result
+ * @property {number} cycleTimeMs - Time to complete in milliseconds
+ * @property {string} taskId - Associated task ID
+ * @property {string} timestamp - ISO timestamp
+ */
+
+/**
+ * @typedef {object} AgentReputation
+ * @property {string} agent - Agent name
+ * @property {number} score - Clamped reputation score [0, 1000]
+ * @property {number} completions - Total successful outcomes
+ * @property {number} failures - Total failed outcomes
+ * @property {number} avgCycleTimeMs - Average cycle time in milliseconds
+ * @property {string | null} lastActive - ISO timestamp of last outcome
+ * @property {string} trend - Trend indicator: '↑', '↓', or '→'
+ * @property {number} reliability - Reliability percentage (0-100)
+ */
+
+/**
+ * Resolves the reputation file path.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string}
+ */
+function resolveReputationPath(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, ENGINE_DIR, REPUTATION_FILE);
+}
+
+/**
+ * Loads the reputation data from disk.
+ *
+ * @param {string} projectRoot - Root directory
+ * @returns {{ outcomes: OutcomeRecord[], lastDecayed: string | null }}
+ */
+function loadReputationData(projectRoot) {
+  const filePath = resolveReputationPath(projectRoot);
+
+  if (!fs.existsSync(filePath)) {
+    return { outcomes: [], lastDecayed: null };
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return { outcomes: [], lastDecayed: null };
+  }
+}
+
+/**
+ * Writes reputation data to disk atomically.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {{ outcomes: OutcomeRecord[], lastDecayed: string | null }} data
+ * @returns {void}
+ */
+function writeReputationData(projectRoot, data) {
+  const filePath = resolveReputationPath(projectRoot);
+  const dir = path.dirname(filePath);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tempPath = `${filePath}.tmp`;
+  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  fs.renameSync(tempPath, filePath);
+}
+
+/**
+ * Clamps a value between min and max.
+ *
+ * @param {number} value - Value to clamp
+ * @param {number} min - Minimum
+ * @param {number} max - Maximum
+ * @returns {number}
+ */
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+/**
+ * Records an agent task outcome.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {object} params - Outcome parameters
+ * @param {string} params.agent - Agent name
+ * @param {'success' | 'failure'} params.result - Outcome result
+ * @param {number} [params.cycleTimeMs] - Cycle time in ms (default: 0)
+ * @param {string} [params.taskId] - Associated task ID
+ * @returns {OutcomeRecord}
+ */
+function recordOutcome(projectRoot, { agent, result, cycleTimeMs, taskId }) {
+  if (!agent || typeof agent !== 'string') {
+    throw new Error('Agent name is required');
+  }
+  if (!['success', 'failure'].includes(result)) {
+    throw new Error(`Invalid result: ${result}. Must be 'success' or 'failure'`);
+  }
+
+  const data = loadReputationData(projectRoot);
+
+  /** @type {OutcomeRecord} */
+  const record = {
+    id: `OUT-${crypto.randomUUID().slice(0, 8).toUpperCase()}`,
+    agent,
+    result,
+    cycleTimeMs: cycleTimeMs || 0,
+    taskId: taskId || 'unknown',
+    timestamp: new Date().toISOString(),
+  };
+
+  data.outcomes.push(record);
+  writeReputationData(projectRoot, data);
+
+  return record;
+}
+
+/**
+ * Calculates the consistency bonus based on outcome streak.
+ * Rewards agents with consecutive successes.
+ *
+ * @param {OutcomeRecord[]} agentOutcomes - Sorted outcomes for an agent
+ * @returns {number} Consistency bonus (0-100)
+ */
+function calculateConsistencyBonus(agentOutcomes) {
+  if (agentOutcomes.length === 0) {
+    return 0;
+  }
+
+  // Count consecutive successes from most recent.
+  // Use original index as a stable tiebreaker when timestamps are identical
+  // (prevents non-deterministic sort across JS engines).
+  let streak = 0;
+  const indexed = agentOutcomes.map((o, i) => ({ ...o, _idx: i }));
+  const sorted = indexed.sort((a, b) => {
+    const timeDiff = new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime();
+    return timeDiff !== 0 ? timeDiff : b._idx - a._idx;
+  });
+
+  for (const outcome of sorted) {
+    if (outcome.result === 'success') {
+      streak += 1;
+    } else {
+      break;
+    }
+  }
+
+  // Cap bonus at 100 (10 consecutive successes)
+  return Math.min(streak * 10, 100);
+}
+
+/**
+ * Computes reputation for a single agent.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {string} agentName - Agent name
+ * @returns {AgentReputation}
+ */
+function getReputation(projectRoot, agentName) {
+  const data = loadReputationData(projectRoot);
+  const agentOutcomes = data.outcomes.filter((o) => o.agent === agentName);
+
+  const completions = agentOutcomes.filter((o) => o.result === 'success').length;
+  const failures = agentOutcomes.filter((o) => o.result === 'failure').length;
+  const totalOutcomes = agentOutcomes.length;
+
+  // Average cycle time
+  const successOutcomes = agentOutcomes.filter((o) => o.result === 'success' && o.cycleTimeMs > 0);
+  const avgCycleTimeMs = successOutcomes.length > 0
+    ? Math.round(successOutcomes.reduce((sum, o) => sum + o.cycleTimeMs, 0) / successOutcomes.length)
+    : 0;
+
+  // Last active
+  const lastActive = agentOutcomes.length > 0
+    ? agentOutcomes.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())[0].timestamp
+    : null;
+
+  // Consistency bonus
+  const consistencyBonus = calculateConsistencyBonus(agentOutcomes);
+
+  // Cold-start bonus — only for agents with at least 1 but fewer than threshold outcomes
+  const coldStartBonus = (totalOutcomes > 0 && totalOutcomes < COLD_START_THRESHOLD) ? COLD_START_BONUS : 0;
+
+  // Raw score
+  const rawScore = (completions * COMPLETION_WEIGHT) - (failures * FAILURE_WEIGHT) + consistencyBonus + coldStartBonus;
+
+  // Clamped score
+  const score = clamp(Math.round(rawScore), MIN_SCORE, MAX_SCORE);
+
+  // Trend — compare last 5 vs previous 5
+  const trend = calculateTrend(agentOutcomes);
+
+  // Reliability percentage
+  const reliability = totalOutcomes > 0 ? Math.round((completions / totalOutcomes) * 100) : 0;
+
+  return {
+    agent: agentName,
+    score,
+    completions,
+    failures,
+    avgCycleTimeMs,
+    lastActive,
+    trend,
+    reliability,
+  };
+}
+
+/**
+ * Calculates trend from recent outcomes.
+ *
+ * @param {OutcomeRecord[]} outcomes - Agent outcomes
+ * @returns {string} '↑', '↓', or '→'
+ */
+function calculateTrend(outcomes) {
+  if (outcomes.length < 2) {
+    return '→';
+  }
+
+  const sorted = [...outcomes].sort(
+    (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
+  );
+
+  const recentFive = sorted.slice(0, 5);
+  const previousFive = sorted.slice(5, 10);
+
+  if (previousFive.length === 0) {
+    return '→';
+  }
+
+  const recentSuccessRate = recentFive.filter((o) => o.result === 'success').length / recentFive.length;
+  const previousSuccessRate = previousFive.filter((o) => o.result === 'success').length / previousFive.length;
+
+  const delta = recentSuccessRate - previousSuccessRate;
+
+  if (delta > 0.1) {
+    return '↑';
+  }
+  if (delta < -0.1) {
+    return '↓';
+  }
+  return '→';
+}
+
+/**
+ * Returns all agents ranked by reputation score (descending).
+ * Agents with fewer than COLD_START_THRESHOLD outcomes are marked as 'new'.
+ *
+ * @param {string} projectRoot - Root directory
+ * @returns {AgentReputation[]}
+ */
+function getRankings(projectRoot) {
+  const data = loadReputationData(projectRoot);
+
+  // Get unique agent names
+  const agentNames = [...new Set(data.outcomes.map((o) => o.agent))];
+
+  const rankings = agentNames.map((name) => getReputation(projectRoot, name));
+
+  // Sort by score descending, then by completions descending
+  rankings.sort((a, b) => {
+    if (b.score !== a.score) {
+      return b.score - a.score;
+    }
+    return b.completions - a.completions;
+  });
+
+  return rankings;
+}
+
+/**
+ * Applies time-decay to all outcome records.
+ * Removes outcomes older than 2× half-life to keep data manageable.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {object} [options] - Decay options
+ * @param {number} [options.halfLifeDays] - Half-life in days (default: 30)
+ * @returns {{ decayed: number, removed: number, remaining: number }}
+ */
+function decayScores(projectRoot, options = {}) {
+  const halfLifeDays = options.halfLifeDays || DEFAULT_HALF_LIFE_DAYS;
+  const maxAgeDays = halfLifeDays * 2;
+  const now = Date.now();
+  const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+
+  const data = loadReputationData(projectRoot);
+  const originalCount = data.outcomes.length;
+
+  // Remove outcomes older than 2× half-life
+  data.outcomes = data.outcomes.filter((outcome) => {
+    const ageMs = now - new Date(outcome.timestamp).getTime();
+    return ageMs < maxAgeMs;
+  });
+
+  const removedCount = originalCount - data.outcomes.length;
+
+  data.lastDecayed = new Date().toISOString();
+  writeReputationData(projectRoot, data);
+
+  return {
+    decayed: originalCount,
+    removed: removedCount,
+    remaining: data.outcomes.length,
+  };
+}
+
+module.exports = {
+  recordOutcome,
+  getReputation,
+  getRankings,
+  decayScores,
+};

package/lib/cli-commands.js

@@ -0,0 +1,235 @@
+/**
+ * Antigravity AI Kit — CLI Command Handlers (Phase 4)
+ *
+ * Extracted command handlers to keep bin/ag-kit.js under 800 lines.
+ * Handles: `market`, `heal`, and dashboard sections.
+ *
+ * @module lib/cli-commands
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ANSI colors (shared with ag-kit.js)
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+};
+
+/**
+ * Marketplace CLI handler.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {string} subCommand - Sub-command: search, info, install, update
+ * @param {string} [argument] - Argument for the sub-command
+ * @param {object} [options] - CLI options
+ * @returns {void}
+ */
+function marketCommand(projectRoot, subCommand, argument, options = {}) {
+  const marketplace = require('./marketplace');
+
+  switch (subCommand) {
+    case 'search': {
+      if (!argument) {
+        console.log(`${colors.yellow}Usage: ag-kit market search <query>${colors.reset}`);
+        return;
+      }
+      const results = marketplace.searchMarket(projectRoot, argument);
+      console.log(`\n${colors.bright}${colors.blue}═══ Marketplace Search: "${argument}" ═══${colors.reset}\n`);
+      if (results.length === 0) {
+        console.log(`   No plugins found matching "${argument}"`);
+      } else {
+        for (const entry of results) {
+          console.log(`   ${colors.green}${entry.name}${colors.reset} v${entry.version}`);
+          console.log(`   ${entry.description}`);
+          console.log(`   Tags: ${(entry.tags || []).join(', ')}`);
+          console.log('');
+        }
+      }
+      console.log(`   ${results.length} result(s)\n`);
+      break;
+    }
+
+    case 'info': {
+      if (!argument) {
+        console.log(`${colors.yellow}Usage: ag-kit market info <plugin-name>${colors.reset}`);
+        return;
+      }
+      const info = marketplace.getMarketInfo(projectRoot, argument);
+      if (!info) {
+        console.log(`${colors.red}Plugin not found: ${argument}${colors.reset}`);
+        return;
+      }
+      console.log(`\n${colors.bright}${colors.blue}═══ Plugin: ${info.name} ═══${colors.reset}\n`);
+      console.log(`   Version:     ${info.version}`);
+      console.log(`   Author:      ${info.author}`);
+      console.log(`   Description: ${info.description}`);
+      console.log(`   Repository:  ${info.repository}`);
+      console.log(`   Tags:        ${(info.tags || []).join(', ')}\n`);
+      break;
+    }
+
+    case 'install': {
+      if (!argument) {
+        console.log(`${colors.yellow}Usage: ag-kit market install <plugin-name>${colors.reset}`);
+        return;
+      }
+      console.log(`${colors.cyan}Installing ${argument}...${colors.reset}`);
+      const result = marketplace.installFromMarket(projectRoot, argument);
+      if (result.success) {
+        console.log(`${colors.green}✓ ${result.message}${colors.reset}`);
+      } else {
+        console.log(`${colors.red}✗ ${result.message}${colors.reset}`);
+      }
+      break;
+    }
+
+    case 'update': {
+      const force = options.force || false;
+      const result = marketplace.updateRegistryIndex(projectRoot, { force });
+      if (result.updated) {
+        console.log(`${colors.green}✓ Registry updated (${result.entryCount} entries)${colors.reset}`);
+      } else {
+        console.log(`${colors.yellow}Registry is fresh (${result.entryCount} entries). Use --force to update.${colors.reset}`);
+      }
+      break;
+    }
+
+    default:
+      console.log(`${colors.yellow}Usage: ag-kit market <search|info|install|update> [arg]${colors.reset}`);
+      break;
+  }
+}
+
+/**
+ * Self-healing CLI handler.
+ *
+ * @param {string} projectRoot - Root directory
+ * @param {object} [options] - CLI options
+ * @param {string} [options.file] - Path to CI log file
+ * @param {boolean} [options.apply] - Apply patches (default: dry-run)
+ * @returns {void}
+ */
+function healCommand(projectRoot, options = {}) {
+  const selfHealing = require('./self-healing');
+  let ciOutput = '';
+
+  // Input source (E-3): file > stdin > last-saved
+  if (options.file) {
+    const filePath = path.resolve(options.file);
+    if (!fs.existsSync(filePath)) {
+      console.log(`${colors.red}✗ CI log file not found: ${filePath}${colors.reset}`);
+      process.exit(1);
+    }
+    ciOutput = fs.readFileSync(filePath, 'utf-8');
+  } else {
+    // Try last-saved CI output
+    const lastCiPath = path.join(projectRoot, '.agent', 'engine', 'last-ci-output.txt');
+    if (fs.existsSync(lastCiPath)) {
+      ciOutput = fs.readFileSync(lastCiPath, 'utf-8');
+    } else {
+      console.log(`${colors.yellow}No CI output found. Use: ag-kit heal --file <path>${colors.reset}`);
+      return;
+    }
+  }
+
+  console.log(`\n${colors.bright}${colors.blue}═══ Self-Healing Pipeline ═══${colors.reset}\n`);
+
+  // Detect failures
+  const failures = selfHealing.detectFailure(ciOutput);
+
+  if (failures.length === 0) {
+    console.log(`   ${colors.green}✓ No failures detected — pipeline is healthy${colors.reset}\n`);
+    return;
+  }
+
+  console.log(`   ${colors.red}${failures.length} failure(s) detected${colors.reset}\n`);
+
+  // Diagnose and generate patches
+  for (const failure of failures) {
+    const diagnosis = selfHealing.diagnoseFailure(failure);
+    console.log(`   ${colors.yellow}[${failure.type.toUpperCase()}]${colors.reset} ${failure.message}`);
+    console.log(`   Diagnosis: ${diagnosis.category} — ${diagnosis.explanation}`);
+
+    if (diagnosis.autoFixable) {
+      const patch = selfHealing.generateFixPatch(failure, diagnosis);
+      if (patch) {
+        const dryRun = !options.apply;
+        const result = selfHealing.applyFixWithConfirmation(projectRoot, patch, { dryRun });
+        console.log(`   Patch ${patch.patchId}: ${dryRun ? 'DRY RUN' : result.applied ? 'APPLIED' : 'FAILED'}`);
+      }
+    } else {
+      console.log(`   ${colors.cyan}→ Manual review required${colors.reset}`);
+    }
+    console.log('');
+  }
+}
+
+/**
+ * Dashboard sections for Phase 4 features.
+ * Called by statusCommand() in ag-kit.js.
+ *
+ * @param {string} projectRoot - Root directory
+ * @returns {void}
+ */
+function renderDashboardSections(projectRoot) {
+  // ═══ Reputation ═══
+  try {
+    const reputation = require('./agent-reputation');
+    const rankings = reputation.getRankings(projectRoot);
+
+    console.log(`\n${colors.bright}${colors.cyan}═══ Reputation ═══${colors.reset}`);
+
+    if (rankings.length === 0) {
+      console.log('   No reputation data yet');
+    } else {
+      for (const agent of rankings.slice(0, 5)) {
+        const trend = agent.trend;
+        console.log(`   ${colors.green}${agent.agent}${colors.reset} — Score: ${agent.score} ${trend} | Reliability: ${agent.reliability}%`);
+      }
+    }
+  } catch {
+    // Reputation module not available — silently skip
+  }
+
+  // ═══ Sprint ═══
+  try {
+    const engMgr = require('./engineering-manager');
+    const metrics = engMgr.getSprintMetrics(projectRoot);
+
+    console.log(`\n${colors.bright}${colors.cyan}═══ Sprint ═══${colors.reset}`);
+    console.log(`   Total Sprints: ${metrics.totalSprints}`);
+    console.log(`   Active Sprint: ${metrics.activeSprint ? metrics.activeSprint.name : 'none'}`);
+    console.log(`   Velocity:      ${metrics.velocity} tasks/sprint`);
+  } catch {
+    // Module not available — silently skip
+  }
+
+  // ═══ Health ═══
+  try {
+    const selfHealing = require('./self-healing');
+    const report = selfHealing.getHealingReport(projectRoot);
+
+    console.log(`\n${colors.bright}${colors.cyan}═══ Health ═══${colors.reset}`);
+    console.log(`   Total Heals:    ${report.totalHeals}`);
+    console.log(`   Success Rate:   ${report.successRate}%`);
+    console.log(`   Pending Patches: ${report.pendingPatches}`);
+  } catch {
+    // Module not available — silently skip
+  }
+}
+
+module.exports = {
+  marketCommand,
+  healCommand,
+  renderDashboardSections,
+};