0xray 4.0.13 → 4.0.15

package/dist/skills/xray-orchestrator/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: xray-orchestrator
+description: |
+  Main orchestration skill for xray agents.
+  Provides commands to coordinate agent work and invoke xray APIs
+  through the local HTTP API server.
+metadata:
+  openclaw:
+    primaryEnv: XRAY_API_KEY
+    emoji: 🤖
+  author: xray
+  tags:
+    - ai
+    - orchestration
+    - agent
+user-invocable: true
+---
+
+# xray Orchestrator Commands
+
+## /xray
+
+Display xray status and available commands.
+
+**Usage:** `/xray`
+
+**Example:**
+```
+/xray
+```
+
+## /xray-status
+
+Get detailed status of xray integration including connection status.
+
+**Usage:** `/xray-status`
+
+**Example:**
+```
+/xray-status
+```
+
+## /xray-analyze
+
+Analyze code using xray code analysis capabilities.
+
+**Usage:** `/xray-analyze <file-path>`
+
+**Arguments:**
+- `file-path`: Path to file to analyze (required)
+
+**Example:**
+```
+/xray-analyze src/index.ts
+```
+
+## /xray-code
+
+Perform code review on a file.
+
+**Usage:** `/xray-code <file-path> [options]`
+
+**Arguments:**
+- `file-path`: Path to file to review (required)
+- `--fix`: Attempt to fix issues automatically (optional)
+
+**Example:**
+```
+/xray-code src/utils/helper.ts
+/xray-code src/utils/helper.ts --fix
+```
+
+## /xray-file
+
+Read file using xray file tools.
+
+**Usage:** `/xray-file <file-path> [line-start:line-end]`
+
+**Arguments:**
+- `file-path`: Path to file to read (required)
+- `line-start:line-end`: Line range to read (optional)
+
+**Example:**
+```
+/xray-file src/index.ts
+/xray-file src/index.ts 1:50
+```
+
+## /xray-exec
+
+Execute arbitrary xray command or script.
+
+**Usage:** `/xray-exec <command>`
+
+**Arguments:**
+- `command`: Command to execute (required)
+
+**Example:**
+```
+/xray-exec list files src/
+```
+
+## /xray-help
+
+Show this help message.
+
+**Usage:** `/xray-help [command]`
+
+**Arguments:**
+- `command`: Specific command to get help for (optional)
+
+**Example:**
+```
+/xray-help
+/xray-help xray-analyze
+```
+
+# Implementation Notes
+
+This skill acts as the main interface between OpenClaw channels and xray agents.
+It processes user commands and forwards them to the xray API server running on localhost:18431.
+
+## API Endpoints
+
+- `POST /api/agent/invoke` - Invoke xray agent
+- `GET /api/agent/status` - Get agent status
+- `GET /health` - Health check
+
+## Authentication
+
+The skill reads the `XRAY_API_KEY` environment variable for authentication.
+
+## Error Handling
+
+All errors are caught and formatted as user-friendly messages.
+Detailed error information is logged for debugging.
+
+# Dependencies
+
+- xray API server running on localhost:18431
+- XRAY_API_KEY environment variable

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/skills/xray-orchestrator/index.js

