0xray 3.4.2 → 3.4.4

package/dist/core/context-validator.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 0xRay Context Size Validator
+ *
+ * Prevents system prompt bloat by validating and rejecting context-injection attempts
+ * that would exceed token budgets.
+ *
+ * @since 2026-03-03
+ */
+/**
+ * Context size configuration
+ */
+export interface ContextSizeConfig {
+    maxSystemPromptLength: number;
+    maxCodexContextLength: number;
+    maxTotalPromptLength: number;
+    enableCompression: boolean;
+    preventDuplicateContent: boolean;
+}
+/**
+ * Context validation result
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    sizeInTokens: number;
+    exceedsBudget: boolean;
+    warnings: string[];
+    compressionApplied: boolean;
+    optimizedContent?: string;
+}
+/**
+ * Validate context size and detect bloat
+ */
+export declare function validateContext(context: string, config?: Partial<ContextSizeConfig>): ValidationResult;
+/**
+ * Validate context collection (multiple contexts combined)
+ */
+export declare function validateContextCollection(contexts: string[], config?: Partial<ContextSizeConfig>): ValidationResult;
+/**
+ * Prevent system prompt bloat middleware
+ */
+export declare function preventSystemPromptBloat(context: string, onWarning?: (warning: string) => void): string;
+/**
+ * Utility function to check if a prompt is likely to cause overflow
+ */
+export declare function isPromptLikelyToOverflow(prompt: string): boolean;
+/**
+ * Generate a safe system prompt template
+ */
+export declare function generateSafeSystemPrompt(baseTemplate: string, additionalContext: string, maxTokens?: number): {
+    prompt: string;
+    safe: boolean;
+};

package/dist/core/features-config.d.ts

