0xray 3.4.2 → 3.4.3

package/dist/mcps/types/json-rpc.types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * JSON-RPC Types
+ *
+ * TypeScript interfaces for JSON-RPC 2.0 protocol messages.
+ * Used for MCP server communication.
+ */
+/**
+ * JSON-RPC Request
+ * Standard JSON-RPC 2.0 request format
+ */
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: string;
+    params?: unknown;
+}
+/**
+ * JSON-RPC Response
+ * Standard JSON-RPC 2.0 response format
+ */
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: number | string;
+    result?: unknown;
+    error?: JsonRpcError;
+}
+/**
+ * JSON-RPC Error
+ * Standard JSON-RPC 2.0 error format
+ */
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}

package/dist/mcps/types/mcp.types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * MCP Types
+ *
+ * Core TypeScript interfaces and types for the MCP Client system.
+ * Extracted from mcp-client.ts as part of Phase 1 refactoring.
+ */
+import type { JsonRpcRequest, JsonRpcResponse } from './json-rpc.types.js';
+/**
+ * MCP Client Configuration
+ * Defines the configuration for connecting to an MCP server
+ */
+export interface MCPClientConfig {
+    serverName: string;
+    command: string;
+    args: string[];
+    timeout?: number;
+    env?: Record<string, string>;
+    basePath?: string;
+}
+/**
+ * MCP Tool Definition
+ * Represents a tool available on an MCP server
+ */
+export interface MCPTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * MCP Tool Result
+ * Represents the result of calling an MCP tool
+ */
+export interface MCPToolResult {
+    content: Array<{
+        type: string;
+        text?: string;
+        data?: unknown;
+    }>;
+    isError?: boolean;
+}
+/**
+ * MCP Connection Interface
+ * Defines the contract for MCP server connections
+ */
+export interface IMcpConnection {
+    readonly serverName: string;
+    readonly isConnected: boolean;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    sendRequest(request: JsonRpcRequest): Promise<JsonRpcResponse>;
+}
+/**
+ * Server Configuration Interface
+ * Abstraction over raw MCPClientConfig for dependency injection
+ */
+export interface IServerConfig {
+    serverName: string;
+    command: string;
+    args: string[];
+    timeout: number;
+    env?: Record<string, string>;
+    basePath?: string;
+}
+/**
+ * Tool Registry Interface
+ * Manages tool registration and lookup across servers
+ */
+export interface IToolRegistry {
+    register(serverName: string, tools: MCPTool[]): void;
+    getTools(serverName: string): MCPTool[];
+    getTool(serverName: string, toolName: string): MCPTool | undefined;
+    hasTool(serverName: string, toolName: string): boolean;
+    clear(): void;
+}
+/**
+ * Protocol Handler Interface
+ * Handles JSON-RPC protocol building and parsing
+ */
+export interface IProtocolHandler {
+    buildInitializeRequest(): JsonRpcRequest;
+    buildToolListRequest(): JsonRpcRequest;
+    buildToolCallRequest(toolName: string, args: unknown): JsonRpcRequest;
+    parseResponse(data: string): JsonRpcResponse;
+}
+/**
+ * Simulation Engine Interface
+ * Provides fallback simulation for MCP tools
+ */
+export interface ISimulationEngine {
+    canSimulate(serverName: string, toolName: string): boolean;
+    simulate(serverName: string, toolName: string, args: unknown): Promise<MCPToolResult>;
+}
+/**
+ * Connection Pool Interface
+ * Manages MCP connection lifecycle and reuse
+ */
+export interface IConnectionPool {
+    acquire(serverName: string): Promise<IMcpConnection>;
+    release(connection: IMcpConnection): void;
+    clear(): Promise<void>;
+}

package/dist/memory-routing/index.d.ts

