0xray 4.0.13 → 4.0.14

package/dist/utils/token-manager.js

@@ -0,0 +1,163 @@
+import * as fs from "fs";
+import * as path from "path";
+import { resolveConfigPath } from "../core/config-paths.js";
+export class TokenManager {
+    config;
+    constructor(configPath = resolveConfigPath("config.json") || path.join(process.cwd(), ".xray", "config.json")) {
+        this.config = this.loadConfig(configPath);
+    }
+    loadConfig(configPath) {
+        try {
+            const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+            return (config.token_management || {
+                maxPromptTokens: 20000,
+                warningThreshold: 15000,
+                modelLimits: {},
+                contextPruning: {
+                    enabled: true,
+                    aggressivePruning: true,
+                    preserveCriticalContext: true,
+                },
+            });
+        }
+        catch (error) {
+            // Fallback defaults if config loading fails
+            return {
+                maxPromptTokens: 20000,
+                warningThreshold: 15000,
+                modelLimits: {},
+                contextPruning: {
+                    enabled: true,
+                    aggressivePruning: true,
+                    preserveCriticalContext: true,
+                },
+            };
+        }
+    }
+    /**
+     * Estimate token count for text (rough approximation)
+     * Uses 4 characters per token as a conservative estimate
+     */
+    estimateTokens(text) {
+        return Math.ceil(text.length / 4);
+    }
+    /**
+     * Check if prompt exceeds limits
+     */
+    checkLimits(prompt, modelName) {
+        const currentTokens = this.estimateTokens(prompt);
+        const maxTokens = modelName
+            ? this.config.modelLimits[modelName] || this.config.maxPromptTokens
+            : this.config.maxPromptTokens;
+        const withinLimit = currentTokens <= maxTokens;
+        const needsPruning = currentTokens > this.config.maxPromptTokens;
+        const warning = currentTokens > this.config.warningThreshold;
+        return {
+            withinLimit,
+            currentTokens,
+            maxTokens,
+            needsPruning,
+            warning,
+        };
+    }
+    /**
+     * Prune context to fit within token limits
+     */
+    pruneContext(context, targetTokens = this.config.maxPromptTokens) {
+        if (!this.config.contextPruning.enabled) {
+            return context;
+        }
+        const currentTokens = this.estimateTokens(context);
+        if (currentTokens <= targetTokens) {
+            return context; // No pruning needed
+        }
+        // Preserve critical sections (AGENTS.md header, codex terms, etc.)
+        const criticalSections = this.extractCriticalSections(context);
+        const criticalTokens = this.estimateTokens(criticalSections.join("\n"));
+        // Calculate available tokens for non-critical content
+        const availableTokens = Math.max(targetTokens - criticalTokens, targetTokens * 0.3); // Reserve at least 30%
+        const nonCriticalContent = this.extractNonCriticalContent(context);
+        const prunedNonCritical = this.pruneNonCriticalContent(nonCriticalContent, availableTokens);
+        return `${criticalSections.join("\n")}\n\n${prunedNonCritical}`;
+    }
+    extractCriticalSections(context) {
+        const lines = context.split("\n");
+        const criticalSections = [];
+        // Always preserve codex terms and framework overview
+        const codexSection = this.extractSection(lines, "Universal Development Codex");
+        const frameworkSection = this.extractSection(lines, "0xRay Framework");
+        if (codexSection)
+            criticalSections.push(codexSection);
+        if (frameworkSection)
+            criticalSections.push(frameworkSection);
+        return criticalSections;
+    }
+    extractSection(lines, sectionTitle) {
+        const startIndex = lines.findIndex((line) => line.includes(sectionTitle));
+        if (startIndex === -1)
+            return null;
+        let endIndex = lines.length;
+        for (let i = startIndex + 1; i < lines.length; i++) {
+            const currentLine = lines[i];
+            if (currentLine &&
+                currentLine.startsWith("#") &&
+                currentLine !== lines[startIndex]) {
+                endIndex = i;
+                break;
+            }
+        }
+        return lines.slice(startIndex, endIndex).join("\n");
+    }
+    extractNonCriticalContent(context) {
+        const criticalSections = this.extractCriticalSections(context);
+        let result = context;
+        for (const section of criticalSections) {
+            result = result.replace(section, "");
+        }
+        return result.trim();
+    }
+    pruneNonCriticalContent(content, maxTokens) {
+        const lines = content.split("\n");
+        const result = [];
+        let currentTokens = 0;
+        for (const line of lines) {
+            const lineTokens = this.estimateTokens(line);
+            if (currentTokens + lineTokens <= maxTokens) {
+                result.push(line);
+                currentTokens += lineTokens;
+            }
+            else {
+                // Truncate line if too long
+                if (lineTokens > maxTokens * 0.1) {
+                    // If single line is >10% of limit
+                    const maxChars = maxTokens * 4 * 0.1; // Convert tokens to chars
+                    result.push(line.substring(0, maxChars) + "...[truncated]");
+                }
+                break;
+            }
+        }
+        return result.join("\n");
+    }
+    /**
+     * Generate warning message for token limits
+     */
+    generateWarning(limitCheck) {
+        if (limitCheck.withinLimit && !limitCheck.warning)
+            return "";
+        const messages = [];
+        if (limitCheck.warning) {
+            messages.push(`⚠️  Token usage warning: ${limitCheck.currentTokens.toLocaleString()} tokens (${((limitCheck.currentTokens / limitCheck.maxTokens) * 100).toFixed(1)}% of limit)`);
+        }
+        if (!limitCheck.withinLimit) {
+            messages.push(`🚨 Token limit exceeded: ${limitCheck.currentTokens.toLocaleString()} > ${limitCheck.maxTokens.toLocaleString()} tokens`);
+            messages.push("Context will be automatically pruned to fit within limits.");
+        }
+        return messages.join("\n");
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}

package/dist/validation/agent-config-validator.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Agent Configuration Validator
+ *
+ * Validates agent configuration files for correctness and completeness
+ * ensuring all required fields are present and properly formatted.
+ *
+ * @since 2026-01-23
+ */
+export interface AgentConfig {
+    name: string;
+    description: string;
+    version: string;
+    model: string;
+    mode: "primary" | "subagent";
+    logging?: {
+        level: string;
+        format: string;
+        destinations: string[];
+        retention_days?: number;
+        sensitive_data_filtering?: boolean;
+        audit_trail?: boolean;
+    };
+    processor_pipeline?: Array<{
+        name: string;
+        type: string;
+        priority: "low" | "medium" | "high" | "critical";
+        timeout_ms?: number;
+        retry_attempts?: number;
+    }>;
+    capabilities?: string[];
+    error_handling?: {
+        retry_attempts?: number;
+        circuit_breaker?: {
+            enabled?: boolean;
+            failure_threshold?: number;
+            recovery_timeout_ms?: number;
+        };
+        fallback_strategy?: string;
+        alert_on_failure?: boolean;
+    };
+    performance?: {
+        timeout_ms?: number;
+        concurrency_limit?: number;
+        memory_limit_mb?: number;
+        cpu_limit_percent?: number;
+    };
+    security?: {
+        sandboxed_execution?: boolean;
+        permission_level?: string;
+        data_classification?: string;
+        encryption_required?: boolean;
+    };
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    config: AgentConfig | null;
+}
+export declare class AgentConfigValidator {
+    private readonly requiredFields;
+    private readonly validModes;
+    private readonly validLogLevels;
+    private readonly validLogFormats;
+    private readonly validPriorities;
+    private readonly validProcessorTypes;
+    /**
+     * Validate agent configuration from file
+     */
+    validateConfigFile(filePath: string): Promise<ValidationResult>;
+    /**
+     * Validate agent configuration object
+     */
+    validateConfig(config: AgentConfig): ValidationResult;
+    /**
+     * Validate logging configuration
+     */
+    private validateLoggingConfig;
+    /**
+     * Validate processor pipeline configuration
+     */
+    private validateProcessorPipeline;
+    /**
+     * Validate performance configuration
+     */
+    private validatePerformanceConfig;
+    /**
+     * Validate security configuration
+     */
+    private validateSecurityConfig;
+    /**
+     * Validate error handling configuration
+     */
+    private validateErrorHandlingConfig;
+    /**
+     * Validate all agent configurations in a directory
+     */
+    validateAllAgentConfigs(agentConfigDir?: string): Promise<{
+        results: Array<{
+            file: string;
+            result: ValidationResult;
+        }>;
+        summary: {
+            total: number;
+            valid: number;
+            invalid: number;
+        };
+    }>;
+}
+export declare const agentConfigValidator: AgentConfigValidator;

package/dist/validation/agent-config-validator.js

@@ -0,0 +1,280 @@
+/**
+ * Agent Configuration Validator
+ *
+ * Validates agent configuration files for correctness and completeness
+ * ensuring all required fields are present and properly formatted.
+ *
+ * @since 2026-01-23
+ */
+import { frameworkLogger } from "../core/framework-logger.js";
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+export class AgentConfigValidator {
+    requiredFields = [
+        "name",
+        "description",
+        "version",
+        "model",
+        "mode",
+    ];
+    validModes = ["primary", "subagent"];
+    validLogLevels = ["debug", "info", "warn", "error"];
+    validLogFormats = ["json", "text"];
+    validPriorities = ["low", "medium", "high", "critical"];
+    validProcessorTypes = [
+        "validation",
+        "orchestration",
+        "monitoring",
+    ];
+    /**
+     * Validate agent configuration from file
+     */
+    async validateConfigFile(filePath) {
+        const jobId = `validate-config-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+        try {
+            // Check if file exists
+            if (!fs.existsSync(filePath)) {
+                return {
+                    valid: false,
+                    errors: [`Configuration file does not exist: ${filePath}`],
+                    warnings: [],
+                    config: null,
+                };
+            }
+            // Read and parse file
+            const content = fs.readFileSync(filePath, "utf8");
+            let config;
+            if (filePath.endsWith(".yml") || filePath.endsWith(".yaml")) {
+                config = yaml.parse(content);
+            }
+            else if (filePath.endsWith(".json")) {
+                config = JSON.parse(content);
+            }
+            else {
+                return {
+                    valid: false,
+                    errors: [`Unsupported file format: ${path.extname(filePath)}`],
+                    warnings: [],
+                    config: null,
+                };
+            }
+            const result = this.validateConfig(config);
+            frameworkLogger.log("agent-config-validator", `Configuration validation ${result.valid ? "passed" : "failed"} for ${filePath}`, result.valid ? "success" : "error", {
+                jobId,
+                filePath,
+                errorCount: result.errors.length,
+                warningCount: result.warnings.length,
+            });
+            return {
+                ...result,
+                config: result.valid ? config : null,
+            };
+        }
+        catch (error) {
+            frameworkLogger.log("agent-config-validator", `Configuration validation error for ${filePath}`, "error", {
+                jobId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return {
+                valid: false,
+                errors: [
+                    `Failed to parse configuration: ${error instanceof Error ? error.message : String(error)}`,
+                ],
+                warnings: [],
+                config: null,
+            };
+        }
+    }
+    /**
+     * Validate agent configuration object
+     */
+    validateConfig(config) {
+        const errors = [];
+        const warnings = [];
+        // Check required fields
+        for (const field of this.requiredFields) {
+            if (!config[field]) {
+                errors.push(`Missing required field: ${field}`);
+            }
+        }
+        // Validate mode
+        if (config.mode && !this.validModes.includes(config.mode)) {
+            errors.push(`Invalid mode '${config.mode}'. Must be one of: ${this.validModes.join(", ")}`);
+        }
+        // Validate logging configuration
+        if (config.logging) {
+            this.validateLoggingConfig(config.logging, errors, warnings);
+        }
+        // Validate processor pipeline
+        if (config.processor_pipeline) {
+            this.validateProcessorPipeline(config.processor_pipeline, errors, warnings);
+        }
+        // Validate performance configuration
+        if (config.performance) {
+            this.validatePerformanceConfig(config.performance, errors, warnings);
+        }
+        // Validate security configuration
+        if (config.security) {
+            this.validateSecurityConfig(config.security, errors, warnings);
+        }
+        // Validate error handling configuration
+        if (config.error_handling) {
+            this.validateErrorHandlingConfig(config.error_handling, errors, warnings);
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+            config: null,
+        };
+    }
+    /**
+     * Validate logging configuration
+     */
+    validateLoggingConfig(logging, errors, warnings) {
+        if (logging.level && !this.validLogLevels.includes(logging.level)) {
+            errors.push(`Invalid log level '${logging.level}'. Must be one of: ${this.validLogLevels.join(", ")}`);
+        }
+        if (logging.format && !this.validLogFormats.includes(logging.format)) {
+            errors.push(`Invalid log format '${logging.format}'. Must be one of: ${this.validLogFormats.join(", ")}`);
+        }
+        if (logging.destinations && !Array.isArray(logging.destinations)) {
+            errors.push("logging.destinations must be an array");
+        }
+        if (logging.retention_days &&
+            (typeof logging.retention_days !== "number" || logging.retention_days < 1)) {
+            errors.push("logging.retention_days must be a positive number");
+        }
+    }
+    /**
+     * Validate processor pipeline configuration
+     */
+    validateProcessorPipeline(pipeline, errors, warnings) {
+        if (!Array.isArray(pipeline)) {
+            errors.push("processor_pipeline must be an array");
+            return;
+        }
+        pipeline.forEach((processor, index) => {
+            if (!processor.name) {
+                errors.push(`processor_pipeline[${index}]: missing 'name' field`);
+            }
+            if (!processor.type) {
+                errors.push(`processor_pipeline[${index}]: missing 'type' field`);
+            }
+            else if (!this.validProcessorTypes.includes(processor.type)) {
+                errors.push(`processor_pipeline[${index}]: invalid type '${processor.type}'. Must be one of: ${this.validProcessorTypes.join(", ")}`);
+            }
+            if (!processor.priority) {
+                errors.push(`processor_pipeline[${index}]: missing 'priority' field`);
+            }
+            else if (!this.validPriorities.includes(processor.priority)) {
+                errors.push(`processor_pipeline[${index}]: invalid priority '${processor.priority}'. Must be one of: ${this.validPriorities.join(", ")}`);
+            }
+            if (processor.timeout_ms &&
+                (typeof processor.timeout_ms !== "number" || processor.timeout_ms < 0)) {
+                errors.push(`processor_pipeline[${index}]: timeout_ms must be a non-negative number`);
+            }
+            if (processor.retry_attempts &&
+                (typeof processor.retry_attempts !== "number" ||
+                    processor.retry_attempts < 0)) {
+                errors.push(`processor_pipeline[${index}]: retry_attempts must be a non-negative number`);
+            }
+        });
+    }
+    /**
+     * Validate performance configuration
+     */
+    validatePerformanceConfig(performance, errors, warnings) {
+        if (performance.timeout_ms &&
+            (typeof performance.timeout_ms !== "number" || performance.timeout_ms < 0)) {
+            errors.push("performance.timeout_ms must be a non-negative number");
+        }
+        if (performance.concurrency_limit &&
+            (typeof performance.concurrency_limit !== "number" ||
+                performance.concurrency_limit < 1)) {
+            errors.push("performance.concurrency_limit must be a positive number");
+        }
+        if (performance.memory_limit_mb &&
+            (typeof performance.memory_limit_mb !== "number" ||
+                performance.memory_limit_mb < 1)) {
+            errors.push("performance.memory_limit_mb must be a positive number");
+        }
+        if (performance.cpu_limit_percent &&
+            (typeof performance.cpu_limit_percent !== "number" ||
+                performance.cpu_limit_percent < 1 ||
+                performance.cpu_limit_percent > 100)) {
+            errors.push("performance.cpu_limit_percent must be between 1 and 100");
+        }
+    }
+    /**
+     * Validate security configuration
+     */
+    validateSecurityConfig(security, errors, warnings) {
+        if (security.permission_level &&
+            typeof security.permission_level !== "string") {
+            errors.push("security.permission_level must be a string");
+        }
+        if (security.data_classification &&
+            typeof security.data_classification !== "string") {
+            errors.push("security.data_classification must be a string");
+        }
+    }
+    /**
+     * Validate error handling configuration
+     */
+    validateErrorHandlingConfig(errorHandling, errors, warnings) {
+        if (errorHandling.retry_attempts &&
+            (typeof errorHandling.retry_attempts !== "number" ||
+                errorHandling.retry_attempts < 0)) {
+            errors.push("error_handling.retry_attempts must be a non-negative number");
+        }
+        if (errorHandling.circuit_breaker) {
+            const cb = errorHandling.circuit_breaker;
+            if (cb.failure_threshold &&
+                (typeof cb.failure_threshold !== "number" || cb.failure_threshold < 1)) {
+                errors.push("error_handling.circuit_breaker.failure_threshold must be a positive number");
+            }
+            if (cb.recovery_timeout_ms &&
+                (typeof cb.recovery_timeout_ms !== "number" ||
+                    cb.recovery_timeout_ms < 0)) {
+                errors.push("error_handling.circuit_breaker.recovery_timeout_ms must be a non-negative number");
+            }
+        }
+    }
+    /**
+     * Validate all agent configurations in a directory
+     */
+    async validateAllAgentConfigs(agentConfigDir = ".opencode/agents") {
+        const results = [];
+        // Gracefully handle missing agent config directory (headless/no .opencode/ mode)
+        if (!fs.existsSync(agentConfigDir)) {
+            frameworkLogger.log("agent-config-validator", `Agent config directory not found, skipping validation: ${agentConfigDir}`, "warning", {});
+            return {
+                results: [],
+                summary: { total: 0, valid: 0, invalid: 0 },
+            };
+        }
+        try {
+            const files = fs.readdirSync(agentConfigDir);
+            const configFiles = files.filter((f) => f.endsWith(".yml") || f.endsWith(".yaml") || f.endsWith(".json"));
+            for (const file of configFiles) {
+                const filePath = path.join(agentConfigDir, file);
+                const result = await this.validateConfigFile(filePath);
+                results.push({ file, result });
+            }
+        }
+        catch (error) {
+            frameworkLogger.log("agent-config-validator", "Failed to read agent config directory", "error", { error: error instanceof Error ? error.message : String(error) });
+        }
+        const summary = {
+            total: results.length,
+            valid: results.filter((r) => r.result.valid).length,
+            invalid: results.length - results.filter((r) => r.result.valid).length,
+        };
+        frameworkLogger.log("agent-config-validator", `Validated ${summary.total} agent configurations: ${summary.valid} valid, ${summary.invalid} invalid`, summary.invalid > 0 ? "error" : "info");
+        return { results, summary };
+    }
+}
+// Export singleton instance
+export const agentConfigValidator = new AgentConfigValidator();

package/dist/validation/estimation-validator.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Estimation Validator
+ *
+ * Tracks estimates vs. actuals and provides calibrated estimates
+ * Prevents the "always estimate high" syndrome by learning from history
+ */
+/**
+ * Estimation Validator
+ * Tracks estimates and learns from actuals to improve future predictions
+ */
+export declare class EstimationValidator {
+    private estimations;
+    private calibrations;
+    private readonly STORAGE_KEY;
+    constructor();
+    /**
+     * Start tracking an estimate
+     */
+    startEstimate(taskId: string, description: string, category: string, estimatedMinutes: number, confidence?: 'high' | 'medium' | 'low'): void;
+    /**
+     * Complete tracking and record actual time
+     */
+    completeEstimate(taskId: string): void;
+    /**
+     * Get calibrated estimate based on historical data
+     */
+    getCalibratedEstimate(category: string, baseEstimate: number, confidence?: 'high' | 'medium' | 'low'): {
+        calibratedEstimate: number;
+        calibrationFactor: number;
+        confidence: number;
+    };
+    /**
+     * Check if an estimate needs adjustment
+     */
+    validateEstimate(category: string, estimate: number): {
+        isReasonable: boolean;
+        suggestedEstimate: number;
+        warning?: string;
+    };
+    /**
+     * Get estimation accuracy report
+     */
+    getAccuracyReport(): {
+        overallAccuracy: number;
+        categoryBreakdown: Array<{
+            category: string;
+            sampleSize: number;
+            avgRatio: number;
+            trend: 'over' | 'under' | 'accurate';
+        }>;
+        recommendations: string[];
+    };
+    private updateCalibration;
+    private loadFromStorage;
+    private saveToStorage;
+}
+export declare function getEstimationValidator(): EstimationValidator;
+/**
+ * Decorator for async functions to track estimates
+ */
+export declare function trackEstimate(taskId: string, description: string, category: string, estimatedMinutes: number): (_target: unknown, _propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;