@yasserkhanorg/e2e-agents 1.8.5 → 1.9.5

package/dist/esm/cli/commands/train.js

@@ -5,13 +5,16 @@ import { existsSync, mkdirSync, renameSync, writeFileSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import * as readline from 'readline';
 import { resolveConfig } from '../../agent/config.js';
-import { loadRouteFamilyManifest } from '../../knowledge/route_families.js';
+import { loadRouteFamilyManifest, serializeManifest } from '../../knowledge/route_families.js';
 import { LLMProviderFactory } from '../../provider_factory.js';
 import { logger, LogLevel } from '../../logger.js';
+import { getVersion } from '../../version.js';
 import { scanProject } from '../../training/scanner.js';
+import { scanFromKnowledgeGraph } from '../../training/kg_scanner.js';
 import { mergeFamilies, detectStaleFamilies } from '../../training/merger.js';
 import { enrichFamilies } from '../../training/enricher.js';
 import { getCommitFiles, validateCommit, buildValidationReport, formatValidationReport } from '../../training/validator.js';
+import { loadKnowledgeGraph } from '../../knowledge/kg_bridge.js';
 class TrainError extends Error {
     constructor(message) {
         super(message);
@@ -121,24 +124,6 @@ function ask(rl, question, defaultValue) {
         });
     });
 }
