@kadi.build/core 0.0.1-alpha.9 → 0.1.0

package/dist/client.js

@@ -0,0 +1,1673 @@
+/**
+ * KadiClient for kadi-core v0.1.0
+ *
+ * The main entry point for building KADI agents.
+ * This client handles:
+ * - Broker connections (WebSocket with Ed25519 authentication)
+ * - Tool registration (local tools that can be invoked remotely)
+ * - Ability loading (native, stdio, broker transports)
+ * - Remote invocation (call tools on other agents)
+ * - Serve modes (stdio server, broker server)
+ *
+ * Design principles:
+ * - Named brokers with optional defaultBroker
+ * - Explicit over implicit (no proxy magic)
+ * - Readable, traceable code flow
+ */
+import { WebSocket } from 'ws';
+import * as crypto from 'crypto';
+import { KadiError } from './errors.js';
+import { zodToJsonSchema, isZodSchema } from './zod.js';
+import { resolveAbilityPath, resolveAbilityScript } from './lockfile.js';
+import { loadNativeTransport } from './transports/native.js';
+import { loadStdioTransport } from './transports/stdio.js';
+import { loadBrokerTransport } from './transports/broker.js';
+// ═══════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════
+const DEFAULT_HEARTBEAT_INTERVAL = 25000; // 25 seconds
+const DEFAULT_REQUEST_TIMEOUT = 30000; // 30 seconds
+const DEFAULT_AUTO_RECONNECT = true;
+const DEFAULT_MAX_RECONNECT_DELAY = 30000; // 30 seconds cap
+const RECONNECT_BASE_DELAY = 1000; // 1 second initial delay
+// ═══════════════════════════════════════════════════════════════
+// MCP CONTENT DETECTION
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Check if a value is a valid MCP ContentBlock.
+ *
+ * MCP supports these content types:
+ * - TextContent: { type: 'text', text: string }
+ * - ImageContent: { type: 'image', data: string, mimeType: string }
+ * - AudioContent: { type: 'audio', data: string, mimeType: string }
+ * - EmbeddedResource: { type: 'resource', resource: object }
+ * - ResourceLink: { type: 'resource_link', uri: string }
+ */
+function isValidMcpContentBlock(item) {
+    if (typeof item !== 'object' || item === null)
+        return false;
+    const block = item;
+    switch (block.type) {
+        case 'text':
+            return typeof block.text === 'string';
+        case 'image':
+        case 'audio':
+            return typeof block.data === 'string' && typeof block.mimeType === 'string';
+        case 'resource':
+            return typeof block.resource === 'object' && block.resource !== null;
+        case 'resource_link':
+            return typeof block.uri === 'string';
+        default:
+            return false;
+    }
+}
+/**
+ * Check if a result is already in MCP CallToolResult format.
+ *
+ * This allows tool handlers to return MCP-shaped content (like images)
+ * directly, without being double-wrapped.
+ *
+ * A valid CallToolResult has at least one of:
+ * - content: array of ContentBlock (with at least one valid block)
+ * - structuredContent: object (JSON data)
+ *
+ * Optional fields (not used for detection):
+ * - isError?: boolean
+ *
+ * @example
+ * // MCP-shaped with content (passes through unchanged):
+ * { content: [{ type: 'image', data: 'base64...', mimeType: 'image/png' }] }
+ *
+ * // MCP-shaped with structuredContent (passes through unchanged):
+ * { structuredContent: { models: ['gpt-4', 'claude-3'] } }
+ *
+ * // NOT MCP-shaped (gets wrapped as text):
+ * { models: ['gpt-4', 'claude-3'] }
+ */
+function isMcpCallToolResult(result) {
+    if (typeof result !== 'object' || result === null)
+        return false;
+    const obj = result;
+    // Check for valid content array (non-empty, all valid blocks)
+    const hasValidContent = Array.isArray(obj.content) &&
+        obj.content.length > 0 &&
+        obj.content.every(isValidMcpContentBlock);
+    // Check for structuredContent (any non-null object)
+    const hasStructuredContent = typeof obj.structuredContent === 'object' && obj.structuredContent !== null;
+    // Must have either content OR structuredContent (or both)
+    return hasValidContent || hasStructuredContent;
+}
+// ═══════════════════════════════════════════════════════════════
+// KADCLIENT CLASS
+// ═══════════════════════════════════════════════════════════════
+/**
+ * The main client for building KADI agents.
+ *
+ * @example
+ * ```typescript
+ * // Create a client with named brokers
+ * const client = new KadiClient({
+ *   name: 'my-agent',
+ *   brokers: {
+ *     production: 'ws://broker-prod:8080',
+ *     internal: 'ws://broker-internal:8080',
+ *   },
+ *   defaultBroker: 'production',
+ * });
+ *
+ * // Register a tool
+ * client.registerTool({
+ *   name: 'add',
+ *   description: 'Add two numbers',
+ *   input: z.object({ a: z.number(), b: z.number() }),
+ * }, async ({ a, b }) => ({ result: a + b }));
+ *
+ * // Connect to brokers
+ * await client.connect();
+ *
+ * // Load and use abilities
+ * const calc = await client.loadNative('calculator');
+ * const result = await calc.invoke('multiply', { x: 5, y: 3 });
+ * ```
+ */
+export class KadiClient {
+    /** Resolved configuration with defaults applied */
+    config;
+    /** Registered tools (local tools this agent provides) */
+    tools = new Map();
+    /** Broker connections by name */
+    brokers = new Map();
+    /** Counter for generating unique request IDs */
+    nextRequestId = 0;
+    /** Event handler callback (set by native transport) */
+    eventHandler = null;
+    /** Whether we're serving via stdio (set by serve('stdio')) */
+    isServingStdio = false;
+    // ─────────────────────────────────────────────────────────────
+    // CONSTRUCTOR
+    // ─────────────────────────────────────────────────────────────
+    constructor(config) {
+        // Validate required fields
+        if (!config.name || typeof config.name !== 'string') {
+            throw new KadiError('Client name is required', 'INVALID_CONFIG', {
+                hint: 'Provide a name for your agent: new KadiClient({ name: "my-agent" })',
+            });
+        }
+        // Resolve configuration with defaults
+        // Auto-select first broker as default if not specified (matches Python behavior)
+        const brokers = config.brokers ?? {};
+        const firstBrokerName = Object.keys(brokers)[0];
+        this.config = {
+            name: config.name,
+            version: config.version ?? '1.0.0',
+            description: config.description ?? '',
+            brokers,
+            defaultBroker: config.defaultBroker ?? firstBrokerName,
+            networks: config.networks ?? ['global'],
+            heartbeatInterval: config.heartbeatInterval ?? DEFAULT_HEARTBEAT_INTERVAL,
+            requestTimeout: config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT,
+            autoReconnect: config.autoReconnect ?? DEFAULT_AUTO_RECONNECT,
+            maxReconnectDelay: config.maxReconnectDelay ?? DEFAULT_MAX_RECONNECT_DELAY,
+        };
+        // Validate defaultBroker if specified
+        if (this.config.defaultBroker && !this.config.brokers[this.config.defaultBroker]) {
+            throw new KadiError(`Default broker "${this.config.defaultBroker}" not found in brokers config`, 'INVALID_CONFIG', {
+                defaultBroker: this.config.defaultBroker,
+                available: Object.keys(this.config.brokers),
+                hint: 'defaultBroker must be a key in the brokers map',
+            });
+        }
+    }
+    // ─────────────────────────────────────────────────────────────
+    // CONNECTION MANAGEMENT
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Connect to all configured brokers.
+     * Call this after registering tools.
+     *
+     * @example
+     * ```typescript
+     * await client.connect(); // Connects to all brokers
+     * await client.connect('production'); // Connect to specific broker
+     * ```
+     */
+    async connect(brokerName) {
+        // If specific broker requested, connect to just that one
+        if (brokerName) {
+            await this.connectToBroker(brokerName);
+            return;
+        }
+        // Connect to all configured brokers
+        const brokerNames = Object.keys(this.config.brokers);
+        if (brokerNames.length === 0) {
+            // No brokers configured - that's okay for local-only usage
+            return;
+        }
+        // Connect to all brokers in parallel
+        await Promise.all(brokerNames.map((name) => this.connectToBroker(name)));
+    }
+    /**
+     * Connect to a specific broker by name.
+     *
+     * Protocol:
+     * 1. Generate Ed25519 keypair
+     * 2. Open WebSocket connection
+     * 3. Send kadi.session.hello
+     * 4. Receive nonce from broker
+     * 5. Send kadi.session.authenticate with signed nonce
+     * 6. Receive agentId from broker
+     * 7. Register tools with broker
+     * 8. Start heartbeat
+     */
+    async connectToBroker(brokerName) {
+        const url = this.config.brokers[brokerName];
+        if (!url) {
+            throw new KadiError(`Broker "${brokerName}" not found in configuration`, 'UNKNOWN_BROKER', {
+                broker: brokerName,
+                available: Object.keys(this.config.brokers),
+                hint: 'Check your brokers configuration',
+            });
+        }
+        // Check if already connected
+        if (this.brokers.has(brokerName)) {
+            const existing = this.brokers.get(brokerName);
+            if (existing.status === 'connected' || existing.status === 'connecting') {
+                return;
+            }
+        }
+        // Generate Ed25519 keypair for authentication
+        const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+        // Create broker state
+        const state = {
+            name: brokerName,
+            url,
+            ws: null,
+            agentId: '',
+            publicKey: publicKey.export({ type: 'spki', format: 'der' }),
+            privateKey: privateKey.export({ type: 'pkcs8', format: 'der' }),
+            heartbeatTimer: null,
+            pendingRequests: new Map(),
+            pendingInvocations: new Map(),
+            status: 'connecting',
+            // Reconnection state
+            intentionalDisconnect: false,
+            reconnectAttempts: 0,
+            reconnectTimer: null,
+            // Event subscriptions (pub/sub)
+            eventHandlers: new Map(),
+            subscribedPatterns: new Set(),
+        };
+        this.brokers.set(brokerName, state);
+        // Open WebSocket connection
+        await this.openWebSocket(state);
+        // Perform handshake
+        await this.performHandshake(state);
+        // Register with broker (transitions to "ready" state)
+        await this.registerWithBroker(state);
+        // Start heartbeat
+        state.heartbeatTimer = setInterval(() => {
+            this.sendHeartbeat(state);
+        }, this.config.heartbeatInterval);
+        state.status = 'connected';
+    }
+    // ─────────────────────────────────────────────────────────────
+    // MESSAGE BUILDERS
+    // ─────────────────────────────────────────────────────────────
+    buildHelloMessage() {
+        return {
+            jsonrpc: '2.0',
+            id: this.nextRequestId++,
+            method: 'kadi.session.hello',
+            params: { role: 'agent' },
+        };
+    }
+    buildAuthMessage(state, nonce) {
+        const privateKey = crypto.createPrivateKey({
+            key: state.privateKey,
+            format: 'der',
+            type: 'pkcs8',
+        });
+        const signature = crypto.sign(null, Buffer.from(nonce, 'utf8'), privateKey);
+        return {
+            jsonrpc: '2.0',
+            id: this.nextRequestId++,
+            method: 'kadi.session.authenticate',
+            params: {
+                publicKey: state.publicKey.toString('base64'),
+                signature: signature.toString('base64'),
+                nonce,
+            },
+        };
+    }
+    buildRegisterMessage(tools, networks) {
+        return {
+            jsonrpc: '2.0',
+            id: this.nextRequestId++,
+            method: 'kadi.agent.register',
+            params: {
+                tools,
+                networks,
+                displayName: this.config.name,
+            },
+        };
+    }
+    buildHeartbeatMessage() {
+        return {
+            jsonrpc: '2.0',
+            id: this.nextRequestId++,
+            method: 'kadi.session.heartbeat',
+            params: { timestamp: Date.now() },
+        };
+    }
+    // ─────────────────────────────────────────────────────────────
+    // CONNECTION HELPERS
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Open WebSocket connection to broker.
+     */
+    openWebSocket(state) {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(state.url);
+            state.ws = ws;
+            const timeout = setTimeout(() => {
+                ws.close();
+                reject(new KadiError(`Timeout connecting to broker "${state.name}"`, 'BROKER_TIMEOUT', {
+                    broker: state.name,
+                    url: state.url,
+                }));
+            }, this.config.requestTimeout);
+            ws.on('open', () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+            ws.on('error', (error) => {
+                clearTimeout(timeout);
+                state.status = 'disconnected';
+                reject(new KadiError(`Failed to connect to broker "${state.name}"`, 'CONNECTION_FAILED', {
+                    broker: state.name,
+                    url: state.url,
+                    reason: error.message,
+                }));
+            });
+            ws.on('close', () => {
+                this.handleWebSocketClose(state);
+            });
+            ws.on('message', (data) => this.handleBrokerMessage(state, data));
+        });
+    }
+    /**
+     * Perform handshake: hello → authenticate.
+     *
+     * Protocol:
+     * 1. Client sends kadi.session.hello
+     * 2. Broker responds with { nonce: "..." }
+     * 3. Client signs nonce and sends kadi.session.authenticate
+     * 4. Broker responds with { agentId: "..." }
+     */
+    async performHandshake(state) {
+        // Step 1: Send hello, get nonce for challenge-response auth
+        // The broker sends a random nonce that we must sign to prove key ownership
+        const helloResult = await this.sendRequest(state, this.buildHelloMessage());
+        // Validate the response shape - sendRequest<T> is type documentation only,
+        // not runtime enforcement. We must validate critical fields ourselves.
+        if (!helloResult.nonce) {
+            throw new KadiError('Hello response missing nonce', 'AUTHENTICATION_FAILED', {
+                broker: state.name,
+                hint: 'Broker may be misconfigured or running incompatible version',
+            });
+        }
+        // Step 2: Sign the nonce and authenticate
+        // This proves we own the private key without revealing it
+        const authResult = await this.sendRequest(state, this.buildAuthMessage(state, helloResult.nonce));
+        if (!authResult.agentId) {
+            throw new KadiError('Auth response missing agentId', 'AUTHENTICATION_FAILED', {
+                broker: state.name,
+            });
+        }
+        state.agentId = authResult.agentId;
+    }
+    /**
+     * Register with broker after authentication.
+     *
+     * This transitions the session from "authenticated" to "ready" state.
+     * Must be called even if no tools are registered - the broker requires
+     * the agent to be in "ready" state before it can invoke remote tools.
+     */
+    async registerWithBroker(state) {
+        // Get tools targeted for this specific broker
+        const tools = this.getToolDefinitions(state.name);
+        // Note: If registration fails, sendRequest will reject with the error.
+        // We don't need to check response.error here - errors are already
+        // handled via Promise rejection in handleBrokerResponse.
+        await this.sendRequest(state, this.buildRegisterMessage(tools, this.config.networks));
+    }
+    /**
+     * Send a JSON-RPC request and wait for the response.
+     *
+     * Design: Returns the result directly (not the full JSON-RPC response).
+     *
+     * Why? The JSON-RPC envelope (jsonrpc, id) is transport metadata.
+     * Once we've matched the response to the pending request, that metadata
+     * has served its purpose. Callers care about the result, not the envelope.
+     *
+     * Errors are handled via Promise rejection in handleBrokerResponse,
+     * so by the time this resolves, we know it's a successful response.
+     *
+     * IMPORTANT: The type parameter T is NOT validated at runtime.
+     * It provides TypeScript type hints but the broker could return any shape.
+     * Callers MUST validate critical fields before using them.
+     *
+     * @template T - Expected type of the result (defaults to unknown for safety)
+     * @param state - Broker connection state
+     * @param request - JSON-RPC request to send
+     * @returns Promise resolving to the typed result
+     *
+     * @example
+     * ```typescript
+     * // Caller specifies expected result type
+     * const result = await this.sendRequest<{ nonce: string }>(state, helloMessage);
+     * // IMPORTANT: Validate before using - the type is not runtime-enforced
+     * if (!result.nonce) throw new Error('Missing nonce');
+     * console.log(result.nonce);
+     * ```
+     */
+    sendRequest(state, request) {
+        // Fail fast if WebSocket is not connected
+        // Without this check, the request would sit pending until timeout (30s),
+        // giving a misleading BROKER_TIMEOUT error instead of the real problem.
+        const ws = state.ws;
+        if (!ws || ws.readyState !== WebSocket.OPEN) {
+            return Promise.reject(new KadiError('Cannot send request: WebSocket not connected', 'BROKER_NOT_CONNECTED', {
+                broker: state.name,
+                method: request.method,
+                hint: 'Call client.connect() first',
+            }));
+        }
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                state.pendingRequests.delete(request.id);
+                reject(new KadiError(`Request timeout: ${request.method}`, 'BROKER_TIMEOUT', {
+                    broker: state.name,
+                    method: request.method,
+                }));
+            }, this.config.requestTimeout);
+            // Store the pending request. When handleBrokerResponse receives a response,
+            // it will clear the timeout, delete from map, and call resolve/reject.
+            state.pendingRequests.set(request.id, {
+                resolve: (result) => resolve(result),
+                reject,
+                timeout,
+                method: request.method,
+                sentAt: new Date(),
+            });
+            ws.send(JSON.stringify(request));
+        });
+    }
+    // ─────────────────────────────────────────────────────────────
+    // MESSAGE HANDLING
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Handle incoming messages from broker.
+     */
+    handleBrokerMessage(state, data) {
+        let message;
+        try {
+            message = JSON.parse(data.toString());
+        }
+        catch {
+            return; // Invalid JSON - ignore
+        }
+        // Handle responses (has id, has result or error)
+        if ('id' in message && ('result' in message || 'error' in message)) {
+            this.handleBrokerResponse(state, message);
+            return;
+        }
+        // Handle requests (has id, has method) - tool invocations from broker
+        if ('id' in message && 'method' in message) {
+            this.handleBrokerRequest(state, message);
+            return;
+        }
+        // Handle notifications (no id, has method)
+        if (!('id' in message) && 'method' in message) {
+            const notification = message;
+            // Route kadi.ability.response notifications to pending invocations
+            if (notification.method === 'kadi.ability.response') {
+                this.handleAbilityResponse(state, notification);
+            }
+            // Route kadi.event.delivery notifications to event handlers
+            else if (notification.method === 'kadi.event.delivery') {
+                this.handleEventDelivery(state, notification);
+            }
+        }
+    }
+    /**
+     * Handle kadi.ability.response notification.
+     *
+     * This is the second part of the async tool invocation pattern:
+     * 1. Client sends kadi.ability.request → gets { status: 'pending', requestId }
+     * 2. Provider executes tool and sends result back to broker
+     * 3. Broker sends this notification with the actual result
+     *
+     * The notification contains:
+     * - requestId: matches what we got in step 1
+     * - result: the tool's return value (if successful)
+     * - error: error message (if failed)
+     */
+    handleAbilityResponse(state, notification) {
+        // The error field can be either a string or an object with code/message.
+        // We accept both forms and normalize for consistent error handling.
+        const params = notification.params;
+        // Validate notification has requestId
+        if (!params?.requestId) {
+            // Malformed notification - ignore
+            return;
+        }
+        // Find pending invocation
+        const pending = state.pendingInvocations.get(params.requestId);
+        if (!pending) {
+            // No one waiting for this - might be stale or already timed out
+            return;
+        }
+        // Clean up: remove from pending and clear timeout
+        clearTimeout(pending.timeout);
+        state.pendingInvocations.delete(params.requestId);
+        // Resolve or reject based on response content
+        if (params.error) {
+            // Normalize error - could be string or { code, message } object
+            const errorMessage = typeof params.error === 'string' ? params.error : params.error.message;
+            const errorCode = typeof params.error === 'object' ? params.error.code : undefined;
+            pending.reject(new KadiError(`Tool "${pending.toolName}" failed: ${errorMessage}`, 'TOOL_INVOCATION_FAILED', {
+                toolName: pending.toolName,
+                requestId: params.requestId,
+                broker: state.name,
+                errorCode, // Include error code if available
+            }));
+        }
+        else {
+            pending.resolve(params.result);
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // BROKER EVENTS (Pub/Sub)
+    // ═══════════════════════════════════════════════════════════════
+    /**
+     * Handle kadi.event.delivery notification from broker.
+     *
+     * When an event is published to a channel that matches one of our subscribed
+     * patterns, the broker sends us this notification with the event data.
+     *
+     * Flow:
+     * 1. Some agent calls publish('user.login', data)
+     * 2. Broker routes to all subscribers matching 'user.*' or 'user.#' etc.
+     * 3. We receive this notification and dispatch to local handlers
+     *
+     * The notification params contain:
+     * - channel: The exact channel name (e.g., 'user.login')
+     * - data: The event payload
+     * - networkId: Which network the event was published to
+     * - source: Session ID of the publisher
+     * - timestamp: When the event was published
+     */
+    handleEventDelivery(state, notification) {
+        const params = notification.params;
+        // Validate notification has required fields
+        if (!params?.channel || params.networkId === undefined) {
+            // Malformed notification - ignore
+            return;
+        }
+        // Create the event object to pass to handlers
+        const event = {
+            channel: params.channel,
+            data: params.data,
+            networkId: params.networkId,
+            source: params.source ?? 'unknown',
+            timestamp: params.timestamp ?? Date.now(),
+        };
+        // Dispatch to all matching handlers
+        // We need to check which patterns match this channel
+        for (const [pattern, handlers] of state.eventHandlers) {
+            if (this.patternMatchesChannel(pattern, event.channel)) {
+                for (const handler of handlers) {
+                    // Fire-and-forget - don't await, don't let one handler block others
+                    try {
+                        const result = handler(event);
+                        // If handler returns a promise, catch errors but don't block
+                        if (result instanceof Promise) {
+                            result.catch((err) => {
+                                // Log but don't throw - one handler error shouldn't affect others
+                                console.error(`[KADI] Event handler error for pattern "${pattern}":`, err);
+                            });
+                        }
+                    }
+                    catch (err) {
+                        // Sync error in handler
+                        console.error(`[KADI] Event handler error for pattern "${pattern}":`, err);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Check if a subscription pattern matches an event channel.
+     *
+     * Pattern matching follows RabbitMQ topic exchange rules:
+     * - '*' matches exactly one word (between dots)
+     * - '#' matches zero or more words
+     * - Literal strings match exactly
+     *
+     * Examples:
+     * - 'user.*' matches 'user.login', 'user.logout', NOT 'user.profile.update'
+     * - 'user.#' matches 'user.login', 'user.profile.update', even just 'user'
+     * - 'user.login' matches only 'user.login'
+     *
+     * @param pattern - The subscription pattern (e.g., 'user.*')
+     * @param channel - The event channel (e.g., 'user.login')
+     */
+    patternMatchesChannel(pattern, channel) {
+        const patternParts = pattern.split('.');
+        const channelParts = channel.split('.');
+        return this.matchPatternRecursive(patternParts, 0, channelParts, 0);
+    }
+    /**
+     * Recursive pattern matcher (RabbitMQ topic exchange style).
+     *
+     * Example: pattern "user.#.status" vs channel "user.profile.settings.status"
+     *          → # eats "profile.settings" → match!
+     */
+    matchPatternRecursive(pattern, pi, channel, ci) {
+        // Both exhausted = match
+        if (pi === pattern.length && ci === channel.length)
+            return true;
+        // Pattern done but channel has more = no match
+        if (pi === pattern.length)
+            return false;
+        const p = pattern[pi];
+        if (p === '#') {
+            // '#' matches zero or more words - try zero first, then one-at-a-time
+            if (this.matchPatternRecursive(pattern, pi + 1, channel, ci))
+                return true;
+            if (ci < channel.length && this.matchPatternRecursive(pattern, pi, channel, ci + 1))
+                return true;
+            return false;
+        }
+        // Channel exhausted but pattern needs more = no match
+        if (ci === channel.length)
+            return false;
+        if (p === '*') {
+            // '*' matches exactly one word
+            return this.matchPatternRecursive(pattern, pi + 1, channel, ci + 1);
+        }
+        // Literal must match exactly
+        return p === channel[ci] && this.matchPatternRecursive(pattern, pi + 1, channel, ci + 1);
+    }
+    /**
+     * Subscribe to events matching a pattern.
+     *
+     * Pattern matching follows RabbitMQ topic exchange rules:
+     * - '*' matches exactly one word (between dots)
+     * - '#' matches zero or more words
+     *
+     * @param pattern - Pattern to subscribe to (e.g., 'user.*', 'order.#')
+     * @param handler - Function called when matching event is received
+     * @param options - Optional: which broker to subscribe through
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to all user events
+     * client.subscribe('user.*', (event) => {
+     *   console.log(`User event: ${event.channel}`, event.data);
+     * });
+     *
+     * // Subscribe to all order events at any depth
+     * client.subscribe('order.#', (event) => {
+     *   console.log(`Order event: ${event.channel}`, event.data);
+     * });
+     * ```
+     */
+    async subscribe(pattern, handler, options = {}) {
+        // Resolve which broker to use
+        const brokerName = options.broker ?? this.config.defaultBroker;
+        if (!brokerName) {
+            throw new KadiError('No broker specified and no defaultBroker configured', 'INVALID_CONFIG', {
+                hint: 'Either specify a broker in options or set defaultBroker in config',
+            });
+        }
+        // Get broker state
+        const state = this.brokers.get(brokerName);
+        if (!state || state.status !== 'connected') {
+            throw new KadiError(`Broker "${brokerName}" is not connected`, 'BROKER_NOT_CONNECTED', {
+                broker: brokerName,
+                status: state?.status ?? 'not found',
+                hint: 'Call client.connect() first',
+            });
+        }
+        // Add handler to local tracking
+        let handlers = state.eventHandlers.get(pattern);
+        if (!handlers) {
+            handlers = new Set();
+            state.eventHandlers.set(pattern, handlers);
+        }
+        handlers.add(handler);
+        // If this is the first handler for this pattern, subscribe on broker
+        if (!state.subscribedPatterns.has(pattern)) {
+            await this.sendRequest(state, {
+                jsonrpc: '2.0',
+                id: this.nextRequestId++,
+                method: 'kadi.event.subscribe',
+                params: { pattern },
+            });
+            state.subscribedPatterns.add(pattern);
+        }
+    }
+    /**
+     * Unsubscribe from events.
+     *
+     * Removes the specified handler from the pattern. If no handlers remain
+     * for a pattern, the broker subscription is also removed.
+     *
+     * @param pattern - Pattern to unsubscribe from
+     * @param handler - The handler function to remove
+     * @param options - Optional: which broker to unsubscribe from
+     *
+     * @example
+     * ```typescript
+     * const handler = (event) => console.log(event);
+     * client.subscribe('user.*', handler);
+     * // ... later
+     * client.unsubscribe('user.*', handler);
+     * ```
+     */
+    async unsubscribe(pattern, handler, options = {}) {
+        // Resolve which broker to use
+        const brokerName = options.broker ?? this.config.defaultBroker;
+        if (!brokerName) {
+            throw new KadiError('No broker specified and no defaultBroker configured', 'INVALID_CONFIG', {
+                hint: 'Either specify a broker in options or set defaultBroker in config',
+            });
+        }
+        // Get broker state
+        const state = this.brokers.get(brokerName);
+        if (!state) {
+            // Broker not found - nothing to unsubscribe
+            return;
+        }
+        // Remove handler from local tracking
+        const handlers = state.eventHandlers.get(pattern);
+        if (handlers) {
+            handlers.delete(handler);
+            // If no more handlers for this pattern, clean up
+            if (handlers.size === 0) {
+                state.eventHandlers.delete(pattern);
+                // Unsubscribe from broker if we were subscribed
+                if (state.subscribedPatterns.has(pattern) && state.status === 'connected') {
+                    try {
+                        await this.sendRequest(state, {
+                            jsonrpc: '2.0',
+                            id: this.nextRequestId++,
+                            method: 'kadi.event.unsubscribe',
+                            params: { pattern },
+                        });
+                    }
+                    catch {
+                        // Ignore errors during unsubscribe (broker might be disconnecting)
+                    }
+                    state.subscribedPatterns.delete(pattern);
+                }
+            }
+        }
+    }
+    /**
+     * Publish an event to a channel.
+     *
+     * Events are published to a specific network. All agents subscribed to
+     * matching patterns on that network will receive the event.
+     *
+     * @param channel - Channel/topic to publish to (e.g., 'user.login')
+     * @param data - Event payload (any JSON-serializable data)
+     * @param options - Optional: network and broker to publish through
+     *
+     * @example
+     * ```typescript
+     * // Publish to default network
+     * await client.publish('user.login', { userId: '123', timestamp: Date.now() });
+     *
+     * // Publish to specific network
+     * await client.publish('order.created', orderData, { network: 'internal' });
+     * ```
+     */
+    async publish(channel, data, options = {}) {
+        // Resolve which broker to use
+        const brokerName = options.broker ?? this.config.defaultBroker;
+        if (!brokerName) {
+            throw new KadiError('No broker specified and no defaultBroker configured', 'INVALID_CONFIG', {
+                hint: 'Either specify a broker in options or set defaultBroker in config',
+            });
+        }
+        // Get broker state
+        const state = this.brokers.get(brokerName);
+        if (!state || state.status !== 'connected') {
+            throw new KadiError(`Broker "${brokerName}" is not connected`, 'BROKER_NOT_CONNECTED', {
+                broker: brokerName,
+                status: state?.status ?? 'not found',
+                hint: 'Call client.connect() first',
+            });
+        }
+        // Resolve which network to publish to
+        const networkId = options.network ?? this.config.networks[0] ?? 'global';
+        // Send publish request to broker
+        await this.sendRequest(state, {
+            jsonrpc: '2.0',
+            id: this.nextRequestId++,
+            method: 'kadi.event.publish',
+            params: {
+                channel,
+                data,
+                networkId,
+            },
+        });
+    }
+    /**
+     * Handle incoming request from broker (tool invocation).
+     */
+    async handleBrokerRequest(state, request) {
+        // Handle tool invocation: kadi.ability.request
+        if (request.method === 'kadi.ability.request') {
+            const params = request.params;
+            const callerProtocol = params._meta?.callerProtocol;
+            await this.handleInvokeRequest(state, request.id, params.toolName, params.toolInput, callerProtocol);
+        }
+    }
+    /**
+     * Handle incoming tool invocation request from broker.
+     *
+     * When callerProtocol is 'mcp', responses are formatted for MCP clients:
+     * - If result is already MCP-shaped (has valid content array), pass through unchanged
+     * - Otherwise, wrap as text: { content: [{ type: 'text', text: '...' }], isError: false }
+     *
+     * This allows tools to return images, audio, or other MCP content types directly,
+     * while plain JSON results are automatically wrapped as text.
+     *
+     * When callerProtocol is 'kadi' or undefined, raw structured data is returned.
+     */
+    async handleInvokeRequest(state, requestId, toolName, toolInput, callerProtocol) {
+        try {
+            const result = await this.invoke(toolName, toolInput);
+            // Format response based on caller protocol
+            let responseResult;
+            if (callerProtocol === 'mcp') {
+                // MCP clients expect CallToolResult format.
+                // If the result is already MCP-shaped, pass through unchanged.
+                // Otherwise, wrap as text content.
+                responseResult = isMcpCallToolResult(result)
+                    ? result
+                    : { content: [{ type: 'text', text: JSON.stringify(result) }], isError: false };
+            }
+            else {
+                // KADI clients receive raw structured data
+                responseResult = result;
+            }
+            const response = {
+                jsonrpc: '2.0',
+                id: requestId,
+                result: responseResult,
+            };
+            state.ws?.send(JSON.stringify(response));
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // For MCP clients, wrap errors in CallToolResult format too
+            if (callerProtocol === 'mcp') {
+                const response = {
+                    jsonrpc: '2.0',
+                    id: requestId,
+                    result: { content: [{ type: 'text', text: errorMessage }], isError: true },
+                };
+                state.ws?.send(JSON.stringify(response));
+            }
+            else {
+                // KADI clients receive JSON-RPC error
+                const response = {
+                    jsonrpc: '2.0',
+                    id: requestId,
+                    error: {
+                        code: -32000,
+                        message: errorMessage,
+                    },
+                };
+                state.ws?.send(JSON.stringify(response));
+            }
+        }
+    }
+    /**
+     * Handle response to a pending request.
+     */
+    handleBrokerResponse(state, response) {
+        const pending = state.pendingRequests.get(response.id);
+        if (!pending) {
+            return; // No one waiting for this response
+        }
+        // Clean up: remove from pending and clear timeout
+        clearTimeout(pending.timeout);
+        state.pendingRequests.delete(response.id);
+        if (response.error) {
+            pending.reject(new KadiError(response.error.message, 'BROKER_ERROR', {
+                code: response.error.code,
+                broker: state.name,
+            }));
+        }
+        else {
+            pending.resolve(response.result);
+        }
+    }
+    /**
+     * Send heartbeat to keep connection alive.
+     */
+    sendHeartbeat(state) {
+        if (state.ws?.readyState === WebSocket.OPEN) {
+            const heartbeat = this.buildHeartbeatMessage();
+            state.ws.send(JSON.stringify(heartbeat));
+        }
+    }
+    /**
+     * Cleanup broker connection state.
+     * Called on disconnect or connection failure.
+     */
+    cleanupBroker(state) {
+        // Stop heartbeat
+        if (state.heartbeatTimer) {
+            clearInterval(state.heartbeatTimer);
+            state.heartbeatTimer = null;
+        }
+        // Cancel any pending reconnect attempt
+        if (state.reconnectTimer) {
+            clearTimeout(state.reconnectTimer);
+            state.reconnectTimer = null;
+        }
+        // Reject pending requests (hello, auth, register, etc.) and clear their timeouts
+        for (const [, pending] of state.pendingRequests) {
+            clearTimeout(pending.timeout);
+            pending.reject(new KadiError('Broker disconnected', 'BROKER_NOT_CONNECTED'));
+        }
+        state.pendingRequests.clear();
+        // Reject pending invocations (invokeRemote waiting for results) and clear their timeouts
+        for (const [, pending] of state.pendingInvocations) {
+            clearTimeout(pending.timeout);
+            pending.reject(new KadiError(`Tool "${pending.toolName}" failed: broker disconnected`, 'BROKER_NOT_CONNECTED', {
+                broker: state.name,
+                toolName: pending.toolName,
+            }));
+        }
+        state.pendingInvocations.clear();
+    }
+    // ─────────────────────────────────────────────────────────────
+    // RECONNECTION LOGIC
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Handle WebSocket close event.
+     *
+     * Decides whether to attempt reconnection based on:
+     * - Was the connection ever established? (don't reconnect on initial failure)
+     * - autoReconnect config setting
+     * - Whether this was an intentional disconnect (user called disconnect())
+     */
+    handleWebSocketClose(state) {
+        // Capture the status before cleanup changes it
+        const wasConnected = state.status === 'connected';
+        // Clean up connection resources (heartbeat, pending requests)
+        this.cleanupBroker(state);
+        // If user intentionally disconnected, don't reconnect
+        if (state.intentionalDisconnect) {
+            state.status = 'disconnected';
+            return;
+        }
+        // If the connection was never established (initial connection failed),
+        // don't reconnect - let the error propagate to the caller
+        if (!wasConnected && state.reconnectAttempts === 0) {
+            state.status = 'disconnected';
+            return;
+        }
+        // If auto-reconnect is disabled, just mark as disconnected
+        if (!this.config.autoReconnect) {
+            state.status = 'disconnected';
+            console.error(`[KADI] Connection to broker "${state.name}" lost. Auto-reconnect is disabled.`);
+            return;
+        }
+        // Schedule reconnection attempt
+        this.scheduleReconnect(state);
+    }
+    /**
+     * Calculate reconnection delay using exponential backoff with jitter.
+     *
+     * Formula: min(baseDelay * 2^attempt, maxDelay) ± 20% jitter
+     *
+     * Examples (with maxDelay=30s):
+     * - Attempt 0: ~1s (1000ms ± 200ms)
+     * - Attempt 1: ~2s (2000ms ± 400ms)
+     * - Attempt 2: ~4s (4000ms ± 800ms)
+     * - Attempt 3: ~8s
+     * - Attempt 4: ~16s
+     * - Attempt 5+: ~30s (capped)
+     *
+     * Why jitter? When a broker restarts and 100 agents try to reconnect,
+     * jitter spreads them out so they don't all hit at once (thundering herd).
+     */
+    getReconnectDelay(attempt) {
+        // Exponential backoff: 1s, 2s, 4s, 8s, 16s, 32s...
+        const exponentialDelay = RECONNECT_BASE_DELAY * Math.pow(2, attempt);
+        // Cap at maximum delay
+        const cappedDelay = Math.min(exponentialDelay, this.config.maxReconnectDelay);
+        // Add jitter: ±20% randomization
+        // (Math.random() * 2 - 1) gives a value between -1 and 1
+        const jitterFactor = 0.2;
+        const jitter = cappedDelay * jitterFactor * (Math.random() * 2 - 1);
+        return Math.round(cappedDelay + jitter);
+    }
+    /**
+     * Schedule a reconnection attempt.
+     *
+     * Logs the attempt number and delay for visibility.
+     *
+     * Note: Reconnection continues indefinitely until successful or
+     * disconnect() is called. There is no max attempt limit - only
+     * the delay is capped at maxReconnectDelay.
+     */
+    scheduleReconnect(state) {
+        state.status = 'reconnecting';
+        state.reconnectAttempts++;
+        const delay = this.getReconnectDelay(state.reconnectAttempts - 1);
+        console.error(`[KADI] Connection to broker "${state.name}" lost. ` +
+            `Reconnecting in ${(delay / 1000).toFixed(1)}s (attempt ${state.reconnectAttempts})...`);
+        state.reconnectTimer = setTimeout(() => {
+            this.attemptReconnect(state);
+        }, delay);
+    }
+    /**
+     * Attempt to reconnect to the broker.
+     *
+     * This reuses the existing keypair (agentId stays the same) and
+     * re-registers tools with the broker.
+     *
+     * On failure, schedules another attempt with increased delay.
+     */
+    async attemptReconnect(state) {
+        state.reconnectTimer = null;
+        try {
+            // Reopen WebSocket connection
+            await this.openWebSocket(state);
+            // Re-authenticate with existing keypair
+            await this.performHandshake(state);
+            // Re-register tools
+            await this.registerWithBroker(state);
+            // Restart heartbeat
+            state.heartbeatTimer = setInterval(() => {
+                this.sendHeartbeat(state);
+            }, this.config.heartbeatInterval);
+            // Success!
+            console.error(`[KADI] Reconnected to broker "${state.name}" after ${state.reconnectAttempts} attempts`);
+            state.reconnectAttempts = 0;
+            state.status = 'connected';
+        }
+        catch (error) {
+            // Log the error and try again
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`[KADI] Reconnection to broker "${state.name}" failed: ${message}`);
+            // If still not intentionally disconnected, schedule another attempt
+            if (!state.intentionalDisconnect) {
+                this.scheduleReconnect(state);
+            }
+        }
+    }
+    /**
+     * Disconnect from broker(s).
+     *
+     * @param brokerName - If provided, disconnect only from that broker.
+     *                     If not provided, disconnect from all brokers.
+     */
+    async disconnect(brokerName) {
+        if (brokerName) {
+            // Disconnect from specific broker
+            const state = this.brokers.get(brokerName);
+            if (state) {
+                this.disconnectBroker(state);
+                this.brokers.delete(brokerName);
+            }
+        }
+        else {
+            // Disconnect from all brokers
+            for (const [_name, state] of this.brokers) {
+                this.disconnectBroker(state);
+            }
+            this.brokers.clear();
+        }
+    }
+    /**
+     * Internal helper to disconnect a single broker.
+     *
+     * IMPORTANT: The order of operations matters!
+     * 1. Set intentionalDisconnect BEFORE closing WebSocket
+     * 2. ws.close() triggers handleWebSocketClose(), which checks this flag
+     * 3. If the flag isn't set first, reconnection would be triggered
+     */
+    disconnectBroker(state) {
+        state.intentionalDisconnect = true;
+        state.status = 'disconnecting';
+        this.cleanupBroker(state);
+        state.ws?.close();
+        state.status = 'disconnected';
+    }
+    // ─────────────────────────────────────────────────────────────
+    // EVENTS
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Set the event handler callback.
+     * Called by native/stdio transport when loading this ability.
+     * @internal
+     */
+    setEventHandler(handler) {
+        this.eventHandler = handler;
+    }
+    /**
+     * Emit an event to the consumer that loaded this ability.
+     *
+     * Events are fire-and-forget notifications - the consumer does not
+     * send a response. Use this for real-time updates, state changes,
+     * or any notification that doesn't require a response.
+     *
+     * @param event - Event name (e.g., 'file.changed', 'user.login')
+     * @param data - Event payload
+     *
+     * @example
+     * ```typescript
+     * // Emit an event when something happens
+     * client.emit('file.changed', { path: '/tmp/foo.txt', action: 'modified' });
+     *
+     * // Emit progress updates
+     * client.emit('job.progress', { percent: 50, message: 'Halfway done' });
+     * ```
+     */
+    emit(event, data) {
+        if (this.eventHandler) {
+            // Native transport: direct callback
+            this.eventHandler(event, data);
+        }
+        else if (this.isServingStdio) {
+            // Stdio transport: write notification to stdout
+            const notification = {
+                jsonrpc: '2.0',
+                method: 'event',
+                params: { name: event, data },
+            };
+            const json = JSON.stringify(notification);
+            process.stdout.write(`Content-Length: ${Buffer.byteLength(json)}\r\n\r\n${json}`);
+        }
+        // If neither condition is met, emit is a no-op (no consumer listening)
+    }
+    // ─────────────────────────────────────────────────────────────
+    // TOOL REGISTRATION
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Register a tool with this agent.
+     *
+     * @param definition - Tool definition (with Zod schemas)
+     * @param handler - Function to handle invocations
+     * @param options - Registration options (broker targeting)
+     *
+     * @example
+     * ```typescript
+     * client.registerTool({
+     *   name: 'add',
+     *   description: 'Add two numbers',
+     *   input: z.object({ a: z.number(), b: z.number() }),
+     *   output: z.object({ result: z.number() }),
+     * }, async ({ a, b }) => ({ result: a + b }));
+     *
+     * // Register only on specific broker
+     * client.registerTool(def, handler, { brokers: ['internal'] });
+     * ```
+     */
+    registerTool(definition, handler, options = {}) {
+        // Check for duplicate
+        if (this.tools.has(definition.name)) {
+            throw new KadiError(`Tool "${definition.name}" is already registered`, 'INVALID_CONFIG', {
+                toolName: definition.name,
+                hint: 'Each tool must have a unique name',
+            });
+        }
+        // Convert Zod schemas to JSON Schema
+        const jsonDefinition = {
+            name: definition.name,
+            description: definition.description,
+            inputSchema: isZodSchema(definition.input) ? zodToJsonSchema(definition.input) : { type: 'object' },
+            outputSchema: definition.output && isZodSchema(definition.output)
+                ? zodToJsonSchema(definition.output)
+                : undefined,
+        };
+        // Store registration
+        const registered = {
+            definition: jsonDefinition,
+            handler: handler,
+            registeredAt: new Date(),
+            targetBrokers: options.brokers ?? [],
+        };
+        this.tools.set(definition.name, registered);
+    }
+    /**
+     */
+    /**
+     * Get tool definitions, optionally filtered for a specific broker.
+     *
+     * @param forBroker - If provided, only return tools targeted for this broker.
+     *                    Tools with empty targetBrokers are included for all brokers.
+     */
+    getToolDefinitions(forBroker) {
+        return Array.from(this.tools.values())
+            .filter((t) => {
+            // If no broker specified, return all tools (e.g., for readAgentJson)
+            if (!forBroker)
+                return true;
+            // Empty targetBrokers means "register with all brokers"
+            if (t.targetBrokers.length === 0)
+                return true;
+            // Otherwise, only include if this broker is in the target list
+            return t.targetBrokers.includes(forBroker);
+        })
+            .map((t) => t.definition);
+    }
+    /**
+     * Invoke a local tool by name.
+     */
+    async invoke(toolName, params) {
+        const tool = this.tools.get(toolName);
+        if (!tool) {
+            throw new KadiError(`Tool "${toolName}" not found`, 'TOOL_NOT_FOUND', {
+                toolName,
+                available: Array.from(this.tools.keys()),
+                hint: 'Register the tool first with registerTool()',
+            });
+        }
+        return tool.handler(params);
+    }
+    // ─────────────────────────────────────────────────────────────
+    // ABILITY LOADING
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Load an in-process ability via dynamic import.
+     *
+     * @param name - Ability name (resolved from agent-lock.json)
+     * @param options - Optional explicit path
+     *
+     * @example
+     * ```typescript
+     * // Load by name (resolves from agent-lock.json)
+     * const calc = await client.loadNative('calculator');
+     *
+     * // Load by explicit path
+     * const calc = await client.loadNative('calculator', { path: './abilities/calc' });
+     * ```
+     */
+    async loadNative(name, options = {}) {
+        // Resolve path from lock file or use explicit path
+        const path = options.path ?? (await resolveAbilityPath(name, options.projectRoot));
+        return loadNativeTransport(path);
+    }
+    /**
+     * Load a child process ability via stdio.
+     *
+     * Three modes of operation:
+     *
+     * 1. **Explicit mode** — Provide `command` and `args` directly (bypasses agent.json):
+     *    ```typescript
+     *    await client.loadStdio('analyzer', {
+     *      command: 'python3',
+     *      args: ['./analyzer/main.py', '--verbose'],
+     *    });
+     *    ```
+     *
+     * 2. **Script selection mode** — Choose which script from ability's agent.json:
+     *    ```typescript
+     *    await client.loadStdio('analyzer', { script: 'dev' });
+     *    // Uses scripts.dev from the ability's agent.json
+     *    ```
+     *
+     * 3. **Default mode** — Uses scripts.start from ability's agent.json:
+     *    ```typescript
+     *    await client.loadStdio('analyzer');
+     *    // Resolves from agent-lock.json, reads scripts.start from agent.json
+     *    ```
+     *
+     * @param name - Ability name (used for error messages and lock file lookup)
+     * @param options - Command/args override, or script selection
+     */
+    async loadStdio(name, options = {}) {
+        // ─────────────────────────────────────────────────────────────────────────
+        // Mode 1: Explicit command — bypass agent.json entirely
+        // If command is provided, script option is ignored (explicit mode wins)
+        // ─────────────────────────────────────────────────────────────────────────
+        if (options.command) {
+            return loadStdioTransport(options.command, options.args ?? [], {
+                timeoutMs: this.config.requestTimeout,
+            });
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // Mode 2 & 3: Resolve script from ability's agent.json
+        // ─────────────────────────────────────────────────────────────────────────
+        const { command, args, cwd } = await resolveAbilityScript(name, options.script ?? 'start', options.projectRoot);
+        return loadStdioTransport(command, args, {
+            timeoutMs: this.config.requestTimeout,
+            cwd, // Run in ability's directory so relative paths work
+        });
+    }
+    /**
+     * Load a remote ability via broker.
+     *
+     * @param name - Ability name to discover on broker
+     * @param options - Broker to use, networks to filter
+     *
+     * @example
+     * ```typescript
+     * // Load from default broker
+     * const ai = await client.loadBroker('text-analyzer');
+     *
+     * // Load from specific broker
+     * const ai = await client.loadBroker('text-analyzer', { broker: 'internal' });
+     * ```
+     */
+    async loadBroker(name, options = {}) {
+        const brokerName = options.broker ?? this.config.defaultBroker;
+        if (!brokerName) {
+            throw new KadiError('No broker specified and no defaultBroker configured', 'INVALID_CONFIG', {
+                hint: 'Either specify a broker in options or set defaultBroker in config',
+            });
+        }
+        const state = this.brokers.get(brokerName);
+        if (!state || state.status !== 'connected') {
+            throw new KadiError(`Broker "${brokerName}" is not connected`, 'BROKER_NOT_CONNECTED', {
+                broker: brokerName,
+                hint: 'Call client.connect() first',
+            });
+        }
+        return loadBrokerTransport(name, {
+            broker: state,
+            requestTimeout: this.config.requestTimeout,
+            networks: options.networks,
+        });
+    }
+    // ─────────────────────────────────────────────────────────────
+    // REMOTE INVOCATION
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Invoke a tool on a remote agent directly (without loading the ability).
+     *
+     * This uses the KADI async invocation pattern:
+     * 1. Send kadi.ability.request → broker immediately returns { status: 'pending', requestId }
+     * 2. Broker forwards request to provider agent
+     * 3. Provider executes tool and sends result back to broker
+     * 4. Broker sends kadi.ability.response notification with the actual result
+     *
+     * @param toolName - Tool name (e.g., "add"). Broker routes to any provider.
+     * @param params - Tool parameters
+     * @param options - Broker to use, timeout
+     *
+     * @example
+     * ```typescript
+     * // Invoke on default broker (broker finds any provider)
+     * const result = await client.invokeRemote('add', { a: 5, b: 3 });
+     *
+     * // Invoke on specific broker
+     * const result = await client.invokeRemote('analyze', { text: 'hi' }, {
+     *   broker: 'internal',
+     * });
+     * ```
+     */
+    async invokeRemote(toolName, params, options = {}) {
+        // ─────────────────────────────────────────────────────────────
+        // VALIDATION
+        // ─────────────────────────────────────────────────────────────
+        const brokerName = options.broker ?? this.config.defaultBroker;
+        if (!brokerName) {
+            throw new KadiError('No broker specified and no defaultBroker configured', 'INVALID_CONFIG', {
+                hint: 'Either specify a broker in options or set defaultBroker in config',
+            });
+        }
+        const state = this.brokers.get(brokerName);
+        if (!state || state.status !== 'connected') {
+            throw new KadiError(`Broker "${brokerName}" is not connected`, 'BROKER_NOT_CONNECTED', {
+                broker: brokerName,
+                hint: 'Call client.connect() first',
+            });
+        }
+        const timeout = options.timeout ?? this.config.requestTimeout;
+        // ─────────────────────────────────────────────────────────────
+        // PHASE 1: Send request, get "pending" acknowledgment
+        // ─────────────────────────────────────────────────────────────
+        // Use existing sendRequest() for the request/response part.
+        // This handles the JSON-RPC id matching for us.
+        const pendingResult = await this.sendRequest(state, {
+            jsonrpc: '2.0',
+            id: ++this.nextRequestId,
+            method: 'kadi.ability.request',
+            params: { toolName, toolInput: params },
+        });
+        // Validate the pending response
+        if (pendingResult.status !== 'pending' || !pendingResult.requestId) {
+            throw new KadiError('Unexpected response from broker: expected pending acknowledgment', 'BROKER_ERROR', {
+                broker: brokerName,
+                toolName,
+                response: pendingResult,
+            });
+        }
+        const requestId = pendingResult.requestId;
+        // ─────────────────────────────────────────────────────────────
+        // PHASE 2: Wait for kadi.ability.response notification
+        // ─────────────────────────────────────────────────────────────
+        // The actual result comes as a notification (no id) with our requestId.
+        // We store in pendingInvocations and handleAbilityResponse() will resolve.
+        return new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                state.pendingInvocations.delete(requestId);
+                reject(new KadiError(`Tool invocation "${toolName}" timed out waiting for result`, 'BROKER_TIMEOUT', {
+                    broker: brokerName,
+                    toolName,
+                    requestId,
+                    timeout,
+                }));
+            }, timeout);
+            state.pendingInvocations.set(requestId, {
+                resolve: (result) => resolve(result),
+                reject,
+                timeout: timeoutHandle,
+                toolName,
+                sentAt: new Date(),
+            });
+        });
+    }
+    // ─────────────────────────────────────────────────────────────
+    // SERVE MODE
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Start serving this agent.
+     *
+     * @param mode - 'stdio' for JSON-RPC over stdin/stdout, 'broker' for broker connection
+     *
+     * @example
+     * ```typescript
+     * // Serve as a stdio server (for loadStdio)
+     * await client.serve('stdio');
+     *
+     * // Serve via broker (connects and waits)
+     * await client.serve('broker');
+     * ```
+     */
+    async serve(mode) {
+        if (mode === 'stdio') {
+            await this.serveStdio();
+        }
+        else {
+            await this.serveBroker();
+        }
+    }
+    /**
+     * Serve as a stdio server (JSON-RPC over stdin/stdout).
+     *
+     * Steps:
+     * 1. Redirect console.log to stderr (keeps stdout clean for JSON-RPC)
+     * 2. Set up binary-safe buffer for message parsing
+     * 3. Set up signal handlers for graceful shutdown
+     * 4. Process incoming messages
+     */
+    async serveStdio() {
+        // Mark that we're serving stdio (for emit() to know it can write to stdout)
+        this.isServingStdio = true;
+        // Step 1: Redirect console.log to stderr (keeps stdout clean for JSON-RPC)
+        // Without this, any console.log() in tool handlers corrupts the protocol
+        const originalLog = console.log;
+        console.log = console.error;
+        // Step 2: Binary-safe buffer and constants
+        let buffer = Buffer.alloc(0);
+        const HEADER_END = '\r\n\r\n';
+        const HEADER_END_LENGTH = 4;
+        const CONTENT_LENGTH_PATTERN = /Content-Length:\s*(\d+)/;
+        /**
+         * Try to read a single complete message from the buffer.
+         */
+        const tryReadSingleMessage = () => {
+            const headerEndIndex = buffer.indexOf(HEADER_END);
+            if (headerEndIndex === -1) {
+                return null;
+            }
+            const header = buffer.slice(0, headerEndIndex).toString('utf8');
+            const match = header.match(CONTENT_LENGTH_PATTERN);
+            if (!match?.[1]) {
+                // Malformed header - log and clear buffer (don't silently recover)
+                console.error('[KADI Stdio Server] Malformed header - missing Content-Length');
+                buffer = Buffer.alloc(0);
+                return null;
+            }
+            const contentLength = parseInt(match[1], 10);
+            const contentStart = headerEndIndex + HEADER_END_LENGTH;
+            const contentEnd = contentStart + contentLength;
+            if (buffer.length < contentEnd) {
+                return null;
+            }
+            const content = buffer.slice(contentStart, contentEnd).toString('utf8');
+            buffer = buffer.slice(contentEnd);
+            try {
+                return JSON.parse(content);
+            }
+            catch {
+                console.error('[KADI Stdio Server] Invalid JSON in message');
+                return null;
+            }
+        };
+        // Step 3: Graceful shutdown handler
+        // CRITICAL: Disconnects loaded abilities to prevent orphan processes
+        const cleanup = async () => {
+            console.error('[KADI Stdio Server] Shutting down...');
+            await this.disconnect();
+            console.log = originalLog;
+            process.exit(0);
+        };
+        process.once('SIGTERM', cleanup);
+        process.once('SIGINT', cleanup);
+        // Step 4: Process incoming messages
+        process.stdin.on('data', (chunk) => {
+            buffer = Buffer.concat([buffer, chunk]);
+            let message;
+            while ((message = tryReadSingleMessage()) !== null) {
+                // Handle message asynchronously but don't await (allows concurrent processing)
+                this.handleStdioMessage(message, cleanup).catch((err) => {
+                    console.error('[KADI Stdio Server] Error handling message:', err);
+                });
+            }
+        });
+        // Keep process alive indefinitely - shutdown happens via signal handlers
+        await new Promise(() => { });
+    }
+    /**
+     * Handle a stdio message.
+     */
+    async handleStdioMessage(message, cleanup) {
+        let result;
+        let error;
+        try {
+            if (message.method === 'readAgentJson') {
+                result = this.readAgentJson();
+            }
+            else if (message.method === 'invoke') {
+                const params = message.params;
+                result = await this.invoke(params.toolName, params.toolInput);
+            }
+            else if (message.method === 'shutdown') {
+                // Graceful shutdown - send response first, then cleanup
+                this.sendStdioResponse(message.id, { ok: true });
+                await cleanup();
+                return;
+            }
+            else {
+                error = { code: -32601, message: `Method not found: ${message.method}` };
+            }
+        }
+        catch (e) {
+            error = { code: -32000, message: e instanceof Error ? e.message : String(e) };
+        }
+        if (error) {
+            this.sendStdioError(message.id, error);
+        }
+        else {
+            this.sendStdioResponse(message.id, result);
+        }
+    }
+    /**
+     * Send a response via stdio.
+     */
+    sendStdioResponse(id, result) {
+        const response = {
+            jsonrpc: '2.0',
+            id,
+            result,
+        };
+        const json = JSON.stringify(response);
+        process.stdout.write(`Content-Length: ${Buffer.byteLength(json)}\r\n\r\n${json}`);
+    }
+    /**
+     * Send an error response via stdio.
+     */
+    sendStdioError(id, error) {
+        const response = {
+            jsonrpc: '2.0',
+            id,
+            error,
+        };
+        const json = JSON.stringify(response);
+        process.stdout.write(`Content-Length: ${Buffer.byteLength(json)}\r\n\r\n${json}`);
+    }
+    /**
+     * Serve via broker (connect and wait for requests).
+     *
+     * Connects to configured brokers and waits for incoming tool requests.
+     * Sets up graceful shutdown to disconnect loaded abilities.
+     */
+    async serveBroker() {
+        await this.connect();
+        // Graceful shutdown handler
+        // CRITICAL: Disconnects loaded abilities to prevent orphan processes
+        const cleanup = async () => {
+            console.error('[KADI Broker Server] Shutting down...');
+            await this.disconnect();
+            process.exit(0);
+        };
+        process.once('SIGTERM', cleanup);
+        process.once('SIGINT', cleanup);
+        // Keep process alive indefinitely - shutdown happens via signal handlers
+        await new Promise(() => { });
+    }
+    // ─────────────────────────────────────────────────────────────
+    // UTILITY
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Get agent information (for readAgentJson protocol).
+     */
+    readAgentJson() {
+        return {
+            name: this.config.name,
+            version: this.config.version,
+            tools: this.getToolDefinitions(),
+        };
+    }
+    /**
+     * Get broker connection state (for broker transport).
+     */
+    getBrokerState(brokerName) {
+        return this.brokers.get(brokerName);
+    }
+    /**
+     * Check if connected to a specific broker or any broker.
+     *
+     * @param brokerName - Optional broker name to check. If not specified, checks any.
+     */
+    isConnected(brokerName) {
+        if (brokerName) {
+            const state = this.brokers.get(brokerName);
+            return state?.status === 'connected';
+        }
+        for (const [, state] of this.brokers) {
+            if (state.status === 'connected') {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Get list of connected broker names.
+     */
+    getConnectedBrokers() {
+        const connected = [];
+        for (const [name, state] of this.brokers) {
+            if (state.status === 'connected') {
+                connected.push(name);
+            }
+        }
+        return connected;
+    }
+}
+//# sourceMappingURL=client.js.map