@wundam/orchex 1.0.0-rc.1

package/dist/intelligence/self-healer.js

@@ -0,0 +1,84 @@
+import { analyzeError } from './error-analyzer.js';
+const MAX_ATTEMPTS = 3;
+/**
+ * Count total attempts in the fix chain by traversing parentStreamId.
+ */
+function countChainAttempts(manifest, streamId) {
+    let count = 0;
+    let currentId = streamId;
+    while (currentId) {
+        const current = manifest.streams[currentId];
+        if (!current)
+            break; // Orphaned fix stream, stop traversing
+        count += current.attempts ?? 0;
+        // Move to parent
+        currentId = current.parentStreamId;
+    }
+    return count;
+}
+/**
+ * Generate a fix stream for a failed stream.
+ * Returns null if the error is non-retryable or max attempts exceeded.
+ *
+ * Tracks fix chain depth via parentStreamId to prevent infinite fix-fix-fix chains.
+ */
+export function generateFixStream(manifest, failedStreamId) {
+    const stream = manifest.streams[failedStreamId];
+    if (!stream)
+        return null;
+    // Skip fix generation for setup failures (never entered in_progress).
+    // Setup failures have error messages prefixed with "Setup failed:" by the orchestrator.
+    if (stream.status === 'failed' && stream.error?.startsWith('Setup failed:')) {
+        return null;
+    }
+    const errorString = stream.error ?? '';
+    const analysis = analyzeError(errorString);
+    if (!analysis.retryable)
+        return null;
+    // Count attempts across the entire fix chain
+    const totalChainAttempts = countChainAttempts(manifest, failedStreamId);
+    if (totalChainAttempts >= MAX_ATTEMPTS)
+        return null;
+    const attempts = stream.attempts ?? 0;
+    const fixNumber = attempts + 1;
+    const fixStreamId = `${failedStreamId}-fix-${fixNumber}`;
+    // Chain the fix stream to the immediate parent (the failed stream just prior)
+    const parentStreamId = failedStreamId;
+    const augmentedPlan = [
+        `## Fix Attempt #${fixNumber} for "${stream.name}"`,
+        '',
+        '### Original Plan',
+        stream.plan ?? '(no plan)',
+        '',
+        '### Error That Occurred',
+        '```',
+        errorString,
+        '```',
+        '',
+        `### Error Category: ${analysis.category}`,
+        '',
+        `### Suggestion: ${analysis.suggestion}`,
+        '',
+        '### Instructions',
+        `This is a retry of the failed stream "${failedStreamId}".`,
+        'Fix the issue described above. The original files are in your owns list.',
+        'Make sure to address the specific error before implementing the rest of the plan.',
+    ].join('\n');
+    const fixStream = {
+        name: `${stream.name} (Fix #${fixNumber})`,
+        deps: stream.deps ?? [],
+        owns: stream.owns ?? [],
+        reads: stream.reads ?? [],
+        plan: augmentedPlan,
+        setup: stream.setup ?? [],
+        verify: stream.verify ?? [],
+        status: 'pending',
+        attempts: 0,
+        parentStreamId: parentStreamId, // Immediate parent is always failedStreamId
+    };
+    return {
+        fixStreamId,
+        fixStream,
+        analysis: { category: analysis.category, suggestion: analysis.suggestion },
+    };
+}

