@yasserkhanorg/e2e-agents 1.8.4 → 1.9.5

package/dist/esm/crew/orchestrator.js

@@ -6,6 +6,8 @@
 import { getChangedFiles, isTestFile } from '../agent/git.js';
 import { preprocess } from '../pipeline/stage0_preprocess.js';
 import { logger } from '../logger.js';
+import { BudgetExceededError } from '../base_provider.js';
+import { BudgetLedger } from '../budget_ledger.js';
 import { createEmptyUsageStats, mergeUsageStats } from './context.js';
 import { WORKFLOWS } from './workflows.js';
 export class CrewOrchestrator {
@@ -15,10 +17,61 @@ export class CrewOrchestrator {
     registerAgent(agent) {
         this.agents.set(agent.role, agent);
     }
+    /**
+     * Load and register plugins from file paths.
+     * Each module must default-export an object satisfying AgentPlugin.
+     */
+    async loadPlugins(pluginPaths) {
+        const loaded = [];
+        for (const pluginPath of pluginPaths) {
+            try {
+                // Security: Only allow relative paths (starting with . or ..) to prevent loading arbitrary modules.
+                // Absolute paths, URLs, and node_modules references are rejected.
+                if (!pluginPath.startsWith('.')) {
+                    logger.warn(`Plugin path must be relative (start with ./): ${pluginPath} — skipped`);
+                    continue;
+                }
+                const resolved = new URL(pluginPath, `file://${process.cwd()}/`).href;
+                // Security: reject paths that resolve outside the workspace (e.g., ../../etc/evil.js)
+                const cwd = `file://${process.cwd()}/`;
+                if (!resolved.startsWith(cwd)) {
+                    logger.warn(`Plugin path '${pluginPath}' resolves outside workspace — skipped`);
+                    continue;
+                }
+                const mod = await import(resolved);
+                const plugin = mod.default || mod;
+                if (!plugin.role || typeof plugin.execute !== 'function') {
+                    logger.warn(`Plugin at ${pluginPath} missing required role/execute — skipped`);
+                    continue;
+                }
+                // Warn if plugin overrides a built-in agent
+                if (this.agents.has(plugin.role)) {
+                    logger.warn(`Plugin '${plugin.role}' overrides built-in agent — ensure this is intentional`);
+                }
+                this.agents.set(plugin.role, plugin);
+                loaded.push(plugin.role);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                logger.warn(`Failed to load plugin ${pluginPath}: ${msg}`);
+            }
+        }
+        return loaded;
+    }
     async run(config) {
         const workflow = WORKFLOWS[config.workflow || 'full-qa'];
         const timings = {};
         const warnings = [];
+        // Load plugins if configured, then inject them into workflow phases
+        const pluginRoles = [];
+        if (config.plugins && config.plugins.length > 0) {
+            const loaded = await this.loadPlugins(config.plugins);
+            pluginRoles.push(...loaded);
+            if (loaded.length > 0) {
+                logger.info(`Loaded ${loaded.length} plugins: ${loaded.join(', ')}`);
+            }
+        }
+        const effectivePhases = this.injectPluginsIntoPhases(workflow.phases, pluginRoles);
         // Step 1: Get changed files
         const gitResult = getChangedFiles(config.appPath, config.gitSince, {
             includeUncommitted: config.gitIncludeUncommitted,
@@ -32,6 +85,8 @@ export class CrewOrchestrator {
         if (changedFiles.length === 0) {
             warnings.push('No changed application files detected.');
         }
+        // Create shared budget ledger for aggregate cost tracking across all agents
+        const budgetLedger = config.budgetUSD ? new BudgetLedger(config.budgetUSD) : undefined;
         // Initialize context (will be populated during preprocess phase)
         const ctx = {
             changedFiles,
@@ -46,6 +101,8 @@ export class CrewOrchestrator {
             testsRoot: config.testsRoot,
             gitSince: config.gitSince,
             providerOverride: config.providerOverride,
+            budgetUSD: config.budgetUSD,
+            budgetLedger,
             impactedFlows: [],
             strategyEntries: [],
             testDesigns: [],
@@ -54,14 +111,21 @@ export class CrewOrchestrator {
             findings: [],
             generatedSpecs: [],
             usage: createEmptyUsageStats(),
+            agentUsage: [],
             messages: [],
             warnings,
         };
         // Execute each phase
-        for (const phase of workflow.phases) {
+        for (const phase of effectivePhases) {
             const timer = logger.timer(`crew:${phase.name}`);
             if (phase.handler === 'built-in') {
                 await this.runBuiltInPhase(phase.name, ctx, config);
+                // Dry-run: after preprocess, return summary without running agents
+                if (config.dryRun && phase.name === 'preprocess') {
+                    timings[phase.name] = timer.end();
+                    ctx.warnings.push('Dry run — no LLM calls were made.');
+                    return { context: ctx, warnings, timings, dryRun: true };
+                }
             }
             else if (phase.parallel && phase.parallel.length > 0) {
                 await this.runParallel(phase.parallel, phase.name, ctx);
@@ -73,9 +137,10 @@ export class CrewOrchestrator {
                 warnings.push(`Phase '${phase.name}' has no handler, parallel, or sequential agents — skipped.`);
             }
             timings[phase.name] = timer.end();
-            // Budget check
-            if (config.budgetUSD && ctx.usage.totalCost >= config.budgetUSD) {
-                warnings.push(`Budget limit reached ($${ctx.usage.totalCost.toFixed(4)} >= $${config.budgetUSD}). Stopping workflow.`);
+            // Budget check — prefer ledger (aggregate across all providers) over ctx.usage
+            const currentCost = budgetLedger ? budgetLedger.totalCost : ctx.usage.totalCost;
+            if (config.budgetUSD && currentCost >= config.budgetUSD) {
+                warnings.push(`Budget limit reached ($${currentCost.toFixed(4)} >= $${config.budgetUSD}). Stopping workflow.`);
                 break;
             }
         }
@@ -92,10 +157,19 @@ export class CrewOrchestrator {
             };
         }
         const task = { role, action, input: null };
+        const startMs = Date.now();
         try {
             const result = await agent.execute(task, ctx);
+            const durationMs = Date.now() - startMs;
             if (result.usage) {
                 mergeUsageStats(ctx.usage, result.usage);
+                ctx.agentUsage.push({
+                    agent: role,
+                    inputTokens: result.usage.totalInputTokens,
+                    outputTokens: result.usage.totalOutputTokens,
+                    cost: result.usage.totalCost,
+                    durationMs,
+                });
             }
             if (result.warnings && result.warnings.length > 0) {
                 ctx.warnings.push(...result.warnings);
@@ -103,6 +177,10 @@ export class CrewOrchestrator {
             return result;
         }
         catch (error) {
+            if (error instanceof BudgetExceededError) {
+                ctx.warnings.push(`Budget exceeded ($${error.currentCost.toFixed(4)} >= $${error.budgetUSD}). Agent '${role}' skipped.`);
+                return { role, status: 'failed', output: null, warnings: [error.message] };
+            }
             const message = error instanceof Error ? error.message : String(error);
             ctx.warnings.push(`Agent '${role}' failed: ${message}`);
             return { role, status: 'failed', output: null, warnings: [message] };
@@ -158,6 +236,86 @@ export class CrewOrchestrator {
         }
         this.checkPhaseResults(phaseName, results, ctx);
     }
+    /**
+     * Inject loaded plugins into workflow phases based on their `phase` and `runAfter` fields.
+     * Plugins with `runAfter` dependencies are appended to the sequential list of the matching phase;
+     * plugins without `runAfter` are appended to the parallel list.
+     * Returns a new array of phases (does not mutate the original workflow definition).
+     */
+    injectPluginsIntoPhases(phases, pluginRoles) {
+        if (pluginRoles.length === 0)
+            return phases;
+        // Build mutable copies keyed by phase name
+        const phaseMap = new Map();
+        const ordered = [];
+        for (const p of phases) {
+            ordered.push(p.name);
+            if (p.handler === 'built-in') {
+                phaseMap.set(p.name, { handler: 'built-in' });
+            }
+            else if (p.parallel) {
+                phaseMap.set(p.name, { parallel: [...p.parallel] });
+            }
+            else if (p.sequential) {
+                phaseMap.set(p.name, { sequential: [...p.sequential] });
+            }
+        }
+        for (const role of pluginRoles) {
+            const agent = this.agents.get(role);
+            if (!agent)
+                continue;
+            const plugin = agent;
+            if (!plugin.phase)
+                continue;
+            const target = phaseMap.get(plugin.phase);
+            if (!target) {
+                logger.warn(`Plugin '${role}' targets phase '${plugin.phase}' which does not exist in workflow — skipped`);
+                continue;
+            }
+            if (target.handler === 'built-in') {
+                logger.warn(`Plugin '${role}' targets built-in phase '${plugin.phase}' — not supported, skipped`);
+                continue;
+            }
+            const pluginRole = role;
+            if (plugin.runAfter && plugin.runAfter.length > 0) {
+                // Validate that runAfter dependencies are either in this phase or a prior phase
+                const phaseRoles = target.parallel || target.sequential || [];
+                const missingDeps = plugin.runAfter.filter((dep) => !phaseRoles.includes(dep) && !this.agents.has(dep));
+                if (missingDeps.length > 0) {
+                    logger.warn(`Plugin '${role}' has unresolved runAfter deps [${missingDeps.join(', ')}] — injecting anyway`);
+                }
+                // Plugin has dependencies — must run sequentially
+                if (target.sequential) {
+                    target.sequential.push(pluginRole);
+                }
+                else if (target.parallel) {
+                    // Convert to sequential to respect dependency ordering
+                    target.sequential = [...target.parallel, pluginRole];
+                    delete target.parallel;
+                }
+            }
+            else {
+                if (target.parallel) {
+                    target.parallel.push(pluginRole);
+                }
+                else if (target.sequential) {
+                    target.sequential.push(pluginRole);
+                }
+            }
+            logger.info(`Plugin '${role}' injected into phase '${plugin.phase}'`);
+        }
+        // Rebuild WorkflowPhase array
+        return ordered.map((name) => {
+            const entry = phaseMap.get(name);
+            if (entry.handler === 'built-in')
+                return { name, handler: 'built-in' };
+            if (entry.parallel)
+                return { name, parallel: entry.parallel };
+            if (entry.sequential)
+                return { name, sequential: entry.sequential };
+            throw new Error(`Phase '${name}' has no handler, parallel, or sequential agents after plugin injection`);
+        });
+    }
     checkPhaseResults(phaseName, results, ctx) {
         const allFailed = results.length > 0 && results.every((r) => r.status === 'failed');
         if (allFailed) {

package/dist/esm/crew/provider.js

@@ -5,9 +5,29 @@
  * instantiation and prevents usage stats fragmentation.
  */
 import { LLMProviderFactory } from '../provider_factory.js';
-export async function getCrewProvider(providerOverride) {
-    if (providerOverride) {
-        return LLMProviderFactory.createFromString(providerOverride);
+import { BaseProvider } from '../base_provider.js';
+import { ModelRouter } from '../model_router.js';
+export async function getCrewProvider(providerOverride, budgetUSD, opts) {
+    let effectiveOverride = providerOverride;
+    // Apply model routing if configured and agent role is provided
+    if (opts?.agentRole && opts?.modelRoutingProviderType) {
+        const router = new ModelRouter(opts.modelRoutingProviderType, opts.modelRoutingOverrides);
+        const model = router.getModel(opts.agentRole);
+        if (model) {
+            // Override uses provider:model format (e.g., "anthropic:claude-haiku-4-5-20251001")
+            effectiveOverride = `${opts.modelRoutingProviderType}:${model}`;
+        }
     }
-    return LLMProviderFactory.createFromEnv();
+    const provider = effectiveOverride
+        ? await LLMProviderFactory.createFromString(effectiveOverride)
+        : await LLMProviderFactory.createFromEnv();
+    if (provider instanceof BaseProvider) {
+        if (opts?.budgetLedger) {
+            provider.setBudgetLedger(opts.budgetLedger);
+        }
+        else if (budgetUSD !== undefined) {
+            provider.setBudget(budgetUSD);
+        }
+    }
+    return provider;
 }

package/dist/esm/custom_provider.js

@@ -65,6 +65,7 @@ export class CustomProvider extends BaseProvider {
         };
     }
     async generateText(prompt, options) {
+        this.checkBudget();
         const startTime = Date.now();
         try {
             if (prompt.length > 10 * 1024 * 1024) {

package/dist/esm/engine/diff_loader.js

@@ -1,20 +1,9 @@
 // Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
 // See LICENSE.txt for license information.
-import { spawnSync } from 'child_process';
+import { runGitRaw } from '../agent/git.js';
 const MAX_DIFF_CHARS = 8000;
 const MAX_TOTAL_CHARS = 60000;
 const TRUNCATION_NOTICE = '\n... (diff truncated)';
-function runGitRaw(args, cwd) {
-    const result = spawnSync('git', args, {
-        cwd,
-        encoding: 'utf-8',
-        timeout: 30000,
-    });
-    if (result.error || result.status !== 0) {
-        return null;
-    }
-    return result.stdout;
-}
 /**
  * Loads git diffs for the given changed files relative to the given since ref.
  * Uses `git merge-base` to find the accurate base ref first.

package/dist/esm/engine/impact_engine.js

@@ -2,7 +2,8 @@
 // See LICENSE.txt for license information.
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { loadRouteFamilyManifest, bindFilesToFamilies, getSpecDirsForBinding, getCypressSpecDirsForBinding, getPriorityForBinding, getUserFlowsForBinding, } from '../knowledge/route_families.js';
+import { loadRouteFamilyManifest, buildHeuristicFamilies, bindFilesToFamilies, getSpecDirsForBinding, getCypressSpecDirsForBinding, getPriorityForBinding, getUserFlowsForBinding, } from '../knowledge/route_families.js';
+import { isTestFile } from '../agent/git.js';
 function scanDirForSpecs(baseDir, specDir, extension) {
     const fullDir = join(baseDir, specDir);
     if (!existsSync(fullDir)) {
@@ -125,7 +126,8 @@ function groupBindings(fileBindings) {
             const key = binding.feature || binding.family;
             const existing = groups.get(key);
             if (existing) {
-                if (!existing.files.includes(fb.file)) {
+                if (!existing._seen.has(fb.file)) {
+                    existing._seen.add(fb.file);
                     existing.files.push(fb.file);
                 }
             }
@@ -134,23 +136,13 @@ function groupBindings(fileBindings) {
                     familyId: binding.family,
                     featureId: binding.feature,
                     files: [fb.file],
+                    _seen: new Set([fb.file]),
                 });
             }
         }
     }
     return groups;
 }
-/** Filter out test files that should not be treated as application changes. */
-function isTestFile(file) {
-    const normalized = file.replace(/\\/g, '/');
-    return /\.(spec|test)\.(ts|tsx|js|jsx)$/.test(normalized) ||
-        /\.snap$/.test(normalized) ||
-        /_test\.go$/.test(normalized) ||
-        normalized.includes('__tests__/') ||
-        normalized.includes('__snapshots__/') ||
-        normalized.includes('/tests/') ||
-        normalized.includes('/test/');
-}
 /** Classify filtered test files by type for downstream decision-making. */
 function classifyPrTestFiles(allFiles, sourceFiles) {
     const sourceSet = new Set(sourceFiles);
@@ -180,17 +172,11 @@ export function analyzeImpact(changedFiles, options) {
     const allOriginalFiles = [...new Set([...changedFiles, ...preFilteredTests])];
     changedFiles = changedFiles.filter((f) => !isTestFile(f));
     const prIncludedTestFiles = classifyPrTestFiles(allOriginalFiles, changedFiles);
-    // Load manifest
-    const manifest = loadRouteFamilyManifest(testsRoot, routeFamilies);
+    // Load manifest, fall back to heuristic families if not found
+    let manifest = loadRouteFamilyManifest(testsRoot, routeFamilies);
     if (!manifest) {
-        return {
-            changedFiles,
-            expandedFiles: options.expandedFiles || [],
-            impactedFeatures: [],
-            unboundFiles: [...changedFiles],
-            warnings: ['Route family manifest not found. All files are unbound.'],
-            prIncludedTestFiles,
-        };
+        manifest = buildHeuristicFamilies(changedFiles, testsRoot);
+        warnings.push('Route family manifest not found. Using directory-based heuristics (lower accuracy).', 'Tip: Run `e2e-ai-agents train` to generate a proper manifest.');
     }
     // Combine original + expanded files
     const allFiles = [...new Set([...changedFiles, ...(options.expandedFiles || [])])];

package/dist/esm/index.js

@@ -44,8 +44,29 @@ export { StrategistAgent } from './agents/strategist.js';
 export { TestDesignerAgent } from './agents/test-designer.js';
 export { CrossImpactAgent } from './agents/cross-impact.js';
 export { RegressionAdvisorAgent } from './agents/regression-advisor.js';
+// Base provider (for extending with custom providers)
+export { BaseProvider, BudgetExceededError } from './base_provider.js';
+// Budget tracking
+export { BudgetLedger } from './budget_ledger.js';
+// Model routing
+export { ModelRouter } from './model_router.js';
+// Resilience
+export { withRetry } from './resilience/retry.js';
+export { CircuitBreaker } from './resilience/circuit_breaker.js';
+// Metrics
+export { PrometheusMetrics } from './metrics/prometheus.js';
+// Secret scanning
+export { sanitizeSecrets, containsSecrets, sanitizeObject } from './sanitize.js';
+// CLI errors
+export { CliError, classifyError, EXIT_CODES } from './cli/errors.js';
 // Training (route-families bootstrap and maintenance)
 export { scanProject } from './training/scanner.js';
 export { mergeFamilies, detectStaleFamilies } from './training/merger.js';
 export { enrichFamilies } from './training/enricher.js';
 export { getCommitFiles, validateCommit, buildValidationReport, formatValidationReport } from './training/validator.js';
+export { loadKnowledgeGraph, classifyProjectType, transformKGToFamilies, loadDiffOverlay } from './knowledge/kg_bridge.js';
+export { scanFromKnowledgeGraph } from './training/kg_scanner.js';
+export { resolveGenerationProfile, isMattermostProfile } from './prompts/generation_profile.js';
+export { detectFramework, detectTestMode } from './adapters/framework_adapter.js';
+// Route families (additional)
+export { serializeManifest } from './knowledge/route_families.js';

package/dist/esm/knowledge/cluster_utils.js

@@ -0,0 +1,60 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Shared cluster ID derivation for knowledge graph processing.
+ * Used by both kg_bridge.ts and kg_scanner.ts.
+ */
+/** Default directories to skip when deriving cluster IDs from file paths. */
+const DEFAULT_SKIP_DIRS = new Set([
+    'src', 'app', 'lib', 'packages', 'server', 'api', 'pages',
+    'components', 'features', 'modules',
+]);
+/** Extended skip set that also excludes test directories. */
+const SKIP_DIRS_WITH_TESTS = new Set([
+    ...DEFAULT_SKIP_DIRS,
+    'test', 'tests', 'e2e', 'spec', 'specs',
+]);
+/**
+ * Normalize a name to a snake_case cluster ID.
+ * Handles camelCase conversion, then strips non-alphanumeric characters.
+ */
+export function normalizeToClusterId(name) {
+    return name
+        .replace(/[A-Z]/g, (c, idx) => (idx > 0 ? `_${c.toLowerCase()}` : c.toLowerCase()))
+        .replace(/[^a-z0-9_]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '');
+}
+/**
+ * Derive a cluster ID from a node that has an optional filePath and name.
+ * Prefers file path grouping for consistency.
+ */
+export function deriveClusterId(node, skipDirs) {
+    if (node.filePath) {
+        return deriveClusterIdFromPath(node.filePath, skipDirs);
+    }
+    const name = normalizeToClusterId(node.name);
+    return name && name.length > 1 ? name : null;
+}
+/**
+ * Derive a cluster ID from a file path by finding the first meaningful
+ * directory segment after skipping common structural prefixes.
+ */
+export function deriveClusterIdFromPath(filePath, skipDirs = DEFAULT_SKIP_DIRS) {
+    const parts = filePath.replace(/\\/g, '/').split('/').filter(Boolean);
+    for (const part of parts) {
+        if (skipDirs.has(part))
+            continue;
+        if (part.includes('.'))
+            continue; // skip files
+        const normalized = part.toLowerCase()
+            .replace(/[^a-z0-9_]/g, '_')
+            .replace(/_+/g, '_')
+            .replace(/^_|_$/g, '');
+        if (normalized && normalized.length > 1) {
+            return normalized;
+        }
+    }
+    return null;
+}
+export { DEFAULT_SKIP_DIRS, SKIP_DIRS_WITH_TESTS };