@decibelsystems/tools 2.0.0

package/dist/lib/agent-services/assumptions.js

@@ -0,0 +1,284 @@
+// ============================================================================
+// Assumption Aggregation Service
+// ============================================================================
+// Aggregates assumptions across runs to identify patterns, high-risk categories,
+// and things the agent should always ask about rather than assume.
+// ============================================================================
+import { getRun, listRuns } from '../../tools/vector.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Threshold for considering a category high-risk */
+const HIGH_RISK_INVALIDATION_RATE = 0.3; // 30%+ invalidation = high risk
+/** Minimum occurrences to consider for "always ask" */
+const MIN_OCCURRENCES_FOR_ALWAYS_ASK = 2;
+/** Invalidation rate threshold for "always ask" */
+const ALWAYS_ASK_INVALIDATION_RATE = 0.5; // 50%+ invalidation = always ask
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Extract tracked assumptions from run events
+ */
+function extractAssumptions(events, run_id) {
+    const assumptions = [];
+    for (const event of events) {
+        if (event.type !== 'assumption_made')
+            continue;
+        if (!event.payload)
+            continue;
+        const payload = event.payload;
+        assumptions.push({
+            assumption: payload.assumption || payload.content || 'Unknown assumption',
+            rationale: payload.rationale,
+            alternatives: payload.alternatives,
+            ask_if_below: payload.ask_if_below,
+            category: normalizeCategory(payload.category),
+            outcome: normalizeOutcome(payload.outcome),
+            run_id,
+            timestamp: event.ts,
+        });
+    }
+    return assumptions;
+}
+/**
+ * Normalize category string to valid AssumptionCategory
+ */
+function normalizeCategory(category) {
+    if (!category)
+        return 'other';
+    const normalized = category.toLowerCase().replace(/[^a-z_]/g, '');
+    const validCategories = [
+        'architecture', 'api_behavior', 'auth', 'data_format',
+        'dependencies', 'environment', 'permissions', 'performance',
+        'security', 'user_intent', 'other'
+    ];
+    if (validCategories.includes(normalized)) {
+        return normalized;
+    }
+    // Map common variations
+    if (normalized.includes('api'))
+        return 'api_behavior';
+    if (normalized.includes('auth') || normalized.includes('login'))
+        return 'auth';
+    if (normalized.includes('data') || normalized.includes('format'))
+        return 'data_format';
+    if (normalized.includes('dep') || normalized.includes('package'))
+        return 'dependencies';
+    if (normalized.includes('env') || normalized.includes('config'))
+        return 'environment';
+    if (normalized.includes('perm') || normalized.includes('access'))
+        return 'permissions';
+    if (normalized.includes('perf') || normalized.includes('speed'))
+        return 'performance';
+    if (normalized.includes('sec'))
+        return 'security';
+    if (normalized.includes('user') || normalized.includes('intent'))
+        return 'user_intent';
+    return 'other';
+}
+/**
+ * Normalize outcome string to valid AssumptionOutcome
+ */
+function normalizeOutcome(outcome) {
+    if (!outcome)
+        return 'unknown';
+    const normalized = outcome.toLowerCase();
+    if (normalized === 'validated' || normalized === 'valid' || normalized === 'correct') {
+        return 'validated';
+    }
+    if (normalized === 'invalidated' || normalized === 'invalid' || normalized === 'wrong' || normalized === 'incorrect') {
+        return 'invalidated';
+    }
+    return 'unknown';
+}
+/**
+ * Infer outcome from subsequent events if not explicitly set
+ */
+function inferOutcome(assumption, allEvents, assumptionIndex) {
+    if (assumption.outcome !== 'unknown') {
+        return assumption.outcome;
+    }
+    // Look at events after this assumption
+    const subsequentEvents = allEvents.slice(assumptionIndex + 1);
+    for (const event of subsequentEvents) {
+        // Backtrack or error after assumption often means it was wrong
+        if (event.type === 'backtrack' || event.type === 'error') {
+            const payload = event.payload;
+            if (payload?.reason?.toLowerCase().includes(assumption.assumption.toLowerCase())) {
+                return 'invalidated';
+            }
+        }
+        // User correction specifically about this assumption
+        if (event.type === 'user_correction') {
+            const payload = event.payload;
+            if (payload?.correction?.toLowerCase().includes(assumption.assumption.toLowerCase())) {
+                return 'invalidated';
+            }
+        }
+    }
+    return 'unknown';
+}
+// ============================================================================
+// Main Functions
+// ============================================================================
+/**
+ * Aggregate assumptions from multiple runs
+ */
+export async function aggregateAssumptions(projectId, options) {
+    const lookbackDays = options?.lookback_days || 30;
+    const maxRuns = options?.max_runs || 100;
+    // Get recent runs
+    const { runs } = await listRuns({
+        projectId,
+        limit: maxRuns,
+    });
+    // Filter by date
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - lookbackDays);
+    const cutoffStr = cutoff.toISOString();
+    const recentRuns = runs.filter(r => r.created_at >= cutoffStr);
+    // Collect all assumptions
+    const allAssumptions = [];
+    for (const run of recentRuns) {
+        try {
+            const runData = await getRun({
+                projectId,
+                run_id: run.run_id,
+                include_events: true,
+            });
+            if (!runData.events)
+                continue;
+            const assumptions = extractAssumptions(runData.events, run.run_id);
+            // Try to infer outcomes
+            for (let i = 0; i < runData.events.length; i++) {
+                const event = runData.events[i];
+                if (event.type === 'assumption_made') {
+                    const assumptionIndex = assumptions.findIndex(a => a.timestamp === event.ts && a.run_id === run.run_id);
+                    if (assumptionIndex >= 0) {
+                        assumptions[assumptionIndex].outcome = inferOutcome(assumptions[assumptionIndex], runData.events, i);
+                    }
+                }
+            }
+            allAssumptions.push(...assumptions);
+        }
+        catch {
+            // Skip runs we can't read
+        }
+    }
+    // Calculate stats
+    const stats = calculateStats(allAssumptions);
+    return {
+        ...stats,
+        assumptions: allAssumptions,
+        period: {
+            start: cutoffStr,
+            end: new Date().toISOString(),
+            run_count: recentRuns.length,
+        },
+    };
+}
+/**
+ * Calculate statistics from assumptions
+ */
+function calculateStats(assumptions) {
+    const byOutcome = {
+        validated: 0,
+        invalidated: 0,
+        unknown: 0,
+    };
+    const byCategory = {
+        architecture: { valid: 0, invalid: 0, total: 0 },
+        api_behavior: { valid: 0, invalid: 0, total: 0 },
+        auth: { valid: 0, invalid: 0, total: 0 },
+        data_format: { valid: 0, invalid: 0, total: 0 },
+        dependencies: { valid: 0, invalid: 0, total: 0 },
+        environment: { valid: 0, invalid: 0, total: 0 },
+        permissions: { valid: 0, invalid: 0, total: 0 },
+        performance: { valid: 0, invalid: 0, total: 0 },
+        security: { valid: 0, invalid: 0, total: 0 },
+        user_intent: { valid: 0, invalid: 0, total: 0 },
+        other: { valid: 0, invalid: 0, total: 0 },
+    };
+    // Track specific assumptions for "always ask"
+    const assumptionOccurrences = new Map();
+    for (const a of assumptions) {
+        byOutcome[a.outcome]++;
+        const cat = byCategory[a.category];
+        cat.total++;
+        if (a.outcome === 'validated')
+            cat.valid++;
+        if (a.outcome === 'invalidated')
+            cat.invalid++;
+        // Normalize assumption text for grouping
+        const normalized = a.assumption.toLowerCase().trim();
+        const existing = assumptionOccurrences.get(normalized) || { valid: 0, invalid: 0 };
+        if (a.outcome === 'validated')
+            existing.valid++;
+        if (a.outcome === 'invalidated')
+            existing.invalid++;
+        assumptionOccurrences.set(normalized, existing);
+    }
+    // Calculate category validation rates and find high-risk ones
+    const categoryValidationRates = {};
+    const highRiskCategories = [];
+    for (const [category, stats] of Object.entries(byCategory)) {
+        const cat = category;
+        if (stats.total === 0) {
+            categoryValidationRates[cat] = 1; // No data = assume safe
+            continue;
+        }
+        const knownOutcomes = stats.valid + stats.invalid;
+        if (knownOutcomes === 0) {
+            categoryValidationRates[cat] = 1;
+            continue;
+        }
+        const validationRate = stats.valid / knownOutcomes;
+        categoryValidationRates[cat] = validationRate;
+        const invalidationRate = stats.invalid / knownOutcomes;
+        if (invalidationRate >= HIGH_RISK_INVALIDATION_RATE && stats.total >= MIN_OCCURRENCES_FOR_ALWAYS_ASK) {
+            highRiskCategories.push(cat);
+        }
+    }
+    // Find specific assumptions to always ask about
+    const alwaysAsk = [];
+    for (const [assumption, counts] of assumptionOccurrences) {
+        const total = counts.valid + counts.invalid;
+        if (total < MIN_OCCURRENCES_FOR_ALWAYS_ASK)
+            continue;
+        const invalidationRate = counts.invalid / total;
+        if (invalidationRate >= ALWAYS_ASK_INVALIDATION_RATE) {
+            alwaysAsk.push(assumption);
+        }
+    }
+    return {
+        total_count: assumptions.length,
+        by_outcome: byOutcome,
+        high_risk_categories: highRiskCategories,
+        always_ask: alwaysAsk,
+        category_validation_rates: categoryValidationRates,
+    };
+}
+/**
+ * Check if a specific assumption should be asked about
+ */
+export async function shouldAskAbout(assumption, category, projectId) {
+    const stats = await aggregateAssumptions(projectId);
+    // Check if this specific assumption is in always_ask
+    const normalized = assumption.toLowerCase().trim();
+    if (stats.always_ask.some(a => normalized.includes(a) || a.includes(normalized))) {
+        return {
+            should_ask: true,
+            reason: 'This assumption has been invalidated frequently in the past',
+        };
+    }
+    // Check if category is high-risk
+    if (stats.high_risk_categories.includes(category)) {
+        return {
+            should_ask: true,
+            reason: `Category "${category}" has a high invalidation rate (${Math.round((1 - stats.category_validation_rates[category]) * 100)}%)`,
+        };
+    }
+    return { should_ask: false };
+}
+//# sourceMappingURL=assumptions.js.map

