0xray 3.4.1 → 3.4.3

package/dist/mcps/tools/tool-cache.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Tool Cache
+ *
+ * Caches discovered tools to reduce network round-trips.
+ * Part of Phase 4 refactoring - Tool Layer extraction.
+ */
+import { MCPTool } from '../types/index.js';
+export interface ToolCacheOptions {
+    ttlMs?: number;
+    maxEntries?: number;
+}
+export declare class ToolCache {
+    private cache;
+    private readonly ttlMs;
+    private readonly maxEntries;
+    private accessOrder;
+    constructor(options?: ToolCacheOptions);
+    /**
+     * Get cached tools for a server
+     */
+    get(serverName: string): MCPTool[] | null;
+    /**
+     * Cache tools for a server
+     */
+    set(serverName: string, tools: MCPTool[]): void;
+    /**
+     * Clear all cached entries
+     */
+    clear(): void;
+    /**
+     * Remove cached tools for a specific server
+     */
+    invalidate(serverName: string): boolean;
+    /**
+     * Check if tools are cached for a server
+     */
+    has(serverName: string): boolean;
+    /**
+     * Get all cached server names
+     */
+    getCachedServers(): string[];
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxEntries: number;
+        ttlMs: number;
+    };
+    private updateAccessOrder;
+    private removeFromAccessOrder;
+    private evictOldest;
+}

package/dist/mcps/tools/tool-discovery.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tool Discovery
+ *
+ * Handles dynamic tool discovery from MCP servers via JSON-RPC protocol.
+ * Part of Phase 4 refactoring - Tool Layer extraction.
+ */
+import { MCPTool, IMcpConnection } from '../types/index.js';
+import { JsonRpcRequest, JsonRpcResponse } from '../types/index.js';
+export declare class ToolDiscovery {
+    /**
+     * Discover available tools from an MCP server connection
+     */
+    discoverTools(connection: IMcpConnection): Promise<MCPTool[]>;
+    /**
+     * Build a tool list request for JSON-RPC
+     */
+    buildToolListRequest(requestId?: number): JsonRpcRequest;
+    /**
+     * Parse tools from a JSON-RPC response
+     */
+    parseTools(response: JsonRpcResponse): MCPTool[];
+    /**
+     * Validate that discovered tools have required fields
+     */
+    validateTools(tools: unknown[]): MCPTool[];
+    private isValidTool;
+}

package/dist/mcps/tools/tool-executor.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Tool Executor
+ *
+ * Handles tool execution via JSON-RPC protocol.
+ * Part of Phase 4 refactoring - Tool Layer extraction.
+ */
+import { MCPToolResult, IMcpConnection } from '../types/index.js';
+import { JsonRpcRequest, JsonRpcResponse } from '../types/index.js';
+export declare class ToolExecutor {
+    private requestId;
+    /**
+     * Execute a tool on an MCP server
+     */
+    executeTool(connection: IMcpConnection, toolName: string, args: unknown): Promise<MCPToolResult>;
+    /**
+     * Build a tool call request for JSON-RPC
+     */
+    buildToolCallRequest(toolName: string, args: unknown, requestId?: number): JsonRpcRequest;
+    /**
+     * Parse a tool result from JSON-RPC response
+     */
+    parseToolResult(response: JsonRpcResponse): MCPToolResult;
+    /**
+     * Execute multiple tools in sequence
+     */
+    executeTools(connection: IMcpConnection, executions: Array<{
+        toolName: string;
+        args: unknown;
+    }>): Promise<MCPToolResult[]>;
+    /**
+     * Execute multiple tools in parallel
+     */
+    executeToolsParallel(connection: IMcpConnection, executions: Array<{
+        toolName: string;
+        args: unknown;
+    }>): Promise<MCPToolResult[]>;
+    /**
+     * Reset the request ID counter
+     */
+    resetRequestId(): void;
+}

package/dist/mcps/tools/tool-registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tool Registry
+ *
+ * Manages tool registration and lookup across MCP servers.
+ * Part of Phase 4 refactoring - Tool Layer extraction.
+ */
+import { MCPTool, IToolRegistry } from '../types/index.js';
+export declare class ToolRegistry implements IToolRegistry {
+    private tools;
+    /**
+     * Register tools for a specific server
+     */
+    register(serverName: string, tools: MCPTool[]): void;
+    /**
+     * Get a specific tool by server and tool name
+     */
+    getTool(serverName: string, toolName: string): MCPTool | undefined;
+    /**
+     * Get all tools for a specific server
+     */
+    getTools(serverName: string): MCPTool[];
+    /**
+     * Check if a tool exists
+     */
+    hasTool(serverName: string, toolName: string): boolean;
+    /**
+     * Clear all registered tools
+     */
+    clear(): void;
+    /**
+     * Get all registered server names
+     */
+    getServerNames(): string[];
+    /**
+     * Remove all tools for a specific server
+     */
+    unregisterServer(serverName: string): boolean;
+    /**
+     * Get total tool count across all servers
+     */
+    getToolCount(): number;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * MCP Types Barrel Export
+ *
+ * Centralized export for all MCP-related types.
+ * Import from this file to access all MCP types.
+ *
+ * @example
+ * ```typescript
+ * import { MCPClientConfig, MCPTool, JsonRpcRequest } from './types/index.js';
+ * ```
+ */
+export * from './mcp.types.js';
+export * from './json-rpc.types.js';

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";