0xray 3.4.2 → 3.4.3

package/dist/session/session-state-manager.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Session State Manager
+ *
+ * Manages cross-session state sharing, dependency tracking,
+ * and coordination for complex workflows.
+ *
+ * @since 2026-01-07
+ */
+import { XrayStateManager } from "../state/state-manager.js";
+import { SessionCoordinator } from "../delegation/session-coordinator.js";
+export interface SessionDependency {
+    sessionId: string;
+    dependsOn: string[];
+    dependedBy: string[];
+    state: "pending" | "active" | "completed" | "failed";
+    priority: number;
+    metadata: Record<string, unknown>;
+}
+export interface SessionGroup {
+    groupId: string;
+    sessionIds: string[];
+    coordinatorSession: string;
+    state: "forming" | "active" | "completing" | "completed" | "failed";
+    sharedState: Map<string, {
+        value: unknown;
+        fromSessionId: string;
+        timestamp: number;
+    }>;
+    createdAt: number;
+    completedAt?: number;
+}
+export interface MigrationPlan {
+    sessionId: string;
+    targetCoordinator: string;
+    stateTransfer: Map<string, unknown>;
+    migrationSteps: string[];
+    rollbackSteps: string[];
+}
+export interface FailoverConfig {
+    sessionId: string;
+    backupCoordinators: string[];
+    failoverThreshold: number;
+    autoFailover: boolean;
+}
+export declare class SessionStateManager {
+    private stateManager;
+    private sessionCoordinator;
+    private dependencies;
+    private sessionGroups;
+    private failoverConfigs;
+    constructor(stateManager: XrayStateManager, sessionCoordinator: SessionCoordinator);
+    /**
+     * Share state between sessions
+     */
+    shareState(fromSessionId: string, toSessionId: string, key: string, value: unknown): boolean;
+    /**
+     * Broadcast state to multiple sessions
+     */
+    broadcastState(fromSessionId: string, targetSessionIds: string[], key: string, value: unknown): number;
+    /**
+     * Register session dependency
+     */
+    registerDependency(sessionId: string, dependsOn: string[], metadata?: Record<string, unknown>): void;
+    /**
+     * Update dependency state
+     */
+    updateDependencyState(sessionId: string, state: SessionDependency["state"]): void;
+    /**
+     * Get dependency chain for a session
+     */
+    getDependencyChain(sessionId: string): {
+        dependencies: string[];
+        dependents: string[];
+        canStart: boolean;
+    };
+    /**
+     * Create session group for complex workflows
+     */
+    createSessionGroup(groupId: string, sessionIds: string[], coordinatorSession: string): SessionGroup;
+    /**
+     * Update session group state
+     */
+    updateSessionGroupState(groupId: string, state: SessionGroup["state"]): void;
+    /**
+     * Share state within a session group
+     */
+    shareGroupState(groupId: string, key: string, value: unknown, fromSessionId: string): boolean;
+    /**
+     * Get session group state
+     */
+    getGroupState(groupId: string, key: string): unknown;
+    /**
+     * Plan session migration
+     */
+    planMigration(sessionId: string, targetCoordinator: string): MigrationPlan;
+    /**
+     * Validate migration plan before execution
+     */
+    validateMigrationPlan(plan: MigrationPlan): Promise<{
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    }>;
+    /**
+     * Validate rollback capability for a migration plan
+     */
+    validateRollbackCapability(plan: MigrationPlan): {
+        canRollback: boolean;
+        reason?: string;
+    };
+    /**
+     * Find orphaned agents in dependency graph
+     */
+    findOrphanedAgents(allAgents: string[], dependencies: Record<string, string[]>): string[];
+    /**
+     * Execute session migration
+     */
+    executeMigration(plan: MigrationPlan): Promise<boolean>;
+    /**
+     * Configure failover for a session
+     */
+    configureFailover(sessionId: string, backupCoordinators: string[], failoverThreshold: number, autoFailover: boolean): void;
+    /**
+     * Execute failover for a session
+     */
+    executeFailover(sessionId: string): Promise<boolean>;
+    /**
+     * Get coordination statistics
+     */
+    getCoordinationStats(): {
+        totalDependencies: number;
+        activeDependencies: number;
+        totalGroups: number;
+        activeGroups: number;
+        failoverConfigs: number;
+    };
+    private propagateDependencyUpdate;
+    private rollbackMigration;
+    private persistDependencies;
+    private persistSessionGroups;
+    private persistFailoverConfigs;
+    shutdown(): void;
+}
+export declare const createSessionStateManager: (stateManager: XrayStateManager, sessionCoordinator: SessionCoordinator) => SessionStateManager;

