openclaw-overlay-plugin 0.7.22

package/src/services/loader.ts

@@ -0,0 +1,344 @@
+/**
+ * Service loader implementation.
+ *
+ * This dynamically loads services from directories, supporting both
+ * built-in services and custom user services.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ServiceDefinition, ServiceLoader } from './types.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Default service loader implementation.
+ */
+export class DefaultServiceLoader implements ServiceLoader {
+  private builtInDir: string;
+  private customDir: string;
+
+  constructor() {
+    // Built-in services directory
+    this.builtInDir = path.resolve(__dirname, 'built-in');
+
+    // Custom services directory (in user's config dir)
+    const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+    this.customDir = path.join(homeDir, '.openclaw', 'services');
+  }
+
+  /**
+   * Load services from a directory.
+   */
+  async loadFromDirectory(directory: string): Promise<ServiceDefinition[]> {
+    if (!fs.existsSync(directory)) {
+      return [];
+    }
+
+    const services: ServiceDefinition[] = [];
+    const entries = fs.readdirSync(directory, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      try {
+        const serviceDefinition = await this.loadServiceFromDirectory(
+          path.join(directory, entry.name)
+        );
+        if (serviceDefinition) {
+          services.push(serviceDefinition);
+        }
+      } catch (error) {
+        console.warn(`Failed to load service from ${entry.name}:`, error);
+      }
+    }
+
+    return services;
+  }
+
+  /**
+   * Load all built-in services.
+   */
+  async loadBuiltInServices(): Promise<ServiceDefinition[]> {
+    return this.loadFromDirectory(this.builtInDir);
+  }
+
+  /**
+   * Load custom user services.
+   */
+  async loadCustomServices(): Promise<ServiceDefinition[]> {
+    return this.loadFromDirectory(this.customDir);
+  }
+
+  /**
+   * Load all services (built-in + custom).
+   */
+  async loadAllServices(): Promise<ServiceDefinition[]> {
+    const [builtIn, custom] = await Promise.all([
+      this.loadBuiltInServices(),
+      this.loadCustomServices()
+    ]);
+
+    return [...builtIn, ...custom];
+  }
+
+  /**
+   * Load a service definition from a directory.
+   */
+  private async loadServiceFromDirectory(serviceDir: string): Promise<ServiceDefinition | null> {
+    const indexPath = path.join(serviceDir, 'index.ts');
+    const jsIndexPath = path.join(serviceDir, 'index.js');
+    const promptPath = path.join(serviceDir, 'prompt.md');
+
+    // Check if index file exists (TypeScript or JavaScript)
+    let modulePath: string;
+    if (fs.existsSync(indexPath)) {
+      modulePath = indexPath;
+    } else if (fs.existsSync(jsIndexPath)) {
+      modulePath = jsIndexPath;
+    } else {
+      throw new Error(`No index.ts or index.js found in ${serviceDir}`);
+    }
+
+    try {
+      // Dynamic import the service module
+      const serviceModule = await import(modulePath);
+      const serviceDefinition = serviceModule.default || serviceModule;
+
+      if (!serviceDefinition || typeof serviceDefinition !== 'object') {
+        throw new Error('Service must export a default ServiceDefinition object');
+      }
+
+      // Validate required fields
+      if (!serviceDefinition.id) {
+        throw new Error('Service definition must have an id');
+      }
+
+      // Add prompt file path if it exists
+      if (fs.existsSync(promptPath)) {
+        serviceDefinition.promptFile = promptPath;
+      }
+
+      return serviceDefinition as ServiceDefinition;
+    } catch (error) {
+      throw new Error(`Failed to import service from ${modulePath}: ${error}`);
+    }
+  }
+
+  /**
+   * Create a new custom service directory.
+   */
+  createCustomServiceDirectory(serviceId: string): string {
+    const serviceDir = path.join(this.customDir, serviceId);
+
+    // Ensure custom services directory exists
+    fs.mkdirSync(this.customDir, { recursive: true });
+
+    // Create service directory
+    if (fs.existsSync(serviceDir)) {
+      throw new Error(`Service directory ${serviceId} already exists`);
+    }
+
+    fs.mkdirSync(serviceDir);
+    return serviceDir;
+  }
+
+  /**
+   * Create a basic service template.
+   */
+  createServiceTemplate(serviceId: string, options: {
+    name: string;
+    description: string;
+    defaultPrice: number;
+    category?: string;
+    hasHandler?: boolean;
+  }): void {
+    const serviceDir = this.createCustomServiceDirectory(serviceId);
+
+    // Create index.ts
+    const indexContent = this.generateServiceTemplate(serviceId, options);
+    fs.writeFileSync(path.join(serviceDir, 'index.ts'), indexContent);
+
+    // Create prompt.md
+    const promptContent = this.generatePromptTemplate(serviceId, options);
+    fs.writeFileSync(path.join(serviceDir, 'prompt.md'), promptContent);
+
+    // Create handler.ts if requested
+    if (options.hasHandler) {
+      const handlerContent = this.generateHandlerTemplate(serviceId, options);
+      fs.writeFileSync(path.join(serviceDir, 'handler.ts'), handlerContent);
+    }
+  }
+
+  /**
+   * Generate service definition template.
+   */
+  private generateServiceTemplate(serviceId: string, options: {
+    name: string;
+    description: string;
+    defaultPrice: number;
+    category?: string;
+    hasHandler?: boolean;
+  }): string {
+    return `/**
+ * ${options.name} service definition.
+ */
+
+import { ServiceDefinition${options.hasHandler ? ', ServiceHandler' : ''} } from '../../types.js';
+${options.hasHandler ? `import { ${serviceId.replace(/-/g, '')}Handler } from './handler.js';` : ''}
+
+const ${serviceId.replace(/-/g, '')}Service: ServiceDefinition = {
+  id: '${serviceId}',
+  name: '${options.name}',
+  description: '${options.description}',
+  defaultPrice: ${options.defaultPrice},${options.category ? `\n  category: '${options.category}',` : ''}
+  inputSchema: {
+    type: 'object',
+    properties: {
+      // Define your input schema here
+      query: {
+        type: 'string',
+        description: 'Query or input for the service'
+      }
+    },
+    required: ['query']
+  }${options.hasHandler ? `,\n  handler: ${serviceId.replace(/-/g, '')}Handler` : ''}
+};
+
+export default ${serviceId.replace(/-/g, '')}Service;
+`;
+  }
+
+  /**
+   * Generate prompt template.
+   */
+  private generatePromptTemplate(serviceId: string, options: {
+    name: string;
+    description: string;
+  }): string {
+    return `# ${options.name} Service
+
+You are processing a request for the "${serviceId}" service.
+
+## Service Description
+${options.description}
+
+## Input
+The user has provided the following input:
+\`\`\`json
+{{input}}
+\`\`\`
+
+## Instructions
+Process the user's request and provide a helpful response based on the service description.
+Format your response as a structured result that can be easily parsed and used.
+
+## Response Format
+Provide your response in this format:
+\`\`\`json
+{
+  "result": "your processed result here",
+  "metadata": {
+    "processingTime": "time taken",
+    "version": "1.0"
+  }
+}
+\`\`\`
+`;
+  }
+
+  /**
+   * Generate handler template.
+   */
+  private generateHandlerTemplate(serviceId: string, options: {
+    name: string;
+  }): string {
+    return `/**
+ * ${options.name} service handler.
+ */
+
+import { ServiceHandler, ValidationResult, ServiceContext, ServiceResult } from '../../types.js';
+
+export const ${serviceId.replace(/-/g, '')}Handler: ServiceHandler = {
+  /**
+   * Validate service input.
+   */
+  validate(input: any): ValidationResult {
+    if (!input || typeof input !== 'object') {
+      return { valid: false, error: 'Input must be an object' };
+    }
+
+    if (!input.query || typeof input.query !== 'string') {
+      return { valid: false, error: 'Query must be a non-empty string' };
+    }
+
+    // Add more validation as needed
+    return { valid: true, sanitized: input };
+  },
+
+  /**
+   * Process the service request.
+   */
+  async process(input: any, context: ServiceContext): Promise<ServiceResult> {
+    try {
+      const startTime = Date.now();
+
+      // Your service logic here
+      const result = {
+        query: input.query,
+        response: 'This is a template response. Implement your logic here.',
+        timestamp: new Date().toISOString()
+      };
+
+      const processingTime = Date.now() - startTime;
+
+      return {
+        success: true,
+        data: result,
+        metadata: {
+          processingTime,
+          version: '1.0'
+        }
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+};
+`;
+  }
+
+  /**
+   * Get the built-in services directory.
+   */
+  getBuiltInDirectory(): string {
+    return this.builtInDir;
+  }
+
+  /**
+   * Get the custom services directory.
+   */
+  getCustomDirectory(): string {
+    return this.customDir;
+  }
+
+  /**
+   * Check if a service directory exists.
+   */
+  serviceExists(serviceId: string, inCustom = false): boolean {
+    const baseDir = inCustom ? this.customDir : this.builtInDir;
+    return fs.existsSync(path.join(baseDir, serviceId));
+  }
+}
+
+/**
+ * Global service loader instance.
+ */
+export const serviceLoader = new DefaultServiceLoader();

