@yasserkhanorg/e2e-agents 1.8.5 → 1.10.0

package/dist/esm/metrics/prometheus.js

@@ -0,0 +1,149 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+const DURATION_BUCKETS = [0.1, 0.5, 1, 2, 5, 10, 30, 60, 120, 300];
+export class PrometheusMetrics {
+    constructor() {
+        this.counters = [];
+        this.gauges = [];
+        this.histograms = [];
+    }
+    /**
+     * Record an LLM request.
+     */
+    recordLLMRequest(provider, agent, durationMs, costUSD, tokens) {
+        this.incrementCounter('e2e_agents_llm_requests_total', 'Total LLM requests', { provider, agent });
+        this.incrementCounter('e2e_agents_llm_tokens_total', 'Total tokens consumed', { provider, agent }, tokens);
+        this.incrementCounter('e2e_agents_llm_cost_usd_total', 'Total LLM cost in USD', { provider, agent }, costUSD);
+        this.observeHistogram('e2e_agents_llm_request_duration_seconds', 'LLM request duration', { provider, agent }, durationMs / 1000);
+    }
+    /**
+     * Record a crew workflow run.
+     */
+    recordCrewRun(workflow, families, durationMs, costUSD) {
+        this.incrementCounter('e2e_agents_crew_runs_total', 'Total crew workflow runs', { workflow });
+        this.incrementCounter('e2e_agents_crew_families_processed_total', 'Total families processed', { workflow }, families);
+        this.incrementCounter('e2e_agents_crew_cost_usd_total', 'Total crew cost in USD', { workflow }, costUSD);
+        this.observeHistogram('e2e_agents_crew_duration_seconds', 'Crew workflow duration', { workflow }, durationMs / 1000);
+    }
+    /**
+     * Record a budget check event.
+     */
+    recordBudgetCheck(exceeded, currentUSD, limitUSD) {
+        this.incrementCounter('e2e_agents_budget_checks_total', 'Total budget checks', { exceeded: String(exceeded) });
+        this.setGauge('e2e_agents_budget_used_usd', 'Current budget usage in USD', {}, currentUSD);
+        this.setGauge('e2e_agents_budget_limit_usd', 'Budget limit in USD', {}, limitUSD);
+    }
+    /**
+     * Record a circuit breaker state change.
+     */
+    recordCircuitBreakerState(state) {
+        this.setGauge('e2e_agents_circuit_breaker_state', 'Circuit breaker state (0=closed, 1=open, 2=half-open)', {}, state === 'closed' ? 0 : state === 'open' ? 1 : 2);
+    }
+    /**
+     * Record a cache hit or miss.
+     */
+    recordCacheResult(hit, agent) {
+        this.incrementCounter('e2e_agents_cache_lookups_total', 'Total cache lookups', { result: hit ? 'hit' : 'miss', agent });
+    }
+    /**
+     * Export all metrics in Prometheus text exposition format.
+     */
+    export() {
+        const lines = [];
+        const seenHelp = new Set();
+        // Export counters
+        for (const counter of this.counters) {
+            if (!seenHelp.has(counter.name)) {
+                lines.push(`# HELP ${counter.name} ${counter.help}`);
+                lines.push(`# TYPE ${counter.name} counter`);
+                seenHelp.add(counter.name);
+            }
+            const labelStr = formatLabels(counter.labels);
+            lines.push(`${counter.name}${labelStr} ${counter.value}`);
+        }
+        // Export gauges
+        for (const gauge of this.gauges) {
+            if (!seenHelp.has(gauge.name)) {
+                lines.push(`# HELP ${gauge.name} ${gauge.help}`);
+                lines.push(`# TYPE ${gauge.name} gauge`);
+                seenHelp.add(gauge.name);
+            }
+            const labelStr = formatLabels(gauge.labels);
+            lines.push(`${gauge.name}${labelStr} ${gauge.value}`);
+        }
+        // Export histograms
+        for (const hist of this.histograms) {
+            if (!seenHelp.has(hist.name)) {
+                lines.push(`# HELP ${hist.name} ${hist.help}`);
+                lines.push(`# TYPE ${hist.name} histogram`);
+                seenHelp.add(hist.name);
+            }
+            const labelStr = formatLabels(hist.labels);
+            let cumulative = 0;
+            for (const bucket of DURATION_BUCKETS) {
+                cumulative += hist.buckets.get(bucket) || 0;
+                lines.push(`${hist.name}_bucket${formatLabels({ ...hist.labels, le: String(bucket) })} ${cumulative}`);
+            }
+            lines.push(`${hist.name}_bucket${formatLabels({ ...hist.labels, le: '+Inf' })} ${hist.count}`);
+            lines.push(`${hist.name}_sum${labelStr} ${hist.sum}`);
+            lines.push(`${hist.name}_count${labelStr} ${hist.count}`);
+        }
+        return lines.join('\n') + '\n';
+    }
+    /**
+     * Reset all metrics to zero.
+     */
+    reset() {
+        this.counters = [];
+        this.gauges = [];
+        this.histograms = [];
+    }
+    incrementCounter(name, help, labels, value = 1) {
+        const existing = this.counters.find((c) => c.name === name && labelsMatch(c.labels, labels));
+        if (existing) {
+            existing.value += value;
+        }
+        else {
+            this.counters.push({ name, help, labels, value });
+        }
+    }
+    setGauge(name, help, labels, value) {
+        const existing = this.gauges.find((c) => c.name === name && labelsMatch(c.labels, labels));
+        if (existing) {
+            existing.value = value;
+        }
+        else {
+            this.gauges.push({ name, help, labels, value });
+        }
+    }
+    observeHistogram(name, help, labels, value) {
+        let existing = this.histograms.find((h) => h.name === name && labelsMatch(h.labels, labels));
+        if (!existing) {
+            existing = { name, help, labels, sum: 0, count: 0, buckets: new Map() };
+            this.histograms.push(existing);
+        }
+        existing.sum += value;
+        existing.count++;
+        for (const bucket of DURATION_BUCKETS) {
+            if (value <= bucket) {
+                existing.buckets.set(bucket, (existing.buckets.get(bucket) || 0) + 1);
+            }
+        }
+    }
+}
+function escapeLabel(v) {
+    return v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+function formatLabels(labels) {
+    const entries = Object.entries(labels);
+    if (entries.length === 0)
+        return '';
+    return `{${entries.map(([k, v]) => `${k}="${escapeLabel(v)}"`).join(',')}}`;
+}
+function labelsMatch(a, b) {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every((k) => a[k] === b[k]);
+}

package/dist/esm/model_router.js

@@ -0,0 +1,59 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+const AGENT_COMPLEXITY = {
+    'impact-analyst': 'classification',
+    'coverage-evaluator': 'classification',
+    'cross-impact': 'extraction',
+    'regression-advisor': 'extraction',
+    'strategist': 'classification',
+    'test-designer': 'generation',
+    'generator': 'generation',
+    'executor': 'generation',
+    'healer': 'reasoning',
+    'explorer': 'reasoning',
+};
+const DEFAULT_MODELS = {
+    anthropic: {
+        classification: 'claude-haiku-4-5-20251001',
+        extraction: 'claude-haiku-4-5-20251001',
+        generation: 'claude-sonnet-4-5-20250514',
+        reasoning: 'claude-sonnet-4-5-20250514',
+    },
+    openai: {
+        classification: 'gpt-4o-mini',
+        extraction: 'gpt-4o-mini',
+        generation: 'gpt-4o',
+        reasoning: 'gpt-4o',
+    },
+};
+export class ModelRouter {
+    constructor(providerType, overrides) {
+        this.providerType = providerType;
+        this.overrides = overrides || {};
+    }
+    /**
+     * Get the recommended model for a given agent role.
+     * Returns undefined if no routing recommendation (use provider default).
+     */
+    getModel(role) {
+        const complexity = AGENT_COMPLEXITY[role];
+        if (!complexity)
+            return undefined;
+        // Check user overrides first
+        const override = this.overrides[complexity];
+        if (override)
+            return override;
+        // Check provider defaults
+        const defaults = DEFAULT_MODELS[this.providerType];
+        if (defaults)
+            return defaults[complexity];
+        // No recommendation — use provider's default model
+        return undefined;
+    }
+    /**
+     * Get the task complexity for an agent role.
+     */
+    getComplexity(role) {
+        return AGENT_COMPLEXITY[role] || 'generation';
+    }
+}

package/dist/esm/ollama_provider.js

@@ -122,6 +122,7 @@ export class OllamaProvider extends BaseProvider {
         this.model = model;
     }
     async generateText(prompt, options) {
+        this.checkBudget();
         const startTime = Date.now();
         try {
             // SECURITY: Validate prompt length

package/dist/esm/openai_provider.js

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

package/dist/esm/pipeline/orchestrator.js

@@ -2,7 +2,7 @@
 // See LICENSE.txt for license information.
 import { existsSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
-import { getChangedFiles } from '../agent/git.js';
+import { getChangedFiles, isTestFile } from '../agent/git.js';
 import { logger } from '../logger.js';
 import { preprocess } from './stage0_preprocess.js';
 import { runImpactStage } from './stage1_impact.js';
@@ -11,6 +11,7 @@ import { runGenerationStage } from './stage3_generation.js';
 import { runHealStage, resolveHealTargets, renderHealMarkdown } from './stage4_heal.js';
 import { buildSummary } from '../validation/output_schema.js';
 import { computeCannotDetermineRatio } from '../validation/guardrails.js';
+import { resolveGenerationProfile } from '../prompts/generation_profile.js';
 function createRunId() {
     const ciRunId = process.env.GITHUB_RUN_ID;
     const entropy = Math.random().toString(36).slice(2, 8);
@@ -20,19 +21,12 @@ function createRunId() {
     }
     return `pipeline-local-${ts}-${entropy}`;
 }
-function isTestFile(file) {
-    const normalized = file.replace(/\\/g, '/');
-    return /\.(spec|test)\.(ts|tsx|js|jsx)$/.test(normalized) ||
-        /_test\.go$/.test(normalized) ||
-        normalized.includes('__tests__/') ||
-        normalized.includes('/tests/') ||
-        normalized.includes('/test/');
-}
 export async function runPipeline(config) {
     const runId = createRunId();
     const startedAt = new Date().toISOString();
     const allWarnings = [];
     const stages = config.stages || ['preprocess', 'impact', 'coverage'];
+    const profile = config.profile || resolveGenerationProfile();
     let generatedSpecs;
     let healResult;
     // Step 1: Get changed files
@@ -87,7 +81,7 @@ export async function runPipeline(config) {
     // Step 4: Coverage stage — AI-powered spec coverage evaluation
     if (stages.includes('coverage') && decisions.length > 0) {
         const coverageTimer = logger.timer('coverage');
-        const coverageResult = await runCoverageStage(decisions, preprocessResult.specIndex, preprocessResult.context, config.testsRoot, config.coverage || {});
+        const coverageResult = await runCoverageStage(decisions, preprocessResult.specIndex, preprocessResult.context, config.testsRoot, { ...(config.coverage || {}), profile });
         decisions = coverageResult.decisions;
         timings.coverage = coverageTimer.end();
         allWarnings.push(...coverageResult.warnings);
@@ -95,7 +89,7 @@ export async function runPipeline(config) {
     // Step 5: Generation stage — AI-powered spec generation for create_spec / add_scenarios
     if (stages.includes('generation') && decisions.length > 0) {
         const generationTimer = logger.timer('generation');
-        const generationResult = await runGenerationStage(decisions, preprocessResult.apiSurface, config.testsRoot, config.generation || {});
+        const generationResult = await runGenerationStage(decisions, preprocessResult.apiSurface, config.testsRoot, { ...(config.generation || {}), profile });
         generatedSpecs = generationResult.generated;
         timings.generation = generationTimer.end();
         allWarnings.push(...generationResult.warnings);
@@ -108,7 +102,7 @@ export async function runPipeline(config) {
             generatedSpecs,
         }, decisions);
         if (healTargets.length > 0) {
-            healResult = await runHealStage(config.testsRoot, healTargets, config.heal || { mcp: true });
+            healResult = await runHealStage(config.testsRoot, healTargets, { ...(config.heal || { mcp: true }), profile });
             allWarnings.push(...healResult.warnings);
         }
         else {

package/dist/esm/pipeline/stage0_preprocess.js

@@ -2,7 +2,7 @@
 // See LICENSE.txt for license information.
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { bindFilesToFamilies, loadRouteFamilyManifest, } from '../knowledge/route_families.js';
+import { bindFilesToFamilies, buildHeuristicFamilies, loadRouteFamilyManifest, } from '../knowledge/route_families.js';
 import { loadOrBuildApiSurface } from '../knowledge/api_surface.js';
 import { buildSpecIndex } from '../knowledge/spec_index.js';
 import { loadContextDocuments } from '../knowledge/context_loader.js';
@@ -31,10 +31,11 @@ function loadFileSnippet(appPath, filePath) {
 }
 export function preprocess(changedFiles, config) {
     const warnings = [];
-    // Load route family manifest
-    const manifest = loadRouteFamilyManifest(config.testsRoot, config.routeFamilies);
+    // Load route family manifest, fall back to heuristic families
+    let manifest = loadRouteFamilyManifest(config.testsRoot, config.routeFamilies);
     if (!manifest) {
-        warnings.push('Route family manifest not found. File-to-family binding will be skipped; AI will operate without route constraints.');
+        manifest = buildHeuristicFamilies(changedFiles, config.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.');
     }
     // Load API surface catalog
     const apiSurface = loadOrBuildApiSurface(config.testsRoot, config.apiSurface);
@@ -46,21 +47,13 @@ export function preprocess(changedFiles, config) {
     // Load context documents
     const context = loadContextDocuments(config.testsRoot, config.appPath);
     warnings.push(...context.warnings);
-    // Bind files to families
-    let fileBindings = [];
-    let unboundFiles = [];
-    if (manifest) {
-        fileBindings = bindFilesToFamilies(changedFiles, manifest);
-        unboundFiles = fileBindings
-            .filter((fb) => fb.bindings.length === 0)
-            .map((fb) => fb.file);
-        if (unboundFiles.length > 0) {
-            warnings.push(`${unboundFiles.length} changed file(s) did not match any route family: ${unboundFiles.slice(0, 5).join(', ')}${unboundFiles.length > 5 ? '...' : ''}`);
-        }
-    }
-    else {
-        fileBindings = changedFiles.map((f) => ({ file: f, bindings: [] }));
-        unboundFiles = changedFiles;
+    // Bind files to families (manifest is always non-null now — either real or heuristic)
+    const fileBindings = bindFilesToFamilies(changedFiles, manifest);
+    const unboundFiles = fileBindings
+        .filter((fb) => fb.bindings.length === 0)
+        .map((fb) => fb.file);
+    if (unboundFiles.length > 0) {
+        warnings.push(`${unboundFiles.length} changed file(s) did not match any route family: ${unboundFiles.slice(0, 5).join(', ')}${unboundFiles.length > 5 ? '...' : ''}`);
     }
     // Group files by family+feature
     const groupMap = new Map();

package/dist/esm/pipeline/stage1_impact.js

@@ -3,7 +3,8 @@
 import { LLMProviderFactory } from '../provider_factory.js';
 import { buildImpactPrompt, parseImpactResponse } from '../prompts/impact.js';
 import { formatContextForPrompt } from '../knowledge/context_loader.js';
-import { getFamilyById } from '../knowledge/route_families.js';
+import { getFamilyById, getAssertionPatternsForBinding } from '../knowledge/route_families.js';
+import { loadFailureHistory, getConfidenceBoost } from '../knowledge/failure_history.js';
 import { getSpecsForFamily } from '../knowledge/spec_index.js';
 import { computeConfidence, shouldForceCannotDetermine } from '../validation/guardrails.js';
 function normalizePriority(value) {
@@ -18,7 +19,7 @@ async function getProvider(config) {
     }
     return LLMProviderFactory.createFromEnv();
 }
-export async function runImpactStage(familyGroups, manifest, specIndex, apiSurface, context, config) {
+export async function runImpactStage(familyGroups, manifest, specIndex, apiSurface, context, config, testsRoot) {
     const warnings = [];
     const allDecisions = [];
     if (familyGroups.length === 0) {
@@ -35,6 +36,8 @@ export async function runImpactStage(familyGroups, manifest, specIndex, apiSurfa
         return { decisions: [], warnings, providerName: 'none' };
     }
     const contextBlock = formatContextForPrompt(context);
+    // Load historical failure correlations for confidence boosting
+    const failureHistory = testsRoot ? loadFailureHistory(testsRoot) : null;
     for (const group of familyGroups) {
         const family = manifest ? getFamilyById(manifest, group.familyId) : null;
         if (!family) {
@@ -83,15 +86,27 @@ export async function runImpactStage(familyGroups, manifest, specIndex, apiSurfa
                 if (!flow.id || !flow.changedFiles || !Array.isArray(flow.changedFiles)) {
                     continue;
                 }
+                // Compute confidence with optional historical failure boost
+                const changedFilesList = Array.isArray(flow.changedFiles)
+                    ? flow.changedFiles.filter((f) => typeof f === 'string')
+                    : [];
+                const historyBoost = failureHistory
+                    ? Math.max(...changedFilesList.map((f) => getConfidenceBoost(failureHistory, f)), 0)
+                    : 0;
                 const confidence = typeof flow.confidence === 'number'
-                    ? Math.max(0, Math.min(100, flow.confidence))
+                    ? Math.min(100, Math.max(0, flow.confidence) + historyBoost)
                     : computeConfidence({
                         hasRouteFamily: true,
                         hasSpecificRoute: Boolean(flow.route),
                         hasPageObject: Boolean(flow.pageObjects && flow.pageObjects.length > 0),
                         hasUserAction: Boolean(flow.userActions && flow.userActions.length > 0),
                         hasExistingSpecCited: false,
+                        historyBoost,
                     });
+                // Resolve assertion patterns from manifest for this flow's family/feature
+                const assertionPatterns = manifest
+                    ? getAssertionPatternsForBinding(manifest, { family: group.familyId, feature: group.featureId })
+                    : [];
                 const decision = {
                     flowId: flow.id,
                     flowName: flow.name || flow.id,
@@ -107,6 +122,7 @@ export async function runImpactStage(familyGroups, manifest, specIndex, apiSurfa
                     blockingReason: shouldForceCannotDetermine(confidence) ? 'Confidence too low to determine action.' : undefined,
                     priority: normalizePriority(flow.priority),
                     userActions: Array.isArray(flow.userActions) ? flow.userActions.filter((a) => typeof a === 'string') : [],
+                    assertionPatterns: assertionPatterns.length > 0 ? assertionPatterns : undefined,
                 };
                 allDecisions.push(decision);
             }

package/dist/esm/pipeline/stage2_coverage.js

@@ -43,13 +43,26 @@ export async function runCoverageStage(decisions, specIndex, context, testsRoot,
     for (const [familyId, familyDecisions] of byFamily) {
         // Gather relevant specs
         const specs = getSpecsForFamily(specIndex, familyId);
-        const specsWithContent = specs
-            .map((s) => {
+        // Two-tier approach: send all spec titles (compact), full content for top matches only
+        const allSpecSummaries = specs.map((s) => ({
+            relativePath: s.relativePath,
+            testTitles: s.testTitles,
+        }));
+        // Load full content with a total budget of 200K chars (~50K tokens) to avoid blowing context windows
+        const MAX_TOTAL_SPEC_CHARS = 200000;
+        let totalSpecChars = 0;
+        const specsWithContent = [];
+        for (const s of specs) {
+            if (specsWithContent.length >= 30)
+                break;
             const content = loadSpecFileContent(testsRoot, s.relativePath, maxSpecChars);
-            return content ? { relativePath: s.relativePath, content, testTitles: s.testTitles } : null;
-        })
-            .filter((s) => s !== null)
-            .slice(0, 15); // Limit to 15 specs per family to stay within token budget
+            if (!content)
+                continue;
+            if (totalSpecChars + content.length > MAX_TOTAL_SPEC_CHARS)
+                break;
+            totalSpecChars += content.length;
+            specsWithContent.push({ relativePath: s.relativePath, content, testTitles: s.testTitles });
+        }
         if (specsWithContent.length === 0) {
             // No specs to evaluate — mark all as create_spec
             for (const d of familyDecisions) {
@@ -70,10 +83,19 @@ export async function runCoverageStage(decisions, specIndex, context, testsRoot,
             evidence: d.evidence,
             priority: d.priority,
         }));
+        // Include titles-only summaries for specs beyond the content limit
+        const extraSummaries = allSpecSummaries
+            .slice(specsWithContent.length)
+            .map((s) => `  - ${s.relativePath}: ${s.testTitles.join(', ')}`)
+            .join('\n');
+        const extraContext = extraSummaries
+            ? `\nADDITIONAL SPECS (titles only, no content loaded):\n${extraSummaries}\n`
+            : '';
         const prompt = buildCoveragePrompt({
             flows,
             specs: specsWithContent,
-            contextBlock,
+            contextBlock: contextBlock + extraContext,
+            profile: config.profile,
         });
         try {
             const response = await provider.generateText(prompt, {

package/dist/esm/pipeline/stage3_generation.js

@@ -86,6 +86,7 @@ export async function runGenerationStage(decisions, apiSurface, testsRoot, confi
             existingSpecContent,
             specPath,
             mode,
+            profile: config.profile,
         });
         try {
             const response = await provider.generateText(prompt, {
@@ -100,10 +101,29 @@ export async function runGenerationStage(decisions, apiSurface, testsRoot, confi
                 skipped.push(`${decision.flowId}: invalid code returned`);
                 continue;
             }
-            // Hallucination detection
+            // Hallucination detection — block specs with hallucinated methods
             const hallucinationWarnings = detectHallucinatedMethods(parsed.code, apiSurface);
             if (hallucinationWarnings.length > 0) {
                 warnings.push(`Flow ${decision.flowId}: suspected hallucinated methods: ${hallucinationWarnings.join(', ')}`);
+                if (!config.warnOnHallucinations) {
+                    // Block: move to needs-review instead of writing to specs dir
+                    if (!dryRun) {
+                        const reviewDir = join(testsRoot, 'generated-needs-review');
+                        mkdirSync(reviewDir, { recursive: true });
+                        const safeName = decision.flowId.replace(/[^a-zA-Z0-9_-]/g, '_').toLowerCase();
+                        const reviewPath = join(reviewDir, `${safeName}-${Date.now().toString(36)}.spec.ts`);
+                        writeFileSync(reviewPath, `${parsed.code}\n`, 'utf-8');
+                        warnings.push(`Flow ${decision.flowId}: blocked — moved to ${reviewPath}`);
+                    }
+                    generated.push({
+                        flowId: decision.flowId,
+                        specPath,
+                        mode,
+                        written: false,
+                        hallucinationWarnings,
+                    });
+                    continue;
+                }
             }
             let written = false;
             if (!dryRun) {

package/dist/esm/progress.js

@@ -0,0 +1,112 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { EventEmitter } from 'events';
+export class ProgressReporter extends EventEmitter {
+    constructor(options) {
+        super();
+        this.isTTY = options?.isTTY ?? (process.stdout.isTTY === true);
+        this.silent = (options?.quiet ?? false) || (options?.jsonMode ?? false);
+        this.completedAgents = 0;
+        this.totalAgents = 0;
+        this.currentPhase = '';
+    }
+    phaseStart(phase, agentCount) {
+        const payload = { phase, agentCount };
+        this.emit('phase-start', payload);
+        if (this.silent) {
+            return;
+        }
+        this.currentPhase = phase;
+        this.completedAgents = 0;
+        this.totalAgents = agentCount;
+        const message = `--- Phase: ${phase} (${agentCount} agent${agentCount !== 1 ? 's' : ''}) ---`;
+        this.writeLine(message);
+    }
+    agentStart(agent, family) {
+        const payload = { agent, family };
+        this.emit('agent-start', payload);
+        if (this.silent) {
+            return;
+        }
+        const familyLabel = family ? ` processing ${family}` : '';
+        if (this.isTTY) {
+            const progress = `[${this.completedAgents}/${this.totalAgents} agents]`;
+            const message = `${progress} ${this.currentPhase}: ${agent}${familyLabel}...`;
+            process.stdout.write(`\r${clearLine()}${message}`);
+        }
+        else {
+            const message = `[${this.currentPhase}] ${agent} started${familyLabel ? ':' + familyLabel : ''}`;
+            this.writeLine(message);
+        }
+    }
+    agentComplete(agent, family, tokens, cost, durationMs) {
+        const payload = { agent, family, tokens, cost, durationMs };
+        this.emit('agent-complete', payload);
+        if (this.silent) {
+            return;
+        }
+        this.completedAgents++;
+        const costStr = formatCost(cost);
+        const durationStr = formatDuration(durationMs);
+        const tokensStr = formatTokens(tokens);
+        const familyLabel = family ? ` ${family}` : '';
+        if (this.isTTY) {
+            const progress = `[${this.completedAgents}/${this.totalAgents} agents]`;
+            const message = `${progress} ${this.currentPhase}: ${agent} complete${familyLabel} (${tokensStr}, ${costStr}, ${durationStr})`;
+            process.stdout.write(`\r${clearLine()}${message}\n`);
+        }
+        else {
+            const message = `[${this.currentPhase}] ${agent} complete:${familyLabel} (${tokensStr}, ${costStr}, ${durationStr})`;
+            this.writeLine(message);
+        }
+    }
+    phaseComplete(phase, elapsedMs) {
+        const payload = { phase, elapsedMs };
+        this.emit('phase-complete', payload);
+        if (this.silent) {
+            return;
+        }
+        const durationStr = formatDuration(elapsedMs);
+        const message = `--- Phase ${phase} complete (${durationStr}) ---`;
+        this.writeLine(message);
+    }
+    workflowComplete(totalCost, totalTokens, elapsedMs) {
+        const payload = { totalCost, totalTokens, elapsedMs };
+        this.emit('workflow-complete', payload);
+        if (this.silent) {
+            return;
+        }
+        const costStr = formatCost(totalCost);
+        const tokensStr = formatTokens(totalTokens);
+        const durationStr = formatDuration(elapsedMs);
+        const message = `=== Workflow complete: ${tokensStr}, ${costStr}, ${durationStr} ===`;
+        this.writeLine(message);
+    }
+    writeLine(message) {
+        process.stdout.write(message + '\n');
+    }
+}
+function clearLine() {
+    return '\x1B[2K';
+}
+function formatCost(cost) {
+    return `$${cost.toFixed(2)}`;
+}
+function formatTokens(tokens) {
+    if (tokens >= 1000000) {
+        return `${(tokens / 1000000).toFixed(1)}M tokens`;
+    }
+    if (tokens >= 1000) {
+        return `${(tokens / 1000).toFixed(0).replace(/\B(?=(\d{3})+(?!\d))/g, ',')} tokens`;
+    }
+    return `${tokens} tokens`;
+}
+function formatDuration(ms) {
+    const seconds = Math.round(ms / 1000);
+    if (seconds >= 60) {
+        const minutes = Math.floor(seconds / 60);
+        const remainingSeconds = seconds % 60;
+        return remainingSeconds > 0 ? `${minutes}m${remainingSeconds}s` : `${minutes}m`;
+    }
+    return `${seconds}s`;
+}