@@ -0,0 +1,6 @@
+export type { MemoryRoutingProvider, MemoryRoutingContext, MemoryInheritedContext, MemoryAgentCapability, MemoryOrchestrationTask, MemoryThinDispatchResult, MemoryRoutingConfig, OrchestratorFeedbackEntry, } from './types.js';
+export { getMemoryRoutingProvider, getMemoryRoutingProviderSync, getMemoryRoutingConfig, resetMemoryRoutingProvider, initializeMemoryRouting, } from './provider-registry.js';
+export { NullMemoryRoutingProvider, createMemoryRoutingProvider } from './null-provider.js';
+export { loadMemoryRoutingProvider } from './provider-loader.js';
+export { validateMemoryRoutingConfig } from './validate-config.js';
+export type { MemoryRoutingValidation } from './validate-config.js';

package/dist/memory-routing/null-provider.d.ts

@@ -0,0 +1,14 @@
+import type { MemoryAgentCapability, MemoryInheritedContext, MemoryOrchestrationTask, MemoryRoutingContext, MemoryRoutingProvider, MemoryTaskConfidence, MemoryThinDispatchResult } from './types.js';
+export declare class NullMemoryRoutingProvider implements MemoryRoutingProvider {
+    readonly id = "null";
+    readonly name = "Null (no memory routing)";
+    isAvailable(): boolean;
+    buildRoutingContext(): MemoryRoutingContext;
+    enhanceAgentCapabilities(base: Map<string, MemoryAgentCapability>): Map<string, MemoryAgentCapability>;
+    enrichTasks(tasks: MemoryOrchestrationTask[]): MemoryOrchestrationTask[];
+    buildInheritedContext(): MemoryInheritedContext;
+    selectAgent(capabilities: Map<string, MemoryAgentCapability>, requiredCapabilities: string[], complexity: number): string | null;
+    resolveThinDispatch(baseAgent: string, _operation: string, complexityScore: number): MemoryThinDispatchResult;
+    getTaskConfidence(): MemoryTaskConfidence;
+}
+export declare function createMemoryRoutingProvider(): MemoryRoutingProvider;

package/dist/memory-routing/provider-loader.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryRoutingConfig, MemoryRoutingProvider } from './types.js';
+export declare function loadMemoryRoutingProvider(config: MemoryRoutingConfig, cwd?: string): Promise<MemoryRoutingProvider>;

package/dist/memory-routing/provider-registry.d.ts

@@ -0,0 +1,8 @@
+import type { MemoryRoutingConfig, MemoryRoutingProvider } from './types.js';
+export declare function getMemoryRoutingConfig(): MemoryRoutingConfig;
+export declare function getMemoryRoutingProvider(forceReload?: boolean): Promise<MemoryRoutingProvider>;
+/** Synchronous accessor — returns shared null singleton until async load completes. */
+export declare function getMemoryRoutingProviderSync(): MemoryRoutingProvider;
+export declare function resetMemoryRoutingProvider(): void;
+/** Kick off background load at module init. */
+export declare function initializeMemoryRouting(): void;