package/dist/lib/agent-services/assumptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assumptions.js","sourceRoot":"","sources":["../../../src/lib/agent-services/assumptions.ts"],"names":[],"mappings":"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"}

package/dist/lib/agent-services/context-pack.d.ts

@@ -0,0 +1,6 @@
+import type { ContextPackRequest, ContextPackResponse } from '../../types/agent-services.js';
+/**
+ * Build a context pack for a new task based on historical runs
+ */
+export declare function buildContextPack(request: ContextPackRequest, projectId?: string): Promise<ContextPackResponse>;
+//# sourceMappingURL=context-pack.d.ts.map

package/dist/lib/agent-services/context-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-pack.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-services/context-pack.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EAIpB,MAAM,+BAA+B,CAAC;AAuTvC;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,kBAAkB,EAC3B,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,mBAAmB,CAAC,CA2G9B"}

package/dist/lib/agent-services/context-pack.js

@@ -0,0 +1,354 @@
+// ============================================================================
+// Context Pack Service
+// ============================================================================
+// Builds a memory brief from past runs before starting a new task.
+// Helps agents avoid repeating past mistakes and learn from history.
+// ============================================================================
+import { getRun, listRuns } from '../../tools/vector.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Default lookback period in days */
+const DEFAULT_LOOKBACK_DAYS = 30;
+/** Default max runs to analyze */
+const DEFAULT_MAX_RUNS = 50;
+/** Minimum similarity score to consider a run relevant */
+const MIN_SIMILARITY_SCORE = 0.3;
+/** Common error patterns to track */
+const COMMON_ERROR_PATTERNS = [
+    { pattern: 'type error', category: 'type_safety' },
+    { pattern: 'undefined', category: 'null_check' },
+    { pattern: 'not found', category: 'missing_resource' },
+    { pattern: 'permission denied', category: 'permissions' },
+    { pattern: 'timeout', category: 'performance' },
+    { pattern: 'connection refused', category: 'connectivity' },
+    { pattern: 'syntax error', category: 'syntax' },
+    { pattern: 'import', category: 'dependencies' },
+    { pattern: 'module not found', category: 'dependencies' },
+];
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Calculate similarity between task and a past run's prompt
+ */
+function calculateSimilarity(task, promptSpec, filesHint) {
+    const taskLower = task.toLowerCase();
+    const promptLower = promptSpec.raw_prompt.toLowerCase();
+    let score = 0;
+    const reasons = [];
+    // Check for shared keywords (simple word overlap)
+    const taskWords = new Set(taskLower.split(/\s+/).filter(w => w.length > 3));
+    const promptWords = new Set(promptLower.split(/\s+/).filter(w => w.length > 3));
+    let sharedWords = 0;
+    for (const word of taskWords) {
+        if (promptWords.has(word))
+            sharedWords++;
+    }
+    if (taskWords.size > 0) {
+        const wordOverlap = sharedWords / taskWords.size;
+        score += wordOverlap * 0.4; // Up to 40% from word overlap
+        if (wordOverlap > 0.3) {
+            reasons.push(`Shares ${sharedWords} keywords`);
+        }
+    }
+    // Check for intent goal similarity
+    if (promptSpec.intent?.goal) {
+        const goalLower = promptSpec.intent.goal.toLowerCase();
+        const goalWords = new Set(goalLower.split(/\s+/).filter(w => w.length > 3));
+        let goalShared = 0;
+        for (const word of taskWords) {
+            if (goalWords.has(word))
+                goalShared++;
+        }
+        if (taskWords.size > 0 && goalShared > 0) {
+            score += 0.2; // 20% boost for goal overlap
+            reasons.push('Similar goal');
+        }
+    }
+    // Check for file hint overlap with scope
+    if (filesHint && filesHint.length > 0 && promptSpec.intent?.scope) {
+        const scopeSet = new Set(promptSpec.intent.scope.map(s => s.toLowerCase()));
+        const hintSet = new Set(filesHint.map(f => f.toLowerCase()));
+        for (const hint of hintSet) {
+            for (const scope of scopeSet) {
+                if (hint.includes(scope) || scope.includes(hint)) {
+                    score += 0.2;
+                    reasons.push(`File overlap: ${hint}`);
+                    break;
+                }
+            }
+        }
+    }
+    // Check for common action verbs
+    const actionVerbs = ['add', 'fix', 'update', 'refactor', 'implement', 'create', 'delete', 'remove'];
+    for (const verb of actionVerbs) {
+        if (taskLower.includes(verb) && promptLower.includes(verb)) {
+            score += 0.1;
+            reasons.push(`Same action: ${verb}`);
+            break;
+        }
+    }
+    return {
+        score: Math.min(score, 1),
+        reason: reasons.length > 0 ? reasons.join(', ') : 'Low similarity',
+    };
+}
+/**
+ * Extract files touched from run events
+ */
+function extractFilesTouched(events) {
+    const files = new Set();
+    for (const event of events) {
+        if (event.type === 'file_touched' && event.payload?.file) {
+            files.add(event.payload.file);
+        }
+        if (event.type === 'command_ran' && event.payload?.files) {
+            for (const f of event.payload.files) {
+                files.add(f);
+            }
+        }
+    }
+    return Array.from(files);
+}
+/**
+ * Extract key learnings from a run
+ */
+function extractLearnings(events, success) {
+    const learnings = [];
+    // Look for user corrections - these are always valuable
+    for (const event of events) {
+        if (event.type === 'user_correction' && event.payload?.correction) {
+            learnings.push(`User correction: ${event.payload.correction}`);
+        }
+    }
+    // Look for backtracks - what went wrong?
+    for (const event of events) {
+        if (event.type === 'backtrack' && event.payload?.reason) {
+            learnings.push(`Had to backtrack: ${event.payload.reason}`);
+        }
+    }
+    // Look for errors
+    for (const event of events) {
+        if (event.type === 'error' && event.payload?.message) {
+            learnings.push(`Error encountered: ${event.payload.message}`);
+        }
+    }
+    // For successful runs, note what worked
+    if (success && events.length > 0) {
+        const lastEvent = events[events.length - 1];
+        if (lastEvent.type === 'run_completed' && lastEvent.payload?.summary) {
+            learnings.push(`Success: ${lastEvent.payload.summary}`);
+        }
+    }
+    return learnings.slice(0, 5); // Cap at 5 learnings
+}
+/**
+ * Analyze file churn across runs
+ */
+function analyzeChurn(runs) {
+    const fileStats = new Map();
+    for (const run of runs) {
+        const files = extractFilesTouched(run.events);
+        for (const file of files) {
+            const existing = fileStats.get(file) || { touches: 0, failures: 0, lastTouch: '' };
+            existing.touches++;
+            if (!run.success)
+                existing.failures++;
+            if (run.created_at > existing.lastTouch)
+                existing.lastTouch = run.created_at;
+            fileStats.set(file, existing);
+        }
+    }
+    // Convert to hotspots, sort by touch count
+    const hotspots = [];
+    for (const [file, stats] of fileStats) {
+        if (stats.touches < 2)
+            continue; // Only interested in files touched multiple times
+        hotspots.push({
+            file,
+            touch_count: stats.touches,
+            failure_rate: stats.touches > 0 ? stats.failures / stats.touches : 0,
+            last_touched: stats.lastTouch,
+        });
+    }
+    // Sort by touch count * failure rate (problematic files bubble up)
+    hotspots.sort((a, b) => {
+        const scoreA = a.touch_count * (1 + a.failure_rate);
+        const scoreB = b.touch_count * (1 + b.failure_rate);
+        return scoreB - scoreA;
+    });
+    return hotspots.slice(0, 10); // Top 10 hotspots
+}
+/**
+ * Analyze failure patterns across runs
+ */
+function analyzeFailurePatterns(runs) {
+    const patternCounts = new Map();
+    for (const run of runs) {
+        if (run.success)
+            continue; // Only look at failed runs
+        for (const event of run.events) {
+            if (event.type !== 'error')
+                continue;
+            const message = (event.payload?.message || '').toLowerCase();
+            for (const { pattern, category } of COMMON_ERROR_PATTERNS) {
+                if (message.includes(pattern)) {
+                    const existing = patternCounts.get(category) || { count: 0, examples: [] };
+                    existing.count++;
+                    if (existing.examples.length < 3) {
+                        existing.examples.push(event.payload?.message || pattern);
+                    }
+                    patternCounts.set(category, existing);
+                }
+            }
+        }
+    }
+    // Convert to patterns with prevention suggestions
+    const patterns = [];
+    const preventionSuggestions = {
+        type_safety: 'Add type annotations and check for type mismatches before running',
+        null_check: 'Check for undefined/null values before accessing properties',
+        missing_resource: 'Verify files and resources exist before operations',
+        permissions: 'Check file permissions and authentication before access',
+        performance: 'Consider timeout settings and async operation handling',
+        connectivity: 'Verify network connectivity and service availability',
+        syntax: 'Validate syntax before executing commands',
+        dependencies: 'Check that all imports and dependencies are installed',
+    };
+    for (const [category, stats] of patternCounts) {
+        if (stats.count < 2)
+            continue; // Only patterns that occur multiple times
+        patterns.push({
+            pattern: category.replace('_', ' '),
+            occurrence_count: stats.count,
+            suggested_prevention: preventionSuggestions[category] || 'Review similar past errors',
+        });
+    }
+    patterns.sort((a, b) => b.occurrence_count - a.occurrence_count);
+    return patterns;
+}
+/**
+ * Generate suggested questions based on task and history
+ */
+function generateQuestions(task, relevantRuns, failurePatterns) {
+    const questions = [];
+    // Questions based on past failures
+    for (const pattern of failurePatterns.slice(0, 2)) {
+        questions.push(`Past runs had ${pattern.pattern} issues - have you addressed this?`);
+    }
+    // Questions based on similar runs that failed
+    const failedRuns = relevantRuns.filter(r => r.outcome === 'failed');
+    if (failedRuns.length > 0) {
+        questions.push('Similar tasks have failed before - what makes this attempt different?');
+    }
+    // Questions based on ambiguous terms in task
+    const ambiguousTerms = ['refactor', 'improve', 'fix', 'update', 'optimize'];
+    for (const term of ambiguousTerms) {
+        if (task.toLowerCase().includes(term)) {
+            questions.push(`What specifically should be ${term}ed?`);
+            break;
+        }
+    }
+    // General scoping question if no files mentioned
+    if (!task.match(/\.(ts|js|py|go|rs|java|tsx|jsx)/) && !task.includes('src/')) {
+        questions.push('Which specific files or modules should be modified?');
+    }
+    return questions.slice(0, 5); // Cap at 5 questions
+}
+// ============================================================================
+// Main Function
+// ============================================================================
+/**
+ * Build a context pack for a new task based on historical runs
+ */
+export async function buildContextPack(request, projectId) {
+    const lookbackDays = request.lookback_days || DEFAULT_LOOKBACK_DAYS;
+    const maxRuns = request.max_runs || DEFAULT_MAX_RUNS;
+    // Get recent runs
+    const { runs } = await listRuns({
+        projectId,
+        limit: maxRuns,
+    });
+    // Filter by date
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - lookbackDays);
+    const cutoffStr = cutoff.toISOString();
+    const recentRuns = runs.filter(r => r.created_at >= cutoffStr);
+    // Load full run data
+    const fullRuns = [];
+    for (const run of recentRuns) {
+        try {
+            const runData = await getRun({
+                projectId,
+                run_id: run.run_id,
+                include_events: true,
+            });
+            fullRuns.push({
+                run_id: run.run_id,
+                prompt: runData.prompt,
+                events: runData.events || [],
+                success: run.success ?? !runData.completed, // If not completed, consider failed
+                created_at: run.created_at,
+            });
+        }
+        catch {
+            // Skip runs we can't read
+        }
+    }
+    // Find relevant runs
+    const relevantRuns = [];
+    for (const run of fullRuns) {
+        const { score, reason } = calculateSimilarity(request.task, run.prompt, request.files_hint);
+        if (score >= MIN_SIMILARITY_SCORE) {
+            relevantRuns.push({
+                run_id: run.run_id,
+                similarity_reason: reason,
+                outcome: run.success ? 'success' : 'failed',
+                key_learnings: extractLearnings(run.events, run.success),
+                files_touched: extractFilesTouched(run.events),
+            });
+        }
+    }
+    // Sort by similarity (implicit in the order we found them, but could enhance)
+    relevantRuns.sort((a, b) => {
+        // Failed runs are more instructive
+        if (a.outcome === 'failed' && b.outcome !== 'failed')
+            return -1;
+        if (b.outcome === 'failed' && a.outcome !== 'failed')
+            return 1;
+        return 0;
+    });
+    // Analyze churn and failure patterns
+    const churnHotspots = analyzeChurn(fullRuns);
+    const failurePatterns = analyzeFailurePatterns(fullRuns);
+    // Generate suggested questions
+    const suggestedQuestions = generateQuestions(request.task, relevantRuns, failurePatterns);
+    // Build context summary
+    let contextSummary = '';
+    if (relevantRuns.length > 0) {
+        const successCount = relevantRuns.filter(r => r.outcome === 'success').length;
+        const failCount = relevantRuns.filter(r => r.outcome === 'failed').length;
+        contextSummary += `Found ${relevantRuns.length} similar past runs (${successCount} successful, ${failCount} failed). `;
+    }
+    else {
+        contextSummary += 'No similar past runs found. ';
+    }
+    if (failurePatterns.length > 0) {
+        contextSummary += `Common issues: ${failurePatterns.map(p => p.pattern).join(', ')}. `;
+    }
+    if (churnHotspots.length > 0) {
+        const problematic = churnHotspots.filter(h => h.failure_rate > 0.3);
+        if (problematic.length > 0) {
+            contextSummary += `High-risk files: ${problematic.slice(0, 3).map(h => h.file).join(', ')}.`;
+        }
+    }
+    return {
+        relevant_runs: relevantRuns.slice(0, 10), // Top 10 relevant runs
+        churn_hotspots: churnHotspots,
+        failure_patterns: failurePatterns,
+        suggested_questions: suggestedQuestions,
+        context_summary: contextSummary.trim() || 'No historical context available.',
+    };
+}
+//# sourceMappingURL=context-pack.js.map