package/dist/skills/xray-orchestrator/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * xray Orchestrator Skill
+ *
+ * OpenClaw skill that provides xray orchestration commands.
+ *
+ * @since 2026-03-14
+ */
+export declare function handleSkill(input: string): Promise<string>;
+declare const _default: {
+    handleSkill: typeof handleSkill;
+};
+export default _default;

package/dist/state/context-providers.d.ts

@@ -0,0 +1,4 @@
+export interface ContextProviders {
+    createProvider: <T>(value: T) => unknown;
+    useContext: <T>() => T;
+}

package/dist/state/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./state-manager.js";
+export * from "./context-providers.js";
+export * from "./state-types.js";
+export { XrayStateManager } from "./state-manager.js";

package/dist/state/state-manager.d.ts

@@ -0,0 +1,41 @@
+export interface StateManager {
+    get: <T>(key: string) => T | undefined;
+    set: <T>(key: string, value: T) => void;
+    clear: (key: string) => void;
+}
+export declare class XrayStateManager implements StateManager {
+    private store;
+    private persistencePath;
+    private persistenceEnabled;
+    private writeQueue;
+    private initialized;
+    private earlyOperationsQueue;
+    static readonly VERSION = "1.5.2";
+    constructor(persistencePath?: string | undefined, persistenceEnabled?: boolean);
+    private initializePersistence;
+    private persistToDisk;
+    private isSerializable;
+    private schedulePersistence;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    clear(key: string): void;
+    clearAll(): void;
+    isPersistenceEnabled(): boolean;
+    getPersistenceStats(): {
+        enabled: boolean;
+        initialized: boolean;
+        keysInMemory: number;
+        pendingWrites: number;
+    };
+    getStateVersion(): string;
+    getAuditLog(): Array<{
+        timestamp: Date;
+        operation: string;
+        key: string;
+    }>;
+    resolveConflict(conflict: {
+        key: string;
+        value1: unknown;
+        value2: unknown;
+    }): unknown;
+}

package/dist/state/state-types.d.ts

@@ -0,0 +1,5 @@
+export type StateValue = string | number | boolean | object | null;
+export interface StateTypes {
+    value: StateValue;
+    timestamp: number;
+}

package/dist/testing/memory-regression-suite.d.ts

@@ -0,0 +1,105 @@
+import { EventEmitter } from "events";
+/**
+ * Memory Regression Testing Suite
+ * Automated testing for memory usage patterns and leak detection
+ */
+export interface MemoryRegressionTest {
+    name: string;
+    description: string;
+    setup?: (() => Promise<void> | void) | undefined;
+    execute: () => Promise<any> | any;
+    cleanup?: (() => Promise<void> | void) | undefined;
+    expectedMemoryDelta: {
+        maxIncrease: number;
+        acceptableLeak: number;
+    };
+}
+export interface MemoryRegressionResult {
+    testName: string;
+    passed: boolean;
+    memoryDelta: number;
+    leakRate: number;
+    duration: number;
+    error?: string;
+    recommendations: string[];
+}
+export interface RegressionSuiteConfig {
+    testTimeout: number;
+    memorySamplingInterval: number;
+    acceptableMemoryGrowth: number;
+    leakDetectionThreshold: number;
+}
+export declare class MemoryRegressionTester extends EventEmitter {
+    private config;
+    private tests;
+    constructor(config?: Partial<RegressionSuiteConfig>);
+    /**
+     * Add a regression test
+     */
+    addTest(test: MemoryRegressionTest): void;
+    /**
+     * Run all regression tests
+     */
+    runAllTests(): Promise<MemoryRegressionResult[]>;
+    /**
+     * Run a single regression test
+     */
+    private runTest;
+    /**
+     * Create a standard memory regression test
+     */
+    createStandardTest(name: string, description: string, testFunction: () => Promise<any> | any, options?: {
+        maxMemoryIncrease?: number;
+        acceptableLeakRate?: number;
+        setup?: () => Promise<void> | void;
+        cleanup?: () => Promise<void> | void;
+    }): MemoryRegressionTest;
+    /**
+     * Generate test report
+     */
+    generateReport(results: MemoryRegressionResult[]): string;
+    /**
+     * Calculate variance of memory samples
+     */
+    private calculateVariance;
+}
+export declare const memoryTestTemplates: {
+    sessionOperations: (sessionCount?: number) => {
+        name: string;
+        description: string;
+        setup: () => Promise<void>;
+        execute: () => Promise<{
+            id: string;
+            data: {
+                userId: number;
+                metadata: {
+                    created: number;
+                    active: boolean;
+                };
+            };
+        }[]>;
+        cleanup: () => Promise<void>;
+        expectedMemoryDelta: {
+            maxIncrease: number;
+            acceptableLeak: number;
+        };
+    };
+    cacheOperations: (cacheSize?: number) => {
+        name: string;
+        description: string;
+        execute: () => Promise<number>;
+        expectedMemoryDelta: {
+            maxIncrease: number;
+            acceptableLeak: number;
+        };
+    };
+    streamingOperations: (messageCount?: number) => {
+        name: string;
+        description: string;
+        execute: () => Promise<number>;
+        expectedMemoryDelta: {
+            maxIncrease: number;
+            acceptableLeak: number;
+        };
+    };
+};