package/src/services/manager.ts

@@ -0,0 +1,304 @@
+/**
+ * Service manager implementation.
+ *
+ * This orchestrates the service system, providing a high-level interface
+ * for service execution while keeping payment and relay logic separate.
+ */
+
+import { ServiceManager, ServiceDefinition, ServiceContext, ServiceResult, ValidationResult } from './types.js';
+import { serviceRegistry, DefaultServiceRegistry } from './registry.js';
+import { serviceLoader, DefaultServiceLoader } from './loader.js';
+
+/**
+ * Default service manager implementation.
+ */
+export class DefaultServiceManager implements ServiceManager {
+  public readonly registry: DefaultServiceRegistry;
+  public readonly loader: DefaultServiceLoader;
+  private initialized = false;
+
+  constructor() {
+    this.registry = serviceRegistry;
+    this.loader = serviceLoader;
+  }
+
+  /**
+   * Initialize the service system.
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    // Load all services
+    const services = await this.loader.loadAllServices();
+
+    // Register all services
+    for (const service of services) {
+      try {
+        this.registry.register(service);
+      } catch (error) {
+        console.warn(`Failed to register service '${service.id}':`, error);
+      }
+    }
+
+    this.initialized = true;
+
+    console.log(`Service manager initialized with ${this.registry.count()} services`);
+  }
+
+  /**
+   * Execute a service request.
+   */
+  async execute(serviceId: string, input: any, context: ServiceContext): Promise<ServiceResult> {
+    if (!this.initialized) {
+      throw new Error('Service manager not initialized');
+    }
+
+    const service = this.registry.get(serviceId);
+    if (!service) {
+      return {
+        success: false,
+        error: `Service '${serviceId}' not found`
+      };
+    }
+
+    // Validate input if service has a handler
+    if (service.handler) {
+      const validation = service.handler.validate(input);
+      if (!validation.valid) {
+        return {
+          success: false,
+          error: `Input validation failed: ${validation.error}`
+        };
+      }
+
+      // Use sanitized input if provided
+      input = validation.sanitized || input;
+    }
+
+    // Execute the service
+    try {
+      if (service.handler) {
+        // Use custom handler
+        return await service.handler.process(input, context);
+      } else {
+        // Service uses agent mode - return success with input for agent processing
+        return {
+          success: true,
+          data: {
+            serviceId,
+            input,
+            mode: 'agent',
+            promptFile: service.promptFile
+          },
+          metadata: {
+            version: '1.0',
+            executionMode: 'agent'
+          }
+        };
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+        metadata: {
+          serviceId,
+          errorType: 'execution_error'
+        }
+      };
+    }
+  }
+
+  /**
+   * Validate service input.
+   */
+  validate(serviceId: string, input: any): ValidationResult {
+    const service = this.registry.get(serviceId);
+    if (!service) {
+      return {
+        valid: false,
+        error: `Service '${serviceId}' not found`
+      };
+    }
+
+    // Use service handler validation if available
+    if (service.handler) {
+      return service.handler.validate(input);
+    }
+
+    // Default validation for agent-mode services
+    if (service.inputSchema) {
+      return this.validateAgainstSchema(input, service.inputSchema);
+    }
+
+    // No validation required
+    return { valid: true };
+  }
+
+  /**
+   * Reload all services.
+   */
+  async reload(): Promise<void> {
+    // Clear existing services
+    this.registry.clear();
+    this.initialized = false;
+
+    // Reinitialize
+    await this.initialize();
+  }
+
+  /**
+   * Get service for agent-mode processing.
+   */
+  getServiceForAgentMode(serviceId: string): {
+    service: ServiceDefinition;
+    promptFile?: string;
+  } | null {
+    const service = this.registry.get(serviceId);
+    if (!service) {
+      return null;
+    }
+
+    return {
+      service,
+      promptFile: service.promptFile
+    };
+  }
+
+  /**
+   * Check if service is available.
+   */
+  isServiceAvailable(serviceId: string): boolean {
+    return this.registry.has(serviceId);
+  }
+
+  /**
+   * Get service execution mode.
+   */
+  getServiceMode(serviceId: string): 'handler' | 'agent' | null {
+    const service = this.registry.get(serviceId);
+    if (!service) {
+      return null;
+    }
+
+    return service.handler ? 'handler' : 'agent';
+  }
+
+  /**
+   * Get all available services for discovery.
+   */
+  getAvailableServices(): Array<{
+    id: string;
+    name: string;
+    description: string;
+    defaultPrice: number;
+    category?: string;
+    mode: 'handler' | 'agent';
+  }> {
+    return this.registry.list().map(service => ({
+      id: service.id,
+      name: service.name,
+      description: service.description,
+      defaultPrice: service.defaultPrice,
+      category: service.category,
+      mode: service.handler ? 'handler' : 'agent'
+    }));
+  }
+
+  /**
+   * Validate input against JSON schema.
+   */
+  private validateAgainstSchema(input: any, schema: object): ValidationResult {
+    // Simple schema validation - in production, you might use a library like ajv
+    try {
+      const schemaObj = schema as any;
+
+      if (schemaObj.type === 'object') {
+        if (!input || typeof input !== 'object') {
+          return { valid: false, error: 'Input must be an object' };
+        }
+
+        // Check required properties
+        if (schemaObj.required && Array.isArray(schemaObj.required)) {
+          for (const requiredProp of schemaObj.required) {
+            if (!(requiredProp in input)) {
+              return { valid: false, error: `Missing required property: ${requiredProp}` };
+            }
+          }
+        }
+
+        // Basic type checking for properties
+        if (schemaObj.properties) {
+          for (const [propName, propSchema] of Object.entries(schemaObj.properties)) {
+            if (propName in input) {
+              const propType = (propSchema as any).type;
+              const actualType = typeof input[propName];
+
+              if (propType && propType !== actualType) {
+                return { valid: false, error: `Property '${propName}' must be of type ${propType}` };
+              }
+            }
+          }
+        }
+      }
+
+      return { valid: true, sanitized: input };
+    } catch (error) {
+      return { valid: false, error: `Schema validation error: ${error}` };
+    }
+  }
+
+  /**
+   * Get service statistics.
+   */
+  getStatistics(): {
+    totalServices: number;
+    handlerServices: number;
+    agentServices: number;
+    servicesByCategory: Record<string, number>;
+  } {
+    const services = this.registry.list();
+    const stats = {
+      totalServices: services.length,
+      handlerServices: 0,
+      agentServices: 0,
+      servicesByCategory: {} as Record<string, number>
+    };
+
+    for (const service of services) {
+      // Count by execution mode
+      if (service.handler) {
+        stats.handlerServices++;
+      } else {
+        stats.agentServices++;
+      }
+
+      // Count by category
+      const category = service.category || 'uncategorized';
+      stats.servicesByCategory[category] = (stats.servicesByCategory[category] || 0) + 1;
+    }
+
+    return stats;
+  }
+}
+
+/**
+ * Global service manager instance.
+ */
+export const serviceManager = new DefaultServiceManager();
+
+/**
+ * Initialize the service system.
+ * This should be called once during application startup.
+ */
+export async function initializeServiceSystem(): Promise<void> {
+  await serviceManager.initialize();
+}
+
+/**
+ * Get service manager instance.
+ */
+export function getServiceManager(): DefaultServiceManager {
+  return serviceManager;
+}