0xray 3.4.1 → 3.4.3

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

@@ -0,0 +1,10 @@
+export interface LoggingConfig {
+    enabled: boolean;
+    level: "debug" | "info" | "warn" | "error";
+    destinations: ("console" | "file" | "monitoring")[];
+    performanceMode: boolean;
+}
+export declare function getLoggingConfig(): LoggingConfig;
+export declare function setLoggingConfig(config: Partial<LoggingConfig>): void;
+export declare function isLoggingEnabled(): boolean;
+export declare function shouldLog(level: string): boolean;

package/dist/core/model-router.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Model Router
+ *
+ * Intelligent model routing based on task complexity and type.
+ * Uses featuresConfigLoader as the single source of truth for all model config.
+ *
+ * @since 2026-01-25
+ */
+import { type TaskType } from "./features-config.js";
+interface TaskContext {
+    toolName?: string;
+    fileCount?: number;
+    isComplex?: boolean;
+    agentType?: string;
+}
+declare class ModelRouter {
+    private availableModels;
+    constructor();
+    private discoverModels;
+    /**
+     * Get the appropriate model for a specific task context
+     * Uses features-config for task-based routing when available
+     */
+    getModelForTask(context: TaskContext): string;
+    /**
+     * Get validated model for agent type
+     */
+    getValidatedModel(agentType?: string): string;
+    /**
+     * Get model for a specific task type directly
+     */
+    getModelForTaskType(taskType: TaskType): string;
+    /**
+     * Get max tokens for a task type
+     */
+    getMaxTokensForTaskType(taskType: TaskType): number;
+    private isModelAvailable;
+    /**
+     * Reload configuration from disk
+     */
+    reloadConfig(): void;
+    /**
+     * Get current configuration summary
+     */
+    getConfigSummary(): {
+        defaultModel: string;
+        fallbackModel: string;
+        taskRoutingEnabled: boolean;
+        availableModels: string[];
+    };
+}
+export declare const modelRouter: ModelRouter;
+export default modelRouter;
+export declare const getModelForTask: (context: TaskContext) => string;
+export declare const getModelForTaskType: (taskType: TaskType) => string;
+export declare const getValidatedModel: (agentType?: string) => string;

package/dist/core/orchestrator.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 0xRay Framework - Core Orchestrator
+ * Main orchestration engine for multi-agent task coordination
+ */
+import { TaskDefinition } from "../agents/types.js";
+export interface OrchestrationResult {
+    success: boolean;
+    taskId: string;
+    agentUsed: string;
+    duration: number;
+    result: unknown;
+    error?: string;
+    errors?: string[];
+}
+export interface OrchestratorConfig {
+    maxConcurrentTasks?: number;
+    taskTimeout?: number;
+    conflictResolutionStrategy?: "majority_vote" | "expert_priority";
+}
+export declare class KernelOrchestrator {
+    private taskQueue;
+    private activeTasks;
+    private totalProcessed;
+    private config;
+    private kernel;
+    constructor(config?: OrchestratorConfig);
+    executeTask(task: TaskDefinition): Promise<OrchestrationResult>;
+    /**
+     * Execute a single task by delegating to appropriate subagent
+     */
+    private executeSingleTask;
+    private dispatchToAgent;
+    executeComplexTask(description: string, tasks: TaskDefinition[], sessionId?: string): Promise<OrchestrationResult[]>;
+    private topologicalSort;
+    /**
+     * Validates that all task dependencies are within the current task batch.
+     * Prevents cross-orchestrator dependency errors by failing fast with a clear message.
+     */
+    private validateTaskDependencies;
+    executeComplexTaskSingle(task: TaskDefinition): Promise<OrchestrationResult>;
+    resolveConflicts(conflicts: Array<{
+        response?: unknown;
+        proposed?: unknown;
+        expertiseScore?: number;
+    }>): {
+        response: string;
+        expertiseScore: number;
+    };
+    private generateTaskId;
+    /**
+     * Delegate a task to a specific agent with timeout protection
+     */
+    delegateToSubagent(agentName: string, task: TaskDefinition): Promise<{
+        success: boolean;
+        result: unknown;
+        agentName: string;
+        executionTime: number;
+    }>;
+    private performDelegation;
+    getStatus(): {
+        queueSize: number;
+        activeTasks: number;
+        totalProcessed: number;
+        config: {
+            maxConcurrentTasks: number;
+            taskTimeout: number;
+            conflictResolutionStrategy: "majority_vote" | "expert_priority";
+        };
+    };
+}
+export declare const xrayOrchestrator: KernelOrchestrator;