@@ -0,0 +1,485 @@
+/**
+ * Features Configuration Loader
+ *
+ * Loads and validates the unified features configuration from features.json
+ * Supports token optimization, model routing, batch operations, and more.
+ *
+ * @since 2026-01-25
+ */
+import type { MemoryRoutingConfig } from "../memory-routing/types.js";
+export type { MemoryRoutingConfig };
+export interface TokenOptimizationConfig {
+    enabled: boolean;
+    max_context_tokens: number;
+    prune_after_task: boolean;
+    summarize_tool_outputs: boolean;
+    context_compression: {
+        enabled: boolean;
+        threshold_tokens: number;
+        compression_ratio: number;
+    };
+}
+export interface TaskRouting {
+    model: string;
+    max_tokens: number;
+    description: string;
+}
+export interface ModelRoutingConfig {
+    enabled: boolean;
+    default_model?: string;
+    fallback_model?: string;
+    task_routing?: {
+        file_read?: TaskRouting;
+        grep_search?: TaskRouting;
+        simple_edit?: TaskRouting;
+        bulk_refactor?: TaskRouting;
+        architecture_review?: TaskRouting;
+        security_audit?: TaskRouting;
+        git_operations?: TaskRouting;
+        documentation?: TaskRouting;
+        code_generation?: TaskRouting;
+        debugging?: TaskRouting;
+    };
+}
+export interface BatchOperationsConfig {
+    enabled: boolean;
+    prefer_sed_for_replacements: boolean;
+    parallel_file_updates: boolean;
+    max_concurrent_edits: number;
+    auto_batch_threshold: number;
+}
+export interface MultiAgentOrchestrationConfig {
+    enabled: boolean;
+    coordination_model: "async-multi-agent" | "sync-multi-agent";
+    max_concurrent_agents: number;
+    task_distribution_strategy: "capability-based" | "load-balanced" | "round-robin";
+    conflict_resolution: "expert-priority" | "majority-vote" | "consensus";
+    progress_tracking: boolean;
+    session_persistence: boolean;
+    /** Lead-dev operating model (codex 67–68) — ON when suit is worn */
+    lead_dev_mode?: boolean;
+    per_suite_test_triage?: boolean;
+    phased_plan_threshold?: number;
+    auto_consult_major_work?: boolean;
+    /** Codex 69 — block new MCP/skill/handler files via PreToolUse (default true) */
+    no_new_surface?: boolean;
+}
+export interface AutonomousReportingConfig {
+    enabled: boolean;
+    interval_minutes: number;
+    auto_schedule: boolean;
+    include_health_assessment: boolean;
+    include_agent_activities: boolean;
+    include_pipeline_operations: boolean;
+    include_critical_issues: boolean;
+    include_recommendations: boolean;
+    report_retention_days: number;
+    notification_channels: string[];
+}
+export interface AgentManagementConfig {
+    disabled_agents: string[];
+    agent_models: Record<string, string>;
+    performance_limits: {
+        max_task_duration_ms: number;
+        max_memory_usage_mb: number;
+        max_tokens_per_request: number;
+    };
+}
+export interface RefactoringConfig {
+    enabled: boolean;
+    automatic_detection: boolean;
+    require_user_approval: boolean;
+    max_complexity_threshold: number;
+    safe_mode: boolean;
+    batch_mode: boolean;
+}
+export interface ActivityLoggingConfig {
+    enabled: boolean;
+    level: "debug" | "info" | "warn" | "error";
+    include_performance_metrics: boolean;
+    include_agent_states: boolean;
+    include_token_usage: boolean;
+    retention_days: number;
+    log_to_file: boolean;
+    log_path: string;
+}
+export interface SecurityConfig {
+    enabled: boolean;
+    prompt_sanitization: boolean;
+    vulnerability_scanning: boolean;
+    code_review_enforcement: boolean;
+    security_score_threshold: number;
+}
+export interface PerformanceMonitoringConfig {
+    enabled: boolean;
+    real_time_metrics: boolean;
+    benchmark_tracking: boolean;
+    token_tracking: boolean;
+    cost_tracking: boolean;
+    alerting: {
+        enabled: boolean;
+        performance_degradation_threshold: number;
+        error_rate_threshold: number;
+        cost_threshold_daily: number;
+    };
+}
+export interface CachingConfig {
+    enabled: boolean;
+    file_content_cache: boolean;
+    search_result_cache: boolean;
+    cache_ttl_seconds: number;
+    max_cache_size_mb: number;
+}
+export interface PublishConfig {
+    enabled: boolean;
+    require_documentation: {
+        enabled: boolean;
+        required_files: string[];
+        readme_version_sync: boolean;
+    };
+    require_reflection: {
+        enabled: boolean;
+        max_age_days: number;
+        auto_create_on_publish: boolean;
+    };
+    require_pipeline_tests: {
+        enabled: boolean;
+        min_pipeline_tests: number;
+    };
+}
+export interface CommitCycleConfig {
+    enabled: boolean;
+    auto_commit: {
+        enabled: boolean;
+        force_commit_after_minutes: number;
+        min_changes_to_commit: number;
+    };
+    require_reflection: {
+        enabled: boolean;
+        max_commits_since_reflection: number;
+        auto_remind: boolean;
+    };
+    validation: {
+        block_on_lint_errors: boolean;
+        block_on_test_failures: boolean;
+        auto_fix_on_commit: boolean;
+    };
+}
+export interface ReflectionConfig {
+    enabled: boolean;
+    auto_generate: boolean;
+    include_patterns: string[];
+    min_quality_score: number;
+    store_inference_data: boolean;
+}
+export interface AutoReflectionConfig {
+    mode: "full" | "minimal" | "off";
+    description: string;
+    triggers: {
+        ci_failure: {
+            enabled: boolean;
+            auto_generate_stub: boolean;
+        };
+        commit_threshold: {
+            enabled: boolean;
+            threshold: number;
+            auto_generate_stub: boolean;
+        };
+        time_threshold: {
+            enabled: boolean;
+            days: number;
+            auto_generate_stub: boolean;
+        };
+        test_failure: {
+            enabled: boolean;
+            auto_generate_stub: boolean;
+        };
+        deployment: {
+            enabled: boolean;
+            auto_generate_stub: boolean;
+        };
+    };
+    thresholds: {
+        full: {
+            commit_threshold: number;
+            days_threshold: number;
+            auto_generate: boolean;
+            auto_commit: boolean;
+            prompt_user: boolean;
+        };
+        minimal: {
+            commit_threshold: number;
+            days_threshold: number;
+            auto_generate: boolean;
+            auto_commit: boolean;
+            prompt_user: boolean;
+        };
+        off: {
+            commit_threshold: number;
+            days_threshold: number;
+            auto_generate: boolean;
+            auto_commit: boolean;
+            prompt_user: boolean;
+        };
+    };
+}
+export interface InferenceConfig {
+    description: string;
+    enabled: boolean;
+    workflow_dir: string;
+    reports_dir: string;
+    pattern_matching: {
+        enabled: boolean;
+        confidence_threshold: number;
+    };
+}
+export interface KernelConfig {
+    description: string;
+    enabled: boolean;
+    pattern_learning: {
+        enabled: boolean;
+        learning_interval_ms: number;
+        auto_apply_threshold: number;
+        min_success_rate: number;
+    };
+    confidence: {
+        default_threshold: number;
+        routing_adjustment: number;
+    };
+}
+export interface ProcessorsConfig {
+    description: string;
+    enabled: boolean;
+    pre_processors: {
+        enabled: boolean;
+        priority_order: string[];
+    };
+    post_processors: {
+        enabled: boolean;
+        priority_order: string[];
+    };
+}
+export interface EnforcementConfig {
+    description: string;
+    enabled: boolean;
+    auto_fix: {
+        enabled: boolean;
+        require_approval: boolean;
+    };
+    codex_validation: {
+        enabled: boolean;
+        strict_mode: boolean;
+    };
+}
+export interface AgentSpawnConfig {
+    enabled: boolean;
+    max_concurrent: number;
+    max_per_type: number;
+    spawn_cooldown_ms: number;
+    rate_limit_per_minute: number;
+}
+export interface DelegationConfig {
+    enabled: boolean;
+    confidence_threshold: number;
+    enable_intelligent_routing: boolean;
+}
+export interface ComplexityThresholds {
+    simple: number;
+    moderate: number;
+    complex: number;
+    enterprise: number;
+}
+export interface AnalyticsConfig {
+    enabled: boolean;
+    default_limit: number;
+    min_samples_for_calibration: number;
+    track_complexity_accuracy: boolean;
+    track_agent_performance: boolean;
+}
+export interface PatternLearningConfig {
+    enabled: boolean;
+    learning_interval_ms: number;
+    auto_apply_threshold: number;
+    min_success_rate: number;
+}
+export interface StoryTypeConfig {
+    location: string;
+    min_words: number;
+    ideal_words: number;
+    framework: string;
+}
+export interface StorytellingTriggerConfig {
+    enabled: boolean;
+    threshold?: number;
+    story_type: string;
+    remind_user?: boolean;
+    file_count_threshold?: number;
+    duration_minutes_threshold?: number;
+    require_saga?: boolean;
+    block_without_story?: boolean;
+}
+export interface StorytellingQualityRequirements {
+    require_frontmatter: boolean;
+    require_key_takeaways: boolean;
+    require_what_next: boolean;
+    fact_check_before_publish: boolean;
+    peer_review_agent: string;
+}
+export interface StorytellingConfig {
+    enabled: boolean;
+    reflection_triggers: {
+        commit_count: StorytellingTriggerConfig;
+        publish: StorytellingTriggerConfig;
+        complex_changes: StorytellingTriggerConfig;
+        session_duration: StorytellingTriggerConfig;
+    };
+    story_types: {
+        reflection: StoryTypeConfig;
+        saga: StoryTypeConfig;
+        journey: StoryTypeConfig;
+        narrative: StoryTypeConfig;
+    };
+    quality_requirements: StorytellingQualityRequirements;
+}
+export interface FeaturesConfig {
+    version?: string;
+    description: string;
+    token_optimization: TokenOptimizationConfig;
+    model_routing: ModelRoutingConfig;
+    batch_operations: BatchOperationsConfig;
+    multi_agent_orchestration: MultiAgentOrchestrationConfig;
+    autonomous_reporting: AutonomousReportingConfig;
+    agent_management: AgentManagementConfig;
+    refactoring: RefactoringConfig;
+    activity_logging: ActivityLoggingConfig;
+    security: SecurityConfig;
+    performance_monitoring: PerformanceMonitoringConfig;
+    caching: CachingConfig;
+    agent_spawn?: AgentSpawnConfig;
+    delegation?: DelegationConfig;
+    complexity_thresholds?: ComplexityThresholds;
+    analytics?: AnalyticsConfig;
+    pattern_learning?: PatternLearningConfig;
+    publish?: PublishConfig;
+    commit_cycle?: CommitCycleConfig;
+    reflection?: ReflectionConfig;
+    storytelling?: StorytellingConfig;
+    auto_reflection?: AutoReflectionConfig;
+    inference?: InferenceConfig;
+    memory_routing?: MemoryRoutingConfig;
+    kernel?: KernelConfig;
+    processors?: ProcessorsConfig;
+    enforcement?: EnforcementConfig;
+}
+export type TaskType = "file_read" | "grep_search" | "simple_edit" | "bulk_refactor" | "architecture_review" | "security_audit" | "git_operations" | "documentation" | "code_generation" | "debugging" | "unknown";
+/**
+ * Detect task type from tool name and context
+ */
+export declare function detectTaskType(toolName: string, context?: {
+    fileCount?: number;
+    isComplex?: boolean;
+}): TaskType;
+export declare class FeaturesConfigLoader {
+    private featuresPath;
+    private cachedConfig;
+    private cacheExpiry;
+    private lastLoadTime;
+    constructor(featuresPath?: string);
+    /**
+     * Load features configuration
+     */
+    loadConfig(): FeaturesConfig;
+    /**
+     * Get model for a specific task type
+     */
+    getModelForTask(taskType: TaskType): string;
+    /**
+     * Get max tokens for a specific task type
+     */
+    getMaxTokensForTask(taskType: TaskType): number;
+    /**
+     * Check if a feature is enabled
+     */
+    isFeatureEnabled(feature: keyof FeaturesConfig): boolean;
+    /**
+     * Get token optimization settings
+     */
+    getTokenOptimization(): TokenOptimizationConfig;
+    /**
+     * Get batch operation settings
+     */
+    getBatchOperations(): BatchOperationsConfig;
+    /**
+     * Get agent spawn settings
+     */
+    getAgentSpawn(): AgentSpawnConfig | undefined;
+    /**
+     * Get activity logging settings
+     */
+    getActivityLogging(): ActivityLoggingConfig;
+    /**
+     * Get performance monitoring alerting settings
+     */
+    getAlertingConfig(): {
+        enabled: boolean;
+        performance_degradation_threshold: number;
+        error_rate_threshold: number;
+        cost_threshold_daily: number;
+    };
+    /**
+     * Check if alerting is enabled from config
+     */
+    isAlertingEnabled(): boolean;
+    /**
+     * Check if agent is disabled
+     */
+    isAgentDisabled(agentName: string): boolean;
+    /**
+     * Get agent model assignment
+     */
+    getAgentModel(agentName: string): string;
+    /**
+     * Merge loaded config with defaults
+     */
+    private mergeWithDefaults;
+    /**
+     * Get default configuration
+     */
+    getDefaultConfig(): FeaturesConfig;
+    /**
+     * Clear configuration cache
+     */
+    clearCache(): void;
+    /**
+     * Save current configuration to file
+     */
+    saveConfig(config: Partial<FeaturesConfig>): void;
+    /**
+     * Enable a feature
+     */
+    enableFeature(feature: keyof FeaturesConfig): void;
+    /**
+     * Disable a feature
+     */
+    disableFeature(feature: keyof FeaturesConfig): void;
+    /**
+     * Get XrayConfig-shaped slice for backward compatibility
+     * @deprecated Use individual getters or loadConfig() directly instead.
+     */
+    getXrayConfig(): import("./config-loader.js").XrayConfig;
+    getTokenManagement(): FeaturesConfig["token_optimization"] | undefined;
+    getProcessors(): ProcessorsConfig | undefined;
+    getCommitCycle(): CommitCycleConfig | undefined;
+    getStorytelling(): StorytellingConfig | undefined;
+    getInference(): InferenceConfig | undefined;
+    getMemoryRouting(): MemoryRoutingConfig | undefined;
+    getPublish(): PublishConfig | undefined;
+    getAutoReporting(): AutonomousReportingConfig | undefined;
+    getGovernance(): InferenceConfig | FeaturesConfig["enforcement"] | undefined;
+}
+export declare const featuresConfigLoader: FeaturesConfigLoader;
+export declare const getModelForTask: (taskType: TaskType) => string;
+export declare const isFeatureEnabled: (feature: keyof FeaturesConfig) => boolean;
+export declare const getTokenOptimization: () => TokenOptimizationConfig;
+export declare const getBatchOperations: () => BatchOperationsConfig;
+export declare const getAgentSpawn: () => AgentSpawnConfig | undefined;

