@contextrail/code-review-agent 0.1.1-alpha.0

package/dist/index.js

@@ -0,0 +1,603 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { loadConfig, validateConfig } from './config/index.js';
+import { DEFAULT_ORCHESTRATOR_MODEL, DEFAULT_REVIEWER_MODEL } from './config/defaults.js';
+import { createLogger, parseLogLevel } from './logging/logger.js';
+import { McpClient } from './mcp/client.js';
+import { buildReviewInputs, triagePr } from './review-inputs/index.js';
+import { runOrchestrator } from './orchestrator/agentic-orchestrator.js';
+import { runReviewerLoop } from './reviewers/executor.js';
+import { aggregateResults, writeResult, writeTokenBudgetMetrics } from './output/writer.js';
+import { metadataSchema } from './output/schema.js';
+import { generateReviewDecision, normalizeDecisionWithSynthesis, synthesizeFindings } from './output/aggregator.js';
+const parseArgs = (args) => {
+    const parsed = {};
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (!arg) {
+            i += 1;
+            continue;
+        }
+        if (arg === '-h' || arg === '--help') {
+            parsed.help = true;
+            i += 1;
+        }
+        else if (arg === '--repo' && i + 1 < args.length) {
+            parsed.repo = args[i + 1];
+            i += 2;
+        }
+        else if (arg === '--from' && i + 1 < args.length) {
+            parsed.from = args[i + 1];
+            i += 2;
+        }
+        else if (arg === '--to' && i + 1 < args.length) {
+            parsed.to = args[i + 1];
+            i += 2;
+        }
+        else if (arg === '--output' && i + 1 < args.length) {
+            parsed.output = args[i + 1];
+            i += 2;
+        }
+        else if (arg === '--files' && i + 1 < args.length) {
+            const raw = args[i + 1] ?? '';
+            const files = raw
+                .split(',')
+                .map((file) => file.trim())
+                .filter(Boolean);
+            if (!parsed.files) {
+                parsed.files = [];
+            }
+            parsed.files.push(...files);
+            i += 2;
+        }
+        else if (arg === '--file' && i + 1 < args.length) {
+            const file = args[i + 1];
+            if (file) {
+                if (!parsed.files) {
+                    parsed.files = [];
+                }
+                parsed.files.push(file);
+            }
+            i += 2;
+        }
+        else if (arg === '--log-level' && i + 1 < args.length) {
+            parsed.logLevel = args[i + 1];
+            i += 2;
+        }
+        else if (arg === '--pr-description' && i + 1 < args.length) {
+            parsed.prDescription = args[i + 1];
+            i += 2;
+        }
+        else if (arg === '--domains' && i + 1 < args.length) {
+            const raw = args[i + 1] ?? '';
+            const domains = raw
+                .split(',')
+                .map((domain) => domain.trim())
+                .filter(Boolean);
+            if (!parsed.domains) {
+                parsed.domains = [];
+            }
+            parsed.domains.push(...domains);
+            i += 2;
+        }
+        else if (arg === '--max-steps' && i + 1 < args.length) {
+            const value = parseInt(args[i + 1] ?? '10', 10);
+            parsed.maxSteps = Number.isNaN(value) ? undefined : value;
+            i += 2;
+        }
+        else if (arg === '--max-iterations' && i + 1 < args.length) {
+            const value = parseInt(args[i + 1] ?? '2', 10);
+            parsed.maxIterations = Number.isNaN(value) ? undefined : value;
+            i += 2;
+        }
+        else if (arg === '--aggregation-max-steps' && i + 1 < args.length) {
+            const value = parseInt(args[i + 1] ?? '5', 10);
+            parsed.aggregationMaxSteps = Number.isNaN(value) ? undefined : value;
+            i += 2;
+        }
+        else if (arg === '--max-tokens-per-file' && i + 1 < args.length) {
+            const value = parseInt(args[i + 1] ?? '20000', 10);
+            parsed.maxTokensPerFile = Number.isNaN(value) ? undefined : value;
+            i += 2;
+        }
+        else if (arg === '--context-lines' && i + 1 < args.length) {
+            const value = parseInt(args[i + 1] ?? '10', 10);
+            parsed.contextLines = Number.isNaN(value) ? undefined : value;
+            i += 2;
+        }
+        else if (!parsed.command && !arg.startsWith('-')) {
+            parsed.command = arg;
+            i += 1;
+        }
+        else {
+            i += 1;
+        }
+    }
+    return parsed;
+};
+const printHelp = (log) => {
+    log.info(`code-review-agent
+
+Usage:
+  code-review-agent review --repo <path> --from <sha> --to <sha> [--output <dir>]
+  code-review-agent review --repo <path> --files <file1,file2> [--output <dir>]
+  code-review-agent review --repo <path> --file <file> [--file <file> ...] [--output <dir>]
+
+Commands:
+  review    Run code review on git diff
+
+Options:
+  --repo <path>              Repository path (default: current directory)
+  --from <sha>               Base commit SHA (required)
+  --to <sha>                  Head commit SHA (required)
+  --files <list>              Comma-separated list of files to review
+  --file <path>               File to review (repeatable)
+  --output <dir>              Output directory (default: ./review)
+  --log-level <lv>            Log level: debug|info|warn|error|silent (overrides DEBUG)
+  --max-steps <n>             Maximum LLM steps per call (default: 10)
+  --max-iterations <n>        Maximum reviewer validation iterations (default: 2)
+  --aggregation-max-steps <n> Maximum steps for aggregation (default: 5)
+  --max-tokens-per-file <n>   Token budget for surrounding context per file (default: 20000)
+  --context-lines <n>         Lines of context around changes (default: 10)
+  --pr-description <text>     PR description to include as context (optional)
+  --domains <list>            Comma-separated review focus domains (optional)
+  -h, --help                  Show this help message
+
+Environment Variables:
+  CONTEXTRAIL_MCP_SERVER_URL  ContextRail MCP server URL (required)
+  CONTEXTRAIL_MCP_JWT_TOKEN   ContextRail MCP authentication token (required)
+  OPENROUTER_API_KEY      OpenRouter API key (required)
+  LLM_MODEL_ORCHESTRATOR  Model for orchestrator (default: anthropic/claude-haiku-4.5)
+  LLM_MODEL_REVIEWER      Model for reviewers (default: anthropic/claude-haiku-4.5)
+  MAX_STEPS               Maximum LLM steps per call (default: 10)
+  MAX_ITERATIONS          Maximum reviewer validation iterations (default: 2)
+  AGGREGATION_MAX_STEPS   Maximum steps for aggregation (default: 5)
+  MAX_TOKENS_PER_FILE     Token budget for surrounding context per file (default: 20000)
+  CONTEXT_LINES           Lines of context around changes (default: 10)
+  REVIEW_DOMAINS          Comma-separated review focus domains (optional)
+
+Examples:
+  code-review-agent review --repo . --from HEAD^ --to HEAD
+  code-review-agent review --repo . --files src/a.ts,src/b.ts
+  code-review-agent review --repo . --file src/a.ts --file src/b.ts
+  code-review-agent review --repo /path/to/repo --from abc123 --to def456 --output ./review-results
+`);
+};
+const validateArgs = (args) => {
+    if (args.help) {
+        return;
+    }
+    if (args.command !== 'review') {
+        throw new Error(`Unknown command: ${args.command ?? 'none'}. Use 'review' or see --help.`);
+    }
+    const hasFileList = Array.isArray(args.files) && args.files.length > 0;
+    if (!hasFileList) {
+        if (!args.from) {
+            throw new Error('Missing required argument: --from');
+        }
+        if (!args.to) {
+            throw new Error('Missing required argument: --to');
+        }
+    }
+};
+const main = async () => {
+    try {
+        const args = parseArgs(process.argv.slice(2));
+        if (args.help) {
+            // Keep --help available even when required env vars are not set.
+            const helpLog = createLogger(parseLogLevel(args.logLevel ?? process.env.DEBUG));
+            printHelp(helpLog);
+            process.exit(0);
+        }
+        const config = loadConfig();
+        const log = createLogger(parseLogLevel(args.logLevel ?? config.logLevel));
+        log.debug(`Log level set to ${args.logLevel ?? config.logLevel}`);
+        // Validate arguments
+        validateArgs(args);
+        // Override config with CLI args
+        if (args.maxSteps !== undefined) {
+            config.maxSteps = args.maxSteps;
+        }
+        if (args.maxIterations !== undefined) {
+            config.maxIterations = args.maxIterations;
+        }
+        if (args.aggregationMaxSteps !== undefined) {
+            config.aggregationMaxSteps = args.aggregationMaxSteps;
+        }
+        if (args.maxTokensPerFile !== undefined) {
+            config.maxTokensPerFile = args.maxTokensPerFile;
+        }
+        if (args.contextLines !== undefined) {
+            config.contextLines = args.contextLines;
+        }
+        if (args.prDescription !== undefined) {
+            config.prDescription = args.prDescription;
+        }
+        if (args.domains && args.domains.length > 0) {
+            config.reviewDomains = args.domains;
+        }
+        // Load and validate config
+        const validatedConfig = validateConfig(config);
+        // Set defaults
+        const repoPath = args.repo ?? process.cwd();
+        const outputDir = args.output ?? path.join(process.cwd(), 'review');
+        log.info('Starting code review...');
+        log.info(`Repository: ${repoPath}`);
+        log.info(`Output: ${outputDir}`);
+        if (args.files && args.files.length > 0) {
+            log.info(`Files: ${args.files.join(', ')}`);
+        }
+        else {
+            log.info(`From: ${args.from}`);
+            log.info(`To: ${args.to}`);
+        }
+        // Connect MCP client
+        const mcpClient = new McpClient({
+            serverUrl: validatedConfig.mcpServerUrl,
+            authToken: validatedConfig.mcpAuthToken,
+            clientName: 'code-review-agent',
+            clientVersion: '0.1.0',
+            logger: log,
+        });
+        mcpClientInstance = mcpClient; // Store for graceful shutdown
+        await mcpClient.connect();
+        log.info('Connected to MCP server');
+        try {
+            // Build review inputs
+            log.info('Building review inputs...');
+            const inputs = args.files && args.files.length > 0
+                ? await buildReviewInputs({
+                    mode: 'file-list',
+                    files: args.files,
+                    basePath: repoPath,
+                    surroundingContext: {
+                        enabled: true,
+                        maxTokensPerFile: validatedConfig.maxTokensPerFile,
+                        contextLines: validatedConfig.contextLines,
+                    },
+                })
+                : await buildReviewInputs({
+                    mode: 'diff',
+                    repoPath,
+                    from: args.from,
+                    to: args.to,
+                    surroundingContext: {
+                        enabled: true,
+                        maxTokensPerFile: validatedConfig.maxTokensPerFile,
+                        contextLines: validatedConfig.contextLines,
+                    },
+                });
+            log.info(`Found ${inputs.files.length} files to review`);
+            if (inputs.files.length > 0) {
+                log.debug(`  Files: ${inputs.files.slice(0, 10).join(', ')}${inputs.files.length > 10 ? ` ... and ${inputs.files.length - 10} more` : ''}`);
+            }
+            // Triage PR to determine if it's trivial
+            const triageResult = triagePr(inputs);
+            log.info(`PR triage: ${triageResult.reason}`);
+            if (triageResult.isTrivial) {
+                log.info(`Trivial PR detected (${triageResult.isDocsOnly ? 'docs-only' : 'small'}). Skipping full reviewer flow.`);
+                // For trivial PRs, we still run orchestrator but with awareness
+                // The orchestrator can use this information to select fewer reviewers or skip entirely
+            }
+            // Run orchestrator
+            log.info('Running orchestrator...');
+            const prDescription = config.prDescription;
+            if (prDescription) {
+                log.debug('PR description provided, will be included in prompts');
+            }
+            if (config.reviewDomains && config.reviewDomains.length > 0) {
+                log.debug(`Review domains provided: ${config.reviewDomains.join(', ')}`);
+            }
+            const orchestratorOutput = await runOrchestrator(inputs, outputDir, {
+                mcpClient,
+                config: {
+                    openRouterApiKey: validatedConfig.openRouterApiKey,
+                    orchestratorModel: validatedConfig.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL,
+                    maxSteps: validatedConfig.maxSteps,
+                    prDescription,
+                    reviewDomains: validatedConfig.reviewDomains,
+                },
+                logger: log,
+            });
+            log.info(`Selected reviewers: ${orchestratorOutput.reviewers.join(', ')}`);
+            log.debug(`Orchestrator understanding:\n${orchestratorOutput.understanding}`);
+            // Run reviewers in parallel with progress logging
+            log.info(`Running ${orchestratorOutput.reviewers.length} reviewer(s) in parallel...`);
+            const reviewerFailures = [];
+            const reviewerResults = await Promise.all(orchestratorOutput.reviewers.map(async (reviewer) => {
+                const startTime = Date.now();
+                log.info(`[${reviewer}] Starting review...`);
+                try {
+                    const findings = await runReviewerLoop(reviewer, inputs, orchestratorOutput.understanding, outputDir, {
+                        mcpClient,
+                        config: {
+                            openRouterApiKey: validatedConfig.openRouterApiKey,
+                            reviewerModel: validatedConfig.reviewerModel ?? DEFAULT_REVIEWER_MODEL,
+                            criticModel: validatedConfig.criticModel,
+                            maxSteps: validatedConfig.maxSteps,
+                            maxIterations: validatedConfig.maxIterations,
+                            prDescription,
+                            reviewDomains: validatedConfig.reviewDomains,
+                        },
+                        logger: log,
+                    });
+                    const result = {
+                        reviewer,
+                        findings: findings.findings,
+                        validated: findings.validated,
+                        notes: findings.notes ?? undefined,
+                    };
+                    const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+                    log.info(`[${reviewer}] Completed in ${duration}s`);
+                    // Log reviewer results
+                    const issueCount = findings.findings.filter((f) => f.severity !== 'pass').length;
+                    const passCount = findings.findings.filter((f) => f.severity === 'pass').length;
+                    if (issueCount === 0) {
+                        log.info(`  ✓ ${reviewer}: Clean pass (pass signals: ${passCount}, validated: ${findings.validated})`);
+                    }
+                    else {
+                        log.info(`  ✓ ${reviewer}: ${issueCount} issue(s) (pass signals: ${passCount}, validated: ${findings.validated})`);
+                    }
+                    log.debug(`    Findings: ${JSON.stringify(findings.findings, null, 2)}`);
+                    if (findings.notes) {
+                        log.debug(`    Notes: ${findings.notes}`);
+                    }
+                    return result;
+                }
+                catch (error) {
+                    const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+                    const message = error instanceof Error ? error.message : 'Unknown error';
+                    log.error(`[${reviewer}] Failed after ${duration}s: ${message}`);
+                    // Provide actionable error guidance
+                    if (message.includes('No object generated') || message.includes('No output generated')) {
+                        log.error(`[${reviewer}] TROUBLESHOOTING: The model may not support structured output well.`);
+                        log.error(`[${reviewer}] Try: 1) Use a different model (e.g., anthropic/claude-haiku-4.5)`);
+                        log.error(`[${reviewer}]      2) Check model compatibility with structured output`);
+                        log.error(`[${reviewer}]      3) Review the model's response format requirements`);
+                    }
+                    reviewerFailures.push({ reviewer, message });
+                    return {
+                        reviewer,
+                        findings: [],
+                        validated: false,
+                        notes: `Error: ${message}`,
+                    };
+                }
+            }));
+            // Aggregate results
+            log.info('Aggregating results...');
+            log.debug(`  Total issue findings to aggregate: ${reviewerResults.reduce((sum, rr) => sum + rr.findings.filter((f) => f.severity !== 'pass').length, 0)}`);
+            log.debug(`  Total pass signals to aggregate: ${reviewerResults.reduce((sum, rr) => sum + rr.findings.filter((f) => f.severity === 'pass').length, 0)}`);
+            log.debug(`  Reviewers validated: ${reviewerResults.filter((rr) => rr.validated).length}/${reviewerResults.length}`);
+            const metadata = metadataSchema.parse({
+                timestamp: new Date().toISOString(),
+                mode: inputs.mode,
+                fileCount: inputs.files.length,
+            });
+            // Synthesize findings across reviewers (deduplication, contradictions, compound risks)
+            log.info(`Synthesis pass starting (model: ${validatedConfig.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL}, reviewers: ${reviewerResults.length})`);
+            const synthesisResult = await synthesizeFindings(reviewerResults, {
+                openRouterApiKey: validatedConfig.openRouterApiKey,
+                model: validatedConfig.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL,
+                maxSteps: validatedConfig.aggregationMaxSteps,
+                logger: log,
+            });
+            log.info(`Synthesis pass complete: ${synthesisResult.synthesis.findings.length} deduped findings, ${synthesisResult.synthesis.contradictions.length} contradictions, ${synthesisResult.synthesis.compoundRisks.length} compound risks`);
+            log.debug(`  Synthesis: ${synthesisResult.synthesis.findings.length} deduplicated findings`);
+            log.debug(`  Contradictions: ${synthesisResult.synthesis.contradictions.length}`);
+            log.debug(`  Compound risks: ${synthesisResult.synthesis.compoundRisks.length}`);
+            const synthesisSeverityCounts = synthesisResult.synthesis.findings.reduce((acc, finding) => {
+                acc[finding.severity] += 1;
+                return acc;
+            }, { critical: 0, major: 0, minor: 0, info: 0, pass: 0 });
+            log.debug(`  Synthesis severity: ${JSON.stringify(synthesisSeverityCounts)}`);
+            // Generate review decision based on synthesized findings
+            log.info(`Decision pass starting (model: ${validatedConfig.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL}, synthesis findings: ${synthesisResult.synthesis.findings.length})`);
+            const decisionResult = await generateReviewDecision(orchestratorOutput.understanding, synthesisResult.synthesis, {
+                openRouterApiKey: validatedConfig.openRouterApiKey,
+                model: validatedConfig.orchestratorModel ?? DEFAULT_ORCHESTRATOR_MODEL,
+                maxSteps: validatedConfig.aggregationMaxSteps,
+                logger: log,
+            });
+            const normalizedDecision = normalizeDecisionWithSynthesis(decisionResult.decision, synthesisResult.synthesis);
+            const decisionEvidence = {
+                findings: synthesisResult.synthesis.findings.length,
+                blockingFindings: synthesisResult.synthesis.findings.filter((f) => f.severity === 'critical' || f.severity === 'major').length,
+                contradictions: synthesisResult.synthesis.contradictions.length,
+                compoundRisks: synthesisResult.synthesis.compoundRisks.length,
+                modelDecision: decisionResult.decision.decision,
+                normalizedDecision: normalizedDecision.decision,
+            };
+            log.debug(`  Decision evidence: ${JSON.stringify(decisionEvidence)}`);
+            if (normalizedDecision.decision !== decisionResult.decision.decision) {
+                log.warn(`Decision normalized from ${decisionResult.decision.decision} to ${normalizedDecision.decision} to match synthesized findings.`);
+            }
+            log.info(`Decision pass complete: ${normalizedDecision.decision}`);
+            log.debug(`  Aggregation decision: ${normalizedDecision.decision}`);
+            log.debug(`  Decision summary: ${normalizedDecision.summary}`);
+            log.debug(`  Decision rationale: ${normalizedDecision.rationale}`);
+            const result = aggregateResults(metadata, orchestratorOutput.understanding, normalizedDecision, reviewerResults, reviewerFailures, synthesisResult.synthesis);
+            // Write result.json
+            await writeResult(outputDir, result);
+            const resultPath = path.join(outputDir, 'result.json');
+            log.info(`Results written to ${resultPath}`);
+            log.debug(`  Full review results available at: ${resultPath}`);
+            // Write token budget metrics
+            const aggregationUsage = [];
+            if (synthesisResult.usage) {
+                aggregationUsage.push(synthesisResult.usage);
+            }
+            if (decisionResult.usage) {
+                aggregationUsage.push(decisionResult.usage);
+            }
+            await writeTokenBudgetMetrics(outputDir, orchestratorOutput.reviewers, aggregationUsage.length > 0 ? aggregationUsage : undefined);
+            log.info(`Token budget metrics written to ${path.join(outputDir, 'token-budget.json')}`);
+            // Print summary
+            log.info('\n═══════════════════════════════════════════════════════════');
+            log.info('Review Summary');
+            log.info('═══════════════════════════════════════════════════════════');
+            log.info(`  Files reviewed: ${result.metadata.fileCount}`);
+            log.info(`  Reviewers executed: ${reviewerResults.length}`);
+            log.info(`  Total issue findings: ${result.summary.totalFindings}`);
+            log.info(`  Critical: ${result.summary.bySeverity.critical}`);
+            log.info(`  Major: ${result.summary.bySeverity.major}`);
+            log.info(`  Minor: ${result.summary.bySeverity.minor}`);
+            log.info(`  Info: ${result.summary.bySeverity.info}`);
+            log.info(`  Pass signals: ${result.summary.bySeverity.pass}`);
+            // Show per-reviewer breakdown
+            if (result.summary.totalFindings > 0) {
+                log.info('\n  Findings by reviewer:');
+                for (const [reviewer, count] of Object.entries(result.summary.byReviewer)) {
+                    log.info(`    ${reviewer}: ${count} finding(s)`);
+                }
+            }
+            // Show decision details
+            log.info(`\n  Decision: ${result.decision.decision.toUpperCase()}`);
+            log.info(`  Summary: ${result.decision.summary}`);
+            log.info(`  Rationale: ${result.decision.rationale}`);
+            // Show reviewer pass summaries (positive signal)
+            const passReviewers = reviewerResults
+                .map((rr) => ({
+                reviewer: rr.reviewer,
+                passFinding: rr.findings.find((f) => f.severity === 'pass'),
+                notes: rr.notes,
+                validated: rr.validated,
+            }))
+                .filter((rr) => rr.validated && (rr.passFinding || rr.notes));
+            if (passReviewers.length > 0) {
+                log.info('\n  Reviewer pass summaries:');
+                for (const rr of passReviewers) {
+                    const passLine = rr.notes?.trim() ?? rr.passFinding?.title ?? 'PASS';
+                    log.info(`    ${rr.reviewer}: ${passLine.split('\n')[0] ?? passLine}`);
+                }
+            }
+            // Debug: Show synthesized (deduplicated) findings when available.
+            if (result.synthesis && result.synthesis.findings.length > 0) {
+                log.debug('\n  Deduplicated findings (synthesis):');
+                for (const finding of result.synthesis.findings) {
+                    log.debug(`      [${finding.severity.toUpperCase()}] ${finding.title}`);
+                    if (finding.file) {
+                        log.debug(`        File: ${finding.file}${finding.line ? `:${finding.line}` : ''}`);
+                    }
+                    if (finding.sourceReviewers && finding.sourceReviewers.length > 0) {
+                        log.debug(`        Source reviewers: ${finding.sourceReviewers.join(', ')}`);
+                    }
+                    if (finding.contextTitles && finding.contextTitles.length > 0) {
+                        log.debug(`        ContextRail Standards: ${finding.contextTitles.join(', ')}`);
+                    }
+                    log.debug(`        ${finding.description}`);
+                }
+            }
+            else {
+                // Fallback: Show raw reviewer findings when synthesis is unavailable.
+                const hasAnyEntries = reviewerResults.some((rr) => rr.findings.length > 0);
+                if (hasAnyEntries) {
+                    log.debug('\n  All findings:');
+                    for (const rr of reviewerResults) {
+                        if (rr.findings.length > 0) {
+                            log.debug(`\n    ${rr.reviewer}:`);
+                            for (const finding of rr.findings) {
+                                log.debug(`      [${finding.severity.toUpperCase()}] ${finding.title}`);
+                                if (finding.file) {
+                                    log.debug(`        File: ${finding.file}${finding.line ? `:${finding.line}` : ''}`);
+                                }
+                                if (finding.contextTitles && finding.contextTitles.length > 0) {
+                                    log.debug(`        ContextRail Standards: ${finding.contextTitles.join(', ')}`);
+                                }
+                                log.debug(`        ${finding.description}`);
+                            }
+                        }
+                    }
+                }
+            }
+            // Show failures if any
+            if (result.failures && result.failures.length > 0) {
+                log.warn('\n  Reviewer failures:');
+                for (const failure of result.failures) {
+                    log.warn(`    ${failure.reviewer}: ${failure.message}`);
+                }
+            }
+            log.info('═══════════════════════════════════════════════════════════\n');
+            // Set exit code based on reviewer statuses
+            const hasFailures = reviewerResults.some((rr) => !rr.validated);
+            if (hasFailures) {
+                log.error('❌ Review failed: Some reviewers did not validate');
+                process.exit(1);
+            }
+            else if (result.decision.decision === 'request-changes') {
+                log.error('❌ Review decision: REQUEST CHANGES');
+                log.error(`   Reason: ${result.decision.rationale}`);
+                process.exit(1);
+            }
+            else {
+                if (result.summary.totalFindings === 0) {
+                    log.info('✅ Review passed: No findings - code is clean!');
+                }
+                else {
+                    log.info('✅ Review passed: Findings present but decision is APPROVE');
+                    log.info(`   ${result.summary.totalFindings} finding(s) were reviewed and deemed acceptable`);
+                }
+                log.info(`   Decision rationale: ${result.decision.rationale}`);
+                process.exit(0);
+            }
+        }
+        finally {
+            await mcpClient.close();
+        }
+    }
+    catch (error) {
+        const log = createLogger(parseLogLevel(process.env.DEBUG));
+        const normalizedError = error instanceof Error ? error : new Error('Unknown error');
+        const message = normalizedError.message;
+        const stack = normalizedError.stack;
+        log.error({ msg: 'Fatal error', error: message, stack });
+        if (stack && process.env.NODE_ENV === 'development') {
+            log.debug({ msg: 'Error stack trace', stack });
+        }
+        await gracefulShutdown('SIGTERM', normalizedError);
+        return;
+    }
+};
+// Set up process-level error handlers with structured logging
+let mcpClientInstance = null;
+const gracefulShutdown = async (signal, error) => {
+    const log = createLogger(parseLogLevel(process.env.DEBUG));
+    log.warn({ msg: `Received ${signal}. Shutting down...`, signal });
+    try {
+        if (mcpClientInstance) {
+            await mcpClientInstance.close();
+        }
+        process.exit(error ? 1 : 0);
+    }
+    catch (shutdownError) {
+        const message = shutdownError instanceof Error ? shutdownError.message : 'Unknown error';
+        log.error({ msg: 'Error during shutdown', error: message });
+        process.exit(1);
+    }
+};
+process.on('uncaughtException', async (error) => {
+    const log = createLogger(parseLogLevel(process.env.DEBUG));
+    log.error({
+        msg: 'Uncaught exception',
+        error: error.message,
+        stack: error.stack,
+        name: error.name,
+    });
+    await gracefulShutdown('SIGTERM', error);
+});
+process.on('unhandledRejection', async (reason) => {
+    const log = createLogger(parseLogLevel(process.env.DEBUG));
+    const message = reason instanceof Error ? reason.message : String(reason);
+    const stack = reason instanceof Error ? reason.stack : undefined;
+    log.error({
+        msg: 'Unhandled rejection',
+        error: message,
+        stack,
+    });
+    await gracefulShutdown('SIGTERM', reason instanceof Error ? reason : new Error(message));
+});
+// Capture SIGTERM and SIGINT for graceful shutdown
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+main();