package/dist/core/system-prompt-generator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 0xRay Lean System Prompt Generator
+ *
+ * Generates optimized, token-efficient system prompts by implementing
+ * selective injection and smart compression strategies.
+ *
+ * @since 2026-03-03
+ */
+/**
+ * System prompt configuration options
+ */
+export interface SystemPromptConfig {
+    showWelcomeBanner?: boolean;
+    showCodexContext?: boolean;
+    enableTokenOptimization?: boolean;
+    maxTokenBudget?: number;
+    showCriticalTermsOnly?: boolean;
+    showEssentialLinks?: boolean;
+}
+/**
+ * Generate optimized system prompt with bloat prevention
+ */
+export declare function generateLeanSystemPrompt(config?: SystemPromptConfig): Promise<string>;
+/**
+ * Smart context injection based on available tokens
+ */
+export declare function injectContextIntelligently(basePrompt: string, additionalContext: string, maxTokens?: number): string;
+/**
+ * System prompt validation
+ */
+export declare function validateSystemPrompt(prompt: string): {
+    valid: boolean;
+    warnings: string[];
+};

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

@@ -0,0 +1,12 @@
+export interface TraceContext {
+    traceId: string;
+    parentId?: string;
+    operation: string;
+    governanceApproved: boolean;
+    startTime: number;
+    metadata?: Record<string, any>;
+}
+export declare function startTrace(operation: string, metadata?: Record<string, any>): TraceContext;
+export declare function getCurrentTrace(): TraceContext | null;
+export declare function endTrace(approved?: boolean): void;
+export declare function propagateTrace(childOperation: string): TraceContext | null;

package/dist/core/xray-activation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Consumer runtime compat shim from prior 0xRay releases (1-line min per Scope Rule; primary xray paths + .xray fallbacks).
+ */
+export interface XrayActivationConfig {
+    enableOrchestrator: boolean;
+    enableBootOrchestrator: boolean;
+    enableStateManagement: boolean;
+    enableHooks: boolean;
+    enableCodexInjection: boolean;
+    enableProcessors: boolean;
+    enablePostProcessor: boolean;
+}
+export declare const defaultXrayConfig: XrayActivationConfig;
+export declare function activateXrayFramework(config?: Partial<XrayActivationConfig>): Promise<void>;

