openclaw-overlay-plugin 0.7.22

package/dist/services/registry.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Service registry implementation.
+ *
+ * This provides a centralized registry for all services, allowing
+ * dynamic registration and discovery without modifying core code.
+ */
+import { ServiceDefinition, ServiceRegistry } from './types.js';
+/**
+ * Default service registry implementation.
+ */
+export declare class DefaultServiceRegistry implements ServiceRegistry {
+    private services;
+    /**
+     * Register a new service definition.
+     */
+    register(service: ServiceDefinition): void;
+    /**
+     * Get a service definition by ID.
+     */
+    get(serviceId: string): ServiceDefinition | undefined;
+    /**
+     * List all registered services.
+     */
+    list(): ServiceDefinition[];
+    /**
+     * List services by category.
+     */
+    listByCategory(category: string): ServiceDefinition[];
+    /**
+     * Check if a service is registered.
+     */
+    has(serviceId: string): boolean;
+    /**
+     * Unregister a service.
+     */
+    unregister(serviceId: string): void;
+    /**
+     * Clear all services (useful for testing).
+     */
+    clear(): void;
+    /**
+     * Get service count.
+     */
+    count(): number;
+    /**
+     * Get services by price range.
+     */
+    getByPriceRange(minPrice: number, maxPrice: number): ServiceDefinition[];
+    /**
+     * Search services by name or description.
+     */
+    search(query: string): ServiceDefinition[];
+    /**
+     * Validate a service definition.
+     */
+    private validateServiceDefinition;
+}
+/**
+ * Global service registry instance.
+ */
+export declare const serviceRegistry: DefaultServiceRegistry;
+/**
+ * Utility functions for working with the service registry.
+ */
+export declare const ServiceRegistryUtils: {
+    /**
+     * Register multiple services at once.
+     */
+    registerMultiple(services: ServiceDefinition[]): void;
+    /**
+     * Get services that support a specific input type.
+     */
+    getServicesForInput(inputType: string): ServiceDefinition[];
+    /**
+     * Validate service exists and return it.
+     */
+    requireService(serviceId: string): ServiceDefinition;
+    /**
+     * Get all service IDs.
+     */
+    getAllServiceIds(): string[];
+    /**
+     * Check if any services are registered.
+     */
+    hasAnyServices(): boolean;
+    /**
+     * Get service statistics.
+     */
+    getStatistics(): {
+        totalServices: number;
+        servicesByCategory: Record<string, number>;
+        priceRange: {
+            min: number;
+            max: number;
+        };
+        servicesWithHandlers: number;
+    };
+};

package/dist/services/registry.js