@@ -0,0 +1,223 @@
+/**
+ * xray Orchestrator Skill
+ *
+ * OpenClaw skill that provides xray orchestration commands.
+ *
+ * @since 2026-03-14
+ */
+const API_BASE = process.env.XRAY_API_URL || 'http://localhost:18431';
+const API_KEY = process.env.XRAY_API_KEY;
+function parseArgs(input) {
+    const parts = input.trim().split(/\s+/);
+    const command = parts[0] || '';
+    const args = {};
+    for (const part of parts.slice(1)) {
+        if (part.startsWith('--')) {
+            const key = part.slice(2);
+            args[key] = true;
+        }
+        else if (part.includes(':')) {
+            const colonIdx = part.indexOf(':');
+            const key = part.slice(0, colonIdx);
+            const value = part.slice(colonIdx + 1);
+            if (key && value)
+                args[key] = value;
+        }
+        else if (!args._) {
+            args._ = [];
+            args._.push(part);
+        }
+        else {
+            args._.push(part);
+        }
+    }
+    return { command, args };
+}
+async function callAPI(endpoint, data) {
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    if (API_KEY) {
+        headers['Authorization'] = `Bearer ${API_KEY}`;
+    }
+    const response = await fetch(`${API_BASE}${endpoint}`, {
+        method: data ? 'POST' : 'GET',
+        headers,
+        body: data ? JSON.stringify(data) : null,
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+        throw new Error(error.error || `HTTP ${response.status}`);
+    }
+    return response.json();
+}
+export async function handleSkill(input) {
+    const { command, args } = parseArgs(input);
+    try {
+        switch (command.toLowerCase()) {
+            // xray primary
+            case 'xray':
+            case 'xray-status':
+                return await handleStatus();
+            case 'xray-analyze':
+                return await handleAnalyze(args);
+            case 'xray-code':
+                return await handleCodeReview(args);
+            case 'xray-file':
+                return await handleFileRead(args);
+            case 'xray-exec':
+                return await handleExec(args);
+            case 'xray-help':
+                return handleHelp(args._);
+            default:
+                return formatHelp();
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return `❌ Error: ${message}`;
+    }
+}
+async function handleStatus() {
+    const health = await callAPI('/health');
+    return `🤖 xray Status
+
+• Status: ${health.status}
+• Version: ${health.version}
+• Uptime: ${formatUptime(health.uptime)}
+
+Use /xray-help for available commands.`;
+}
+async function handleAnalyze(args) {
+    const filePath = args._?.[0];
+    if (!filePath) {
+        return '❌ Usage: /xray-analyze <file-path>';
+    }
+    const result = await callAPI('/api/agent/invoke', {
+        command: 'analyze',
+        args: { filePath },
+    });
+    if (!result.success) {
+        return `❌ Analysis failed: ${result.error}`;
+    }
+    return `✅ Analysis complete for ${filePath}\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+async function handleCodeReview(args) {
+    const filePath = args._?.[0];
+    const fix = args.fix === true;
+    if (!filePath) {
+        return '❌ Usage: /xray-code <file-path> [--fix]';
+    }
+    const result = await callAPI('/api/agent/invoke', {
+        command: 'code-review',
+        args: { filePath, fix },
+    });
+    if (!result.success) {
+        return `❌ Code review failed: ${result.error}`;
+    }
+    return `✅ Code review complete for ${filePath}\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+async function handleFileRead(args) {
+    const rest = args._;
+    const filePath = rest?.[0];
+    const range = rest?.[1];
+    if (!filePath) {
+        return '❌ Usage: /xray-file <file-path> [line-start:line-end]';
+    }
+    let lineRange;
+    if (range?.includes(':')) {
+        const [rawStart, rawEnd] = range.split(':');
+        lineRange = {};
+        if (rawStart)
+            lineRange.start = Number(rawStart);
+        if (rawEnd)
+            lineRange.end = Number(rawEnd);
+    }
+    const result = await callAPI('/api/agent/invoke', {
+        command: 'read',
+        args: { filePath, ...lineRange },
+    });
+    if (!result.success) {
+        return `❌ File read failed: ${result.error}`;
+    }
+    return `📄 ${filePath}\n\`\`\`\n${result.result}\n\`\`\``;
+}
+async function handleExec(args) {
+    const command = args._?.[0];
+    if (!command) {
+        return '❌ Usage: /xray-exec <command>';
+    }
+    const result = await callAPI('/api/agent/invoke', {
+        command: 'exec',
+        args: { command },
+    });
+    if (!result.success) {
+        return `❌ Execution failed: ${result.error}`;
+    }
+    return `✅ Command executed\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+function handleHelp(command) {
+    if (command) {
+        switch (command) {
+            case 'xray-analyze':
+                return `📖 /xray-analyze <file-path>
+
+Analyze code in a file.
+
+Example: /xray-analyze src/index.ts`;
+            case 'xray-code':
+                return `📖 /xray-code <file-path> [--fix]
+
+Perform code review on a file.
+Use --fix to attempt automatic fixes.
+
+Example: /xray-code src/utils/helper.ts
+Example: /xray-code src/utils/helper.ts --fix`;
+            case 'xray-file':
+                return `📖 /xray-file <file-path> [line-start:line-end]
+
+Read a file.
+Optionally specify line range.
+
+Example: /xray-file src/index.ts
+Example: /xray-file src/index.ts 1:50`;
+            case 'xray-exec':
+                return `📖 /xray-exec <command>
+
+Execute an arbitrary command.
+
+Example: /xray-exec list files src/`;
+            default:
+                return `Unknown command: ${command}`;
+        }
+    }
+    return formatHelp();
+}
+function formatHelp() {
+    return `🤖 xray Orchestrator
+
+Available Commands:
+• /xray - Show status
+• /xray-analyze <file> - Analyze code
+• /xray-code <file> [--fix] - Code review
+• /xray-file <file> [lines] - Read file
+• /xray-exec <command> - Execute command
+• /xray-help [command] - Show help
+
+Use /xray-help <command> for detailed usage.`;
+}
+function formatUptime(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0)
+        return `${days}d ${hours % 24}h`;
+    if (hours > 0)
+        return `${hours}h ${minutes % 60}m`;
+    if (minutes > 0)
+        return `${minutes}m`;
+    return `${seconds}s`;
+}
+// Export for OpenClaw
+export default { handleSkill };

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/context-providers.js

@@ -0,0 +1 @@
+export {};

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/index.js

@@ -0,0 +1,7 @@
+// 0xRay Framework State Management
+// Export all state management utilities and providers
+export * from "./state-manager.js";
+export * from "./context-providers.js";
+export * from "./state-types.js";
+// Re-export commonly used state utilities
+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-manager.js

@@ -0,0 +1,207 @@
+import { frameworkLogger } from "../core/framework-logger.js";
+import { resolveStateFilePath } from "../core/config-paths.js";
+export class XrayStateManager {
+    store = new Map();
+    persistencePath;
+    persistenceEnabled;
+    writeQueue = new Map();
+    initialized = false;
+    earlyOperationsQueue = []; // Queue keys that need persistence after init
+    static VERSION = "1.5.2";
+    constructor(persistencePath = undefined, persistenceEnabled = true) {
+        if (!persistencePath) {
+            persistencePath = resolveStateFilePath();
+        }
+        this.persistencePath = persistencePath;
+        this.persistenceEnabled = persistenceEnabled;
+        this.initializePersistence();
+    }
+    async initializePersistence() {
+        if (!this.persistenceEnabled) {
+            this.initialized = true;
+            return;
+        }
+        try {
+            const fs = await import("fs");
+            const path = await import("path");
+            // Ensure persistence directory exists
+            const dir = path.dirname(this.persistencePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            // Handle case where persistencePath exists but is a file instead of expected location
+            if (fs.existsSync(this.persistencePath)) {
+                const stats = fs.statSync(this.persistencePath);
+                if (stats.isFile()) {
+                    // If it's a file blocking our path, remove it (it's likely old state)
+                    fs.unlinkSync(this.persistencePath);
+                }
+                else if (!stats.isFile()) {
+                    // If it's not a file (e.g., directory), use a different filename
+                    this.persistencePath = path.join(this.persistencePath, "state.json");
+                }
+            }
+            // Load existing state from disk
+            if (fs.existsSync(this.persistencePath)) {
+                const data = fs.readFileSync(this.persistencePath, "utf8");
+                const parsed = JSON.parse(data);
+                for (const [key, value] of Object.entries(parsed)) {
+                    this.store.set(key, value);
+                }
+                frameworkLogger.log("state-manager", "persistence loaded", "success", {
+                    keysLoaded: Object.keys(parsed).length,
+                });
+            }
+            this.initialized = true;
+            // Process any early operations that were queued
+            if (this.persistenceEnabled && this.earlyOperationsQueue.length > 0) {
+                const pendingOps = this.earlyOperationsQueue.length;
+                for (const key of this.earlyOperationsQueue) {
+                    this.schedulePersistence(key);
+                }
+                this.earlyOperationsQueue = [];
+                frameworkLogger.log("state-manager", "processed queued early operations", "info", {
+                    operationsProcessed: pendingOps,
+                });
+            }
+        }
+        catch (error) {
+            frameworkLogger.log("state-manager", "persistence initialization failed", "error", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Continue without persistence rather than failing
+            this.persistenceEnabled = false;
+            this.initialized = true;
+        }
+    }
+    async persistToDisk() {
+        if (!this.persistenceEnabled || !this.initialized)
+            return;
+        try {
+            const fs = await import("fs");
+            // Convert Map to object for JSON serialization
+            const data = {};
+            for (const [key, value] of this.store.entries()) {
+                // Only persist serializable data
+                if (this.isSerializable(value)) {
+                    data[key] = value;
+                }
+            }
+            fs.writeFileSync(this.persistencePath, JSON.stringify(data, null, 2));
+        }
+        catch (error) {
+            frameworkLogger.log("state-manager", "disk persistence failed", "error", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    isSerializable(value) {
+        try {
+            JSON.stringify(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    schedulePersistence(key) {
+        // Debounce writes to disk (100ms delay)
+        const existingTimeout = this.writeQueue.get(key);
+        if (existingTimeout) {
+            clearTimeout(existingTimeout);
+        }
+        const timeout = setTimeout(() => {
+            this.persistToDisk();
+            this.writeQueue.delete(key);
+        }, 100);
+        this.writeQueue.set(key, timeout);
+    }
+    get(key) {
+        const value = this.store.get(key);
+        frameworkLogger.log("state-manager", "get operation", "info", {
+            key,
+            hasValue: value !== undefined,
+        });
+        return value;
+    }
+    set(key, value) {
+        const jobId = `state-set-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+        // Store in memory immediately, even if persistence isn't ready yet
+        this.store.set(key, value);
+        // If initialized, schedule persistence
+        if (this.initialized && this.persistenceEnabled) {
+            this.schedulePersistence(key);
+        }
+        else if (!this.initialized) {
+            // Queue for persistence once initialized
+            if (!this.earlyOperationsQueue.includes(key)) {
+                this.earlyOperationsQueue.push(key);
+            }
+            frameworkLogger.log("state-manager", "set called before initialization, queued for persistence", "debug", { jobId, key });
+        }
+        frameworkLogger.log("state-manager", "set operation", "success", {
+            jobId,
+            key,
+        });
+    }
+    clear(key) {
+        // If not initialized yet, queue the operation
+        if (!this.initialized) {
+            this.earlyOperationsQueue.push(key);
+            frameworkLogger.log("state-manager", "clear queued for initialization", "info", { key, queueSize: this.earlyOperationsQueue.length });
+            return;
+        }
+        const existed = this.store.has(key);
+        this.store.delete(key);
+        // Immediately persist the deletion
+        if (this.persistenceEnabled && existed) {
+            this.persistToDisk();
+        }
+        frameworkLogger.log("state-manager", "clear operation", existed ? "success" : "info", { key, existed });
+    }
+    clearAll() {
+        // Ensure persistence is initialized
+        if (!this.initialized) {
+            frameworkLogger.log("state-manager", "clearAll called before initialization", "error", {});
+            return;
+        }
+        const keysCount = this.store.size;
+        this.store.clear();
+        // Immediately persist the empty state
+        if (this.persistenceEnabled && keysCount > 0) {
+            this.persistToDisk();
+        }
+        frameworkLogger.log("state-manager", "clearAll operation", "success", {
+            keysCleared: keysCount,
+        });
+    }
+    // New method to check if persistence is enabled
+    isPersistenceEnabled() {
+        return this.persistenceEnabled;
+    }
+    // New method to get persistence stats
+    getPersistenceStats() {
+        return {
+            enabled: this.persistenceEnabled,
+            initialized: this.initialized,
+            keysInMemory: this.store.size,
+            pendingWrites: this.writeQueue.size,
+        };
+    }
+    // Enterprise features for advanced state management
+    getStateVersion() {
+        return XrayStateManager.VERSION || "1.1.1";
+    }
+    getAuditLog() {
+        return []; // Simplified implementation for testing
+    }
+    resolveConflict(conflict) {
+        // Simple resolution strategy: prefer the newer value
+        frameworkLogger.log("state-manager", "conflict-resolved", "info", {
+            key: conflict.key,
+            strategy: "prefer-newer",
+        });
+        return conflict.value2; // Prefer the second value as newer
+    }
+}
+// Export alias for scripts expecting XrayStateManager

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/state/state-types.js

@@ -0,0 +1 @@
+export {};