swarm-orchestrator 7.0.0-alpha.0

package/dist/src/agents-exporter.js

@@ -0,0 +1,398 @@
+"use strict";
+// Generates empirically-derived .agent.md files from execution history.
+// Reads knowledge base patterns across runs, aggregates per-agent stats,
+// and produces agent definitions enriched with learned conventions.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentsExporter = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_loader_1 = require("./config-loader");
+// 30-day half-life for exponential decay weighting
+const HALF_LIFE_DAYS = 30;
+/**
+ * Reads knowledge base data from execution history and generates
+ * .agent.md files with learned conventions baked into the instructions.
+ */
+class AgentsExporter {
+    runsDir;
+    configLoader;
+    constructor(workingDir) {
+        const baseDir = workingDir || process.cwd();
+        this.runsDir = path.join(baseDir, 'runs');
+        this.configLoader = new config_loader_1.ConfigLoader();
+    }
+    /**
+     * Export all agents as .agent.md files.
+     * If sufficient run data exists, enriches base definitions with learned patterns.
+     * Otherwise, generates from base definitions with a note about needing more data.
+     */
+    export(options) {
+        if (!fs.existsSync(options.outputDir)) {
+            fs.mkdirSync(options.outputDir, { recursive: true });
+        }
+        const baseAgents = this.loadBaseAgents();
+        const knowledgeBases = this.loadAllKnowledgeBases();
+        const totalRuns = this.countDistinctRuns(knowledgeBases);
+        const fromData = totalRuns >= options.minRuns;
+        const agentStats = fromData
+            ? this.aggregatePerAgent(knowledgeBases, baseAgents)
+            : new Map();
+        const diffs = [];
+        const agentsExported = [];
+        for (const agent of baseAgents) {
+            const stats = agentStats.get(agent.name);
+            const content = this.generateAgentMd(agent, stats, fromData, totalRuns);
+            const filename = agent.name.toLowerCase().replace(/[^a-z0-9]+/g, '_') + '.agent.md';
+            const outputPath = path.join(options.outputDir, filename);
+            // Compute diff if requested and a previous export exists
+            if (options.diff && fs.existsSync(outputPath)) {
+                const previous = fs.readFileSync(outputPath, 'utf8');
+                const entryDiffs = this.computeDiff(agent.name, previous, content);
+                diffs.push(...entryDiffs);
+            }
+            fs.writeFileSync(outputPath, content, 'utf8');
+            agentsExported.push(agent.name);
+        }
+        return { agentsExported, outputDir: options.outputDir, fromData, diffs };
+    }
+    /**
+     * Load base agent profiles from config.
+     */
+    loadBaseAgents() {
+        return this.configLoader.loadAllAgents();
+    }
+    /**
+     * Scan the runs directory for knowledge-base.json files.
+     */
+    loadAllKnowledgeBases() {
+        if (!fs.existsSync(this.runsDir))
+            return [];
+        const results = [];
+        let entries;
+        try {
+            entries = fs.readdirSync(this.runsDir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const kbPath = path.join(this.runsDir, entry.name, 'knowledge-base.json');
+            if (fs.existsSync(kbPath)) {
+                try {
+                    const content = fs.readFileSync(kbPath, 'utf8');
+                    const kb = JSON.parse(content);
+                    results.push(kb);
+                }
+                catch {
+                    // Skip malformed files without crashing the export
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Count distinct runs across all knowledge bases, weighting recent runs
+     * more heavily via exponential decay (30-day half-life).
+     */
+    countDistinctRuns(bases) {
+        // Each knowledge base file represents one or more runs.
+        // totalRuns from the statistics field is the authoritative count per file.
+        return bases.reduce((sum, kb) => sum + (kb.statistics.totalRuns || 1), 0);
+    }
+    /**
+     * Aggregate knowledge patterns per agent with recency weighting.
+     */
+    aggregatePerAgent(bases, agents) {
+        const statsMap = new Map();
+        // Initialize stats for each known agent
+        for (const agent of agents) {
+            statsMap.set(agent.name, {
+                agentName: agent.name,
+                totalMentions: 0,
+                failureModes: [],
+                successPatterns: [],
+                toolGuidance: [],
+                scopePatterns: [],
+                boundaryViolations: [],
+                avgDurationHint: undefined,
+                costHint: undefined
+            });
+        }
+        const now = Date.now();
+        for (const kb of bases) {
+            for (const pattern of kb.patterns) {
+                const weight = this.computeRecencyWeight(pattern.lastSeen, now);
+                // Only process patterns above minimum relevance weight
+                if (weight < 0.1)
+                    continue;
+                // Find which agent(s) this pattern mentions
+                for (const agent of agents) {
+                    const nameLower = agent.name.toLowerCase();
+                    // Normalize for matching: strip underscores so "backend_master" matches "backendmaster" in KB text
+                    const nameNormalized = nameLower.replace(/_/g, '');
+                    const insightLower = pattern.insight.toLowerCase();
+                    const evidenceStr = pattern.evidence.join(' ').toLowerCase();
+                    const nameMatches = insightLower.includes(nameLower)
+                        || insightLower.includes(nameNormalized)
+                        || evidenceStr.includes(nameLower)
+                        || evidenceStr.includes(nameNormalized);
+                    if (!nameMatches) {
+                        continue;
+                    }
+                    const stats = statsMap.get(agent.name);
+                    if (!stats)
+                        continue;
+                    stats.totalMentions++;
+                    this.classifyPattern(pattern, stats, weight);
+                }
+            }
+        }
+        return statsMap;
+    }
+    /**
+     * Apply exponential decay weighting based on when the pattern was last seen.
+     */
+    computeRecencyWeight(lastSeen, nowMs) {
+        const seenMs = new Date(lastSeen).getTime();
+        if (isNaN(seenMs))
+            return 0.5; // Unknown date gets neutral weight
+        const daysSince = (nowMs - seenMs) / (1000 * 60 * 60 * 24);
+        return Math.pow(0.5, daysSince / HALF_LIFE_DAYS);
+    }
+    /**
+     * Classify a knowledge pattern into the appropriate stats bucket.
+     */
+    classifyPattern(pattern, stats, _weight) {
+        switch (pattern.category) {
+            case 'failure_mode':
+                if (!stats.failureModes.includes(pattern.insight)) {
+                    stats.failureModes.push(pattern.insight);
+                }
+                break;
+            case 'best_practice':
+                if (!stats.successPatterns.includes(pattern.insight)) {
+                    stats.successPatterns.push(pattern.insight);
+                }
+                break;
+            case 'anti_pattern':
+                if (!stats.boundaryViolations.includes(pattern.insight)) {
+                    stats.boundaryViolations.push(pattern.insight);
+                }
+                break;
+            case 'agent_behavior':
+                // Extract file path patterns from evidence
+                for (const ev of pattern.evidence) {
+                    if (ev.includes('/') && !stats.scopePatterns.includes(ev)) {
+                        stats.scopePatterns.push(ev);
+                    }
+                }
+                break;
+            case 'cost_history':
+                // Extract cost insights for the agent
+                if (pattern.insight.includes('premium request')) {
+                    stats.costHint = pattern.insight;
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    /**
+     * Generate .agent.md content for a single agent with optional learned data.
+     */
+    generateAgentMd(agent, stats, fromData, totalRuns) {
+        const sections = [];
+        // YAML frontmatter
+        sections.push('---');
+        sections.push(`name: ${agent.name}`);
+        sections.push(`description: ${agent.purpose}`);
+        sections.push('tools:');
+        const tools = agent.tools || ['file_operations', 'terminal', 'git'];
+        for (const tool of tools) {
+            sections.push(`  - ${tool}`);
+        }
+        sections.push('model: claude-sonnet-4');
+        sections.push('---');
+        sections.push('');
+        // Title
+        sections.push(`# ${agent.name}`);
+        sections.push('');
+        // Data notice
+        if (!fromData) {
+            sections.push('> **Note:** This agent definition is generated from base configuration.');
+            sections.push(`> Only ${totalRuns} run(s) recorded. Export again after 5+ runs for`);
+            sections.push('> data-driven recommendations.');
+            sections.push('');
+        }
+        // Purpose
+        sections.push('## Purpose');
+        sections.push('');
+        sections.push(agent.purpose + '.');
+        sections.push('');
+        // Scope
+        sections.push('## Scope');
+        sections.push('');
+        for (const item of agent.scope) {
+            sections.push(`- ${item}`);
+        }
+        sections.push('');
+        // Boundaries
+        sections.push('## Boundaries');
+        sections.push('');
+        for (const item of agent.boundaries) {
+            sections.push(`- ${item}`);
+        }
+        sections.push('');
+        // Done Definition
+        sections.push('## Done Definition');
+        sections.push('');
+        for (const item of agent.done_definition) {
+            sections.push(`- ${item}`);
+        }
+        sections.push('');
+        // Learned sections (only when sufficient data exists)
+        if (fromData && stats && stats.totalMentions > 0) {
+            // Failure prevention
+            if (stats.failureModes.length > 0) {
+                sections.push('## Failure Prevention (Learned)');
+                sections.push('');
+                sections.push('The following patterns have caused failures in past runs. Avoid them:');
+                sections.push('');
+                for (const mode of stats.failureModes.slice(0, 10)) {
+                    sections.push(`- ${mode}`);
+                }
+                sections.push('');
+            }
+            // Success patterns
+            if (stats.successPatterns.length > 0) {
+                sections.push('## Proven Patterns');
+                sections.push('');
+                sections.push('These approaches have consistently succeeded:');
+                sections.push('');
+                for (const pattern of stats.successPatterns.slice(0, 10)) {
+                    sections.push(`- ${pattern}`);
+                }
+                sections.push('');
+            }
+            // Scope insights from actual file paths
+            if (stats.scopePatterns.length > 0) {
+                sections.push('## Observed File Scope');
+                sections.push('');
+                sections.push('Files this agent typically modifies (based on execution history):');
+                sections.push('');
+                for (const sp of stats.scopePatterns.slice(0, 15)) {
+                    sections.push(`- \`${sp}\``);
+                }
+                sections.push('');
+            }
+            // Boundary violations
+            if (stats.boundaryViolations.length > 0) {
+                sections.push('## Anti-Patterns (Do Not Repeat)');
+                sections.push('');
+                for (const violation of stats.boundaryViolations.slice(0, 10)) {
+                    sections.push(`- ${violation}`);
+                }
+                sections.push('');
+            }
+            // Cost hints
+            if (stats.costHint) {
+                sections.push('## Performance Notes');
+                sections.push('');
+                sections.push(`- ${stats.costHint}`);
+                sections.push('');
+            }
+        }
+        // Refusal rules (always included)
+        sections.push('## Refusal Rules');
+        sections.push('');
+        for (const rule of agent.refusal_rules) {
+            sections.push(`- ${rule}`);
+        }
+        sections.push('');
+        return sections.join('\n');
+    }
+    /**
+     * Compute a simple section-level diff between previous and current exports.
+     */
+    computeDiff(agentName, previous, current) {
+        const diffs = [];
+        const prevSections = this.extractSections(previous);
+        const currSections = this.extractSections(current);
+        // Compare each section header
+        const allHeaders = new Set([...prevSections.keys(), ...currSections.keys()]);
+        for (const header of allHeaders) {
+            const prevContent = prevSections.get(header) || '';
+            const currContent = currSections.get(header) || '';
+            if (prevContent !== currContent) {
+                diffs.push({
+                    agentName,
+                    field: header,
+                    previous: prevContent.slice(0, 200),
+                    current: currContent.slice(0, 200)
+                });
+            }
+        }
+        return diffs;
+    }
+    /**
+     * Extract markdown sections as header -> body map.
+     */
+    extractSections(content) {
+        const sections = new Map();
+        const lines = content.split('\n');
+        let currentHeader = '_frontmatter';
+        let currentBody = [];
+        for (const line of lines) {
+            const match = line.match(/^##?\s+(.+)/);
+            if (match) {
+                // Save previous section
+                sections.set(currentHeader, currentBody.join('\n').trim());
+                currentHeader = match[1];
+                currentBody = [];
+            }
+            else {
+                currentBody.push(line);
+            }
+        }
+        // Save last section
+        sections.set(currentHeader, currentBody.join('\n').trim());
+        return sections;
+    }
+}
+exports.AgentsExporter = AgentsExporter;
+exports.default = AgentsExporter;

package/dist/src/analytics-log.js

@@ -0,0 +1,161 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_1 = require("./logger");
+const logger = (0, logger_1.getLogger)('analytics-log');
+const ANALYTICS_SCHEMA_VERSION = 1;
+/**
+ * Append-only analytics log for orchestrator runs
+ * Persists to runs/analytics.json
+ */
+class AnalyticsLog {
+    logPath;
+    constructor(runsDir = 'runs') {
+        this.logPath = path.join(runsDir, 'analytics.json');
+    }
+    /**
+     * Append a run to the analytics log
+     */
+    appendRun(metrics) {
+        const entry = {
+            schemaVersion: ANALYTICS_SCHEMA_VERSION,
+            timestamp: new Date().toISOString(),
+            metrics
+        };
+        let entries = [];
+        if (fs.existsSync(this.logPath)) {
+            try {
+                const content = fs.readFileSync(this.logPath, 'utf8');
+                entries = JSON.parse(content);
+                // Validate schema
+                if (!Array.isArray(entries)) {
+                    logger.warn('Analytics log is not an array, resetting');
+                    entries = [];
+                }
+            }
+            catch (error) {
+                logger.warn('Failed to parse analytics log, resetting:', error instanceof Error ? error.message : error);
+                entries = [];
+            }
+        }
+        entries.push(entry);
+        // Ensure directory exists
+        const dir = path.dirname(this.logPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // Write atomically via temp file
+        const tmpPath = this.logPath + '.tmp';
+        fs.writeFileSync(tmpPath, JSON.stringify(entries, null, 2), 'utf8');
+        fs.renameSync(tmpPath, this.logPath);
+    }
+    /**
+     * Get recent runs (default: last 10)
+     */
+    getRecentRuns(count = 10) {
+        if (!fs.existsSync(this.logPath)) {
+            return [];
+        }
+        try {
+            const content = fs.readFileSync(this.logPath, 'utf8');
+            const entries = JSON.parse(content);
+            if (!Array.isArray(entries)) {
+                return [];
+            }
+            // Return most recent entries
+            return entries.slice(-count).reverse();
+        }
+        catch (error) {
+            logger.warn('Failed to read analytics log:', error instanceof Error ? error.message : error);
+            return [];
+        }
+    }
+    /**
+     * Get all runs
+     */
+    getAllRuns() {
+        if (!fs.existsSync(this.logPath)) {
+            return [];
+        }
+        try {
+            const content = fs.readFileSync(this.logPath, 'utf8');
+            const entries = JSON.parse(content);
+            if (!Array.isArray(entries)) {
+                return [];
+            }
+            return entries;
+        }
+        catch (error) {
+            logger.warn('Failed to read analytics log:', error instanceof Error ? error.message : error);
+            return [];
+        }
+    }
+    /**
+     * Compare current run with historical average
+     */
+    compareWithHistory(currentMetrics, historyCount = 5) {
+        const recent = this.getRecentRuns(historyCount + 1); // +1 to exclude current if already logged
+        // Filter out current run if it's already in the log
+        const historical = recent.filter(e => e.metrics.executionId !== currentMetrics.executionId);
+        if (historical.length === 0) {
+            return null; // No history to compare
+        }
+        // Calculate averages
+        const avgTime = historical.reduce((sum, e) => sum + e.metrics.totalTimeMs, 0) / historical.length;
+        const avgCommits = historical.reduce((sum, e) => sum + e.metrics.commitCount, 0) / historical.length;
+        const avgPassRate = historical.reduce((sum, e) => {
+            const total = e.metrics.verificationsPassed + e.metrics.verificationsFailed;
+            return sum + (total > 0 ? e.metrics.verificationsPassed / total : 0);
+        }, 0) / historical.length;
+        const currentTotal = currentMetrics.verificationsPassed + currentMetrics.verificationsFailed;
+        const currentPassRate = currentTotal > 0 ? currentMetrics.verificationsPassed / currentTotal : 0;
+        return {
+            current: currentMetrics,
+            averageHistorical: {
+                totalTimeMs: avgTime,
+                commitCount: avgCommits,
+                verificationPassRate: avgPassRate
+            },
+            delta: {
+                timePercent: avgTime > 0 ? ((currentMetrics.totalTimeMs - avgTime) / avgTime) * 100 : 0,
+                commitCountDiff: currentMetrics.commitCount - avgCommits,
+                passRateDiff: currentPassRate - avgPassRate
+            }
+        };
+    }
+}
+exports.default = AnalyticsLog;

package/dist/src/baseline-scanner.js

@@ -0,0 +1,65 @@
+"use strict";
+// Scans a git repo before execution to capture existing files.
+// Feeds into shared instructions so agents know what not to break.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanBaseline = scanBaseline;
+exports.formatPreservationRules = formatPreservationRules;
+const child_process_1 = require("child_process");
+const TEST_PATTERN = /(?:^|\/)(?:test|tests|__tests__|spec)\/|\.(?:test|spec)\.\w+$/i;
+// Vendored dependency directories whose test files are irrelevant to the project
+const VENDORED_DIRS = /^(?:node_modules|venv|\.venv|env|\.env|\.tox|__pypackages__|bower_components|\.bundle)\//i;
+const SITE_PACKAGES = /\/site-packages\//;
+/**
+ * Run `git ls-files` and split results into test vs non-test.
+ * Returns empty lists if the directory isn't a git repo or has no commits.
+ */
+function scanBaseline(workingDir) {
+    let output;
+    try {
+        output = (0, child_process_1.execSync)('git ls-files', {
+            cwd: workingDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+    }
+    catch {
+        return { allFiles: [], testFiles: [], headCommit: '' };
+    }
+    // Capture HEAD so quality gates can scope checks to agent-changed files
+    let headCommit = '';
+    try {
+        headCommit = (0, child_process_1.execSync)('git rev-parse HEAD', {
+            cwd: workingDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+    }
+    catch { /* empty repo with no commits yet */ }
+    if (!output)
+        return { allFiles: [], testFiles: [], headCommit };
+    const allFiles = output.split('\n').filter(f => f.length > 0);
+    const testFiles = allFiles.filter(f => TEST_PATTERN.test(f) && !VENDORED_DIRS.test(f) && !SITE_PACKAGES.test(f));
+    return { allFiles, testFiles, headCommit };
+}
+/**
+ * Build preservation rules for .copilot-instructions.md.
+ * Lists existing test files and tells agents not to break them.
+ */
+function formatPreservationRules(snapshot) {
+    if (snapshot.allFiles.length === 0)
+        return '';
+    const lines = [
+        '## Pre-existing Code',
+        `This repository has ${snapshot.allFiles.length} existing file(s).`,
+        '- Do NOT modify or delete files outside your assigned scope.',
+        '- Do NOT break existing tests. If they fail after your changes, fix the regression before finishing.',
+        '- When modifying shared files (e.g., package.json), make only the changes your task requires.',
+        '- Run the existing test suite after your changes to confirm nothing is broken.',
+        '',
+    ];
+    if (snapshot.testFiles.length > 0) {
+        lines.push('### Protected Test Files');
+        lines.push('These tests must continue to pass:');
+        for (const f of snapshot.testFiles) {
+            lines.push(`- ${f}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}