package/dist/tools/assess-complexity-tool.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Assess Complexity Tool
+ *
+ * Wraps ComplexityAnalyzer so the main AI can query task complexity
+ * and decide whether to delegate to subagents.
+ *
+ * Exposes:
+ *  - assessComplexity() — full analysis returning score, level, strategy, agents
+ *  - simple assess() helper for quick threshold checks
+ */
+export interface AssessmentInput {
+    taskDescription: string;
+    files?: string[];
+    dependencies?: string[];
+    changeVolume?: number;
+    riskLevel?: "low" | "medium" | "high" | "critical";
+    estimatedDuration?: number;
+}
+export interface AssessmentResult {
+    score: number;
+    level: "simple" | "moderate" | "complex" | "enterprise";
+    strategy: "single-agent" | "multi-agent" | "orchestrator-led";
+    estimatedAgents: number;
+    reasoning: string[];
+}
+export declare function assessComplexity(input: AssessmentInput): AssessmentResult;
+export declare function shouldDelegate(input: AssessmentInput): boolean;
+export declare function getDelegationStrategy(input: AssessmentInput): AssessmentResult;

package/dist/tools/query-routing-tool.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Query Routing Tool
+ *
+ * Lets the main AI discover which agent/skill best matches a task.
+ * Combines ROUTING_MAPPINGS keyword lookup with AGENT_REGISTRY metadata.
+ */
+export interface AgentRoutingDetail {
+    agent: string;
+    skill: string;
+    confidence: number;
+    matchedKeywords: string[];
+    description: string | undefined;
+    capabilities: string[];
+    expertise: string | undefined;
+}
+export declare function queryRouting(keywords: string[]): AgentRoutingDetail[];
+export declare function listAllRoutes(): AgentRoutingDetail[];

package/dist/types/metamorphosis.d.ts

@@ -0,0 +1,21 @@
+/**
+ * MetamorphosisEngine interface — lifecycle hooks for self-evolution proposals.
+ *
+ * Extracted from postprocessor/metamorphosis/ for neutral access by kernel.
+ */
+export interface MetamorphosisProposal {
+    id: string;
+    type: 'add' | 'modify' | 'remove';
+    target: string;
+    description: string;
+    rationale: string;
+    impact: 'low' | 'medium' | 'high';
+}
+export interface MetamorphosisEngine {
+    /** Human-readable engine name (for logging) */
+    name: string;
+    /** Called when PostProcessor enters a phase */
+    onPhase?(phase: string, context: unknown): Promise<void>;
+    /** Called when a metamorphosis proposal is generated */
+    onProposal?(proposal: MetamorphosisProposal): Promise<void>;
+}

package/dist/utils/batch-operations.d.ts

