0xray 4.0.13 → 4.0.14

package/dist/memory-routing/null-provider.js

@@ -0,0 +1,63 @@
+const EMPTY_CONTEXT = {
+    providerId: 'null',
+    matchedSignals: [],
+    matchedTags: [],
+    flags: {},
+    synthesisAvailable: false,
+};
+export class NullMemoryRoutingProvider {
+    id = 'null';
+    name = 'Null (no memory routing)';
+    isAvailable() {
+        return true;
+    }
+    buildRoutingContext() {
+        return { ...EMPTY_CONTEXT };
+    }
+    enhanceAgentCapabilities(base) {
+        return new Map(base);
+    }
+    enrichTasks(tasks) {
+        return tasks;
+    }
+    buildInheritedContext() {
+        return { providerId: 'null', matchedSignals: [], flags: {} };
+    }
+    selectAgent(capabilities, requiredCapabilities, complexity) {
+        let bestAgent = null;
+        let bestScore = -1;
+        for (const [agent, caps] of capabilities) {
+            if (complexity > caps.complexityThreshold)
+                continue;
+            const matchCount = requiredCapabilities.filter((c) => caps.capabilities.includes(c)).length;
+            const score = matchCount * 10 + caps.concurrentTasks;
+            if (score > bestScore) {
+                bestScore = score;
+                bestAgent = agent;
+            }
+        }
+        return bestAgent;
+    }
+    resolveThinDispatch(baseAgent, _operation, complexityScore) {
+        return {
+            agent: baseAgent,
+            adjustedScore: complexityScore,
+            context: { ...EMPTY_CONTEXT },
+        };
+    }
+    getTaskConfidence() {
+        return {
+            signals: [],
+            matchedSignals: [],
+            avgConfidence: 0,
+            maxConfidence: 0,
+            highConfidenceTrapPresent: false,
+            ontologicalTrapDetected: false,
+            complexityBoost: 0,
+            recommendedAgent: null,
+        };
+    }
+}
+export function createMemoryRoutingProvider() {
+    return new NullMemoryRoutingProvider();
+}

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

@@ -0,0 +1,6 @@
+import type { MemoryRoutingConfig, MemoryRoutingProvider } from './types.js';
+export declare function isExplicitMemoryRoutingOptOut(config: MemoryRoutingConfig): boolean;
+/** Leftover shipped default: enabled false + provider null. Not an explicit opt-out. */
+export declare function isLeftoverMemoryRoutingOff(config: MemoryRoutingConfig): boolean;
+export declare function resolveLeftoverEnabledConfig(config: MemoryRoutingConfig, cwd: string): MemoryRoutingConfig | null;
+export declare function loadMemoryRoutingProvider(config: MemoryRoutingConfig, cwd?: string): Promise<MemoryRoutingProvider>;

package/dist/memory-routing/provider-loader.js

