@wundam/orchex 1.0.0-rc.1

package/dist/intelligence/learning-feedback.js

@@ -0,0 +1,202 @@
+/**
+ * Learning feedback module for adaptive heuristic adjustment.
+ * Analyzes execution history to improve slicing thresholds.
+ */
+/**
+ * Default heuristic thresholds (conservative starting point).
+ */
+export const DEFAULT_THRESHOLDS = {
+    maxOwnsCount: 4,
+    maxReadsCount: 4,
+    maxPlanAndCount: 3,
+    maxOutputTokens: 5000,
+    minSuccessRate: 0.7,
+};
+/**
+ * Minimum samples required before learning from a category.
+ */
+export const MIN_CATEGORY_SAMPLES = 5;
+/**
+ * Minimum total samples before suggesting adjustments.
+ */
+export const MIN_TOTAL_SAMPLES = 20;
+/**
+ * Learn from execution metrics and suggest threshold adjustments.
+ *
+ * @param metrics - Map of category to execution metrics
+ * @param currentThresholds - Current threshold values
+ * @param minSamples - Minimum samples required for learning
+ * @returns Array of suggested threshold adjustments
+ */
+export function learnFromMetrics(metrics, currentThresholds = DEFAULT_THRESHOLDS, minSamples = MIN_TOTAL_SAMPLES) {
+    const adjustments = [];
+    // Aggregate all metrics
+    let totalExecutions = 0;
+    let totalSuccess = 0;
+    let weightedOwns = 0;
+    let weightedReads = 0;
+    let categoriesWithData = 0;
+    for (const m of metrics.values()) {
+        if (m.totalExecutions < MIN_CATEGORY_SAMPLES)
+            continue;
+        totalExecutions += m.totalExecutions;
+        totalSuccess += m.successCount;
+        weightedOwns += m.avgOwnsCount * m.totalExecutions;
+        weightedReads += m.avgReadsCount * m.totalExecutions;
+        categoriesWithData++;
+    }
+    if (totalExecutions < minSamples) {
+        return []; // Not enough data to learn from
+    }
+    const overallSuccessRate = totalSuccess / totalExecutions;
+    const avgOwns = weightedOwns / totalExecutions;
+    const avgReads = weightedReads / totalExecutions;
+    const confidence = totalExecutions >= 100 ? 'high' :
+        totalExecutions >= 50 ? 'medium' : 'low';
+    // Analyze high-owns categories with low success
+    const highOwnsLowSuccess = [...metrics.values()].filter(m => m.totalExecutions >= MIN_CATEGORY_SAMPLES &&
+        m.avgOwnsCount > currentThresholds.maxOwnsCount &&
+        m.successRate < 0.6);
+    if (highOwnsLowSuccess.length > 0) {
+        const newThreshold = Math.max(2, Math.floor(avgOwns * 0.8));
+        if (newThreshold !== currentThresholds.maxOwnsCount) {
+            adjustments.push({
+                field: 'maxOwnsCount',
+                oldValue: currentThresholds.maxOwnsCount,
+                newValue: newThreshold,
+                reason: `Streams with >${currentThresholds.maxOwnsCount} owns have <60% success rate`,
+                confidence,
+            });
+        }
+    }
+    // Analyze high-reads categories with high timeout rate
+    const highReadsHighTimeout = [...metrics.values()].filter(m => m.totalExecutions >= MIN_CATEGORY_SAMPLES &&
+        m.avgReadsCount > currentThresholds.maxReadsCount &&
+        (m.timeoutCount / m.totalExecutions) > 0.15);
+    if (highReadsHighTimeout.length > 0) {
+        const newThreshold = Math.max(2, Math.floor(avgReads * 0.7));
+        if (newThreshold !== currentThresholds.maxReadsCount) {
+            adjustments.push({
+                field: 'maxReadsCount',
+                oldValue: currentThresholds.maxReadsCount,
+                newValue: newThreshold,
+                reason: `Streams with >${currentThresholds.maxReadsCount} reads have >15% timeout rate`,
+                confidence,
+            });
+        }
+    }
+    // Adjust minSuccessRate if overall success is consistently high
+    if (overallSuccessRate > 0.85 && currentThresholds.minSuccessRate < 0.8) {
+        adjustments.push({
+            field: 'minSuccessRate',
+            oldValue: currentThresholds.minSuccessRate,
+            newValue: 0.8,
+            reason: `Overall success rate is ${(overallSuccessRate * 100).toFixed(0)}%, raising minimum threshold`,
+            confidence,
+        });
+    }
+    // Adjust minSuccessRate down if overall success is struggling
+    if (overallSuccessRate < 0.6 && currentThresholds.minSuccessRate > 0.6) {
+        adjustments.push({
+            field: 'minSuccessRate',
+            oldValue: currentThresholds.minSuccessRate,
+            newValue: 0.6,
+            reason: `Overall success rate is ${(overallSuccessRate * 100).toFixed(0)}%, lowering minimum threshold temporarily`,
+            confidence,
+        });
+    }
+    // Analyze high output token categories
+    const highTokensLowSuccess = [...metrics.values()].filter(m => m.totalExecutions >= MIN_CATEGORY_SAMPLES &&
+        m.avgOutputTokens > currentThresholds.maxOutputTokens &&
+        m.successRate < 0.7);
+    if (highTokensLowSuccess.length > 0) {
+        // Calculate average across high-token categories
+        const avgHighTokens = highTokensLowSuccess.reduce((sum, m) => sum + m.avgOutputTokens, 0) / highTokensLowSuccess.length;
+        const newThreshold = Math.max(3000, Math.floor(avgHighTokens * 0.8));
+        if (newThreshold !== currentThresholds.maxOutputTokens) {
+            adjustments.push({
+                field: 'maxOutputTokens',
+                oldValue: currentThresholds.maxOutputTokens,
+                newValue: newThreshold,
+                reason: `High-token streams averaging ${avgHighTokens.toFixed(0)} tokens have <70% success rate`,
+                confidence,
+            });
+        }
+    }
+    return adjustments;
+}
+/**
+ * Apply adjustments to thresholds with learning rate control.
+ *
+ * @param currentThresholds - Current threshold values
+ * @param adjustments - Suggested adjustments
+ * @param learningRate - How much to move toward suggested values (0-1)
+ * @returns Updated thresholds
+ */
+export function applyAdjustments(currentThresholds, adjustments, learningRate = 0.3) {
+    const updated = { ...currentThresholds };
+    for (const adj of adjustments) {
+        const current = currentThresholds[adj.field];
+        const suggested = adj.newValue;
+        // Apply learning rate for gradual adaptation
+        const newValue = current * (1 - learningRate) + suggested * learningRate;
+        // Round appropriately based on field type
+        if (adj.field === 'minSuccessRate') {
+            updated[adj.field] = Math.round(newValue * 100) / 100; // 2 decimal places
+        }
+        else {
+            updated[adj.field] = Math.round(newValue);
+        }
+    }
+    return updated;
+}
+/**
+ * Format adjustments as a human-readable report.
+ */
+export function formatAdjustmentsReport(adjustments) {
+    if (adjustments.length === 0) {
+        return 'No threshold adjustments suggested. Current thresholds are performing well.';
+    }
+    const lines = [
+        '=== Learning Feedback Report ===',
+        '',
+        `${adjustments.length} threshold adjustment${adjustments.length > 1 ? 's' : ''} suggested:`,
+        '',
+    ];
+    for (const adj of adjustments) {
+        const confidenceIcon = adj.confidence === 'high' ? '✅' : adj.confidence === 'medium' ? '⚠️' : '❓';
+        lines.push(`${confidenceIcon} ${adj.field}: ${adj.oldValue} → ${adj.newValue}`);
+        lines.push(`   Reason: ${adj.reason}`);
+        lines.push(`   Confidence: ${adj.confidence}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Generate insights from category metrics.
+ */
+export function generateCategoryInsights(metrics) {
+    const insights = [];
+    for (const [category, m] of metrics) {
+        if (m.totalExecutions < MIN_CATEGORY_SAMPLES)
+            continue;
+        // Low success rate warning
+        if (m.successRate < 0.6) {
+            insights.push(`${category} streams have ${(m.successRate * 100).toFixed(0)}% success rate. Consider reducing scope.`);
+        }
+        // High timeout rate warning
+        const timeoutRate = m.timeoutCount / m.totalExecutions;
+        if (timeoutRate > 0.15) {
+            insights.push(`${category} streams have ${(timeoutRate * 100).toFixed(0)}% timeout rate. Consider increasing timeout or reducing reads.`);
+        }
+        // High owns warning
+        if (m.avgOwnsCount > 4) {
+            insights.push(`${category} streams average ${m.avgOwnsCount.toFixed(1)} owned files. Consider splitting into smaller streams.`);
+        }
+        // High reads warning
+        if (m.avgReadsCount > 5) {
+            insights.push(`${category} streams average ${m.avgReadsCount.toFixed(1)} read files. High synthesis complexity may cause timeouts.`);
+        }
+    }
+    return insights;
+}

package/dist/intelligence/pattern-analyzer.d.ts

@@ -0,0 +1,35 @@
+import type { TelemetryAggregate } from '../telemetry/telemetry-types.js';
+import type { ErrorCategory } from './error-analyzer.js';
+export interface RetryPattern {
+    category: ErrorCategory;
+    totalOccurrences: number;
+    retrySuccessRate: number;
+    recommendation: 'always_retry' | 'conditional_retry' | 'no_retry';
+}
+export interface DurationPrediction {
+    complexityScore: number;
+    predictedDurationMs: number;
+    confidence: 'high' | 'medium' | 'low';
+}
+export interface WaveSizingRecommendation {
+    optimalParallelCount: number;
+    rationale: string;
+}
+export interface PatternAnalysis {
+    retryPatterns: RetryPattern[];
+    durationPredictions: DurationPrediction[];
+    waveSizing: WaveSizingRecommendation;
+    insights: string[];
+}
+/**
+ * Analyze telemetry aggregates to derive patterns.
+ * Requires at least 7 days of data for meaningful analysis.
+ */
+export declare function analyzePatterns(aggregates: TelemetryAggregate[]): PatternAnalysis;
+/**
+ * Get retry recommendation for a specific error category.
+ */
+export declare function getRetryRecommendation(patterns: RetryPattern[], category: ErrorCategory): {
+    shouldRetry: boolean;
+    confidence: number;
+};

package/dist/intelligence/pattern-analyzer.js

@@ -0,0 +1,189 @@
+/**
+ * Analyze telemetry aggregates to derive patterns.
+ * Requires at least 7 days of data for meaningful analysis.
+ */
+export function analyzePatterns(aggregates) {
+    const insights = [];
+    if (aggregates.length < 7) {
+        insights.push(`Insufficient data: ${aggregates.length} days. Need at least 7 days for pattern analysis.`);
+        return {
+            retryPatterns: [],
+            durationPredictions: [],
+            waveSizing: { optimalParallelCount: 5, rationale: 'Default (insufficient data)' },
+            insights,
+        };
+    }
+    // Aggregate totals across all periods
+    const totals = aggregates.reduce((acc, agg) => ({
+        orchestrationsTotal: acc.orchestrationsTotal + agg.orchestrationsTotal,
+        orchestrationsSuccess: acc.orchestrationsSuccess + agg.orchestrationsSuccess,
+        streamsTotal: acc.streamsTotal + agg.streamsTotal,
+        streamsSuccess: acc.streamsSuccess + agg.streamsSuccess,
+        selfHealTriggered: acc.selfHealTriggered + agg.selfHealTriggered,
+        selfHealSuccess: acc.selfHealSuccess + agg.selfHealSuccess,
+        errorsByCategory: {
+            timeout: acc.errorsByCategory.timeout + agg.errorsByCategory.timeout,
+            edit_mismatch: acc.errorsByCategory.edit_mismatch + agg.errorsByCategory.edit_mismatch,
+            invalid_artifact: acc.errorsByCategory.invalid_artifact + agg.errorsByCategory.invalid_artifact,
+            environment: acc.errorsByCategory.environment + agg.errorsByCategory.environment,
+            test_failure: acc.errorsByCategory.test_failure + agg.errorsByCategory.test_failure,
+            lint_error: acc.errorsByCategory.lint_error + agg.errorsByCategory.lint_error,
+            runtime_error: acc.errorsByCategory.runtime_error + agg.errorsByCategory.runtime_error,
+            unknown: acc.errorsByCategory.unknown + agg.errorsByCategory.unknown,
+        },
+        durationSum: acc.durationSum + (agg.avgDurationMs ?? 0),
+        durationCount: acc.durationCount + (agg.avgDurationMs ? 1 : 0),
+    }), {
+        orchestrationsTotal: 0, orchestrationsSuccess: 0, streamsTotal: 0, streamsSuccess: 0,
+        selfHealTriggered: 0, selfHealSuccess: 0,
+        errorsByCategory: {
+            timeout: 0, edit_mismatch: 0, invalid_artifact: 0, environment: 0,
+            test_failure: 0, lint_error: 0, runtime_error: 0, unknown: 0,
+        },
+        durationSum: 0,
+        durationCount: 0,
+    });
+    // Calculate retry patterns
+    const retryPatterns = [];
+    const selfHealRate = totals.selfHealTriggered > 0
+        ? totals.selfHealSuccess / totals.selfHealTriggered
+        : 0;
+    for (const [category, count] of Object.entries(totals.errorsByCategory)) {
+        if (count === 0)
+            continue;
+        // Estimate retry success rate based on error category characteristics
+        // These rates are derived from empirical observations and can be tuned
+        let retrySuccessRate;
+        let recommendation;
+        switch (category) {
+            case 'timeout':
+                retrySuccessRate = 0.7; // Timeouts often succeed on retry
+                recommendation = 'always_retry';
+                break;
+            case 'edit_mismatch':
+                retrySuccessRate = 0.9; // Almost always fixable with fresh context
+                recommendation = 'always_retry';
+                break;
+            case 'invalid_artifact':
+                retrySuccessRate = 0.6; // Often fixable with clearer instructions
+                recommendation = 'conditional_retry';
+                break;
+            case 'environment':
+                retrySuccessRate = 0.1; // Rarely fixable by retry
+                recommendation = 'no_retry';
+                break;
+            case 'test_failure':
+                // Self-healing helps significantly with test failures
+                retrySuccessRate = selfHealRate > 0.5 ? 0.7 : 0.5;
+                recommendation = 'conditional_retry';
+                break;
+            case 'lint_error':
+                retrySuccessRate = 0.8; // Usually fixable
+                recommendation = 'always_retry';
+                break;
+            case 'runtime_error':
+                retrySuccessRate = 0.4; // Depends on error type
+                recommendation = 'conditional_retry';
+                break;
+            default:
+                retrySuccessRate = 0.3;
+                recommendation = 'conditional_retry';
+        }
+        retryPatterns.push({ category, totalOccurrences: count, retrySuccessRate, recommendation });
+    }
+    // Calculate success rates
+    const successRate = totals.orchestrationsTotal > 0
+        ? totals.orchestrationsSuccess / totals.orchestrationsTotal
+        : 0;
+    const streamSuccessRate = totals.streamsTotal > 0
+        ? totals.streamsSuccess / totals.streamsTotal
+        : 0;
+    // Generate insights
+    insights.push(`Overall success rate: ${(successRate * 100).toFixed(1)}% (${totals.orchestrationsSuccess}/${totals.orchestrationsTotal})`);
+    insights.push(`Stream success rate: ${(streamSuccessRate * 100).toFixed(1)}% (${totals.streamsSuccess}/${totals.streamsTotal})`);
+    if (selfHealRate > 0) {
+        insights.push(`Self-healing success rate: ${(selfHealRate * 100).toFixed(1)}% (${totals.selfHealSuccess}/${totals.selfHealTriggered})`);
+    }
+    // Find most common error
+    const topError = Object.entries(totals.errorsByCategory)
+        .sort(([, a], [, b]) => b - a)[0];
+    if (topError && topError[1] > 0) {
+        insights.push(`Most common error: ${topError[0]} (${topError[1]} occurrences)`);
+    }
+    // Analyze trends
+    if (aggregates.length >= 14) {
+        const recentWeek = aggregates.slice(-7);
+        const previousWeek = aggregates.slice(-14, -7);
+        const recentSuccess = recentWeek.reduce((sum, a) => sum + a.orchestrationsSuccess, 0) /
+            Math.max(1, recentWeek.reduce((sum, a) => sum + a.orchestrationsTotal, 0));
+        const previousSuccess = previousWeek.reduce((sum, a) => sum + a.orchestrationsSuccess, 0) /
+            Math.max(1, previousWeek.reduce((sum, a) => sum + a.orchestrationsTotal, 0));
+        const trend = recentSuccess - previousSuccess;
+        if (Math.abs(trend) > 0.05) {
+            insights.push(`Trend: ${trend > 0 ? 'Improving' : 'Declining'} (${(trend * 100).toFixed(1)}% change week-over-week)`);
+        }
+    }
+    // Duration predictions based on actual data
+    const avgDuration = totals.durationCount > 0
+        ? totals.durationSum / totals.durationCount
+        : 60000; // Default 60s
+    const durationPredictions = [
+        {
+            complexityScore: 1,
+            predictedDurationMs: Math.round(avgDuration * 0.3),
+            confidence: totals.durationCount >= 10 ? 'medium' : 'low',
+        },
+        {
+            complexityScore: 5,
+            predictedDurationMs: Math.round(avgDuration),
+            confidence: totals.durationCount >= 10 ? 'high' : 'medium',
+        },
+        {
+            complexityScore: 10,
+            predictedDurationMs: Math.round(avgDuration * 2),
+            confidence: totals.durationCount >= 10 ? 'medium' : 'low',
+        },
+    ];
+    // Wave sizing recommendation based on success rate and error patterns
+    let optimalParallelCount = 5;
+    let rationale = '';
+    if (successRate > 0.85) {
+        optimalParallelCount = 10;
+        rationale = 'High success rate (>85%) supports aggressive parallelization';
+    }
+    else if (successRate > 0.7) {
+        optimalParallelCount = 7;
+        rationale = 'Good success rate (>70%) supports moderate parallelization';
+    }
+    else if (successRate > 0.5) {
+        optimalParallelCount = 5;
+        rationale = 'Moderate success rate (>50%) suggests conservative parallelization';
+    }
+    else {
+        optimalParallelCount = 3;
+        rationale = 'Low success rate (<50%) - recommend limited parallelization for easier debugging';
+    }
+    // Adjust for timeout patterns (high timeouts suggest reducing parallelism)
+    const timeoutRate = totals.orchestrationsTotal > 0
+        ? totals.errorsByCategory.timeout / totals.orchestrationsTotal
+        : 0;
+    if (timeoutRate > 0.2 && optimalParallelCount > 5) {
+        optimalParallelCount = Math.max(5, optimalParallelCount - 2);
+        rationale += '; reduced due to high timeout rate';
+    }
+    const waveSizing = { optimalParallelCount, rationale };
+    return { retryPatterns, durationPredictions, waveSizing, insights };
+}
+/**
+ * Get retry recommendation for a specific error category.
+ */
+export function getRetryRecommendation(patterns, category) {
+    const pattern = patterns.find(p => p.category === category);
+    if (!pattern) {
+        return { shouldRetry: true, confidence: 0.5 }; // Default to retry with low confidence
+    }
+    return {
+        shouldRetry: pattern.recommendation !== 'no_retry',
+        confidence: pattern.retrySuccessRate,
+    };
+}

package/dist/intelligence/plan-parser.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Markdown plan document parser.
+ * Extracts structure from planning documents for stream generation.
+ */
+/**
+ * Code block extracted from markdown.
+ */
+export interface CodeBlock {
+    /** Programming language (from fence) */
+    language: string;
+    /** Code content */
+    code: string;
+    /** Filename if specified in comment */
+    filename?: string;
+}
+/**
+ * Parsed section from markdown document.
+ */
+export interface ParsedSection {
+    /** Header level (1=H1, 2=H2, etc.) */
+    level: number;
+    /** Section title */
+    title: string;
+    /** Section content (excluding children) */
+    content: string;
+    /** Code blocks in this section */
+    codeBlocks: CodeBlock[];
+    /** File references found in content */
+    fileReferences: string[];
+    /** Explicit dependencies mentioned in text */
+    explicitDeps: string[];
+    /** Child sections */
+    children: ParsedSection[];
+}
+/**
+ * Fully parsed planning document.
+ */
+export interface ParsedPlan {
+    /** Document title (from first H1) */
+    title: string;
+    /** Brief description */
+    description: string;
+    /** Top-level sections */
+    sections: ParsedSection[];
+    /** All file references across document */
+    allFileReferences: string[];
+    /** All code blocks across document */
+    allCodeBlocks: CodeBlock[];
+}
+/**
+ * Extract file references from text.
+ * Matches patterns like: `src/foo.ts`, "src/bar.js", src/baz.ts
+ *
+ * Code blocks are stripped first to avoid extracting import paths
+ * (e.g., `from './foo.js'`) as real file references.
+ *
+ * Post-processing: `.js` files are dropped when a corresponding `.ts` exists,
+ * since TypeScript projects use .js in imports but .ts as source files.
+ */
+export declare function extractFileReferences(text: string): string[];
+/**
+ * Extract explicit dependency mentions from text.
+ * Matches patterns like: "depends on X", "requires Y", "after Z"
+ */
+export declare function extractExplicitDeps(text: string): string[];
+/**
+ * Extract code blocks from markdown.
+ * Only matches fences at column 0 (start of line) to avoid treating
+ * indented code examples inside YAML plan fields as separate blocks.
+ */
+export declare function extractCodeBlocks(markdown: string): CodeBlock[];
+/**
+ * Parse markdown into hierarchical sections.
+ */
+export declare function parseMarkdownSections(markdown: string): ParsedSection[];
+/**
+ * Parse a markdown planning document.
+ */
+export declare function parsePlanDocument(markdown: string): ParsedPlan;
+/**
+ * Get sections at a specific level (typically H2 for major deliverables).
+ */
+export declare function getSectionsAtLevel(sections: ParsedSection[], level: number): ParsedSection[];
+/**
+ * Flatten all sections into a single array.
+ */
+export declare function flattenSections(sections: ParsedSection[]): ParsedSection[];
+/**
+ * Parsed YAML stream definition from a code block.
+ */
+export interface YamlStreamDefinition {
+    /** Stream ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Dependencies */
+    deps?: string[];
+    /** Owned files */
+    owns?: string[];
+    /** Read files */
+    reads?: string[];
+    /** Implementation plan */
+    plan?: string;
+    /** Verification commands */
+    verify?: string[];
+    /** Setup commands */
+    setup?: string[];
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+}
+/**
+ * Extract YAML stream definitions from code blocks in a section.
+ * Supports both flat format (one block per stream) and nested `streams:` wrapper format.
+ */
+export declare function extractYamlStreamDefinitions(section: ParsedSection): YamlStreamDefinition[];
+/**
+ * Find all sections that contain YAML stream definitions.
+ */
+export declare function findYamlStreamSections(sections: ParsedSection[]): ParsedSection[];
+/**
+ * Detect whether content is an unpopulated init-plan template.
+ * Checks for the ORCHEX PLAN TEMPLATE marker in HTML comments.
+ */
+export declare function isUnpopulatedTemplate(content: string): boolean;