package/dist/delegation/agent-delegator.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Agent Delegator
+ *
+ * Intelligent agent delegation system that uses complexity analysis to determine
+ * optimal task distribution strategies and conflict resolution.
+ *
+ * Integrates with TaskSkillRouter for keyword-based preprocessing.
+ *
+ * @since 2026-01-07
+ */
+import { ComplexityScore } from "./complexity-analyzer.js";
+import { XrayStateManager } from "../state/state-manager.js";
+import { xrayConfigLoader } from "../core/config-loader.js";
+import { type AggregatedMetrics, type MetricsExport } from "./metrics-aggregator.js";
+export interface AgentCapability {
+    name: string;
+    capabilities: string[];
+    expertise?: string[];
+    specialties?: string[];
+    status: "active" | "inactive";
+    [key: string]: string | string[] | boolean | number | undefined;
+}
+export interface DelegationContext {
+    workingDirectory?: string;
+    availableTools?: string[];
+    isDelegated?: boolean;
+    files?: string[];
+    dependencies?: string[];
+    changeVolume?: number;
+    riskLevel?: string;
+    [key: string]: unknown;
+}
+export interface DelegationResponse {
+    agent: string;
+    operation: string;
+    description: string;
+    capabilities: string[];
+    mode: string;
+    status: string;
+    timestamp: string;
+    message: string;
+}
+export interface DelegationRequest {
+    operation: string;
+    description: string;
+    context?: DelegationContext;
+    sessionId?: string;
+}
+export interface DelegationAnalysis {
+    strategy: "single-agent" | "multi-agent" | "orchestrator-led";
+    agents: string[];
+    agentDetails: Array<{
+        name: string;
+        confidence: number;
+        role: string;
+    }>;
+    complexity: ComplexityScore;
+    conflictResolution: "majority_vote" | "expert_priority" | "consensus";
+    estimatedDuration: number;
+    metrics?: Record<string, string | number | boolean>;
+}
+export interface DelegationResult {
+    success: boolean;
+    results: Array<{
+        agent: string;
+        output: DelegationResponse;
+        executionTime: number;
+    }>;
+    totalTime: number;
+    errors?: string[] | undefined;
+    agents?: string[];
+}
+export interface PerformanceMetrics {
+    totalDelegations: number;
+    successfulDelegations: number;
+    failedDelegations: number;
+    averageExecutionTime: number;
+    averageResponseTime: number;
+    averageComplexity: number;
+    averageDuration: number;
+    strategyUsage: Record<string, number>;
+    agentUtilization: Record<string, number>;
+}
+export interface DelegationMetrics extends PerformanceMetrics {
+    recentDelegations: Array<{
+        timestamp: number;
+        operation: string;
+        strategy: string;
+        success: boolean;
+        totalTime: number;
+    }>;
+}
+/**
+ * AgentDelegator class for intelligent task delegation
+ */
+export declare class AgentDelegator {
+    private complexityAnalyzer;
+    private stateManager;
+    private configLoader;
+    private kernel;
+    private agentMetrics;
+    /** Minimum confidence for a learned mapping to override hardcoded routing. */
+    private static readonly MAPPING_CONFIDENCE_THRESHOLD;
+    constructor(stateManager: XrayStateManager, configLoader: typeof xrayConfigLoader);
+    /**
+     * Load routing-mappings.json from disk (fresh each call — picks up tuner writes).
+     * Same path resolution as inference-tuner.ts.
+     */
+    private loadRoutingMappings;
+    /**
+     * Match a task description against learned keyword mappings.
+     * Returns the best matching mapping if any keyword hits above threshold.
+     */
+    private matchRoutingMappings;
+    getAvailableAgents(): AgentCapability[];
+    /**
+     * Pre-process a task description using TaskSkillRouter
+     * This extracts operation type and context from natural language descriptions
+     * before running complexity analysis
+     */
+    preprocessTaskDescription(description: string, options?: {
+        sessionId?: string;
+        taskId?: string;
+        complexity?: number;
+    }): {
+        operation: string;
+        context: Record<string, unknown>;
+        suggestedAgent: string;
+        suggestedSkill: string;
+        confidence: number;
+    };
+    analyzeDelegation(request: DelegationRequest): Promise<DelegationAnalysis>;
+    private determineAgents;
+    private mapOperationToType;
+    /**
+     * Record analysis results for learning system
+     */
+    private recordAnalysisForLearning;
+    private determineConflictResolution;
+    /**
+   * Resolve the project directory for delegated agents
+   * Ensures working directory is set correctly (src/ vs dist/ vs project root)
+   */
+    private resolveProjectDirectory;
+    /**
+     * Allowlist of valid agent names for dynamic imports
+     * Prevents path traversal and unauthorized agent loading
+     */
+    private static readonly ALLOWED_AGENTS;
+    /**
+     * Validate agent name for security
+     * @throws Error if agent name is invalid or not allowed
+     */
+    private validateAgentName;
+    /**
+     * Create a properly configured agent with full tool access and working directory context
+     */
+    private createProperlyConfiguredAgent;
+    /**
+     * Clear agent-stub creation and deprecated features
+     * Remove this method if it exists in the future version
+     */
+    private clearDeprecatedStubAgent;
+    executeDelegation(analysis: DelegationAnalysis, request: DelegationRequest): Promise<DelegationResult>;
+    getPerformanceMetrics(): PerformanceMetrics;
+    getDelegationMetrics(): DelegationMetrics;
+    aggregateAllMetrics(): {
+        delegation: AggregatedMetrics;
+        orchestration: AggregatedMetrics;
+    };
+    getMetricsByAgent(type?: "delegation" | "orchestration"): Record<string, unknown>;
+    getMetricsByComplexity(type?: "delegation" | "orchestration"): Record<string, unknown>;
+    getMetricsByTimePeriod(type?: "delegation" | "orchestration"): Record<string, unknown>;
+    rotateMetricsEntries(maxEntries?: number): {
+        delegation: number;
+        orchestration: number;
+    };
+    cleanupMetricsOlderThan(olderThanMs: number): {
+        delegation: number;
+        orchestration: number;
+    };
+    exportMetricsData(format?: "json" | "csv" | "summary"): MetricsExport;
+    updateAgentCapability(agentName: string, capabilities: Partial<AgentCapability>): void;
+}
+export declare function createAgentDelegator(stateManager: XrayStateManager, configLoader: typeof xrayConfigLoader): AgentDelegator;

