openclaw-overlay-plugin 0.7.22

package/src/services/registry.ts

@@ -0,0 +1,246 @@
+/**
+ * Service registry implementation.
+ *
+ * This provides a centralized registry for all services, allowing
+ * dynamic registration and discovery without modifying core code.
+ */
+
+import { ServiceDefinition, ServiceRegistry, ServiceCategory } from './types.js';
+
+/**
+ * Default service registry implementation.
+ */
+export class DefaultServiceRegistry implements ServiceRegistry {
+  private services = new Map<string, ServiceDefinition>();
+
+  /**
+   * Register a new service definition.
+   */
+  register(service: ServiceDefinition): void {
+    // 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: string): ServiceDefinition | undefined {
+    return this.services.get(serviceId);
+  }
+
+  /**
+   * List all registered services.
+   */
+  list(): ServiceDefinition[] {
+    return Array.from(this.services.values());
+  }
+
+  /**
+   * List services by category.
+   */
+  listByCategory(category: string): ServiceDefinition[] {
+    return this.list().filter(service => service.category === category);
+  }
+
+  /**
+   * Check if a service is registered.
+   */
+  has(serviceId: string): boolean {
+    return this.services.has(serviceId);
+  }
+
+  /**
+   * Unregister a service.
+   */
+  unregister(serviceId: string): void {
+    this.services.delete(serviceId);
+  }
+
+  /**
+   * Clear all services (useful for testing).
+   */
+  clear(): void {
+    this.services.clear();
+  }
+
+  /**
+   * Get service count.
+   */
+  count(): number {
+    return this.services.size;
+  }
+
+  /**
+   * Get services by price range.
+   */
+  getByPriceRange(minPrice: number, maxPrice: number): ServiceDefinition[] {
+    return this.list().filter(
+      service => service.defaultPrice >= minPrice && service.defaultPrice <= maxPrice
+    );
+  }
+
+  /**
+   * Search services by name or description.
+   */
+  search(query: string): ServiceDefinition[] {
+    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.
+   */
+  private validateServiceDefinition(service: ServiceDefinition): void {
+    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 as ServiceCategory)) {
+      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: ServiceDefinition[]): void {
+    for (const service of services) {
+      serviceRegistry.register(service);
+    }
+  },
+
+  /**
+   * Get services that support a specific input type.
+   */
+  getServicesForInput(inputType: string): ServiceDefinition[] {
+    return serviceRegistry.list().filter(service => {
+      if (!service.inputSchema) return false;
+      const schema = service.inputSchema as any;
+      return schema.properties && schema.properties[inputType];
+    });
+  },
+
+  /**
+   * Validate service exists and return it.
+   */
+  requireService(serviceId: string): ServiceDefinition {
+    const service = serviceRegistry.get(serviceId);
+    if (!service) {
+      throw new Error(`Service '${serviceId}' not found`);
+    }
+    return service;
+  },
+
+  /**
+   * Get all service IDs.
+   */
+  getAllServiceIds(): string[] {
+    return serviceRegistry.list().map(service => service.id);
+  },
+
+  /**
+   * Check if any services are registered.
+   */
+  hasAnyServices(): boolean {
+    return serviceRegistry.count() > 0;
+  },
+
+  /**
+   * Get service statistics.
+   */
+  getStatistics(): {
+    totalServices: number;
+    servicesByCategory: Record<string, number>;
+    priceRange: { min: number; max: number };
+    servicesWithHandlers: number;
+  } {
+    const services = serviceRegistry.list();
+    const servicesByCategory: Record<string, number> = {};
+    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/src/services/types.ts

@@ -0,0 +1,259 @@
+/**
+ * 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 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 enum ServiceStatus {
+  ACTIVE = 'active',
+  INACTIVE = 'inactive',
+  ERROR = 'error',
+  LOADING = 'loading'
+}