swarm-orchestrator 7.0.0-alpha.0

package/dist/src/knowledge-base.js

@@ -0,0 +1,300 @@
+"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 });
+exports.KnowledgeBaseManager = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const text_similarity_1 = require("./text-similarity");
+const logger_1 = require("./logger");
+const logger = (0, logger_1.getLogger)('knowledge-base');
+// Auto-prune triggers when pattern count exceeds this threshold
+const MAX_PATTERNS = 500;
+/**
+ * knowledge base for learning from execution patterns
+ * stores insights from reviewer-role analysis
+ */
+class KnowledgeBaseManager {
+    knowledgeBasePath;
+    knowledgeBase;
+    constructor(workingDir) {
+        const baseDir = workingDir || process.cwd();
+        this.knowledgeBasePath = path.join(baseDir, 'knowledge-base.json');
+        this.knowledgeBase = this.loadKnowledgeBase();
+    }
+    /**
+     * load knowledge base from disk or create new
+     */
+    loadKnowledgeBase() {
+        if (fs.existsSync(this.knowledgeBasePath)) {
+            try {
+                const content = fs.readFileSync(this.knowledgeBasePath, 'utf8');
+                return JSON.parse(content);
+            }
+            catch (error) {
+                logger.warn(`Failed to load knowledge base, creating new: ${error}`);
+            }
+        }
+        return {
+            version: 1,
+            lastUpdated: new Date().toISOString(),
+            patterns: [],
+            statistics: {
+                totalRuns: 0,
+                totalPatterns: 0,
+                avgPatternsPerRun: 0
+            }
+        };
+    }
+    /**
+     * save knowledge base to disk
+     */
+    saveKnowledgeBase() {
+        try {
+            fs.writeFileSync(this.knowledgeBasePath, JSON.stringify(this.knowledgeBase, null, 2), 'utf8');
+        }
+        catch (error) {
+            logger.error(`Failed to save knowledge base: ${error}`);
+        }
+    }
+    /**
+     * add or update pattern in knowledge base.
+     * Auto-prunes when pattern count exceeds MAX_PATTERNS to bound
+     * Levenshtein search cost and disk footprint.
+     */
+    addOrUpdatePattern(pattern) {
+        const now = new Date().toISOString();
+        // check if similar pattern exists
+        const existing = this.knowledgeBase.patterns.find(p => p.category === pattern.category &&
+            this.isSimilarInsight(p.insight, pattern.insight));
+        if (existing) {
+            // update existing pattern
+            existing.occurrences++;
+            existing.lastSeen = now;
+            existing.confidence = pattern.confidence;
+            existing.evidence.push(...pattern.evidence);
+            existing.impact = pattern.impact;
+        }
+        else {
+            // create new pattern
+            const newPattern = {
+                id: this.generatePatternId(pattern.category),
+                category: pattern.category,
+                insight: pattern.insight,
+                confidence: pattern.confidence,
+                evidence: pattern.evidence,
+                occurrences: 1,
+                firstSeen: now,
+                lastSeen: now,
+                impact: pattern.impact,
+                examples: []
+            };
+            this.knowledgeBase.patterns.push(newPattern);
+        }
+        // Prevent unbounded growth: prune stale and low-value entries
+        if (this.knowledgeBase.patterns.length > MAX_PATTERNS) {
+            this.prunePatterns({ removeOlderThan: 90, removeLowConfidence: true });
+        }
+        this.knowledgeBase.lastUpdated = now;
+        this.knowledgeBase.statistics.totalPatterns = this.knowledgeBase.patterns.length;
+        this.saveKnowledgeBase();
+    }
+    /**
+     * Record a recipe execution for historical tracking.
+     * Stores structured run data so future recipe invocations can reference
+     * success rates and typical durations.
+     */
+    recordRecipeRun(data) {
+        const status = data.passed ? 'passed' : 'failed';
+        const completionRatio = `${data.stepsCompleted}/${data.totalSteps}`;
+        this.addOrUpdatePattern({
+            category: 'recipe_run',
+            insight: `recipe:${data.recipe} tool:${data.tool} ${status} (${completionRatio} steps, ${data.duration}ms)`,
+            confidence: 'high',
+            evidence: [
+                `recipe:${data.recipe}`,
+                `tool:${data.tool}`,
+                `passed:${data.passed}`,
+                `duration:${data.duration}`,
+                `completed:${completionRatio}`,
+                `params:${JSON.stringify(data.parameters)}`,
+            ],
+            impact: data.passed ? 'low' : 'medium',
+        });
+    }
+    /**
+     * get patterns by category
+     */
+    getPatternsByCategory(category) {
+        return this.knowledgeBase.patterns.filter(p => p.category === category);
+    }
+    /**
+     * get high-confidence patterns
+     */
+    getHighConfidencePatterns() {
+        return this.knowledgeBase.patterns.filter(p => p.confidence === 'high');
+    }
+    /**
+     * get patterns that should influence planning
+     */
+    getPlanningRelevantPatterns() {
+        return this.knowledgeBase.patterns.filter(p => (p.category === 'dependency_order' || p.category === 'best_practice') &&
+            p.confidence !== 'low' &&
+            p.occurrences >= 2);
+    }
+    /**
+     * get anti-patterns to warn about
+     */
+    getAntiPatterns() {
+        return this.knowledgeBase.patterns.filter(p => p.category === 'anti_pattern' && p.impact !== 'low');
+    }
+    /**
+     * record execution run
+     */
+    recordRun(_patternsDetected) {
+        this.knowledgeBase.statistics.totalRuns++;
+        const { totalRuns, totalPatterns } = this.knowledgeBase.statistics;
+        this.knowledgeBase.statistics.avgPatternsPerRun = totalPatterns / totalRuns;
+        this.knowledgeBase.lastUpdated = new Date().toISOString();
+        this.saveKnowledgeBase();
+    }
+    /**
+     * get summary statistics
+     */
+    getStatistics() {
+        return { ...this.knowledgeBase.statistics };
+    }
+    /**
+     * export knowledge base for review
+     */
+    export() {
+        return JSON.parse(JSON.stringify(this.knowledgeBase));
+    }
+    /**
+     * clear old or low-value patterns
+     */
+    prunePatterns(options) {
+        const now = new Date();
+        let removed = 0;
+        this.knowledgeBase.patterns = this.knowledgeBase.patterns.filter(pattern => {
+            if (options?.removeOlderThan) {
+                const lastSeenDate = new Date(pattern.lastSeen);
+                const daysSinceLastSeen = (now.getTime() - lastSeenDate.getTime()) / (1000 * 60 * 60 * 24);
+                if (daysSinceLastSeen > options.removeOlderThan) {
+                    removed++;
+                    return false;
+                }
+            }
+            if (options?.removeLowConfidence && pattern.confidence === 'low') {
+                removed++;
+                return false;
+            }
+            if (options?.removeRare && pattern.occurrences < 2) {
+                removed++;
+                return false;
+            }
+            return true;
+        });
+        if (removed > 0) {
+            this.knowledgeBase.statistics.totalPatterns = this.knowledgeBase.patterns.length;
+            this.saveKnowledgeBase();
+        }
+        return removed;
+    }
+    /**
+     * check if two insights are similar (simple string similarity)
+     */
+    isSimilarInsight(insight1, insight2) {
+        const normalize = (s) => s.toLowerCase().replace(/[^\w\s]/g, '').trim();
+        const n1 = normalize(insight1);
+        const n2 = normalize(insight2);
+        // exact match
+        if (n1 === n2)
+            return true;
+        // high overlap (simple check)
+        const words1 = new Set(n1.split(/\s+/));
+        const words2 = new Set(n2.split(/\s+/));
+        const intersection = new Set([...words1].filter(w => words2.has(w)));
+        const union = new Set([...words1, ...words2]);
+        const similarity = intersection.size / union.size;
+        return similarity > 0.7;
+    }
+    /**
+     * generate unique pattern ID
+     */
+    generatePatternId(category) {
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 8);
+        return `${category}-${timestamp}-${random}`;
+    }
+    /**
+     * Delegates to the shared levenshtein from text-similarity.ts.
+     * Kept as a public method for backward compatibility with tests.
+     */
+    levenshtein(a, b) {
+        return (0, text_similarity_1.levenshtein)(a, b);
+    }
+    /**
+     * Find stored patterns similar to a task description.
+     * Uses keyword overlap + normalized Levenshtein similarity.
+     * Skips patterns where length difference exceeds 2x (Levenshtein
+     * similarity cannot reach the threshold in those cases).
+     */
+    findSimilarTasks(description, threshold = 0.7) {
+        const descLower = description.toLowerCase();
+        const descWords = new Set(descLower.split(/\s+/));
+        const descLen = descLower.length;
+        return this.knowledgeBase.patterns.filter(p => {
+            const insightLower = p.insight.toLowerCase();
+            // Length pre-filter: when one string is more than 2x the other,
+            // the normalized Levenshtein similarity is at most 0.5, so the
+            // combined score (keyword + lev) / 2 cannot reach 0.7 threshold
+            // unless keyword overlap is near-perfect. Skip the O(n*m) call.
+            const insightLen = insightLower.length;
+            const shorter = Math.min(descLen, insightLen);
+            const longer = Math.max(descLen, insightLen);
+            if (shorter > 0 && longer / shorter > 2)
+                return false;
+            const insightWords = new Set(insightLower.split(/\s+/));
+            const overlap = [...descWords].filter(w => insightWords.has(w)).length;
+            const union = new Set([...descWords, ...insightWords]).size;
+            const keywordSim = union > 0 ? overlap / union : 0;
+            const maxLen = longer || 1;
+            const levSim = 1 - (0, text_similarity_1.levenshtein)(descLower, insightLower) / maxLen;
+            const combined = (keywordSim + levSim) / 2;
+            return combined >= threshold;
+        });
+    }
+}
+exports.KnowledgeBaseManager = KnowledgeBaseManager;