package/dist/delegation/agent-expertise.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Agent Expertise Configuration
+ *
+ * Defines expertise levels for weighted voting across all 0xRay agents.
+ * Higher expertise = higher weight in voting decisions.
+ *
+ * @since 2026-04-16
+ */
+import type { AgentExpertise } from "./voting-types.js";
+export declare const AGENT_EXPERTISE_LEVELS: Record<string, AgentExpertise>;
+export declare function getAgentExpertise(agentName: string): AgentExpertise | undefined;
+export declare function getAgentExpertiseLevel(agentName: string): number;
+export declare function getVotingWeight(agentName: string): number;
+export declare function getAgentsWithExpertiseDomain(domain: string): AgentExpertise[];
+export declare function getTopExpertsForDomain(domain: string, count?: number): AgentExpertise[];

package/dist/delegation/analytics/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Analytics Module Index
+ *
+ * Barrel export for all analytics components.
+ * Extracted from task-skill-router.ts as part of Phase 2 refactoring.
+ *
+ * @since 2026-03-12
+ */
+export { RoutingOutcomeTracker, routingOutcomeTracker } from './outcome-tracker.js';
+export { RoutingAnalytics } from './routing-analytics.js';
+export { LearningEngine, learningEngine } from './learning-engine.js';

package/dist/delegation/analytics/learning-engine.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Learning Engine
+ *
+ * P9 learning system - analyzes patterns, detects drift, and improves routing.
+ * Extracted from task-skill-router.ts as part of Phase 2 refactoring.
+ *
+ * @since 2026-03-12
+ */
+import { P9LearningStats, PatternDriftAnalysis, LearningResult, AdaptiveThresholds } from '../config/types.js';
+/**
+ * LearningEngine class
+ *
+ * Active implementation for P9 learning capabilities:
+ * - Pattern drift detection
+ * - Automatic routing refinement
+ * - Success rate learning
+ * - Adaptive confidence thresholds
+ */
+export declare class LearningEngine {
+    private enabled;
+    private learningHistory;
+    constructor(enabled?: boolean);
+    /**
+     * Get P9 learning statistics
+     */
+    getP9LearningStats(): P9LearningStats;
+    /**
+     * Calculate overall success rate from outcome tracker
+     */
+    private calculateOverallSuccessRate;
+    /**
+     * Get pattern drift analysis from performance tracker
+     */
+    getPatternDriftAnalysis(): PatternDriftAnalysis;
+    /**
+     * Get adaptive thresholds based on learned data
+     */
+    getAdaptiveThresholds(): AdaptiveThresholds;
+    /**
+     * Trigger P9 learning process
+     */
+    triggerLearning(): Promise<LearningResult>;
+    /**
+     * Enable or disable learning
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if learning is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get learning history
+     */
+    getLearningHistory(): Array<{
+        timestamp: Date;
+        patternsAnalyzed: number;
+        adaptations: number;
+        successRate: number;
+    }>;
+    /**
+     * Clear learning history
+     */
+    clearHistory(): void;
+    /**
+     * Analyze a specific pattern for optimization opportunities
+     */
+    analyzePattern(patternId: string): {
+        optimized: boolean;
+        recommendations: string[];
+        confidence: number;
+    };
+    /**
+     * Suggest routing improvements based on learning
+     */
+    suggestImprovements(): Array<{
+        type: 'mapping' | 'threshold' | 'confidence';
+        description: string;
+        impact: 'low' | 'medium' | 'high';
+    }>;
+}
+/**
+ * Global learning engine instance (enabled by default)
+ */
+export declare const learningEngine: LearningEngine;