package/dist/intelligence/slicing-metrics.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Slicing metrics for stream execution analysis.
+ * Provides category-specific timeout recommendations and execution insights.
+ *
+ * NOTE: StreamCategory and categorizeStream are imported from learning-engine.ts
+ * to maintain a single source of truth for stream categorization.
+ */
+import type { TelemetryEvent } from '../telemetry/telemetry-types.js';
+import type { StreamResult } from '../types.js';
+import { type StreamCategory, categorizeStream as categorizeStreamFromLearningEngine } from './learning-engine.js';
+export type { StreamCategory };
+export { categorizeStreamFromLearningEngine as categorizeStream };
+/**
+ * Aggregated metrics for a specific stream category.
+ */
+export interface CategoryMetrics {
+    category: StreamCategory;
+    totalStreams: number;
+    successfulStreams: number;
+    failedStreams: number;
+    timeoutStreams: number;
+    successRate: number;
+    timeoutRate: number;
+    avgExecutionMs: number;
+    p50ExecutionMs: number;
+    p95ExecutionMs: number;
+    maxExecutionMs: number;
+}
+/**
+ * Insight or warning about stream execution patterns.
+ */
+export interface SlicingInsight {
+    category: StreamCategory;
+    type: 'warning' | 'info';
+    message: string;
+    metric: string;
+    value: number;
+    threshold: number;
+}
+/**
+ * Aggregate execution metrics by stream category.
+ * Calculates success rates, timeout rates, and execution time percentiles.
+ */
+export declare function aggregateMetricsByCategory(events: TelemetryEvent[], streamResults?: StreamResult[]): Map<StreamCategory, CategoryMetrics>;
+/**
+ * Generate insights and warnings based on category metrics.
+ * Identifies categories with low success rates or high timeout rates.
+ */
+export declare function generateSlicingInsights(categoryMetrics: Map<StreamCategory, CategoryMetrics>): SlicingInsight[];
+/**
+ * Get recommended timeout value for a stream category.
+ * Returns timeout in milliseconds with safety margin included.
+ */
+export declare function getRecommendedTimeout(category: StreamCategory): number;
+/**
+ * Get recommended timeout for a specific stream based on its characteristics.
+ */
+export declare function getStreamTimeout(streamName: string, streamPlan?: string, customTimeout?: number): number;
+/**
+ * Format category metrics into a human-readable report.
+ */
+export declare function formatCategoryReport(categoryMetrics: Map<StreamCategory, CategoryMetrics>): string;

package/dist/intelligence/slicing-metrics.js

