@wundam/orchex 1.0.0-rc.1

package/dist/intelligence/file-chunker.js

@@ -0,0 +1,64 @@
+// file-chunker.ts
+// Extracts relevant sections from large files based on keywords (stream plan)
+/**
+ * Chunks a file's content, selecting only the most relevant sections if it's large.
+ * For files over minLines, returns sections around lines matching any of the keywords (case-insensitive).
+ *
+ * - Keeps several lines of surrounding context (`contextRadius`).
+ * - If no matches, falls back to the first and last section slices.
+ *
+ * @param content The full file content
+ * @param keywords List of relevant keywords (from the stream plan)
+ * @param minLines Minimum lines above which chunking is triggered (default: 300)
+ * @param contextRadius How many lines before/after a match to include (default: 10)
+ * @param maxTotalLines Max total lines to include from this file (default: 120)
+ * @returns string (either chunks joined by \n, or full content if not large enough)
+ */
+export function extractRelevantChunks(content, keywords, minLines = 300, contextRadius = 10, maxTotalLines = 120, withLineNumbers = false) {
+    const lines = content.split(/\r?\n/);
+    if (lines.length < minLines || keywords.length === 0)
+        return content;
+    const keywordRegexes = keywords.map(kw => new RegExp(escapeRegExp(kw), 'i'));
+    // Find lines matching any keyword
+    const matches = [];
+    for (let i = 0; i < lines.length; ++i) {
+        if (keywordRegexes.some(re => re.test(lines[i]))) {
+            matches.push(i);
+        }
+    }
+    const included = new Set();
+    for (const idx of matches) {
+        for (let j = Math.max(0, idx - contextRadius); j <= Math.min(lines.length - 1, idx + contextRadius); ++j) {
+            included.add(j);
+        }
+    }
+    // If too few (or no) matches, provide fallback: first + last N lines
+    if (included.size < Math.min(20, contextRadius * 2)) {
+        for (let i = 0; i < Math.min(contextRadius * 2, lines.length); ++i)
+            included.add(i);
+        for (let i = Math.max(0, lines.length - contextRadius * 2); i < lines.length; ++i)
+            included.add(i);
+    }
+    // Sort and slice to max lines
+    const selected = Array.from(included).sort((a, b) => a - b);
+    const clipped = selected.slice(0, maxTotalLines);
+    let prev = -2;
+    const chunks = [];
+    const padWidth = withLineNumbers ? String(lines.length).length : 0;
+    for (const i of clipped) {
+        if (i > prev + 1 && chunks.length > 0)
+            chunks.push('...'); // Ellipsis between non-contiguous blocks
+        if (withLineNumbers) {
+            chunks.push(`${String(i + 1).padStart(padWidth)}: ${lines[i]}`);
+        }
+        else {
+            chunks.push(lines[i]);
+        }
+        prev = i;
+    }
+    return chunks.join('\n');
+}
+function escapeRegExp(str) {
+    // For safe regex construction
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/intelligence/fix-stream-manager.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Fix Stream Manager
+ *
+ * Handles lifecycle management of self-healing fix streams:
+ * - Cleanup of orphan fix streams when parent completes
+ * - Detection of fix stream chains
+ * - Status synchronization between parent and fix streams
+ */
+import type { Manifest, StreamStatus } from '../types.js';
+export interface CleanupResult {
+    /** Fix stream IDs that were marked as skipped */
+    skipped: string[];
+    /** Warning messages (e.g., in_progress fix streams) */
+    warnings: string[];
+}
+export interface FixChainInfo {
+    /** The original stream ID at the root of the chain */
+    rootStreamId: string;
+    /** All fix stream IDs in the chain, in order */
+    fixChain: string[];
+    /** Current status of the root stream */
+    rootStatus: StreamStatus;
+}
+/**
+ * Clean up orphan fix streams.
+ *
+ * An orphan fix stream is one where:
+ * - It has a parentStreamId pointing to another stream
+ * - That parent (or any ancestor) is now 'complete'
+ * - The fix stream itself is still 'pending'
+ *
+ * This function should be called:
+ * - Before wave calculation (to prevent orphans from appearing in waves)
+ * - After any stream is marked complete
+ */
+export declare function cleanupOrphanFixStreams(projectDir: string): Promise<CleanupResult>;
+/**
+ * Called when a stream is marked complete.
+ * Automatically cleans up any pending fix streams descended from this stream.
+ *
+ * This handles:
+ * - Direct fix streams (scaffold-fix-1 depends on scaffold)
+ * - Nested chains (scaffold-fix-2 -> scaffold-fix-1 -> scaffold)
+ */
+export declare function onStreamComplete(projectDir: string, completedStreamId: string): Promise<CleanupResult>;
+/**
+ * Get information about a fix stream chain.
+ * Useful for debugging and display.
+ */
+export declare function getFixChainInfo(manifest: Manifest, streamId: string): FixChainInfo | null;
+/**
+ * Check if this stream is a fix stream (has a parent).
+ */
+export declare function isFixStream(manifest: Manifest, streamId: string): boolean;
+/**
+ * Get the original stream ID for a fix stream.
+ * Returns the input ID if it's not a fix stream.
+ */
+export declare function getOriginalStreamId(manifest: Manifest, streamId: string): string;

package/dist/intelligence/fix-stream-manager.js

@@ -0,0 +1,212 @@
+/**
+ * Fix Stream Manager
+ *
+ * Handles lifecycle management of self-healing fix streams:
+ * - Cleanup of orphan fix streams when parent completes
+ * - Detection of fix stream chains
+ * - Status synchronization between parent and fix streams
+ */
+import { loadManifest, saveManifest } from '../manifest.js';
+import { createLogger } from '../logging.js';
+const log = createLogger('fix-stream-manager');
+// ============================================================================
+// Core Functions
+// ============================================================================
+/**
+ * Clean up orphan fix streams.
+ *
+ * An orphan fix stream is one where:
+ * - It has a parentStreamId pointing to another stream
+ * - That parent (or any ancestor) is now 'complete'
+ * - The fix stream itself is still 'pending'
+ *
+ * This function should be called:
+ * - Before wave calculation (to prevent orphans from appearing in waves)
+ * - After any stream is marked complete
+ */
+export async function cleanupOrphanFixStreams(projectDir) {
+    const manifest = await loadManifest(projectDir);
+    const result = { skipped: [], warnings: [] };
+    // Find all fix streams (streams with parentStreamId)
+    const fixStreams = Object.entries(manifest.streams).filter(([_, stream]) => stream.parentStreamId !== undefined);
+    for (const [id, stream] of fixStreams) {
+        // Only process pending fix streams
+        if (stream.status !== 'pending')
+            continue;
+        // Check if any ancestor is complete
+        if (isAncestorComplete(manifest, stream.parentStreamId)) {
+            manifest.streams[id].status = 'skipped';
+            manifest.streams[id].error = 'Parent stream completed; fix no longer needed';
+            result.skipped.push(id);
+        }
+    }
+    // Save if any changes were made
+    if (result.skipped.length > 0) {
+        await saveManifest(projectDir, manifest);
+    }
+    return result;
+}
+/**
+ * Called when a stream is marked complete.
+ * Automatically cleans up any pending fix streams descended from this stream.
+ *
+ * This handles:
+ * - Direct fix streams (scaffold-fix-1 depends on scaffold)
+ * - Nested chains (scaffold-fix-2 -> scaffold-fix-1 -> scaffold)
+ */
+export async function onStreamComplete(projectDir, completedStreamId) {
+    const manifest = await loadManifest(projectDir);
+    const result = { skipped: [], warnings: [] };
+    // Find all descendant fix streams
+    const descendants = findDescendantFixStreams(manifest, completedStreamId);
+    for (const id of descendants) {
+        const stream = manifest.streams[id];
+        if (stream.status === 'pending') {
+            // Safe to skip pending fix streams
+            manifest.streams[id].status = 'skipped';
+            manifest.streams[id].error = `Ancestor '${completedStreamId}' completed; fix no longer needed`;
+            result.skipped.push(id);
+        }
+        else if (stream.status === 'in_progress') {
+            // Can't skip in_progress streams - they may be actively running
+            // Just warn about the inconsistent state
+            result.warnings.push(`Fix stream '${id}' is in_progress but ancestor '${completedStreamId}' completed. ` +
+                `Manual intervention may be needed.`);
+        }
+        // complete, failed, skipped, blocked - no action needed
+    }
+    // Backward propagation: if the completing stream is a fix stream,
+    // mark the root original stream as complete to unblock its dependents
+    let propagated = false;
+    const completedStream = manifest.streams[completedStreamId];
+    if (completedStream?.parentStreamId) {
+        let rootId = completedStream.parentStreamId;
+        while (manifest.streams[rootId]?.parentStreamId) {
+            rootId = manifest.streams[rootId].parentStreamId;
+        }
+        const root = manifest.streams[rootId];
+        if (root && root.status === 'failed') {
+            manifest.streams[rootId].status = 'complete';
+            delete manifest.streams[rootId].error;
+            propagated = true;
+            log.info({ fixStreamId: completedStreamId, rootStreamId: rootId }, 'fix_stream_propagated_completion_to_root');
+        }
+    }
+    if (result.skipped.length > 0 || propagated) {
+        await saveManifest(projectDir, manifest);
+    }
+    return result;
+}
+/**
+ * Get information about a fix stream chain.
+ * Useful for debugging and display.
+ */
+export function getFixChainInfo(manifest, streamId) {
+    const stream = manifest.streams[streamId];
+    if (!stream)
+        return null;
+    // If this stream has no parent, it's not a fix stream
+    if (!stream.parentStreamId) {
+        return null;
+    }
+    // Walk up the chain to find the root
+    const chain = [streamId];
+    let currentId = stream.parentStreamId;
+    const visited = new Set();
+    while (currentId && !visited.has(currentId)) {
+        visited.add(currentId);
+        const current = manifest.streams[currentId];
+        if (!current)
+            break;
+        chain.unshift(currentId);
+        if (!current.parentStreamId) {
+            // Found the root
+            return {
+                rootStreamId: currentId,
+                fixChain: chain.slice(1), // Exclude the root from the fix chain
+                rootStatus: current.status ?? 'pending',
+            };
+        }
+        currentId = current.parentStreamId;
+    }
+    // If we get here, we couldn't find a valid root (broken chain)
+    return null;
+}
+/**
+ * Check if this stream is a fix stream (has a parent).
+ */
+export function isFixStream(manifest, streamId) {
+    return manifest.streams[streamId]?.parentStreamId !== undefined;
+}
+/**
+ * Get the original stream ID for a fix stream.
+ * Returns the input ID if it's not a fix stream.
+ */
+export function getOriginalStreamId(manifest, streamId) {
+    const info = getFixChainInfo(manifest, streamId);
+    return info?.rootStreamId ?? streamId;
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Check if any ancestor in the fix chain is complete.
+ */
+function isAncestorComplete(manifest, parentStreamId) {
+    let currentId = parentStreamId;
+    const visited = new Set();
+    while (currentId) {
+        // Prevent infinite loops from circular references
+        if (visited.has(currentId)) {
+            log.warn({ streamId: currentId }, 'circular_reference_in_fix_chain');
+            break;
+        }
+        visited.add(currentId);
+        const stream = manifest.streams[currentId];
+        if (!stream) {
+            // Orphaned reference - parent doesn't exist
+            log.warn({ parentId: currentId }, 'fix_stream_orphaned_parent');
+            break;
+        }
+        if (stream.status === 'complete') {
+            return true;
+        }
+        currentId = stream.parentStreamId;
+    }
+    return false;
+}
+/**
+ * Find all fix streams that descend from a given stream.
+ * This includes:
+ * - Direct children (fix streams where parentStreamId = ancestorId)
+ * - Indirect descendants (fix streams of fix streams)
+ */
+function findDescendantFixStreams(manifest, ancestorId) {
+    const descendants = [];
+    for (const [id, stream] of Object.entries(manifest.streams)) {
+        if (!stream.parentStreamId)
+            continue;
+        // Check if this stream's parent chain includes the ancestor
+        if (isDescendantOf(manifest, id, ancestorId)) {
+            descendants.push(id);
+        }
+    }
+    return descendants;
+}
+/**
+ * Check if a stream is a descendant of another stream.
+ */
+function isDescendantOf(manifest, streamId, ancestorId) {
+    let currentId = manifest.streams[streamId]?.parentStreamId;
+    const visited = new Set();
+    while (currentId) {
+        if (visited.has(currentId))
+            break;
+        visited.add(currentId);
+        if (currentId === ancestorId) {
+            return true;
+        }
+        currentId = manifest.streams[currentId]?.parentStreamId;
+    }
+    return false;
+}

package/dist/intelligence/heuristics.d.ts

@@ -0,0 +1,23 @@
+export interface FileGroup {
+    files: string[];
+    reason: string;
+}
+export interface ComplexityScore {
+    score: number;
+    factors: string[];
+}
+/**
+ * Analyze import/require statements to find files commonly modified together.
+ * Takes a map of filePath -> fileContent.
+ */
+export declare function detectFileCoChanges(fileContents: Record<string, string>): FileGroup[];
+/**
+ * Estimate stream complexity from plan text, file count, and dependency count.
+ */
+export declare function estimateComplexity(stream: {
+    plan?: string;
+    owns?: string[];
+    deps?: string[];
+}): ComplexityScore;
+export declare function extractImports(content: string): string[];
+export declare function resolveImportPath(fromFile: string, importPath: string): string | null;

package/dist/intelligence/heuristics.js

@@ -0,0 +1,124 @@
+/**
+ * Analyze import/require statements to find files commonly modified together.
+ * Takes a map of filePath -> fileContent.
+ */
+export function detectFileCoChanges(fileContents) {
+    const importGraph = new Map();
+    for (const [filePath, content] of Object.entries(fileContents)) {
+        const imports = extractImports(content);
+        importGraph.set(filePath, new Set(imports));
+    }
+    // Group files that import each other (bidirectional edges)
+    const groups = [];
+    const visited = new Set();
+    for (const [file, imports] of importGraph) {
+        if (visited.has(file))
+            continue;
+        const group = [file];
+        visited.add(file);
+        for (const imported of imports) {
+            const resolvedImport = resolveImportPath(file, imported);
+            if (resolvedImport && importGraph.has(resolvedImport) && !visited.has(resolvedImport)) {
+                // Check if it imports back
+                const reverseImports = importGraph.get(resolvedImport);
+                if (reverseImports) {
+                    const resolvedBack = Array.from(reverseImports).some((imp) => resolveImportPath(resolvedImport, imp) === file);
+                    if (resolvedBack) {
+                        group.push(resolvedImport);
+                        visited.add(resolvedImport);
+                    }
+                }
+            }
+        }
+        if (group.length > 1) {
+            groups.push({
+                files: group,
+                reason: 'Bidirectional imports detected \u2014 these files are tightly coupled.',
+            });
+        }
+    }
+    return groups;
+}
+/**
+ * Estimate stream complexity from plan text, file count, and dependency count.
+ */
+export function estimateComplexity(stream) {
+    const factors = [];
+    let score = 1;
+    // Plan length factor
+    const planLength = stream.plan?.length ?? 0;
+    if (planLength > 1000) {
+        score += 3;
+        factors.push(`Long plan (${planLength} chars)`);
+    }
+    else if (planLength > 500) {
+        score += 2;
+        factors.push(`Medium plan (${planLength} chars)`);
+    }
+    else if (planLength > 200) {
+        score += 1;
+        factors.push(`Short plan (${planLength} chars)`);
+    }
+    // File count factor
+    const fileCount = stream.owns?.length ?? 0;
+    if (fileCount > 5) {
+        score += 3;
+        factors.push(`Many files (${fileCount})`);
+    }
+    else if (fileCount > 2) {
+        score += 2;
+        factors.push(`Several files (${fileCount})`);
+    }
+    else if (fileCount > 0) {
+        score += 1;
+        factors.push(`Few files (${fileCount})`);
+    }
+    // Dependency count factor
+    const depCount = stream.deps?.length ?? 0;
+    if (depCount > 3) {
+        score += 2;
+        factors.push(`Many deps (${depCount})`);
+    }
+    else if (depCount > 0) {
+        score += 1;
+        factors.push(`Some deps (${depCount})`);
+    }
+    return {
+        score: Math.min(score, 10),
+        factors,
+    };
+}
+// --- Exported helpers ---
+export function extractImports(content) {
+    const imports = [];
+    // ESM: import ... from '...'
+    const esmRegex = /(?:import|export)\s+.*?from\s+['"](.+?)['"]/g;
+    let match;
+    while ((match = esmRegex.exec(content)) !== null) {
+        imports.push(match[1]);
+    }
+    // CJS: require('...')
+    const cjsRegex = /require\s*\(\s*['"](.+?)['"]\s*\)/g;
+    while ((match = cjsRegex.exec(content)) !== null) {
+        imports.push(match[1]);
+    }
+    return imports;
+}
+export function resolveImportPath(fromFile, importPath) {
+    if (!importPath.startsWith('.'))
+        return null; // skip node_modules
+    const dir = fromFile.substring(0, fromFile.lastIndexOf('/'));
+    // Normalize: remove .js extension, add .ts for matching
+    const normalized = importPath.replace(/\.js$/, '');
+    const parts = [...dir.split('/'), ...normalized.split('/')];
+    const resolved = [];
+    for (const part of parts) {
+        if (part === '..')
+            resolved.pop();
+        else if (part !== '.')
+            resolved.push(part);
+    }
+    const result = resolved.join('/');
+    // Try .ts extension
+    return result.endsWith('.ts') ? result : result + '.ts';
+}

package/dist/intelligence/learning-engine.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Learning engine for adaptive threshold adjustment in Orchex Learn.
+ * Correlates context characteristics with execution success and adapts thresholds.
+ */
+import type { TelemetryEvent } from '../telemetry/telemetry-types.js';
+/**
+ * Stream categories for per-category learning.
+ * Canonical source of truth for stream categorization across all intelligence modules.
+ */
+export type StreamCategory = 'code' | 'docs' | 'tutorial' | 'integration-guide' | 'test' | 'migration' | 'api-reference' | 'other';
+/**
+ * Confidence level for learned thresholds.
+ */
+export type ConfidenceLevel = 'low' | 'medium' | 'high';
+/**
+ * Learned thresholds that adapt based on execution history.
+ */
+export interface LearnedThresholds {
+    /** Maximum recommended owns count per category */
+    maxOwnsCount: Record<StreamCategory, number>;
+    /** Maximum recommended reads count per category */
+    maxReadsCount: Record<StreamCategory, number>;
+    /** Maximum recommended context tokens per category */
+    maxContextTokens: Record<StreamCategory, number>;
+    /** Global soft limit derived from learning */
+    globalSoftLimit: number;
+    /** Global hard limit derived from learning */
+    globalHardLimit: number;
+    /** Number of samples used to derive these thresholds */
+    sampleCount: number;
+    /** Confidence level based on sample count */
+    confidence: ConfidenceLevel;
+    /** Last update timestamp */
+    lastUpdated: string;
+    /** Version for schema evolution */
+    version: number;
+}
+/**
+ * Correlation between a factor and execution success.
+ */
+export interface LearningCorrelation {
+    /** The factor being analyzed */
+    factor: string;
+    /** Success rate (0-1) for this factor */
+    successRate: number;
+    /** Number of samples */
+    sampleSize: number;
+    /** Recommended threshold value */
+    threshold: number;
+    /** Human-readable recommendation */
+    recommendation: string;
+}
+/**
+ * Result of learning analysis.
+ */
+export interface LearningResult {
+    /** Correlations discovered */
+    correlations: LearningCorrelation[];
+    /** Suggested threshold updates */
+    suggestedThresholds: Partial<LearnedThresholds>;
+    /** Human-readable insights */
+    insights: string[];
+    /** Whether enough data exists for meaningful learning */
+    hasEnoughData: boolean;
+}
+/** Default thresholds before learning */
+export declare const DEFAULT_THRESHOLDS: LearnedThresholds;
+/** Minimum samples required for learning */
+export declare const MIN_SAMPLES_FOR_LEARNING = 20;
+/** Minimum samples for high confidence */
+export declare const HIGH_CONFIDENCE_THRESHOLD = 100;
+/** Minimum samples for medium confidence */
+export declare const MEDIUM_CONFIDENCE_THRESHOLD = 50;
+/**
+ * Determine confidence level from sample count.
+ */
+export declare function getConfidenceLevel(sampleCount: number): ConfidenceLevel;
+/**
+ * Categorize a stream based on its name and plan.
+ * Order matters: more specific patterns before general ones.
+ * Returns 'code' as default since most uncategorized streams are implementation work.
+ */
+export declare function categorizeStream(name: string, plan?: string): StreamCategory;
+/**
+ * Correlate context characteristics with success from telemetry events.
+ */
+export declare function correlateContextWithSuccess(events: TelemetryEvent[], minSamples?: number): LearningResult;
+/**
+ * Update thresholds based on learning results.
+ */
+export declare function updateThresholds(current: LearnedThresholds, learningResult: LearningResult, learningRate?: number): LearnedThresholds;
+/**
+ * Save learned thresholds to project directory.
+ */
+export declare function saveLearnedThresholds(projectDir: string, thresholds: LearnedThresholds): Promise<void>;
+/**
+ * Load learned thresholds from project directory.
+ */
+export declare function loadLearnedThresholds(projectDir: string): Promise<LearnedThresholds | null>;
+/**
+ * Get thresholds for a project, falling back to defaults.
+ */
+export declare function getThresholds(projectDir: string): Promise<LearnedThresholds>;
+/**
+ * Get recommended limit for a stream category.
+ */
+export declare function getRecommendedLimit(thresholds: LearnedThresholds, category: StreamCategory, limitType: 'owns' | 'reads' | 'tokens'): number;
+/**
+ * Minimal stream result shape needed for learning event conversion.
+ * Avoids importing full StreamResultWithBudget to prevent circular deps.
+ */
+export interface LearningStreamResult {
+    id: string;
+    name: string;
+    status: string;
+    error?: string;
+    tokensUsed?: {
+        input?: number;
+        output?: number;
+    };
+    executionTimeMs?: number;
+    contextMetrics?: {
+        estimatedTokens: number;
+        budgetUtilization: number;
+        violationType: string;
+        budgetLimit: number;
+    };
+}
+/**
+ * Convert a stream result to a TelemetryEvent for learning.
+ */
+export declare function streamResultToTelemetryEvent(result: LearningStreamResult, provider?: string, model?: string): TelemetryEvent;
+/**
+ * Append telemetry events to the local events file (.orchex/learn/events.jsonl).
+ * Uses JSONL (one JSON object per line) for append-friendly storage.
+ */
+export declare function appendLocalEvents(projectDir: string, events: TelemetryEvent[]): Promise<void>;
+/**
+ * Load all local telemetry events from the JSONL file.
+ * Skips malformed lines silently.
+ */
+export declare function loadLocalEvents(projectDir: string): Promise<TelemetryEvent[]>;
+/**
+ * Run a complete learning cycle: load events → correlate → update → save.
+ * Returns the learning result (or null if not enough data).
+ * This is the main entry point called after an orchestration completes.
+ */
+export declare function runLearningCycle(projectDir: string): Promise<LearningResult | null>;
+/**
+ * Run learning cycle from telemetry store events (cloud mode).
+ * Aggregates across all users for global threshold learning.
+ */
+export declare function runCloudLearningCycle(events: TelemetryEvent[], projectDir: string): Promise<LearningResult | null>;
+/**
+ * Format a learning report for display.
+ */
+export declare function formatLearningReport(result: LearningResult): string;