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

package/dist/broker/BrokerConnectionManager.js

@@ -0,0 +1,305 @@
+/**
+ * Broker Connection Manager
+ *
+ * Manages multiple broker connections.
+ * Handles connection lifecycle, failover, and routing.
+ *
+ * @module broker/BrokerConnectionManager
+ */
+import { EventEmitter } from 'events';
+import { KadiError, ErrorCode } from '../types/index.js';
+import { BrokerConnection } from './BrokerConnection.js';
+/**
+ * Broker Connection Manager
+ *
+ * Single responsibility: Manage multiple broker connections.
+ * Does NOT handle:
+ * - Protocol logic (that's BrokerProtocol's job)
+ * - Tool registration/invocation (that's ToolRegistry/Client's job)
+ *
+ * @example
+ * ```typescript
+ * const manager = new BrokerConnectionManager();
+ *
+ * // Add brokers
+ * await manager.connect({
+ *   url: 'ws://localhost:8080',
+ *   name: 'local'
+ * });
+ *
+ * await manager.connect({
+ *   url: 'wss://prod.example.com',
+ *   name: 'production'
+ * });
+ *
+ * // Get a connection
+ * const connection = manager.getConnection('local');
+ *
+ * // Get default connection
+ * const defaultConn = manager.getDefaultConnection();
+ * ```
+ */
+export class BrokerConnectionManager extends EventEmitter {
+    /**
+     * Active broker connections (name -> connection)
+     */
+    connections = new Map();
+    /**
+     * Default broker name
+     */
+    defaultBrokerName = null;
+    /**
+     * Connect to a broker
+     *
+     * @param config - Broker configuration
+     * @param setAsDefault - Set this as the default broker
+     * @returns The established connection
+     *
+     * @throws {KadiError} If connection fails
+     *
+     * @example
+     * ```typescript
+     * const connection = await manager.connect({
+     *   url: 'ws://localhost:8080',
+     *   name: 'local'
+     * }, true);
+     * ```
+     */
+    async connect(config, setAsDefault = false) {
+        // Check if already connected
+        if (this.connections.has(config.name)) {
+            const existing = this.connections.get(config.name);
+            if (existing.isConnected) {
+                return existing;
+            }
+            // Remove stale connection
+            this.connections.delete(config.name);
+        }
+        // Create new connection
+        const connection = new BrokerConnection(config);
+        // Set up event forwarding
+        connection.on('connected', () => {
+            this.emit('brokerConnected', config.name);
+        });
+        connection.on('disconnected', (code, reason) => {
+            this.emit('brokerDisconnected', config.name, code, reason);
+        });
+        connection.on('error', (error) => {
+            this.emit('brokerError', config.name, error);
+        });
+        connection.on('message', (message) => {
+            this.emit('brokerMessage', config.name, message);
+        });
+        // Connect
+        await connection.connect();
+        // Store connection
+        this.connections.set(config.name, connection);
+        // Set as default if requested or if it's the first connection
+        if (setAsDefault || this.connections.size === 1) {
+            this.defaultBrokerName = config.name;
+        }
+        return connection;
+    }
+    /**
+     * Connect to multiple brokers
+     *
+     * @param configs - Array of broker configurations
+     * @param defaultBrokerName - Name of the default broker
+     * @returns Array of established connections
+     *
+     * @throws {KadiError} If any connection fails
+     *
+     * @example
+     * ```typescript
+     * await manager.connectMultiple([
+     *   { url: 'ws://localhost:8080', name: 'local' },
+     *   { url: 'wss://prod.example.com', name: 'prod' }
+     * ], 'local');
+     * ```
+     */
+    async connectMultiple(configs, defaultBrokerName) {
+        const connections = [];
+        for (const config of configs) {
+            const isDefault = config.name === defaultBrokerName;
+            const connection = await this.connect(config, isDefault);
+            connections.push(connection);
+        }
+        return connections;
+    }
+    /**
+     * Disconnect from a broker
+     *
+     * @param brokerName - Name of broker to disconnect from
+     *
+     * @example
+     * ```typescript
+     * await manager.disconnect('local');
+     * ```
+     */
+    async disconnect(brokerName) {
+        const connection = this.connections.get(brokerName);
+        if (!connection) {
+            return;
+        }
+        await connection.disconnect();
+        this.connections.delete(brokerName);
+        // Clear default if this was it
+        if (this.defaultBrokerName === brokerName) {
+            this.defaultBrokerName = this.connections.size > 0
+                ? Array.from(this.connections.keys())[0] ?? null
+                : null;
+        }
+    }
+    /**
+     * Disconnect from all brokers
+     *
+     * @example
+     * ```typescript
+     * await manager.disconnectAll();
+     * ```
+     */
+    async disconnectAll() {
+        const disconnectPromises = Array.from(this.connections.keys()).map(name => this.disconnect(name));
+        await Promise.all(disconnectPromises);
+    }
+    /**
+     * Get a broker connection by name
+     *
+     * @param brokerName - Name of the broker
+     * @returns The connection or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const conn = manager.getConnection('local');
+     * if (conn) {
+     *   await conn.sendRequest(...);
+     * }
+     * ```
+     */
+    getConnection(brokerName) {
+        return this.connections.get(brokerName);
+    }
+    /**
+     * Get the default broker connection
+     *
+     * @returns The default connection
+     * @throws {KadiError} If no default broker is set
+     *
+     * @example
+     * ```typescript
+     * const conn = manager.getDefaultConnection();
+     * await conn.sendRequest(...);
+     * ```
+     */
+    getDefaultConnection() {
+        if (!this.defaultBrokerName) {
+            throw new KadiError('No default broker set', ErrorCode.BROKER_NOT_CONNECTED, 503);
+        }
+        const connection = this.connections.get(this.defaultBrokerName);
+        if (!connection) {
+            throw new KadiError(`Default broker '${this.defaultBrokerName}' not found`, ErrorCode.BROKER_NOT_CONNECTED, 503, { defaultBroker: this.defaultBrokerName });
+        }
+        return connection;
+    }
+    /**
+     * Get all broker connections
+     *
+     * @returns Array of all connections
+     *
+     * @example
+     * ```typescript
+     * const connections = manager.getAllConnections();
+     * console.log(`Connected to ${connections.length} brokers`);
+     * ```
+     */
+    getAllConnections() {
+        return Array.from(this.connections.values());
+    }
+    /**
+     * Get all connected broker connections
+     *
+     * @returns Array of connected connections
+     *
+     * @example
+     * ```typescript
+     * const connected = manager.getConnectedBrokers();
+     * ```
+     */
+    getConnectedBrokers() {
+        return this.getAllConnections().filter(conn => conn.isConnected);
+    }
+    /**
+     * Check if connected to a specific broker
+     *
+     * @param brokerName - Broker name
+     * @returns true if connected
+     *
+     * @example
+     * ```typescript
+     * if (manager.isConnected('local')) {
+     *   // Use local broker
+     * }
+     * ```
+     */
+    isConnected(brokerName) {
+        const connection = this.connections.get(brokerName);
+        return connection?.isConnected ?? false;
+    }
+    /**
+     * Check if connected to any broker
+     *
+     * @returns true if connected to at least one broker
+     *
+     * @example
+     * ```typescript
+     * if (!manager.hasConnections()) {
+     *   throw new Error('Not connected to any broker');
+     * }
+     * ```
+     */
+    hasConnections() {
+        return this.getConnectedBrokers().length > 0;
+    }
+    /**
+     * Set the default broker
+     *
+     * @param brokerName - Name of broker to set as default
+     * @throws {KadiError} If broker doesn't exist
+     *
+     * @example
+     * ```typescript
+     * manager.setDefaultBroker('production');
+     * ```
+     */
+    setDefaultBroker(brokerName) {
+        if (!this.connections.has(brokerName)) {
+            throw new KadiError(`Broker '${brokerName}' not found`, ErrorCode.BROKER_NOT_CONNECTED, 404, { brokerName, available: Array.from(this.connections.keys()) });
+        }
+        this.defaultBrokerName = brokerName;
+    }
+    /**
+     * Get default broker name
+     *
+     * @returns Default broker name or null if not set
+     */
+    getDefaultBrokerName() {
+        return this.defaultBrokerName;
+    }
+    /**
+     * Get number of active connections
+     *
+     * @returns Connection count
+     */
+    get connectionCount() {
+        return this.connections.size;
+    }
+    /**
+     * Get broker names
+     *
+     * @returns Array of broker names
+     */
+    getBrokerNames() {
+        return Array.from(this.connections.keys());
+    }
+}
+//# sourceMappingURL=BrokerConnectionManager.js.map