@@ -0,0 +1,202 @@
+/**
+ * Slicing metrics for stream execution analysis.
+ * Provides category-specific timeout recommendations and execution insights.
+ *
+ * NOTE: StreamCategory and categorizeStream are imported from learning-engine.ts
+ * to maintain a single source of truth for stream categorization.
+ */
+import { categorizeStream as categorizeStreamFromLearningEngine, } from './learning-engine.js';
+export { categorizeStreamFromLearningEngine as categorizeStream };
+/**
+ * Recommended timeout values by category.
+ * Based on p95 execution times with safety margin.
+ */
+const RECOMMENDED_TIMEOUTS = {
+    code: 120000, // 2 minutes - typical code generation
+    docs: 60000, // 1 minute - documentation is usually faster
+    tutorial: 90000, // 1.5 minutes - tutorials with examples
+    'integration-guide': 90000, // 1.5 minutes - similar to tutorials
+    'api-reference': 60000, // 1 minute - structured API docs
+    test: 120000, // 2 minutes - test generation can be complex
+    migration: 180000, // 3 minutes - migrations are complex
+    other: 120000, // 2 minutes - default for uncategorized
+};
+/**
+ * Thresholds for generating warnings.
+ */
+const WARNING_THRESHOLDS = {
+    lowSuccessRate: 0.8, // Warn if success rate < 80%
+    highTimeoutRate: 0.2, // Warn if timeout rate > 20%
+};
+/**
+ * Aggregate execution metrics by stream category.
+ * Calculates success rates, timeout rates, and execution time percentiles.
+ */
+export function aggregateMetricsByCategory(events, streamResults = []) {
+    const categoryData = new Map();
+    // Initialize all categories
+    const categories = [
+        'code',
+        'docs',
+        'tutorial',
+        'integration-guide',
+        'api-reference',
+        'test',
+        'migration',
+        'other',
+    ];
+    for (const cat of categories) {
+        categoryData.set(cat, {
+            total: 0,
+            success: 0,
+            failed: 0,
+            timeout: 0,
+            durations: [],
+        });
+    }
+    // Process telemetry events
+    const streamEvents = events.filter(e => e.eventType === 'stream_complete' || e.eventType === 'stream_failed');
+    for (const event of streamEvents) {
+        // Extract stream name from event (would need to be added to TelemetryEvent)
+        // For now, we'll primarily use streamResults which have names
+    }
+    // Process stream results (primary source)
+    for (const result of streamResults) {
+        const category = categorizeStreamFromLearningEngine(result.name, result.summary);
+        const data = categoryData.get(category);
+        data.total++;
+        if (result.status === 'complete') {
+            data.success++;
+        }
+        else if (result.status === 'failed') {
+            data.failed++;
+            // Check if it's a timeout error
+            if (result.error?.toLowerCase().includes('timeout')) {
+                data.timeout++;
+            }
+        }
+        // Record execution time if available
+        if (result.executionTimeMs !== undefined) {
+            data.durations.push(result.executionTimeMs);
+        }
+    }
+    // Calculate metrics for each category
+    const metrics = new Map();
+    for (const [category, data] of categoryData) {
+        const sortedDurations = data.durations.sort((a, b) => a - b);
+        const categoryMetrics = {
+            category,
+            totalStreams: data.total,
+            successfulStreams: data.success,
+            failedStreams: data.failed,
+            timeoutStreams: data.timeout,
+            successRate: data.total > 0 ? data.success / data.total : 0,
+            timeoutRate: data.total > 0 ? data.timeout / data.total : 0,
+            avgExecutionMs: sortedDurations.length > 0
+                ? Math.round(sortedDurations.reduce((a, b) => a + b, 0) / sortedDurations.length)
+                : 0,
+            p50ExecutionMs: sortedDurations.length > 0
+                ? sortedDurations[Math.floor(sortedDurations.length * 0.5)]
+                : 0,
+            p95ExecutionMs: sortedDurations.length > 0
+                ? sortedDurations[Math.floor(sortedDurations.length * 0.95)]
+                : 0,
+            maxExecutionMs: sortedDurations.length > 0
+                ? sortedDurations[sortedDurations.length - 1]
+                : 0,
+        };
+        metrics.set(category, categoryMetrics);
+    }
+    return metrics;
+}
+/**
+ * Generate insights and warnings based on category metrics.
+ * Identifies categories with low success rates or high timeout rates.
+ */
+export function generateSlicingInsights(categoryMetrics) {
+    const insights = [];
+    for (const [category, metrics] of categoryMetrics) {
+        // Skip categories with no data
+        if (metrics.totalStreams === 0) {
+            continue;
+        }
+        // Check for low success rate
+        if (metrics.successRate < WARNING_THRESHOLDS.lowSuccessRate) {
+            insights.push({
+                category,
+                type: 'warning',
+                message: `Low success rate for ${category} streams: ${(metrics.successRate * 100).toFixed(1)}%`,
+                metric: 'successRate',
+                value: metrics.successRate,
+                threshold: WARNING_THRESHOLDS.lowSuccessRate,
+            });
+        }
+        // Check for high timeout rate
+        if (metrics.timeoutRate > WARNING_THRESHOLDS.highTimeoutRate) {
+            insights.push({
+                category,
+                type: 'warning',
+                message: `High timeout rate for ${category} streams: ${(metrics.timeoutRate * 100).toFixed(1)}%. Consider increasing timeout to ${getRecommendedTimeout(category)}ms`,
+                metric: 'timeoutRate',
+                value: metrics.timeoutRate,
+                threshold: WARNING_THRESHOLDS.highTimeoutRate,
+            });
+        }
+        // Informational insight if p95 is approaching recommended timeout
+        const recommendedTimeout = getRecommendedTimeout(category);
+        if (metrics.p95ExecutionMs > 0 &&
+            metrics.p95ExecutionMs > recommendedTimeout * 0.8) {
+            insights.push({
+                category,
+                type: 'info',
+                message: `${category} streams approaching timeout threshold. P95: ${metrics.p95ExecutionMs}ms, recommended: ${recommendedTimeout}ms`,
+                metric: 'p95ExecutionMs',
+                value: metrics.p95ExecutionMs,
+                threshold: recommendedTimeout,
+            });
+        }
+    }
+    return insights;
+}
+/**
+ * Get recommended timeout value for a stream category.
+ * Returns timeout in milliseconds with safety margin included.
+ */
+export function getRecommendedTimeout(category) {
+    return RECOMMENDED_TIMEOUTS[category];
+}
+/**
+ * Get recommended timeout for a specific stream based on its characteristics.
+ */
+export function getStreamTimeout(streamName, streamPlan, customTimeout) {
+    // Use custom timeout if provided
+    if (customTimeout !== undefined && customTimeout > 0) {
+        return customTimeout;
+    }
+    // Otherwise, use category-based recommendation
+    const category = categorizeStreamFromLearningEngine(streamName, streamPlan);
+    return getRecommendedTimeout(category);
+}
+/**
+ * Format category metrics into a human-readable report.
+ */
+export function formatCategoryReport(categoryMetrics) {
+    const lines = ['\n=== Stream Execution Metrics by Category ===\n'];
+    for (const [category, metrics] of categoryMetrics) {
+        if (metrics.totalStreams === 0)
+            continue;
+        lines.push(`${category.toUpperCase()}:`);
+        lines.push(`  Total: ${metrics.totalStreams}`);
+        lines.push(`  Success Rate: ${(metrics.successRate * 100).toFixed(1)}% (${metrics.successfulStreams}/${metrics.totalStreams})`);
+        if (metrics.timeoutStreams > 0) {
+            lines.push(`  Timeout Rate: ${(metrics.timeoutRate * 100).toFixed(1)}% (${metrics.timeoutStreams}/${metrics.totalStreams})`);
+        }
+        if (metrics.avgExecutionMs > 0) {
+            lines.push(`  Avg Execution: ${(metrics.avgExecutionMs / 1000).toFixed(1)}s`);
+            lines.push(`  P95 Execution: ${(metrics.p95ExecutionMs / 1000).toFixed(1)}s`);
+            lines.push(`  Recommended Timeout: ${(getRecommendedTimeout(category) / 1000).toFixed(0)}s`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/intelligence/slicing-templates.d.ts

@@ -0,0 +1,81 @@
+import type { StreamDefinition, StreamDefinitionInput } from '../types.js';
+/**
+ * A template for common stream patterns.
+ * Templates help guide automatic stream generation for typical tasks.
+ */
+export interface SlicingTemplate {
+    /** Template identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of when to use this template */
+    description: string;
+    /** Keywords that suggest this template applies */
+    keywords: string[];
+    /** Pattern indicators (e.g., "multiple files in same directory") */
+    patterns: string[];
+    /** Suggested stream structure */
+    streamStructure: TemplateStreamStructure[];
+    /** Guidelines for applying the template */
+    guidelines: string[];
+}
+/**
+ * Structure for a stream in a template.
+ */
+export interface TemplateStreamStructure {
+    /** Stream name pattern (e.g., "setup-{component}") */
+    namePattern: string;
+    /** Description of what this stream does */
+    purpose: string;
+    /** Dependencies on other streams in the template */
+    dependsOn: string[];
+    /** Typical file ownership patterns */
+    ownsPatterns: string[];
+    /** Typical file reading patterns */
+    readsPatterns: string[];
+    /** Suggested plan outline */
+    planOutline: string;
+}
+/**
+ * Suggestion for splitting a stream into smaller streams.
+ */
+export interface SplitSuggestion {
+    /** Original stream name */
+    originalStream: string;
+    /** Reason for suggesting a split */
+    reason: string;
+    /** Matched template (if any) */
+    template?: SlicingTemplate;
+    /** Suggested new streams */
+    suggestedStreams: StreamDefinitionInput[];
+    /** Additional guidance */
+    guidance: string[];
+}
+/**
+ * Find the best matching template for a stream description.
+ * Returns null if no good match is found.
+ */
+export declare function findMatchingTemplate(description: string): SlicingTemplate | null;
+/**
+ * Apply a template to generate stream definitions.
+ * Returns suggested streams based on the template structure.
+ */
+export declare function applyTemplate(template: SlicingTemplate, context: {
+    featureName: string;
+    components?: string[];
+    topics?: string[];
+    modules?: string[];
+}): StreamDefinitionInput[];
+/**
+ * Analyze a stream and suggest how to split it if needed.
+ * Returns null if the stream seems appropriately sized.
+ */
+export declare function suggestSplit(stream: StreamDefinition | StreamDefinitionInput): SplitSuggestion | null;
+/**
+ * Get all available templates.
+ */
+export declare function getAllTemplates(): SlicingTemplate[];
+/**
+ * Get a specific template by ID.
+ */
+export declare function getTemplate(id: string): SlicingTemplate | null;