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

package/src/KadiAbility.js

@@ -1,478 +0,0 @@
-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

@@ -1,65 +0,0 @@
-// 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