package/dist/broker/BrokerConnectionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrokerConnectionManager.js","sourceRoot":"","sources":["../../src/broker/BrokerConnectionManager.ts"],"names":[],"mappings":"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"}

package/dist/broker/BrokerProtocol.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Broker Protocol
+ *
+ * Implements the KADI broker protocol on top of BrokerConnection.
+ * Handles handshake, authentication, heartbeat, and capability registration.
+ *
+ * @module broker/BrokerProtocol
+ */
+import type { HandshakeParams, HandshakeResult, RegisterCapabilitiesParams, ToolDefinition, ToolInvokeParams, EventSubscribeParams, EventPublishParams } from '../types/index.js';
+import type { BrokerConnection } from './BrokerConnection.js';
+/**
+ * Protocol version
+ */
+export declare const PROTOCOL_VERSION = "2.0.0";
+/**
+ * Broker Protocol
+ *
+ * Implements KADI broker protocol operations.
+ * Sits on top of BrokerConnection and provides high-level protocol methods.
+ *
+ * @example
+ * ```typescript
+ * const protocol = new BrokerProtocol(connection);
+ *
+ * // Perform handshake
+ * const result = await protocol.handshake({
+ *   name: 'my-agent',
+ *   version: '1.0.0',
+ *   protocolVersion: PROTOCOL_VERSION,
+ *   networks: ['global']
+ * });
+ *
+ * // Register capabilities
+ * await protocol.registerCapabilities({
+ *   tools: [
+ *     { name: 'add', description: 'Add numbers' }
+ *   ]
+ * });
+ * ```
+ */
+export declare class BrokerProtocol {
+    /**
+     * Underlying broker connection
+     */
+    private readonly connection;
+    /**
+     * Heartbeat interval timer
+     */
+    private heartbeatTimer;
+    /**
+     * Ed25519 keypair for authentication
+     */
+    private publicKey?;
+    private privateKey?;
+    /**
+     * Create a new BrokerProtocol
+     *
+     * @param connection - Broker connection to use
+     */
+    constructor(connection: BrokerConnection);
+    /**
+     * Perform handshake with broker
+     *
+     * First step in establishing a session with the broker.
+     * The broker will assign an agent ID and confirm protocol compatibility.
+     *
+     * @param params - Handshake parameters
+     * @returns Handshake result with agent ID and broker info
+     *
+     * @throws {KadiError} If handshake fails
+     *
+     * @example
+     * ```typescript
+     * const result = await protocol.handshake({
+     *   name: 'calculator',
+     *   version: '1.0.0',
+     *   protocolVersion: PROTOCOL_VERSION,
+     *   networks: ['global']
+     * });
+     *
+     * console.log('Assigned agent ID:', result.agentId);
+     * ```
+     */
+    handshake(params: HandshakeParams): Promise<HandshakeResult>;
+    /**
+     * Authenticate with broker using Ed25519 signature
+     *
+     * @param nonce - Challenge nonce from broker
+     * @returns Assigned agent ID
+     * @private
+     */
+    private authenticate;
+    /**
+     * Start heartbeat to keep connection alive
+     *
+     * Sends periodic heartbeat messages to the broker.
+     *
+     * @param intervalMs - Heartbeat interval in milliseconds
+     *
+     * @example
+     * ```typescript
+     * protocol.startHeartbeat(30000); // Every 30 seconds
+     * ```
+     */
+    startHeartbeat(intervalMs: number): void;
+    /**
+     * Stop heartbeat
+     *
+     * @example
+     * ```typescript
+     * protocol.stopHeartbeat();
+     * ```
+     */
+    stopHeartbeat(): void;
+    /**
+     * Send a single heartbeat
+     *
+     * @returns Promise that resolves when heartbeat is acknowledged
+     */
+    private sendHeartbeat;
+    /**
+     * Register capabilities (tools) with the broker
+     *
+     * Tells the broker what tools this agent provides.
+     * Other agents can then discover and invoke these tools.
+     *
+     * @param params - Capability registration parameters
+     *
+     * @throws {KadiError} If registration fails
+     *
+     * @example
+     * ```typescript
+     * await protocol.registerCapabilities({
+     *   tools: [
+     *     {
+     *       name: 'calculate',
+     *       description: 'Perform calculations',
+     *       inputSchema: { type: 'object', ... },
+     *       outputSchema: { type: 'object', ... }
+     *     }
+     *   ],
+     *   networks: ['global']
+     * });
+     * ```
+     */
+    registerCapabilities(params: RegisterCapabilitiesParams): Promise<void>;
+    /**
+     * Unregister capabilities from the broker
+     *
+     * @param toolNames - Names of tools to unregister (empty = unregister all)
+     *
+     * @example
+     * ```typescript
+     * // Unregister specific tools
+     * await protocol.unregisterCapabilities(['old-tool']);
+     *
+     * // Unregister all
+     * await protocol.unregisterCapabilities([]);
+     * ```
+     */
+    unregisterCapabilities(_toolNames?: string[]): Promise<void>;
+    /**
+     * Discover agents on the network
+     *
+     * NOTE: Broker returns all tools with providers, we transform to agent-centric view client-side.
+     * Future enhancement: Add broker support for agent filtering to reduce network overhead.
+     *
+     * @param networks - Networks to search in
+     * @returns Array of discovered agents
+     *
+     * @example
+     * ```typescript
+     * const agents = await protocol.discoverAgents(['global']);
+     * console.log('Found agents:', agents);
+     * ```
+     */
+    discoverAgents(networks: string[]): Promise<Array<{
+        name: string;
+        capabilities: string[];
+    }>>;
+    /**
+     * Query capabilities of a specific agent
+     *
+     * NOTE: Broker doesn't support filtering by agentName yet, so we filter client-side.
+     * Future enhancement: Add broker support for agent filtering.
+     *
+     * @param agentName - Name of the agent
+     * @param networks - Networks to search in
+     * @returns Array of tool definitions
+     *
+     * @example
+     * ```typescript
+     * const capabilities = await protocol.queryCapabilities('calculator', ['global']);
+     * console.log('Calculator tools:', capabilities);
+     * ```
+     */
+    queryCapabilities(agentName: string, networks: string[]): Promise<ToolDefinition[]>;
+    /**
+     * Invoke a tool on a remote agent
+     *
+     * @template T - Result type
+     * @param params - Tool invocation parameters
+     * @returns Tool invocation result
+     *
+     * @throws {KadiError} If invocation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await protocol.invokeTool<{ result: number }>({
+     *   targetAgent: 'calculator',
+     *   toolName: 'add',
+     *   toolInput: { a: 5, b: 3 },
+     *   timeout: 30000
+     * });
+     *
+     * console.log('Result:', result.result); // 8
+     * ```
+     */
+    invokeTool<T = unknown>(params: ToolInvokeParams): Promise<T>;
+    /**
+     * Subscribe to events on specific channels
+     *
+     * NOTE: Currently subscribes to first channel only - broker supports one pattern per subscription.
+     * For multiple patterns, call this method multiple times.
+     *
+     * @param params - Event subscription parameters
+     *
+     * @example
+     * ```typescript
+     * await protocol.subscribeToEvents({
+     *   channels: ['user.*'],
+     *   networkId: 'global'
+     * });
+     * ```
+     */
+    subscribeToEvents(params: EventSubscribeParams): Promise<void>;
+    /**
+     * Unsubscribe from event channels
+     *
+     * NOTE: Currently unsubscribes from first channel only - broker supports one pattern per unsubscribe.
+     * For multiple patterns, call this method multiple times.
+     *
+     * @param params - Event unsubscribe parameters
+     *
+     * @example
+     * ```typescript
+     * await protocol.unsubscribeFromEvents({
+     *   channels: ['user.*'],
+     *   networkId: 'global'
+     * });
+     * ```
+     */
+    unsubscribeFromEvents(params: EventSubscribeParams): Promise<void>;
+    /**
+     * Publish an event to a channel
+     *
+     * @param params - Event publish parameters
+     *
+     * @example
+     * ```typescript
+     * await protocol.publishEvent({
+     *   channel: 'user.login',
+     *   data: { userId: '123', timestamp: Date.now() },
+     *   networkId: 'global',
+     *   hints: { latestOnly: true }
+     * });
+     * ```
+     */
+    publishEvent(params: EventPublishParams): Promise<void>;
+    /**
+     * Cleanup protocol resources
+     *
+     * @example
+     * ```typescript
+     * protocol.cleanup();
+     * ```
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=BrokerProtocol.d.ts.map

package/dist/broker/BrokerProtocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrokerProtocol.d.ts","sourceRoot":"","sources":["../../src/broker/BrokerProtocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,0BAA0B,EAC1B,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,cAAc;IACzB;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAE9C;;OAEG;IACH,OAAO,CAAC,cAAc,CAA+B;IAErD;;OAEG;IACH,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAC,CAAS;IAE5B;;;;OAIG;gBACS,UAAU,EAAE,gBAAgB;IAIxC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAyClE;;;;;;OAMG;YACW,YAAY;IAgC1B;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAYxC;;;;;;;OAOG;IACH,aAAa,IAAI,IAAI;IAOrB;;;;OAIG;YACW,aAAa;IAgB3B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,oBAAoB,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7E;;;;;;;;;;;;;OAaG;IACG,sBAAsB,CAAC,UAAU,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAMtE;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAmClG;;;;;;;;;;;;;;;OAeG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAsBzF;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IAcnE;;;;;;;;;;;;;;;OAeG;IACG,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBpE;;;;;;;;;;;;;;;OAeG;IACG,qBAAqB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBxE;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAW7D;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;CAGhB"}