@wundam/orchex 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/intelligence/budget-enforcer.js

@@ -1,226 +0,0 @@
-/**
- * Context budget enforcement for Orchex Learn.
- * Implements soft/hard limit checking with provider-aware context limits.
- */
-/**
- * Provider-specific context window limits (in tokens).
- * These represent the maximum input context size for each provider's models.
- */
-export const PROVIDER_CONTEXT_LIMITS = {
-    anthropic: 200000, // Claude 4.5 Sonnet/Opus context window
-    openai: 128000, // GPT-4.5 Turbo context window
-    gemini: 1000000, // Gemini 2.5 Pro context window
-    deepseek: 128000, // DeepSeek V3.2 context window
-    ollama: 128000, // Llama 3.3 70B context window
-    default: 100000, // Safe default for unknown providers
-};
-/**
- * Model-specific context limits (overrides provider defaults).
- */
-export const MODEL_CONTEXT_LIMITS = {
-    // Anthropic (Feb 2026)
-    'claude-opus-4-5-20251101': 200000,
-    'claude-sonnet-4-5-20250929': 200000,
-    'claude-sonnet-4-20250514': 200000,
-    'claude-3-5-sonnet-20241022': 200000,
-    'claude-3-opus-20240229': 200000,
-    'claude-3-haiku-20240307': 200000,
-    // OpenAI (Feb 2026)
-    'gpt-4.5-turbo': 128000,
-    'gpt-4-turbo': 128000,
-    'gpt-4-turbo-preview': 128000,
-    'gpt-4o': 128000,
-    'gpt-4o-mini': 128000,
-    'o1-preview': 128000,
-    'o1-mini': 128000,
-    'o3-mini': 200000,
-    'gpt-3.5-turbo': 16385,
-    // Google (Feb 2026)
-    'gemini-2.5-pro': 1000000,
-    'gemini-2.0-flash': 1000000,
-    'gemini-1.5-pro': 1000000,
-    'gemini-1.5-flash': 1000000,
-    'gemini-pro': 32768,
-    // DeepSeek (Feb 2026)
-    'deepseek-chat': 128000, // V3.2
-    'deepseek-coder': 128000, // V3.2
-    'deepseek-reasoner': 128000, // R1
-    // Ollama/Local
-    'llama3.3:70b': 128000,
-    'llama3.2:latest': 128000,
-    'mistral:latest': 32000,
-};
-/** Default soft limit as percentage of provider limit */
-export const DEFAULT_SOFT_LIMIT_RATIO = 0.7;
-/** Default hard limit as percentage of provider limit */
-export const DEFAULT_HARD_LIMIT_RATIO = 0.9;
-/** Default warning threshold (start warning at 80% of soft limit) */
-export const DEFAULT_WARNING_THRESHOLD = 0.8;
-/**
- * Get the context limit for a provider, optionally with model-specific override.
- */
-export function getProviderLimit(provider, model) {
-    // Check model-specific limit first
-    if (model && MODEL_CONTEXT_LIMITS[model]) {
-        return MODEL_CONTEXT_LIMITS[model];
-    }
-    // Fall back to provider limit
-    return PROVIDER_CONTEXT_LIMITS[provider] ?? PROVIDER_CONTEXT_LIMITS.default;
-}
-/**
- * Create a budget config from manifest/stream settings and provider info.
- */
-export function createBudgetConfig(budget, provider, model) {
-    const providerLimit = getProviderLimit(provider, model);
-    // Use explicit limits if provided, otherwise derive from provider limit
-    const softLimitTokens = budget?.softLimitTokens ?? Math.floor(providerLimit * DEFAULT_SOFT_LIMIT_RATIO);
-    const hardLimitTokens = budget?.hardLimitTokens ?? Math.floor(providerLimit * DEFAULT_HARD_LIMIT_RATIO);
-    const enforcementLevel = budget?.enforcementLevel ?? 'warn';
-    const warningThreshold = budget?.warningThreshold ?? DEFAULT_WARNING_THRESHOLD;
-    return {
-        enforcementLevel,
-        softLimitTokens,
-        hardLimitTokens,
-        warningThreshold,
-        provider,
-        model,
-    };
-}
-/**
- * Generate a suggestion for reducing context size.
- */
-export function getSuggestion(violationType, estimatedTokens, limit) {
-    const overage = estimatedTokens - limit;
-    const percentOver = Math.round((overage / limit) * 100);
-    if (violationType === 'none') {
-        return '';
-    }
-    const suggestions = [
-        `Context is ${percentOver}% over the ${violationType} limit.`,
-        'Consider:',
-        '  - Reducing the number of files in "reads"',
-        '  - Splitting the stream into smaller tasks',
-        '  - Using file patterns instead of directories',
-        '  - Extracting only function signatures instead of full files',
-    ];
-    if (violationType === 'hard') {
-        suggestions.push('  - Or increase the hard limit in contextBudget settings');
-    }
-    return suggestions.join('\n');
-}
-/**
- * Check estimated context size against budget limits.
- *
- * @param estimatedTokens - Estimated context tokens
- * @param config - Budget configuration
- * @returns Check result with violation status and suggestions
- */
-export function checkBudget(estimatedTokens, config) {
-    const providerLimit = getProviderLimit(config.provider, config.model);
-    const { softLimitTokens, hardLimitTokens, warningThreshold, enforcementLevel } = config;
-    // Determine violation type
-    let violationType = 'none';
-    let budgetLimit = softLimitTokens;
-    if (estimatedTokens >= hardLimitTokens) {
-        violationType = 'hard';
-        budgetLimit = hardLimitTokens;
-    }
-    else if (estimatedTokens >= softLimitTokens) {
-        violationType = 'soft';
-        budgetLimit = softLimitTokens;
-    }
-    // Calculate utilization ratio (against soft limit for warnings)
-    const utilizationRatio = estimatedTokens / softLimitTokens;
-    // Determine if execution is allowed based on enforcement level
-    let allowed = true;
-    if (violationType === 'hard' && enforcementLevel === 'hard') {
-        allowed = false;
-    }
-    else if (violationType === 'soft' && enforcementLevel === 'soft') {
-        // Soft enforcement: warn but don't block by default
-        // Could be extended to block with user confirmation
-        allowed = true;
-    }
-    // Generate warning if needed
-    let warning;
-    if (violationType !== 'none') {
-        const limitType = violationType === 'hard' ? 'hard limit' : 'soft limit';
-        warning = `Context size (${estimatedTokens.toLocaleString()} tokens) exceeds ${limitType} (${budgetLimit.toLocaleString()} tokens)`;
-        if (!allowed) {
-            warning += '. Execution blocked.';
-        }
-    }
-    else if (utilizationRatio >= warningThreshold) {
-        // Warn if approaching soft limit
-        const percentUsed = Math.round(utilizationRatio * 100);
-        warning = `Context size at ${percentUsed}% of soft limit (${estimatedTokens.toLocaleString()} / ${softLimitTokens.toLocaleString()} tokens)`;
-    }
-    // Generate suggestion if violating
-    const suggestion = violationType !== 'none'
-        ? getSuggestion(violationType, estimatedTokens, budgetLimit)
-        : undefined;
-    return {
-        allowed,
-        violationType,
-        estimatedTokens,
-        budgetLimit,
-        utilizationRatio,
-        warning,
-        suggestion,
-        providerLimit,
-    };
-}
-/**
- * Analyze budget for multiple streams.
- *
- * @param streams - Map of stream ID to estimated tokens
- * @param config - Budget configuration
- * @returns Analysis result with warnings and violation details
- */
-export function analyzeStreamBudgets(streams, config) {
-    const analyses = [];
-    const streamsAtRisk = [];
-    const streamsTooLarge = [];
-    const warnings = [];
-    let totalEstimatedTokens = 0;
-    for (const [streamId, estimatedTokens] of streams) {
-        const check = checkBudget(estimatedTokens, config);
-        totalEstimatedTokens += estimatedTokens;
-        analyses.push({ streamId, estimatedTokens, check });
-        if (check.violationType === 'hard') {
-            streamsTooLarge.push(streamId);
-            warnings.push(`Stream "${streamId}": ${check.warning}`);
-        }
-        else if (check.violationType === 'soft') {
-            streamsAtRisk.push(streamId);
-            warnings.push(`Stream "${streamId}": ${check.warning}`);
-        }
-        else if (check.warning) {
-            // Approaching limit warning
-            warnings.push(`Stream "${streamId}": ${check.warning}`);
-        }
-    }
-    return {
-        totalEstimatedTokens,
-        streamsAtRisk,
-        streamsTooLarge,
-        hasHardViolations: streamsTooLarge.length > 0,
-        hasSoftViolations: streamsAtRisk.length > 0,
-        analyses,
-        warnings,
-    };
-}
-/**
- * Custom error for budget exceeded scenarios.
- */
-export class ContextBudgetExceededError extends Error {
-    checkResult;
-    streamId;
-    constructor(checkResult, streamId) {
-        const streamInfo = streamId ? ` for stream "${streamId}"` : '';
-        super(`Context budget exceeded${streamInfo}: ${checkResult.warning}`);
-        this.checkResult = checkResult;
-        this.streamId = streamId;
-        this.name = 'ContextBudgetExceededError';
-    }
-}