@@ -0,0 +1,204 @@
+/**
+ * Service registry implementation.
+ *
+ * This provides a centralized registry for all services, allowing
+ * dynamic registration and discovery without modifying core code.
+ */
+import { ServiceCategory } from './types.js';
+/**
+ * Default service registry implementation.
+ */
+export class DefaultServiceRegistry {
+    services = new Map();
+    /**
+     * Register a new service definition.
+     */
+    register(service) {
+        // Validate service definition
+        this.validateServiceDefinition(service);
+        // Check for duplicates
+        if (this.services.has(service.id)) {
+            throw new Error(`Service '${service.id}' is already registered`);
+        }
+        // Register the service
+        this.services.set(service.id, { ...service });
+    }
+    /**
+     * Get a service definition by ID.
+     */
+    get(serviceId) {
+        return this.services.get(serviceId);
+    }
+    /**
+     * List all registered services.
+     */
+    list() {
+        return Array.from(this.services.values());
+    }
+    /**
+     * List services by category.
+     */
+    listByCategory(category) {
+        return this.list().filter(service => service.category === category);
+    }
+    /**
+     * Check if a service is registered.
+     */
+    has(serviceId) {
+        return this.services.has(serviceId);
+    }
+    /**
+     * Unregister a service.
+     */
+    unregister(serviceId) {
+        this.services.delete(serviceId);
+    }
+    /**
+     * Clear all services (useful for testing).
+     */
+    clear() {
+        this.services.clear();
+    }
+    /**
+     * Get service count.
+     */
+    count() {
+        return this.services.size;
+    }
+    /**
+     * Get services by price range.
+     */
+    getByPriceRange(minPrice, maxPrice) {
+        return this.list().filter(service => service.defaultPrice >= minPrice && service.defaultPrice <= maxPrice);
+    }
+    /**
+     * Search services by name or description.
+     */
+    search(query) {
+        const lowerQuery = query.toLowerCase();
+        return this.list().filter(service => service.name.toLowerCase().includes(lowerQuery) ||
+            service.description.toLowerCase().includes(lowerQuery) ||
+            service.id.toLowerCase().includes(lowerQuery));
+    }
+    /**
+     * Validate a service definition.
+     */
+    validateServiceDefinition(service) {
+        if (!service.id) {
+            throw new Error('Service ID is required');
+        }
+        if (typeof service.id !== 'string' || service.id.trim().length === 0) {
+            throw new Error('Service ID must be a non-empty string');
+        }
+        // Validate ID format (kebab-case)
+        if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(service.id)) {
+            throw new Error('Service ID must be in kebab-case format (lowercase, hyphens only)');
+        }
+        if (!service.name || typeof service.name !== 'string' || service.name.trim().length === 0) {
+            throw new Error('Service name is required and must be a non-empty string');
+        }
+        if (!service.description || typeof service.description !== 'string' || service.description.trim().length === 0) {
+            throw new Error('Service description is required and must be a non-empty string');
+        }
+        if (typeof service.defaultPrice !== 'number' || service.defaultPrice < 0 || !Number.isInteger(service.defaultPrice)) {
+            throw new Error('Service defaultPrice must be a non-negative integer');
+        }
+        if (service.category && !Object.values(ServiceCategory).includes(service.category)) {
+            throw new Error(`Invalid service category: ${service.category}`);
+        }
+        // Validate input schema if provided
+        if (service.inputSchema && typeof service.inputSchema !== 'object') {
+            throw new Error('Service inputSchema must be an object');
+        }
+        // Validate handler if provided
+        if (service.handler) {
+            if (typeof service.handler.validate !== 'function') {
+                throw new Error('Service handler must have a validate function');
+            }
+            if (typeof service.handler.process !== 'function') {
+                throw new Error('Service handler must have a process function');
+            }
+        }
+    }
+}
+/**
+ * Global service registry instance.
+ */
+export const serviceRegistry = new DefaultServiceRegistry();
+/**
+ * Utility functions for working with the service registry.
+ */
+export const ServiceRegistryUtils = {
+    /**
+     * Register multiple services at once.
+     */
+    registerMultiple(services) {
+        for (const service of services) {
+            serviceRegistry.register(service);
+        }
+    },
+    /**
+     * Get services that support a specific input type.
+     */
+    getServicesForInput(inputType) {
+        return serviceRegistry.list().filter(service => {
+            if (!service.inputSchema)
+                return false;
+            const schema = service.inputSchema;
+            return schema.properties && schema.properties[inputType];
+        });
+    },
+    /**
+     * Validate service exists and return it.
+     */
+    requireService(serviceId) {
+        const service = serviceRegistry.get(serviceId);
+        if (!service) {
+            throw new Error(`Service '${serviceId}' not found`);
+        }
+        return service;
+    },
+    /**
+     * Get all service IDs.
+     */
+    getAllServiceIds() {
+        return serviceRegistry.list().map(service => service.id);
+    },
+    /**
+     * Check if any services are registered.
+     */
+    hasAnyServices() {
+        return serviceRegistry.count() > 0;
+    },
+    /**
+     * Get service statistics.
+     */
+    getStatistics() {
+        const services = serviceRegistry.list();
+        const servicesByCategory = {};
+        let minPrice = Infinity;
+        let maxPrice = -Infinity;
+        let servicesWithHandlers = 0;
+        for (const service of services) {
+            // Count by category
+            const category = service.category || 'uncategorized';
+            servicesByCategory[category] = (servicesByCategory[category] || 0) + 1;
+            // Track price range
+            minPrice = Math.min(minPrice, service.defaultPrice);
+            maxPrice = Math.max(maxPrice, service.defaultPrice);
+            // Count services with handlers
+            if (service.handler) {
+                servicesWithHandlers++;
+            }
+        }
+        return {
+            totalServices: services.length,
+            servicesByCategory,
+            priceRange: {
+                min: minPrice === Infinity ? 0 : minPrice,
+                max: maxPrice === -Infinity ? 0 : maxPrice
+            },
+            servicesWithHandlers
+        };
+    }
+};

