0xray 2.0.0 → 2.0.1

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

@@ -0,0 +1,101 @@
+/**
+ * OpenClaw Integration - Main Module
+ *
+ * Combines all OpenClaw integration components into a single interface.
+ *
+ * @version 1.0.0
+ * @since 2026-03-14
+ */
+import { BaseIntegration } from '../base/index.js';
+import type { OpenClawIntegrationConfig, IntegrationStatistics } from './types.js';
+import { OpenClawClient } from './client.js';
+import { StringRayAPIServer } from './api-server.js';
+import { OpenClawHooksManager } from './hooks/strray-hooks.js';
+import type { AgentInvoker } from './api-server.js';
+/**
+ * Main OpenClaw Integration class
+ * Extends BaseIntegration for consistent lifecycle management
+ */
+export declare class OpenClawIntegration extends BaseIntegration {
+    private configLoader;
+    private client;
+    private apiServer;
+    private hooksManager;
+    private agentInvoker;
+    private mcpToolBeforeUnsubscribe;
+    private mcpToolAfterUnsubscribe;
+    constructor(configPath?: string);
+    /**
+     * Set the agent invoker for the API server
+     */
+    setAgentInvoker(invoker: AgentInvoker): void;
+    /**
+     * Perform integration-specific initialization
+     * Called by BaseIntegration.initialize() after base setup
+     */
+    protected performInitialization(): Promise<void>;
+    /**
+     * Wire OpenClaw hooks to MCPClient tool events
+     */
+    private wireHooksToMCP;
+    /**
+     * Perform integration-specific shutdown
+     * Called by BaseIntegration.shutdown() for cleanup
+     */
+    protected performShutdown(): Promise<void>;
+    /**
+     * Perform integration-specific health check
+     */
+    protected performHealthCheck(): Promise<{
+        healthy: boolean;
+        message: string;
+        details?: Record<string, unknown>;
+    }>;
+    /**
+     * Get statistics including client, API server, and base stats
+     */
+    getStatistics(): IntegrationStatistics;
+    /**
+     * Get the API server instance
+     */
+    getAPIServer(): StringRayAPIServer | null;
+    /**
+     * Get the client instance
+     */
+    getClient(): OpenClawClient | null;
+    /**
+     * Get the hooks manager
+     */
+    getHooksManager(): OpenClawHooksManager | null;
+    /**
+     * Get OpenClaw-specific configuration
+     */
+    getOpenClawConfig(): OpenClawIntegrationConfig;
+    /**
+     * Reload configuration
+     */
+    reloadConfig(): void;
+    /**
+     * Get the agent invoker
+     */
+    getAgentInvoker(): AgentInvoker | null;
+    private getDefaultClientStats;
+    private getDefaultAPIServerStats;
+}
+/**
+ * Initialize the global integration
+ */
+export declare function initializeOpenClawIntegration(configPath?: string, agentInvoker?: AgentInvoker): Promise<OpenClawIntegration>;
+/**
+ * Get the global integration
+ */
+export declare function getOpenClawIntegration(): OpenClawIntegration | null;
+/**
+ * Shutdown the global integration
+ */
+export declare function shutdownOpenClawIntegration(): Promise<void>;
+export * from './types.js';
+export * from './config.js';
+export * from './client.js';
+export * from './api-server.js';
+export { OpenClawHooksManager } from './hooks/strray-hooks.js';

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

@@ -0,0 +1,426 @@
+/**
+ * OpenClaw Integration Types
+ *
+ * TypeScript interfaces for OpenClaw Gateway Protocol v3
+ * and 0xRay integration components.
+ *
+ * @version 1.0.0
+ * @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 StringRayAPIServerConfig {
+    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",
+    STRINGRAY_UNAVAILABLE = "STRINGRAY_UNAVAILABLE",
+    STRINGRAY_TIMEOUT = "STRINGRAY_TIMEOUT",
+    STRINGRAY_ERROR = "STRINGRAY_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,10 @@
+/**
+ * Plugin System Exports
+ *
+ * Industrial-grade plugin system for 0xRay.
+ * Provides lifecycle management, security, metrics, and extensibility.
+ *
+ * @version 1.1.0
+ */
+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";