@@ -0,0 +1,25 @@
+export interface ReplacementOperation {
+    pattern: string;
+    replacement: string;
+    isRegex?: boolean;
+    caseSensitive?: boolean;
+}
+export interface BatchResult {
+    success: boolean;
+    filesModified: number;
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+    duration: number;
+}
+export interface FileOperation {
+    filePath: string;
+    operation: "replace" | "append" | "prepend" | "delete";
+    content?: string;
+    pattern?: string;
+}
+export declare function batchReplace(files: string[], operations: ReplacementOperation[]): Promise<BatchResult>;
+export declare function batchFileOperations(operations: FileOperation[]): Promise<BatchResult>;
+export declare function findFilesWithPattern(directory: string, pattern: string, extensions?: string[]): string[];
+export declare function bulkRename(directory: string, oldName: string, newName: string, extensions?: string[]): Promise<BatchResult>;

package/dist/utils/codex-parser.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 0xRay Codex Parser Utility
+ *
+ * Unified parsing utility for codex content in both JSON and Markdown formats.
+ * Provides consistent parsing across all components with format detection and validation.
+ *
+ * @since 2026-01-07
+ */
+import { CodexContext } from "../core/context-loader.js";
+/**
+ * Content format detection result
+ */
+export interface FormatDetectionResult {
+    format: "json" | "markdown" | "unknown";
+    confidence: number;
+}
+/**
+ * Parsing result
+ */
+export interface ParsingResult {
+    success: boolean;
+    context?: CodexContext;
+    error?: string;
+    warnings: string[];
+}
+/**
+ * Detect content format
+ */
+export declare function detectContentFormat(content: string): FormatDetectionResult;
+/**
+ * Unified codex content parser
+ */
+export declare function parseCodexContent(content: string, sourcePath?: string): ParsingResult;
+/**
+ * Extract codex metadata from content (for compatibility with existing code)
+ */
+export declare function extractCodexMetadata(content: string): {
+    version: string;
+    termCount: number;
+};
+/**
+ * Pre-modification validation result
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Validate TypeScript code syntax
+ */
+export declare function validateTypeScriptSyntax(code: string, filePath?: string): Promise<ValidationResult>;
+/**
+ * Validate JSON syntax
+ */
+export declare function validateJsonSyntax(jsonString: string): ValidationResult;
+/**
+ * Comprehensive pre-modification validation
+ */
+export declare function validateBeforeModification(content: string, filePath: string): Promise<ValidationResult>;

package/dist/utils/command-runner.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Simple command runner utility for executing shell commands
+ */
+export interface CommandResult {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface CommandOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeout?: number;
+    silent?: boolean;
+}
+/**
+ * Run a shell command and return the result
+ */
+export declare function runCommand(command: string, options?: CommandOptions): Promise<CommandResult>;
+/**
+ * Run a command and throw on failure
+ */
+export declare function runCommandStrict(command: string, options?: CommandOptions): Promise<string>;
+/**
+ * Run a command safely using spawn with an args array (no shell interpretation).
+ * This prevents command injection when args may contain user-controlled input.
+ */
+export declare function runCommandSafe(command: string, args: string[], options?: CommandOptions): Promise<CommandResult>;
+/**
+ * Run a safe command and throw on failure
+ */
+export declare function runCommandSafeStrict(command: string, args: string[], options?: CommandOptions): Promise<string>;

package/dist/utils/import-resolver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Import Resolver Utility
+ * Dynamically resolves module imports across different environments
+ *
+ * This solves the systemic path resolution issue where hardcoded paths
+ * break between development, built, and deployed environments.
+ */
+export declare class ImportResolver {
+    private static instance;
+    private currentDir;
+    private projectRoot;
+    private isDevelopment;
+    private isBuilt;
+    private isInstalled;
+    private isTesting;
+    private constructor();
+    static getInstance(): ImportResolver;
+    private getCurrentDirectory;
+    private findProjectRoot;
+    private fileExists;
+    private detectDevelopment;
+    private detectBuilt;
+    private detectInstalled;
+    private detectTesting;
+    /**
+     * Resolve module import path for any module
+     */
+    resolveModulePath(moduleName: string, subPath?: string): string;
+    /**
+     * Resolve agent import path (special case for agents)
+     */
+    resolveAgentPath(agentName: string): string;
+    /**
+     * Dynamic import with comprehensive environment resolution
+     */
+    importModule(moduleName: string, subPath?: string): Promise<any>;
+    /**
+     * Generate alternative import paths for fallback
+     */
+    private generateAlternativePaths;
+    /**
+     * Get comprehensive environment information
+     */
+    getEnvironmentInfo(): {
+        currentDir: string;
+        projectRoot: string;
+        isDevelopment: boolean;
+        isBuilt: boolean;
+        isInstalled: boolean;
+        isTesting: boolean;
+        nodeEnv: string | undefined;
+    };
+}
+export declare const importResolver: ImportResolver;

