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

package/dist/client/KadiClient.js

@@ -0,0 +1,902 @@
+/**
+ * KADI Client
+ *
+ * Thin orchestrator that composes specialized modules to provide the
+ * complete KADI client functionality.
+ *
+ * This is dramatically simpler than the old implementation because each
+ * concern has been properly separated.
+ *
+ * @module client/KadiClient
+ */
+import { EventEmitter } from 'events';
+import { KadiError, ErrorCode } from '../types/index.js';
+import { KadiMessages } from '../messages/index.js';
+import { ConfigResolver } from '../config/ConfigResolver.js';
+import { ToolRegistry } from '../tools/ToolRegistry.js';
+import { EventHub } from '../events/EventHub.js';
+import { BrokerConnectionManager } from '../broker/BrokerConnectionManager.js';
+import { BrokerProtocol, PROTOCOL_VERSION } from '../broker/BrokerProtocol.js';
+import { AbilityLoader } from '../abilities/index.js';
+// Import Zod utilities for automatic schema conversion
+import { zodToJsonSchema, isZodSchema } from '../schemas/zod-to-json-schema.js';
+/**
+ * KADI Client
+ *
+ * Main client class for KADI framework.
+ * Orchestrates tool registry, event hub, broker connections, and ability loading.
+ *
+ * @example
+ * ```typescript
+ * // Create client
+ * const client = new KadiClient({
+ *   name: 'my-service',
+ *   brokers: { local: 'ws://localhost:8080' },
+ *   networks: ['global']
+ * });
+ *
+ * // Register a tool
+ * client.registerTool('greet', async ({ name }) => {
+ *   return { message: `Hello, ${name}!` };
+ * });
+ *
+ * // Connect to brokers
+ * await client.connect();
+ *
+ * // Load an ability (explicit transport)
+ * const calc = await client.load('calculator', 'broker');
+ * const result = await calc.add({ a: 5, b: 3 });
+ *
+ * // Subscribe to events
+ * client.subscribeToEvent('user.*', (data) => {
+ *   console.log('User event:', data);
+ * });
+ *
+ * // Publish an event
+ * client.publishEvent('user.login', { userId: '123' });
+ * ```
+ */
+export class KadiClient extends EventEmitter {
+    /**
+     * Resolved configuration
+     */
+    config;
+    /**
+     * Tool registry
+     */
+    tools;
+    /**
+     * Event hub
+     */
+    events;
+    /**
+     * Broker connection manager
+     */
+    brokers;
+    /**
+     * Broker protocol instances (per broker)
+     */
+    protocols = new Map();
+    /**
+     * Ability loader
+     */
+    abilityLoader;
+    /**
+     * Whether client is initialized
+     */
+    initialized = false;
+    /**
+     * Create a new KADI Client
+     *
+     * @param config - Client configuration
+     */
+    constructor(config) {
+        super();
+        // Initialize specialized modules
+        this.tools = new ToolRegistry();
+        this.events = new EventHub('unknown'); // Will be updated after config resolution
+        this.brokers = new BrokerConnectionManager();
+        this.abilityLoader = new AbilityLoader();
+        // Resolve configuration (synchronous placeholder - will be async in connect())
+        // For now, create a minimal config
+        this.config = this.createMinimalConfig(config);
+        // Update event hub source to match client name
+        this.events.setSource(this.config.name);
+        // Forward broker events
+        this.setupBrokerEventForwarding();
+    }
+    /**
+     * Connect to configured brokers
+     *
+     * @throws {KadiError} If connection fails
+     *
+     * @example
+     * ```typescript
+     * await client.connect();
+     * console.log('Connected to brokers');
+     * ```
+     */
+    async connect() {
+        if (this.initialized) {
+            return;
+        }
+        // Resolve full configuration
+        const resolver = new ConfigResolver();
+        const resolved = await resolver.resolve(this.config);
+        Object.assign(this.config, resolved);
+        // Connect to brokers if configured
+        if (this.config.brokers && Object.keys(this.config.brokers).length > 0) {
+            await this.connectToBrokers();
+        }
+        this.initialized = true;
+        this.emit('ready');
+    }
+    /**
+     * Connect to all configured brokers
+     */
+    async connectToBrokers() {
+        if (!this.config.brokers) {
+            return;
+        }
+        const brokerConfigs = Object.entries(this.config.brokers).map(([name, url]) => ({
+            name,
+            url,
+            heartbeatInterval: this.config.advanced.heartbeatInterval,
+            requestTimeout: this.config.advanced.requestTimeout,
+            connectionTimeout: this.config.advanced.connectionTimeout
+        }));
+        // Connect to all brokers
+        await this.brokers.connectMultiple(brokerConfigs, this.config.defaultBroker);
+        // Perform handshake and register capabilities for each broker
+        for (const brokerName of this.brokers.getBrokerNames()) {
+            const connection = this.brokers.getConnection(brokerName);
+            if (!connection) {
+                continue;
+            }
+            // Create protocol instance
+            const protocol = new BrokerProtocol(connection);
+            this.protocols.set(brokerName, protocol);
+            // Perform handshake
+            await protocol.handshake({
+                role: this.config.role || 'agent',
+                name: this.config.name,
+                version: this.config.version,
+                protocolVersion: PROTOCOL_VERSION,
+                networks: this.config.networks
+            });
+            // Register capabilities
+            await this.registerCapabilitiesWithBroker(protocol);
+            // Start heartbeat
+            protocol.startHeartbeat(this.config.advanced.heartbeatInterval ?? 30000);
+        }
+    }
+    /**
+     * Register capabilities with a broker
+     *
+     * @param protocol - Broker protocol instance
+     */
+    async registerCapabilitiesWithBroker(protocol) {
+        const toolDefinitions = this.tools.extractDefinitions();
+        if (toolDefinitions.length > 0) {
+            await protocol.registerCapabilities({
+                tools: toolDefinitions,
+                networks: this.config.networks,
+                displayName: this.config.name
+            });
+        }
+    }
+    /**
+     * Register a tool (MCP-based)
+     *
+     * @template TInput - Tool input type
+     * @template TOutput - Tool output type
+     * @param definition - MCP-compliant tool definition
+     * @param handler - Tool handler function
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * client.registerTool({
+     *   name: 'add',
+     *   description: 'Add two numbers',
+     *   version: '1.0.0',
+     *   tags: ['math'],
+     *   inputSchema: {
+     *     type: 'object',
+     *     properties: {
+     *       a: { type: 'number' },
+     *       b: { type: 'number' }
+     *     },
+     *     required: ['a', 'b']
+     *   },
+     *   outputSchema: {
+     *     type: 'object',
+     *     properties: {
+     *       result: { type: 'number' }
+     *     }
+     *   }
+     * }, async ({ a, b }) => {
+     *   return { result: a + b };
+     * });
+     * ```
+     */
+    registerTool(definition, handler) {
+        // Support both JSON Schema and Zod schemas
+        // Zod approach: { input: z.object(...), output: z.object(...) }
+        // JSON Schema approach: { inputSchema: {...}, outputSchema: {...} }
+        let finalDefinition;
+        // Check if using Zod schemas (has 'input' field instead of 'inputSchema')
+        if ('input' in definition && definition.input !== undefined) {
+            const zodDef = definition;
+            // Validate that input is actually a Zod schema
+            if (!isZodSchema(zodDef.input)) {
+                throw new KadiError(`Tool '${definition.name}': 'input' must be a Zod schema. Use 'inputSchema' for JSON Schema.`, ErrorCode.INVALID_INPUT, 400, { toolName: definition.name });
+            }
+            // Convert Zod schemas to JSON Schema
+            finalDefinition = {
+                name: zodDef.name,
+                description: zodDef.description,
+                title: zodDef.title,
+                version: zodDef.version,
+                tags: zodDef.tags,
+                networks: zodDef.networks,
+                // Convert input Zod schema → JSON Schema
+                inputSchema: zodToJsonSchema(zodDef.input),
+                // Convert output Zod schema → JSON Schema (if provided)
+                outputSchema: zodDef.output && isZodSchema(zodDef.output)
+                    ? zodToJsonSchema(zodDef.output)
+                    : undefined
+            };
+        }
+        else {
+            // Traditional JSON Schema approach - use as-is
+            finalDefinition = definition;
+        }
+        // Register the tool with the converted schemas
+        this.tools.register(finalDefinition, handler);
+        // If already connected to brokers, register the new tool
+        if (this.initialized && this.protocols.size > 0) {
+            for (const protocol of this.protocols.values()) {
+                protocol.registerCapabilities({
+                    tools: [finalDefinition], // Use converted definition
+                    networks: this.config.networks,
+                    displayName: this.config.name
+                }).catch(error => {
+                    this.emit('error', new KadiError(`Failed to register tool with broker: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.BROKER_RESPONSE_ERROR, 500, { toolName: definition.name }));
+                });
+            }
+        }
+        return this;
+    }
+    /**
+     * Get a registered tool by name
+     *
+     * Retrieves a tool that has been registered with this client.
+     * Useful for inspecting registered tools or accessing their metadata.
+     *
+     * @param name - Tool name to retrieve
+     * @returns The registered tool with its definition and handler, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const tool = client.getRegisteredTool('add');
+     * if (tool) {
+     *   console.log('Tool:', tool.definition.name);
+     *   console.log('Description:', tool.definition.description);
+     * }
+     * ```
+     */
+    getRegisteredTool(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Get all registered tools
+     *
+     * Returns an array of all tools that have been registered with this client.
+     * Useful for listing available tools or debugging.
+     *
+     * @returns Array of all registered tools
+     *
+     * @example
+     * ```typescript
+     * const allTools = client.getAllRegisteredTools();
+     * console.log('Available tools:', allTools.map(t => t.definition.name));
+     * ```
+     */
+    getAllRegisteredTools() {
+        return this.tools.getAll();
+    }
+    /**
+     * Check if a tool is registered
+     *
+     * @param name - Tool name to check
+     * @returns true if the tool is registered, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (client.hasRegisteredTool('add')) {
+     *   // Tool is available
+     * }
+     * ```
+     */
+    hasRegisteredTool(name) {
+        return this.tools.has(name);
+    }
+    /**
+     * Load an ability
+     *
+     * **Explicit Transport, Excellent Developer Experience:**
+     * - Explicit transport selection (no magic)
+     * - Transport-specific options (only relevant fields shown)
+     * - Smart caching (avoids duplicate loads)
+     * - Runtime validation (optional)
+     * - Helpful errors with suggestions
+     *
+     * @param name - Ability name
+     * @param transport - Transport type ('native', 'stdio', or 'broker')
+     * @param options - Load options (transport-specific, optional)
+     * @returns Proxied ability with dynamic method access
+     *
+     * @throws {KadiError} If loading fails
+     *
+     * @example
+     * ```typescript
+     * // Simple broker load
+     * const calc = await client.load('calculator', 'broker');
+     * await calc.add({ a: 5, b: 3 });
+     *
+     * // With options
+     * const remote = await client.load('gpu-service', 'broker', {
+     *   networks: ['global', 'gpu-cluster']
+     * });
+     *
+     * // With runtime validation
+     * const validated = await client.load('calculator', 'broker', {
+     *   validate: true  // Runtime check for expected methods
+     * });
+     *
+     * // Native transport
+     * const local = await client.load('math-lib', 'native', {
+     *   path: './abilities/math'
+     * });
+     * ```
+     */
+    async load(name, transport, options = {}) {
+        return await this.abilityLoader.load(name, transport, options, this);
+    }
+    /**
+     * Subscribe to events
+     *
+     * @template T - Event data type
+     * @param pattern - Event pattern (supports wildcards)
+     * @param callback - Event callback
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = client.subscribeToEvent('user.*', (data) => {
+     *   console.log('User event:', data);
+     * });
+     *
+     * // Later...
+     * unsubscribe();
+     * ```
+     */
+    subscribeToEvent(pattern, callback) {
+        // Subscribe locally
+        const localUnsub = this.events.subscribe(pattern, callback);
+        // Subscribe on broker if connected
+        if (this.protocols.size > 0) {
+            const protocol = this.getBrokerProtocol();
+            protocol.subscribeToEvents({
+                channels: [pattern],
+                networkId: this.config.networks[0]
+            }).catch(error => {
+                this.emit('error', new KadiError(`Failed to subscribe to broker events: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.EVENT_SUBSCRIPTION_FAILED, 500, { pattern }));
+            });
+        }
+        return localUnsub;
+    }
+    /**
+     * Publish an event
+     *
+     * @template T - Event data type
+     * @param eventName - Event name
+     * @param data - Event data
+     * @param options - Publishing options
+     *
+     * @example
+     * ```typescript
+     * client.publishEvent('user.login', {
+     *   userId: '123',
+     *   timestamp: Date.now()
+     * });
+     * ```
+     */
+    publishEvent(eventName, data, options) {
+        // Publish locally
+        this.events.publish(eventName, data, options);
+        // Publish to broker if connected
+        if (this.protocols.size > 0) {
+            const protocol = this.getBrokerProtocol();
+            protocol.publishEvent({
+                channel: eventName,
+                data,
+                networkId: this.config.networks[0],
+                hints: options
+            }).catch(error => {
+                this.emit('error', new KadiError(`Failed to publish event to broker: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.EVENT_PUBLISH_FAILED, 500, { eventName }));
+            });
+        }
+    }
+    /**
+     * Disconnect from all brokers and cleanup
+     *
+     * @example
+     * ```typescript
+     * await client.disconnect();
+     * ```
+     */
+    async disconnect() {
+        // Stop all broker heartbeats
+        for (const protocol of this.protocols.values()) {
+            protocol.cleanup();
+        }
+        // Disconnect from all brokers
+        await this.brokers.disconnectAll();
+        // Unload all abilities
+        await this.abilityLoader.unloadAll();
+        // Clear event subscriptions
+        this.events.clear();
+        // Clear protocols
+        this.protocols.clear();
+        this.initialized = false;
+        this.emit('disconnected');
+        // If running in stdio mode, exit process
+        if (this.stdioServer) {
+            this.stdioServer.shutdown();
+        }
+    }
+    /**
+     * Stdio server instance (when running in stdio mode)
+     */
+    stdioServer;
+    /**
+     * Start serving this ability in the specified mode
+     *
+     * **Universal Entry Point**:
+     * Starts the appropriate server based on the mode parameter.
+     * This enables the same ability code to work across all transports
+     *
+     * **Modes**:
+     * - **native**: No-op (ability already loaded in-process as ES module)
+     * - **stdio**: Starts JSON-RPC server over stdin/stdout (for child processes)
+     * - **broker**: Connects to WebSocket broker and serves remotely
+     *
+     * @param mode - Transport mode to serve in ('native' | 'stdio' | 'broker')
+     * @returns Promise that resolves when server is ready (never resolves for stdio/broker - they keep running)
+     *
+     * @example
+     * ```typescript
+     * // ability.ts
+     * const client = new KadiClient({
+     *   name: 'calculator',
+     *   version: '1.0.0',
+     *   brokers: { default: 'ws://localhost:8080' }  // For broker mode
+     * });
+     *
+     * client.registerTool({ name: 'add', ... }, async ({ a, b }) => {
+     *   return { result: a + b };
+     * });
+     *
+     * export default client;
+     *
+     * // If running standalone, start server
+     * if (import.meta.url === `file://${process.argv[1]}`) {
+     *   await client.serve('stdio');  // or 'broker' for distributed mode
+     * }
+     * ```
+     */
+    async serve(mode) {
+        if (mode === 'stdio') {
+            return this.serveStdio();
+        }
+        if (mode === 'broker') {
+            return this.serveBroker();
+        }
+        // Native mode - ability already loaded in-process, nothing to serve
+        return Promise.resolve();
+    }
+    /**
+     * Serve via stdio (JSON-RPC over stdin/stdout)
+     *
+     * **Steps**:
+     * 1. Redirect console.log to stderr (keeps stdout clean for JSON-RPC)
+     * 2. Create Content-Length message reader/writer for stdin/stdout
+     * 3. Listen for incoming JSON-RPC requests (invoke, readAgentJson, shutdown)
+     * 4. Execute tool handlers for 'invoke' requests
+     * 5. Send JSON-RPC responses back via stdout
+     * 6. Handle graceful shutdown on SIGTERM/SIGINT
+     * 7. Keep process alive until shutdown
+     *
+     * @returns Promise that never resolves (server runs until killed)
+     */
+    async serveStdio() {
+        const { StdioMessageReader } = await import('../utils/StdioMessageReader.js');
+        const { StdioMessageWriter } = await import('../utils/StdioMessageWriter.js');
+        // Step 1: Redirect console.log to stderr (keeps stdout clean for JSON-RPC)
+        const originalLog = console.log;
+        console.log = console.error;
+        // Step 2: Create Content-Length message reader/writer for stdin/stdout
+        const reader = new StdioMessageReader();
+        const writer = new StdioMessageWriter(process.stdout);
+        // Step 3: Listen for incoming JSON-RPC requests
+        reader.on('message', async (message) => {
+            try {
+                const { id, method, params } = message;
+                if (method === 'invoke') {
+                    // Step 4: Execute tool handler for 'invoke' request
+                    const { toolName, toolInput } = params;
+                    const result = await this.invoke(toolName, toolInput);
+                    // Step 5: Send JSON-RPC success response
+                    await writer.write({
+                        jsonrpc: '2.0',
+                        id,
+                        result
+                    });
+                }
+                else if (method === 'readAgentJson') {
+                    // Return agent.json representation (used during discovery)
+                    const agentJson = this.readAgentJson();
+                    await writer.write({
+                        jsonrpc: '2.0',
+                        id,
+                        result: agentJson
+                    });
+                }
+                else if (method === 'shutdown') {
+                    // Graceful shutdown request
+                    await writer.write({
+                        jsonrpc: '2.0',
+                        id,
+                        result: { success: true }
+                    });
+                    // Restore console.log
+                    console.log = originalLog;
+                    // Exit after short delay to allow response to flush
+                    setTimeout(() => {
+                        process.exit(0);
+                    }, 100);
+                }
+                else {
+                    // Unknown method - send error
+                    await writer.write({
+                        jsonrpc: '2.0',
+                        id,
+                        error: {
+                            code: -32601,
+                            message: `Method not found: ${method}`
+                        }
+                    });
+                }
+            }
+            catch (error) {
+                // Step 5: Send JSON-RPC error response on failure
+                const kadiError = error instanceof KadiError ? error : KadiError.from(error);
+                await writer.write({
+                    jsonrpc: '2.0',
+                    id: message.id,
+                    error: {
+                        code: kadiError.statusCode || -32603,
+                        message: kadiError.message,
+                        data: kadiError.context
+                    }
+                });
+            }
+        });
+        reader.on('error', (error) => {
+            // Log parse errors to stderr
+            console.error('[KADI Stdio Server] Parse error:', error.message);
+        });
+        // Feed stdin data to reader for Content-Length framing
+        process.stdin.on('data', (chunk) => {
+            reader.onData(chunk);
+        });
+        // Step 6: Handle graceful shutdown on SIGTERM/SIGINT
+        const cleanup = () => {
+            console.log = originalLog;
+            reader.destroy();
+            writer.destroy();
+            process.exit(0);
+        };
+        process.on('SIGTERM', cleanup);
+        process.on('SIGINT', cleanup);
+        // Store server instance for programmatic shutdown
+        this.stdioServer = {
+            shutdown: () => {
+                console.log = originalLog;
+                reader.destroy();
+                writer.destroy();
+            }
+        };
+        // Step 7: Keep process alive until shutdown
+        return new Promise(() => {
+            // Never resolves - server runs until killed
+        });
+    }
+    /**
+     * Serve via broker (WebSocket-based distributed mode)
+     *
+     * Connects to the broker, registers this ability's tools, and handles
+     * incoming tool invocation requests.
+     *
+     * **Steps**:
+     * 1. Get broker URL from constructor config
+     * 2. Create and connect to broker via BrokerConnection
+     * 3. Perform handshake and authentication
+     * 4. Register all tools from the registry
+     * 5. Listen for incoming 'kadi.ability.request' messages
+     * 6. Execute tool handlers and send responses
+     * 7. Handle graceful shutdown on SIGTERM/SIGINT
+     * 8. Keep process alive until shutdown
+     *
+     * @returns Promise that never resolves (server runs until killed)
+     * @throws {KadiError} If broker config missing or connection fails
+     * @private
+     */
+    async serveBroker() {
+        // Step 1: Validate broker configuration exists
+        if (!this.brokers) {
+            throw new KadiError('Cannot serve in broker mode - no broker configuration provided', ErrorCode.INVALID_CONFIG, 400, {
+                suggestion: 'Add brokers configuration to KadiClient constructor',
+                example: 'new KadiClient({ brokers: { default: "ws://localhost:8080" } })'
+            });
+        }
+        // Step 2: Connect to broker (this performs handshake and registers capabilities)
+        await this.connect();
+        // Step 3: Get connection for error/disconnect handling
+        const connection = this.brokers.getDefaultConnection();
+        // Note: Tool invocation requests are handled by setupBrokerEventForwarding()
+        // which was called during initialization. No need to duplicate the listener here.
+        // Handle connection errors
+        connection.on('error', (error) => {
+            console.error('[KADI Broker Server] Connection error:', error);
+        });
+        // Handle disconnection
+        connection.on('disconnected', (code, reason) => {
+            console.log(`[KADI Broker Server] Disconnected from broker (code: ${code}, reason: ${reason})`);
+            // Broker connection should auto-reconnect if configured
+        });
+        // Step 7: Handle graceful shutdown on SIGTERM/SIGINT
+        const shutdown = async () => {
+            console.log('\n[KADI Broker Server] Shutting down...');
+            await connection.disconnect();
+            console.log('[KADI Broker Server] Disconnected from broker');
+            process.exit(0);
+        };
+        process.on('SIGTERM', shutdown);
+        process.on('SIGINT', shutdown);
+        // Step 8: Keep process alive until shutdown
+        return new Promise(() => {
+            // Never resolves - server runs until killed
+        });
+    }
+    /**
+     * Read agent.json representation
+     *
+     * Returns the runtime representation of this client's agent.json configuration.
+     * This enables KadiClient to function as an ability module that can be loaded
+     * natively by other agents.
+     *
+     * **What this returns:**
+     * - Represents what would be in the ability's agent.json file
+     * - Runtime `tools` field is mapped from agent.json's `exports` field
+     * - Used for discovery, type generation, and validation
+     *
+     * **Registration Pattern (Option A):**
+     * Ability developers write their code once using KadiClient.registerTool(),
+     * and it works across all transports (native, stdio, broker).
+     *
+     * @returns agent.json representation with name, version, and tools
+     *
+     * @example
+     * ```typescript
+     * // ability.ts (alongside agent.json file)
+     * const client = new KadiClient({ name: 'calculator', version: '1.0.0' });
+     * client.registerTool({ name: 'add', ... }, handler);
+     * export default client;
+     *
+     * // When loaded natively:
+     * const agentJson = client.readAgentJson();
+     * // { name: 'calculator', version: '1.0.0', tools: [...] }
+     * //   ↑ Represents agent.json's runtime structure
+     * ```
+     */
+    readAgentJson() {
+        return {
+            name: this.config.name,
+            version: this.config.version,
+            description: this.config.description,
+            tools: this.tools.extractDefinitions()
+        };
+    }
+    /**
+     * Invoke a tool by name
+     *
+     * Enables KadiClient to be used as an ability module. When loaded natively,
+     * this method is called by NativeTransport to execute registered tools.
+     *
+     * **Write Once, Run Anywhere:**
+     * The same tool handler works whether the ability is loaded natively,
+     * via stdio, or through a broker.
+     *
+     * @template TInput - Tool input type
+     * @template TOutput - Tool output type
+     * @param toolName - Name of the tool to invoke
+     * @param params - Tool input parameters
+     * @returns Promise resolving to tool result
+     *
+     * @throws {KadiError} If tool not found or invocation fails
+     *
+     * @example
+     * ```typescript
+     * // Registered tool:
+     * client.registerTool({ name: 'add', ... }, ({ a, b }) => ({ result: a + b }));
+     *
+     * // Invoke via agent.json protocol (native loading):
+     * const result = await client.invoke('add', { a: 5, b: 3 });
+     * // { result: 8 }
+     * ```
+     */
+    async invoke(toolName, params) {
+        // Look up the tool handler
+        const handler = this.tools.getHandler(toolName);
+        if (!handler) {
+            throw new KadiError(`Tool '${toolName}' not found`, ErrorCode.TOOL_NOT_FOUND, 404, {
+                toolName,
+                availableTools: this.tools.extractDefinitions().map(t => t.name),
+                suggestion: 'Check tool name or register tool first'
+            });
+        }
+        try {
+            // Execute the handler
+            const result = await handler(params);
+            return result;
+        }
+        catch (error) {
+            // Enhance error with context
+            if (error instanceof KadiError) {
+                throw error;
+            }
+            throw new KadiError(`Tool invocation failed: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.TOOL_INVOCATION_FAILED, 500, {
+                toolName,
+                input: params,
+                originalError: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    /**
+     * Get broker manager (implements IBrokerClient)
+     */
+    getBrokerManager() {
+        return this.brokers;
+    }
+    /**
+     * Get broker protocol instance (implements IBrokerClient)
+     *
+     * @param brokerName - Optional broker name (uses default if not specified)
+     */
+    getBrokerProtocol(brokerName) {
+        const name = brokerName ?? this.brokers.getDefaultBrokerName();
+        if (!name) {
+            throw new KadiError('No broker available', ErrorCode.BROKER_NOT_CONNECTED, 503);
+        }
+        const protocol = this.protocols.get(name);
+        if (!protocol) {
+            throw new KadiError(`Broker protocol not initialized for '${name}'`, ErrorCode.BROKER_NOT_CONNECTED, 503, { brokerName: name });
+        }
+        return protocol;
+    }
+    /**
+     * Networks (implements IBrokerClient)
+     */
+    get networks() {
+        return this.config.networks;
+    }
+    /**
+     * Create minimal configuration for constructor
+     * Full resolution happens in connect()
+     */
+    createMinimalConfig(config) {
+        const normalized = typeof config === 'string'
+            ? { brokers: { default: config } }
+            : config;
+        return {
+            name: normalized.name ?? 'unnamed-client',
+            version: normalized.version ?? '1.0.0',
+            description: normalized.description ?? '',
+            role: normalized.role ?? 'agent',
+            transport: normalized.transport ?? 'native',
+            brokers: normalized.brokers ?? { default: '' },
+            defaultBroker: normalized.defaultBroker ?? 'default',
+            networks: normalized.networks ?? ['global'],
+            abilityAgentJSON: normalized.abilityAgentJSON ?? '',
+            autoConnect: normalized.autoConnect ?? false,
+            advanced: {
+                heartbeatInterval: 30000,
+                requestTimeout: 30000,
+                connectionTimeout: 10000,
+                autoReconnect: true,
+                maxReconnectAttempts: 5,
+                verbose: false
+            },
+            sources: {}
+        };
+    }
+    /**
+     * Setup broker event forwarding
+     */
+    setupBrokerEventForwarding() {
+        this.brokers.on('brokerMessage', async (brokerName, message) => {
+            if (!message || typeof message !== 'object' || !('method' in message)) {
+                return;
+            }
+            const msg = message;
+            // Handle incoming tool invocation requests
+            if (msg.method === KadiMessages.ABILITY_REQUEST && msg.params) {
+                await this.handleIncomingToolRequest(brokerName, msg);
+                return;
+            }
+            // Handle event deliveries
+            if (msg.method === KadiMessages.EVENT_DELIVERY && msg.params) {
+                const { channel, data } = msg.params;
+                if (channel && data !== undefined) {
+                    this.events.publish(channel, data);
+                }
+            }
+        });
+    }
+    /**
+     * Handle incoming tool invocation requests from broker
+     *
+     * Flow:
+     * 1. Extract id from top-level message (JSON-RPC request id)
+     * 2. Look up tool handler by name
+     * 3. Execute handler with toolInput
+     * 4. Send JSON-RPC response back to broker with matching id
+     *
+     * @param brokerName - Name of the broker connection to use for response
+     * @param message - Full JSON-RPC request message with id, method, and params
+     * @private
+     */
+    async handleIncomingToolRequest(brokerName, message) {
+        const { toolName, toolInput } = message.params || {};
+        const requestId = message.id;
+        try {
+            // Step 1: Look up the tool handler
+            const handler = this.tools.getHandler(toolName);
+            if (!handler) {
+                throw new KadiError(`Tool '${toolName}' not found`, ErrorCode.TOOL_NOT_FOUND, 404, { toolName });
+            }
+            // Step 2: Execute the handler
+            const result = await handler(toolInput);
+            // Step 3: Send JSON-RPC response back to broker
+            // CRITICAL: id must match the incoming request id for proper routing
+            const connection = this.brokers.getConnection(brokerName);
+            if (!connection) {
+                console.error(`[DEBUG] No connection found for broker: ${brokerName}`);
+                return;
+            }
+            connection.sendResponse(requestId, result);
+        }
+        catch (error) {
+            // Send JSON-RPC error response back to broker with same id for proper routing
+            const connection = this.brokers.getConnection(brokerName);
+            if (connection) {
+                const kadiError = error instanceof KadiError ? error : KadiError.from(error);
+                connection.sendError(requestId, kadiError.code, kadiError.message);
+            }
+        }
+    }
+}
+//# sourceMappingURL=KadiClient.js.map