package/dist/src/logger.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureLogger = configureLogger;
+exports.setPrettyMode = setPrettyMode;
+exports.isPrettyMode = isPrettyMode;
+exports.getLogger = getLogger;
+exports.getLoggerConfig = getLoggerConfig;
+exports.isJsonOutput = isJsonOutput;
+exports.writeStructuredOutput = writeStructuredOutput;
+const LEVEL_RANK = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    debug: 3,
+    trace: 4,
+};
+const state = {
+    level: 'info',
+    outputFormat: 'text',
+    diagnosticsToStderr: false,
+    // Pretty mode: hide `[scope]` prefixes for a cleaner CLI UX.
+    // Auto-enabled by user-facing commands. Scope still shown in JSON output.
+    prettyMode: false,
+};
+function normalizeArgs(args) {
+    return args.map((arg) => {
+        if (typeof arg === 'string')
+            return arg;
+        if (arg instanceof Error)
+            return arg.stack || arg.message;
+        try {
+            return JSON.stringify(arg);
+        }
+        catch {
+            return String(arg);
+        }
+    }).join(' ');
+}
+function shouldLog(level) {
+    if (state.level === 'silent')
+        return false;
+    return LEVEL_RANK[level] <= LEVEL_RANK[state.level];
+}
+function writeLine(stream, line) {
+    stream.write(line + '\n');
+}
+function emit(level, scope, args) {
+    if (!shouldLog(level))
+        return;
+    const message = normalizeArgs(args);
+    if (state.outputFormat === 'json') {
+        writeLine(process.stderr, JSON.stringify({
+            timestamp: new Date().toISOString(),
+            level,
+            ...(scope ? { scope } : {}),
+            message,
+        }));
+        return;
+    }
+    const prefix = (!state.prettyMode && scope) ? `[${scope}] ` : '';
+    // Diagnostic levels (info/debug/trace) go to stderr when explicitly routed there
+    // so the presenter owns stdout cleanly. Error/warn always to stderr.
+    const isDiagnostic = level === 'info' || level === 'debug' || level === 'trace';
+    const stream = level === 'error' || level === 'warn'
+        ? process.stderr
+        : (state.diagnosticsToStderr && isDiagnostic ? process.stderr : process.stdout);
+    writeLine(stream, `${prefix}${message}`);
+}
+function createLogger(scope) {
+    return {
+        error: (...args) => emit('error', scope, args),
+        warn: (...args) => emit('warn', scope, args),
+        info: (...args) => emit('info', scope, args),
+        debug: (...args) => emit('debug', scope, args),
+        trace: (...args) => emit('trace', scope, args),
+        child: (childScope) => createLogger(scope ? `${scope}:${childScope}` : childScope),
+    };
+}
+function configureLogger(config) {
+    if (config.level)
+        state.level = config.level;
+    if (config.outputFormat)
+        state.outputFormat = config.outputFormat;
+    if (config.diagnosticsToStderr !== undefined)
+        state.diagnosticsToStderr = config.diagnosticsToStderr;
+}
+/**
+ * Hide `[scope]` prefixes for a cleaner user-facing CLI UX.
+ * Auto-enabled by user-facing commands; structured JSON output is unaffected.
+ */
+function setPrettyMode(pretty) {
+    state.prettyMode = pretty;
+}
+function isPrettyMode() {
+    return state.prettyMode;
+}
+function getLogger(scope) {
+    return createLogger(scope);
+}
+function getLoggerConfig() {
+    return { ...state };
+}
+function isJsonOutput() {
+    return state.outputFormat === 'json';
+}
+function writeStructuredOutput(payload) {
+    const content = typeof payload === 'string'
+        ? payload
+        : JSON.stringify(payload, null, 2);
+    process.stdout.write(content + '\n');
+}

