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

package/examples/example-agent/index.js

@@ -1,102 +0,0 @@
-#!/usr/bin/env node
-
-// npm install ../../kadi.build-core-0.0.1-alpha.2.tgz
-import { loadAbility } from '@kadi.build/core';
-
-async function main() {
-  console.log('🎬 KADI LoadAbility Mechanism Demo');
-  console.log('====================================================');
-
-  // === WORKING ABILITIES ===
-  console.log('\n✅ === WORKING ABILITIES ===');
-
-  // try {
-  //   console.log('\n🔧 Loading hash-go ability (Go)...');
-  //   let goAbility = await loadAbility('hash-go');
-  //   console.log('Available methods:', goAbility.__list());
-  //   const hashGoResult = await goAbility.digest({
-  //     text: 'I am calling hash-go digest method from Javascript',
-  //     algo: 'sha256'
-  //   });
-  //   console.log('Go digest result:', hashGoResult);
-
-  //   // This is done on purpose to test the error handling
-  //   const someFunctionResult = await goAbility.someFunction({
-  //     message: 'this function does not exist'
-  //   });
-
-  //   console.log('Go ability someFunction result:', someFunctionResult);
-  // } catch (err) {
-  //   console.error('❌ hash-go failed:', err.message);
-  // }
-
-  try {
-    console.log('\n🔧 Loading echo-js ability using native (Javascript)...');
-    let echoJsAbility = await loadAbility('echo-js');
-
-    // Subscribe first
-    echoJsAbility.events.on('echo:test-event', (data) => {
-      console.log(`[NATIVE] echo:test-event received:`, data);
-    });
-
-    console.log('Available methods:', echoJsAbility.__list());
-    const echoJsResult = await echoJsAbility.echo({
-      message: 'I am calling echo-js echo method from Javascript'
-    });
-    console.log('Echo-js echo result:', echoJsResult);
-  } catch (err) {
-    console.error('❌ echo-js failed:', err.message);
-  }
-
-  try {
-    console.log('\n🔧 Loading echo-js ability using stdio (Javascript)...');
-    let echoJsAbility = await loadAbility('echo-js', 'stdio');
-    console.log('Available methods:', echoJsAbility.__list());
-
-    // Subscribe first
-    echoJsAbility.events.on('echo:test-event', (data) => {
-      console.log(`[STDIO] echo:test-event received:`, data);
-    });
-    // Now trigger the method that emits the event
-    const echoJsResult = await echoJsAbility.echo({
-      message: 'I am calling echo-js echo method from Javascript'
-    });
-
-    console.log('Echo-js echo result:', echoJsResult);
-  } catch (err) {
-    console.error('❌ echo-js failed:', err.message);
-  }
-
-  // try {
-  //   console.log('\n🔧 Loading echo-js ability using broker (Javascript)...');
-  //   let echoJsAbility = await loadAbility('echo-js', 'broker');
-  //   console.log('Available methods:', echoJsAbility.__list());
-  //   const echoJsResult = await echoJsAbility.echo({
-  //     message:
-  //       'I am calling echo-js echo method from Javascript - ability speaking through Broker - open your browser to http://kadi.build/network.html to see the network'
-  //   });
-  //   console.log('Echo-js ability result:', echoJsResult);
-
-  //   const sayMessageResult = await echoJsAbility.say_message({
-  //     message: 'I am calling echo-js say_message method from Javascript'
-  //   });
-  //   console.log('say_message result:', sayMessageResult);
-  // } catch (err) {
-  //   console.error('❌ echo-js failed:', err.message);
-  // }
-}
-
-// Start the agent
-main().catch((err) => {
-  // Display a concise, user-friendly message
-  console.error('❌ ' + (err?.message || err));
-  // Exit gracefully (0) so parent runner does not
-  // print an additional stack trace
-  process.exit(0);
-});
-
-// Handle graceful shutdown
-process.on('SIGINT', () => {
-  console.log('\nShutting down...');
-  process.exit(0);
-});

package/examples/example-agent/package-lock.json

@@ -1,93 +0,0 @@
-{
-  "name": "example-agent",
-  "version": "0.0.1",
-  "lockfileVersion": 3,
-  "requires": true,
-  "packages": {
-    "": {
-      "name": "example-agent",
-      "version": "0.0.1",
-      "license": "ISC",
-      "dependencies": {
-        "@kadi.build/core": "file:kadi.build-core-0.0.1-alpha.2.tgz"
-      }
-    },
-    "node_modules/@kadi.build/core": {
-      "version": "0.0.1-alpha.2",
-      "resolved": "file:kadi.build-core-0.0.1-alpha.2.tgz",
-      "integrity": "sha512-CLLvPCq6ZiUWb0pSIIUfBJdpbsB23J8Ie0lZ8OynTO9j98cOfUISMIBo4iL3vgMVA7E0UNf1hD+whVBWQSdqeA==",
-      "license": "MIT",
-      "dependencies": {
-        "chalk": "^5.5.0",
-        "debug": "^4.4.1",
-        "events": "^3.3.0",
-        "ws": "^8.16.0"
-      }
-    },
-    "node_modules/chalk": {
-      "version": "5.6.0",
-      "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.0.tgz",
-      "integrity": "sha512-46QrSQFyVSEyYAgQ22hQ+zDa60YHA4fBstHmtSApj1Y5vKtG27fWowW03jCk5KcbXEWPZUIR894aARCA/G1kfQ==",
-      "license": "MIT",
-      "engines": {
-        "node": "^12.17.0 || ^14.13 || >=16.0.0"
-      },
-      "funding": {
-        "url": "https://github.com/chalk/chalk?sponsor=1"
-      }
-    },
-    "node_modules/debug": {
-      "version": "4.4.1",
-      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.1.tgz",
-      "integrity": "sha512-KcKCqiftBJcZr++7ykoDIEwSa3XWowTfNPo92BYxjXiyYEVrUQh2aLyhxBCwww+heortUFxEJYcRzosstTEBYQ==",
-      "license": "MIT",
-      "dependencies": {
-        "ms": "^2.1.3"
-      },
-      "engines": {
-        "node": ">=6.0"
-      },
-      "peerDependenciesMeta": {
-        "supports-color": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/events": {
-      "version": "3.3.0",
-      "resolved": "https://registry.npmjs.org/events/-/events-3.3.0.tgz",
-      "integrity": "sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=0.8.x"
-      }
-    },
-    "node_modules/ms": {
-      "version": "2.1.3",
-      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
-      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
-      "license": "MIT"
-    },
-    "node_modules/ws": {
-      "version": "8.18.3",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.18.3.tgz",
-      "integrity": "sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=10.0.0"
-      },
-      "peerDependencies": {
-        "bufferutil": "^4.0.1",
-        "utf-8-validate": ">=5.0.2"
-      },
-      "peerDependenciesMeta": {
-        "bufferutil": {
-          "optional": true
-        },
-        "utf-8-validate": {
-          "optional": true
-        }
-      }
-    }
-  }
-}

package/examples/example-agent/package.json

@@ -1,17 +0,0 @@
-{
-  "name": "example-agent",
-  "version": "0.0.1",
-  "main": "index.js",
-  "type": "module",
-  "scripts": {
-    "start": "node index.js",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": "",
-  "dependencies": {
-    "@kadi.build/core": "file:kadi.build-core-0.0.1-alpha.2.tgz"
-  }
-}

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;