-function serializeManifest(manifest) {
-    const output = {
-        families: manifest.families.map((f) => {
-            // Remove undefined/empty optional fields for clean JSON
-            const cleaned = { ...f };
-            const optionalArrays = ['pageObjects', 'components', 'webappPaths', 'serverPaths', 'specDirs', 'cypressSpecDirs', 'tags', 'userFlows', 'features'];
-            for (const key of optionalArrays) {
-                if (!cleaned[key] || (Array.isArray(cleaned[key]) && cleaned[key].length === 0)) {
-                    delete cleaned[key];
-                }
-            }
-            if (!cleaned.priority)
-                delete cleaned.priority;
-            return cleaned;
-        }),
-    };
-    return JSON.stringify(output, null, 2) + '\n';
-}
 export async function runTrainCommand(args, autoConfig) {
     const opts = resolveTrainOptions(args, autoConfig);
     const totalTimer = logger.timer('train-total');
@@ -151,12 +136,22 @@ export async function runTrainCommand(args, autoConfig) {
     logger.info('e2e-ai-agents train');
     logger.info('===================');
     // ---------- Phase 1: Deterministic scan ----------
+    // Prefer knowledge graph when available
+    const kg = loadKnowledgeGraph(opts.appPath);
     logger.info('Scanning project structure...');
     if (opts.serverRoot) {
         logger.info(`Server root: ${opts.serverRoot}`);
     }
     const scanTimer = logger.timer('scan');
-    const scanResult = scanProject(opts.appPath, opts.testsRoot !== opts.appPath ? opts.testsRoot : undefined, opts.serverRoot, opts.gitRepoRoot);
+    let scanResult;
+    if (kg) {
+        logger.info('Using knowledge graph for scanning (found .understand-anything/knowledge-graph.json)');
+        scanResult = scanFromKnowledgeGraph(kg);
+        logger.info(`KG: ${kg.nodes.length} nodes, ${kg.edges.length} edges`);
+    }
+    else {
+        scanResult = scanProject(opts.appPath, opts.testsRoot !== opts.appPath ? opts.testsRoot : undefined, opts.serverRoot, opts.gitRepoRoot);
+    }
     timings.scan = scanTimer.end();
     logger.info(`Found ${scanResult.stats.totalSourceFiles} source files, ${scanResult.stats.totalTestFiles} test files`);
     logger.info(`Discovered ${scanResult.families.length} candidate families`);
@@ -332,7 +327,7 @@ export async function runTrainCommand(args, autoConfig) {
         const reportDir = dirname(opts.outputPath);
         const trainReport = {
             timestamp: new Date().toISOString(),
-            version: '1.7.0',
+            version: getVersion(),
             timings,
             families: {
                 total: mergeResult.manifest.families.length,

package/dist/esm/cli/defaults.js

@@ -0,0 +1,118 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, readFileSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { join, resolve } from 'path';
+/**
+ * Detect the test framework from package.json dependencies.
+ */
+export function detectFramework(appPath) {
+    const resolvedPath = resolve(appPath);
+    const pkgPath = join(resolvedPath, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return 'auto';
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+        if (allDeps['@playwright/test'] || allDeps.playwright) {
+            return 'playwright';
+        }
+        if (allDeps.cypress) {
+            return 'cypress';
+        }
+        if (allDeps['selenium-webdriver'] || allDeps.webdriverio) {
+            return 'selenium';
+        }
+    }
+    catch {
+        // ignore malformed package.json
+    }
+    return 'auto';
+}
+/**
+ * Detect the tests root directory by scanning common conventions.
+ */
+export function detectTestsRoot(appPath) {
+    const resolvedPath = resolve(appPath);
+    const candidates = [
+        'e2e-tests/playwright',
+        'e2e-tests',
+        'e2e',
+        'tests/e2e',
+        'test/e2e',
+        'tests',
+        'test',
+        'specs',
+        'playwright',
+        'cypress',
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(join(resolvedPath, candidate))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Detect the git default branch for diffing.
+ * Returns origin/<branch> format.
+ */
+export function detectGitDefaultBranch(appPath) {
+    try {
+        // Try to find the remote HEAD branch first
+        const remoteInfo = execFileSync('git', ['remote', 'show', 'origin'], {
+            cwd: resolve(appPath),
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        });
+        const headMatch = remoteInfo.match(/HEAD branch:\s*(.+)/);
+        if (headMatch) {
+            return `origin/${headMatch[1].trim()}`;
+        }
+    }
+    catch {
+        // fallback to current branch
+    }
+    try {
+        const result = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+            cwd: resolve(appPath),
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        }).trim();
+        return `origin/${result}`;
+    }
+    catch {
+        return 'origin/main';
+    }
+}
+/**
+ * Detect the project root by walking up to find package.json or .git.
+ */
+export function detectProjectRoot(startDir) {
+    let current = resolve(startDir);
+    while (true) {
+        if (existsSync(join(current, 'package.json')) || existsSync(join(current, '.git'))) {
+            return current;
+        }
+        const parent = resolve(current, '..');
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return startDir;
+}
+/**
+ * Resolve defaults for CLI commands that need path/testsRoot/framework/since.
+ * Explicit values from CLI flags take precedence over detected values.
+ */
+export function resolveDefaults(explicit) {
+    const path = explicit.path || detectProjectRoot(process.cwd());
+    const testsRoot = explicit.testsRoot || detectTestsRoot(path) || '.';
+    const framework = explicit.framework || detectFramework(path);
+    const since = explicit.gitSince || detectGitDefaultBranch(path);
+    return { path, testsRoot, framework, since };
+}

package/dist/esm/cli/errors.js

@@ -0,0 +1,52 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * CLI Error types with structured exit codes.
+ *
+ * Exit codes:
+ *   0 = success
+ *   1 = general/user error (bad args, missing config, invalid input)
+ *   2 = budget exceeded
+ *   3 = LLM provider unavailable (API down, auth failure)
+ *   4 = invalid manifest or config file
+ */
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    GENERAL_ERROR: 1,
+    BUDGET_EXCEEDED: 2,
+    PROVIDER_UNAVAILABLE: 3,
+    INVALID_CONFIG: 4,
+};
+export class CliError extends Error {
+    constructor(message, exitCode = EXIT_CODES.GENERAL_ERROR) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'CliError';
+    }
+}
+/**
+ * Classify an unknown error into the appropriate exit code.
+ */
+export function classifyError(error) {
+    if (error instanceof CliError)
+        return error.exitCode;
+    const msg = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    // Budget errors
+    if (msg.includes('budget exceeded') || msg.includes('budget limit')) {
+        return EXIT_CODES.BUDGET_EXCEEDED;
+    }
+    // Provider/auth errors
+    if (msg.includes('api key') || msg.includes('authentication') ||
+        msg.includes('unauthorized') || msg.includes('403') ||
+        (msg.includes('provider') && msg.includes('unavailable')) ||
+        msg.includes('econnrefused') || msg.includes('econnreset')) {
+        return EXIT_CODES.PROVIDER_UNAVAILABLE;
+    }
+    // Config/manifest errors
+    if ((msg.includes('manifest') && (msg.includes('invalid') || msg.includes('not found') || msg.includes('parse'))) ||
+        (msg.includes('config') && msg.includes('invalid')) ||
+        (msg.includes('route-families') && msg.includes('invalid'))) {
+        return EXIT_CODES.INVALID_CONFIG;
+    }
+    return EXIT_CODES.GENERAL_ERROR;
+}

package/dist/esm/cli/parse_args.js

@@ -2,6 +2,7 @@
 // See LICENSE.txt for license information.
 import { existsSync } from 'fs';
 import { dirname, join, resolve } from 'path';
+import { logger } from '../logger.js';
 export const CONFIG_CANDIDATES = ['e2e-ai-agents.config.json', '.e2e-ai-agents.config.json'];
 export function findConfigUpwards(startDir) {
     if (!startDir) {
@@ -62,6 +63,7 @@ const FLAGS = {
     '--generate': { key: 'analyzeGenerate', type: 'boolean' },
     '--heal': { key: 'analyzeHeal', type: 'boolean' },
     '--no-ai': { key: 'noAi', type: 'boolean' },
+    '--degraded-mode': { key: 'degradedMode', type: 'boolean' },
     '--enrich': { key: 'trainEnrich', type: 'boolean' },
     '--no-enrich': { key: 'trainEnrich', type: 'boolean-false' },
     '--validate': { key: 'trainValidate', type: 'boolean' },
@@ -131,6 +133,13 @@ const FLAGS = {
         type: 'csv',
         transform: (v) => csvSplit(v).filter((s) => s === 'run-now' || s === 'must-add-tests' || s === 'safe-to-merge'),
     },
+    // -- gate command --
+    '--threshold': { key: 'gateThreshold', type: 'number' },
+    // -- bootstrap command --
+    '--kg-path': { key: 'bootstrapKgPath', type: 'string' },
+    '--scaffold-framework': { key: 'bootstrapScaffoldFramework', type: 'boolean' },
+    '--test-mode': { key: 'bootstrapTestMode', type: 'enum', enumValues: ['ui', 'api', 'both'] },
+    '--max-families': { key: 'bootstrapMaxFamilies', type: 'number' },
 };
 // Build a lookup from alias -> canonical flag name
 const ALIAS_MAP = {};
@@ -146,7 +155,8 @@ const COMMANDS = new Set([
     'init', 'impact', 'plan', 'heal', 'suggest', 'generate',
     'finalize-generated-tests', 'feedback',
     'traceability-capture', 'traceability-ingest',
-    'analyze', 'llm-health', 'train', 'crew',
+    'analyze', 'llm-health', 'train', 'crew', 'cost-report', 'gate',
+    'bootstrap',
 ]);
 // ---------------------------------------------------------------------------
 // Parser
@@ -168,6 +178,9 @@ export function parseArgs(argv) {
         const arg = argv[i];
         const canonical = ALIAS_MAP[arg];
         if (!canonical) {
+            if (arg.startsWith('--')) {
+                logger.warn(`Unknown flag "${arg}" (ignored)`);
+            }
             continue;
         }
         const def = FLAGS[canonical];
@@ -196,7 +209,16 @@ export function parseArgs(argv) {
                 break;
             case 'number-raw':
                 if (next) {
-                    setField(parsed, def.key, def.transform ? def.transform(next) : Number(next));
+                    const rawValue = def.transform ? def.transform(next) : Number(next);
+                    // Allow non-number transforms through; reject NaN/Infinity for numbers
+                    if (typeof rawValue === 'number') {
+                        if (Number.isFinite(rawValue)) {
+                            setField(parsed, def.key, rawValue);
+                        }
+                    }
+                    else {
+                        setField(parsed, def.key, rawValue);
+                    }
                     i += 1;
                 }
                 break;

package/dist/esm/cli.js

@@ -3,6 +3,7 @@
 // See LICENSE.txt for license information.
 import { resolveConfig } from './agent/config.js';
 import { parseArgs, resolveAutoConfig } from './cli/parse_args.js';
+import { resolveDefaults } from './cli/defaults.js';
 import { printUsage } from './cli/usage.js';
 import { runLlmHealth } from './cli/commands/llm_health.js';
 import { runAnalyzeCommand } from './cli/commands/analyze.js';
@@ -16,14 +17,42 @@ import { runGenerateCommand } from './cli/commands/generate.js';
 import { runInitCommand } from './cli/commands/init.js';
 import { runTrainCommand } from './cli/commands/train.js';
 import { runCrewCommand } from './cli/commands/crew.js';
+import { runCostReportCommand } from './cli/commands/cost_report.js';
+import { runGateCommand } from './cli/commands/gate.js';
+import { runBootstrapCommand } from './cli/commands/bootstrap.js';
+import { classifyError, EXIT_CODES } from './cli/errors.js';
+// Commands that skip default resolution (they handle their own setup)
+const SKIP_DEFAULTS_COMMANDS = new Set(['init', 'llm-health', 'cost-report', 'bootstrap']);
+// Commands that need path/testsRoot/framework/since
+const NEEDS_DEFAULTS_COMMANDS = new Set([
+    'impact', 'plan', 'suggest', 'crew', 'generate', 'heal', 'analyze', 'train',
+    'feedback', 'traceability-capture', 'traceability-ingest', 'finalize-generated-tests',
+]);
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     const autoConfig = resolveAutoConfig(args);
+    // Auto-detect defaults for commands that need them (when no config file found)
+    if (args.command && NEEDS_DEFAULTS_COMMANDS.has(args.command) && !SKIP_DEFAULTS_COMMANDS.has(args.command)) {
+        const defaults = resolveDefaults({
+            path: args.path,
+            testsRoot: args.testsRoot,
+            framework: args.framework,
+            gitSince: args.gitSince,
+        });
+        args.path = args.path || defaults.path;
+        args.testsRoot = args.testsRoot || defaults.testsRoot;
+        args.framework = args.framework || defaults.framework;
+        args.gitSince = args.gitSince || defaults.since;
+    }
     if (args.command === 'init') {
         const hasYes = process.argv.includes('--yes') || process.argv.includes('-y');
         await runInitCommand(hasYes);
         return;
     }
+    if (args.command === 'bootstrap') {
+        await runBootstrapCommand(args);
+        return;
+    }
     if (args.command === 'train') {
         await runTrainCommand(args, autoConfig);
         return;
@@ -64,6 +93,14 @@ async function main() {
         await runCrewCommand(args, autoConfig);
         return;
     }
+    if (args.command === 'cost-report') {
+        runCostReportCommand(args);
+        return;
+    }
+    if (args.command === 'gate') {
+        await runGateCommand(args, autoConfig);
+        return;
+    }
     if (!args.path && !autoConfig) {
         console.error('Error: --path is required (or provide a config file with path set)');
         printUsage();
@@ -138,6 +175,14 @@ async function main() {
     process.exit(1);
 }
 main().catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(1);
+    const exitCode = classifyError(error);
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    if (exitCode === EXIT_CODES.BUDGET_EXCEEDED) {
+        console.error('Hint: Increase --budget or use --degraded-mode to skip AI features.');
+    }
+    else if (exitCode === EXIT_CODES.PROVIDER_UNAVAILABLE) {
+        console.error('Hint: Check API key or use --degraded-mode for deterministic analysis only.');
+    }
+    process.exit(exitCode);
 });

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;
 }