package/dist/intelligence/context-optimizer.d.ts

@@ -1,111 +0,0 @@
-export interface TokenBudget {
-    totalTokens: number;
-    projectContext: number;
-    streamContext: number;
-    dependencyContext: number;
-    instructions: number;
-}
-export interface ContextOptimization {
-    includedFiles: string[];
-    excludedFiles: string[];
-    tokenBudget: TokenBudget;
-    cachingHints: CachingHint[];
-    estimatedSavings: number;
-    warnings?: string[];
-    metrics?: OptimizationMetrics;
-}
-export interface CachingHint {
-    content: string;
-    type: 'system_prompt' | 'project_context' | 'stream_context';
-    reusable: boolean;
-    estimatedTokens: number;
-}
-export interface OptimizationMetrics {
-    totalFiles: number;
-    includedFiles: number;
-    excludedFiles: number;
-    originalTokens: number;
-    optimizedTokens: number;
-    compressionRatio: number;
-}
-/**
- * Default token budgets by model.
- * Based on Anthropic's context window sizes.
- */
-export declare const MODEL_TOKEN_LIMITS: Record<string, number>;
-/**
- * Analyze import graph and return files actually needed for a stream.
- * Prunes files that are not transitively imported.
- *
- * Uses breadth-first search to traverse the import graph starting from owned files.
- * Detects circular dependencies and includes them in warnings.
- *
- * Algorithm:
- * - BFS from owned files, following imports
- * - Track the import chain (path from root) for each discovered file
- * - Detect cycles when we find an import to an already-visited file
- */
-export declare function pruneUnusedFiles(ownedFiles: string[], readFiles: string[], fileContents: Record<string, string>): {
-    needed: string[];
-    pruned: string[];
-    warnings?: string[];
-};
-/**
- * Allocate token budget across context layers with intelligent prioritization.
- *
- * Priority: instructions > stream context > dependency context > project context
- *
- * Strategy:
- * - Instructions: Fixed 15% or 1000 tokens (whichever is smaller) for task description
- * - Stream context: Up to 50% of remaining, based on actual file sizes
- * - Dependency context: Up to 30% of remaining, ~300 tokens per artifact
- * - Project context: Remaining budget for file tree and metadata
- *
- * When file contents are provided, uses actual token estimates for more accurate allocation.
- */
-export declare function allocateTokenBudget(totalTokens: number, streamFiles: string[], dependencyArtifacts: number, fileContents?: Record<string, string>): TokenBudget;
-/**
- * Generate caching hints for Anthropic's prompt caching.
- *
- * Prompt caching can reduce costs by up to 90% for repeated context.
- * See: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
- *
- * Caching strategy:
- * - System prompts: Highly reusable across all streams
- * - Project context: Reusable within an orchestration run
- * - Stream context: Reusable across retries of the same stream
- *
- * Only generates hints for content exceeding minimum thresholds to avoid
- * cache overhead on small contexts.
- */
-export declare function generateCachingHints(projectContext: string, streamContext: string, instructions: string): CachingHint[];
-/**
- * Estimate token count for a string using content-aware heuristics.
- *
- * Different content types have different token densities:
- * - Code: ~3.5 chars/token (dense, lots of symbols)
- * - Comments: ~4.5 chars/token (prose, more natural language)
- * - Whitespace: ~6.0 chars/token (sparse)
- * - JSON: ~3.8 chars/token (structured data)
- * - Markdown: ~4.2 chars/token (formatted prose)
- *
- * This provides better accuracy than simple char/4 estimation.
- */
-export declare function estimateTokens(text: string): number;
-/**
- * Full context optimization for a stream.
- *
- * This is the main entry point for context optimization. It:
- * 1. Prunes unused files based on import graph analysis
- * 2. Allocates token budget across context layers
- * 3. Generates prompt caching hints for cost optimization
- * 4. Calculates optimization metrics and savings estimates
- *
- * @param ownedFiles - Files this stream owns (will always be included)
- * @param readFiles - Files this stream needs to read (will always be included)
- * @param fileContents - Map of file paths to their contents
- * @param dependencyArtifacts - Number of dependency artifacts to include
- * @param model - Claude model name for token limit lookup
- * @returns Complete optimization analysis with included/excluded files, budgets, and hints
- */
-export declare function optimizeContext(ownedFiles: string[], readFiles: string[], fileContents: Record<string, string>, dependencyArtifacts: number, model?: string): ContextOptimization;

