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

package/dist/client/KadiClient.d.ts

@@ -13,7 +13,7 @@ import { EventEmitter } from 'events';
 import type { KadiConfig, ResolvedConfig, ToolHandler, KadiTool, EventCallback, UnsubscribeFunction, PublishOptions } from '../types/index.js';
 import { BrokerConnectionManager } from '../broker/BrokerConnectionManager.js';
 import { BrokerProtocol } from '../broker/BrokerProtocol.js';
-import { type LoadedAbility, type LoadOptions } from '../abilities/index.js';
+import { type LoadedAbility, type LoadOptions, type AgentJson } from '../abilities/index.js';
 import type { IBrokerClient } from '../transports/BrokerTransport.js';
 /**
  * KADI Client
@@ -143,7 +143,58 @@ export declare class KadiClient extends EventEmitter implements IBrokerClient {
      * });
      * ```
      */
-    registerTool<TInput = unknown, TOutput = unknown>(definition: KadiTool, handler: ToolHandler<TInput, TOutput>): this;
+    registerTool<TInput = unknown, TOutput = unknown>(definition: KadiTool | (Omit<KadiTool, 'inputSchema' | 'outputSchema'> & {
+        input?: any;
+        output?: any;
+    }), handler: ToolHandler<TInput, TOutput>): 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: string): import("../schemas/kadi-extensions.js").RegisteredTool<unknown, unknown> | undefined;
+    /**
+     * 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(): import("../schemas/kadi-extensions.js").RegisteredTool<unknown, unknown>[];
+    /**
+     * 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: string): boolean;
     /**
      * Load an ability
      *
@@ -229,6 +280,144 @@ export declare class KadiClient extends EventEmitter implements IBrokerClient {
      * ```
      */
     disconnect(): Promise<void>;
+    /**
+     * Stdio server instance (when running in stdio mode)
+     */
+    private 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
+     * }
+     * ```
+     */
+    serve(mode: 'native' | 'stdio' | 'broker'): Promise<void>;
+    /**
+     * 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)
+     */
+    private serveStdio;
+    /**
+     * 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
+     */
+    private serveBroker;
+    /**
+     * 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(): AgentJson;
+    /**
+     * 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 }
+     * ```
+     */
+    invoke<TInput = unknown, TOutput = unknown>(toolName: string, params: TInput): Promise<TOutput>;
     /**
      * Get broker manager (implements IBrokerClient)
      */

package/dist/client/KadiClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KadiClient.d.ts","sourceRoot":"","sources":["../../src/client/KadiClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAEV,UAAU,EACV,cAAc,EACd,WAAW,EACX,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAoB,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAiB,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,UAAW,SAAQ,YAAa,YAAW,aAAa;IACnE;;OAEG;IACH,SAAgB,MAAM,EAAE,cAAc,CAAC;IAEvC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAElC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAE/D;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAE9C;;OAEG;IACH,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;gBACS,MAAM,EAAE,UAAU;IAoB9B;;;;;;;;;;OAUG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB9B;;OAEG;YACW,gBAAgB;IA4C9B;;;;OAIG;YACW,8BAA8B;IAY5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,YAAY,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC9C,UAAU,EAAE,QAAQ,EACpB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,IAAI;IAwBP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,EACxC,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,aAAa,CAAC;IAIzB;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GACzB,mBAAmB;IAuBtB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,CAAC,GAAG,OAAO,EACtB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,cAAc,GACvB,IAAI;IAuBP;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBjC;;OAEG;IACH,gBAAgB,IAAI,uBAAuB;IAI3C;;;;OAIG;IACH,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,cAAc;IAuBtD;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,EAAE,CAEvB;IAED;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA4B3B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAwBlC;;;;;;;;;;;;OAYG;YACW,yBAAyB;CAwCxC"}
+{"version":3,"file":"KadiClient.d.ts","sourceRoot":"","sources":["../../src/client/KadiClient.ts"],"names":[],"mappings":"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"}

package/dist/client/KadiClient.js

@@ -18,6 +18,8 @@ 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
  *
@@ -219,12 +221,44 @@ export class KadiClient extends EventEmitter {
      * ```
      */
     registerTool(definition, handler) {
-        this.tools.register(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: [definition],
+                    tools: [finalDefinition], // Use converted definition
                     networks: this.config.networks,
                     displayName: this.config.name
                 }).catch(error => {
@@ -234,6 +268,60 @@ export class KadiClient extends EventEmitter {
         }
         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
      *
@@ -364,6 +452,328 @@ export class KadiClient extends EventEmitter {
         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)