package/dist/delegation/analytics/outcome-tracker.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Routing Outcome Tracker
+ *
+ * Tracks routing outcomes and provides statistics for performance analysis.
+ * Extracted from task-skill-router.ts as part of Phase 2 refactoring.
+ *
+ * @since 2026-03-12
+ */
+import { RoutingOutcome, AgentStats, PromptDataPoint, RoutingDecision } from '../config/types.js';
+/**
+ * RoutingOutcomeTracker class
+ *
+ * Tracks routing outcomes with circular buffer pattern for memory efficiency.
+ * Provides methods for recording outcomes, calculating statistics, and
+ * retrieving data for analytics.
+ *
+ * Persists outcomes to logs/framework/routing-outcomes.json for analytics to read.
+ */
+export declare class RoutingOutcomeTracker {
+    private outcomes;
+    private readonly maxOutcomes;
+    private readonly persistencePath;
+    private saveTimeout;
+    private readonly SAVE_DEBOUNCE_MS;
+    /**
+     * Create a new outcome tracker
+     * @param maxOutcomes Maximum number of outcomes to retain (default: 1000)
+     */
+    constructor(maxOutcomes?: number);
+    /**
+     * Ensure the log directory and file exist on initialization
+     */
+    private initializeFile;
+    /**
+     * Load outcomes from disk on initialization
+     */
+    private loadFromDisk;
+    /**
+     * Save outcomes to disk (debounced)
+     */
+    private scheduleSave;
+    /**
+     * Immediately save to disk (synchronous for reliability)
+     */
+    private saveToDisk;
+    /**
+     * Record a new routing outcome
+     * @param outcome The outcome to record (timestamp will be added)
+     */
+    recordOutcome(outcome: Omit<RoutingOutcome, 'timestamp'>): void;
+    /**
+     * Update an existing outcome by taskId
+     * @param taskId The task ID to update
+     * @param updates The fields to update
+     * @returns true if updated, false if not found
+     */
+    updateOutcome(taskId: string, updates: Partial<RoutingOutcome>): boolean;
+    /**
+     * Force reload from disk - call this before analytics to get latest data
+     */
+    reloadFromDisk(): Promise<void>;
+    /**
+     * Get all outcomes, optionally filtered by agent
+     * @param agent Optional agent name to filter by
+     * @returns Array of routing outcomes
+     */
+    getOutcomes(agent?: string): RoutingOutcome[];
+    /**
+     * Calculate success rate for a specific agent
+     * @param agent The agent name
+     * @returns Success rate between 0 and 1
+     */
+    getSuccessRate(agent: string): number;
+    /**
+     * Get statistics for all agents
+     * @returns Array of agent statistics
+     */
+    getStats(): AgentStats[];
+    /**
+     * Clear all recorded outcomes
+     */
+    clear(): void;
+    /**
+     * Get the count of recorded outcomes
+     * @returns Number of outcomes
+     */
+    getCount(): number;
+    /**
+     * Export outcomes to JSON string
+     * @returns JSON string of all outcomes
+     */
+    toJSON(): string;
+    /**
+     * Convert outcomes to prompt data points for pattern analysis
+     * @returns Array of prompt data points
+     */
+    getPromptData(): PromptDataPoint[];
+    /**
+     * Convert outcomes to routing decisions
+     * @returns Array of routing decisions
+     */
+    getRoutingDecisions(): RoutingDecision[];
+    /**
+     * Apply routing refinements to existing outcomes
+     * @param changes Array of changes to apply
+     */
+    applyRoutingRefinements(changes: Array<{
+        taskId: string;
+        agent?: string;
+        skill?: string;
+        confidence?: number;
+    }>): void;
+}
+/**
+ * Global routing outcome tracker instance
+ */
+export declare const routingOutcomeTracker: RoutingOutcomeTracker;

package/dist/delegation/analytics/routing-analytics.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Routing Analytics
+ *
+ * Provides analytics aggregation and insights generation for routing data.
+ * Extracted from task-skill-router.ts as part of Phase 2 refactoring.
+ *
+ * @since 2026-03-12
+ */
+import { DailyAnalyticsSummary, RoutingAnalyticsData, RoutingRefinementResult } from '../config/types.js';
+import { RoutingOutcomeTracker } from './outcome-tracker.js';
+/**
+ * RoutingAnalytics class
+ *
+ * Aggregates routing data and provides analytics insights.
+ * Works with RoutingOutcomeTracker to generate reports and recommendations.
+ */
+export declare class RoutingAnalytics {
+    private tracker;
+    constructor(tracker: RoutingOutcomeTracker);
+    /**
+     * Get daily analytics summary for reporting
+     * @returns Daily summary with metrics and insights
+     */
+    getDailySummary(): DailyAnalyticsSummary;
+    /**
+     * Get full routing analytics data
+     * @returns Comprehensive analytics data
+     */
+    getFullAnalytics(): RoutingAnalyticsData;
+    /**
+     * Apply routing refinements based on analytics
+     * @param apply Whether to actually apply the changes
+     * @returns Refinement result with changes list
+     */
+    applyRoutingRefinements(apply: boolean): RoutingRefinementResult;
+    /**
+     * Generate insights from routing data
+     * @returns Array of insight strings
+     */
+    generateInsights(): string[];
+    /**
+     * Get raw statistics from the tracker
+     * @returns Record of agent statistics
+     */
+    getRawStats(): Record<string, {
+        attempts: number;
+        successes: number;
+        successRate: number;
+    }>;
+    /**
+     * Compare current performance to historical baseline
+     * @returns Comparison metrics
+     */
+    compareToBaseline(): {
+        improved: boolean;
+        changePercent: number;
+        currentRate: number;
+        baselineRate: number;
+    };
+}