package/dist/services/types.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Service architecture type definitions.
+ *
+ * This module defines the core interfaces for the pluggable service system.
+ * Services can be added without modifying core payment or relay logic.
+ */
+export interface ServiceDefinition {
+    /** Unique service identifier (kebab-case) */
+    id: string;
+    /** Human-readable service name */
+    name: string;
+    /** Service description for discovery */
+    description: string;
+    /** Default price in satoshis */
+    defaultPrice: number;
+    /** Optional JSON schema for input validation */
+    inputSchema?: object;
+    /** Optional legacy handler for non-agent mode */
+    handler?: ServiceHandler;
+    /** Optional path to agent mode prompt file */
+    promptFile?: string;
+    /** Service category for organization */
+    category?: string;
+    /** Whether this service requires special permissions */
+    requiresVerification?: boolean;
+}
+export interface ServiceHandler {
+    /**
+     * Validate incoming service input.
+     * @param input - Raw input from service request
+     * @returns Validation result
+     */
+    validate(input: any): ValidationResult;
+    /**
+     * Process the service request.
+     * Payment has already been verified at this point.
+     * @param input - Validated input data
+     * @param context - Service execution context
+     * @returns Service processing result
+     */
+    process(input: any, context: ServiceContext): Promise<ServiceResult>;
+}
+export interface ValidationResult {
+    /** Whether input is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Sanitized/normalized input if valid */
+    sanitized?: any;
+}
+export interface ServiceContext {
+    /** Unique request identifier */
+    requestId: string;
+    /** Sender's identity key */
+    from: string;
+    /** Service being requested */
+    serviceId: string;
+    /** Payment information (already verified) */
+    payment: PaymentInfo;
+    /** Request timestamp */
+    timestamp: number;
+}
+export interface PaymentInfo {
+    /** Transaction ID */
+    txid: string;
+    /** Amount paid in satoshis */
+    satoshis: number;
+    /** Whether payment was accepted by wallet */
+    accepted: boolean;
+    /** Payment verification details */
+    verification?: {
+        /** BEEF transaction data */
+        beef: string;
+        /** Derivation prefix for BRC-29 */
+        derivationPrefix?: string;
+        /** Derivation suffix for BRC-29 */
+        derivationSuffix?: string;
+    };
+}
+export interface ServiceResult {
+    /** Whether service execution was successful */
+    success: boolean;
+    /** Service output data */
+    data?: any;
+    /** Error message if unsuccessful */
+    error?: string;
+    /** Additional metadata */
+    metadata?: {
+        /** Processing time in milliseconds */
+        processingTime?: number;
+        /** Service version */
+        version?: string;
+        /** Additional context */
+        [key: string]: any;
+    };
+}
+export interface ServiceRegistry {
+    /**
+     * Register a new service definition.
+     * @param service - Service to register
+     */
+    register(service: ServiceDefinition): void;
+    /**
+     * Get a service definition by ID.
+     * @param serviceId - Service identifier
+     * @returns Service definition or undefined
+     */
+    get(serviceId: string): ServiceDefinition | undefined;
+    /**
+     * List all registered services.
+     * @returns Array of all service definitions
+     */
+    list(): ServiceDefinition[];
+    /**
+     * List services by category.
+     * @param category - Service category
+     * @returns Array of services in category
+     */
+    listByCategory(category: string): ServiceDefinition[];
+    /**
+     * Check if a service is registered.
+     * @param serviceId - Service identifier
+     * @returns Whether service exists
+     */
+    has(serviceId: string): boolean;
+    /**
+     * Unregister a service.
+     * @param serviceId - Service identifier
+     */
+    unregister(serviceId: string): void;
+}
+export interface ServiceLoader {
+    /**
+     * Load services from a directory.
+     * @param directory - Directory path to scan
+     * @returns Array of loaded service definitions
+     */
+    loadFromDirectory(directory: string): Promise<ServiceDefinition[]>;
+    /**
+     * Load all built-in services.
+     * @returns Array of built-in service definitions
+     */
+    loadBuiltInServices(): Promise<ServiceDefinition[]>;
+    /**
+     * Load custom user services.
+     * @returns Array of custom service definitions
+     */
+    loadCustomServices(): Promise<ServiceDefinition[]>;
+}
+/**
+ * Service execution context for handlers.
+ * This provides access to validated input and request context
+ * without exposing payment verification or relay logic.
+ */
+export interface ServiceExecutionContext {
+    /** Service definition being executed */
+    service: ServiceDefinition;
+    /** Validated input data */
+    input: any;
+    /** Request context */
+    context: ServiceContext;
+}
+/**
+ * Service plugin interface for advanced services.
+ * This allows services to define additional hooks and lifecycle methods.
+ */
+export interface ServicePlugin {
+    /** Service definition */
+    definition: ServiceDefinition;
+    /** Optional initialization hook */
+    initialize?(): Promise<void>;
+    /** Optional cleanup hook */
+    cleanup?(): Promise<void>;
+    /** Optional health check */
+    healthCheck?(): Promise<boolean>;
+}
+/**
+ * Service manager interface for orchestrating service lifecycle.
+ */
+export interface ServiceManager {
+    /** Service registry */
+    registry: ServiceRegistry;
+    /** Service loader */
+    loader: ServiceLoader;
+    /**
+     * Initialize the service system.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Execute a service request.
+     * @param serviceId - Service to execute
+     * @param input - Service input
+     * @param context - Execution context
+     * @returns Service result
+     */
+    execute(serviceId: string, input: any, context: ServiceContext): Promise<ServiceResult>;
+    /**
+     * Validate service input.
+     * @param serviceId - Service to validate for
+     * @param input - Input to validate
+     * @returns Validation result
+     */
+    validate(serviceId: string, input: any): ValidationResult;
+    /**
+     * Reload all services.
+     */
+    reload(): Promise<void>;
+}
+/**
+ * Common service categories for organization.
+ */
+export declare enum ServiceCategory {
+    UTILITY = "utility",
+    AI = "ai",
+    BLOCKCHAIN = "blockchain",
+    COMMUNICATION = "communication",
+    DEVELOPMENT = "development",
+    RESEARCH = "research",
+    ENTERTAINMENT = "entertainment",
+    CUSTOM = "custom"
+}
+/**
+ * Service status for monitoring and management.
+ */
+export declare enum ServiceStatus {
+    ACTIVE = "active",
+    INACTIVE = "inactive",
+    ERROR = "error",
+    LOADING = "loading"
+}