package/dist/core/framework-logger.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Generate a unique job ID for tracking work sessions
+ */
+export declare function generateJobId(prefix?: string): string;
+export declare function generateTraceId(): string;
+export declare function generateSpanId(): string;
+export declare function setTraceContext(traceId: string, parentSpanId?: string): string;
+export declare function getTraceContext(): {
+    traceId: string | null;
+    spanId: string | null;
+    parentSpanId: string | null;
+};
+export declare function clearTraceContext(): void;
+export declare function withTraceContext<T>(traceId: string, operation: (spanId: string) => Promise<T> | T, parentSpanId?: string): Promise<T>;
+export declare function getCurrentJobId(): string | null;
+export declare function setCurrentJobContext(jobId?: string): JobContext;
+export declare function withJobContext<T>(operation: () => Promise<T> | T, jobId?: string): Promise<T>;
+export type LogStatus = "success" | "error" | "info" | "debug" | "warning";
+/**
+ * Job context for tracking work sessions
+ * Enhanced with outcome and complexity accuracy tracking for pattern analytics
+ */
+export type Outcome = "success" | "fail" | "escalated" | "auto-fixed";
+export type ComplexityAccuracy = "underestimated" | "accurate" | "overestimated";
+export declare class JobContext {
+    readonly jobId: string;
+    readonly startTime: number;
+    complexityScore?: number;
+    agentUsed?: string;
+    operationType?: string;
+    outcome?: Outcome;
+    predictedDuration?: number;
+    constructor(jobId?: string);
+    /**
+     * Set the outcome after task completion
+     */
+    setOutcome(success: boolean, escalated?: boolean, autoFixed?: boolean): void;
+    /**
+     * Set predicted duration for complexity accuracy comparison
+     */
+    setPredictedDuration(completionTimeMs: number): void;
+    /**
+     * Log job completion with diagnostic info
+     * Enhanced with outcome and complexity accuracy tracking
+     */
+    complete(success?: boolean, details?: any): Promise<void>;
+}
+export interface FrameworkLogEntry {
+    timestamp: number;
+    component: string;
+    action: string;
+    status: LogStatus;
+    agent: string;
+    sessionId?: string;
+    jobId?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    details?: any;
+}
+export declare class FrameworkUsageLogger {
+    private logs;
+    private maxLogs;
+    private buffer;
+    private flushTimer?;
+    private flushing;
+    private readonly FLUSH_INTERVAL_MS;
+    private readonly MAX_BUFFER_SIZE;
+    log(component: string, action: string, status: LogStatus, details?: any, sessionId?: string, jobId?: string): Promise<void>;
+    private bufferEntry;
+    private flushBuffer;
+    getRecentLogs(count?: number): FrameworkLogEntry[];
+    getComponentUsage(component: string): FrameworkLogEntry[];
+    printRundown(): void;
+}
+export declare const frameworkLogger: FrameworkUsageLogger;

package/dist/core/index.d.ts

@@ -0,0 +1,5 @@
+export { KernelOrchestrator } from "./orchestrator.js";
+export { defaultXrayConfig } from "./xray-activation.js";
+export { getConfigDir, resolveConfigPath, resolveStateDir, resolveProfilesDir, resolveCodexPath, resolveLogDir, resetConfigDirCache, XRAY_CONFIG_DIR_ENV, } from "./config-paths.js";
+export { formatCodexPrompt, formatMinimalCodexPrompt, getCodexConfig, findCodexPath, loadCodex, BUILTIN_CODEX, } from "./codex-formatter.js";
+export type { CodexTerm, CodexConfig, FormatOptions, FormatResult, } from "./codex-formatter.js";