@yasserkhanorg/e2e-agents 1.8.1 → 1.8.3

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

@@ -1,9 +1,10 @@
 // Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
 // See LICENSE.txt for license information.
-import { appendFileSync } from 'fs';
+import { appendFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { writeCiSummary } from '../../engine/plan_builder.js';
 import { recommendTestsAI, recommendTestsDeterministic } from '../../api.js';
+import { appendCrewToSummary, runPlanCrewAnalysis, writeCrewArtifacts } from './plan_crew.js';
 export async function runPlanCommand(args, autoConfig, config) {
     const reportRoot = config.testsRoot || config.path;
     const apiOptions = {
@@ -40,41 +41,77 @@ export async function runPlanCommand(args, autoConfig, config) {
             const { aiEnrichment } = result;
             console.log(`AI enrichment: ${aiEnrichment.enrichedFeatures.length} features enriched (${aiEnrichment.tokenUsage.input + aiEnrichment.tokenUsage.output} tokens)`);
         }
-        else if (!process.env.ANTHROPIC_API_KEY) {
-            console.log('Tip: set ANTHROPIC_API_KEY to enable AI-powered enrichment');
+        else if (!process.env.ANTHROPIC_API_KEY && !process.env.OPENAI_API_KEY && !process.env.LLM_PROVIDER) {
+            console.log('Tip: configure ANTHROPIC_API_KEY, OPENAI_API_KEY, or LLM_PROVIDER to enable AI-powered enrichment');
         }
     }
     const { plan, planPath, ciSummaryMarkdown, ciSummaryPath } = result;
-    // Write CI summary to an additional path if --ci-comment-path was specified
-    if (args.ciCommentPath) {
-        writeCiSummary(reportRoot, ciSummaryMarkdown, args.ciCommentPath);
+    let planReport = plan;
+    let combinedSummaryMarkdown = ciSummaryMarkdown;
+    let crewSummaryPath = '';
+    let crewMarkdownPath = '';
+    let crewTestPlanPath = '';
+    if (args.crew) {
+        try {
+            const crew = await runPlanCrewAnalysis(plan, config, args);
+            planReport = {
+                ...plan,
+                crew,
+            };
+            combinedSummaryMarkdown = appendCrewToSummary(ciSummaryMarkdown, crew, plan);
+            const artifacts = writeCrewArtifacts(reportRoot, crew, plan);
+            crewSummaryPath = artifacts.crewSummaryPath;
+            crewMarkdownPath = artifacts.crewMarkdownPath;
+            crewTestPlanPath = artifacts.crewTestPlanPath;
+            writeFileSync(planPath, JSON.stringify(planReport, null, 2), 'utf-8');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`Crew analysis unavailable: ${message}`);
+        }
     }
-    const summaryPath = ciSummaryPath;
+    writeCiSummary(reportRoot, combinedSummaryMarkdown);
+    const summaryPath = args.ciCommentPath
+        ? writeCiSummary(reportRoot, combinedSummaryMarkdown, args.ciCommentPath)
+        : ciSummaryPath;
     // Compute metrics paths (api already wrote metrics; derive paths for GHA output)
     const metricsEventsPath = join(reportRoot, '.e2e-ai-agents/metrics.jsonl');
     const metricsSummaryPath = join(reportRoot, '.e2e-ai-agents/metrics-summary.json');
     const ghaOutput = args.githubOutputPath || process.env.GITHUB_OUTPUT;
     if (ghaOutput) {
-        appendFileSync(ghaOutput, `run_set=${plan.runSet}\n`);
-        appendFileSync(ghaOutput, `action=${plan.decision.action}\n`);
-        appendFileSync(ghaOutput, `confidence=${plan.confidence}\n`);
-        appendFileSync(ghaOutput, `enforcement_mode=${plan.enforcement.mode}\n`);
-        appendFileSync(ghaOutput, `enforcement_should_fail=${plan.enforcement.shouldFail}\n`);
-        appendFileSync(ghaOutput, `recommended_tests_count=${plan.recommendedTests.length}\n`);
-        appendFileSync(ghaOutput, `required_new_tests_count=${plan.requiredNewTests.length}\n`);
+        appendFileSync(ghaOutput, `run_set=${planReport.runSet}\n`);
+        appendFileSync(ghaOutput, `action=${planReport.decision.action}\n`);
+        appendFileSync(ghaOutput, `confidence=${planReport.confidence}\n`);
+        appendFileSync(ghaOutput, `enforcement_mode=${planReport.enforcement.mode}\n`);
+        appendFileSync(ghaOutput, `enforcement_should_fail=${planReport.enforcement.shouldFail}\n`);
+        appendFileSync(ghaOutput, `recommended_tests_count=${planReport.recommendedTests.length}\n`);
+        appendFileSync(ghaOutput, `required_new_tests_count=${planReport.requiredNewTests.length}\n`);
         appendFileSync(ghaOutput, `plan_path=${planPath}\n`);
         appendFileSync(ghaOutput, `summary_path=${summaryPath}\n`);
         appendFileSync(ghaOutput, `metrics_events_path=${metricsEventsPath}\n`);
         appendFileSync(ghaOutput, `metrics_summary_path=${metricsSummaryPath}\n`);
+        appendFileSync(ghaOutput, `crew_enabled=${planReport.crew ? 'true' : 'false'}\n`);
+        appendFileSync(ghaOutput, `crew_workflow=${planReport.crew?.workflow || ''}\n`);
+        appendFileSync(ghaOutput, `crew_summary_path=${crewSummaryPath}\n`);
+        appendFileSync(ghaOutput, `crew_markdown_path=${crewMarkdownPath}\n`);
+        appendFileSync(ghaOutput, `crew_test_plan_path=${crewTestPlanPath}\n`);
+        appendFileSync(ghaOutput, `crew_impacted_flows=${planReport.crew?.summary.impactedFlows || 0}\n`);
+        appendFileSync(ghaOutput, `crew_strategy_entries=${planReport.crew?.summary.strategyEntries || 0}\n`);
+        appendFileSync(ghaOutput, `crew_test_designs=${planReport.crew?.summary.testDesigns || 0}\n`);
     }
-    console.log(`Suggested run set: ${plan.runSet} (confidence ${plan.confidence})`);
-    console.log(`Decision: ${plan.decision.action} - ${plan.decision.summary}`);
-    console.log(`Enforcement: ${plan.enforcement.mode} (shouldFail=${plan.enforcement.shouldFail})`);
+    console.log(`Suggested run set: ${planReport.runSet} (confidence ${planReport.confidence})`);
+    console.log(`Decision: ${planReport.decision.action} - ${planReport.decision.summary}`);
+    console.log(`Enforcement: ${planReport.enforcement.mode} (shouldFail=${planReport.enforcement.shouldFail})`);
     console.log(`Plan data: ${planPath}`);
     console.log(`CI summary: ${summaryPath}`);
+    if (planReport.crew) {
+        console.log(`Crew workflow: ${planReport.crew.workflow} (impactedFlows=${planReport.crew.summary.impactedFlows}, strategyEntries=${planReport.crew.summary.strategyEntries}, testDesigns=${planReport.crew.summary.testDesigns})`);
+        console.log(`Crew summary: ${crewSummaryPath}`);
+        console.log(`Crew test plan: ${crewTestPlanPath}`);
+    }
     console.log(`Plan metrics: ${metricsSummaryPath}`);
-    const failOnLegacyFlag = args.failOnMustAddTests && plan.decision.action === 'must-add-tests';
-    if (failOnLegacyFlag || plan.enforcement.shouldFail) {
+    const failOnLegacyFlag = args.failOnMustAddTests && planReport.decision.action === 'must-add-tests';
+    if (failOnLegacyFlag || planReport.enforcement.shouldFail) {
         process.exit(2);
     }
 }

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

@@ -0,0 +1,266 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { CrossImpactAgent } from '../../agents/cross-impact.js';
+import { ImpactAnalystAgent } from '../../agents/impact-analyst.js';
+import { RegressionAdvisorAgent } from '../../agents/regression-advisor.js';
+import { StrategistAgent } from '../../agents/strategist.js';
+import { TestDesignerAgent } from '../../agents/test-designer.js';
+import { CrewOrchestrator } from '../../crew/orchestrator.js';
+const VALID_WORKFLOWS = new Set(['full-qa', 'quick-check', 'design-only']);
+function uniqueStrings(values) {
+    return Array.from(new Set(values.filter(Boolean)));
+}
+function singleLine(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+function chooseCrewWorkflow(explicitWorkflow, plan) {
+    if (explicitWorkflow && VALID_WORKFLOWS.has(explicitWorkflow)) {
+        return explicitWorkflow;
+    }
+    if (plan.decision.action === 'must-add-tests' || plan.metrics.uncoveredP0P1Flows > 0) {
+        return 'design-only';
+    }
+    return 'quick-check';
+}
+function registerCrewAgents(orchestrator) {
+    orchestrator.registerAgent(new ImpactAnalystAgent());
+    orchestrator.registerAgent(new StrategistAgent());
+    orchestrator.registerAgent(new TestDesignerAgent());
+    orchestrator.registerAgent(new CrossImpactAgent());
+    orchestrator.registerAgent(new RegressionAdvisorAgent());
+}
+export async function runPlanCrewAnalysis(plan, config, args) {
+    const reportRoot = config.testsRoot || config.path;
+    const workflow = chooseCrewWorkflow(args.crewWorkflow, plan);
+    const normalizedProvider = config.llm.provider?.trim().toLowerCase();
+    const providerOverride = normalizedProvider && normalizedProvider !== 'auto' ? normalizedProvider : 'auto';
+    const orchestrator = new CrewOrchestrator();
+    registerCrewAgents(orchestrator);
+    const result = await orchestrator.run({
+        appPath: config.path,
+        testsRoot: reportRoot,
+        gitSince: args.gitSince || config.git.since,
+        routeFamilies: config.routeFamilies,
+        apiSurface: config.apiSurface,
+        workflow,
+        providerOverride: providerOverride === 'auto' ? undefined : providerOverride,
+        budgetUSD: args.budgetUSD,
+        dryRun: args.dryRun,
+    });
+    const ctx = result.context;
+    const highRiskCrossImpacts = ctx.crossImpacts.filter((entry) => entry.riskLevel === 'high');
+    const manualReviewEntries = ctx.strategyEntries.filter((entry) => entry.approach === 'manual-review');
+    return {
+        workflow,
+        providerOverride,
+        summary: {
+            impactedFlows: ctx.impactedFlows.length,
+            strategyEntries: ctx.strategyEntries.length,
+            testDesigns: ctx.testDesigns.length,
+            crossImpacts: ctx.crossImpacts.length,
+            highRiskCrossImpacts: highRiskCrossImpacts.length,
+            regressionRisks: ctx.regressionRisks.length,
+            findings: ctx.findings.length,
+            generatedSpecs: ctx.generatedSpecs.length,
+            manualReviewEntries: manualReviewEntries.length,
+            totalCostUSD: Number(ctx.usage.totalCost.toFixed(4)),
+            totalTokens: ctx.usage.totalTokens,
+        },
+        impactedFlows: ctx.impactedFlows,
+        strategyEntries: ctx.strategyEntries,
+        testDesigns: ctx.testDesigns,
+        crossImpacts: ctx.crossImpacts,
+        regressionRisks: ctx.regressionRisks,
+        findings: ctx.findings,
+        warnings: uniqueStrings([...ctx.warnings, ...result.warnings]),
+        timings: result.timings,
+    };
+}
+export function buildCrewMarkdown(crew, plan) {
+    const totalCases = crew.testDesigns.reduce((n, td) => n + td.testCases.length, 0);
+    const gapFamilies = new Set((plan?.gapDetails ?? []).map((g) => g.id));
+    const gapDesigns = gapFamilies.size > 0
+        ? crew.testDesigns.filter((td) => Array.from(gapFamilies).some((fam) => td.flowId.startsWith(fam) || td.flowName.toLowerCase().includes(fam.replace(/_/g, ' '))))
+        : [];
+    const gapCases = gapDesigns.reduce((n, td) => n + td.testCases.length, 0);
+    const gapP0Cases = gapDesigns.reduce((n, td) => n + td.testCases.filter((tc) => tc.priority === 'P0').length, 0);
+    const lines = [
+        '### Crew Insights',
+        '',
+        `Workflow: \`${crew.workflow}\``,
+        `Impacted flows: **${crew.summary.impactedFlows}**`,
+        `Structured test designs: **${crew.summary.testDesigns}** flows, **${totalCases}** test cases`,
+    ];
+    if (gapFamilies.size > 0 && gapDesigns.length > 0) {
+        lines.push(`Gap-focused: **${gapDesigns.length}** flows, **${gapCases}** test cases (**${gapP0Cases}** P0)`);
+    }
+    lines.push(`Cross-impacts: **${crew.summary.crossImpacts}** (${crew.summary.highRiskCrossImpacts} high risk)`, `Estimated AI cost: **$${crew.summary.totalCostUSD.toFixed(4)}**`);
+    if (crew.strategyEntries.length > 0) {
+        lines.push('');
+        lines.push('Top Strategy Recommendations:');
+        for (const entry of crew.strategyEntries.slice(0, 5)) {
+            lines.push(`- ${entry.priority} ${entry.flowName} -> ${entry.approach} (${entry.crossImpactRisk} cross-impact risk)`);
+        }
+    }
+    if (crew.testDesigns.length > 0) {
+        lines.push('');
+        lines.push('Structured Test Designs:');
+        for (const design of crew.testDesigns.slice(0, 3)) {
+            lines.push(`- ${design.flowName}: ${design.testCases.length} designed test case(s)`);
+        }
+    }
+    const riskyCrossImpacts = crew.crossImpacts.filter((entry) => entry.riskLevel === 'high');
+    if (riskyCrossImpacts.length > 0) {
+        lines.push('');
+        lines.push('High-Risk Cross-Impacts:');
+        for (const entry of riskyCrossImpacts.slice(0, 5)) {
+            lines.push(`- ${entry.sourceFamily} -> ${entry.affectedFamily}: ${entry.sharedDependency}`);
+        }
+    }
+    if (crew.findings.length > 0) {
+        lines.push('');
+        lines.push('Crew Findings:');
+        for (const finding of crew.findings.slice(0, 5)) {
+            lines.push(`- ${finding.severity} ${finding.type}: ${finding.summary}`);
+        }
+    }
+    if (crew.warnings.length > 0) {
+        lines.push('');
+        lines.push('Crew Warnings:');
+        for (const warning of crew.warnings.slice(0, 5)) {
+            lines.push(`- ${singleLine(warning)}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function appendCrewToSummary(baseMarkdown, crew, plan) {
+    return `${baseMarkdown}\n\n---\n\n${buildCrewMarkdown(crew, plan)}`;
+}
+/**
+ * Build a full structured test plan as a Markdown document.
+ * Sections: gap flows first (P0 cases expanded), then covered-flow smoke tests.
+ */
+export function buildCrewTestPlan(crew, plan) {
+    const gapFamilies = new Set((plan?.gapDetails ?? []).map((g) => g.id));
+    const totalCases = crew.testDesigns.reduce((n, td) => n + td.testCases.length, 0);
+    // Split designs into gap-related and coverage-expansion
+    const gapDesigns = [];
+    const coveredDesigns = [];
+    for (const td of crew.testDesigns) {
+        // Match by flowId prefix against gap family ids
+        const isGap = Array.from(gapFamilies).some((fam) => td.flowId.startsWith(fam) || td.flowName.toLowerCase().includes(fam.replace(/_/g, ' ')));
+        if (isGap) {
+            gapDesigns.push(td);
+        }
+        else {
+            coveredDesigns.push(td);
+        }
+    }
+    const gapCases = gapDesigns.reduce((n, td) => n + td.testCases.length, 0);
+    const coveredCases = coveredDesigns.reduce((n, td) => n + td.testCases.length, 0);
+    const lines = [
+        '# Crew Test Plan',
+        '',
+        `> Auto-generated by e2e-agents crew (\`${crew.workflow}\` workflow)`,
+        '',
+        '## Summary',
+        '',
+        `| Metric | Count |`,
+        `|--------|-------|`,
+        `| Gap flows (missing tests) | ${gapDesigns.length} flows, **${gapCases} test cases** |`,
+        `| Covered flows (expansion) | ${coveredDesigns.length} flows, ${coveredCases} test cases |`,
+        `| Total | ${crew.testDesigns.length} flows, ${totalCases} test cases |`,
+        `| High-risk cross-impacts | ${crew.summary.highRiskCrossImpacts} |`,
+        `| AI cost | $${crew.summary.totalCostUSD.toFixed(4)} |`,
+        '',
+    ];
+    // Priority action items
+    if (gapDesigns.length > 0) {
+        lines.push('## Priority: Gap Flows (Missing Tests)');
+        lines.push('');
+        lines.push('These flows have **no existing E2E coverage** and should be addressed first.');
+        lines.push('');
+        for (const td of gapDesigns) {
+            const strategy = crew.strategyEntries.find((s) => s.flowId === td.flowId);
+            const approach = strategy?.approach ?? 'full-test';
+            const risk = strategy?.crossImpactRisk ?? 'unknown';
+            const p0Cases = td.testCases.filter((tc) => tc.priority === 'P0');
+            const p1Cases = td.testCases.filter((tc) => tc.priority === 'P1');
+            lines.push(`### ${td.flowName}`);
+            lines.push('');
+            lines.push(`Strategy: **${approach}** | Cross-impact risk: **${risk}** | ${td.testCases.length} cases (${p0Cases.length} P0, ${p1Cases.length} P1)`);
+            lines.push('');
+            // Show P0 cases expanded
+            if (p0Cases.length > 0) {
+                lines.push('**P0 — Must test:**');
+                lines.push('');
+                for (const tc of p0Cases) {
+                    lines.push(`- [ ] **${tc.name}** (${tc.type})`);
+                    if (tc.preconditions.length > 0) {
+                        lines.push(`  - Preconditions: ${tc.preconditions.join('; ')}`);
+                    }
+                    lines.push(`  - Steps: ${tc.steps.join(' → ')}`);
+                    lines.push(`  - Expected: ${tc.expectedOutcome}`);
+                }
+                lines.push('');
+            }
+            // Show P1 as a collapsed checklist
+            if (p1Cases.length > 0) {
+                lines.push(`<details><summary>P1 — Should test (${p1Cases.length})</summary>`);
+                lines.push('');
+                for (const tc of p1Cases) {
+                    lines.push(`- [ ] **${tc.name}** (${tc.type}) — ${tc.expectedOutcome}`);
+                }
+                lines.push('');
+                lines.push('</details>');
+                lines.push('');
+            }
+        }
+    }
+    // Covered flow expansion — collapsed by default
+    if (coveredDesigns.length > 0) {
+        lines.push('## Covered Flows (Regression / Expansion)');
+        lines.push('');
+        lines.push('These flows already have specs. The test cases below extend coverage for changes in this PR.');
+        lines.push('');
+        for (const td of coveredDesigns) {
+            const strategy = crew.strategyEntries.find((s) => s.flowId === td.flowId);
+            const approach = strategy?.approach ?? 'smoke-test';
+            const p0Count = td.testCases.filter((tc) => tc.priority === 'P0').length;
+            lines.push(`<details><summary><strong>${td.flowName}</strong> — ${approach} | ${td.testCases.length} cases (${p0Count} P0)</summary>`);
+            lines.push('');
+            for (const tc of td.testCases) {
+                lines.push(`- [ ] **${tc.name}** (${tc.priority}, ${tc.type}) — ${tc.expectedOutcome}`);
+            }
+            lines.push('');
+            lines.push('</details>');
+            lines.push('');
+        }
+    }
+    // Cross-impacts section
+    const highRisk = crew.crossImpacts.filter((ci) => ci.riskLevel === 'high');
+    if (highRisk.length > 0) {
+        lines.push('## High-Risk Cross-Impacts');
+        lines.push('');
+        lines.push('These cross-family dependencies should be verified during release testing:');
+        lines.push('');
+        for (const ci of highRisk) {
+            lines.push(`- **${ci.sourceFamily}** → **${ci.affectedFamily}**: ${ci.sharedDependency}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function writeCrewArtifacts(reportRoot, crew, plan) {
+    const outputDir = join(reportRoot, '.e2e-ai-agents');
+    mkdirSync(outputDir, { recursive: true });
+    const crewSummaryPath = join(outputDir, 'crew-summary.json');
+    const crewMarkdownPath = join(outputDir, 'crew-summary.md');
+    const crewTestPlanPath = join(outputDir, 'crew-test-plan.md');
+    writeFileSync(crewSummaryPath, JSON.stringify(crew, null, 2), 'utf-8');
+    writeFileSync(crewMarkdownPath, buildCrewMarkdown(crew, plan), 'utf-8');
+    writeFileSync(crewTestPlanPath, buildCrewTestPlan(crew, plan), 'utf-8');
+    return { crewSummaryPath, crewMarkdownPath, crewTestPlanPath };
+}

package/dist/esm/cli/parse_args.js

@@ -56,6 +56,7 @@ const FLAGS = {
     '--pipeline-parallel': { key: 'pipelineParallel', type: 'boolean' },
     '--pipeline-dry-run': { key: 'pipelineDryRun', type: 'boolean' },
     '--fail-on-must-add-tests': { key: 'failOnMustAddTests', type: 'boolean' },
+    '--crew': { key: 'crew', type: 'boolean' },
     '--create-pr': { key: 'createPr', type: 'boolean' },
     '--dry-run': { key: 'dryRun', type: 'boolean' },
     '--generate': { key: 'analyzeGenerate', type: 'boolean' },
@@ -99,6 +100,7 @@ const FLAGS = {
     '--output': { key: 'trainOutput', type: 'string' },
     '--server-path': { key: 'serverPath', type: 'string' },
     '--workflow': { key: 'crewWorkflow', type: 'string' },
+    '--crew-workflow': { key: 'crewWorkflow', type: 'string' },
     // -- number flags (with isFinite guard) --
     '--pipeline-scenarios': { key: 'pipelineScenarios', type: 'number' },
     '--time': { key: 'timeLimitMinutes', type: 'number' },

package/dist/esm/cli/usage.js

@@ -56,6 +56,8 @@ export function printUsage() {
         '  --policy-risky-patterns <globs>     Comma-separated risky file globs',
         '  --policy-enforcement-mode <mode>    advisory | warn | block',
         '  --policy-block-actions <actions>    Comma-separated CI actions to block/warn',
+        '  --crew                               Run Crew enrichment and attach insights to plan output',
+        '  --crew-workflow <name>               full-qa | quick-check | design-only',
         '  --ci-comment-path <path>            Write CI markdown summary',
         '  --github-output <path>              Write GitHub Actions outputs',
         '  --fail-on-must-add-tests            Exit non-zero on must-add-tests decision',

package/dist/esm/mcp-server.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 // Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
 // See LICENSE.txt for license information.
 /**
@@ -6,7 +7,7 @@
  */
 import { spawnSync } from 'child_process';
 import { readFileSync, writeFileSync, existsSync, realpathSync } from 'fs';
-import { resolve } from 'path';
+import { join, resolve, dirname } from 'path';
 import { globSync } from 'glob';
 /**
  * SECURITY: Path validation helper
@@ -471,12 +472,152 @@ export class E2EAgentsMCPServer {
     }
 }
 /**
- * Start MCP server
- * Usage: node dist/mcp-server.js
+ * Read the package version at runtime so the MCP initialize response
+ * always reflects the installed version.
  */
+function getPackageVersion() {
+    try {
+        const pkgPath = join(dirname(__dirname), 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.version || '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/**
+ * Encode a JSON-RPC message with Content-Length framing.
+ * Exported for testability.
+ */
+export function encodeJsonRpcMessage(message) {
+    const body = JSON.stringify(message);
+    return `Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`;
+}
+/**
+ * Parse Content-Length framed JSON-RPC messages from a buffer.
+ * Returns parsed messages and the remaining (unconsumed) buffer.
+ * Exported for testability.
+ */
+export function parseJsonRpcFrames(input) {
+    const messages = [];
+    let buffer = Buffer.from(input);
+    while (true) {
+        const headerEnd = buffer.indexOf('\r\n\r\n');
+        if (headerEnd === -1)
+            break;
+        const headerText = buffer.slice(0, headerEnd).toString('utf8');
+        const match = headerText.match(/Content-Length:\s*(\d+)/i);
+        if (!match) {
+            buffer = Buffer.alloc(0);
+            break;
+        }
+        const contentLength = Number(match[1]);
+        const messageEnd = headerEnd + 4 + contentLength;
+        if (buffer.length < messageEnd)
+            break;
+        const body = buffer.slice(headerEnd + 4, messageEnd).toString('utf8');
+        buffer = buffer.slice(messageEnd);
+        messages.push(JSON.parse(body));
+    }
+    return { messages, remainder: buffer };
+}
+/**
+ * Handle a single JSON-RPC message against the server.
+ * Returns the response message (or null for notifications).
+ * Exported for testability.
+ */
+export async function handleJsonRpcMessage(server, message) {
+    const { id, method, params } = message;
+    const version = getPackageVersion();
+    if (method === 'initialize') {
+        return {
+            jsonrpc: '2.0',
+            id,
+            result: {
+                protocolVersion: typeof params?.protocolVersion === 'string' ? params.protocolVersion : '2024-11-05',
+                capabilities: { tools: {}, resources: {}, prompts: {} },
+                serverInfo: { name: 'e2e-agents-mcp', version },
+            },
+        };
+    }
+    if (method === 'notifications/initialized' || method === 'initialized') {
+        return null;
+    }
+    if (method === 'tools/list') {
+        return {
+            jsonrpc: '2.0',
+            id,
+            result: {
+                tools: server.getTools().map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                })),
+            },
+        };
+    }
+    if (method === 'tools/call') {
+        const resultText = await server.callTool(typeof params?.name === 'string' ? params.name : '', typeof params?.arguments === 'object' && params.arguments !== null ? params.arguments : {});
+        let isError = false;
+        try {
+            const parsed = JSON.parse(resultText);
+            isError = Boolean(parsed.error);
+        }
+        catch {
+            isError = false;
+        }
+        return {
+            jsonrpc: '2.0',
+            id,
+            result: { content: [{ type: 'text', text: resultText }], isError },
+        };
+    }
+    if (method === 'resources/list') {
+        return { jsonrpc: '2.0', id, result: { resources: [] } };
+    }
+    if (method === 'prompts/list') {
+        return { jsonrpc: '2.0', id, result: { prompts: [] } };
+    }
+    if (method === 'ping') {
+        return { jsonrpc: '2.0', id, result: {} };
+    }
+    return { jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } };
+}
+/**
+ * Start MCP server over stdio using Content-Length framed JSON-RPC messages.
+ */
+export function startStdioServer(repoRoot = process.cwd()) {
+    const server = new E2EAgentsMCPServer(repoRoot);
+    let buffer = Buffer.alloc(0);
+    const sendMessage = (message) => {
+        process.stdout.write(encodeJsonRpcMessage(message));
+    };
+    const sendError = (id, code, msg) => {
+        sendMessage({ jsonrpc: '2.0', id, error: { code, message: msg } });
+    };
+    const processBuffer = () => {
+        const { messages, remainder } = parseJsonRpcFrames(buffer);
+        buffer = remainder;
+        for (const parsed of messages) {
+            void handleJsonRpcMessage(server, parsed)
+                .then((response) => {
+                if (response)
+                    sendMessage(response);
+            })
+                .catch((error) => {
+                sendError(parsed.id ?? null, -32603, error instanceof Error ? error.message : String(error));
+            });
+        }
+    };
+    process.stdin.on('data', (chunk) => {
+        buffer = Buffer.concat([buffer, chunk]);
+        processBuffer();
+    });
+    process.stdin.on('end', () => {
+        process.exit(0);
+    });
+}
 if (require.main === module) {
-    const server = new E2EAgentsMCPServer();
-    console.log('E2E Agents MCP Server started');
-    console.log('Tools:', server.getTools().map((t) => t.name).join(', '));
+    startStdioServer();
 }
 export default E2EAgentsMCPServer;

package/dist/esm/provider_factory.js

@@ -141,6 +141,17 @@ export class LLMProviderFactory {
             '3. Set OPENAI_API_KEY environment variable\n' +
             '4. Set LLM_PROVIDER environment variable');
     }
+    /**
+     * Create provider from an explicit preference when supplied, otherwise
+     * fall back to environment auto-detection.
+     */
+    static async createFromPreference(providerPreference) {
+        const normalized = providerPreference?.trim().toLowerCase();
+        if (!normalized || normalized === 'auto') {
+            return this.createFromEnv();
+        }
+        return this.createFromString(normalized);
+    }
     /**
      * Create provider from simple string format
      *

package/dist/mcp-server.d.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 interface Tool {
     name: string;
     description: string;
@@ -31,5 +32,37 @@ export declare class E2EAgentsMCPServer {
      */
     getTools(): Tool[];
 }
+/**
+ * Encode a JSON-RPC message with Content-Length framing.
+ * Exported for testability.
+ */
+export declare function encodeJsonRpcMessage(message: Record<string, unknown>): string;
+/**
+ * Parse Content-Length framed JSON-RPC messages from a buffer.
+ * Returns parsed messages and the remaining (unconsumed) buffer.
+ * Exported for testability.
+ */
+export declare function parseJsonRpcFrames(input: Buffer): {
+    messages: Array<{
+        id?: unknown;
+        method?: string;
+        params?: Record<string, unknown>;
+    }>;
+    remainder: Buffer<ArrayBuffer>;
+};
+/**
+ * Handle a single JSON-RPC message against the server.
+ * Returns the response message (or null for notifications).
+ * Exported for testability.
+ */
+export declare function handleJsonRpcMessage(server: E2EAgentsMCPServer, message: {
+    id?: unknown;
+    method?: string;
+    params?: Record<string, unknown>;
+}): Promise<Record<string, unknown> | null>;
+/**
+ * Start MCP server over stdio using Content-Length framed JSON-RPC messages.
+ */
+export declare function startStdioServer(repoRoot?: string): void;
 export default E2EAgentsMCPServer;
 //# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAaA,UAAU,IAAI;IACV,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AA4GD;;;GAGG;AACH,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,WAAW,CAAc;gBAErB,QAAQ,GAAE,MAAsB;IAM5C,OAAO,CAAC,WAAW;IAmGnB;;;OAGG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAwB5E,OAAO,CAAC,aAAa;IA6BrB,OAAO,CAAC,QAAQ;IAmBhB,OAAO,CAAC,SAAS;IAwCjB,OAAO,CAAC,QAAQ;IAyDhB,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,oBAAoB;IAqD5B,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,sBAAsB;IAW9B;;OAEG;IACH,QAAQ,IAAI,IAAI,EAAE;CAGrB;AAYD,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":";AAeA,UAAU,IAAI;IACV,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AA4GD;;;GAGG;AACH,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,WAAW,CAAc;gBAErB,QAAQ,GAAE,MAAsB;IAM5C,OAAO,CAAC,WAAW;IAmGnB;;;OAGG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAwB5E,OAAO,CAAC,aAAa;IA6BrB,OAAO,CAAC,QAAQ;IAmBhB,OAAO,CAAC,SAAS;IAwCjB,OAAO,CAAC,QAAQ;IAyDhB,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,oBAAoB;IAqD5B,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,sBAAsB;IAW9B;;OAEG;IACH,QAAQ,IAAI,IAAI,EAAE;CAGrB;AAgBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAG7E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAC,QAAQ,EAAE,KAAK,CAAC;QAAC,EAAE,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAC,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,CAAA;CAAC,CA0BtK;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE;IAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAC,GAC3E,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAmEzC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,GAAE,MAAsB,GAAG,IAAI,CAmCvE;AAMD,eAAe,kBAAkB,CAAC"}