@@ -0,0 +1,165 @@
+import { existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { frameworkLogger } from '../core/framework-logger.js';
+import { createMemoryRoutingProvider as createNullProvider } from './null-provider.js';
+import { validateMemoryRoutingConfig } from './validate-config.js';
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function resolveUnavailableReason(provider) {
+    const statusProvider = provider;
+    if (typeof statusProvider.getAvailabilityStatus !== 'function') {
+        return null;
+    }
+    try {
+        return statusProvider.getAvailabilityStatus().reason ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+const REPERTOIRE_CANDIDATE_PATHS = [
+    'node_modules/@0xray/repertoire/dist/provider/memory-routing-provider.js',
+    'vendor/@0xray/repertoire/dist/provider/memory-routing-provider.js',
+    'node_modules/0xray/vendor/@0xray/repertoire/dist/provider/memory-routing-provider.js',
+    '../repertoire/dist/provider/memory-routing-provider.js',
+    '../../repertoire/dist/provider/memory-routing-provider.js',
+    '../../../repertoire/dist/provider/memory-routing-provider.js',
+];
+/**
+ * SECURITY: features.json is a trusted configuration boundary.
+ * module_path is resolved from disk and dynamically imported without signature
+ * verification. Only grant write access to features.json to trusted operators.
+ */
+function resolveModulePath(configuredPath, cwd) {
+    if (!configuredPath)
+        return null;
+    const candidates = [
+        resolve(cwd, configuredPath),
+        configuredPath,
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function defaultPathForProvider(provider, cwd) {
+    if (provider !== 'repertoire')
+        return null;
+    for (const rel of REPERTOIRE_CANDIDATE_PATHS) {
+        const abs = resolve(cwd, rel);
+        if (existsSync(abs))
+            return abs;
+    }
+    const nm = join(cwd, 'node_modules', '@0xray', 'repertoire', 'dist', 'provider', 'memory-routing-provider.js');
+    return existsSync(nm) ? nm : null;
+}
+export function isExplicitMemoryRoutingOptOut(config) {
+    return config.enabled === false && config.provider === 'repertoire';
+}
+/** Leftover shipped default: enabled false + provider null. Not an explicit opt-out. */
+export function isLeftoverMemoryRoutingOff(config) {
+    if (config.enabled === true)
+        return false;
+    if (isExplicitMemoryRoutingOptOut(config))
+        return false;
+    return config.provider === 'null' || !config.provider;
+}
+function leftoverRepertoireModulePath(cwd) {
+    const nm = join(cwd, 'node_modules', '@0xray', 'repertoire', 'dist', 'provider', 'memory-routing-provider.js');
+    if (existsSync(nm))
+        return nm;
+    const vendor = join(cwd, 'vendor', '@0xray', 'repertoire', 'dist', 'provider', 'memory-routing-provider.js');
+    if (existsSync(vendor))
+        return vendor;
+    const packedVendor = join(cwd, 'node_modules', '0xray', 'vendor', '@0xray', 'repertoire', 'dist', 'provider', 'memory-routing-provider.js');
+    if (existsSync(packedVendor))
+        return packedVendor;
+    const sibling = resolve(cwd, '../repertoire/dist/provider/memory-routing-provider.js');
+    if (existsSync(sibling))
+        return sibling;
+    return null;
+}
+export function resolveLeftoverEnabledConfig(config, cwd) {
+    if (!isLeftoverMemoryRoutingOff(config))
+        return null;
+    const modulePath = resolveModulePath(config.module_path, cwd) ?? leftoverRepertoireModulePath(cwd);
+    if (!modulePath)
+        return null;
+    const enabled = {
+        enabled: true,
+        provider: 'repertoire',
+        module_path: modulePath,
+    };
+    if (config.config)
+        enabled.config = config.config;
+    return enabled;
+}
+export async function loadMemoryRoutingProvider(config, cwd = process.cwd()) {
+    const validation = validateMemoryRoutingConfig(config);
+    if (!validation.valid) {
+        await frameworkLogger.log('memory-routing', 'config-invalid', 'error', { errors: validation.errors, provider: config.provider });
+        return createNullProvider();
+    }
+    const leftover = resolveLeftoverEnabledConfig(validation.normalized, cwd);
+    const effective = leftover ?? validation.normalized;
+    if (!effective.enabled || effective.provider === 'null') {
+        return createNullProvider();
+    }
+    const modulePath = resolveModulePath(effective.module_path, cwd) ??
+        defaultPathForProvider(effective.provider, cwd);
+    if (!modulePath) {
+        await frameworkLogger.log('memory-routing', 'provider-not-found', 'error', {
+            provider: effective.provider,
+            module_path: effective.module_path,
+            message: `Provider "${effective.provider}" is configured but module_path could not be resolved. Falling back to null provider.`,
+        });
+        return createNullProvider();
+    }
+    try {
+        const mod = await import(pathToFileURL(modulePath).href);
+        const factory = mod.createMemoryRoutingProvider ??
+            mod.default?.createMemoryRoutingProvider;
+        if (typeof factory !== 'function') {
+            throw new Error(`Module ${modulePath} must export createMemoryRoutingProvider()`);
+        }
+        const provider = factory((effective.config ?? {}));
+        if (!provider?.id || typeof provider.isAvailable !== 'function') {
+            throw new Error(`Invalid memory routing provider from ${modulePath}`);
+        }
+        const availabilityReason = resolveUnavailableReason(provider);
+        if (!provider.isAvailable()) {
+            await frameworkLogger.log('memory-routing', 'provider-unavailable', 'error', {
+                providerId: provider.id,
+                modulePath,
+                unavailableReason: availabilityReason,
+                message: `Provider "${provider.id}" loaded but isAvailable() returned false (${availabilityReason ?? 'unknown'}). Falling back to null provider.`,
+            });
+            if (availabilityReason === 'empty_registry') {
+                await sleep(100);
+                if (provider.isAvailable()) {
+                    await frameworkLogger.log('memory-routing', 'provider-retry-ok', 'info', { providerId: provider.id, modulePath });
+                }
+                else {
+                    return createNullProvider();
+                }
+            }
+            else {
+                return createNullProvider();
+            }
+        }
+        await frameworkLogger.log('memory-routing', 'provider-loaded', 'info', { providerId: provider.id, name: provider.name, modulePath });
+        return provider;
+    }
+    catch (err) {
+        await frameworkLogger.log('memory-routing', 'provider-load-failed', 'error', {
+            modulePath,
+            error: err instanceof Error ? err.message : String(err),
+            cwd,
+            configDir: dirname(modulePath),
+        });
+        return createNullProvider();
+    }
+}

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/provider-registry.js

@@ -0,0 +1,41 @@
+import { featuresConfigLoader } from '../core/features-config.js';
+import { NullMemoryRoutingProvider } from './null-provider.js';
+import { loadMemoryRoutingProvider, resolveLeftoverEnabledConfig } from './provider-loader.js';
+import { validateMemoryRoutingConfig } from './validate-config.js';
+let cachedProvider = null;
+let loadPromise = null;
+const nullProviderSingleton = new NullMemoryRoutingProvider();
+export function getMemoryRoutingConfig() {
+    const raw = featuresConfigLoader.loadConfig().memory_routing;
+    const validation = validateMemoryRoutingConfig(raw ?? { enabled: false, provider: 'null' });
+    return (resolveLeftoverEnabledConfig(validation.normalized, process.cwd()) ??
+        validation.normalized);
+}
+export async function getMemoryRoutingProvider(forceReload = false) {
+    if (!forceReload && cachedProvider)
+        return cachedProvider;
+    if (!forceReload && loadPromise)
+        return loadPromise;
+    const config = getMemoryRoutingConfig();
+    loadPromise = loadMemoryRoutingProvider(config).then((provider) => {
+        cachedProvider = provider;
+        loadPromise = null;
+        return provider;
+    });
+    return loadPromise;
+}
+/** Synchronous accessor — returns shared null singleton until async load completes. */
+export function getMemoryRoutingProviderSync() {
+    return cachedProvider ?? nullProviderSingleton;
+}
+export function resetMemoryRoutingProvider() {
+    cachedProvider = null;
+    loadPromise = null;
+}
+/** Kick off background load at module init. */
+export function initializeMemoryRouting() {
+    const config = getMemoryRoutingConfig();
+    if (config.enabled) {
+        void getMemoryRoutingProvider();
+    }
+}

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

@@ -0,0 +1,111 @@
+/**
+ * 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;
+    buildSynthesisContext?(opts: {
+        projectRoot: string;
+        dueReason?: string | null;
+    }): Record<string, unknown> | null;
+    refreshMetaInference?(): Promise<{
+        refreshed: boolean;
+    }>;
+}
+export interface MemoryRoutingConfig {
+    enabled: boolean;
+    provider: 'null' | 'repertoire' | 'custom';
+    module_path?: string;
+    config?: MemoryRoutingProviderConfig;
+}

package/dist/memory-routing/types.js

@@ -0,0 +1,7 @@
+/**
+ * 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 {};

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/memory-routing/validate-config.js

@@ -0,0 +1,32 @@
+const VALID_PROVIDERS = new Set(['null', 'repertoire', 'custom']);
+export function validateMemoryRoutingConfig(raw) {
+    const errors = [];
+    const input = (raw ?? {});
+    const enabled = input.enabled === true;
+    const provider = typeof input.provider === 'string' ? input.provider : 'null';
+    if (!VALID_PROVIDERS.has(provider)) {
+        errors.push(`Invalid memory_routing.provider "${provider}". Must be one of: null, repertoire, custom.`);
+    }
+    if (enabled && provider !== 'null' && !input.module_path) {
+        errors.push(`memory_routing.provider "${provider}" requires module_path when enabled.`);
+    }
+    if (input.module_path !== undefined && typeof input.module_path !== 'string') {
+        errors.push('memory_routing.module_path must be a string.');
+    }
+    if (input.config !== undefined && (typeof input.config !== 'object' || input.config === null)) {
+        errors.push('memory_routing.config must be an object.');
+    }
+    const normalized = {
+        enabled,
+        provider: VALID_PROVIDERS.has(provider)
+            ? provider
+            : 'null',
+    };
+    if (typeof input.module_path === 'string') {
+        normalized.module_path = input.module_path;
+    }
+    if (input.config && typeof input.config === 'object') {
+        normalized.config = input.config;
+    }
+    return { valid: errors.length === 0, errors, normalized };
+}

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;