package/dist/llm/factory.d.ts

@@ -0,0 +1,21 @@
+import { LlmService } from './service.js';
+import type { ModelProvider } from './types.js';
+import type { Logger } from '../logging/logger.js';
+import { LlmMetricsCollector } from '../observability/metrics.js';
+import type { McpClient } from '../mcp/client.js';
+/**
+ * Create an OpenRouter model provider.
+ */
+export declare const createOpenRouterModelProvider: (apiKey: string) => ModelProvider;
+/**
+ * Create an LLM service with OpenRouter and optional MCP tools.
+ */
+export declare const createLlmService: (config: {
+    openRouterApiKey: string;
+    mcpClient?: McpClient;
+    logger?: Logger;
+    enableMetrics?: boolean;
+}) => {
+    service: LlmService;
+    metrics?: LlmMetricsCollector;
+};

package/dist/llm/factory.js

@@ -0,0 +1,50 @@
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { LlmService } from './service.js';
+import { LlmMetricsCollector } from '../observability/metrics.js';
+import { createToolsProvider } from '../mcp/tools-provider.js';
+/**
+ * Create an OpenRouter model provider.
+ */
+export const createOpenRouterModelProvider = (apiKey) => {
+    const openrouter = createOpenRouter({ apiKey });
+    return (modelName) => openrouter(modelName);
+};
+/**
+ * Create an LLM service with OpenRouter and optional MCP tools.
+ */
+export const createLlmService = (config) => {
+    const { openRouterApiKey, mcpClient, logger, enableMetrics = true } = config;
+    // Create model provider
+    const modelProvider = createOpenRouterModelProvider(openRouterApiKey);
+    // Create tools provider if MCP client is available
+    const toolsProvider = mcpClient ? createToolsProvider(mcpClient) : undefined;
+    // Create metrics collector if enabled
+    const metrics = enableMetrics ? new LlmMetricsCollector(logger) : undefined;
+    // Create observability hooks
+    const hooks = metrics
+        ? {
+            onCallStart: (metadata) => {
+                logger?.debug(`[LLM] Starting: ${metadata.operation} (model: ${metadata.model})`);
+            },
+            onCallComplete: (metadata, usage) => {
+                metrics.recordCall(metadata, usage);
+                logger?.debug(`[LLM] Completed: ${metadata.operation} (tokens: ${usage?.totalTokens ?? 'unknown'})`);
+            },
+            onCallError: (metadata, error) => {
+                metrics.recordError(metadata, error);
+                logger?.error(`[LLM] Error: ${metadata.operation}`, error);
+            },
+            onToolCall: (metadata, toolName) => {
+                metrics.recordToolCall(metadata, toolName);
+                logger?.debug(`[LLM] Tool call: ${toolName} (operation: ${metadata.operation})`);
+            },
+        }
+        : undefined;
+    const service = new LlmService({
+        modelProvider,
+        toolsProvider,
+        hooks,
+        logger,
+    });
+    return { service, metrics };
+};

package/dist/llm/index.d.ts

@@ -0,0 +1,3 @@
+export { LlmService } from './service.js';
+export { createLlmService, createOpenRouterModelProvider } from './factory.js';
+export type { LlmCallResult, LlmCallConfig, LlmCallMetadata, TokenUsage, ModelProvider, ToolsProvider, LlmObservabilityHooks, ToolChoice, } from './types.js';