@kadi.build/core 0.0.1-alpha.1 → 0.0.1-alpha.3

package/src/KadiAbility.js

@@ -0,0 +1,478 @@
+import { EventEmitter } from 'events';
+import { StdioRpcServer } from './servers/StdioRpcServer.js';
+import { BrokerRpcServer } from './servers/BrokerRpcServer.js';
+import fs from 'fs';
+import path from 'path';
+import { createComponentLogger } from './utils/logger.js';
+
+/**
+ * Factory for creating RPC servers based on protocol
+ */
+class RpcServerFactory {
+  static create(protocol, options = {}) {
+    switch (protocol?.toLowerCase()) {
+      case 'native':
+        return undefined; // Native protocol doesn't need an RPC server
+      case 'stdio':
+        return new StdioRpcServer(options);
+      case 'broker':
+        return new BrokerRpcServer(options);
+      default:
+        // Default to stdio for backward compatibility
+        return new StdioRpcServer(options);
+    }
+  }
+}
+
+/**
+ * KadiAbility - High-level, user-friendly wrapper around RpcServer
+ *
+ * This class provides a clean API for creating abilities and handles
+ * transport selection automatically based on configuration.
+ *
+ * @example
+ * const ability = new KadiAbility({ name: 'my-ability' });
+ * ability
+ *   .method('doSomething', async (params) => {
+ *     return { result: 'done' };
+ *   })
+ *   .serve();
+ */
+export class KadiAbility extends EventEmitter {
+  /**
+   * Create a new KadiAbility instance
+   *
+   * @param {Object} options - Configuration options
+   * @param {string} options.name - Ability name
+   * @param {string} options.version - Ability version
+   * @param {string} options.description - Ability description
+   * @param {string} options.scope - Ability scope - Same as the agent's. global if not specified
+   * @param {string} options.abilityAgentJSON - Path to the ability agent.json file
+   * @param {string} options.protocol - Transport mode: 'stdio' or 'broker'
+   */
+  constructor(options = {}) {
+    super();
+
+    // Store basic ability information
+    this.name = options.name || 'unnamed-ability';
+    this.version = options.version || '1.0.0';
+    this.description = options.description || '';
+    this.protocol = options.protocol || process.env.KADI_PROTOCOL || 'native';
+    this.abilityAgentJSON = options.abilityAgentJSON;
+    this.scope = options.scope || 'global';
+
+    this.logger = createComponentLogger('KadiAbility');
+    this.logger.lifecycle(
+      'constructor',
+      `Creating ability: ${this.name}@${this.version}`
+    );
+    this.logger.trace('constructor options', {
+      name: this.name,
+      version: this.version,
+      protocol: options.protocol,
+      scope: this.scope
+    });
+
+    // Create RPC server for handling requests for the given protocol
+    this.rpcServer = RpcServerFactory.create(this.protocol, {
+      maxBufferSize: options.maxBufferSize,
+      brokerUrl: options.brokerUrl,
+      ...options
+    });
+
+    this.methodHandlers = new Map(); // method name -> function
+    this.methodMCPSchemas = new Map(); // method name -> schema object
+
+    // Forward events from RPC server (only if server exists)
+    if (this.rpcServer) {
+      this.rpcServer.on('start', (data) =>
+        this.emit('start', { ...data, protocol: this.protocol })
+      );
+      this.rpcServer.on('error', (error) => this.emit('error', error));
+      this.rpcServer.on('stop', () => this.emit('stop'));
+      this.rpcServer.on('request', (data) => this.emit('request', data));
+      this.rpcServer.on('response', (data) => this.emit('response', data));
+    }
+  }
+
+  /**
+   * Register a method with the ability
+   *
+   * @param {string} name - Method name
+   * @param {Function} handler - Handler function that processes the request
+   * @param {Object} [optionalMCPSchema] - Optional MCP schema for the method
+   * @returns {KadiAbility} - For chaining
+   *
+   * @example
+   * // Simple method
+   * ability.method('echo', async ({ message }) => ({ echo: message }));
+   *
+   * // Method with MCP schema
+   * ability.method('format', async ({ text }) => ({ formatted: text.toUpperCase() }), {
+   *   description: 'Format text to uppercase',
+   *   inputSchema: {
+   *     type: 'object',
+   *     properties: {
+   *       text: { type: 'string', description: 'Text to format' }
+   *     },
+   *     required: ['text']
+   *   },
+   *   outputSchema: {
+   *     type: 'object',
+   *     properties: {
+   *       formatted: { type: 'string', description: 'Formatted text' }
+   *     }
+   *   }
+   * });
+   */
+  method(name, handler, optionalMCPSchema) {
+    if (typeof name !== 'string') {
+      throw new TypeError('Method name must be a string');
+    }
+
+    if (typeof handler !== 'function') {
+      throw new TypeError('Method handler must be a function');
+    }
+
+    this.logger.methodCall('method', `Registering method: ${name}`);
+    if (optionalMCPSchema) {
+      this.logger.trace('method schema', { name, schema: optionalMCPSchema });
+    }
+
+    this.methodHandlers.set(name, handler);
+
+    if (optionalMCPSchema) {
+      this.methodMCPSchemas.set(name, optionalMCPSchema);
+    }
+
+    return this;
+  }
+
+  /**
+   * Publish an event to the connected agent/parent process
+   *
+   * Events are fire-and-forget notifications that flow from ability to agent.
+   * The transport layer determines how events are delivered:
+   * - Native: Direct EventEmitter (in-process)
+   * - Stdio: JSON-RPC notification with __kadi_event method
+   * - Broker: kadi.event message via WebSocket
+   *
+   * @param {string} eventName - Name of the event to publish
+   * @param {any} data - Event data payload (should be JSON-serializable for remote transports)
+   * @returns {void}
+   *
+   * @example
+   * // Publish a simple event
+   * ability.publishEvent('server:started', { port: 3000 });
+   *
+   * // Publish progress updates
+   * ability.publishEvent('download:progress', {
+   *   file: 'data.zip',
+   *   progress: 0.75,
+   *   bytesDownloaded: 75000,
+   *   totalBytes: 100000
+   * });
+   *
+   * // Publish error events
+   * ability.publishEvent('error', {
+   *   message: 'Connection failed',
+   *   code: 'ECONNREFUSED'
+   * });
+   */
+  publishEvent(eventName, data = {}) {
+    if (typeof eventName !== 'string' || !eventName) {
+      throw new TypeError('Event name must be a non-empty string');
+    }
+
+    this.logger.trace('publishEvent', `Publishing event: ${eventName}`);
+    this.logger.trace('publishEvent data', { eventName, data });
+
+    // For native protocol, emit directly on this EventEmitter
+    // The agent will have direct access to this instance
+    if (this.protocol === 'native') {
+      this.logger.trace('publishEvent', 'Using native EventEmitter for event');
+      // Emit with a special prefix to distinguish from internal events
+      this.emit('ability:event', { eventName, data });
+      return;
+    }
+
+    // For remote protocols, delegate to the RPC server
+    if (this.rpcServer && typeof this.rpcServer.publishEvent === 'function') {
+      this.logger.trace(
+        'publishEvent',
+        `Delegating to ${this.protocol} RPC server`
+      );
+      this.rpcServer.publishEvent(eventName, data);
+    } else {
+      this.logger.warn(
+        'publishEvent',
+        `Cannot publish event: RPC server (${this.protocol}) does not support event publishing`
+      );
+    }
+  }
+
+  /**
+   * Get all registered method names (excluding internal methods)
+   */
+  getMethodNames() {
+    return Array.from(this.methodHandlers.keys()).filter(
+      (name) => !name.startsWith('__kadi_')
+    );
+  }
+
+  /**
+   * Check if a method is registered
+   */
+  hasMethod(name) {
+    return this.methodHandlers.has(name);
+  }
+
+  /**
+   * Get method handler
+   */
+  getMethodHandler(name) {
+    return this.methodHandlers.get(name);
+  }
+
+  /**
+   * Get method schema (if available)
+   */
+  getMethodSchema(name) {
+    return this.methodMCPSchemas.get(name);
+  }
+
+  /**
+   * Extract tool definitions for broker capability registration
+   * Combines schemas from agent.json exports and inline schemas
+   *
+   * @returns {Array<Object>} - Array of tool definitions for broker
+   */
+  async extractToolsForBroker() {
+    this.logger.methodCall(
+      'extractToolsForBroker',
+      'Extracting tools for broker registration'
+    );
+
+    const tools = [];
+
+    // console.error(`Registered handlers: ${Array.from(this.methodHandlers.keys())}`);
+    // console.error(`Schema map: ${Array.from(this.methodMCPSchemas.entries())}`);
+
+    // 1. Try to load agent.json exports
+    const agentJsonExports = await this._loadAgentJsonExports();
+
+    this.logger.trace(
+      'extractToolsForBroker',
+      `Loaded ${agentJsonExports.length} exports from agent.json`
+    );
+
+    // 2. Build tools array from registered methods
+    for (const [methodName, handler] of this.methodHandlers) {
+      if (methodName.startsWith('__kadi_')) continue; // Skip internal methods
+
+      let schema = this.methodMCPSchemas.get(methodName);
+
+      // Resolve schema source
+      if (!schema) {
+        // Look in agent.json exports
+        schema = agentJsonExports.find((exp) => exp.name === methodName);
+      }
+
+      if (!schema) {
+        this.logger.warn(
+          'extractToolsForBroker',
+          `No schema found for method '${methodName}', skipping broker registration`
+        );
+
+        continue;
+      }
+
+      tools.push({
+        name: methodName,
+        description: schema.description || `Execute ${methodName}`,
+        inputSchema: schema.inputSchema || { type: 'object' },
+        outputSchema: schema.outputSchema
+      });
+    }
+
+    this.logger.success(
+      'extractToolsForBroker',
+      `Extracted ${tools.length} tools for broker`
+    );
+    return tools;
+  }
+
+  /**
+   * Start serving requests
+   *
+   * @param {Object} options - Serve options
+   * @param {string} options.mode - Override transport mode
+   * @returns {Promise<void>}
+   */
+  async serve(options = {}) {
+    this.logger.lifecycle('serve', `Starting to serve ability: ${this.name}`);
+    this.logger.info(
+      'serve',
+      `Protocol: ${this.protocol}, Methods: ${this.getMethodNames().join(', ')}`
+    );
+    try {
+      // Override protocol if specified in options
+      if (options.mode && options.mode !== this.protocol) {
+        this.logger.info(
+          'serve',
+          `Protocol override: ${this.protocol} -> ${options.mode}`
+        );
+
+        this.protocol = options.mode;
+        this.rpcServer = RpcServerFactory.create(this.protocol, options);
+
+        // Re-wire events for new server (only if server exists)
+        if (this.rpcServer) {
+          this.rpcServer.on('start', (data) =>
+            this.emit('start', { ...data, protocol: this.protocol })
+          );
+          this.rpcServer.on('error', (error) => this.emit('error', error));
+          this.rpcServer.on('stop', () => this.emit('stop'));
+          this.rpcServer.on('request', (data) => this.emit('request', data));
+          this.rpcServer.on('response', (data) => this.emit('response', data));
+        }
+      }
+
+      // Start serving this ability using the RPC server (if it exists)
+      if (this.rpcServer) {
+        await this.rpcServer.serve(this);
+        this.logger.success(
+          'serve',
+          `Successfully started serving ${this.name} via ${this.protocol}`
+        );
+      } else {
+        // For native protocol, just emit start event and keep running
+        this.logger.success(
+          'serve',
+          `Successfully started serving ${this.name} via ${this.protocol} (native mode)`
+        );
+        this.emit('start', {
+          protocol: this.protocol,
+          methods: this.getMethodNames()
+        });
+
+        // Keep the process alive for native protocol
+        // This allows the ability to be imported and used directly
+        return new Promise(() => {
+          // Never resolve - keep the process running
+        });
+      }
+    } catch (error) {
+      this.logError('Failed to start serving', { error: error.message });
+      this.emit('error', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Log a message to stderr (safe for stdio mode since stdout is used for RPC)
+   *
+   * @param {...any} args - Arguments to log
+   */
+  log(...args) {
+    this.logger.info('general', args.join(' '));
+  }
+
+  /**
+   * Log an error to stderr
+   *
+   * @param {...any} args - Arguments to log
+   */
+  logError(...args) {
+    this.logger.error('general', args.join(' '));
+  }
+
+  /**
+   * Load exports from agent.json file
+   *
+   * @returns {Array<Object>} - Array of export definitions
+   * @private
+   */
+  async _loadAgentJsonExports() {
+    this.logger.methodCall(
+      '_loadAgentJsonExports',
+      'Loading agent.json exports'
+    );
+    try {
+      const agentJsonPath = await this._findAgentJson();
+
+      this.logger.trace(
+        '_loadAgentJsonExports',
+        `Found agent.json at: ${agentJsonPath}`
+      );
+
+      const agentJson = JSON.parse(fs.readFileSync(agentJsonPath, 'utf8'));
+
+      const exportCount = agentJson.exports?.length || 0;
+      this.logger.success(
+        '_loadAgentJsonExports',
+        `Loaded ${exportCount} exports`
+      );
+
+      return agentJson.exports || [];
+    } catch (err) {
+      this.logger.warn(
+        '_loadAgentJsonExports',
+        `Could not load agent.json exports: ${err.message}`
+      );
+
+      return [];
+    }
+  }
+
+  /**
+   * Find agent.json file in current directory or parent directories
+   *
+   * @returns {string} - Path to agent.json file
+   * @private
+   */
+  async _findAgentJson() {
+    this.logger.methodCall('_findAgentJson', 'Searching for agent.json file');
+    this.logger.trace(
+      '_findAgentJson',
+      `Current working directory: ${process.cwd()}`
+    );
+
+    const possiblePaths = [
+      // Use explicit path if provided
+      this.abilityAgentJSON,
+      // Standard locations
+      path.join(process.cwd(), 'agent.json'),
+      path.join(path.dirname(process.argv[1]), 'agent.json'), // Same directory as the script
+      path.join(process.cwd(), '..', 'agent.json'),
+      path.join(process.cwd(), '..', '..', 'agent.json')
+    ].filter(Boolean); // Remove undefined entries
+
+    this.logger.trace(
+      '_findAgentJson',
+      `Checking paths: ${possiblePaths.join(', ')}`
+    );
+
+    for (const agentPath of possiblePaths) {
+      this.logger.trace('_findAgentJson', `Checking: ${agentPath}`);
+
+      if (fs.existsSync(agentPath)) {
+        this.logger.success(
+          '_findAgentJson',
+          `Found agent.json at: ${agentPath}`
+        );
+
+        return agentPath;
+      }
+    }
+
+    this.logger.error(
+      '_findAgentJson',
+      'agent.json not found in any checked locations'
+    );
+
+    throw new Error('agent.json not found in any of the checked locations');
+  }
+}
+
+export default KadiAbility;

package/src/index.js

@@ -0,0 +1,65 @@
+// Update your existing index.js to export the new classes
+export { KadiAbility } from './KadiAbility.js';
+
+// Export logging facilities
+export { createLogger, loggers, isDebugEnabled } from './utils/logger.js';
+
+// Export servers for advanced users
+export { BaseRpcServer } from './servers/BaseRpcServer.js';
+export { StdioRpcServer } from './servers/StdioRpcServer.js';
+export { BrokerRpcServer } from './servers/BrokerRpcServer.js';
+
+// Re-export transport utilities (maintain backward compatibility)
+export {
+  StdioFrameReader,
+  StdioFrameWriter,
+  IpcServer,
+  StdioTransport,
+  BrokerTransport
+} from './transport/IpcMessageBuilder.js';
+
+export {
+  Broker,
+  IdFactory,
+  toBase64Der
+} from './transport/BrokerMessageBuilder.js';
+
+// Export loadAbility from its own file
+export { loadAbility } from './loadAbility.js';
+
+// Your existing utility functions from utils files
+export {
+  getAbilityJSON,
+  getAbilityJSONPath,
+  getAbilitiesDir,
+  getProjectJSON,
+  getProjectJSONPath,
+  getKadiCoreJSON,
+  getKadiCoreJSONPath,
+  getKadiJSON,
+  getKadiJSONPath,
+  getKadiExecPath,
+  getKadiInstallPath,
+  saveAgentJSON,
+  getAbilityVersionFromArray,
+  KADI_API_URL,
+  SEARCH_API_URL,
+  GET_API_URL
+} from './utils/agentUtils.js';
+
+export { runExecCommand, runSpawnCommand } from './utils/commandUtils.js';
+
+export {
+  KADI_BROKERS,
+  KADI_BROKER_URL,
+  getBrokerUrl,
+  getBrokerNames,
+  getDefaultBrokerName,
+  setActiveBroker,
+  getActiveBrokerName,
+  getActiveBrokerUrl,
+  findAbilityVersionByName
+} from './utils/configUtils.js';
+
+// Note: pathUtils.js exports are internal and not typically needed by external users
+// but you can add them if needed