@devran-ai/kit 4.1.0

package/lib/agent-registry.js

@@ -0,0 +1,228 @@
+/**
+ * Devran AI Kit — Agent Registry
+ *
+ * Formalizes agent contracts by validating that every agent markdown
+ * file exposes required metadata structure.
+ *
+ * @module lib/agent-registry
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { AGENT_DIR } = require('./constants');
+const AGENTS_SUBDIR = 'agents';
+const MANIFEST_FILE = 'manifest.json';
+
+/** Minimum expected file size for a valid agent file (bytes) */
+const MIN_AGENT_SIZE = 100;
+/** Maximum expected file size for a valid agent file (bytes) */
+const MAX_AGENT_SIZE = 50000;
+
+/**
+ * @typedef {object} AgentValidation
+ * @property {string} name - Agent name
+ * @property {boolean} valid - Overall validity
+ * @property {string[]} errors - Validation errors
+ * @property {string[]} warnings - Validation warnings
+ * @property {object} metadata - Extracted metadata
+ */
+
+/**
+ * @typedef {object} RegistryReport
+ * @property {number} total - Total agents checked
+ * @property {number} valid - Number of valid agents
+ * @property {number} invalid - Number of invalid agents
+ * @property {AgentValidation[]} agents - Individual agent results
+ */
+
+/**
+ * Extracts metadata from an agent markdown file by parsing its structure.
+ *
+ * @param {string} content - Raw markdown content
+ * @returns {object} Extracted metadata
+ */
+function extractAgentMetadata(content) {
+  const lines = content.split('\n');
+  const metadata = {
+    hasTitle: false,
+    title: '',
+    hasRoleDescription: false,
+    hasCapabilities: false,
+    hasOutputFormat: false,
+    headingCount: 0,
+    lineCount: lines.length,
+  };
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Check for title (# heading)
+    if (trimmed.startsWith('# ') && !metadata.hasTitle) {
+      metadata.hasTitle = true;
+      metadata.title = trimmed.slice(2).trim();
+    }
+
+    // Count all headings
+    if (trimmed.startsWith('#')) {
+      metadata.headingCount += 1;
+    }
+
+    // Check for role/responsibility keywords
+    const roleLower = trimmed.toLowerCase();
+    if (roleLower.includes('role') || roleLower.includes('responsibility') || roleLower.includes('purpose') || roleLower.includes('identity')) {
+      metadata.hasRoleDescription = true;
+    }
+
+    // Check for capabilities/skills mentions
+    if (roleLower.includes('capabilit') || roleLower.includes('skill') || roleLower.includes('tool') || roleLower.includes('expertise')) {
+      metadata.hasCapabilities = true;
+    }
+
+    // Check for output format
+    if (roleLower.includes('output') || roleLower.includes('format') || roleLower.includes('deliver') || roleLower.includes('produce')) {
+      metadata.hasOutputFormat = true;
+    }
+  }
+
+  return metadata;
+}
+
+/**
+ * Validates a single agent file against contract requirements.
+ *
+ * @param {string} agentName - Name of the agent
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {AgentValidation}
+ */
+function validateAgent(agentName, projectRoot) {
+  const agentPath = path.join(projectRoot, AGENT_DIR, AGENTS_SUBDIR, `${agentName}.md`);
+  /** @type {string[]} */
+  const errors = [];
+  /** @type {string[]} */
+  const warnings = [];
+
+  if (!fs.existsSync(agentPath)) {
+    return { name: agentName, valid: false, errors: [`File not found: ${agentName}.md`], warnings: [], metadata: {} };
+  }
+
+  const stats = fs.statSync(agentPath);
+  const content = fs.readFileSync(agentPath, 'utf-8');
+  const metadata = extractAgentMetadata(content);
+
+  // Size checks
+  if (stats.size < MIN_AGENT_SIZE) {
+    errors.push(`File too small (${stats.size} bytes) — likely incomplete`);
+  }
+  if (stats.size > MAX_AGENT_SIZE) {
+    warnings.push(`File very large (${stats.size} bytes) — consider splitting`);
+  }
+
+  // Contract checks
+  if (!metadata.hasTitle) {
+    errors.push('Missing title header (# AgentName)');
+  }
+  if (!metadata.hasRoleDescription) {
+    warnings.push('No role/responsibility section detected');
+  }
+  if (!metadata.hasCapabilities) {
+    warnings.push('No capabilities/skills section detected');
+  }
+  if (metadata.headingCount < 2) {
+    warnings.push('Very few headings — agent file may lack structure');
+  }
+
+  return {
+    name: agentName,
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    metadata,
+  };
+}
+
+/**
+ * Validates all agents registered in the manifest.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {RegistryReport}
+ */
+function validateAllAgents(projectRoot) {
+  const manifestPath = path.join(projectRoot, AGENT_DIR, MANIFEST_FILE);
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return { total: 0, valid: 0, invalid: 0, agents: [] };
+  }
+
+  const agents = manifest.capabilities?.agents?.items || [];
+
+  const results = agents.map((agent) => validateAgent(agent.name, projectRoot));
+  const validCount = results.filter((r) => r.valid).length;
+
+  return {
+    total: results.length,
+    valid: validCount,
+    invalid: results.length - validCount,
+    agents: results,
+  };
+}
+
+/**
+ * Loads the full agent registry from manifest + filesystem.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ agents: object[], totalCount: number }}
+ */
+function loadRegistry(projectRoot) {
+  const manifestPath = path.join(projectRoot, AGENT_DIR, MANIFEST_FILE);
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return { agents: [], totalCount: 0 };
+  }
+
+  const agents = manifest.capabilities?.agents?.items || [];
+
+  return {
+    agents: agents.map((agent) => ({
+      name: agent.name,
+      file: agent.file,
+      domain: agent.domain,
+    })),
+    totalCount: agents.length,
+  };
+}
+
+/**
+ * Finds agents matching a domain keyword.
+ *
+ * @param {string} domain - Domain keyword to search for
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {object[]} Matching agents
+ */
+function getAgentByDomain(domain, projectRoot) {
+  const { agents } = loadRegistry(projectRoot);
+  const lowerDomain = domain.toLowerCase();
+
+  return agents.filter((agent) =>
+    agent.domain.toLowerCase().includes(lowerDomain) ||
+    agent.name.toLowerCase().includes(lowerDomain)
+  );
+}
+
+module.exports = {
+  validateAgent,
+  validateAllAgents,
+  loadRegistry,
+  getAgentByDomain,
+  extractAgentMetadata,
+};

package/lib/agent-reputation.js

@@ -0,0 +1,343 @@
+/**
+ * Devran 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, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
+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);
+  writeJsonAtomic(filePath, data);
+}
+
+/**
+ * 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,
+};