package/dist/memory-routing/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Memory Routing Provider — pluggable contract for long-term memory enrichment.
+ *
+ * Repertoire is one implementation. Any provider exposing createMemoryRoutingProvider()
+ * can be loaded via features.json memory_routing.module_path.
+ */
+export interface MemoryAgentCapability {
+    capabilities: string[];
+    complexityThreshold: number;
+    concurrentTasks: number;
+    memorySignals?: string[];
+    memoryTags?: string[];
+}
+export interface MemoryOrchestrationTask {
+    id: string;
+    description: string;
+    type: string;
+    priority?: 'critical' | 'high' | 'medium' | 'low';
+    dependencies?: string[];
+    estimatedComplexity?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface MemoryTaskConfidence {
+    signals: Array<{
+        name: string;
+        confidence: number;
+    }>;
+    matchedSignals: string[];
+    avgConfidence: number;
+    maxConfidence: number;
+    highConfidenceTrapPresent: boolean;
+    ontologicalTrapDetected: boolean;
+    complexityBoost: number;
+    recommendedAgent: string | null;
+}
+export interface MemoryRoutingContext {
+    providerId: string;
+    matchedSignals: string[];
+    matchedTags: string[];
+    flags: Record<string, boolean>;
+    synthesisAvailable: boolean;
+    signalConfidences?: Record<string, number>;
+    avgMatchConfidence?: number;
+}
+export interface MemoryInheritedContext {
+    providerId: string;
+    matchedSignals: Array<{
+        name: string;
+        definition: string;
+        priority: string;
+    }>;
+    synthesisExcerpt?: string;
+    flags: Record<string, boolean>;
+}
+export interface MemoryThinDispatchResult {
+    agent: string;
+    adjustedScore: number;
+    context: MemoryRoutingContext;
+}
+export interface OrchestratorFeedbackEntry {
+    timestamp: string;
+    sessionId: string;
+    taskId: string;
+    assignedAgent: string;
+    memorySignals: string[];
+    complexity: number;
+    success: boolean;
+    durationMs: number;
+    dynamoResult?: Record<string, unknown>;
+}
+export interface MemoryRoutingProviderConfig {
+    [key: string]: unknown;
+}
+/**
+ * Contract every memory routing provider must implement.
+ * Export factory: createMemoryRoutingProvider(config?) => MemoryRoutingProvider
+ *
+ * Agent selection split:
+ * - selectAgent() — used by ExecutionPlanner / AgentCapabilitiesManager when
+ *   required capabilities and operation text are known at plan time.
+ * - resolveThinDispatch() — used by thinDispatch.scoreAndRoute() when only a
+ *   complexity score and operation string exist; may adjust score and override
+ *   the tier-default agent. Both may consult the same signal registry but
+ *   operate at different pipeline stages.
+ */
+export interface MemoryRoutingProvider {
+    readonly id: string;
+    readonly name: string;
+    isAvailable(): boolean;
+    buildRoutingContext(operation: string): MemoryRoutingContext;
+    enhanceAgentCapabilities(base: Map<string, MemoryAgentCapability>): Map<string, MemoryAgentCapability>;
+    enrichTasks(tasks: MemoryOrchestrationTask[]): MemoryOrchestrationTask[];
+    buildInheritedContext(tasks: MemoryOrchestrationTask[]): MemoryInheritedContext;
+    selectAgent(capabilities: Map<string, MemoryAgentCapability>, requiredCapabilities: string[], complexity: number, operation: string): string | null;
+    resolveThinDispatch(baseAgent: string, operation: string, complexityScore: number): MemoryThinDispatchResult;
+    getTaskConfidence?(task: MemoryOrchestrationTask): MemoryTaskConfidence;
+    ingestFeedback?(entry: OrchestratorFeedbackEntry): void;
+}
+export interface MemoryRoutingConfig {
+    enabled: boolean;
+    provider: 'null' | 'repertoire' | 'custom';
+    module_path?: string;
+    config?: MemoryRoutingProviderConfig;
+}

package/dist/memory-routing/validate-config.d.ts

@@ -0,0 +1,7 @@
+import type { MemoryRoutingConfig } from './types.js';
+export interface MemoryRoutingValidation {
+    valid: boolean;
+    errors: string[];
+    normalized: MemoryRoutingConfig;
+}
+export declare function validateMemoryRoutingConfig(raw: unknown): MemoryRoutingValidation;

package/dist/metrics/agent-metrics.d.ts

@@ -0,0 +1,169 @@
+import { XrayStateManager } from "../state/state-manager.js";
+export interface AgentInvocation {
+    id: string;
+    agentName: string;
+    agentType: AgentType;
+    timestamp: number;
+    operation: string;
+    description: string;
+    complexityLevel: ComplexityLevel;
+    complexityScore: number;
+    duration: number;
+    success: boolean;
+    error: string | undefined;
+    sessionId: string | undefined;
+    parentTaskId: string | undefined;
+    inputTokens: number | undefined;
+    outputTokens: number | undefined;
+    metadata: Record<string, unknown> | undefined;
+}
+export type AgentType = "architect" | "code-analyzer" | "code-reviewer" | "researcher" | "frontend-engineer" | "backend-engineer" | "devops-engineer" | "security-auditor" | "database-engineer" | "testing-lead" | "performance-engineer" | "refactorer" | "bug-triage-specialist" | "strategist" | "tech-writer" | "content-creator" | "seo-consultant" | "growth-strategist" | "log-monitor" | "multimodal-looker" | "mobile-developer" | "frontend-ui-ux-engineer" | "custom" | "unknown";
+export type ComplexityLevel = "simple" | "moderate" | "complex" | "enterprise";
+export interface AgentInvocationSummary {
+    agentName: string;
+    totalInvocations: number;
+    successfulInvocations: number;
+    failedInvocations: number;
+    successRate: number;
+    averageDuration: number;
+    averageComplexity: number;
+    lastInvoked: number;
+    firstInvoked: number;
+    operations: string[];
+}
+export interface TimePeriodSummary {
+    period: string;
+    periodType: "hour" | "day" | "week" | "month";
+    totalInvocations: number;
+    successfulInvocations: number;
+    failedInvocations: number;
+    successRate: number;
+    averageDuration: number;
+    agents: Record<string, number>;
+}
+export interface ComplexitySummary {
+    level: ComplexityLevel;
+    totalInvocations: number;
+    successfulInvocations: number;
+    failedInvocations: number;
+    successRate: number;
+    averageDuration: number;
+    agents: Record<string, number>;
+}
+export interface AggregatedAgentMetrics {
+    summary: {
+        totalInvocations: number;
+        totalAgents: number;
+        timeRange: {
+            start: number;
+            end: number;
+        };
+        overallSuccessRate: number;
+        averageDuration: number;
+    };
+    byAgent: Record<string, AgentInvocationSummary>;
+    byTimePeriod: Record<string, TimePeriodSummary>;
+    byComplexity: Record<string, ComplexitySummary>;
+}
+export interface MetricsRetentionConfig {
+    maxEntries: number;
+    maxAgeMs: number;
+    enableAutoCleanup: boolean;
+    cleanupIntervalMs: number;
+}
+export interface MetricsExport {
+    format: "json" | "csv" | "summary" | "detailed";
+    data: unknown;
+    exportedAt: number;
+    entryCount: number;
+    metadata: {
+        fromDate: number | undefined;
+        toDate: number | undefined;
+        filter: Record<string, unknown> | undefined;
+    };
+}
+export interface AgentMetricsFilter {
+    agentNames?: string[];
+    agentTypes?: AgentType[];
+    timeRange?: {
+        start: number;
+        end: number;
+    };
+    complexityLevels?: ComplexityLevel[];
+    successOnly?: boolean;
+    failureOnly?: boolean;
+    sessionId?: string;
+}
+export declare class AgentMetricsSystem {
+    private stateManager;
+    private retentionConfig;
+    private cleanupInterval;
+    private initialized;
+    constructor(stateManager: XrayStateManager, retentionConfig?: Partial<MetricsRetentionConfig>);
+    initialize(): Promise<void>;
+    private startAutoCleanup;
+    private performCleanup;
+    private getInvocations;
+    private saveInvocations;
+    private generateId;
+    trackInvocation(params: {
+        agentName: string;
+        agentType: AgentType;
+        operation: string;
+        description?: string;
+        complexityLevel?: ComplexityLevel;
+        complexityScore?: number;
+        duration?: number;
+        success: boolean;
+        error?: string;
+        sessionId?: string;
+        parentTaskId?: string;
+        inputTokens?: number;
+        outputTokens?: number;
+        metadata?: Record<string, unknown>;
+    }): AgentInvocation;
+    trackSuccess(params: Omit<Parameters<typeof this.trackInvocation>[0], "success" | "error">): AgentInvocation;
+    trackFailure(params: Omit<Parameters<typeof this.trackInvocation>[0], "success"> & {
+        error: string;
+    }): AgentInvocation;
+    getInvocationsByAgent(agentName: string): AgentInvocation[];
+    getInvocationsBySession(sessionId: string): AgentInvocation[];
+    getInvocationsByTimeRange(start: number, end: number): AgentInvocation[];
+    filterInvocations(filter: AgentMetricsFilter): AgentInvocation[];
+    aggregateMetrics(filter?: AgentMetricsFilter): AggregatedAgentMetrics;
+    private getHourKey;
+    private getDayKey;
+    private getWeekKey;
+    private getMonthKey;
+    private getWeekNumber;
+    private getPeriodType;
+    getAgentSummary(agentName: string): AgentInvocationSummary | null;
+    getTimePeriodSummary(period: string, periodType: "hour" | "day" | "week" | "month"): TimePeriodSummary | null;
+    getComplexitySummary(level: ComplexityLevel): ComplexitySummary | null;
+    cleanup(olderThanMs?: number, maxEntries?: number): {
+        removed: number;
+        total: number;
+        byAgent: Record<string, number>;
+    };
+    resetMetrics(): void;
+    exportMetrics(format?: "json" | "csv" | "summary" | "detailed", filter?: AgentMetricsFilter): MetricsExport;
+    private toCSV;
+    private escapeCSV;
+    getStatistics(): {
+        totalInvocations: number;
+        uniqueAgents: number;
+        oldestInvocation: number | null;
+        newestInvocation: number | null;
+        successRate: number;
+        averageDuration: number;
+        topAgents: Array<{
+            name: string;
+            count: number;
+        }>;
+    };
+    updateRetentionConfig(config: Partial<MetricsRetentionConfig>): void;
+    destroy(): void;
+}
+export declare function getAgentMetricsSystem(stateManager?: XrayStateManager): AgentMetricsSystem;
+export declare function initializeAgentMetrics(stateManager: XrayStateManager): AgentMetricsSystem;
+export declare function resetAgentMetricsSystem(): void;

package/dist/metrics/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Metrics Module
+ *
+ * Re-exports all metrics-related functionality from the Agent Metrics System.
+ */
+export { AgentMetricsSystem, getAgentMetricsSystem, initializeAgentMetrics, resetAgentMetricsSystem, type AgentInvocation, type AgentType, type ComplexityLevel, type AgentInvocationSummary, type TimePeriodSummary, type ComplexitySummary, type AggregatedAgentMetrics, type MetricsRetentionConfig, type MetricsExport, type AgentMetricsFilter, } from "./agent-metrics.js";

package/dist/monitoring/advanced-profiler.d.ts

@@ -0,0 +1,51 @@
+import { EventEmitter } from "events";
+interface ProfileData {
+    agentName: string;
+    operation: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    memoryUsage: {
+        before: NodeJS.MemoryUsage;
+        after?: NodeJS.MemoryUsage;
+    };
+    success: boolean;
+    error?: string;
+    metadata: Record<string, any>;
+}
+interface ProfilingMetrics {
+    totalOperations: number;
+    successfulOperations: number;
+    failedOperations: number;
+    averageDuration: number;
+    memoryDelta: number;
+    slowestOperation: string;
+    fastestOperation: string;
+}
+export declare class AdvancedProfiler extends EventEmitter {
+    private profiles;
+    private activeProfiles;
+    private profilingEnabled;
+    private profileStoragePath;
+    private reportTimer?;
+    private cleanupTimer?;
+    private isRunning;
+    constructor(storagePath?: string | undefined);
+    start(): void;
+    stop(): void;
+    private ensureStorageDirectory;
+    startProfiling(operationId: string, agentName: string, operation: string, metadata?: Record<string, any>): void;
+    endProfiling(operationId: string, success?: boolean, error?: string): void;
+    private detectAnomalies;
+    private calculateMemoryDelta;
+    getMetrics(agentName?: string): ProfilingMetrics;
+    private generatePerformanceReport;
+    private generateRecommendations;
+    private cleanupOldProfiles;
+    enableProfiling(): void;
+    disableProfiling(): void;
+    clearProfiles(): void;
+    exportProfiles(): Record<string, ProfileData[]>;
+}
+export declare const advancedProfiler: AdvancedProfiler;
+export {};

package/dist/monitoring/memory-monitor.d.ts

@@ -0,0 +1,113 @@
+import { EventEmitter } from "events";
+export interface MemoryStats {
+    heapUsed: number;
+    heapTotal: number;
+    external: number;
+    rss: number;
+    timestamp: number;
+    sessionId?: string;
+}
+export interface MemoryLeakAlert {
+    type: "leak_detected" | "high_usage" | "spike_detected";
+    severity: "low" | "medium" | "high" | "critical";
+    message: string;
+    details: {
+        currentUsage: number;
+        threshold: number;
+        trend: "increasing" | "stable" | "decreasing";
+        recommendations: string[];
+    };
+}
+export interface MemoryMonitorConfig {
+    checkInterval: number;
+    alertThresholds: {
+        warning: number;
+        critical: number;
+        leakDetection: {
+            growthRate: number;
+            sustainedPeriod: number;
+        };
+    };
+    enableFrameworkLogging: boolean;
+    sessionTracking: boolean;
+}
+export interface MemorySummary {
+    current: MemoryStats;
+    peak: MemoryStats;
+    average: number;
+    trend: "increasing" | "stable" | "decreasing";
+}
+export declare class MemoryMonitor extends EventEmitter {
+    private config;
+    private monitoringInterval;
+    private statsHistory;
+    private maxHistorySize;
+    private leakDetectionEnabled;
+    private lastLeakCheck;
+    private leakCheckInterval;
+    private listenersInitialized;
+    constructor(config?: Partial<MemoryMonitorConfig>);
+    /**
+     * Start memory monitoring
+     */
+    start(): void;
+    /**
+     * Stop memory monitoring
+     */
+    stop(): void;
+    /**
+     * Get current memory statistics
+     */
+    getCurrentStats(): MemoryStats;
+    /**
+     * Check memory usage and detect issues
+     */
+    private checkMemory;
+    /**
+     * Check memory usage against thresholds
+     */
+    private checkThresholds;
+    /**
+     * Detect potential memory leaks
+     */
+    private detectMemoryLeaks;
+    /**
+     * Calculate memory usage trend
+     */
+    private calculateTrend;
+    /**
+     * Emit memory alert
+     */
+    private emitAlert;
+    /**
+     * Log memory stats to framework log
+     */
+    private logFrameworkMemory;
+    /**
+     * Get memory usage history
+     */
+    getHistory(hours?: number): MemoryStats[];
+    /**
+     * Get memory usage summary
+     */
+    getSummary(): MemorySummary;
+    /**
+     * Force garbage collection (if available)
+     */
+    forceGC(): boolean;
+    /**
+     * Internal logging method - writes to framework log only
+     */
+    private log;
+    /**
+     * Safely add an alert listener, preventing duplicates
+     */
+    addAlertListener(callback: (alert: MemoryLeakAlert) => void): void;
+}
+export declare const memoryMonitor: MemoryMonitor;
+export declare function getMemoryUsage(): MemoryStats;
+export declare function logMemoryUsage(): MemoryStats;
+export declare function checkMemoryHealth(): {
+    healthy: boolean;
+    issues: string[];
+};