package/dist/utils/language-detector.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Language Detector Utility
+ *
+ * Detects project language and test framework from project files.
+ * Supports: TypeScript, JavaScript, Python, Go, Rust, Java, C++, Ruby, PHP
+ *
+ * @since 2026-02-25
+ */
+export interface ProjectLanguage {
+    language: string;
+    testFramework: string;
+    testCommand: string;
+    testFilePattern: string;
+    configFiles: string[];
+}
+export interface LanguageConfig {
+    language: string;
+    extensions: string[];
+    testFrameworks: {
+        name: string;
+        patterns: string[];
+        testCommands: string[];
+        configFiles: string[];
+    }[];
+}
+export declare const LANGUAGE_CONFIGS: LanguageConfig[];
+/**
+ * Detect the project language from directory contents
+ */
+export declare function detectProjectLanguage(cwd: string): ProjectLanguage | null;
+/**
+ * Get the test file path for a given source file
+ */
+export declare function getTestFilePath(sourceFilePath: string, projectLanguage: ProjectLanguage): string;
+/**
+ * Build the test command for running specific tests
+ */
+export declare function buildTestCommand(projectLanguage: ProjectLanguage, testFilePath?: string): string;
+export declare const languageDetector: {
+    detect: typeof detectProjectLanguage;
+    getTestFilePath: typeof getTestFilePath;
+    buildTestCommand: typeof buildTestCommand;
+};

package/dist/utils/path-resolver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Path Resolution Utility for 0xRay Framework
+ * Resolves import paths that work across development, build, and installed environments
+ */
+export declare class PathResolver {
+    private static instance;
+    private currentDir;
+    private isDevelopment;
+    private isBuilt;
+    private isInstalled;
+    private constructor();
+    static getInstance(): PathResolver;
+    /**
+     * Get current working directory
+     */
+    private getCurrentDirectory;
+    /**
+     * Detect if we're running in development environment (src/ directory)
+     */
+    private detectDevelopment;
+    /**
+     * Detect if we're running in built environment (dist/ directory)
+     */
+    private detectBuilt;
+    /**
+     * Detect if we're running in installed package environment
+     */
+    private detectInstalled;
+    /**
+     * Resolve agent import path for current environment
+     */
+    resolveAgentPath(agentName: string): string;
+    /**
+     * Resolve any module path for current environment
+     */
+    resolveModulePath(modulePath: string): string;
+    /**
+     * Get environment information for debugging
+     */
+    getEnvironmentInfo(): {
+        currentDir: string;
+        isDevelopment: boolean;
+        isBuilt: boolean;
+        isInstalled: boolean;
+        nodeEnv: string | undefined;
+    };
+}
+export declare const pathResolver: PathResolver;

package/dist/utils/shutdown-handler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Graceful Shutdown Handler
+ *
+ * Centralized shutdown handling for MCP servers.
+ * Extracts common shutdown patterns to reduce code duplication.
+ *
+ * @since 2026-03-22
+ */
+export interface ShutdownOptions {
+    serverName: string;
+    server: {
+        close: () => Promise<void>;
+    } | null;
+    shutdownTimeout?: number;
+}
+export interface ShutdownHandler {
+    cleanup: (signal: string) => Promise<void>;
+    stop: () => void;
+}
+/**
+ * Creates a graceful shutdown handler for MCP servers
+ *
+ * @param options - Configuration for the shutdown handler
+ * @returns ShutdownHandler with cleanup and stop methods
+ */
+export declare function createGracefulShutdown(options: ShutdownOptions): ShutdownHandler;