package/dist/src/meta-analyzer.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetaAnalyzer = void 0;
+/**
+ * meta-analysis engine - reviews execution quality and decides on replanning
+ */
+class MetaAnalyzer {
+    /**
+     * analyze wave results and determine if replanning needed
+     */
+    analyzeWave(waveIndex, waveSteps, results, plan, executionId) {
+        const waveResults = results.filter(r => waveSteps.includes(r.stepNumber));
+        const stepReviews = waveResults.map(result => {
+            return this.reviewStep(result);
+        });
+        const detectedPatterns = this.detectPatterns(waveResults);
+        const failureRate = stepReviews.filter(r => !r.verificationPassed).length / stepReviews.length;
+        let overallHealth = 'healthy';
+        if (failureRate > 0.5) {
+            overallHealth = 'critical';
+        }
+        else if (failureRate > 0.2) {
+            overallHealth = 'degraded';
+        }
+        const replanNeeded = failureRate > 0.5;
+        const replanReason = replanNeeded
+            ? `Wave ${waveIndex + 1} failed: ${Math.round(failureRate * 100)}% of steps did not pass verification`
+            : null;
+        const suggestedChanges = this.generateSuggestedChanges(stepReviews, plan);
+        const knowledgeUpdates = this.extractKnowledge(stepReviews, detectedPatterns);
+        const nextActions = this.determineNextActions(overallHealth, replanNeeded, suggestedChanges);
+        return {
+            analysisTimestamp: new Date().toISOString(),
+            executionId,
+            waveAnalyzed: waveIndex + 1,
+            overallHealth,
+            stepReviews,
+            detectedPatterns,
+            replanNeeded,
+            replanReason,
+            suggestedChanges,
+            knowledgeUpdates,
+            nextActions
+        };
+    }
+    /**
+     * review individual step result
+     */
+    reviewStep(result) {
+        const verificationPassed = result.verificationResult?.passed ?? false;
+        const issues = [];
+        let rootCause = 'Unknown';
+        let recommendation = 'Continue';
+        if (!verificationPassed && result.verificationResult) {
+            // analyze verification failures
+            result.verificationResult.checks.forEach(check => {
+                if (!check.passed && check.required) {
+                    issues.push(`${check.type}: ${check.description} - ${check.reason || 'failed'}`);
+                }
+            });
+            if (result.verificationResult.unverifiedClaims.length > 0) {
+                issues.push(`Unverified claims: ${result.verificationResult.unverifiedClaims.length} detected`);
+            }
+            // determine root cause
+            if (issues.some(i => i.includes('test'))) {
+                rootCause = 'Tests not executed or failed';
+                recommendation = 'Re-execute with explicit test requirement';
+            }
+            else if (issues.some(i => i.includes('build'))) {
+                rootCause = 'Build not executed or failed';
+                recommendation = 'Re-execute with build verification';
+            }
+            else if (issues.some(i => i.includes('commit'))) {
+                rootCause = 'No commits made';
+                recommendation = 'Re-execute with commit requirement';
+            }
+            else {
+                rootCause = 'Verification checks failed';
+                recommendation = 'Review transcript and re-execute';
+            }
+        }
+        return {
+            stepNumber: result.stepNumber,
+            agentName: result.agentName,
+            verificationPassed,
+            issues,
+            rootCause,
+            recommendation
+        };
+    }
+    /**
+     * detect patterns across multiple steps
+     */
+    detectPatterns(results) {
+        const patterns = [];
+        // check for generic commit messages (anti-pattern)
+        const genericCommitAgents = results.filter(r => {
+            const commits = r.verificationResult?.checks.find(c => c.type === 'commit');
+            if (!commits?.evidence)
+                return false;
+            return /update|fix|change/i.test(commits.evidence) && commits.evidence.length < 30;
+        });
+        if (genericCommitAgents.length >= 2) {
+            patterns.push({
+                type: 'anti-pattern',
+                pattern: 'generic_commit_messages',
+                occurrences: genericCommitAgents.length,
+                affectedAgents: genericCommitAgents.map(r => r.agentName),
+                example: 'Commits like "update files" or "fix issues"',
+                severity: 'medium'
+            });
+        }
+        // check for unverified claims (drift)
+        const driftingAgents = results.filter(r => {
+            return (r.verificationResult?.unverifiedClaims.length || 0) > 2;
+        });
+        if (driftingAgents.length >= 1) {
+            patterns.push({
+                type: 'context-gap',
+                pattern: 'unverified_claims',
+                occurrences: driftingAgents.length,
+                affectedAgents: driftingAgents.map(r => r.agentName),
+                example: 'Agent claims work done without evidence in transcript',
+                severity: 'high'
+            });
+        }
+        return patterns;
+    }
+    /**
+     * generate suggested changes based on review
+     */
+    generateSuggestedChanges(stepReviews, _plan) {
+        const changes = [];
+        stepReviews.forEach(review => {
+            if (!review.verificationPassed) {
+                changes.push({
+                    type: 're-execute',
+                    targetStep: review.stepNumber,
+                    reason: review.rootCause,
+                    details: review.recommendation
+                });
+            }
+        });
+        return changes;
+    }
+    /**
+     * extract knowledge from analysis
+     */
+    extractKnowledge(stepReviews, patterns) {
+        const updates = [];
+        // extract from patterns
+        patterns.forEach(pattern => {
+            if (pattern.severity === 'high') {
+                updates.push({
+                    category: pattern.type === 'anti-pattern' ? 'anti_pattern' : 'agent_behavior',
+                    insight: `Pattern detected: ${pattern.pattern} in ${pattern.occurrences} step(s)`,
+                    confidence: 'high',
+                    evidence: pattern.example
+                });
+            }
+        });
+        return updates;
+    }
+    /**
+     * determine next actions
+     */
+    determineNextActions(health, replanNeeded, changes) {
+        const actions = [];
+        if (replanNeeded) {
+            actions.push('Trigger full replan');
+            actions.push('Preserve git history from completed steps');
+        }
+        else if (health === 'degraded') {
+            if (changes.length > 0) {
+                actions.push(`Re-execute ${changes.length} failed step(s)`);
+            }
+            actions.push('Monitor next wave closely');
+        }
+        else {
+            actions.push('Continue to next wave');
+        }
+        return actions;
+    }
+    /**
+     * make replan decision based on analysis
+     */
+    makeReplanDecision(analysis, _plan, _completedSteps) {
+        if (!analysis.replanNeeded) {
+            return {
+                shouldReplan: false,
+                reason: 'Execution healthy, continue as planned',
+                preserveHistory: true
+            };
+        }
+        // identify which steps to retry
+        const stepsToRetry = analysis.suggestedChanges
+            .filter(c => c.type === 're-execute')
+            .map(c => c.targetStep)
+            .filter(s => s !== undefined);
+        return {
+            shouldReplan: true,
+            reason: analysis.replanReason || 'Critical issues detected',
+            stepsToRetry,
+            preserveHistory: true
+        };
+    }
+}
+exports.MetaAnalyzer = MetaAnalyzer;