0xray 3.4.1 → 3.4.3

package/dist/integrations/openclaw/types.d.ts

@@ -0,0 +1,425 @@
+/**
+ * OpenClaw Integration Types
+ *
+ * TypeScript interfaces for OpenClaw Gateway Protocol v3
+ * and 0xRay integration components.
+ *
+ * @since 2026-03-14
+ */
+/**
+ * OpenClaw WebSocket connection handshake parameters
+ */
+export interface OpenClawConnectParams {
+    minProtocol: number;
+    maxProtocol: number;
+    client: {
+        id: string;
+        version: string;
+        platform: string;
+        mode: 'operator' | 'node' | 'local' | 'cli';
+    };
+    role: 'operator' | 'node';
+    scopes: string[];
+    caps: string[];
+    commands: string[];
+    permissions?: Record<string, boolean>;
+    auth?: {
+        token?: string;
+    };
+    device?: {
+        id: string;
+        publicKey: string;
+        signature: string;
+        signedAt: number;
+        nonce: string;
+    };
+    locale?: string;
+    userAgent: string;
+}
+/**
+ * OpenClaw WebSocket frame - Request (client → server)
+ */
+export interface OpenClawFrameRequest {
+    type: 'req';
+    id: string;
+    method: string;
+    params: Record<string, unknown>;
+}
+/**
+ * OpenClaw WebSocket frame - Response (server → client)
+ */
+export interface OpenClawFrameResponse {
+    type: 'res';
+    id: string;
+    ok: boolean;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * OpenClaw WebSocket frame - Event (server → client)
+ */
+export interface OpenClawFrameEvent {
+    type: 'event';
+    event: string;
+    data?: Record<string, unknown>;
+    seq?: number;
+    stateVersion?: string;
+}
+/**
+ * Union type for all OpenClaw frame types
+ */
+export type OpenClawFrame = OpenClawFrameRequest | OpenClawFrameResponse | OpenClawFrameEvent;
+/**
+ * OpenClaw client connection states
+ */
+export type OpenClawClientState = 'disconnected' | 'connecting' | 'connected' | 'authenticating' | 'authorized' | 'reconnecting' | 'error';
+/**
+ * Pending request for request/response handling
+ */
+export interface PendingRequest {
+    resolve: (value: unknown) => void;
+    reject: (reason: Error) => void;
+    timeout: NodeJS.Timeout;
+    timestamp: number;
+}
+/**
+ * Client configuration options
+ */
+export interface OpenClawClientConfig {
+    gatewayUrl: string;
+    authToken?: string | undefined;
+    deviceId?: string | undefined;
+    deviceKeyPair?: {
+        publicKey: string;
+        privateKey: string;
+    } | undefined;
+    reconnect?: boolean;
+    reconnectAttempts?: number;
+    reconnectDelay?: number;
+    pingInterval?: number;
+    requestTimeout?: number;
+}
+/**
+ * 0xRay API server configuration
+ */
+export interface XrayAPIServerConfig {
+    port: number;
+    host?: string;
+    apiKey?: string;
+    cors?: boolean;
+    rateLimit?: {
+        windowMs: number;
+        maxRequests: number;
+    };
+}
+/**
+ * Agent invocation request from OpenClaw skill
+ */
+export interface AgentInvokeRequest {
+    command: string;
+    args?: Record<string, unknown>;
+    sessionId?: string;
+    agent?: string;
+    timeout?: number;
+}
+/**
+ * Agent invocation response
+ */
+export interface AgentInvokeResponse {
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    sessionId?: string;
+    executionTime?: number;
+}
+/**
+ * Health check response
+ */
+export interface HealthCheckResponse {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    version: string;
+    uptime: number;
+    openclaw?: {
+        connected: boolean;
+        state: OpenClawClientState;
+    };
+}
+/**
+ * API route definitions
+ */
+export interface APIRoute {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    path: string;
+    handler: (req: Request, res: Response) => Promise<void>;
+    requiresAuth?: boolean;
+}
+/**
+ * OpenClaw Skill metadata (SKILL.md frontmatter)
+ */
+export interface OpenClawSkillMetadata {
+    name: string;
+    description: string;
+    version?: string;
+    metadata?: {
+        openclaw?: {
+            requires?: {
+                bins?: string[];
+                env?: string[];
+                config?: string[];
+            };
+            primaryEnv?: string;
+            emoji?: string;
+        };
+        author?: string;
+        tags?: string[];
+    };
+    userInvocable?: boolean;
+    commands?: SkillCommand[];
+}
+/**
+ * Skill command definition
+ */
+export interface SkillCommand {
+    name: string;
+    description: string;
+    usage?: string;
+    examples?: string[];
+    requiresAuth?: boolean;
+}
+/**
+ * Skill command execution request
+ */
+export interface SkillExecutionRequest {
+    command: string;
+    args: Record<string, unknown>;
+    userId?: string;
+    sessionId?: string;
+    channel?: string;
+}
+/**
+ * Skill command execution response
+ */
+export interface SkillExecutionResponse {
+    success: boolean;
+    output?: string;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Tool execution event from 0xRay
+ */
+export interface ToolExecutionEvent {
+    toolName: string;
+    toolId: string;
+    args: Record<string, unknown>;
+    result?: unknown;
+    error?: string;
+    duration: number;
+    timestamp: number;
+    sessionId?: string;
+    agent?: string;
+}
+/**
+ * Tool before execution event
+ */
+export interface ToolBeforeEvent extends ToolExecutionEvent {
+    eventType: 'tool.before';
+}
+/**
+ * Tool after execution event
+ */
+export interface ToolAfterEvent extends ToolExecutionEvent {
+    eventType: 'tool.after';
+    success: boolean;
+}
+/**
+ * Tool event subscription options
+ */
+export interface ToolEventSubscription {
+    toolNames?: string[];
+    includeArgs?: boolean;
+    includeResult?: boolean;
+    includeMetadata?: boolean;
+}
+/**
+ * Complete OpenClaw integration configuration
+ */
+export interface OpenClawIntegrationConfig {
+    gatewayUrl: string;
+    authToken?: string;
+    deviceId?: string;
+    deviceKeyPair?: {
+        publicKey: string;
+        privateKey: string;
+    };
+    autoReconnect: boolean;
+    maxReconnectAttempts: number;
+    reconnectDelay: number;
+    apiServer: {
+        enabled: boolean;
+        port: number;
+        host?: string;
+        apiKey?: string;
+    };
+    hooks: {
+        enabled: boolean;
+        toolBefore: boolean;
+        toolAfter: boolean;
+        includeArgs: boolean;
+        includeResult: boolean;
+        toolFilter?: string[];
+    };
+    enabled: boolean;
+    debug: boolean;
+    logLevel?: 'error' | 'warn' | 'info' | 'debug';
+}
+/**
+ * Configuration validation result
+ */
+export interface ConfigValidationResult {
+    valid: boolean;
+    errors: ConfigValidationError[];
+    warnings: ConfigValidationWarning[];
+}
+export interface ConfigValidationError {
+    field: string;
+    message: string;
+    code: string;
+}
+export interface ConfigValidationWarning {
+    field: string;
+    message: string;
+}
+/**
+ * OpenClaw integration error codes
+ */
+export declare enum OpenClawErrorCode {
+    CONNECTION_FAILED = "CONNECTION_FAILED",
+    CONNECTION_TIMEOUT = "CONNECTION_TIMEOUT",
+    AUTH_FAILED = "AUTH_FAILED",
+    TOKEN_MISMATCH = "TOKEN_MISMATCH",
+    DEVICE_NOT_PAIRED = "DEVICE_NOT_PAIRED",
+    INVALID_FRAME = "INVALID_FRAME",
+    UNSUPPORTED_METHOD = "UNSUPPORTED_METHOD",
+    OUT_OF_SCOPE = "OUT_OF_SCOPE",
+    PROTOCOL_VERSION_MISMATCH = "PROTOCOL_VERSION_MISMATCH",
+    REQUEST_TIMEOUT = "REQUEST_TIMEOUT",
+    REQUEST_CANCELLED = "REQUEST_CANCELLED",
+    SERVER_ERROR = "SERVER_ERROR",
+    SERVER_UNAVAILABLE = "SERVER_UNAVAILABLE",
+    SKILL_NOT_FOUND = "SKILL_NOT_FOUND",
+    SKILL_LOAD_FAILED = "SKILL_LOAD_FAILED",
+    SKILL_EXECUTION_FAILED = "SKILL_EXECUTION_FAILED",
+    XRAY_UNAVAILABLE = "XRAY_UNAVAILABLE",
+    XRAY_TIMEOUT = "XRAY_TIMEOUT",
+    XRAY_ERROR = "XRAY_ERROR",
+    CONFIG_INVALID = "CONFIG_INVALID",
+    CONFIG_MISSING = "CONFIG_MISSING",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Base error class for OpenClaw integration
+ */
+export declare class OpenClawError extends Error {
+    code: OpenClawErrorCode;
+    recoverable: boolean;
+    context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: OpenClawErrorCode, recoverable: boolean, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Connection error
+ */
+export declare class OpenClawConnectionError extends OpenClawError {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+/**
+ * Authentication error
+ */
+export declare class OpenClawAuthError extends OpenClawError {
+    authType?: "token" | "device" | undefined;
+    constructor(message: string, authType?: "token" | "device" | undefined);
+}
+/**
+ * Request timeout error
+ */
+export declare class OpenClawTimeoutError extends OpenClawError {
+    method: string;
+    timeout: number;
+    constructor(method: string, timeout: number);
+}
+/**
+ * Configuration error
+ */
+export declare class OpenClawConfigError extends OpenClawError {
+    field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+/**
+ * Check if frame is a request frame
+ */
+export declare function isOpenClawRequest(frame: unknown): frame is OpenClawFrameRequest;
+/**
+ * Check if frame is a response frame
+ */
+export declare function isOpenClawResponse(frame: unknown): frame is OpenClawFrameResponse;
+/**
+ * Check if frame is an event frame
+ */
+export declare function isOpenClawEvent(frame: unknown): frame is OpenClawFrameEvent;
+/**
+ * Check if error is recoverable
+ */
+export declare function isRecoverableError(error: OpenClawError): boolean;
+/**
+ * Client statistics
+ */
+export interface ClientStatistics {
+    connectedAt?: number;
+    lastMessageAt?: number;
+    messagesSent: number;
+    messagesReceived: number;
+    requestsSent: number;
+    requestsSucceeded: number;
+    requestsFailed: number;
+    reconnects: number;
+    errors: number;
+}
+/**
+ * API server statistics
+ */
+export interface APIServerStatistics {
+    startedAt: number;
+    requestsTotal: number;
+    requestsByEndpoint: Record<string, number>;
+    requestsByStatus: Record<number, number>;
+    averageResponseTime: number;
+    errors: number;
+}
+/**
+ * Integration statistics
+ */
+export interface IntegrationStatistics {
+    client: ClientStatistics;
+    apiServer: APIServerStatistics;
+    uptime: number;
+}
+/**
+ * OpenClaw client events
+ */
+export type OpenClawClientEvent = 'connecting' | 'connected' | 'disconnected' | 'authorized' | 'reconnecting' | 'error' | 'frame' | 'event';
+/**
+ * Client event listener type
+ */
+export type OpenClawEventListener = (data?: unknown) => void | Promise<void>;
+/**
+ * State change event
+ */
+export interface StateChangeEvent {
+    previousState: OpenClawClientState;
+    newState: OpenClawClientState;
+    timestamp: number;
+}

package/dist/integrations/plugins/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Plugin System Exports
+ *
+ * Industrial-grade plugin system for 0xRay.
+ * Provides lifecycle management, security, metrics, and extensibility.
+ *
+ */
+export { PluginIntegration, PluginType, PluginState, PluginConfig, PluginManifest, PluginRoutingMapping, PluginResourceLimits, PluginPermissions, PluginMetrics, PluginValidationResult, DEFAULT_PLUGIN_CONFIG, parseYamlManifest, validatePluginManifest, satisfiesVersion, } from "./plugin-integration.js";
+export { PluginRegistry, type PluginRegistryConfig, type PluginLoadResult, type PluginStatus, type RegistryMetrics, type DependencyInfo, type PluginRegistryEventType, type PluginRegistryEvent, } from "./plugin-registry.js";

package/dist/integrations/plugins/plugin-integration.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Plugin Integration
+ *
+ * Industrial-grade plugin system extending the existing Integration architecture.
+ * Plugins are integrations that can provide MCP servers, skills, and capabilities.
+ *
+ * Features:
+ * - Lifecycle management with state machine
+ * - Security sandboxing and permission system
+ * - Dependency resolution and validation
+ * - Semantic version compatibility checking
+ * - Resource limits and quotas
+ * - Comprehensive observability with metrics
+ * - Graceful shutdown with retry logic
+ * - Plugin isolation with process spawning
+ *
+ */
+import { BaseIntegration, type IntegrationConfig, type HealthResult } from "../base/index.js";
+/**
+ * Plugin types matching the plugin architecture spec
+ */
+export declare enum PluginType {
+    MCP_SERVER = "mcp-server",
+    SKILL = "skill",
+    INTEGRATION = "integration",
+    AGENT = "agent"
+}
+/**
+ * Plugin lifecycle states
+ */
+export declare enum PluginState {
+    UNINSTALLED = "uninstalled",
+    INSTALLED = "installed",
+    ENABLED = "enabled",
+    ACTIVE = "active",
+    ERROR = "error",
+    DISABLING = "disabling",
+    ENABLING = "enabling"
+}
+/**
+ * Plugin configuration
+ */
+export interface PluginConfig extends IntegrationConfig {
+    type: PluginType;
+    autoStart: boolean;
+    config?: Record<string, unknown>;
+    resourceLimits?: PluginResourceLimits;
+    permissions?: PluginPermissions;
+}
+/**
+ * Resource limits for plugin
+ */
+export interface PluginResourceLimits {
+    maxMemoryMB?: number;
+    maxCpuPercent?: number;
+    maxProcessTime?: number;
+    maxFileDescriptors?: number;
+}
+/**
+ * Plugin permissions
+ */
+export interface PluginPermissions {
+    allowedPaths?: string[];
+    allowedCommands?: string[];
+    networkAccess?: boolean;
+    filesystemAccess?: boolean;
+    envWhitelist?: string[];
+}
+/**
+ * Plugin manifest (from plugin.yaml)
+ */
+export interface PluginManifest {
+    name: string;
+    version: string;
+    type: PluginType;
+    description: string;
+    license?: string | undefined;
+    author?: string | undefined;
+    homepage?: string | undefined;
+    repository?: string | undefined;
+    minXrayVersion?: string | undefined;
+    runtime?: {
+        command: string;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+        timeout?: number | undefined;
+        workingDir?: string | undefined;
+    } | undefined;
+    tools?: Array<{
+        name: string;
+        description: string;
+        inputSchema?: object | undefined;
+        outputSchema?: object | undefined;
+    }> | undefined;
+    capabilities?: string[] | undefined;
+    dependencies?: Record<string, string> | undefined;
+    optionalDependencies?: Record<string, string> | undefined;
+    routing?: Array<{
+        keywords: string[];
+        skill: string;
+        agent: string;
+        confidence: number;
+    }> | undefined;
+    resourceLimits?: PluginResourceLimits | undefined;
+    permissions?: PluginPermissions | undefined;
+}
+/**
+ * Plugin routing mapping for enforcer
+ */
+export interface PluginRoutingMapping {
+    keywords: string[];
+    skill: string;
+    agent: string;
+    confidence: number;
+}
+/**
+ * Plugin metrics for observability
+ */
+export interface PluginMetrics {
+    name: string;
+    uptime: number;
+    totalRestarts: number;
+    lastStartTime: number;
+    lastError?: string | undefined;
+    memoryUsageMB?: number | undefined;
+    cpuUsagePercent?: number | undefined;
+    toolCallsCount: number;
+    errorsCount: number;
+}
+/**
+ * Validation result for plugin
+ */
+export interface PluginValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Default plugin configuration
+ */
+export declare const DEFAULT_PLUGIN_CONFIG: PluginConfig;
+/**
+ * Parse YAML manifest (shared utility)
+ */
+export declare function parseYamlManifest(content: string): Record<string, unknown>;
+/**
+ * Semantic version comparison
+ */
+export declare function satisfiesVersion(version: string, range: string): boolean;
+/**
+ * Validate plugin manifest
+ */
+export declare function validatePluginManifest(manifest: PluginManifest): PluginValidationResult;
+/**
+ * Plugin Integration Class
+ *
+ * Extends BaseIntegration to leverage existing:
+ * - Lifecycle management (initialize/shutdown)
+ * - Configuration handling
+ * - Event emission
+ * - Health checking
+ * - Logging
+ */
+export declare class PluginIntegration extends BaseIntegration {
+    private manifest;
+    private childProcess;
+    private pluginPath;
+    private pluginType;
+    private autoStart;
+    private pluginState;
+    private restarts;
+    private lastStartTime;
+    private lastError?;
+    private toolCallsCount;
+    private errorsCount;
+    private resourceLimits;
+    private permissions;
+    constructor(name: string, version: string, pluginPath: string, type?: PluginType, config?: Partial<PluginConfig>);
+    /**
+     * Load plugin from plugin.yaml
+     */
+    load(): Promise<PluginManifest>;
+    /**
+     * Initialize the plugin
+     */
+    protected performInitialization(): Promise<void>;
+    /**
+     * Shutdown the plugin
+     */
+    protected performShutdown(): Promise<void>;
+    /**
+     * Health check implementation
+     */
+    protected performHealthCheck(): Promise<HealthResult>;
+    /**
+     * Get plugin uptime in milliseconds
+     */
+    getUptime(): number;
+    /**
+     * Start the MCP server process
+     */
+    startPlugin(): Promise<void>;
+    /**
+     * Stop the MCP server process gracefully
+     */
+    stopPlugin(): Promise<void>;
+    /**
+     * Enable the plugin
+     */
+    enable(): Promise<void>;
+    /**
+     * Disable the plugin
+     */
+    disable(): Promise<void>;
+    /**
+     * Restart the plugin
+     */
+    restart(): Promise<void>;
+    /**
+     * Get MCP server configuration (if type is MCP_SERVER)
+     */
+    getMcpServerConfig(): {
+        serverName: string;
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+        timeout?: number;
+    } | null;
+    /**
+     * Get tools provided by this plugin
+     */
+    getTools(): Array<{
+        name: string;
+        description: string;
+    }>;
+    /**
+     * Record a tool call
+     */
+    recordToolCall(): void;
+    /**
+     * Get capabilities
+     */
+    getCapabilities(): string[];
+    /**
+     * Get routing mappings for this plugin
+     */
+    getRoutingMappings(): PluginRoutingMapping[];
+    /**
+     * Set auto-start preference
+     */
+    setAutoStart(autoStart: boolean): void;
+    /**
+     * Get plugin type
+     */
+    getPluginType(): PluginType;
+    /**
+     * Get plugin state
+     */
+    getPluginState(): PluginState;
+    /**
+     * Get manifest
+     */
+    getManifest(): PluginManifest | null;
+    /**
+     * Check if plugin is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get resource limits
+     */
+    getResourceLimits(): PluginResourceLimits;
+    /**
+     * Get permissions
+     */
+    getPermissions(): PluginPermissions;
+    /**
+     * Get comprehensive metrics
+     */
+    getMetrics(): PluginMetrics;
+    /**
+     * Get dependencies
+     */
+    getDependencies(): Record<string, string>;
+    /**
+     * Get optional dependencies
+     */
+    getOptionalDependencies(): Record<string, string>;
+}