package/dist/intelligence/context-optimizer.js

@@ -1,282 +0,0 @@
-import { extractImports, resolveImportPath } from './heuristics.js';
-/**
- * Default token budgets by model.
- * Based on Anthropic's context window sizes.
- */
-export const MODEL_TOKEN_LIMITS = {
-    'claude-sonnet-4-20250514': 8192,
-    'claude-3-5-sonnet-20241022': 8192,
-    'claude-3-opus-20240229': 4096,
-    default: 8192,
-};
-/**
- * Token estimation constants based on empirical analysis.
- * Different content types have different token densities.
- */
-const TOKEN_DENSITY = {
-    CODE: 3.5, // chars per token for code
-    COMMENTS: 4.5, // chars per token for comments/prose
-    WHITESPACE: 6.0, // chars per token for whitespace
-    JSON: 3.8, // chars per token for JSON
-    MARKDOWN: 4.2, // chars per token for markdown
-};
-/**
- * Analyze import graph and return files actually needed for a stream.
- * Prunes files that are not transitively imported.
- *
- * Uses breadth-first search to traverse the import graph starting from owned files.
- * Detects circular dependencies and includes them in warnings.
- *
- * Algorithm:
- * - BFS from owned files, following imports
- * - Track the import chain (path from root) for each discovered file
- * - Detect cycles when we find an import to an already-visited file
- */
-export function pruneUnusedFiles(ownedFiles, readFiles, fileContents) {
-    const needed = new Set([...ownedFiles]);
-    const visited = new Set();
-    const queue = [...ownedFiles];
-    const warnings = [];
-    const importChain = new Map(); // Track import path for cycle reporting
-    // Initialize chains for owned files (they're the roots)
-    for (const file of ownedFiles) {
-        importChain.set(file, []);
-    }
-    // BFS through import graph
-    while (queue.length > 0) {
-        const file = queue.shift();
-        if (visited.has(file))
-            continue; // Already processed
-        visited.add(file);
-        const content = fileContents[file];
-        if (!content)
-            continue;
-        const imports = extractImports(content);
-        for (const imp of imports) {
-            const resolved = resolveImportPath(file, imp);
-            if (resolved && fileContents[resolved]) {
-                if (visited.has(resolved)) {
-                    // CYCLE DETECTED: importing a file we've already fully processed
-                    const currentChain = importChain.get(file) || [];
-                    warnings.push(`Circular dependency detected: ${[...currentChain, file, resolved].join(' → ')}`);
-                }
-                else if (!needed.has(resolved)) {
-                    // New file discovered - add to queue
-                    needed.add(resolved);
-                    queue.push(resolved);
-                    // Track import chain for cycle reporting
-                    const currentChain = importChain.get(file) || [];
-                    importChain.set(resolved, [...currentChain, file]);
-                }
-            }
-        }
-    }
-    // Add explicitly requested read files
-    for (const f of readFiles) {
-        needed.add(f);
-    }
-    const pruned = Object.keys(fileContents).filter(f => !needed.has(f));
-    return {
-        needed: [...needed],
-        pruned,
-        warnings: warnings.length > 0 ? warnings : undefined
-    };
-}
-/**
- * Allocate token budget across context layers with intelligent prioritization.
- *
- * Priority: instructions > stream context > dependency context > project context
- *
- * Strategy:
- * - Instructions: Fixed 15% or 1000 tokens (whichever is smaller) for task description
- * - Stream context: Up to 50% of remaining, based on actual file sizes
- * - Dependency context: Up to 30% of remaining, ~300 tokens per artifact
- * - Project context: Remaining budget for file tree and metadata
- *
- * When file contents are provided, uses actual token estimates for more accurate allocation.
- */
-export function allocateTokenBudget(totalTokens, streamFiles, dependencyArtifacts, fileContents) {
-    // Reserve fixed amounts for essential parts
-    const instructions = Math.min(1000, totalTokens * 0.15); // 15% or 1000 max
-    const remaining = totalTokens - instructions;
-    // If we have file contents, use actual sizes; otherwise use estimates
-    let streamContext;
-    if (fileContents) {
-        const actualTokens = streamFiles.reduce((sum, file) => {
-            const content = fileContents[file] || '';
-            return sum + estimateTokens(content);
-        }, 0);
-        streamContext = Math.min(remaining * 0.5, actualTokens);
-    }
-    else {
-        streamContext = Math.min(remaining * 0.5, streamFiles.length * 500); // ~500 tokens per file estimate
-    }
-    const afterStream = remaining - streamContext;
-    // Dependency context: ~300 tokens per artifact
-    const dependencyContext = Math.min(afterStream * 0.3, dependencyArtifacts * 300);
-    const afterDeps = afterStream - dependencyContext;
-    // Project context gets the rest
-    const projectContext = afterDeps;
-    return {
-        totalTokens,
-        projectContext: Math.floor(projectContext),
-        streamContext: Math.floor(streamContext),
-        dependencyContext: Math.floor(dependencyContext),
-        instructions: Math.floor(instructions),
-    };
-}
-/**
- * Generate caching hints for Anthropic's prompt caching.
- *
- * Prompt caching can reduce costs by up to 90% for repeated context.
- * See: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
- *
- * Caching strategy:
- * - System prompts: Highly reusable across all streams
- * - Project context: Reusable within an orchestration run
- * - Stream context: Reusable across retries of the same stream
- *
- * Only generates hints for content exceeding minimum thresholds to avoid
- * cache overhead on small contexts.
- */
-export function generateCachingHints(projectContext, streamContext, instructions) {
-    const hints = [];
-    // System prompt / instructions are highly reusable
-    if (instructions.length > 100) {
-        hints.push({
-            content: instructions,
-            type: 'system_prompt',
-            reusable: true,
-            estimatedTokens: estimateTokens(instructions),
-        });
-    }
-    // Project context (file tree, deps) is reusable within an orchestration
-    if (projectContext.length > 500) {
-        hints.push({
-            content: projectContext,
-            type: 'project_context',
-            reusable: true,
-            estimatedTokens: estimateTokens(projectContext),
-        });
-    }
-    // Stream context is reusable across retries of the same stream
-    if (streamContext.length > 500) {
-        hints.push({
-            content: streamContext,
-            type: 'stream_context',
-            reusable: true,
-            estimatedTokens: estimateTokens(streamContext),
-        });
-    }
-    return hints;
-}
-/**
- * Estimate token count for a string using content-aware heuristics.
- *
- * Different content types have different token densities:
- * - Code: ~3.5 chars/token (dense, lots of symbols)
- * - Comments: ~4.5 chars/token (prose, more natural language)
- * - Whitespace: ~6.0 chars/token (sparse)
- * - JSON: ~3.8 chars/token (structured data)
- * - Markdown: ~4.2 chars/token (formatted prose)
- *
- * This provides better accuracy than simple char/4 estimation.
- */
-export function estimateTokens(text) {
-    if (!text || text.length === 0)
-        return 0;
-    // Detect file type from content patterns
-    const isJson = text.trim().startsWith('{') || text.trim().startsWith('[');
-    const isMarkdown = /^#+\s|^-\s|^\*\s|^\d+\.\s/m.test(text);
-    // For JSON and Markdown, use specialized densities
-    if (isJson) {
-        return Math.ceil(text.length / TOKEN_DENSITY.JSON);
-    }
-    if (isMarkdown) {
-        return Math.ceil(text.length / TOKEN_DENSITY.MARKDOWN);
-    }
-    // For code, analyze line-by-line
-    const lines = text.split('\n');
-    let totalChars = 0;
-    let codeChars = 0;
-    let commentChars = 0;
-    let whitespaceChars = 0;
-    for (const line of lines) {
-        const trimmed = line.trim();
-        totalChars += line.length;
-        // Whitespace-only lines
-        if (trimmed.length === 0) {
-            whitespaceChars += line.length;
-            continue;
-        }
-        // Detect code vs comments (rough heuristic)
-        if (trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*') || trimmed.startsWith('#')) {
-            commentChars += line.length;
-        }
-        else {
-            codeChars += line.length;
-            // Account for indentation as whitespace
-            const indent = line.length - trimmed.length;
-            whitespaceChars += indent;
-            codeChars -= indent;
-        }
-    }
-    // Calculate tokens by content type
-    const codeTokens = Math.ceil(codeChars / TOKEN_DENSITY.CODE);
-    const commentTokens = Math.ceil(commentChars / TOKEN_DENSITY.COMMENTS);
-    const whitespaceTokens = Math.ceil(whitespaceChars / TOKEN_DENSITY.WHITESPACE);
-    const otherTokens = Math.ceil((totalChars - codeChars - commentChars - whitespaceChars) / TOKEN_DENSITY.COMMENTS);
-    return codeTokens + commentTokens + whitespaceTokens + otherTokens;
-}
-/**
- * Full context optimization for a stream.
- *
- * This is the main entry point for context optimization. It:
- * 1. Prunes unused files based on import graph analysis
- * 2. Allocates token budget across context layers
- * 3. Generates prompt caching hints for cost optimization
- * 4. Calculates optimization metrics and savings estimates
- *
- * @param ownedFiles - Files this stream owns (will always be included)
- * @param readFiles - Files this stream needs to read (will always be included)
- * @param fileContents - Map of file paths to their contents
- * @param dependencyArtifacts - Number of dependency artifacts to include
- * @param model - Claude model name for token limit lookup
- * @returns Complete optimization analysis with included/excluded files, budgets, and hints
- */
-export function optimizeContext(ownedFiles, readFiles, fileContents, dependencyArtifacts, model = 'default') {
-    const totalTokens = MODEL_TOKEN_LIMITS[model] ?? MODEL_TOKEN_LIMITS.default;
-    // Prune unused files
-    const { needed, pruned, warnings } = pruneUnusedFiles(ownedFiles, readFiles, fileContents);
-    // Build context strings
-    const streamContext = needed.map(f => fileContents[f] || '').join('\n');
-    const projectContext = `Project files: ${Object.keys(fileContents).length}\nIncluded: ${needed.length}`;
-    const instructions = `You are implementing stream changes. Output an orchex-artifact block.`;
-    // Allocate budget using actual file contents
-    const tokenBudget = allocateTokenBudget(totalTokens, needed, dependencyArtifacts, fileContents);
-    // Generate caching hints
-    const cachingHints = generateCachingHints(projectContext, streamContext, instructions);
-    // Calculate optimization metrics
-    const originalTokens = estimateTokens(Object.values(fileContents).join('\n'));
-    const optimizedTokens = estimateTokens(streamContext);
-    const estimatedSavings = originalTokens > 0
-        ? Math.round((1 - optimizedTokens / originalTokens) * 100)
-        : 0;
-    const metrics = {
-        totalFiles: Object.keys(fileContents).length,
-        includedFiles: needed.length,
-        excludedFiles: pruned.length,
-        originalTokens,
-        optimizedTokens,
-        compressionRatio: originalTokens > 0 ? optimizedTokens / originalTokens : 0,
-    };
-    return {
-        includedFiles: needed,
-        excludedFiles: pruned,
-        tokenBudget,
-        cachingHints,
-        estimatedSavings,
-        warnings,
-        metrics,
-    };
-}