package/dist/services/types.js

@@ -0,0 +1,30 @@
+/**
+ * Service architecture type definitions.
+ *
+ * This module defines the core interfaces for the pluggable service system.
+ * Services can be added without modifying core payment or relay logic.
+ */
+/**
+ * Common service categories for organization.
+ */
+export var ServiceCategory;
+(function (ServiceCategory) {
+    ServiceCategory["UTILITY"] = "utility";
+    ServiceCategory["AI"] = "ai";
+    ServiceCategory["BLOCKCHAIN"] = "blockchain";
+    ServiceCategory["COMMUNICATION"] = "communication";
+    ServiceCategory["DEVELOPMENT"] = "development";
+    ServiceCategory["RESEARCH"] = "research";
+    ServiceCategory["ENTERTAINMENT"] = "entertainment";
+    ServiceCategory["CUSTOM"] = "custom";
+})(ServiceCategory || (ServiceCategory = {}));
+/**
+ * Service status for monitoring and management.
+ */
+export var ServiceStatus;
+(function (ServiceStatus) {
+    ServiceStatus["ACTIVE"] = "active";
+    ServiceStatus["INACTIVE"] = "inactive";
+    ServiceStatus["ERROR"] = "error";
+    ServiceStatus["LOADING"] = "loading";
+})(ServiceStatus || (ServiceStatus = {}));

package/dist/test/cli.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CLI test suite — tests the compiled CLI as a subprocess.
+ *
+ * Uses child_process.execFile to invoke `node dist/cli.js <command>`
+ * and validates stdout JSON, stderr, and exit codes.
+ */
+export {};