@kadi.build/core 0.4.0 → 0.6.0

package/src/client.ts

@@ -0,0 +1,2385 @@
+/**
+ * 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 {
+  convertToEncryptionKey,
+  convertToEncryptionKeyPair,
+  type EncryptionKeyPair,
+} from './crypto.js';
+// @ts-expect-error - tweetnacl-sealedbox-js doesn't have type definitions
+import sealedbox from 'tweetnacl-sealedbox-js';
+import type {
+  ClientConfig,
+  ResolvedConfig,
+  ClientIdentity,
+  BrokerState,
+  RegisteredTool,
+  ToolDefinition,
+  ZodToolDefinition,
+  ToolHandler,
+  LoadedAbility,
+  ToolExecutionBridge,
+  RegisterToolOptions,
+  LoadNativeOptions,
+  LoadStdioOptions,
+  LoadBrokerOptions,
+  InvokeRemoteOptions,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcNotification,
+  RequestContext,
+  // Broker events (pub/sub)
+  BrokerEvent,
+  BrokerEventHandler,
+  PublishOptions,
+  SubscribeOptions,
+  EmitOptions,
+} from './types.js';
+import { KadiError } from './errors.js';
+import { zodToJsonSchema, isZodSchema } from './zod.js';
+import { resolveAbilityEntry, 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 = 600000; // 10 minutes
+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: unknown): boolean {
+  if (typeof item !== 'object' || item === null) return false;
+  const block = item as Record<string, unknown>;
+
+  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: unknown): boolean {
+  if (typeof result !== 'object' || result === null) return false;
+
+  const obj = result as Record<string, unknown>;
+
+  // 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 */
+  private readonly config: ResolvedConfig;
+
+  /** Registered tools (local tools this agent provides) */
+  private readonly tools: Map<string, RegisteredTool> = new Map();
+
+  /** Broker connections by name */
+  private readonly brokers: Map<string, BrokerState> = new Map();
+
+  /** Counter for generating unique request IDs */
+  private nextRequestId = 0;
+
+  /** Event handler callback (set by native transport) */
+  private eventHandler: ((event: string, data: unknown) => void) | null = null;
+
+  /** Whether we're serving via stdio (set by serve('stdio')) */
+  private isServingStdio = false;
+
+  // ─────────────────────────────────────────────────────────────
+  // IDENTITY (single keypair shared across all broker connections)
+  // ─────────────────────────────────────────────────────────────
+
+  /** Ed25519 private key (DER format) - used for signing */
+  private readonly _privateKey: Buffer;
+
+  /** Base64-encoded Ed25519 public key (SPKI DER format) */
+  private readonly _publicKeyBase64: string;
+
+  /** Deterministic agent ID: SHA256(publicKey).hex().substring(0, 16) */
+  private readonly _agentId: string;
+
+  // ─────────────────────────────────────────────────────────────
+  // CONSTRUCTOR
+  // ─────────────────────────────────────────────────────────────
+
+  constructor(config: ClientConfig) {
+    // 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" })',
+      });
+    }
+
+    // Use provided identity or generate ephemeral Ed25519 keypair
+    if (config.identity) {
+      this._privateKey = config.identity.privateKey;
+      this._publicKeyBase64 = config.identity.publicKey;
+    } else {
+      const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+      this._privateKey = privateKey.export({ type: 'pkcs8', format: 'der' });
+      this._publicKeyBase64 = publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+    }
+
+    // Derive agentId using same algorithm as broker: SHA256(publicKey).hex().substring(0, 16)
+    this._agentId = crypto.createHash('sha256').update(this._publicKeyBase64).digest('hex').substring(0, 16);
+
+    // 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',
+        }
+      );
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // IDENTITY GETTERS
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Get the client's cryptographic identity.
+   *
+   * Available immediately after construction (before connect).
+   * The same identity is used for all broker connections.
+   *
+   * @example
+   * ```typescript
+   * const client = new KadiClient({ name: 'my-agent' });
+   * console.log(client.identity);
+   * // { publicKey: 'MIIBIjAN...', agentId: 'a1b2c3d4e5f67890' }
+   * ```
+   */
+  get identity(): ClientIdentity {
+    return {
+      publicKey: this._publicKeyBase64,
+      agentId: this._agentId,
+    };
+  }
+
+  /**
+   * Get the client's public key (base64-encoded SPKI DER format).
+   *
+   * This is the key used for Ed25519 authentication with brokers.
+   */
+  get publicKey(): string {
+    return this._publicKeyBase64;
+  }
+
+  /**
+   * Get the client's agent ID.
+   *
+   * Derived deterministically from publicKey: SHA256(publicKey).hex().substring(0, 16)
+   * This is the same ID that brokers will assign during authentication.
+   */
+  get agentId(): string {
+    return this._agentId;
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // ENCRYPTION KEY GETTERS
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Get the client's X25519 encryption public key.
+   *
+   * This key is derived from the client's Ed25519 signing key and can be
+   * shared with others so they can encrypt messages that only this client
+   * can decrypt.
+   *
+   * Use this when you want others to send encrypted data to your agent.
+   *
+   * @example
+   * ```typescript
+   * // Agent shares its encryption public key
+   * await client.publish('secrets.request', {
+   *   agentId: client.agentId,
+   *   publicKey: client.publicKey,  // Ed25519 for identity
+   *   // The sender will use convertToEncryptionKey(publicKey) to encrypt
+   * });
+   * ```
+   */
+  get encryptionPublicKey(): Uint8Array {
+    return convertToEncryptionKey(this._publicKeyBase64);
+  }
+
+  /**
+   * Get the client's X25519 encryption key pair.
+   *
+   * This key pair is derived from the client's Ed25519 signing keys and can
+   * be used to decrypt messages that were encrypted with the client's
+   * encryption public key.
+   *
+   * Use this when you need to decrypt sealed box messages sent to your agent.
+   *
+   * @example
+   * ```typescript
+   * import nacl from 'tweetnacl';
+   * nacl.sealedbox = require('tweetnacl-sealedbox-js');
+   *
+   * // Decrypt a sealed box message
+   * const keyPair = client.encryptionKeyPair;
+   * const decrypted = nacl.sealedbox.open(
+   *   encrypted,
+   *   keyPair.publicKey,
+   *   keyPair.secretKey
+   * );
+   * ```
+   */
+  get encryptionKeyPair(): EncryptionKeyPair {
+    return convertToEncryptionKeyPair(this._privateKey, this._publicKeyBase64);
+  }
+
+  /**
+   * Get the agent name (from config).
+   */
+  get name(): string {
+    return this.config.name;
+  }
+
+  /**
+   * Get the agent version (from config).
+   */
+  get version(): string {
+    return this.config.version;
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // 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?: string): Promise<void> {
+    // 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, continuing even if some fail
+    const results = await Promise.allSettled(
+      brokerNames.map((name) => this.connectToBroker(name))
+    );
+
+    // Log failures but don't throw unless ALL brokers failed
+    const failures: string[] = [];
+    for (const [i, result] of results.entries()) {
+      if (result.status === 'rejected') {
+        const failedBroker = brokerNames[i];
+        if (failedBroker === undefined) continue;
+        const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+        console.error(`[KADI] Failed to connect to broker "${failedBroker}": ${reason}`);
+        failures.push(failedBroker);
+      }
+    }
+
+    // Only throw if ALL brokers failed
+    if (failures.length === brokerNames.length) {
+      throw new KadiError(
+        `Failed to connect to any broker`,
+        'CONNECTION_FAILED',
+        { failedBrokers: failures }
+      );
+    }
+
+    // Log partial success
+    if (failures.length > 0) {
+      const succeeded = brokerNames.length - failures.length;
+      console.error(`[KADI] Connected to ${succeeded}/${brokerNames.length} brokers`);
+    }
+  }
+
+  /**
+   * Connect to a specific broker by name.
+   *
+   * Protocol:
+   * 1. Open WebSocket connection
+   * 2. Send kadi.session.hello
+   * 3. Receive nonce from broker
+   * 4. Send kadi.session.authenticate with signed nonce (using client's identity)
+   * 5. Receive agentId from broker (should match client.agentId)
+   * 6. Register tools with broker
+   * 7. Start heartbeat
+   *
+   * Note: The keypair is generated once at client construction and shared
+   * across all broker connections, ensuring consistent identity.
+   */
+  private async connectToBroker(brokerName: string): Promise<void> {
+    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;
+      }
+    }
+
+    // Create broker state (identity is at client level, not per-broker)
+    const state: BrokerState = {
+      name: brokerName,
+      url,
+      ws: null,
+      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
+  // ─────────────────────────────────────────────────────────────
+
+  private buildHelloMessage(): JsonRpcRequest {
+    return {
+      jsonrpc: '2.0',
+      id: this.nextRequestId++,
+      method: 'kadi.session.hello',
+      params: { role: 'agent' },
+    };
+  }
+
+  private buildAuthMessage(nonce: string): JsonRpcRequest {
+    // Sign the nonce using the client's private key
+    const privateKey = crypto.createPrivateKey({
+      key: this._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: this._publicKeyBase64,
+        signature: signature.toString('base64'),
+        nonce,
+      },
+    };
+  }
+
+  private buildRegisterMessage(tools: ToolDefinition[], networks: string[]): JsonRpcRequest {
+    return {
+      jsonrpc: '2.0',
+      id: this.nextRequestId++,
+      method: 'kadi.agent.register',
+      params: {
+        tools,
+        networks,
+        displayName: this.config.name,
+      },
+    };
+  }
+
+  private buildHeartbeatMessage(): JsonRpcRequest {
+    return {
+      jsonrpc: '2.0',
+      id: this.nextRequestId++,
+      method: 'kadi.session.heartbeat',
+      params: { timestamp: Date.now() },
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // CONNECTION HELPERS
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Open WebSocket connection to broker.
+   */
+  private openWebSocket(state: BrokerState): Promise<void> {
+    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: "..." }
+   */
+  private async performHandshake(state: BrokerState): Promise<void> {
+    // 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<{ nonce: string }>(
+      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<{ agentId: string }>(
+      state,
+      this.buildAuthMessage(helloResult.nonce)
+    );
+
+    if (!authResult.agentId) {
+      throw new KadiError('Auth response missing agentId', 'AUTHENTICATION_FAILED', {
+        broker: state.name,
+      });
+    }
+
+    // Verify broker assigned the expected agentId (sanity check)
+    if (authResult.agentId !== this._agentId) {
+      console.warn(
+        `[KADI] Broker "${state.name}" returned different agentId: ` +
+        `expected ${this._agentId}, got ${authResult.agentId}. ` +
+        `This may indicate the broker uses a different ID derivation algorithm.`
+      );
+    }
+  }
+
+  /**
+   * 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.
+   */
+  private async registerWithBroker(state: BrokerState): Promise<void> {
+    // 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<{ status: string }>(
+      state,
+      this.buildRegisterMessage(tools, this.config.networks)
+    );
+  }
+
+  /**
+   * Send a JSON-RPC request and wait for the response.
+   * Returns the result directly (not the JSON-RPC envelope).
+   * Note: Type parameter T is not validated at runtime.
+   */
+  private sendRequest<T = unknown>(state: BrokerState, request: JsonRpcRequest): Promise<T> {
+    // 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: unknown) => resolve(result as T),
+        reject,
+        timeout,
+        method: request.method,
+        sentAt: new Date(),
+      });
+
+      ws.send(JSON.stringify(request));
+    });
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // MESSAGE HANDLING
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Handle incoming messages from broker.
+   */
+  private handleBrokerMessage(state: BrokerState, data: WebSocket.RawData): void {
+    let message: JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
+    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 as JsonRpcResponse);
+      return;
+    }
+
+    // Handle requests (has id, has method) - tool invocations from broker
+    if ('id' in message && 'method' in message) {
+      this.handleBrokerRequest(state, message as JsonRpcRequest);
+      return;
+    }
+
+    // Handle notifications (no id, has method)
+    if (!('id' in message) && 'method' in message) {
+      const notification = message as JsonRpcNotification;
+
+      // 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
+   */
+  private handleAbilityResponse(state: BrokerState, notification: JsonRpcNotification): void {
+    const params = notification.params as {
+      requestId?: string;
+      result?: unknown;
+      error?: string | { code?: number; message: string };
+    };
+
+    if (!params?.requestId) {
+      return;
+    }
+
+    const pending = state.pendingInvocations.get(params.requestId);
+    if (!pending) {
+      // No listener - response is orphaned (timed out or unknown requestId)
+      return;
+    }
+
+    clearTimeout(pending.timeout);
+    state.pendingInvocations.delete(params.requestId);
+    this.resolveAbilityResponse(pending, params, state.name);
+  }
+
+  /**
+   * Resolve or reject a pending invocation based on response content.
+   */
+  private resolveAbilityResponse(
+    pending: { resolve: (value: unknown) => void; reject: (error: Error) => void; toolName: string },
+    response: { result?: unknown; error?: string | { code?: number; message: string } },
+    brokerName: string
+  ): void {
+    if (response.error) {
+      const errorMessage = typeof response.error === 'string' ? response.error : response.error.message;
+      const errorCode = typeof response.error === 'object' ? response.error.code : undefined;
+      pending.reject(
+        new KadiError(`Tool "${pending.toolName}" failed: ${errorMessage}`, 'TOOL_INVOCATION_FAILED', {
+          toolName: pending.toolName,
+          broker: brokerName,
+          errorCode,
+        })
+      );
+    } else {
+      pending.resolve(response.result);
+    }
+  }
+
+  /**
+   * Get a connected broker's state, throwing if not available.
+   */
+  private getConnectedBrokerState(optionsBroker?: string): { state: BrokerState; brokerName: string } {
+    const brokerName = optionsBroker ?? 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,
+        status: state?.status ?? 'not found',
+        hint: 'Call client.connect() first',
+      });
+    }
+    return { state, brokerName };
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // BROKER EVENTS (Pub/Sub)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Handle kadi.event.delivery notification from broker.
+   * Dispatches to local handlers matching the event channel.
+   */
+  private handleEventDelivery(state: BrokerState, notification: JsonRpcNotification): void {
+    const params = notification.params as BrokerEvent | undefined;
+
+    // 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: BrokerEvent = {
+      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')
+   */
+  private patternMatchesChannel(pattern: string, channel: string): boolean {
+    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!
+   */
+  private matchPatternRecursive(
+    pattern: string[],
+    pi: number,
+    channel: string[],
+    ci: number
+  ): boolean {
+    // 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: string,
+    handler: BrokerEventHandler,
+    options: SubscribeOptions = {}
+  ): Promise<void> {
+    const { state } = this.getConnectedBrokerState(options.broker);
+
+    // 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: string,
+    handler: BrokerEventHandler,
+    options: SubscribeOptions = {}
+  ): Promise<void> {
+    // 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: string, data: unknown, options: PublishOptions = {}): Promise<void> {
+    const { state } = this.getConnectedBrokerState(options.broker);
+
+    // 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,
+      },
+    });
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // DEPLOYMENT SECRETS (Trusted Introducer Pattern)
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Request secrets from the deployer during agent startup.
+   *
+   * This implements the agent side of the "Trusted Introducer" pattern:
+   * 1. Check for KADI_DEPLOY_NONCE env var (set by deployer)
+   * 2. Subscribe to secrets.response.{agentId} channel
+   * 3. Publish request to secrets.request with nonce and public key
+   * 4. Wait for response from deployer (approved with encrypted secrets, or rejected)
+   * 5. If approved, decrypt using agent's encryption key pair
+   * 6. Set secrets in process.env
+   *
+   * The deployer (kadi deploy) stays connected after deployment and waits
+   * for this request. It verifies the nonce, prompts for approval, and
+   * either shares encrypted secrets or sends a rejection.
+   *
+   * @param options - Configuration options
+   * @returns Decrypted secrets as key-value pairs, or null if no secrets needed
+   * @throws KadiError if timeout waiting for secrets or decryption fails
+   *
+   * @example
+   * ```typescript
+   * const client = new KadiClient({ name: 'my-agent', ... });
+   * await client.connect();
+   *
+   * // Request secrets from deployer (throws if timeout)
+   * const secrets = await client.requestSecrets();
+   *
+   * if (secrets) {
+   *   console.log('Received secrets:', Object.keys(secrets));
+   *   // Secrets are also set in process.env
+   * }
+   *
+   * // With custom timeout
+   * const secrets = await client.requestSecrets({ timeout: 120000 });
+   * ```
+   */
+  async requestSecrets(options: { timeout?: number } = {}): Promise<Record<string, string> | null> {
+    const { timeout = 60000 } = options; // Default 60 seconds
+
+    // Check for deployment nonce - if not set, no secrets needed
+    const nonce = process.env.KADI_DEPLOY_NONCE;
+    if (!nonce) {
+      return null;
+    }
+
+    // Parse required/optional secrets from env
+    const requiredSecrets = process.env.KADI_REQUIRED_SECRETS?.split(',').filter(Boolean) || [];
+    const optionalSecrets = process.env.KADI_OPTIONAL_SECRETS?.split(',').filter(Boolean) || [];
+
+    if (requiredSecrets.length === 0 && optionalSecrets.length === 0) {
+      return null;
+    }
+
+    // Ensure we're connected to at least one broker
+    const connectedBrokers: [string, BrokerState][] = [];
+    for (const [name, state] of this.brokers.entries()) {
+      if (state.status === 'connected') {
+        connectedBrokers.push([name, state]);
+      }
+    }
+
+    if (connectedBrokers.length === 0) {
+      throw new KadiError(
+        'Cannot request secrets: not connected to any broker',
+        'SECRETS_NOT_CONNECTED',
+        { hint: 'Call client.connect() before requestSecrets()' }
+      );
+    }
+
+    // Determine which broker to use for the secret handshake
+    let brokerName: string;
+    const rendezvousBrokerUrl = process.env.KADI_RENDEZVOUS_BROKER;
+
+    if (rendezvousBrokerUrl) {
+      // Find the broker matching the rendezvous URL
+      const match = connectedBrokers.find(([_, state]) => state.url === rendezvousBrokerUrl);
+
+      if (!match) {
+        const connectedUrlsFormatted = connectedBrokers.map(([name, state]) => `  - ${name}: ${state.url}`).join('\n');
+        throw new KadiError(
+          `This agent needs secrets, but it's not connected to the right broker.`,
+          'SECRETS_NOT_CONNECTED',
+          {
+            hint: `Secrets will be delivered on:\n  ${rendezvousBrokerUrl}\n\nYour client is connected to:\n${connectedUrlsFormatted}\n\nTo fix, add the delivery broker URL to your KadiClient config,\nor update agent.json brokers to include this URL.`,
+          }
+        );
+      }
+
+      brokerName = match[0];
+    } else {
+      // No rendezvous broker specified - use first connected (for dev/testing)
+      brokerName = connectedBrokers[0]![0];
+    }
+
+    return new Promise((resolve, reject) => {
+      let resolved = false;
+      let timeoutHandle: NodeJS.Timeout | undefined;
+
+      // Cleanup function
+      const cleanup = () => {
+        if (timeoutHandle) {
+          clearTimeout(timeoutHandle);
+        }
+        // Unsubscribe from the channel
+        this.unsubscribe(`secrets.response.${this._agentId}`, handleSecrets, { broker: brokerName })
+          .catch(() => {}); // Ignore unsubscribe errors
+      };
+
+      // Handler for receiving secrets response
+      const handleSecrets: BrokerEventHandler = async (event: BrokerEvent) => {
+        if (resolved) return;
+
+        // Extract response data from event
+        const data = event.data as {
+          status?: 'approved' | 'rejected';
+          encrypted?: string;
+          reason?: string;
+          sharedAt?: string;
+          rejectedAt?: string;
+        } | undefined;
+
+        if (!data?.status) {
+          // Malformed response - ignore
+          return;
+        }
+
+        // Validate status is expected value
+        if (data.status !== 'approved' && data.status !== 'rejected') {
+          // Unknown status - ignore malformed response
+          return;
+        }
+
+        resolved = true;
+        cleanup();
+
+        // Handle rejection
+        if (data.status === 'rejected') {
+          reject(new KadiError(
+            `Secrets request rejected: ${data.reason || 'No reason provided'}`,
+            'SECRETS_REJECTED',
+            { reason: data.reason }
+          ));
+          return;
+        }
+
+        // Handle approval - must have encrypted data
+        if (!data.encrypted) {
+          reject(new KadiError(
+            'Secrets approved but no encrypted data received',
+            'SECRETS_DECRYPTION_FAILED',
+            { hint: 'The deployer may have encountered an error' }
+          ));
+          return;
+        }
+
+        try {
+          // Decode base64 encrypted blob
+          const encryptedBytes = Buffer.from(data.encrypted, 'base64');
+
+          // Get our encryption key pair
+          const keyPair = this.encryptionKeyPair;
+
+          // Decrypt the sealed box
+          const decrypted = sealedbox.open(
+            new Uint8Array(encryptedBytes),
+            keyPair.publicKey,
+            keyPair.secretKey
+          );
+
+          if (!decrypted) {
+            reject(new KadiError(
+              'Failed to decrypt secrets: invalid sealed box or wrong key',
+              'SECRETS_DECRYPTION_FAILED',
+              { hint: 'The secrets may have been encrypted for a different agent' }
+            ));
+            return;
+          }
+
+          // Parse JSON
+          const secretsJson = new TextDecoder().decode(decrypted);
+          const secrets: Record<string, string> = JSON.parse(secretsJson);
+
+          // Set secrets in process.env
+          for (const [key, value] of Object.entries(secrets)) {
+            process.env[key] = value;
+          }
+
+          resolve(secrets);
+        } catch (err) {
+          reject(new KadiError(
+            `Failed to decrypt secrets: ${(err as Error).message}`,
+            'SECRETS_DECRYPTION_FAILED',
+            { cause: err, hint: 'The secrets may have been encrypted for a different agent' }
+          ));
+        }
+      };
+
+      // Set timeout
+      timeoutHandle = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          cleanup();
+          reject(new KadiError(
+            `Timeout waiting for secrets (${timeout / 1000}s). Deployer may have disconnected or denied the request.`,
+            'SECRETS_TIMEOUT',
+            {
+              timeout,
+              hint: 'Ensure the deployer is still running and approves the secret request',
+            }
+          ));
+        }
+      }, timeout);
+
+      // Subscribe to our response channel
+      this.subscribe(`secrets.response.${this._agentId}`, handleSecrets, { broker: brokerName })
+        .then(() => {
+          // Publish secret request
+          return this.publish('secrets.request', {
+            nonce,
+            agentId: this._agentId,
+            publicKey: this._publicKeyBase64,
+            required: requiredSecrets,
+            optional: optionalSecrets,
+          }, { broker: brokerName });
+        })
+        .catch((err) => {
+          if (!resolved) {
+            resolved = true;
+            cleanup();
+            reject(new KadiError(
+              `Failed to request secrets: ${(err as Error).message}`,
+              'SECRETS_REQUEST_FAILED',
+              { cause: err }
+            ));
+          }
+        });
+    });
+  }
+
+  /**
+   * Handle incoming request from broker (tool invocation).
+   */
+  private async handleBrokerRequest(state: BrokerState, request: JsonRpcRequest): Promise<void> {
+    // Handle tool invocation: kadi.ability.request
+    if (request.method === 'kadi.ability.request') {
+      const params = request.params as {
+        toolName: string;
+        toolInput: unknown;
+        _meta?: {
+          callerProtocol?: 'mcp' | 'kadi';
+          kadi_caller?: {
+            sessionId?: string;
+            publicKey?: string;
+          };
+          network?: string;
+        };
+      };
+
+      // Build request context from broker metadata
+      // Only include optional fields if present (cleaner objects, matches Python SDK)
+      const context: RequestContext = {
+        broker: state.name,
+        requestId: String(request.id),
+      };
+      if (params._meta?.network) context.network = params._meta.network;
+      if (params._meta?.callerProtocol) context.callerProtocol = params._meta.callerProtocol;
+      if (params._meta?.kadi_caller?.sessionId) context.callerSessionId = params._meta.kadi_caller.sessionId;
+      if (params._meta?.kadi_caller?.publicKey) context.callerPublicKey = params._meta.kadi_caller.publicKey;
+
+      await this.handleInvokeRequest(state, request.id, params.toolName, params.toolInput, context);
+    }
+  }
+
+  /**
+   * 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.
+   */
+  private async handleInvokeRequest(
+    state: BrokerState,
+    requestId: string | number,
+    toolName: string,
+    toolInput: unknown,
+    context: RequestContext
+  ): Promise<void> {
+    try {
+      const result = await this.executeToolHandler(toolName, toolInput, context);
+
+      // Format response based on caller protocol
+      let responseResult: unknown;
+      if (context.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: JsonRpcResponse = {
+        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 (context.callerProtocol === 'mcp') {
+        const response: JsonRpcResponse = {
+          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: JsonRpcResponse = {
+          jsonrpc: '2.0',
+          id: requestId,
+          error: {
+            code: -32000,
+            message: errorMessage,
+          },
+        };
+        state.ws?.send(JSON.stringify(response));
+      }
+    }
+  }
+
+  /**
+   * Handle response to a pending request.
+   */
+  private handleBrokerResponse(state: BrokerState, response: JsonRpcResponse): void {
+    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.
+   */
+  private sendHeartbeat(state: BrokerState): void {
+    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.
+   */
+  private cleanupBroker(state: BrokerState): void {
+    // 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())
+   */
+  private handleWebSocketClose(state: BrokerState): void {
+    // 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;
+    }
+
+    // If we're already in a reconnection attempt (status = 'reconnecting'),
+    // don't schedule another one here. The catch block in attemptReconnect()
+    // will handle rescheduling. This prevents duplicate timers when the
+    // WebSocket closes during a reconnection attempt (e.g., handshake fails).
+    if (state.status === 'reconnecting') {
+      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).
+   */
+  private getReconnectDelay(attempt: number): number {
+    // 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.
+   */
+  private scheduleReconnect(state: BrokerState): void {
+    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.
+   *
+   * Uses the client's identity (same keypair/agentId for all connections)
+   * and re-registers tools with the broker.
+   *
+   * On failure, schedules another attempt with increased delay.
+   */
+  private async attemptReconnect(state: BrokerState): Promise<void> {
+    // Guard against orphaned timers firing after successful reconnection
+    // or after intentional disconnect was requested
+    if (state.status === 'connected' || state.intentionalDisconnect) {
+      return;
+    }
+
+    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?: string): Promise<void> {
+    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
+   */
+  private disconnectBroker(state: BrokerState): void {
+    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: (event: string, data: unknown) => void): void {
+    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
+   * @param options - Optional: specify broker to also broadcast to
+   *
+   * @example
+   * ```typescript
+   * // Emit locally only
+   * client.emit('progress', { percent: 50 });
+   *
+   * // Emit locally AND broadcast to broker subscribers
+   * client.emit('order.created', orderData, { broker: 'local' });
+   * ```
+   */
+  emit(event: string, data: unknown, options?: EmitOptions): void {
+    // Local emit: to parent agent (if loaded as ability)
+    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}`);
+    }
+
+    // Broadcast: also publish to broker (if specified and connected)
+    if (options?.broker) {
+      const state = this.brokers.get(options.broker);
+      if (state?.status === 'connected') {
+        // Fire-and-forget: don't await, but log errors
+        this.publish(event, data, { broker: options.broker, network: options.network }).catch((err) => {
+          const message = err instanceof Error ? err.message : String(err);
+          console.error(`[KADI] emit() broadcast to broker "${options.broker}" failed: ${message}`);
+        });
+      }
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // 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<TInput, TOutput>(
+    definition: ZodToolDefinition<TInput, TOutput>,
+    handler: ToolHandler<TInput, TOutput>,
+    options: RegisterToolOptions = {}
+  ): void {
+    // 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: ToolDefinition = {
+      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: RegisteredTool = {
+      definition: jsonDefinition,
+      handler: handler as ToolHandler,
+      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.
+   */
+  private getToolDefinitions(forBroker?: string): ToolDefinition[] {
+    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);
+  }
+
+  /**
+   * Execute a tool registered on this client.
+   *
+   * This is a PRIVATE method - not for external use.
+   * It handles INCOMING tool calls from:
+   * - Broker (when another agent calls your tools)
+   * - Stdio (when running as an ability)
+   * - Native transport (when loaded in-process)
+   *
+   * To call tools on OTHER agents, use:
+   * - `loadBroker(name).invoke(tool, params)` - for repeated calls to the same agent
+   * - `invokeRemote(tool, params, { timeout })` - for one-off calls with custom timeout
+   *
+   * @param toolName - Name of the registered tool to execute
+   * @param params - Input parameters for the tool
+   * @param context - Request context with caller info (provided by broker/stdio)
+   * @internal
+   */
+  private async executeToolHandler(toolName: string, params: unknown, context?: RequestContext): Promise<unknown> {
+    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()',
+      });
+    }
+
+    // TODO: Validate params against tool.definition.input schema before invoking.
+    // Currently the schema is only used for discovery (kadi.ability.list) and TypeScript types.
+    // Tool handlers must do their own validation, which defeats the purpose of requiring a schema.
+    // Should call tool.definition.input.safeParse(params) and throw on validation errors.
+
+    return tool.handler(params, context);
+  }
+
+  /**
+   * Create a bridge for internal transport use.
+   *
+   * This allows native transport to call tools on this client without
+   * exposing the full client interface.
+   *
+   * @internal - Not for external use
+   */
+  createToolBridge(): ToolExecutionBridge {
+    return {
+      executeToolHandler: (toolName, params, context) =>
+        this.executeToolHandler(toolName, params, context),
+      getRegisteredTools: () =>
+        Array.from(this.tools.values()).map((t) => t.definition),
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // 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: string, options: LoadNativeOptions = {}): Promise<LoadedAbility> {
+    // Resolve path and entrypoint from lock file or use explicit path
+    let path: string;
+    let entrypoint: string | undefined;
+
+    if (options.path) {
+      path = options.path;
+    } else {
+      const entry = await resolveAbilityEntry(name, options.projectRoot);
+      path = entry.absolutePath;
+      entrypoint = entry.entrypoint;
+    }
+
+    return loadNativeTransport(path, entrypoint, {
+      timeout: options.timeout ?? this.config.requestTimeout,
+    });
+  }
+
+  /**
+   * 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: string, options: LoadStdioOptions = {}): Promise<LoadedAbility> {
+    // ─────────────────────────────────────────────────────────────────────────
+    // 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: options.timeout ?? 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: options.timeout ?? 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: string, options: LoadBrokerOptions = {}): Promise<LoadedAbility> {
+    const { state, brokerName } = this.getConnectedBrokerState(options.broker);
+
+    return loadBrokerTransport(name, {
+      broker: state,
+      requestTimeout: options.timeout ?? this.config.requestTimeout,
+      networks: options.networks,
+      // Provide subscribe/unsubscribe for ability.on()/off() support
+      subscribe: (pattern, handler) => this.subscribe(pattern, handler, { broker: brokerName }),
+      unsubscribe: (pattern, handler) => this.unsubscribe(pattern, handler, { broker: brokerName }),
+    });
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // 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<T = unknown>(
+    toolName: string,
+    params: unknown,
+    options: InvokeRemoteOptions = {}
+  ): Promise<T> {
+    const { state, brokerName } = this.getConnectedBrokerState(options.broker);
+    const timeout = options.timeout ?? this.config.requestTimeout;
+
+    // Generate requestId FIRST, before any async operations.
+    // This allows us to set up the response listener before sending,
+    // eliminating the race condition where fast responses arrive
+    // before the listener exists.
+    const requestId = crypto.randomUUID();
+
+    // Set up result listener BEFORE sending the request.
+    // When the broker sends kadi.ability.response, handleAbilityResponse()
+    // will find this listener and resolve/reject the promise.
+    const resultPromise = new Promise<T>((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: unknown) => resolve(result as T),
+        reject,
+        timeout: timeoutHandle,
+        toolName,
+        sentAt: new Date(),
+      });
+    });
+
+    // Helper to clean up the pending invocation on failure
+    const cleanupPendingInvocation = () => {
+      const pending = state.pendingInvocations.get(requestId);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        state.pendingInvocations.delete(requestId);
+      }
+    };
+
+    // NOW send the request (listener already exists, no race possible)
+    try {
+      const pendingResult = await this.sendRequest<{ status: string; requestId: string }>(
+        state,
+        {
+          jsonrpc: '2.0',
+          id: ++this.nextRequestId,
+          method: 'kadi.ability.request',
+          params: { toolName, toolInput: params, requestId },
+        }
+      );
+
+      // Validate the broker accepted the request
+      if (pendingResult.status !== 'pending') {
+        cleanupPendingInvocation();
+        throw new KadiError(
+          'Unexpected response from broker: expected pending acknowledgment',
+          'BROKER_ERROR',
+          { broker: brokerName, toolName, response: pendingResult }
+        );
+      }
+    } catch (error) {
+      cleanupPendingInvocation();
+      throw error;
+    }
+
+    return resultPromise;
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // 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: 'stdio' | 'broker'): Promise<void> {
+    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
+   */
+  private async serveStdio(): Promise<void> {
+    // 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 = (): JsonRpcRequest | null => {
+      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) as JsonRpcRequest;
+      } 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 = Buffer.concat([buffer, chunk]);
+
+      let message: JsonRpcRequest | null;
+      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.
+   */
+  private async handleStdioMessage(
+    message: JsonRpcRequest,
+    cleanup: () => Promise<void>
+  ): Promise<void> {
+    let result: unknown;
+    let error: { code: number; message: string } | undefined;
+
+    try {
+      if (message.method === 'readAgentJson') {
+        result = this.readAgentJson();
+      } else if (message.method === 'invoke') {
+        const params = message.params as { toolName: string; toolInput: unknown };
+        result = await this.executeToolHandler(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.
+   */
+  private sendStdioResponse(id: string | number, result: unknown): void {
+    const response: JsonRpcResponse = {
+      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.
+   */
+  private sendStdioError(id: string | number, error: { code: number; message: string }): void {
+    const response: JsonRpcResponse = {
+      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.
+   */
+  private async serveBroker(): Promise<void> {
+    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(): { name: string; version: string; tools: ToolDefinition[] } {
+    return {
+      name: this.config.name,
+      version: this.config.version,
+      tools: this.getToolDefinitions(),
+    };
+  }
+
+  /**
+   * Get broker connection state (for broker transport).
+   */
+  getBrokerState(brokerName: string): BrokerState | undefined {
+    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?: string): boolean {
+    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(): string[] {
+    return Array.from(this.brokers.entries())
+      .filter(([, state]) => state.status === 'connected')
+      .map(([name]) => name);
+  }
+}